createStore

(StoreModel: function, iden: ?string, …constructorArgs): AltStore

This is a function that takes in a class of your store and returns back the singleton store. The second parameter iden is a string that is used as a unique identifier for serializing/deserializing your store. The name of the store comes from the class name but on production due to heavy minification it is a good idea to provide your own name to avoid collisions. constructorArgs are passed to the StoreModel constructor (if StoreModel is a class).

StoreModel

StoreModel.config

The config object on your store classes allow you to configure your stores for specific behavior.

Available configuration options:

setState

setState(currentState: object, nextState: object): object

setState is used internally by Alt to set the state. You can override this to provide your own setState implementation. Internally, setState is an alias for Object.assign. setState must return an object.

getState

getState(currentState: object): mixed

getState receives the current state and returns a copy of it. You can override this function to provide your own implementation.

onSerialize

onSerialize is also called before the store’s state is serialized. You may optionally return an object, which will be used directly as the snapshot data for the store. If you do not return anything, the default, MyStore#getState() is used for the snapshot data. See the serialization for an example.

class TodoStore {
  static config = {
    onSerialize: function(data) {
      // do something here
      // optional return of data to be used in snapshot
      // return mySnapshotData
    }
  }
}

onDeserialize

onDeserialize is called before the store’s state is deserialized. This occurs whenever the store’s state is being set to an existing snapshot/bootstrap data. Here you can perform any final tasks you need to before the snapshot/bootstrap data is set on the store such as mapping the data to model objects, or converting data an external source like a JSON API into a format the store expects. onDeserialize takes in a parameter that is an object of snapshot/bootstrap data and must return the data to be set to the store’s state. If nothing is returned, then the data from the snapshot is set to the store’s state. See the serialization for an example.

class TodoStore {
  static config = {
    onDeserialize: function(data) {
      // do something here
      return modifiedData
    }
  }
}

StoreModel#constructor

(…args): StoreModel

The constructor of your store definition receives any constructor arguments passed through the createStore function. All instance variables, values assigned to this, in any part of the StoreModel will become part of state.

StoreModel#on

(lifecycleMethod: string, handler: function): undefined

This method can be used to listen to Lifecycle events. Normally they would be set up in the constructor.

class MyStore {
  constructor() {
    this.on('bootstrap', () => {
    });
  }
}

StoreModel#bindAction

(actionsSymbol: symbol, storeHandler: function): undefined

This method takes in an action’s symbol and a store’s method defined in your StoreModel class. The store’s method is then bound to that action so whenever the action dispatches a payload, the specified handler will receive it.

class MyStore {
  constructor() {
    this.bindAction(MyActions.FOO, this.handleFoo);
  }

  handleFoo(data) {
    // do something with data
  }
}

StoreModel#bindActions

(actions: object): undefined

This is a magic method which takes in an object of action symbols and binds them to their specially named handlers which are defined in the StoreModel. An action with the name foo will match an action handler method defined in the StoreModel named onFoo or just foo but not both.

class MyStore {
  constructor() {
    this.bindActions(MyActions);
  }

  onFoo(data) {
    // do something with data
  }
}

StoreModel#bindListeners

(listenersMap: object): undefined

bindListeners is the inversion of bindAction but in a much more convenient way. With this method you can exercise precise control over which actions you wish your store listens to and what handlers those actions are bound to. bindListeners accepts an object where the keys correspond to the method in your StoreModel and the values can either be an array of action symbols or a single action symbol.

class MyStore {
  constructor() {
    this.bindListeners({
      handleFoo: MyActions.FOO,
      handleBar: [MyActions.BAR, OtherActions.BAR]
    });
  }

  handleFoo(data) {
    // will only be called by MyActions.foo()
  }

  handleBar(data) {
    // will be called by MyActions.bar() and OtherActions.bar()
  }
}

StoreModel#waitFor

(dispatcherSource: mixed): undefined

dispatcherSource can be either a single token/source or an array of tokens/sources. waitFor is mostly an alias for the flux dispatcher’s waitFor method. This method is used to enable dependencies between stores and signal to the dispatcher that this store needs to wait for another store to update first before it can be updated itself.

