@piemekanika/x-machina 0.0.1 → 0.0.2

package/README.md

@@ -47,28 +47,39 @@ const order = new XMachina<OrderContext, OrderState>({
     pending: {
       transitions: {
         pay: (ctx, paymentId) => {
+          // Business logic: charge customer, send receipt, etc.
           ctx.trackingNumber = `PAY-${paymentId}`
           return 'paid'
         },
-        cancel: () => 'cancelled',
+        cancel: () => {
+          // Business logic: refund if applicable, notify customer, etc.
+          return 'cancelled'
+        },
       },
     },
     paid: {
       transitions: {
         ship: (ctx, tracking) => {
+          // Business logic: notify shipping carrier, update inventory, etc.
           ctx.trackingNumber = tracking
           return 'shipped'
         },
-        cancel: () => 'cancelled',
+        cancel: () => {
+          // Business logic: process refund, restock items, etc.
+          return 'cancelled'
+        },
       },
     },
     shipped: {
       transitions: {
-        deliver: () => 'delivered',
+        deliver: () => {
+          // Business logic: confirm delivery, update records, etc.
+          return 'delivered'
+        },
       },
     },
-    delivered: { transitions: {} },
-    cancelled: { transitions: {} },
+    delivered: null,
+    cancelled: null,
   },
 })
 
@@ -92,6 +103,47 @@ console.log(order.getJsonDump())
 // {"state":"delivered","context":{"orderId":"ORD-12345",...}}
 ```
 
+## API
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | `S` | Current state |
+| `context` | `Readonly<C>` | Readonly view of the context |
+| `isFinal` | `boolean` | Whether the machine is in a final state |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `transition(event, data?)` | Trigger a transition by event name |
+| `updateContext(patch)` | Merge a partial patch into the context |
+| `getJsonDump()` | Serialize state and context as JSON |
+
+### Final States
+
+A state set to `null` is a final state. Once reached:
+
+- `isFinal` returns `true`
+- `transition()` throws an error
+- `updateContext()` throws an error
+
+```typescript
+delivered: null,    // final state
+cancelled: null,   // final state
+```
+
+### Updating Context
+
+Use `updateContext()` to merge patches into context without direct mutation:
+
+```typescript
+await order.transition('pay', 'txn_abc123')
+order.updateContext({ lastUpdated: new Date() })
+console.log(order.context.lastUpdated) // Date object
+```
+
 ## Development
 
 ```bash

package/dist/XMachina.d.ts

@@ -0,0 +1,21 @@
+import { MachinaContext, MachinaStates } from './types';
+export type XMachinaParams<C extends MachinaContext, S extends string> = {
+    initialState: S;
+    initialContext: C;
+    states: MachinaStates<C, S>;
+};
+export declare class XMachina<C extends MachinaContext, S extends string> {
+    private _state;
+    private _context;
+    private states;
+    constructor(params: XMachinaParams<C, S>);
+    get state(): S;
+    get context(): Readonly<C>;
+    get isFinal(): boolean;
+    private getHandlerByEventName;
+    transition(event: string, data?: any): Promise<void>;
+    private goTo;
+    updateContext(patch: Partial<C>): void;
+    getJsonDump(): string;
+}
+//# sourceMappingURL=XMachina.d.ts.map

package/dist/XMachina.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XMachina.d.ts","sourceRoot":"","sources":["../src/XMachina.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAA;AAErE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,MAAM,IAAI;IACxE,YAAY,EAAE,CAAC,CAAA;IACf,cAAc,EAAE,CAAC,CAAA;IACjB,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CAC3B,CAAA;AAED,qBAAa,QAAQ,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,MAAM;IAC/D,OAAO,CAAC,MAAM,CAAG;IACjB,OAAO,CAAC,QAAQ,CAAG;IACnB,OAAO,CAAC,MAAM,CAAqB;IAEnC,YAAY,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAMvC;IAED,IAAI,KAAK,IAAI,CAAC,CAEb;IAED,IAAI,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,CAEzB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,CAAC,qBAAqB;IAoBvB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAazD;YAEa,IAAI;IAQlB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAQrC;IAED,WAAW,IAAI,MAAM,CAKpB;CACD"}

package/dist/XMachina.js

