Goals

[craigspaeth]

The 🔑 to high-quality software is a programmer being able to rapidly—test, change, understand the effects of, deploy, monitor production usage of, and rollback—code. Elixir as a language/VM should help this with solid testing tools, functional patterns, immutability/minimized side-effects, hot code reload/deploying, let-it-crash fault tolerance. I'm going to bet that in the majority of cases the language/VM alone can be leveraged to allow one to accidentally accomplish an acceptable level of performance, fault-tolerance, error handling, modularity, robustness, etc. So this framework should 80% of the time make tradeoffs in favor of simpler/easier patterns and rapid development experience.

• Rapid iteration with easy testing and code reloading
• Simplicity/ease > performance
• Dirty & simple/easy > proper (If it requires jumping through hoops and additional LOC without dead obvious benefit then probably don't do it. e.g. favor obvious dirty mocking techniques over dependency injection/avoiding side-effects like the plague/wrapping mock modules)
• Explicit/obvious > elegant/clever
• YAGNI: MVP 80/20 architecture (bare minimum concepts that work for 80% of typical CRUD work)
• Modular architecture (easy to OSSify views/apps, libraries can be used independently, etc.)
• Flexible/extensible architecture (easy to swap out or extend patterns with escape hatches)
• Simple > robust interop with JS
• Easy/obvious integration with React ecosystem
• A somewhat lowest common denominator b/t JS & Elixir would be operating close to JSON data types. Less magic and minor conveniences like macros and more functions operating on maps. So...
  • Strings > Charlists, Binaries
  • Floats > Ints ~= Numbers
  • Booleans, Lists, Atoms, Nil, Functions ~= Booleans, Arrays, Symbols, Null, Functions
  • Maps > Structs ~= Data Objects (Primary type for passing around data from e.g. databases or APIs)
  • Keyword Lists ~= Options Objects (Primary type for DSLs, configuration, function options e.g. don't grow in size)
  • Explicit APIs > DSLs > Macros
  • Modules ~= ES Modules/Classes (mainly used as a namespace of private/public functions, maybe occasionally used to export co-located metadata/config like mix.exs)
  • Avoid advanced Elixir metaprogramming features like Protocols, Structs, Sigils, Typespecs, Macros
• YAGNI and limited patterns
  • Error handling is more let-it-crash than cond {:error, _ } ->
  • Simple DSLs & Functions > module attrs, macros, etcs.
  • Doesn't ship with a preferred database adapter—uses in-memory or ETS
• Encourage a thin client-side layer, pushing business logic to the server and keeping an isomorphic view layer focused on UI and changes to a vanilla state map.
• ...?

[craigspaeth]

We should practice extreme minimalism + extensibility with this. There're too many problems to solve as it is, so let's just focus providing the bear-minimum API surface area that heavily leverages pure-ish functions, pipelines, and data-based DSLs to be extensible.

Extreme minimalism

Models

• schema/0 defines schema fields and relationships for graphql by returning a DSL.

Views

• render/1 determines markup (which can be wrapped to do inline styling or otherwise & other React APIs can be hooked into if necessary)

Controller

• emit/2 dispatches events
• events/0 Maps event listeners to view model state changes with built-in events for routing/etc. like choo's
• state/1 determines the initial state map and derived state (e.g. reselect, materialised views)

Slightly less extreme

✅ Winner because clear separation of concerns and more practical

Data Models

• fields/0 defines CRUD schema fields and relationships using a DSL
• resolve/1 Middleware/changset-like function for converting GraphQL query to persistence/validation/etc (minimal ETS based adapter provided out of the box).

View Models

• model/1 determines the initial state map and derived state (e.g. reselect, materialised views)
• update/1 persists state and re-renders the view.

Views

• render/1 determines markup (which can be wrapped to do inline styling or otherwise & other React APIs can be hooked into if necessary)
• styles/1 defines a DSL for doing component and global styling similar to styled-jsx ergonomics with Next.

Controller

• emit/2 dispatches events
• events/0 Maps event listeners to view model state changes with built-in events for routing/etc. like choo's

[craigspaeth]

def model, do: [
  author: [
    id: :id!,
    first_name: :string,
    last_name: :string,
    posts: [:"[post!]!",
      "The list of Posts by this author",
      &resolve_posts/3
    ]
  ],
  post: [
    id: :id!,
    title: :string,
    author: :author,
    votes: :int
  ],
  query: [
    posts: [:"[post]", &resolve_posts/3]
  ],
  mutation: [
    upvote_post: [[post_id: :id!], :post, &resolve_upvote_post/3]
  ],
  schema: [
    query: :query,
    mutation: :mutation
  ]
]

DSL is like...

field_name: [
  args (keywords),
  return type (atom),
  description (string),
  resolver (func)
]
or
field_name: return type (atom)

[craigspaeth]

How the controller works:

Server:

Plug middleware...

1. Finds :route in events
2. Runs the corresponding func with VM.model(), ctx
3. Send VM.model(state) to view

Client:

1. Griffin script loads code
2. Runs emit(:dom_ready)
3. Mounts view
4. Runs emit(:route, url)