shared-reducer 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2024 David Evans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# Shared Reducer
+
+Shared state management via websockets.
+
+Designed to work with
+[json-immutability-helper](https://github.com/davidje13/json-immutability-helper).
+
+## Install dependency
+
+```bash
+npm install --save shared-reducer json-immutability-helper
+```
+
+(if you want to use an alternative reducer, see the instructions below).
+
+## Usage (Backend)
+
+This project is compatible with
+[websocket-express](https://github.com/davidje13/websocket-express),
+but can also be used in isolation.
+
+### With websocket-express
+
+```js
+import {
+  Broadcaster,
+  websocketHandler,
+  InMemoryModel,
+  ReadWrite,
+} from 'shared-reducer/backend';
+import context from 'json-immutability-helper';
+import { WebSocketExpress } from 'websocket-express';
+
+const model = new InMemoryModel();
+const broadcaster = Broadcaster.for(model)
+  .withReducer(context)
+  .build();
+model.set('a', { foo: 'v1' });
+
+const app = new WebSocketExpress();
+const server = app.listen(0, 'localhost');
+
+const handler = websocketHandler(broadcaster);
+app.ws('/:id', handler((req) => req.params.id, () => ReadWrite));
+```
+
+For real use-cases, you will probably want to add authentication middleware
+to the expressjs chain, and you may want to give some users read-only and
+others read-write access, which can be achieved in the second lambda.
+
+### Alone
+
+```js
+import { Broadcaster, InMemoryModel } from 'shared-reducer/backend';
+import context from 'json-immutability-helper';
+
+const model = new InMemoryModel();
+const broadcaster = Broadcaster.for(model)
+  .withReducer(context)
+  .build();
+model.set('a', { foo: 'v1' });
+
+// ...
+
+const subscription = await broadcaster.subscribe(
+  'a',
+  (change, meta) => { /*...*/ },
+);
+
+const begin = subscription.getInitialData();
+await subscription.send(['=', { foo: 'v2' }]);
+// callback provided earlier is invoked
+
+await subscription.close();
+```
+
+## Persisting data
+
+A convenience wrapper is provided for use with
+[collection-storage](https://github.com/davidje13/collection-storage),
+or you can write your own implementation of the `Model` interface to
+link any backend.
+
+```js
+import {
+  Broadcaster,
+  CollectionStorageModel,
+} from 'shared-reducer/backend';
+import context from 'json-immutability-helper';
+import CollectionStorage from 'collection-storage';
+
+const db = await CollectionStorage.connect('memory://something');
+const model = new CollectionStorageModel(
+  db.getCollection('foo'),
+  'id',
+  // a function which takes in an object and returns it if valid,
+  // or throws if invalid (protects stored data from malicious changes)
+  MY_VALIDATOR,
+);
+const broadcaster = Broadcaster.for(model)
+  .withReducer(context)
+  .build();
+```
+
+Note that the provided validator MUST verify structural integrity (e.g.
+ensuring no unexpected fields are added or types are changed).
+
+## Usage (Frontend)
+
+```javascript
+import { SharedReducer, actionsHandledCallback, actionsSyncedCallback } from 'shared-reducer/frontend';
+import context from 'json-immutability-helper';
+
+const reducer = SharedReducer
+  .for('ws://destination', (state) => {
+    console.log('latest state is', state);
+  })
+  .withReducer(context)
+  .withToken('my-token')
+  .withErrorHandler((error) => { console.log('connection lost', error); })
+  .withWarningHandler((warning) => { console.log('latest change failed', warning); })
+  .build();
+
+const dispatch = reducer.dispatch;
+
+dispatch([
+  { a: ['=', 8] },
+]);
+
+dispatch([
+  (state) => {
+    return {
+      a: ['=', Math.pow(2, state.a)],
+    };
+  },
+]);
+
+dispatch([
+  actionsHandledCallback((state) => {
+    console.log('state after handling is', state);
+  }),
+]);
+
+dispatch([
+  actionsSyncedCallback((state) => {
+    console.log('state after syncing is', state);
+  }),
+]);
+
+dispatch([
+  { a: ['add', 1] },
+  { a: ['add', 1] },
+]);
+```
+
+### Specs
+
+The specs need to match whichever reducer you are using. In the examples
+above, that is
+[json-immutability-helper](https://github.com/davidje13/json-immutability-helper).
+
+## WebSocket protocol
+
+The websocket protocol is minimal:
+
+### Client-to-server
+
+`<token>`:
+The authentication token is sent as the first message when the connection is
+established. This is plaintext. The server should respond by either terminating
+the connection (if the token is deemed invalid), or with an `init` event which
+defines the latest state in its entirety. If no token is specified using
+`withToken`, no message will be sent (when not using authentication, it is
+assumed the server will send the `init` event unprompted).
+
+`P` (ping):
+Can be sent periodically to keep the connection alive. The server sends a
+"Pong" message in response immediately.
+
+`{"change": <spec>, "id": <id>}`:
+Defines a delta. This may contain the aggregate result of many operations
+performed on the client. The ID is an opaque identifier which is reflected
+back to the same client in the confirmation message. Other clients will not
+receive the ID.
+
+### Server-to-client
+
+`p` (pong):
+Reponse to a ping. May also be sent unsolicited.
+
+`{"init": <state>}`:
+The first message sent by the server, in response to a successful
+connection.
+
+`{"change": <spec>}`:
+Sent whenever another client has changed the server state.
+
+`{"change": <spec>, "id": <id>}`:
+Sent whenever the current client has changed the server state. Note that
+the spec and ID will match the client-sent values.
+
+The IDs sent by different clients can coincide, so the ID is only reflected
+to the client which sent the spec.
+
+`{"error": <message>, "id": <id>}`:
+Sent if the server rejects a client-initiated change.
+
+If this is returned, the server state will not have changed (i.e. the
+entire spec failed).
+
+### Specs
+
+The specs need to match whichever reducer you are using. In the examples
+above, that is
+[json-immutability-helper](https://github.com/davidje13/json-immutability-helper).
+
+## Alternative reducer
+
+To enable different features of `json-immutability-helper`, you can
+customise it before passing it to `withReducer`. For example, to
+enable list commands such as `updateWhere` and mathematical commands
+such as Reverse Polish Notation (`rpn`):
+
+### Backend
+
+```js
+import { Broadcaster, InMemoryModel } from 'shared-reducer/backend';
+import listCommands from 'json-immutability-helper/commands/list';
+import mathCommands from 'json-immutability-helper/commands/math';
+import context from 'json-immutability-helper';
+
+const broadcaster = Broadcaster.for(new InMemoryModel())
+  .withReducer(context.with(listCommands, mathCommands))
+  .build();
+```
+
+If you want to use an entirely different reducer, create a wrapper
+and pass it to `withReducer`:
+
+```js
+import { Broadcaster, InMemoryModel } from 'shared-reducer/backend';
+
+```
+
+### Frontend
+
+```js
+import { SharedReducer } from 'shared-reducer/frontend';
+import listCommands from 'json-immutability-helper/commands/list';
+import mathCommands from 'json-immutability-helper/commands/math';
+import context from 'json-immutability-helper';
+
+const reducer = SharedReducer
+  .for('ws://destination', (state) => {})
+  .withReducer(context.with(listCommands, mathCommands))
+  .build();
+```
+
+If you want to use an entirely different reducer, create a wrapper
+and pass it to `withReducer`:
+
+```js
+import context from 'json-immutability-helper';
+
+const myReducer = {
+  update: (value, spec) => {
+    // return a new value which is the result of applying
+    // the given spec to the given value (or throw an error)
+  },
+  combine: (specs) => {
+    // return a new spec which is equivalent to applying
+    // all the given specs in order
+  },
+};
+
+// backend
+const broadcaster = Broadcaster.for(new InMemoryModel())
+  .withReducer(myReducer)
+  .build();
+
+// frontend
+const reducer = SharedReducer
+  .for('ws://destination', (state) => {})
+  .withReducer(myReducer)
+  .build();
+```
+
+Be careful when using your own reducer to avoid introducing
+security vulnerabilities; the functions will be called with
+untrusted input, so should be careful to avoid attacks such
+as code injection or prototype pollution.
+
+## Other customisations (Backend)
+
+The `Broadcaster` builder has other settable properties:
+
+- `withSubscribers`: specify a custom keyed broadcaster, used
+  for communicating changes to all consumers. Required interface:
+
+  ```js
+  {
+    add(key, listener) {
+      // add the listener function to key
+    },
+    remove(key, listener) {
+      // remove the listener function from key
+    },
+    broadcast(key, message) {
+      // call all current listener functions for key with
+      // the parameter message
+    },
+  }
+  ```
+
+  All functions can be asynchronous or synchronous.
+
+  The main use-case for overriding this would be to share
+  messages between multiple servers for load balancing, but
+  note that in most cases you probably want to load balance
+  _documents_ rather than _users_ for better scalability.
+
+- `withTaskQueues`: specify a custom task queue, used to ensure
+  operations happen in the correct order. Required interface:
+
+  ```js
+  {
+    push(key, task) {
+      // add the (possibly asynchronous) task to the queue
+      // for the given key
+    },
+  }
+  ```
+
+  The default implementation will execute the task if it is
+  the first task in a particular queue. If there is already
+  a task in the queue, it will be stored and executed once
+  the existing tasks have finished. Once all tasks for a
+  particular key have finished, it will remove the queue.
+
+  As with `withSubscribers`, the main reason to override
+  this is to provide consistency if multiple servers are
+  able to modify the same document simultaneously.
+
+- `withIdProvider`: specify a custom unique ID provider.
+  Required interface:
+
+  ```js
+  {
+    get() {
+      // return a unique string (must be synchronous)
+    },
+  }
+  ```
+
+  The returned ID is used internally and passed through
+  the configured `taskQueues` to identify the source of
+  a change. It is not revealed to users. The default
+  implementation uses a fixed random prefix followed by
+  an incrementing number, which should be sufficient for
+  most use cases.
+
+## Older versions
+
+For older versions of this library, see the separate
+[backend](https://github.com/davidje13/shared-reducer-backend) and
+[frontend](https://github.com/davidje13/shared-reducer-frontend) repositories.

package/backend/index.d.ts

@@ -0,0 +1,163 @@
+declare class UniqueIdProvider {
+    private readonly _shared;
+    private _unique;
+    get(): string;
+}
+
+type Task<T> = () => Promise<T>;
+interface TaskQueue<T> extends EventTarget {
+    push(task: Task<T>): Promise<T>;
+}
+type TaskQueueFactory<T> = () => TaskQueue<T>;
+
+declare class TaskQueueMap<T> {
+    private readonly _queueFactory;
+    private readonly _queues;
+    constructor(_queueFactory?: () => TaskQueue<T>);
+    push(key: string, task: Task<T>): Promise<T>;
+}
+
+type TopicListener<T> = (message: T) => void;
+interface Topic<T> {
+    add(fn: TopicListener<T>): Promise<void> | void;
+    remove(fn: TopicListener<T>): Promise<boolean> | boolean;
+    broadcast(message: T): Promise<void> | void;
+}
+
+interface TopicMap<T> {
+    add(key: string, fn: TopicListener<T>): Promise<void> | void;
+    remove(key: string, fn: TopicListener<T>): Promise<void> | void;
+    broadcast(key: string, message: T): Promise<void> | void;
+}
+
+declare class PermissionError extends Error {
+}
+interface Permission<T, SpecT> {
+    validateWriteSpec?(spec: SpecT): void;
+    validateWrite(newValue: T, oldValue: T): void;
+}
+
+interface Model<T> {
+    validate(v: unknown): Readonly<T>;
+    read(id: string): Promise<Readonly<T> | null | undefined> | Readonly<T> | null | undefined;
+    write(id: string, newValue: T, oldValue: T): Promise<void> | void;
+}
+
+interface Context<T, SpecT> {
+    update: (input: T, spec: SpecT) => T;
+}
+interface Subscription<T, SpecT, MetaT> {
+    getInitialData: () => Readonly<T>;
+    send: (change: SpecT, meta?: MetaT) => Promise<void>;
+    close: () => Promise<void>;
+}
+type Identifier = string | null;
+type ChangeInfo<SpecT> = {
+    change: SpecT;
+    error?: undefined;
+} | {
+    change?: undefined;
+    error: string;
+};
+interface TopicMessage<SpecT> {
+    message: ChangeInfo<SpecT>;
+    source: Identifier;
+    meta?: unknown;
+}
+interface BroadcasterBuilder<T, SpecT> {
+    withReducer<SpecT2 extends SpecT>(context: Context<T, SpecT2>): BroadcasterBuilder<T, SpecT2>;
+    withSubscribers(subscribers: TopicMap<TopicMessage<SpecT>>): this;
+    withTaskQueues(taskQueues: TaskQueueMap<void>): this;
+    withIdProvider(idProvider: UniqueIdProvider): this;
+    build(): Broadcaster<T, SpecT>;
+}
+declare class Broadcaster<T, SpecT> {
+    private readonly _model;
+    private readonly _context;
+    private readonly _subscribers;
+    private readonly _taskQueues;
+    private readonly _idProvider;
+    private constructor();
+    static for<T2>(model: Model<T2>): BroadcasterBuilder<T2, unknown>;
+    subscribe<MetaT>(id: string, onChange: (message: ChangeInfo<SpecT>, meta: MetaT | undefined) => void, permission?: Permission<T, SpecT>): Promise<Subscription<T, SpecT, MetaT> | null>;
+    update(id: string, change: SpecT, permission?: Permission<T, SpecT>): Promise<void>;
+    private _internalApplyChange;
+    private _internalQueueChange;
+}
+
+declare const PING = "P";
+declare const PONG = "p";
+type MaybePromise<T> = Promise<T> | T;
+interface ServerWebSocket {
+    on(event: 'close', listener: () => void): void;
+    on(event: 'message', listener: (data: unknown, isBinary?: boolean) => void): void;
+    send(message: string): void;
+}
+interface WSResponse {
+    accept(): Promise<ServerWebSocket>;
+    sendError(httpStatus: number): void;
+    beginTransaction(): void;
+    endTransaction(): void;
+}
+declare const websocketHandler: <T, SpecT>(broadcaster: Broadcaster<T, SpecT>) => <Req, Res extends WSResponse>(idGetter: (req: Req, res: Res) => MaybePromise<string>, permissionGetter: (req: Req, res: Res) => MaybePromise<Permission<T, SpecT>>) => (req: Req, res: Res) => Promise<void>;
+
+interface Collection<T> {
+    get<K extends keyof T & string>(searchAttribute: K, searchValue: T[K]): Promise<Readonly<T> | null>;
+    update<K extends keyof T & string>(searchAttribute: K, searchValue: T[K], update: Partial<T>): Promise<void>;
+}
+declare class CollectionStorageModel<T extends object> implements Model<T> {
+    private readonly _collection;
+    private readonly _idCol;
+    readonly validate: (v: unknown) => T;
+    private readonly _readErrorIntercept;
+    private readonly _writeErrorIntercept;
+    constructor(_collection: Collection<T>, _idCol: keyof T & string, validate: (v: unknown) => T, _readErrorIntercept?: (e: Error) => Error, _writeErrorIntercept?: (e: Error) => Error);
+    read(id: string): Promise<Readonly<T> | null>;
+    write(id: string, newValue: T, oldValue: T): Promise<void>;
+}
+
+declare class InMemoryModel<T> implements Model<T> {
+    readonly read: (id: string) => Readonly<T> | undefined;
+    readonly validate: (v: unknown) => T;
+    private readonly _memory;
+    constructor(validator?: (x: unknown) => T);
+    set(id: string, value: T): void;
+    get(id: string): Readonly<T> | undefined;
+    delete(id: string): void;
+    write(id: string, newValue: T, oldValue: T): void;
+}
+
+declare const ReadOnly: Permission<unknown, unknown>;
+
+declare const ReadWrite: Permission<unknown, unknown>;
+
+declare class ReadWriteStruct<T extends object> implements Permission<T, unknown> {
+    private readonly _readOnlyFields;
+    constructor(_readOnlyFields?: (keyof T)[]);
+    validateWrite(newValue: T, oldValue: T): void;
+}
+
+declare class AsyncTaskQueue<T> extends EventTarget implements TaskQueue<T> {
+    private readonly _queue;
+    private _running;
+    push(task: Task<T>): Promise<T>;
+    private _internalConsumeQueue;
+}
+
+declare class InMemoryTopic<T> implements Topic<T> {
+    private readonly _subscribers;
+    add(fn: TopicListener<T>): void;
+    remove(fn: TopicListener<T>): boolean;
+    broadcast(message: T): void;
+}
+
+declare class TrackingTopicMap<T> implements TopicMap<T> {
+    private readonly _topicFactory;
+    private readonly _data;
+    constructor(_topicFactory: (key: string) => Topic<T>);
+    add(key: string, fn: TopicListener<T>): Promise<void>;
+    remove(key: string, fn: TopicListener<T>): Promise<void>;
+    broadcast(key: string, message: T): Promise<void>;
+}
+
+export { AsyncTaskQueue, Broadcaster, type ChangeInfo, CollectionStorageModel, type Context, InMemoryModel, InMemoryTopic, type Model, PING, PONG, type Permission, PermissionError, ReadOnly, ReadWrite, ReadWriteStruct, type Subscription, type Task, type TaskQueue, type TaskQueueFactory, TaskQueueMap, type Topic, type TopicMap, type TopicMessage, TrackingTopicMap, UniqueIdProvider, websocketHandler };

package/backend/index.js

@@ -0,0 +1 @@
+"use strict";class t{t=crypto.randomUUID().substring(0,8);i=0;get(){const t=this.i;return this.i++,`${this.t}-${t}`}}class e extends EventTarget{o=[];h=!1;push(t){return new Promise(((e,s)=>{this.o.push({task:t,resolve:e,reject:s}),this.h||this.u()}))}async u(){for(this.h=!0;this.o.length>0;){const{task:t,resolve:e,reject:s}=this.o.shift();let r=null,i=!1;try{r=await t(),i=!0}catch(t){s(t)}i&&e(r)}this.h=!1,this.dispatchEvent(new CustomEvent("drain"))}}class s{l;p=new Map;constructor(t=()=>new e){this.l=t}push(t,e){let s=this.p.get(t);return s||(s=this.l(),s.addEventListener("drain",(()=>{this.p.delete(t)})),this.p.set(t,s)),s.push(e)}}class r{v;m=new Map;constructor(t){this.v=t}async add(t,e){let s=this.m.get(t);s||(s=this.v(t),this.m.set(t,s)),await s.add(e)}async remove(t,e){const s=this.m.get(t);if(s){await s.remove(e)||this.m.delete(t)}}async broadcast(t,e){const s=this.m.get(t);s&&await s.broadcast(e)}}class i{_=new Set;add(t){this._.add(t)}remove(t){return this._.delete(t),this._.size>0}broadcast(t){this._.forEach((e=>e(t)))}}const n={validateWrite(){}};class a{O;j;_;C;S;constructor(t,e,s,r,i){this.O=t,this.j=e,this._=s,this.C=r,this.S=i}static for(e){let n,o,c,h;return{withReducer(t){return n=t,this},withSubscribers(t){return o=t,this},withTaskQueues(t){return c=t,this},withIdProvider(t){return h=t,this},build(){if(!n)throw new Error("must set broadcaster context");return new a(e,n,o||new r((()=>new i)),c||new s,h||new t)}}}async subscribe(t,e,s=n){let r=await this.O.read(t);if(null==r)return null;const i=this.S.get(),a=({message:t,source:s,meta:r})=>{s===i?e(t,r):t.change&&e(t,void 0)};return this._.add(t,a),{getInitialData:()=>{if(null===r)throw new Error("Already fetched initialData");const t=r;return r=null,t},send:(e,r)=>this.I(t,e,s,i,r),close:async()=>{await this._.remove(t,a)}}}update(t,e,s=n){return this.I(t,e,s,null,void 0)}async P(t,e,s,r,i){try{const r=await this.O.read(t);if(!r)throw new Error("Deleted");s.validateWriteSpec?.(e);const i=this.j.update(r,e),n=this.O.validate(i);s.validateWrite(n,r),await this.O.write(t,n,r)}catch(e){return void this._.broadcast(t,{message:{error:e instanceof Error?e.message:"Internal error"},source:r,meta:i})}this._.broadcast(t,{message:{change:e},source:r,meta:i})}async I(t,e,s,r,i){return this.C.push(t,(()=>this.P(t,e,s,r,i)))}}function o(t){return"object"==typeof t&&null!==t&&!Array.isArray(t)}function c(t){return function(t){if(!o(t))throw new Error("Must specify change and optional id");const{id:e,change:s}=t;if(!o(s))throw new Error("change must be a dictionary");if(void 0===e)return{change:s};if("number"!=typeof e)throw new Error("if specified, id must be a number");return{change:s,id:e}}(JSON.parse(t))}const h=t=>t;class u extends Error{}const l="Cannot modify data",d={validateWriteSpec(){throw new u(l)},validateWrite(){throw new u(l)}};exports.AsyncTaskQueue=e,exports.Broadcaster=a,exports.CollectionStorageModel=class{$;k;validate;q;M;constructor(t,e,s,r=h,i=h){this.$=t,this.k=e,this.validate=s,this.q=r,this.M=i}async read(t){try{return await this.$.get(this.k,t)}catch(t){throw this.q(t)}}async write(t,e,s){const r={};Object.entries(e).forEach((([t,e])=>{const i=t;e!==(Object.prototype.hasOwnProperty.call(s,i)?s[i]:void 0)&&(r[i]?Object.defineProperty(r,i,{value:e,configurable:!0,enumerable:!0,writable:!0}):r[i]=e)}));try{await this.$.update(this.k,t,r)}catch(t){throw this.M(t)}}},exports.InMemoryModel=class{read=this.get;validate;W=new Map;constructor(t=t=>t){this.validate=t}set(t,e){this.W.set(t,e)}get(t){return this.W.get(t)}delete(t){this.W.delete(t)}write(t,e,s){if(s!==this.W.get(t))throw new Error("Unexpected previous value");this.W.set(t,e)}},exports.InMemoryTopic=i,exports.PING="P",exports.PONG="p",exports.PermissionError=u,exports.ReadOnly=d,exports.ReadWrite=n,exports.ReadWriteStruct=class{A;constructor(t=[]){this.A=t}validateWrite(t,e){Object.keys(e).forEach((e=>{const s=e;if(!Object.prototype.hasOwnProperty.call(t,s)&&this.A.includes(s))throw new u(`Cannot remove field ${s}`)})),Object.keys(t).forEach((s=>{const r=s;if(this.A.includes(r)){if(!Object.prototype.hasOwnProperty.call(e,r))throw new u(`Cannot add field ${r}`);if(t[r]!==e[r])throw new u(`Cannot edit field ${r}`)}}))}},exports.TaskQueueMap=s,exports.TrackingTopicMap=r,exports.UniqueIdProvider=t,exports.websocketHandler=t=>(e,s)=>async(r,i)=>{const n=await i.accept(),a=await e(r,i),o=await s(r,i),h=await t.subscribe(a,((t,e)=>{const s=void 0!==e?{id:e,...t}:t;n.send(JSON.stringify(s))}),o);h?(n.on("close",h.close),n.on("message",((t,e)=>{if(e)return;const s=String(t);if("P"===s)return void n.send("p");const r=c(s);i.beginTransaction(),h.send(r.change,r.id).finally((()=>i.endTransaction()))})),n.send(JSON.stringify({init:h.getInitialData()}))):i.sendError(404)};

package/backend/index.mjs

@@ -0,0 +1 @@
+class t{t=crypto.randomUUID().substring(0,8);i=0;get(){const t=this.i;return this.i++,`${this.t}-${t}`}}class e extends EventTarget{o=[];h=!1;push(t){return new Promise(((e,r)=>{this.o.push({task:t,resolve:e,reject:r}),this.h||this.u()}))}async u(){for(this.h=!0;this.o.length>0;){const{task:t,resolve:e,reject:r}=this.o.shift();let s=null,i=!1;try{s=await t(),i=!0}catch(t){r(t)}i&&e(s)}this.h=!1,this.dispatchEvent(new CustomEvent("drain"))}}class r{l;v=new Map;constructor(t=()=>new e){this.l=t}push(t,e){let r=this.v.get(t);return r||(r=this.l(),r.addEventListener("drain",(()=>{this.v.delete(t)})),this.v.set(t,r)),r.push(e)}}class s{m;p=new Map;constructor(t){this.m=t}async add(t,e){let r=this.p.get(t);r||(r=this.m(t),this.p.set(t,r)),await r.add(e)}async remove(t,e){const r=this.p.get(t);if(r){await r.remove(e)||this.p.delete(t)}}async broadcast(t,e){const r=this.p.get(t);r&&await r.broadcast(e)}}class i{_=new Set;add(t){this._.add(t)}remove(t){return this._.delete(t),this._.size>0}broadcast(t){this._.forEach((e=>e(t)))}}const n={validateWrite(){}};class a{O;j;_;C;S;constructor(t,e,r,s,i){this.O=t,this.j=e,this._=r,this.C=s,this.S=i}static for(e){let n,o,c,h;return{withReducer(t){return n=t,this},withSubscribers(t){return o=t,this},withTaskQueues(t){return c=t,this},withIdProvider(t){return h=t,this},build(){if(!n)throw new Error("must set broadcaster context");return new a(e,n,o||new s((()=>new i)),c||new r,h||new t)}}}async subscribe(t,e,r=n){let s=await this.O.read(t);if(null==s)return null;const i=this.S.get(),a=({message:t,source:r,meta:s})=>{r===i?e(t,s):t.change&&e(t,void 0)};return this._.add(t,a),{getInitialData:()=>{if(null===s)throw new Error("Already fetched initialData");const t=s;return s=null,t},send:(e,s)=>this.I(t,e,r,i,s),close:async()=>{await this._.remove(t,a)}}}update(t,e,r=n){return this.I(t,e,r,null,void 0)}async P(t,e,r,s,i){try{const s=await this.O.read(t);if(!s)throw new Error("Deleted");r.validateWriteSpec?.(e);const i=this.j.update(s,e),n=this.O.validate(i);r.validateWrite(n,s),await this.O.write(t,n,s)}catch(e){return void this._.broadcast(t,{message:{error:e instanceof Error?e.message:"Internal error"},source:s,meta:i})}this._.broadcast(t,{message:{change:e},source:s,meta:i})}async I(t,e,r,s,i){return this.C.push(t,(()=>this.P(t,e,r,s,i)))}}function o(t){return"object"==typeof t&&null!==t&&!Array.isArray(t)}function c(t){return function(t){if(!o(t))throw new Error("Must specify change and optional id");const{id:e,change:r}=t;if(!o(r))throw new Error("change must be a dictionary");if(void 0===e)return{change:r};if("number"!=typeof e)throw new Error("if specified, id must be a number");return{change:r,id:e}}(JSON.parse(t))}const h="P",u="p",l=t=>(e,r)=>async(s,i)=>{const n=await i.accept(),a=await e(s,i),o=await r(s,i),h=await t.subscribe(a,((t,e)=>{const r=void 0!==e?{id:e,...t}:t;n.send(JSON.stringify(r))}),o);h?(n.on("close",h.close),n.on("message",((t,e)=>{if(e)return;const r=String(t);if("P"===r)return void n.send("p");const s=c(r);i.beginTransaction(),h.send(s.change,s.id).finally((()=>i.endTransaction()))})),n.send(JSON.stringify({init:h.getInitialData()}))):i.sendError(404)},d=t=>t;class w{$;k;validate;q;M;constructor(t,e,r,s=d,i=d){this.$=t,this.k=e,this.validate=r,this.q=s,this.M=i}async read(t){try{return await this.$.get(this.k,t)}catch(t){throw this.q(t)}}async write(t,e,r){const s={};Object.entries(e).forEach((([t,e])=>{const i=t;e!==(Object.prototype.hasOwnProperty.call(r,i)?r[i]:void 0)&&(s[i]?Object.defineProperty(s,i,{value:e,configurable:!0,enumerable:!0,writable:!0}):s[i]=e)}));try{await this.$.update(this.k,t,s)}catch(t){throw this.M(t)}}}class f extends Error{}class y{read=this.get;validate;W=new Map;constructor(t=t=>t){this.validate=t}set(t,e){this.W.set(t,e)}get(t){return this.W.get(t)}delete(t){this.W.delete(t)}write(t,e,r){if(r!==this.W.get(t))throw new Error("Unexpected previous value");this.W.set(t,e)}}const b="Cannot modify data",v={validateWriteSpec(){throw new f(b)},validateWrite(){throw new f(b)}};class m{A;constructor(t=[]){this.A=t}validateWrite(t,e){Object.keys(e).forEach((e=>{const r=e;if(!Object.prototype.hasOwnProperty.call(t,r)&&this.A.includes(r))throw new f(`Cannot remove field ${r}`)})),Object.keys(t).forEach((r=>{const s=r;if(this.A.includes(s)){if(!Object.prototype.hasOwnProperty.call(e,s))throw new f(`Cannot add field ${s}`);if(t[s]!==e[s])throw new f(`Cannot edit field ${s}`)}}))}}export{e as AsyncTaskQueue,a as Broadcaster,w as CollectionStorageModel,y as InMemoryModel,i as InMemoryTopic,h as PING,u as PONG,f as PermissionError,v as ReadOnly,n as ReadWrite,m as ReadWriteStruct,r as TaskQueueMap,s as TrackingTopicMap,t as UniqueIdProvider,l as websocketHandler};

package/frontend/index.d.ts

@@ -0,0 +1,56 @@
+interface Context<T, SpecT> {
+    update: (input: T, spec: SpecT) => T;
+    combine: (specs: SpecT[]) => SpecT;
+}
+declare class SyncCallback<T> {
+    readonly sync: (state: T) => void;
+    readonly reject: (message: string) => void;
+    constructor(sync: (state: T) => void, reject: (message: string) => void);
+}
+type SpecGenerator<T, SpecT> = (state: T) => SpecSource<T, SpecT>[] | null | undefined;
+type SpecSource<T, SpecT> = SpecT | SpecGenerator<T, SpecT> | SyncCallback<T> | null | undefined;
+type DispatchSpec<T, SpecT> = SpecSource<T, SpecT>[];
+type Dispatch<T, SpecT> = (specs: DispatchSpec<T, SpecT> | null | undefined) => void;
+
+declare function actionsHandledCallback<T>(callback?: (state: T) => void): ((state: T) => null) | null;
+
+declare function actionsSyncedCallback<T>(resolve?: (state: T) => void, reject?: (message: string) => void): SyncCallback<T> | null;
+
+interface SharedReducerBuilder<T, SpecT> {
+    withReducer<SpecT2 extends SpecT>(context: Context<T, SpecT2>): SharedReducerBuilder<T, SpecT2>;
+    withToken(token: string): this;
+    withErrorHandler(handler: (error: string) => void): this;
+    withWarningHandler(handler: (error: string) => void): this;
+    build(): SharedReducer<T, SpecT>;
+}
+declare class SharedReducer<T, SpecT> {
+    private readonly _context;
+    private readonly _changeHandler;
+    private readonly _warningHandler;
+    private readonly _connection;
+    private _latestStates;
+    private _currentChange;
+    private _currentSyncCallbacks;
+    private _localChanges;
+    private _pendingChanges;
+    private readonly _dispatchLock;
+    private readonly _nextId;
+    private constructor();
+    static for<T2>(wsUrl: string, changeHandler?: (state: T2) => void): SharedReducerBuilder<T2, unknown>;
+    close(): void;
+    dispatch: Dispatch<T, SpecT>;
+    addSyncCallback(resolve: (state: T) => void, reject?: (message: string) => void): void;
+    syncedState(): Promise<T>;
+    getState(): T | undefined;
+    private _sendCurrentChange;
+    private _addCurrentChange;
+    private _applySpecs;
+    private _popLocalChange;
+    private _handleErrorMessage;
+    private _handleInitMessage;
+    private _handleChangeMessage;
+    private _handleMessage;
+    private _computeLocal;
+}
+
+export { type Context, type Dispatch, type DispatchSpec, SharedReducer, actionsHandledCallback, actionsSyncedCallback };

package/frontend/index.js

@@ -0,0 +1 @@
+"use strict";class t{sync;reject;constructor(t,s){this.sync=t,this.reject=s}}const s=()=>null;function i(i,e){return i||e?new t(i||s,e||s):null}class e{t;h;l;o=null;constructor(t,s=void 0,i,e=void 0){this.t=i,this.h=e,this.l=new WebSocket(t),this.l.addEventListener("message",this.u),this.l.addEventListener("error",this._),this.l.addEventListener("close",this.p),s&&this.l.addEventListener("open",(()=>this.l.send(s)),{once:!0}),this.C()}send(t){this.l.send(JSON.stringify(t))}close(){this.l.close(),null!==this.o&&clearTimeout(this.o)}C(){null!==this.o&&clearTimeout(this.o),this.o=setTimeout(this.v,2e4)}v=()=>{this.l.send("P")};u=({data:t})=>{this.C(),"p"!==t&&this.t(JSON.parse(t))};_=()=>{this.h?.("Failed to connect")};p=()=>{null!==this.o&&clearTimeout(this.o)}}class n{m;S;k;I;O=null;P;T=[];j=[];M=[];N=function(t){let s=!1;return i=>{if(s)throw new Error(t);try{return s=!0,i()}finally{s=!1}}}("Cannot dispatch recursively");H=function(){let t=1;return()=>t++}();constructor(t,s,i,n,h,r){this.m=t,this.S=n,this.k=r,this.I=new e(s,i,this.u,h)}static for(t,s){let i,e,h,r;return{withReducer(t){return i=t,this},withToken(t){return e=t,this},withErrorHandler(t){return h=t,this},withWarningHandler(t){return r=t,this},build(){if(!i)throw new Error("must set broadcaster context");return new n(i,t,e,s,h,r)}}}close(){this.I.close(),this.O=null,this.P=void 0,this.T=[],this.j=[],this.M=[]}dispatch=t=>{if(t&&t.length)if(this.O){const s=this.J(this.O,t);s!==this.O&&(this.O=s,this.S?.(s.local))}else this.M.push(...t)};addSyncCallback(t,s){this.dispatch([i(t,s)])}syncedState(){return new Promise(((t,s)=>{this.addSyncCallback(t,s)}))}getState(){return this.O?.local}$=()=>{if(void 0===this.P)return;const t=this.H(),s=this.P,i=this.T;this.P=void 0,this.T=[],this.j.push({change:s,id:t,syncCallbacks:i}),this.I.send({change:s,id:t})};A(t){void 0===this.P?(this.P=t,setTimeout(this.$,0)):this.P=this.m.combine([this.P,t])}J(s,i){if(!i.length)return s;const{state:e,delta:n}=this.N((()=>function(s,i,e,n){let h=i;const r=[],l=[];function o(){if(l.length>0){const t=s.combine(l);r.push(t),h=s.update(h,t),l.length=0}}return function(t,s){let i={vs:t,i:0,prev:null};for(;i;)if(i.i>=i.vs.length)i=i.prev;else{const t=s(i.vs[i.i]);i.i+=1,t&&t.length&&(i={vs:t,i:0,prev:i})}}(e,(s=>s instanceof t?(o(),n(s,h),null):"function"==typeof s?(o(),s(h)):(s&&l.push(s),null))),o(),{state:h,delta:s.combine(r)}}(this.m,s.local,i,((t,i)=>{i===s.local&&void 0===this.P?t.sync(s.local):this.T.push(t)}))));return e===s.local?s:(this.A(n),{server:s.server,local:e})}L(t){const s=void 0===t?-1:this.j.findIndex((s=>s.id===t));return-1===s?{localChange:null,index:s}:{localChange:this.j.splice(s,1)[0],index:s}}W(t){const{localChange:s}=this.L(t.id);s?(this.k?.(`API rejected update: ${t.error}`),this.O&&(this.O=this.q(this.O.server),this.S?.(this.O.local)),s.syncCallbacks.forEach((s=>s.reject(t.error)))):this.k?.(`API sent error: ${t.error}`)}F(t){this.O=this.J(this.q(t.init),this.M),this.M.length=0,this.S?.(this.O.local)}R(t){if(!this.O)return void this.k?.(`Ignoring change before init: ${JSON.stringify(t)}`);const{localChange:s,index:i}=this.L(t.id),e=this.m.update(this.O.server,t.change);0===i?this.O={server:e,local:this.O.local}:(this.O=this.q(e),this.S?.(this.O.local));const n=this.O.local;s?.syncCallbacks.forEach((t=>t.sync(n)))}u=t=>{Object.prototype.hasOwnProperty.call(t,"change")?this.R(t):Object.prototype.hasOwnProperty.call(t,"init")?this.F(t):Object.prototype.hasOwnProperty.call(t,"error")?this.W(t):this.k?.(`Ignoring unknown API message: ${JSON.stringify(t)}`)};q(t){let s=t;if(this.j.length>0){const t=this.m.combine(this.j.map((({change:t})=>t)));s=this.m.update(s,t)}return void 0!==this.P&&(s=this.m.update(s,this.P)),{server:t,local:s}}}exports.SharedReducer=n,exports.actionsHandledCallback=function(t){return t?s=>(t(s),null):null},exports.actionsSyncedCallback=i;

package/frontend/index.mjs

@@ -0,0 +1 @@
+function t(t){return t?s=>(t(s),null):null}class s{sync;reject;constructor(t,s){this.sync=t,this.reject=s}}const i=()=>null;function e(t,e){return t||e?new s(t||i,e||i):null}class n{t;h;l;o=null;constructor(t,s=void 0,i,e=void 0){this.t=i,this.h=e,this.l=new WebSocket(t),this.l.addEventListener("message",this.u),this.l.addEventListener("error",this._),this.l.addEventListener("close",this.C),s&&this.l.addEventListener("open",(()=>this.l.send(s)),{once:!0}),this.p()}send(t){this.l.send(JSON.stringify(t))}close(){this.l.close(),null!==this.o&&clearTimeout(this.o)}p(){null!==this.o&&clearTimeout(this.o),this.o=setTimeout(this.v,2e4)}v=()=>{this.l.send("P")};u=({data:t})=>{this.p(),"p"!==t&&this.t(JSON.parse(t))};_=()=>{this.h?.("Failed to connect")};C=()=>{null!==this.o&&clearTimeout(this.o)}}class h{m;S;k;I;O=null;P;T=[];j=[];M=[];N=function(t){let s=!1;return i=>{if(s)throw new Error(t);try{return s=!0,i()}finally{s=!1}}}("Cannot dispatch recursively");H=function(){let t=1;return()=>t++}();constructor(t,s,i,e,h,r){this.m=t,this.S=e,this.k=r,this.I=new n(s,i,this.u,h)}static for(t,s){let i,e,n,r;return{withReducer(t){return i=t,this},withToken(t){return e=t,this},withErrorHandler(t){return n=t,this},withWarningHandler(t){return r=t,this},build(){if(!i)throw new Error("must set broadcaster context");return new h(i,t,e,s,n,r)}}}close(){this.I.close(),this.O=null,this.P=void 0,this.T=[],this.j=[],this.M=[]}dispatch=t=>{if(t&&t.length)if(this.O){const s=this.J(this.O,t);s!==this.O&&(this.O=s,this.S?.(s.local))}else this.M.push(...t)};addSyncCallback(t,s){this.dispatch([e(t,s)])}syncedState(){return new Promise(((t,s)=>{this.addSyncCallback(t,s)}))}getState(){return this.O?.local}$=()=>{if(void 0===this.P)return;const t=this.H(),s=this.P,i=this.T;this.P=void 0,this.T=[],this.j.push({change:s,id:t,syncCallbacks:i}),this.I.send({change:s,id:t})};A(t){void 0===this.P?(this.P=t,setTimeout(this.$,0)):this.P=this.m.combine([this.P,t])}J(t,i){if(!i.length)return t;const{state:e,delta:n}=this.N((()=>function(t,i,e,n){let h=i;const r=[],l=[];function o(){if(l.length>0){const s=t.combine(l);r.push(s),h=t.update(h,s),l.length=0}}return function(t,s){let i={vs:t,i:0,prev:null};for(;i;)if(i.i>=i.vs.length)i=i.prev;else{const t=s(i.vs[i.i]);i.i+=1,t&&t.length&&(i={vs:t,i:0,prev:i})}}(e,(t=>t instanceof s?(o(),n(t,h),null):"function"==typeof t?(o(),t(h)):(t&&l.push(t),null))),o(),{state:h,delta:t.combine(r)}}(this.m,t.local,i,((s,i)=>{i===t.local&&void 0===this.P?s.sync(t.local):this.T.push(s)}))));return e===t.local?t:(this.A(n),{server:t.server,local:e})}L(t){const s=void 0===t?-1:this.j.findIndex((s=>s.id===t));return-1===s?{localChange:null,index:s}:{localChange:this.j.splice(s,1)[0],index:s}}W(t){const{localChange:s}=this.L(t.id);s?(this.k?.(`API rejected update: ${t.error}`),this.O&&(this.O=this.q(this.O.server),this.S?.(this.O.local)),s.syncCallbacks.forEach((s=>s.reject(t.error)))):this.k?.(`API sent error: ${t.error}`)}F(t){this.O=this.J(this.q(t.init),this.M),this.M.length=0,this.S?.(this.O.local)}R(t){if(!this.O)return void this.k?.(`Ignoring change before init: ${JSON.stringify(t)}`);const{localChange:s,index:i}=this.L(t.id),e=this.m.update(this.O.server,t.change);0===i?this.O={server:e,local:this.O.local}:(this.O=this.q(e),this.S?.(this.O.local));const n=this.O.local;s?.syncCallbacks.forEach((t=>t.sync(n)))}u=t=>{Object.prototype.hasOwnProperty.call(t,"change")?this.R(t):Object.prototype.hasOwnProperty.call(t,"init")?this.F(t):Object.prototype.hasOwnProperty.call(t,"error")?this.W(t):this.k?.(`Ignoring unknown API message: ${JSON.stringify(t)}`)};q(t){let s=t;if(this.j.length>0){const t=this.m.combine(this.j.map((({change:t})=>t)));s=this.m.update(s,t)}return void 0!==this.P&&(s=this.m.update(s,this.P)),{server:t,local:s}}}export{h as SharedReducer,t as actionsHandledCallback,e as actionsSyncedCallback};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "shared-reducer",
+  "version": "4.0.0",
+  "description": "shared state management",
+  "author": "David Evans",
+  "license": "MIT",
+  "keywords": [
+    "reducer",
+    "websocket"
+  ],
+  "exports": {
+    "./backend": {
+      "import": {
+        "default": "./backend/index.mjs",
+        "types": "./backend/index.d.ts"
+      },
+      "require": {
+        "default": "./backend/index.js",
+        "types": "./backend/index.d.ts"
+      }
+    },
+    "./frontend": {
+      "import": {
+        "default": "./frontend/index.mjs",
+        "types": "./frontend/index.d.ts"
+      },
+      "require": {
+        "default": "./frontend/index.js",
+        "types": "./frontend/index.d.ts"
+      }
+    }
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "test": "lean-test --preprocess=tsc --parallel-suites && package/build.sh && package/run.sh && tsc && prettier --check .",
+    "dopublish": "package/build.sh && npm publish package.tgz"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidje13/shared-reducer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davidje13/shared-reducer/issues"
+  },
+  "homepage": "https://github.com/davidje13/shared-reducer#readme",
+  "devDependencies": {
+    "@rollup/plugin-terser": "0.4.x",
+    "@rollup/plugin-typescript": "11.x",
+    "collection-storage": "3.x",
+    "json-immutability-helper": "3.x",
+    "lean-test": "2.x",
+    "prettier": "3.3.3",
+    "rollup": "4.x",
+    "rollup-plugin-dts": "6.x",
+    "superwstest": "2.x",
+    "tslib": "2.7.x",
+    "typescript": "5.5.x",
+    "websocket-express": "3.x"
+  }
+}