RFC: Consistent API

Okay, so my thoughts came together this morning 😃

I want to change the API surface of Cerebral to:

import { Controller, Module, Provider, Compute } from 'cerebral'

These are the constructs that Cerebral consists of and you use them like this:

Controller

The controller takes a module and options.

const controller =Controller(rootModule, {
  devtools: null
})

Module

The module is how you structure your application.

const app =Module({
  state: {},
  signals: {},
  providers: {},
  modules: {},
  catch: null
})

1. Providers are now an object instead of an array. This makes a more sense as providers needs a name and we do not need this provide factory:

const app =Module({
  state: {},
  providers: {
    http:HttpProvider({})
  }
})

1. The only way to catch an error now is at the module level. Errors propagate up to parent modules if not caught. Meaning there is no signal specific error catching or “global”. “Global” would be your root level module.

You still have a callback version

const app =Module(({ name, path, controller ) => ({
  state: {}
}))

Provider

Providers will now have a stronger concept. The concept is being the API between your application and your tools of choice. It can only be defined in one way, an object with methods. This makes things consistent and also enforces the idea that you think of a provider as a “bridge” between your app and the tools your are using.

const myProvider = Provider({
  foo() {}
})

With existing context:

const myProvider = Provider(({ http }) => ({
  foo() {
    return http.get()
  }
}))

All providers defined this way is automatically cached and wrapped for debugger purposes. You can still just add a tool if you want to:

Module({
  providers: { uuid }
})

But these are not wrapped.

Compute

This is just a change to be consistent with the other APIs:

const myComputed =Compute(state`foo`, (foo) => ())

Catch

There is no need to use Map for catching errors. Also catching is now moved to one spot… the module.

Module({
  signals: {},
  catch: [
    [Error, sequences.catchError]
  ]
})

Allrighty… please comment and I will get to work on this as soon as we agree. It is of course a breaking change, but it is small. This is what needs to be changed in the apps:

1. Change controller configuration to take in a top level module
2. Wrap all modules in Module constructor
3. Change configuration of providers to use object

Here is a video as well: https://drive.google.com/open?id=0B1pYKovu9UpyT1NTWVlHN0c2ZTA

[christianalfoni]

@nickbreaton Hehe, thanks for your input 😃 This is certainly interesting. It does make sense to make computed part of the module, allowing for the module tag to be used across action and connect usage. I will have to do a little bit of research here in case there is something I am missing, but it makes total sense. Thankful for fresh eyes here! 👍 😃

[nickbreaton]

I’m fairly new to Cerebral, and I have yet to built anything real with it, but I have built some things with Redux, MobX, and mobx-state-tree, so I feel like I can still understand some of the problems in this space.

The new module tag is awesome! I feel like it’s super important to be able to move modules are our applications, but not have to refactor any internal module code. The module tag us pretty close, but there is still one piece that I feel is pretty important. Computed properties.

As I was reading over this issue and related PR, something came to mind.

Like I said, I’m fairly new, but if this would be possible, I think it would be awesome. What if we could use compute at the module level:

/*
  Define our compute, but be able to use the module tag.
*/
const getFullName = Compute(module`firstName`, module`lastName`, (firstName, lastName) => {
  return `${firstName} ${lastName}`
})

/*
  Attach our compute to our module, by having a "computed" 
  key available to us. 
*/
const user = Module({
  state: {
    firstName: 'Joe',
    lastName: 'Smith'
  },
  computed: {
    fullName: getFullName
  }
})

/*
  We could then also have a "computed" tag.
  An example of using the "computed" tag in @cerebral/react:
*/
connect({
  firstName: state`user.firstName`,
  fullName: computed`user.fullName`
}, ({ firstName, fullName }) => (
  <div>
    <p>{firstName}'s full name is {fullName}</p>
  </div>
))

I think this would dramatically increase portability of compute, which for me personally, is a huge problem when using Redux selectors, and seems just about the same level of mess in Cerebral currently.

This is somewhat inspired by mobx-state-tree’s views layer.

If I’m completely off my rocker, please shoot me down. If this is something worth considering, I would gladly make a new issue for it. I would be willing to help with implementation as well, but it may take me some time to get up to speed.

Cerebral seems like an awesome project! Thanks for taking the time to read this.