Improved mutator API

src/CombinedMutator.ts

@@ -0,0 +1,31 @@
+import ActionMessage from './interfaces/ActionMessage';
+import MutatorMap from './interfaces/MutatorMap';
+
+export default class CombinedMutator<TState extends { [key: string]: any }> {
+    private mutatorKeys: string[];
+
+    constructor(private mutatorMap: MutatorMap<TState>) {
+        this.mutatorKeys = Object.keys(this.mutatorMap);
+    }
+
+    getInitialValue() {
+        let initialValue: TState = <TState>{};
+        this.mutatorKeys.forEach(key => {
+            initialValue[key] = this.mutatorMap[key].getInitialValue();
+        });
+
+        return initialValue;
+    }
+
+    handleAction(
+        currentState: TState,
+        actionMessage: ActionMessage,
+        replaceState: (newState: TState) => void
+    ) {
+        this.mutatorKeys.forEach(key => {
+            this.mutatorMap[key].handleAction(currentState[key], actionMessage, newState => {
+                currentState[key] = newState;
+            });
+        });
+    }
+}

src/LeafMutator.ts

@@ -0,0 +1,47 @@
+import ActionCreator from './interfaces/ActionCreator';
+import ActionMessage from './interfaces/ActionMessage';
+import { getPrivateActionId } from './actionCreator';
+
+export type MutatorHandler<TState, TAction extends ActionMessage> = (
+    state: TState,
+    action: TAction
+) => TState | void;
+
+// Represents a mutator for a leaf node in the state tree
+export default class LeafMutator<TState> {
+    private handlers: { [actionId: string]: MutatorHandler<TState, ActionMessage> } = {};
+
+    constructor(private initialValue: TState) {}
+
+    getInitialValue() {
+        return this.initialValue;
+    }
+
+    handles<TAction extends ActionMessage>(
+        actionCreator: ActionCreator<TAction>,
+        handler: MutatorHandler<TState, TAction>
+    ) {
+        let actionId = getPrivateActionId(actionCreator);
+        if (this.handlers[actionId]) {
+            throw new Error('A mutator may not handle the same action twice.');
+        }
+
+        this.handlers[actionId] = handler;
+        return this;
+    }
+
+    handleAction(
+        currentState: TState,
+        actionMessage: ActionMessage,
+        replaceState: (newState: TState) => void
+    ) {
+        let actionId = getPrivateActionId(actionMessage);
+        let handler = this.handlers[actionId];
+        if (handler) {
+            let returnValue = handler(currentState, actionMessage);
+            if (returnValue !== undefined) {
+                replaceState(<TState>returnValue);
+            }
+        }
+    }
+}

src/combineMutators.ts

@@ -0,0 +1,6 @@
+import MutatorMap from './interfaces/MutatorMap';
+import CombinedMutator from './CombinedMutator';
+
+export default function combineMutators<TState>(mutatorMap: MutatorMap<TState>) {
+    return new CombinedMutator(mutatorMap);
+}

src/createMutator.ts

@@ -0,0 +1,5 @@
+import LeafMutator from './LeafMutator';
+
+export default function createMutator<TState>(initialValue: TState) {
+    return new LeafMutator(initialValue);
+}

src/createStore.ts

@@ -1,5 +1,9 @@
 import { action } from 'mobx';
 import getRootStore from './getRootStore';