class MyStore {
  onFoo(data) {

    // All of these do the same thing:
    this.waitFor(OtherStore);
    this.waitFor(OtherStore.dispatchToken);

    // You can also pass in multiple stores, these are all the same:
    this.waitFor([Store1, Store2]);
    this.waitFor([Store1.dispatchToken, Store2.dispatchToken]);
    this.waitFor(Store1, Store2);
    this.waitFor(Store1.dispatchToken, Store2.dispatchToken);

    // handle data once OtherStore is updated
  }
}

StoreModel#setState

(state = {}: function

object): undefined

setState is the recommended way to set state for a store. This method automatically emits a change event. setState also accepts a function which returns an object of the state to be set. For convenience, calls to setState are automatically batched as they are in React and only one change event will be emitted once the action finishes dispatching.

class MyStore {
  handleFoo() {
    this.state = { foo: 0 };

    setTimeout(() => {
      // set foo to 1 and emit a change.
      this.setState({
        foo: 1
      });
    }, 100);

    // supress emitting a change.
    this.preventDefault();
  }
}

StoreModel#exportPublicMethods

(methods: object): undefined

exportPublicMethods is an explicit, less magical alternative to declaring public methods as type static. The method accepts an object where the keys correspond to a method that exists inside or outside the StoreModel object.

const externalFunc = () => {
  // do something
};

class StoreBase {
  baseMethod() {
    // do something
  }
}

class Store extends StoreBase {
  constructor() {
    this.exportPublicMethods({
      baseMethod: this.baseMethod,
      ownMethod: this.ownMethod,
      externalFunc: externalFunc
    });
  }

  ownMethod() {
    // do something
  }
}

StoreModel#getInstance

(): (AltStore)[stores.md]

This method retrieves the store instance which contains any of the public methods you’ve exported as well as the listen/unlisten methods.

class MyStore {
  constructor() {
    this.exportPublicMethods({
      accessToPublicMethod: () => 2
    });
  }

  handleFoo() {
    this.getInstance().accessToPublicMethod();
  }
}

StoreModel#emitChange

(): undefined

Shorthand for emitting a change from within a store.

class MyStore {
  handleFoo() {
    setTimeout(() => {
      this.emitChange();
    }, 100);

    // supress emitting a change.
    this.preventDefault();
  }
}

StoreModel#dispatcher

This is a reference to the dispatcher used by alt which is flux’s own dispatcher. You may use this to listen in on all the global dispatches yourself.

this.dispatcher.register(function (payload) {
  console.log(payload);
});

StoreModel#alt

This is a reference to the alt instance. It can be used for getting other stores, dispatching, recycling, flushing, bootstrapping, snapshotting, etc. If you’re using alt stores as instances rather than singletons then this property is very useful.

class MyStore {
  constructor() {
    const actions = this.alt.getActions('MyActions');
  }
}

StoreModel#displayName

This is a reference to the store’s internal name. This is either the identifier you provided to createStore or StoreModel’s class name.

StoreModel#otherwise

otherwise(data, action)

This is a method you can implement in your store in order to receive all dispatches that are not currently being handled in your store explicitly via bindActions, bindAction, or bindListeners. This is similar to guards matching in Haskell.

StoreModel#output

output(state): {}

A method you can use to control the output of what gets sent down to listen() as “state”.

output(state) {
  return { foo: 'bar' }
}

store.listen((state) => {
  state.foo === 'bar'
})

StoreModel#reduce

reduce(state, { action, data }): {}

Another method you can implement in your store. This method receives all dispatches and the result that is returned is then set as the new state of your store. This way you can write your stores as reducers of dispatches.

StoreModel#preventDefault

You may call this method in order to suppress a change event from being pushed. Alternatively, you can just return false from your action handler in your store.

StoreModel#observe

observe(alt): {}

A method you can implement in your stores, mostly useful when using plain objects to create a store. This method will receive the current alt instance and returns an object containing the methods/actions it’ll handle.