@piemekanika/x-machina 0.0.1

package/AGENTS.md

@@ -0,0 +1,50 @@
+# x-machina Rules
+
+## Package Manager
+
+Always use `bun` for package management. Do NOT use `npm`, `yarn`, or `pnpm`.
+
+## Type Checking
+
+Use `bun run check` for type checking. Do NOT use `npx tsc` or `npm run check`.
+
+## Testing
+
+Use `bun run test` for running tests. Do NOT use `npm test` or `yarn test`.
+
+Use the AAA (Arrange, Act, Assert) pattern. Keep a blank line between each section.
+
+Example:
+
+```
+test('adds two numbers', () => {
+
+  const a = 1;
+  const b = 2;
+
+  const result = add(a, b);
+
+  expect(result).toBe(3);
+});
+```
+
+## JSDoc
+
+Write JSDoc comments for functions and classes.
+
+Omit types in JSDoc since TypeScript already provides type information.
+
+Use blank lines to separate description, params, and returns.
+
+Example:
+
+```
+/**
+ * Adds two numbers together.
+ *
+ * @param a - The first number.
+ * @param b - The second number.
+ *
+ * @returns The sum of the two numbers.
+ */
+```

package/README.md

@@ -0,0 +1,108 @@
+# x-machina
+
+A lightweight TypeScript state machine with typed context and transition handlers.
+
+## Installation
+
+```bash
+bun install
+```
+
+## How It Works
+
+XMachina manages state through a configuration of states, each with transition handlers.
+
+- **initialState** - The starting state
+- **initialContext** - Arbitrary data object attached to the machine
+- **states** - Map of state names to transition handlers
+
+Transition handlers receive `(context, eventData?)` and return a new state name or `null` to stay in the current state. Handlers can mutate context directly.
+
+## Usage
+
+### Order Processing
+
+```typescript
+type OrderContext = {
+  orderId: string
+  items: { name: string; quantity: number; price: number }[]
+  totalAmount: number
+  customerEmail: string
+  trackingNumber?: string
+}
+
+type OrderState = 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled'
+
+const order = new XMachina<OrderContext, OrderState>({
+  initialState: 'pending',
+  initialContext: {
+    orderId: 'ORD-12345',
+    items: [
+      { name: 'Widget', quantity: 2, price: 9.99 },
+    ],
+    totalAmount: 19.98,
+    customerEmail: 'alice@example.com',
+  },
+  states: {
+    pending: {
+      transitions: {
+        pay: (ctx, paymentId) => {
+          ctx.trackingNumber = `PAY-${paymentId}`
+          return 'paid'
+        },
+        cancel: () => 'cancelled',
+      },
+    },
+    paid: {
+      transitions: {
+        ship: (ctx, tracking) => {
+          ctx.trackingNumber = tracking
+          return 'shipped'
+        },
+        cancel: () => 'cancelled',
+      },
+    },
+    shipped: {
+      transitions: {
+        deliver: () => 'delivered',
+      },
+    },
+    delivered: { transitions: {} },
+    cancelled: { transitions: {} },
+  },
+})
+
+await order.transition('pay', 'txn_abc123')
+console.log(order.state)           // 'paid'
+console.log(order.context.trackingNumber) // 'PAY-txn_abc123'
+
+await order.transition('ship', '1Z999AA10123456784')
+console.log(order.state)           // 'shipped'
+
+await order.transition('deliver')
+console.log(order.state)            // 'delivered'
+```
+
+### Dumping State
+
+Use `getJsonDump()` to serialize the current state and context as JSON. Useful for logging and debugging.
+
+```typescript
+console.log(order.getJsonDump())
+// {"state":"delivered","context":{"orderId":"ORD-12345",...}}
+```
+
+## Development
+
+```bash
+bun install         # Install dependencies
+bun test            # Run tests once
+bun test:watch      # Watch mode for tests
+bun run build       # Build to dist/
+bun run build:watch # Watch mode for build
+bun dev             # Dev mode (test watch)
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@piemekanika/x-machina",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "author": "Dmitrii Beliakov",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "check": "tsgo --noEmit",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch",
+    "build": "tsgo && bun build src/index.ts --outdir dist --format esm --target node",
+    "build:watch": "bun --watch run build",
+    "dev": "bun --watch run test"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "^7.0.0-dev.20260320.1",
+    "vitest": "4.1.0"
+  }
+}

package/src/XMachina.ts

@@ -0,0 +1,97 @@
+import { deepMerge } from './helpers/deepMerge'
+import { toPromise } from './helpers/toPromise'
+import { makeReadonlyObject } from './helpers/makeReadonlyObject'
+import { dummyClone } from './helpers/dummyClone'
+import { MachinaContext, MachinaStates, TransitionFn } from './types'
+
+export type XMachinaParams<C extends MachinaContext, S extends string> = {
+	initialState: S
+	initialContext: C
+	states: MachinaStates<C, S>
+}
+
+export class XMachina<C extends MachinaContext, S extends string> {
+	private _state: S
+	private _context: C
+	private states: MachinaStates<C, S>
+
+	constructor(params: XMachinaParams<C, S>) {
+		this._state = params.initialState
+		this._context = dummyClone(params.initialContext)
+		this.states = params.states
+
+		return this
+	}
+
+	get state(): S {
+		return this._state
+	}
+
+	get context(): Readonly<C> {
+		return makeReadonlyObject(this._context)
+	}
+
+	get isFinal(): boolean {
+		return this.states[this._state] === null
+	}
+
+	private getHandlerByEventName(event: string) {
+		if (this.isFinal) {
+			throw new Error(
+				`Cannot transition from final state '${this._state}'`,
+			)
+		}
+		const stateDefinition = this.states[this.state]
+		if (!stateDefinition) {
+			throw new Error(
+				`No transition handler for event '${event}' in state '${this.state}'`,
+			)
+		}
+		const transitions: Record<string, TransitionFn<C, S>> | undefined =
+			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: string, data?: any): Promise<void> {
+		const handler = this.getHandlerByEventName(event)
+
+		const newState = await toPromise(() => handler(this._context, data))()
+
+		if (newState) {
+			await this.goTo(newState)
+		}
+	}
+
+	private async goTo(newState: S): Promise<void> {
+		if (!(newState in this.states)) {
+			throw new Error(`State '${newState}' is not defined`)
+		}
+
+		this._state = newState
+	}
+
+	updateContext(patch: Partial<C>): void {
+		if (this.isFinal) {
+			throw new Error(
+				`Cannot update context in final state '${this._state}'`,
+			)
+		}
+
+		this._context = deepMerge(this._context, patch) as C
+	}
+
+	getJsonDump(): string {
+		return JSON.stringify({
+			state: this.state,
+			context: this.context,
+		})
+	}
+}

package/src/__tests__/XMachina.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { XMachina } from '../XMachina'
+
+type TestContext = { count: number; user?: { name: string } }
+type TestState = 'idle' | 'active' | 'finished'
+
+describe('XMachina', () => {
+	let machine: XMachina<TestContext, TestState>
+
+	beforeEach(() => {
+		machine = new XMachina<TestContext, TestState>({
+			initialState: 'idle',
+			initialContext: { count: 0 },
+			states: {
+				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({ initialState: 'idle', initialContext: originalContext, states: { idle: {} } })
+			m.updateContext({ count: 5 })
+			expect(originalContext).toEqual({ count: 0 })
+		})
+
+		it('returns this from constructor', () => {
+			const m = new XMachina({ initialState: 'idle', initialContext: { count: 0 }, states: { idle: {} } })
+			expect(m).toBe(m)
+		})
+
+		it('can chain methods after construction', () => {
+			const m = new XMachina({ initialState: 'idle', initialContext: { count: 0 }, states: { idle: {} } })
+			const result = m.updateContext({ count: 5 })
+			expect(result).toBeUndefined()
+			expect(m.context.count).toBe(5)
+		})
+	})
+
+	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 as { count: number }
+			expect(() => ((context as any).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<TestContext, TestState>({
+				initialState: 'idle',
+				initialContext: { count: 0 },
+				states: {
+					idle: {
+						transitions: {
+							goToUnknown: () => 'unknown' as TestState,
+						},
+					},
+					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()
+		})
+	})
+
+	describe('getJsonDump', () => {
+		it('returns JSON string with current state and context', () => {
+			const dump = machine.getJsonDump()
+			const parsed = JSON.parse(dump)
+			expect(parsed.state).toBe('idle')
+			expect(parsed.context).toEqual({ count: 0 })
+		})
+
+		it('reflects context changes after updateContext', () => {
+			machine.updateContext({ count: 42 })
+			const parsed = JSON.parse(machine.getJsonDump())
+			expect(parsed.context.count).toBe(42)
+		})
+
+		it('reflects state changes after transition', async () => {
+			await machine.transition('start')
+			const parsed = JSON.parse(machine.getJsonDump())
+			expect(parsed.state).toBe('active')
+			expect(parsed.context.count).toBe(1)
+		})
+
+		it('returns valid JSON that can be parsed', () => {
+			const dump = machine.getJsonDump()
+			expect(() => JSON.parse(dump)).not.toThrow()
+		})
+	})
+})

package/src/helpers/__tests__/deepMerge.test.ts

@@ -0,0 +1,60 @@
+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/src/helpers/__tests__/dummyClone.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { dummyClone } from '../dummyClone';
+
+describe('dummyClone', () => {
+	it('clones a plain object', () => {
+		const original = { a: 1, b: 2, c: 3 };
+
+		const result = dummyClone(original);
+
+		expect(result).toEqual(original);
+		expect(result).not.toBe(original);
+	});
+
+	it('clones an array', () => {
+		const original = [1, 2, 3, 4, 5];
+
+		const result = dummyClone(original);
+
+		expect(result).toEqual(original);
+		expect(result).not.toBe(original);
+	});
+
+	it('clones nested objects', () => {
+		const original = {
+			user: {
+				name: 'Alice',
+				address: {
+					city: 'Wonderland',
+					zip: '12345',
+				},
+			},
+			tags: ['a', 'b'],
+		};
+
+		const result = dummyClone(original);
+
+		expect(result).toEqual(original);
+		expect(result).not.toBe(original);
+		expect(result.user).not.toBe(original.user);
+		expect(result.user.address).not.toBe(original.user.address);
+	});
+
+	it('handles primitive values', () => {
+		expect(dummyClone(42)).toBe(42);
+		expect(dummyClone('hello')).toBe('hello');
+		expect(dummyClone(true)).toBe(true);
+		expect(dummyClone(false)).toBe(false);
+	});
+
+	it('handles null', () => {
+		expect(dummyClone(null)).toBe(null);
+	});
+
+	it('handles undefined', () => {
+		expect(dummyClone(undefined)).toBe(undefined);
+	});
+
+	it('handles empty object', () => {
+		const original = {};
+
+		const result = dummyClone(original);
+
+		expect(result).toEqual(original);
+		expect(result).not.toBe(original);
+	});
+
+	it('handles empty array', () => {
+		const original: number[] = [];
+
+		const result = dummyClone(original);
+
+		expect(result).toEqual(original);
+		expect(result).not.toBe(original);
+	});
+
+	it('converts Date to string (JSON limitation)', () => {
+		const original = { date: new Date('2024-01-01T00:00:00.000Z') };
+
+		const result = dummyClone(original);
+
+		expect(typeof result.date).toBe('string');
+		expect(result.date).toBe('2024-01-01T00:00:00.000Z');
+	});
+
+	it('can modify clone without affecting original', () => {
+		const original = { a: 1, b: 2 };
+
+		const result = dummyClone(original);
+		result.b = 99;
+
+		expect(original.b).toBe(2);
+		expect(result.b).toBe(99);
+	});
+});

package/src/helpers/__tests__/isObject.test.ts

@@ -0,0 +1,33 @@
+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/src/helpers/__tests__/jsonSafe.test.ts

@@ -0,0 +1,166 @@
+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((() => {}) as any)).toThrow('Function at root is not JSON-safe');
+	});
+
+	it('throws with path for function in object', () => {
+		expect(() => assertJsonSafe({ fn: (() => {}) as any })).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 as any, 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 as any } } } } }))
+			.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<typeof original>(json);
+		expect(restored).toEqual(original);
+	});
+});

package/src/helpers/__tests__/makeReadonlyObject.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import { makeReadonlyObject } from '../makeReadonlyObject';
+
+describe('makeReadonlyObject', () => {
+	describe('returns new object', () => {
+		it('does not modify the original object', () => {
+			const original = { a: 1, b: 2 };
+			const readonly = makeReadonlyObject(original);
+
+			original.a = 99;
+			expect(original.a).toBe(99);
+			expect(readonly.a).toBe(1);
+		});
+
+		it('returns a different reference', () => {
+			const original = { a: 1 };
+			const readonly = makeReadonlyObject(original);
+			expect(readonly).not.toBe(original);
+		});
+	});
+
+	describe('setting properties throws', () => {
+		it('throws when setting an existing property', () => {
+			const readonly = makeReadonlyObject({ a: 1 });
+			expect(() => {
+				readonly.a = 2;
+			}).toThrow(TypeError);
+		});
+
+		it('throws when adding a new property', () => {
+			const readonly = makeReadonlyObject({ a: 1 });
+			expect(() => {
+				readonly.b = 2;
+			}).toThrow(TypeError);
+		});
+
+		it('error message includes property name', () => {
+			const readonly = makeReadonlyObject({ a: 1 });
+			expect(() => {
+				readonly.a = 2;
+			}).toThrow('Cannot set property "a"');
+		});
+	});
+
+	describe('deleting properties throws', () => {
+		it('throws when deleting a property', () => {
+			const readonly = makeReadonlyObject({ a: 1 });
+			expect(() => {
+				delete readonly.a;
+			}).toThrow(TypeError);
+		});
+
+		it('error message includes property name', () => {
+			const readonly = makeReadonlyObject({ a: 1 });
+			expect(() => {
+				delete readonly.a;
+			}).toThrow('Cannot delete property "a"');
+		});
+	});
+
+	describe('reading properties works', () => {
+		it('returns primitive values', () => {
+			const readonly = makeReadonlyObject({ a: 1, b: 'string', c: true });
+			expect(readonly.a).toBe(1);
+			expect(readonly.b).toBe('string');
+			expect(readonly.c).toBe(true);
+		});
+
+		it('returns nested objects as readonly proxies', () => {
+			const readonly = makeReadonlyObject({ nested: { deep: 42 } });
+			expect(readonly.nested.deep).toBe(42);
+		});
+	});
+
+	describe('nested objects are readonly', () => {
+		it('throws when setting a nested property', () => {
+			const readonly = makeReadonlyObject({ nested: { deep: 42 } });
+			expect(() => {
+				readonly.nested.deep = 100;
+			}).toThrow(TypeError);
+		});
+
+		it('throws when adding a nested property', () => {
+			const readonly = makeReadonlyObject({ nested: { deep: 42 } });
+			expect(() => {
+				readonly.nested.newProp = 'value';
+			}).toThrow(TypeError);
+		});
+
+		it('throws when deleting a nested property', () => {
+			const readonly = makeReadonlyObject({ nested: { deep: 42 } });
+			expect(() => {
+				delete readonly.nested.deep;
+			}).toThrow(TypeError);
+		});
+	});
+
+	describe('arrays are readonly', () => {
+		it('throws when mutating an array', () => {
+			const readonly = makeReadonlyObject([1, 2, 3]);
+			expect(() => {
+				readonly.push(4);
+			}).toThrow(TypeError);
+		});
+
+		it('throws when setting array element', () => {
+			const readonly = makeReadonlyObject([1, 2, 3]);
+			expect(() => {
+				readonly[0] = 99;
+			}).toThrow(TypeError);
+		});
+
+		it('throws when adding array element', () => {
+			const readonly = makeReadonlyObject([1, 2, 3]);
+			expect(() => {
+				readonly[10] = 99;
+			}).toThrow(TypeError);
+		});
+
+		it('reading array elements works', () => {
+			const readonly = makeReadonlyObject([1, 2, 3]);
+			expect(readonly[0]).toBe(1);
+			expect(readonly.length).toBe(3);
+		});
+	});
+
+	describe('handles edge cases', () => {
+		it('returns null as-is', () => {
+			const result = makeReadonlyObject(null);
+			expect(result).toBe(null);
+		});
+
+		it('returns primitives as-is', () => {
+			expect(makeReadonlyObject(42)).toBe(42);
+			expect(makeReadonlyObject('string')).toBe('string');
+			expect(makeReadonlyObject(true)).toBe(true);
+			expect(makeReadonlyObject(undefined)).toBe(undefined);
+		});
+
+		it('handles empty objects', () => {
+			const readonly = makeReadonlyObject({});
+			expect(() => {
+				readonly.a = 1;
+			}).toThrow(TypeError);
+		});
+
+		it('handles deeply nested structures', () => {
+			const readonly = makeReadonlyObject({
+				level1: {
+					level2: {
+						level3: {
+							value: 'deep',
+						},
+					},
+				},
+			});
+			expect(readonly.level1.level2.level3.value).toBe('deep');
+			expect(() => {
+				readonly.level1.level2.level3.value = 'changed';
+			}).toThrow(TypeError);
+		});
+
+		it('handles arrays containing objects', () => {
+			const readonly = makeReadonlyObject([{ a: 1 }, { b: 2 }]);
+			expect(readonly[0].a).toBe(1);
+			expect(() => {
+				readonly[0].a = 99;
+			}).toThrow(TypeError);
+		});
+	});
+});

package/src/helpers/__tests__/toPromise.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest'
+import { toPromise } from '../toPromise'
+
+describe('toPromise', () => {
+	it('should return a function that returns a promise', () => {
+		const syncFn = () => 'result'
+		const promisified = toPromise(syncFn)
+		expect(typeof promisified).toBe('function')
+		const result = promisified()
+		expect(result).toBeInstanceOf(Promise)
+	})
+
+	it('should wrap sync function and return resolved promise', async () => {
+		const syncFn = () => 'sync result'
+		const result = await toPromise(syncFn)()
+		expect(result).toBe('sync result')
+	})
+
+	it('should wrap async function and return the same promise', async () => {
+		const asyncFn = async () => 'async result'
+		const result = await toPromise(asyncFn)()
+		expect(result).toBe('async result')
+	})
+
+	it('should pass through the result value of sync function returning undefined', async () => {
+		const syncFn = () => undefined
+		const result = await toPromise(syncFn)()
+		expect(result).toBeUndefined()
+	})
+
+	it('should pass through the result value of async function returning null', async () => {
+		const asyncFn = async () => null
+		const result = await toPromise(asyncFn)()
+		expect(result).toBeNull()
+	})
+})

package/src/helpers/deepMerge.ts

@@ -0,0 +1,21 @@
+import { isObject } from './isObject';
+
+export function deepMerge(target: any, source: any): any {
+	const output = { ...target };
+
+	if (isObject(target) && isObject(source)) {
+		Object.keys(source).forEach(key => {
+			if (isObject(source[key])) {
+				if (!(key in target)) {
+					output[key] = source[key];
+				} else {
+					output[key] = deepMerge(target[key], source[key]);
+				}
+			} else {
+				output[key] = source[key];
+			}
+		});
+	}
+
+	return output;
+}

package/src/helpers/dummyClone.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates a deep clone of a value using JSON parse/stringify.
+ * This is a simple but limited cloning approach - it only works
+ * with JSON-safe values and will convert Date objects to strings.
+ *
+ * @param obj - The value to clone.
+ *
+ * @returns A deep clone of the input value.
+ */
+export function dummyClone<T>(obj: T): T {
+	if (obj === undefined) {
+		return undefined as T;
+	}
+	return JSON.parse(JSON.stringify(obj)) as T;
+}

package/src/helpers/isObject.ts

@@ -0,0 +1,3 @@
+export function isObject(item: unknown): boolean {
+	return item !== null && typeof item === 'object' && !Array.isArray(item);
+}

package/src/helpers/jsonSafe.ts

@@ -0,0 +1,71 @@
+export function isJsonSafe(value: unknown): boolean {
+  if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isJsonSafe);
+  }
+
+  if (typeof value === 'object') {
+    if (value instanceof Date) {
+      return true;
+    }
+    if (value instanceof RegExp) {
+      return true;
+    }
+    if (value instanceof Map || value instanceof Set) {
+      return false;
+    }
+    if (value instanceof Error) {
+      return false;
+    }
+
+    return Object.entries(value).every(([k, v]) => typeof k === 'string' && isJsonSafe(v));
+  }
+
+  if (typeof value === 'function' || typeof value === 'undefined' || typeof value === 'symbol' || typeof value === 'bigint') {
+    return false;
+  }
+
+  return false;
+}
+
+export function assertJsonSafe(value: unknown, path = ''): void {
+  if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertJsonSafe(item, `${path}[${i}]`));
+    return;
+  }
+
+  if (typeof value === 'object') {
+    if (value instanceof Date) return;
+    if (value instanceof RegExp) return;
+    if (value instanceof Map) throw new TypeError(`Map at ${path} is not JSON-safe`);
+    if (value instanceof Set) throw new TypeError(`Set at ${path} is not JSON-safe`);
+    if (value instanceof Error) throw new TypeError(`Error at ${path} is not JSON-safe`);
+
+    for (const [k, v] of Object.entries(value)) {
+      assertJsonSafe(v, path ? `${path}.${k}` : k);
+    }
+    return;
+  }
+
+  if (typeof value === 'function') throw new TypeError(`Function at ${path || 'root'} is not JSON-safe`);
+  if (typeof value === 'undefined') throw new TypeError(`Undefined at ${path || 'root'} is not JSON-safe`);
+  if (typeof value === 'symbol') throw new TypeError(`Symbol at ${path || 'root'} is not JSON-safe`);
+  if (typeof value === 'bigint') throw new TypeError(`BigInt at ${path || 'root'} is not JSON-safe`);
+
+  throw new TypeError(`Value at ${path || 'root'} is not JSON-safe`);
+}
+
+export function toJson(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+export function fromJson<T>(json: string): T {
+  return JSON.parse(json) as T;
+}

package/src/helpers/makeReadonlyObject.ts

@@ -0,0 +1,34 @@
+import { isObject } from './isObject';
+import { dummyClone } from './dummyClone';
+
+export function makeReadonlyObject<T extends object>(obj: T): Readonly<T> {
+	if (obj === null) {
+		return null as unknown as Readonly<T>;
+	}
+
+	if (typeof obj !== 'object' && typeof obj !== 'function') {
+		return obj;
+	}
+
+	const cloned = dummyClone(obj);
+
+	const handler: ProxyHandler<object> = {
+		set(_target, property, _value) {
+			throw new TypeError(`Cannot set property "${String(property)}": object is readonly`);
+		},
+		deleteProperty(_target, property) {
+			throw new TypeError(`Cannot delete property "${String(property)}": object is readonly`);
+		},
+		get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver);
+
+			if (isObject(value) || Array.isArray(value)) {
+				return new Proxy(value, handler);
+			}
+
+			return value;
+		},
+	};
+
+	return new Proxy(cloned, handler) as Readonly<T>;
+}

package/src/helpers/toPromise.ts

@@ -0,0 +1,5 @@
+export function toPromise<T>(
+  fn: (() => T) | (() => Promise<T>)
+): () => Promise<T> {
+  return () => Promise.resolve(fn());
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { MachinaContext, MachinaStates, TransitionFn } from './types';
+export { XMachina } from './XMachina';

package/src/types.ts

@@ -0,0 +1,11 @@
+export type MachinaContext = Record<string, any>;
+
+export type TransitionFn<C extends MachinaContext, S extends string> = 
+  (context: C, event?: any) => (S | null) | Promise<S | null>;
+
+export type MachinaStates<C extends MachinaContext, S extends string> = Record<
+	S,
+	{
+		transitions?: Record<string, TransitionFn<C, S>>
+	} | null
+>

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		include: ['**/__tests__/**/*.test.ts'],
+		environment: 'node',
+		globals: false,
+	},
+})