@@ -0,0 +1,64 @@
+import { deepMerge } from './helpers/deepMerge';
+import { toPromise } from './helpers/toPromise';
+import { makeReadonlyObject } from './helpers/makeReadonlyObject';
+import { dummyClone } from './helpers/dummyClone';
+export class XMachina {
+    _state;
+    _context;
+    states;
+    constructor(params) {
+        this._state = params.initialState;
+        this._context = dummyClone(params.initialContext);
+        this.states = params.states;
+        return this;
+    }
+    get state() {
+        return this._state;
+    }
+    get context() {
+        return makeReadonlyObject(this._context);
+    }
+    get isFinal() {
+        return this.states[this._state] === null;
+    }
+    getHandlerByEventName(event) {
+        const stateDefinition = this.states[this.state];
+        if (!stateDefinition) {
+            throw new Error(`No transition handler for event '${event}' in state '${this.state}'`);
+        }
+        const transitions = stateDefinition.transitions;
+        const handler = transitions?.[event];
+        if (!handler) {
+            throw new Error(`No transition handler for event '${event}' in state '${this.state}'`);
+        }
+        return handler;
+    }
+    async transition(event, data) {
+        if (this.isFinal) {
+            throw new Error(`Cannot transition from final state '${this._state}'`);
+        }
+        const handler = this.getHandlerByEventName(event);
+        const newState = await toPromise(() => handler(this._context, data))();
+        if (newState) {
+            await this.goTo(newState);
+        }
+    }
+    async goTo(newState) {
+        if (!(newState in this.states)) {
+            throw new Error(`State '${newState}' is not defined`);
+        }
+        this._state = newState;
+    }
+    updateContext(patch) {
+        if (this.isFinal) {
+            throw new Error(`Cannot update context in final state '${this._state}'`);
+        }
+        this._context = deepMerge(this._context, patch);
+    }
+    getJsonDump() {
+        return JSON.stringify({
+            state: this.state,
+            context: this.context,
+        });
+    }
+}

package/dist/__tests__/XMachina.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=XMachina.test.d.ts.map

package/dist/__tests__/XMachina.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XMachina.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/XMachina.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/XMachina.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { XMachina } from '../XMachina';
+describe('XMachina', () => {
+    let machine;
+    beforeEach(() => {
+        machine = new XMachina('idle', { count: 0 }, {
+            idle: {
+                transitions: {
+                    start: (ctx) => {
+                        ctx.count = 1;
+                        return 'active';
+                    },
+                },
+            },
+            active: {
+                transitions: {
+                    finish: () => 'finished',
+                    increment: (ctx) => {
+                        ctx.count += 1;
+                        return null;
+                    },
+                    setUser: (ctx, data) => {
+                        ctx.user = data;
+                        return null;
+                    },
+                },
+            },
+            finished: {
+                transitions: {},
+            },
+        });
+    });
+    describe('constructor', () => {
+        it('sets initial state', () => {
+            expect(machine.state).toBe('idle');
+        });
+        it('sets initial context', () => {
+            expect(machine.context).toEqual({ count: 0 });
+        });
+        it('does not mutate original context object', () => {
+            const originalContext = { count: 0 };
+            const m = new XMachina('idle', originalContext, { idle: {} });
+            m.updateContext({ count: 5 });
+            expect(originalContext).toEqual({ count: 0 });
+        });
+    });
+    describe('state getter', () => {
+        it('returns current state', () => {
+            expect(machine.state).toBe('idle');
+        });
+    });
+    describe('context getter', () => {
+        it('returns readonly context', () => {
+            const context = machine.context;
+            expect(context).toEqual({ count: 0 });
+        });
+        it('returns a frozen copy of the context', () => {
+            const context = machine.context;
+            expect(() => (context.count = 999)).toThrow();
+            expect(machine.context).toEqual({ count: 0 });
+        });
+    });
+    describe('transition', () => {
+        it('changes state when transition handler returns new state', async () => {
+            await machine.transition('start');
+            expect(machine.state).toBe('active');
+        });
+        it('updates context when handler modifies it', async () => {
+            await machine.transition('start');
+            expect(machine.context.count).toBe(1);
+        });
+        it('stays in same state when handler returns null', async () => {
+            await machine.transition('start');
+            await machine.transition('increment');
+            expect(machine.state).toBe('active');
+            expect(machine.context.count).toBe(2);
+        });
+        it('can pass data to transition handler', async () => {
+            await machine.transition('start');
+            await machine.transition('setUser', { name: 'Alice' });
+            expect(machine.context.user).toEqual({ name: 'Alice' });
+        });
+        it('throws when no transition handler for event in current state', async () => {
+            await expect(machine.transition('finish')).rejects.toThrow("No transition handler for event 'finish' in state 'idle'");
+        });
+        it('throws when transition returns undefined state', async () => {
+            const machineWithBadTransition = new XMachina('idle', { count: 0 }, {
+                idle: {
+                    transitions: {
+                        goToUnknown: () => 'unknown',
+                    },
+                },
+                active: { transitions: {} },
+                finished: { transitions: {} },
+            });
+            await expect(machineWithBadTransition.transition('goToUnknown')).rejects.toThrow("State 'unknown' is not defined");
+        });
+    });
+    describe('updateContext', () => {
+        it('merges partial updates into context', () => {
+            machine.updateContext({ count: 10 });
+            expect(machine.context).toEqual({ count: 10 });
+        });
+        it('deep merges nested objects', () => {
+            machine.updateContext({ user: { name: 'Bob' } });
+            expect(machine.context).toEqual({ count: 0, user: { name: 'Bob' } });
+        });
+        it('preserves existing properties not being updated', () => {
+            machine.updateContext({ count: 5 });
+            expect(machine.context.count).toBe(5);
+            expect(machine.context.count).toBeDefined();
+        });
+    });
+});