+import CombinedMutator from './CombinedMutator';
+import LeafMutator from './LeafMutator';
+import { subscribeAll } from './dispatcher';
+import wrapMutator from './wrapMutator';
 
 let createStoreAction = action('createStore', function createStoreAction(
     key: string,
@@ -8,7 +12,36 @@ let createStoreAction = action('createStore', function createStoreAction(
     getRootStore().set(key, initialState);
 });
 
-export default function createStore<T>(key: string, initialState: T): () => T {
+export default function createStore<TState>(
+    key: string,
+    arg2: TState | LeafMutator<TState> | CombinedMutator<TState>
+): () => TState {
+    // Get the initial state (from the mutator, if necessary)
+    let mutator = getMutator(arg2);
+    let initialState = mutator ? mutator.getInitialValue() : arg2;
+
+    // Create the store under the root store
     createStoreAction(key, initialState);
-    return () => <T>getRootStore().get(key);
+    let getStore = () => <TState>getRootStore().get(key);
+
+    // If necessary, hook the mutator up to the dispatcher
+    if (mutator) {
+        subscribeAll(
+            wrapMutator(actionMessage => {
+                mutator.handleAction(getStore(), actionMessage, newState => {
+                    getRootStore().set(key, newState);
+                });
+            })
+        );
+    }
+
+    return getStore;
+}
+
+function getMutator<TState>(mutator: TState | LeafMutator<TState> | CombinedMutator<TState>) {
+    if ((<any>mutator).handleAction) {
+        return <LeafMutator<TState> | CombinedMutator<TState>>mutator;
+    }
+
+    return null;
 }

src/dispatcher.ts

@@ -3,7 +3,7 @@ import Subscriber from './interfaces/Subscriber';
 import { getPrivateActionId } from './actionCreator';
 import { getGlobalContext } from './globalContext';
 
-export function subscribe(actionId: string, callback: Subscriber<any>) {
+export function subscribe(actionId: string, callback: Subscriber<ActionMessage>) {
     let subscriptions = getGlobalContext().subscriptions;
     if (!subscriptions[actionId]) {
         subscriptions[actionId] = [];
@@ -12,6 +12,10 @@ export function subscribe(actionId: string, callback: Subscriber<any>) {
     subscriptions[actionId].push(callback);
 }
 
+export function subscribeAll(callback: Subscriber<ActionMessage>) {
+    getGlobalContext().subscriptionsToAll.push(callback);
+}
+
 export function dispatch(actionMessage: ActionMessage) {
     if (getGlobalContext().inMutator) {
         throw new Error('Mutators cannot dispatch further actions.');
@@ -23,20 +27,27 @@ export function dispatch(actionMessage: ActionMessage) {
 
 export function finalDispatch(actionMessage: ActionMessage): void | Promise<void> {
     let actionId = getPrivateActionId(actionMessage);
-    let subscribers = getGlobalContext().subscriptions[actionId];
+    let promises: Promise<any>[] = [];
 
+    // Callback subscribers to specific actions
+    let subscribers = getGlobalContext().subscriptions[actionId];
     if (subscribers) {
-        let promises: Promise<any>[] = [];
-
         subscribers.forEach(subscriber => {
             let returnValue = subscriber(actionMessage);
             if (returnValue) {
                 promises.push(returnValue);
             }
         });
+    }
+
+    // Callback subscribers to all actions
+    getGlobalContext().subscriptionsToAll.forEach(subscriber => {
+        // These subscribers must be mutators, which cannot be async
+        subscriber(actionMessage);
+    });
 
-        if (promises.length) {
-            return promises.length == 1 ? promises[0] : Promise.all(promises);
-        }
+    // If multiple promises are returned, merge them
+    if (promises.length) {
+        return promises.length == 1 ? promises[0] : Promise.all(promises);
     }
 }

src/globalContext.ts

@@ -13,6 +13,7 @@ export interface GlobalContext {
     rootStore: ObservableMap<any>;
     nextActionId: number;
     subscriptions: { [key: string]: Subscriber<ActionMessage>[] };
+    subscriptionsToAll: Subscriber<ActionMessage>[];
     dispatchWithMiddleware: DispatchFunction;
     inMutator: boolean;
 
@@ -38,6 +39,7 @@ export function __resetGlobalContext() {
         rootStore: observable.map({}),
         nextActionId: 0,
         subscriptions: {},
+        subscriptionsToAll: [],
         dispatchWithMiddleware: null,
         inMutator: false,
         legacyInDispatch: 0,

src/index.ts

@@ -9,10 +9,13 @@ export { default as MutatorFunction } from './interfaces/MutatorFunction';
 export { default as OrchestratorFunction } from './interfaces/OrchestratorFunction';
 export { action, actionCreator } from './actionCreator';
 export { default as applyMiddleware } from './applyMiddleware';
+export { default as createMutator } from './createMutator';
+export { default as combineMutators } from './combineMutators';
 export { default as createStore } from './createStore';
 export { dispatch } from './dispatcher';
-export { default as mutator } from './mutator';
-import { default as orchestrator } from './orchestrator';
+export { default as mutator } from './mutatorDecorator';
+export { default as LeafMutator } from './LeafMutator';
+import { default as orchestrator } from './orchestratorDecorator';
 export { default as getRootStore } from './getRootStore';
 export { mutatorAction, orchestratorAction } from './simpleSubscribers';
 export { useStrict };

src/interfaces/MutatorMap.ts

@@ -0,0 +1,8 @@
+import LeafMutator from '../LeafMutator';
+import CombinedMutator from '../CombinedMutator';
+
+type MutatorMap<TState extends { [key: string]: any }> = {
+    [K in keyof TState]: LeafMutator<TState[K]> | CombinedMutator<TState[K]>
+};
+
+export default MutatorMap;

src/mutator.ts → src/mutatorDecorator.ts

@@ -6,6 +6,7 @@ import MutatorFunction from './interfaces/MutatorFunction';
 import { getPrivateActionId } from './actionCreator';
 import { subscribe } from './dispatcher';
 import { getGlobalContext } from './globalContext';
+import wrapMutator from './wrapMutator';
 
 export default function mutator<T extends ActionMessage>(
     actionCreator: ActionCreator<T>,
@@ -16,20 +17,9 @@ export default function mutator<T extends ActionMessage>(
         throw new Error('Mutators can only subscribe to action creators.');
     }
 
-    // Wrap the callback in a MobX action so it can modify the store
-    let wrappedTarget = action((actionMessage: T) => {
-        try {
-            getGlobalContext().inMutator = true;
-            if (target(actionMessage)) {
-                throw new Error('Mutators cannot return a value and cannot be async.');
-            }
-        } finally {
-            getGlobalContext().inMutator = false;
-        }
-    });
-
     // Subscribe to the action
-    subscribe(actionId, wrappedTarget);
+    subscribe(actionId, wrapMutator(target));
 
+    // Return the original function so it can be exported for tests
     return target;
 }

src/simpleSubscribers.ts

@@ -2,8 +2,8 @@ import ActionCreator from './interfaces/ActionCreator';
 import SimpleAction from './interfaces/SimpleAction';
 import Subscriber from './interfaces/Subscriber';
 import { action } from './actionCreator';
-import mutator from './mutator';
-import orchestrator from './orchestrator';
+import mutator from './mutatorDecorator';
+import orchestrator from './orchestratorDecorator';
 
 export function createSimpleSubscriber(decorator: Function) {
     return function simpleSubscriber<T extends SimpleAction>(actionType: string, target: T): T {

src/wrapMutator.ts

@@ -0,0 +1,21 @@
+import { action } from 'mobx';
+import ActionMessage from './interfaces/ActionMessage';
+import MutatorFunction from './interfaces/MutatorFunction';
+import { getGlobalContext } from './globalContext';
+
+// Wraps the target function for use as a mutator
+export default function wrapMutator<T extends ActionMessage>(
+    target: MutatorFunction<T>
+): MutatorFunction<T> {
+    // Wrap the target in a MobX action so it can modify the store
+    return action((actionMessage: T) => {
+        try {
+            getGlobalContext().inMutator = true;
+            if (target(actionMessage)) {
+                throw new Error('Mutators cannot return a value and cannot be async.');
+            }
+        } finally {
+            getGlobalContext().inMutator = false;
+        }
+    });
+}

test/CombinedMutatorTests.ts

@@ -0,0 +1,59 @@
+import { actionCreator } from '../src/index';
+import CombinedMutator from '../src/CombinedMutator';
+import createMutator from '../src/createMutator';
+
+describe('CombinedMutator', () => {
+    const mutatorA = createMutator('a');
+    const mutatorB = createMutator('b');
+
+    it('combines the initial values of its child mutators', () => {
+        // Act
+        let combinedMutator = new CombinedMutator({
+            A: mutatorA,
+            B: mutatorB,
+        });
+
+        // Assert
+        expect(combinedMutator.getInitialValue()).toEqual({ A: 'a', B: 'b' });
+    });
+
+    it('dispatches actions to each child mutator', () => {
+        // Arrange
+        const actionMessage = {};
+        const spyA = spyOn(mutatorA, 'handleAction');
+        const spyB = spyOn(mutatorB, 'handleAction');
+
+        let combinedMutator = new CombinedMutator({
+            A: mutatorA,
+            B: mutatorB,
+        });
+
+        // Act
+        combinedMutator.handleAction({ A: 'a', B: 'b' }, actionMessage, null);
+
+        // Assert
+        expect(spyA.calls.argsFor(0)[0]).toBe('a');
+        expect(spyA.calls.argsFor(0)[1]).toBe(actionMessage);
+        expect(spyB.calls.argsFor(0)[0]).toBe('b');
+        expect(spyB.calls.argsFor(0)[1]).toBe(actionMessage);
+    });
+
+    it('replaces a child state when the replaceState callback gets called', () => {
+        // Arrange
+        spyOn(
+            mutatorA,
+            'handleAction'
+        ).and.callFake((state: any, actionMessage: any, replaceState: Function) => {
+            replaceState('x');
+        });
+
+        let state = { A: 'a' };
+        let combinedMutator = new CombinedMutator({ A: mutatorA });
+
+        // Act
+        combinedMutator.handleAction(state, {}, null);
+
+        // Assert
+        expect(state.A).toBe('x');
+    });
+});