If an store listens to an action 'foo', but app.create.action('foo') is not explicitly called, then the app creates an implicit action.

app.create.action('foo') creates an explicit action.

if two store try to listen to an action that isn't registered explicitely, then the app will warn/throw on app.start()

Pondering what should be easily available when.

From within an store's action callback:

@action is the action payload as packaged by the action packager.
@stores is a ref to the App.stores, so that @stores.fooStore.getFoosByID(id) can be called without needing to know about a global reference to the App itself.

From inside of an adaptor's callback for a a store change event:

@stores is available to get @stores.fooStore.getFoosByID()

@actions is funny, because calling them directly in the CB would result in nothing happening because the dispatcher wouldn't dispatch them.

If for some reason we wanted to send 'immeditaly-ish', we could have a function like @enqueue(@actions.fooAction) and it would wrap a setTimeout or something like it.

From inside of an mixin'd react view's callback for a store change event:

Going along with the idea that views shouldn't necessarily be part of App, views might want to reference the app via an actual variable.

Question: Do we care about having multiple apps? i.e. one view can subscribe to change events on one app and change events on a totally unrelated app?

Option #1: Mixins Per store. Global Refs all the way

FooView = React.CreateFactory React.CreateClass
  displayName: 'Foo View'
  mixins: [App.stores.fooStore.mixin, App.stores.boopStore.mixin]
  getInitialState: -> 
    foo: App.stores.fooStore.getFooByID(id)
  onFooStoreChange: -> 
    @setState foo: App.stores.fooStore.getFooByID(id)

Option #2: Mixins per store, set up store refs in the view

FooView = React.CreateFactory React.CreateClass
  displayName: 'Foo View 2'
  mixins: [App.stores.fooStore.mixin, App.stores.boopStore.mixin]
  getInitialState: -> 
    foo: @fooStore.getFooByID(id)
    boops: @boopStore.getBoops()
  onFooStoreChange: -> @setState foo: @fooStore.getFooByID(id)
  onBoopStoreChange: -> @setState boops: @boopStore.getBoops()

Option #3: 1 Mixin per app + store keys, set up single stores ref in the view

FooView = React.CreateFactory React.CreateClass
  displayName: 'Foo View 2'
  mixins: [App.ReactMixin(boop: 'onBoopChange', foo: 'onFooChange')]
  getInitialState: -> 
    foo: @stores.foo.getFooByID(id)
    boops: @stores.boop.getBoops()
  onFooChange: -> @setState foo: @stores.foo.getFooByID(id)
  onBoopChange: -> @setState boops: @stores.boop.getBoops()

it may require some use of ProvidePlugin to work properly.

http://webpack.github.io/docs/shimming-modules.html

The action validation syntax is awesome.

current:

app.create.action 'actionName', (arg1, arg2) -> 
  @require(_.isString(arg1), "arg1 must be a string)

Potential Improvement:

app.create.action 'actionName', (arg1, arg2) -> 
  @require _.isString(arg1), "arg1 must be a string"
  @suggest _.isBoolean(arg2), "arg2 should be a boolean"

name tbd. The idea where is that you want to let some thing slide but raise concern. if arg2 should be a boolean, but some truthy or falsey value is being passed then the app designer might want the system to still work, and then they can go and fiddle with the call site and coerce it to boolean or whatever they want to do.

This is sort of patterned off of react's array key warnings.

When higher level component changes due to a store subscription, it may unmount a lower level component, even if that component has subscriptions.

That lower level component's subscription callbacks may be run before componentWillUnmount is called to remove those subscription callbacks.

Checking this.isMounted() appears sufficient to execute a no-op instead.

If possible, the system should either:

(1) run these callbacks in the right order
(2) differentiate between the above condition and any more dangerous conditions

If no dangerous conditions exist, then the logging should just be removed.

In the case that you have something like:

app.create.action('actionName', function (foo) {
  this.require(foo, "foo is required")
  this.require(foo.id, "foo ID is required")
});

or even

app.create.action('actionName', function (foo) {
  this.require(foo.id, "foo ID is required")
});

If foo is undefined, then the exception should be caught and the action would not be dispatched.

We should not give store's action callbacks access to an @actions object.

But, async operations created via store methods could be controlled, and their callbacks could be executed in a second private context, which would have an @actions object present. (@action would likely also have to be wired up to match the calling action as show below, or variable references will need to be passed in some other way, whatever is more reliable)

Below is a store which has an @ajax method which copy's jquery's syntax, but binds the callbacks to the the special async context. A more generic @async method might also be appropriate. @promise is not much of a stretch from there. The only difference is that .done() or in fact any of the .then() calls would have access to the @update or other state altering methods. The .done() would have to issue an action in order to effect a change in state.

It is still the case that for larger applications, adapters should be used for async tasks like networking (especially if any sort of cooperation, throttling, queueing, etc is desired), but for simple stores that only make GET calls, this provides a much more succinct definition. It is effectively an 'inline adapter'.

app.createStore 'someStore',
  intialize: -> 
    @update
      baz: 1

  privateMethod: (foo, bar) -> 
    foo + bar

  api:
    publicMethod: (foo) -> 
      @get(foo)

  actions:
    'someAction': -> 
      @update(baz: @action.baz)

    'otherAction': ->
      @ajax
        url: "/api/0/foos/#{@action.fooId}"
        type: 'GET'
        success: (response) -> 
          @actions.newFoo(@action.fooId, response)
        error: (error) -> 
          @actions.fooError(@action.fooId, error)

    'newFoo': -> 
      @update(@action.fooId, @action.foo)

    'fooError': ->
      @update(@action.fooId, {type: 'error', timestamp: new Date().getTime()})

Problem Statement

Packaging action data onto an object provides 'named arugments' but leads to a bunch of boilerplate whenever you want to process an action as you peel the arguments back off.

Actions that do not pass data (somewhat an anti pattern, but not unreasonable) are ridiculous as they have no payload.

Trying to use the packager function as syntactic validation is cumbersome and unpredictable.

Proposal 1 (Will)

• Action args are simply positional arguments passed straight from the action caller to the action callbacks.
• createAction (or equivalent) declarations are only required if multiple stores listen to the same action.
• createAction's function is simply a validation function on the syntactic correctness of the passed arguments. It is therefore basically argTypes to React's propTypes.

app.create.store 'foos', 
  stores: ['bars']
  actions: 
    'foo.create': (fooData) -> 
      @update(fooData.id, fooData)
    'bar.setId': (barId) -> 
      @update(fooId: @stores.bar.getDefaultFooId())

app.create.store 'bars', 
  actions: 
    'bar.setId': (barId) -> @update(barId: barId)

app.create.action 'bar.setId', (barId) -> 
  @isNumber(barId)

given these stores and actions:

app.actions.foo.create( {id: 12, baz: 42} ) # fires action

app.actions.foo.create( {id: null, baz: 'bloop'} ) # still fires action, store might blow up.  

app.actions.bar.setBarId(12) # fires action

app.actions.bar.setBarId(null) # doesn't fire action, logs an error

Given an action like so:

app.create.action 'actionName', (arg1, arg2) -> 
  @require _.isString(arg1), "arg1 must be a string"

and a call like so:

> app.actions.actionName(null, null)
'viewName' sent the action 'actionName' with args [null, null] but validation failed with messages: 
      - arg1 must be a string
and the action was not dispatched.  
[storeName1,  storeName2] subscribe to this action

It would be nice if the action validator messsages spat out as much context as they can about what was going on in the state of the system when the action failed.