package/dist/helpers/__tests__/deepMerge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deepMerge.test.d.ts.map

package/dist/helpers/__tests__/deepMerge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepMerge.test.d.ts","sourceRoot":"","sources":["../../../src/helpers/__tests__/deepMerge.test.ts"],"names":[],"mappings":""}

package/dist/helpers/__tests__/deepMerge.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { deepMerge } from '../deepMerge';
+describe('deepMerge', () => {
+    it('merges two flat objects', () => {
+        const target = { a: 1, b: 2 };
+        const source = { b: 3, c: 4 };
+        expect(deepMerge(target, source)).toEqual({ a: 1, b: 3, c: 4 });
+    });
+    it('does not mutate original objects', () => {
+        const target = { a: 1 };
+        const source = { b: 2 };
+        deepMerge(target, source);
+        expect(target).toEqual({ a: 1 });
+        expect(source).toEqual({ b: 2 });
+    });
+    it('deeply merges nested objects', () => {
+        const target = { a: { b: 1, c: 2 } };
+        const source = { a: { b: 3, d: 4 } };
+        expect(deepMerge(target, source)).toEqual({ a: { b: 3, c: 2, d: 4 } });
+    });
+    it('adds new nested objects from source', () => {
+        const target = { a: 1 };
+        const source = { b: { nested: true } };
+        expect(deepMerge(target, source)).toEqual({ a: 1, b: { nested: true } });
+    });
+    it('overwrites primitives with source values', () => {
+        const target = { a: 1, b: 'old' };
+        const source = { b: 'new', c: true };
+        expect(deepMerge(target, source)).toEqual({ a: 1, b: 'new', c: true });
+    });
+    it('handles empty objects', () => {
+        expect(deepMerge({}, {})).toEqual({});
+        expect(deepMerge({ a: 1 }, {})).toEqual({ a: 1 });
+        expect(deepMerge({}, { b: 2 })).toEqual({ b: 2 });
+    });
+    it('handles arrays - source replaces target array', () => {
+        const target = { arr: [1, 2, 3] };
+        const source = { arr: [4, 5] };
+        expect(deepMerge(target, source)).toEqual({ arr: [4, 5] });
+    });
+    it('handles null values in source', () => {
+        const target = { a: 1 };
+        const source = { a: null };
+        expect(deepMerge(target, source)).toEqual({ a: null });
+    });
+    it('handles undefined values in source', () => {
+        const target = { a: 1 };
+        const source = { a: undefined };
+        expect(deepMerge(target, source)).toEqual({ a: undefined });
+    });
+});

package/dist/helpers/__tests__/isObject.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=isObject.test.d.ts.map

package/dist/helpers/__tests__/isObject.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isObject.test.d.ts","sourceRoot":"","sources":["../../../src/helpers/__tests__/isObject.test.ts"],"names":[],"mappings":""}

