Local Storage Middleware (#65)

* Local Storage Middleware

* Cannot set local storage on browsers, so stub if exists

* fix tests

* skip safari tests

Author: agubler

src/stores/README.md

@@ -26,8 +26,9 @@ An application store designed to complement @dojo/widgets and @dojo/widget-core
      - [Transforming Executor Arguments](#transforming-executor-arguments)
      - [Optimistic Update Pattern](#optimistic-update-pattern)
      - [Executing Concurrent Commands](#executing-concurrent-commands)
-     - [Decorating Processes](#decorating-processes)
-        - [Decorating Multiple Processes](#decorating-multiple-processes)
+ - [Middleware](#middleware)
+     - [Applying Middleware to Multiple Processes](#applying-middleware-to-multiple-processes)
+     - [Local Storage Middleware](#local-storage-middleware)
 
 -----
 
@@ -524,21 +525,23 @@ In this example, `commandOne` is executed, then both `concurrentCommandOne` and
 
 **Note:** Concurrent commands are always assumed to be asynchronous and resolved using `Promise.all`.
 
-### Decorating Processes
+## Middleware
 
-The `Process` callback provides a hook to apply generic/global functionality across multiple or all processes used within an application. This is done using higher order functions that wrap the process' local `callback` using the error and result payload to decorate or perform an action for all processes it is used for.
+Middleware provides a hook to apply generic/global functionality across multiple or all processes used within an application. Middleware is a function that receives the error and the result of a process to perform a specific action, before calling the next middleware if provided.
+
+This is done using higher order functions that wrap the process' local `callback` using the error and result payload to decorate or perform an action for all processes it is used for.
 
 `callback` decorators can be composed together to combine multiple units of functionality, such that in the example below `myProcess` would run the `error` and `result` through the `collector`, `logger` and then `snapshot` callbacks.
 
 ```ts
 const myProcess = createProcess('my-process', [ commandOne, commandTwo ], collector(logger(snapshot())));
 ```
 
-#### Decorating Multiple Processes
+### Applying Middleware to Multiple Processes
 
-Specifying a `callback` decorator on an individual process explicitly works for targeted behavior but can become cumbersome when the decorator needs to be applied to multiple processes throughout the application.
+Specifying a middleware on an individual process explicitly works for targeted behavior but can become cumbersome when the middleware needs to be applied to multiple processes throughout the application.
 
-The `createProcessWith` higher order function can be used to specify `callback` decorators that need to be applied across multiple `processes`. The function accepts an array of `callback` decorators and returns a new `createProcess` factory function that will automatically apply the decorators to any process that it creates.
+The `createProcessWith` higher order function can be used to specify middlewares that need to be applied across multiple `processes`. The function accepts an array of middleware and returns a new `createProcess` factory function that will automatically apply the middleware to any process that it creates.
 
 ```ts
 const customCreateProcess = createProcessWith([ logger ]);
@@ -547,18 +550,43 @@ const customCreateProcess = createProcessWith([ logger ]);
 const myProcess = customCreateProcess('my-process', [ commandOne, commandTwo ]);
 ```
 
-An additional helper function `createCallbackDecorator` can be used to turn a simple `ProcessCallback` into a decorator that ensures the passed callback is executed after the decorating `callback` has been run.
+An additional helper function `createCallbackDecorator` can be used to ensure that a middleware function calls the next middleware after it has finished executing.
 
 ```ts
-const myCallback = (error: ProcessError, result: ProcessResult) => {
+const myMiddleware = (error: ProcessError, result: ProcessResult) => {
 	// do things with the outcome of the process
 };
 
-// turns the callback into a callback decorator
-const myCallbackDecorator = createCallbackDecorator(myCallback);
+// ensures the middleware will call the next middleware in the stack
+const myMiddlewareDecorator = createCallbackDecorator(myMiddleware);
+
+// use the middleware decorator as normal
+const myProcess = createProcess('my-process', [ commandOne ], myMiddlewareDecorator());
+```
+
+### Local Storage Middleware
+
+Middleware that provides a `collector` that saves state to `LocalStorage` and a `load` function to hydrate a store from `LocalStorage`.
+
+```ts
+export const myProcess = createProcess(
+	'my-process',
+	[ command ],
+	collector('my-process', (path) => {
+		return [
+			path('state', 'to', 'save'),
+			path('other', 'state', 'to', 'save')
+		];
+	})
+);
+```
+
+```ts
+import { load } from '@dojo/framework/stores/middleware/localStorage';
+import { Store } from '@dojo/framework/stores/Store';
 
-// use the callback decorator as normal
-const myProcess = createProcess('my-process', [ commandOne ], myCallbackDecorator());
+const store = new Store();
+load('my-process', store);
 ```
 
 <!-- doc-viewer-config

src/stores/middleware/localStorage.ts

@@ -0,0 +1,32 @@
+import global from '../../shim/global';
+import { ProcessError, ProcessResult, ProcessCallback, processExecutor } from '../process';
+import { Store } from '../Store';
+import { GetPaths } from '../StoreInjector';
+import { add } from '../state/operations';
+
+export function collector<T = any>(id: string, getPaths: GetPaths<T>, callback?: ProcessCallback): ProcessCallback {
+	return (error: ProcessError | null, result: ProcessResult): void => {
+		const paths = getPaths(result.store.path);
+		const data = paths.map((path) => {
+			const state = result.get(path);
+			return { meta: { path: path.path }, state };
+		});
+		global.localStorage.setItem(id, JSON.stringify(data));
+		callback && callback(error, result);
+	};
+}
+
+export function load<T>(id: string, store: Store<T>) {
+	let data = global.localStorage.getItem(id);
+	if (data) {
+		try {
+			const parsedData: any[] = JSON.parse(data);
+			const operations = parsedData.map((item) => {
+				return add(store.path(item.meta.path), item.state);
+			});
+			processExecutor('local-storage-load', [() => operations], store, undefined, undefined)({});
+		} catch {
+			// do nothing?
+		}
+	}
+}

tests/stores/unit/all.ts

@@ -1,4 +1,5 @@
 import './middleware/HistoryManager';
+import './middleware/localStorage';
 import './Store';
 import './process';
 import './state/all';

tests/stores/unit/middleware/localStorage.ts

@@ -0,0 +1,90 @@
+import global from '../../../../src/shim/global';
+const { describe, it, beforeEach, before } = intern.getInterface('bdd');
+const { assert } = intern.getPlugin('chai');
+
+import { collector, load } from './../../../../src/stores/middleware/localStorage';
+import { Store } from './../../../../src/stores/Store';
+import { CommandRequest, createProcess } from '../../../../src/stores/process';
+import { PatchOperation, OperationType } from '../../../../src/stores/state/Patch';
+import { Pointer } from '../../../../src/stores/state/Pointer';
+
+function incrementCounter({ get, path }: CommandRequest<{ counter: number }>): PatchOperation[] {
+	let counter = get(path('counter')) || 0;
+	return [{ op: OperationType.REPLACE, path: new Pointer('/counter'), value: ++counter }];
+}
+
+const LOCAL_STORAGE_TEST_ID = 'local-storage-id';
+
+if (!global.localStorage) {
+	global.localStorage = {
+		storage: {},
+		getItem(this: any, key: string) {
+			return this.storage[key];
+		},
+		setItem(this: any, key: string, item: string) {
+			this.storage[key] = item;
+		},
+		removeItem(this: any, key: string) {
+			delete this.storage[key];
+		}
+	};
+}
+
+let store: Store;
+
+describe('middleware - local storage', (suite) => {
+	before(() => {
+		try {
+			global.localStorage.setItem('test', '');
+		} catch {
+			suite.skip('Local Storage is not accessible on private mode pre version 11.');
+		}
+	});
+
+	beforeEach(() => {
+		global.localStorage.removeItem(LOCAL_STORAGE_TEST_ID);
+		store = new Store();
+	});
+
+	it('Should save state to local storage', () => {
+		const incrementCounterProcess = createProcess(
+			'increment',
+			[incrementCounter],
+			collector(LOCAL_STORAGE_TEST_ID, (path) => [path('counter')])
+		);
+		incrementCounterProcess(store)({});
+		assert.deepEqual(
+			global.localStorage.getItem(LOCAL_STORAGE_TEST_ID),
+			'[{"meta":{"path":"/counter"},"state":1}]'
+		);
+	});
+
+	it('Should call next middleware', () => {
+		let composedMiddlewareCalled = false;
+		const incrementCounterProcess = createProcess(
+			'increment',
+			[incrementCounter],
+			collector(
+				LOCAL_STORAGE_TEST_ID,
+				(path) => [path('counter')],
+				(error, result) => {
+					composedMiddlewareCalled = true;
+				}
+			)
+		);
+		incrementCounterProcess(store)({});
+		assert.isTrue(composedMiddlewareCalled);
+	});
+
+	it('should load from local storage', () => {
+		global.localStorage.setItem(LOCAL_STORAGE_TEST_ID, '[{"meta":{"path":"/counter"},"state":1}]');
+		load(LOCAL_STORAGE_TEST_ID, store);
+		assert.deepEqual((store as any)._state, { counter: 1 });
+	});
+
+	it('should not load anything or throw an error if data does exist', () => {
+		global.localStorage.setItem('other-storage-id', '[{"meta":{"path":"/counter"},"state":1}]');
+		load(LOCAL_STORAGE_TEST_ID, store);
+		assert.deepEqual((store as any)._state, {});
+	});
+});