package/dist/helpers/__tests__/isObject.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { isObject } from '../isObject';
+describe('isObject', () => {
+    it('returns true for plain objects', () => {
+        expect(isObject({})).toBe(true);
+        expect(isObject({ a: 1 })).toBe(true);
+        expect(isObject({ nested: { deep: true } })).toBe(true);
+    });
+    it('returns false for arrays', () => {
+        expect(isObject([])).toBe(false);
+        expect(isObject([1, 2, 3])).toBe(false);
+        expect(isObject([{}, {}])).toBe(false);
+    });
+    it('returns false for null', () => {
+        expect(isObject(null)).toBe(false);
+    });
+    it('returns false for primitives', () => {
+        expect(isObject('string')).toBe(false);
+        expect(isObject(123)).toBe(false);
+        expect(isObject(true)).toBe(false);
+        expect(isObject(undefined)).toBe(false);
+        expect(isObject(Symbol('test'))).toBe(false);
+    });
+    it('returns false for functions', () => {
+        expect(isObject(() => { })).toBe(false);
+        expect(isObject(function () { })).toBe(false);
+    });
+});

package/dist/helpers/__tests__/jsonSafe.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=jsonSafe.test.d.ts.map

package/dist/helpers/__tests__/jsonSafe.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonSafe.test.d.ts","sourceRoot":"","sources":["../../../src/helpers/__tests__/jsonSafe.test.ts"],"names":[],"mappings":""}

package/dist/helpers/__tests__/jsonSafe.test.js

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import { isJsonSafe, assertJsonSafe, toJson, fromJson } from '../jsonSafe';
+describe('isJsonSafe', () => {
+    it('returns true for primitives', () => {
+        expect(isJsonSafe(null)).toBe(true);
+        expect(isJsonSafe(true)).toBe(true);
+        expect(isJsonSafe(false)).toBe(true);
+        expect(isJsonSafe(0)).toBe(true);
+        expect(isJsonSafe(42)).toBe(true);
+        expect(isJsonSafe(-3.14)).toBe(true);
+        expect(isJsonSafe('')).toBe(true);
+        expect(isJsonSafe('hello')).toBe(true);
+        expect(isJsonSafe('hello world')).toBe(true);
+    });
+    it('returns true for plain objects', () => {
+        expect(isJsonSafe({})).toBe(true);
+        expect(isJsonSafe({ a: 1 })).toBe(true);
+        expect(isJsonSafe({ nested: { deep: true } })).toBe(true);
+        expect(isJsonSafe({ arr: [1, 2, 3] })).toBe(true);
+    });
+    it('returns true for arrays', () => {
+        expect(isJsonSafe([])).toBe(true);
+        expect(isJsonSafe([1, 2, 3])).toBe(true);
+        expect(isJsonSafe([{}, [], 'string'])).toBe(true);
+        expect(isJsonSafe([[1, 2], [3, 4]])).toBe(true);
+    });
+    it('returns true for Date', () => {
+        expect(isJsonSafe(new Date())).toBe(true);
+    });
+    it('returns true for RegExp', () => {
+        expect(isJsonSafe(/test/)).toBe(true);
+        expect(isJsonSafe(new RegExp('pattern'))).toBe(true);
+    });
+    it('returns false for functions', () => {
+        expect(isJsonSafe(() => { })).toBe(false);
+        expect(isJsonSafe(function () { })).toBe(false);
+        expect(isJsonSafe(Math.random)).toBe(false);
+    });
+    it('returns false for undefined', () => {
+        expect(isJsonSafe(undefined)).toBe(false);
+    });
+    it('returns false for symbols', () => {
+        expect(isJsonSafe(Symbol('test'))).toBe(false);
+    });
+    it('returns false for bigint', () => {
+        expect(isJsonSafe(BigInt(123))).toBe(false);
+    });
+    it('returns false for Map', () => {
+        expect(isJsonSafe(new Map())).toBe(false);
+        expect(isJsonSafe(new Map([['a', 1]]))).toBe(false);
+    });
+    it('returns false for Set', () => {
+        expect(isJsonSafe(new Set())).toBe(false);
+        expect(isJsonSafe(new Set([1, 2, 3]))).toBe(false);
+    });
+    it('returns false for Error', () => {
+        expect(isJsonSafe(new Error())).toBe(false);
+        expect(isJsonSafe(new TypeError('msg'))).toBe(false);
+    });
+    it('returns false for objects with unsafe values', () => {
+        expect(isJsonSafe({ fn: () => { } })).toBe(false);
+        expect(isJsonSafe({ u: undefined })).toBe(false);
+        expect(isJsonSafe([() => { }])).toBe(false);
+    });
+    it('returns true for deeply nested safe objects', () => {
+        expect(isJsonSafe({ a: { b: { c: { d: { e: 1 } } } } })).toBe(true);
+        expect(isJsonSafe({ arr: [{ nested: { arr: [1, 2, { deep: true }] } }] })).toBe(true);
+    });
+});
+describe('assertJsonSafe', () => {
+    it('does not throw for safe values', () => {
+        expect(() => assertJsonSafe(null)).not.toThrow();
+        expect(() => assertJsonSafe({})).not.toThrow();
+        expect(() => assertJsonSafe({ a: 1 })).not.toThrow();
+        expect(() => assertJsonSafe([1, 2, 3])).not.toThrow();
+        expect(() => assertJsonSafe(new Date())).not.toThrow();
+        expect(() => assertJsonSafe({ nested: { deep: true } })).not.toThrow();
+    });
+    it('throws with path for function at root', () => {
+        expect(() => assertJsonSafe((() => { }))).toThrow('Function at root is not JSON-safe');
+    });
+    it('throws with path for function in object', () => {
+        expect(() => assertJsonSafe({ fn: (() => { }) })).toThrow('Function at fn is not JSON-safe');
+    });
+    it('throws with path for undefined at root', () => {
+        expect(() => assertJsonSafe(undefined)).toThrow('Undefined at root is not JSON-safe');
+    });
+    it('throws with path for undefined in array', () => {
+        expect(() => assertJsonSafe([1, undefined, 3])).toThrow('Undefined at [1] is not JSON-safe');
+    });
+    it('throws with path for Map', () => {
+        expect(() => assertJsonSafe(new Map())).toThrow('Map at  is not JSON-safe');
+    });
+    it('throws with path for Set', () => {
+        expect(() => assertJsonSafe(new Set())).toThrow('Set at  is not JSON-safe');
+    });
+    it('throws with path for Error', () => {
+        expect(() => assertJsonSafe(new Error())).toThrow('Error at  is not JSON-safe');
+    });
+    it('includes nested paths', () => {
+        expect(() => assertJsonSafe({ a: { b: { c: { d: { e: undefined } } } } }))
+            .toThrow('a.b.c.d.e');
+    });
+});
+describe('toJson', () => {
+    it('serializes safe values to JSON string', () => {
+        expect(toJson(null)).toBe('null');
+        expect(toJson(true)).toBe('true');
+        expect(toJson(42)).toBe('42');
+        expect(toJson('hello')).toBe('"hello"');
+        expect(toJson({ a: 1 })).toBe('{"a":1}');
+        expect(toJson([1, 2, 3])).toBe('[1,2,3]');
+    });
+    it('serializes nested objects', () => {
+        const obj = { a: { b: { c: 1 } }, arr: [1, 2, { nested: true }] };
+        expect(toJson(obj)).toBe('{"a":{"b":{"c":1}},"arr":[1,2,{"nested":true}]}');
+    });
+});
+describe('fromJson', () => {
+    it('parses JSON string to object', () => {
+        expect(fromJson('null')).toBe(null);
+        expect(fromJson('true')).toBe(true);
+        expect(fromJson('42')).toBe(42);
+        expect(fromJson('"hello"')).toBe('hello');
+        expect(fromJson('{"a":1}')).toEqual({ a: 1 });
+        expect(fromJson('[1,2,3]')).toEqual([1, 2, 3]);
+    });
+    it('parses nested objects', () => {
+        const json = '{"a":{"b":{"c":1}},"arr":[1,2,{"nested":true}]}';
+        expect(fromJson(json)).toEqual({ a: { b: { c: 1 } }, arr: [1, 2, { nested: true }] });
+    });
+    it('round-trips safely through toJson and fromJson', () => {
+        const original = { a: 1, b: { c: 2 }, arr: [1, 2, 3], nested: { deep: { value: 'test' } } };
+        const json = toJson(original);
+        const restored = fromJson(json);
+        expect(restored).toEqual(original);
+    });
+});

package/dist/helpers/__tests__/makeReadonlyObject.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=makeReadonlyObject.test.d.ts.map

package/dist/helpers/__tests__/makeReadonlyObject.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makeReadonlyObject.test.d.ts","sourceRoot":"","sources":["../../../src/helpers/__tests__/makeReadonlyObject.test.ts"],"names":[],"mappings":""}