@classytic/primitives 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-05-02
+
+### Added — state-machine ↔ mongokit/sqlitekit integration
+
+State-machine primitives now compose directly with the kit-level CAS surface shipped in mongokit 3.13 and the sqlitekit follow-up. Three additions:
+
+- **`StateMachine.validTargets(from)`** — every status the aggregate can move TO from `from`. Useful for UI dropdowns ("which actions are legal right now?") and for fanning a single source state into a multi-source CAS via a repo's `claim({ from: machine.validTargets(current), to })`.
+- **`StateMachine.validSources(to)`** — every status that can transition INTO `to` (reverse adjacency). Pair with a repo's multi-source `claim({ from: machine.validSources(to), to })` when the target is fixed but the caller doesn't yet know the current state — the canonical "cancel from any non-terminal" / "error from any in-flight" pattern. Pre-computed at definition time, O(1) lookup, frozen arrays safe to expose by reference.
+- **`assertAndClaim(machine, repo, id, args)`** — pairs `machine.assertTransition` (sync domain check) with `repo.claim()` (atomic CAS) in one call. The canonical state-machine-backed CAS pattern. Skipping either layer leaves a hole: skip `assertTransition` and bad transitions reach storage; skip `claim` and concurrent writers race.
+
+```ts
+import { defineStateMachine, assertAndClaim } from '@classytic/primitives/state-machine';
+
+const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+  name: 'Order',
+  transitions: {
+    draft:     ['approved', 'cancelled'],
+    approved:  ['shipped', 'cancelled'],
+    shipped:   [],
+    cancelled: [],
+  },
+});
+
+// Single-source:
+const updated = await assertAndClaim(ORDER_MACHINE, orderRepo, orderId, {
+  from: 'draft',
+  to: 'approved',
+  patch: { approvedAt: new Date() },
+  options: { organizationId: ctx.organizationId, session },
+});
+
+// Multi-source via reverse adjacency — "cancel from any legal predecessor":
+await assertAndClaim(ORDER_MACHINE, orderRepo, orderId, {
+  from: ORDER_MACHINE.validSources('cancelled'), // ['draft', 'approved']
+  to: 'cancelled',
+  patch: { cancelledAt: new Date() },
+  options: { organizationId: ctx.organizationId },
+});
+```
+
+#### `ClaimableRepo<TDoc>` — structural dependency on the kit
+
+`assertAndClaim` accepts any object matching `ClaimableRepo<TDoc>` — a structural type that mirrors the mongokit 3.13 `Repository.claim()` signature. Primitives doesn't take a hard peer dep on mongokit; consumers wire the kit they want. Sqlitekit's `claim()` matches the same shape (verified by mongokit/sqlitekit cross-conformance).
+
+```ts
+export interface ClaimableRepo<TDoc> {
+  claim(
+    id: string,
+    transition: {
+      field?: string;
+      from: unknown | readonly unknown[];
+      to: unknown;
+      where?: Record<string, unknown>;
+    },
+    patch?: Record<string, unknown>,
+    options?: Record<string, unknown>,
+  ): Promise<TDoc | null>;
+}
+```
+
+#### Why a 0.3.1 (not 0.4.0)
+
+Purely additive — no removals, no signature changes. `defineStateMachine` callers from 0.3.0 see two new methods on the returned `StateMachine` (`validTargets`, `validSources`) and one new free function (`assertAndClaim`). Backwards-compatible.
+
 ## [0.3.0] - 2026-04-29
 
 ### Removed — `/errors` subpath (BREAKING)

package/dist/state-machine.d.mts

@@ -95,9 +95,89 @@ interface StateMachine<TStatus extends string> {
    * `entityId` is included in the error for traceability.
    */
   assertTransition(entityId: string, from: TStatus, to: TStatus): void;
+  /**
+   * Forward lookup — every status the aggregate can move TO from `from`.
+   * Useful for UI dropdowns ("which actions are legal right now?") and
+   * for fanning a single source state into a multi-source CAS via a
+   * repo's `claim({ from: machine.validTargets(current), to })`.
+   */
+  validTargets(from: TStatus): readonly TStatus[];
+  /**
+   * Reverse lookup — every status that can transition INTO `to`. Pair
+   * with a repo's multi-source `claim({ from: machine.validSources(to), to })`
+   * when the target is fixed but the caller doesn't yet know the
+   * current state (or wants to authorize ALL legal predecessors in one
+   * round-trip).
+   */
+  validSources(to: TStatus): readonly TStatus[];
   /** The raw transition table — exposed read-only for advanced callers. */
   readonly transitions: Readonly<Record<TStatus, readonly TStatus[]>>;
 }
 declare function defineStateMachine<TStatus extends string>(definition: StateMachineDefinition<TStatus>): StateMachine<TStatus>;
+/**
+ * Minimal structural type for any kit's `claim()` operation. Lets
+ * `assertAndClaim` work against `@classytic/mongokit` (and future
+ * sqlitekit / pgkit) without primitives taking a hard peer dep.
+ *
+ * Mirrors the mongokit 3.13 `Repository.claim()` signature with
+ * `unknown`-typed values where the kit-specific shape (ObjectId, etc.)
+ * doesn't concern the state-machine layer.
+ */
+interface ClaimableRepo<TDoc> {
+  claim(id: string, transition: {
+    field?: string;
+    from: unknown | readonly unknown[];
+    to: unknown;
+    where?: Record<string, unknown>;
+  }, patch?: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc | null>;
+}
+/**
+ * Pair a state-machine `assertTransition()` (sync domain check) with a
+ * repo's `claim()` (runtime concurrency CAS) in one call. This is the
+ * canonical state-machine-backed CAS pattern documented in mongokit
+ * 3.13's CLAUDE.md.
+ *
+ *   - `assertTransition` rejects malformed transitions BEFORE we hit the
+ *     database (compile-time-typed targets, sync, fast).
+ *   - `claim` rejects concurrent writers AT the database (atomic
+ *     CAS, returns `null` on race-loss).
+ *
+ * Skipping either layer leaves a hole: skip `assertTransition` and bad
+ * transitions reach storage; skip `claim` and concurrent writers race.
+ *
+ * `from` accepts a single status OR an array of statuses (multi-source
+ * CAS). When the array form is used, `assertTransition` is asserted for
+ * EVERY listed source — a single illegal source aborts the call before
+ * the round-trip.
+ *
+ * @example Single-source
+ * ```ts
+ * const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+ *   from: 'planned',
+ *   to: 'released',
+ *   patch: { releasedAt: new Date() },
+ *   options: { organizationId: ctx.organizationId, session },
+ * });
+ * if (!updated) throw new ConcurrencyError(); // race-loss
+ * ```
+ *
+ * @example Multi-source via `validSources`
+ * ```ts
+ * const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+ *   from: WAVE_MACHINE.validSources('cancelled'), // every legal predecessor
+ *   to: 'cancelled',
+ *   patch: { cancelledAt: new Date() },
+ *   options: { organizationId: ctx.organizationId },
+ * });
+ * ```
+ */
+declare function assertAndClaim<TDoc, TStatus extends string>(machine: StateMachine<TStatus>, repo: ClaimableRepo<TDoc>, id: string, args: {
+  from: TStatus | readonly TStatus[];
+  to: TStatus;
+  field?: string;
+  patch?: Record<string, unknown>;
+  where?: Record<string, unknown>;
+  options?: Record<string, unknown>;
+}): Promise<TDoc | null>;
 //#endregion
-export { IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, defineStateMachine };
+export { ClaimableRepo, IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, assertAndClaim, defineStateMachine };

package/dist/state-machine.mjs

@@ -68,7 +68,18 @@ var IllegalTransitionError = class extends Error {
 function defineStateMachine(definition) {
 	const { name, transitions, errorFactory } = definition;
 	const terminal = /* @__PURE__ */ new Set();
-	for (const [status, allowed] of Object.entries(transitions)) if (allowed.length === 0) terminal.add(status);
+	const reverse = /* @__PURE__ */ new Map();
+	for (const [status, allowed] of Object.entries(transitions)) {
+		if (allowed.length === 0) terminal.add(status);
+		for (const target of allowed) {
+			const sources = reverse.get(target);
+			if (sources) sources.push(status);
+			else reverse.set(target, [status]);
+		}
+	}
+	const frozenReverse = /* @__PURE__ */ new Map();
+	for (const [target, sources] of reverse) frozenReverse.set(target, Object.freeze(sources.slice()));
+	const EMPTY = Object.freeze([]);
 	const buildError = errorFactory ? errorFactory : (ctx) => new IllegalTransitionError(ctx.entityType, ctx.entityId, ctx.from, ctx.to);
 	return {
 		name,
@@ -87,8 +98,64 @@ function defineStateMachine(definition) {
 				from,
 				to
 			});
+		},
+		validTargets(from) {
+			return transitions[from] ?? EMPTY;
+		},
+		validSources(to) {
+			return frozenReverse.get(to) ?? EMPTY;
 		}
 	};
 }
+/**
+* Pair a state-machine `assertTransition()` (sync domain check) with a
+* repo's `claim()` (runtime concurrency CAS) in one call. This is the
+* canonical state-machine-backed CAS pattern documented in mongokit
+* 3.13's CLAUDE.md.
+*
+*   - `assertTransition` rejects malformed transitions BEFORE we hit the
+*     database (compile-time-typed targets, sync, fast).
+*   - `claim` rejects concurrent writers AT the database (atomic
+*     CAS, returns `null` on race-loss).
+*
+* Skipping either layer leaves a hole: skip `assertTransition` and bad
+* transitions reach storage; skip `claim` and concurrent writers race.
+*
+* `from` accepts a single status OR an array of statuses (multi-source
+* CAS). When the array form is used, `assertTransition` is asserted for
+* EVERY listed source — a single illegal source aborts the call before
+* the round-trip.
+*
+* @example Single-source
+* ```ts
+* const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+*   from: 'planned',
+*   to: 'released',
+*   patch: { releasedAt: new Date() },
+*   options: { organizationId: ctx.organizationId, session },
+* });
+* if (!updated) throw new ConcurrencyError(); // race-loss
+* ```
+*
+* @example Multi-source via `validSources`
+* ```ts
+* const updated = await assertAndClaim(WAVE_MACHINE, repo, waveId, {
+*   from: WAVE_MACHINE.validSources('cancelled'), // every legal predecessor
+*   to: 'cancelled',
+*   patch: { cancelledAt: new Date() },
+*   options: { organizationId: ctx.organizationId },
+* });
+* ```
+*/
+async function assertAndClaim(machine, repo, id, args) {
+	const sources = Array.isArray(args.from) ? args.from : [args.from];
+	for (const from of sources) machine.assertTransition(id, from, args.to);
+	return repo.claim(id, {
+		from: Array.isArray(args.from) ? args.from : args.from,
+		to: args.to,
+		...args.field !== void 0 ? { field: args.field } : {},
+		...args.where !== void 0 ? { where: args.where } : {}
+	}, args.patch, args.options);
+}
 //#endregion
-export { IllegalTransitionError, defineStateMachine };
+export { IllegalTransitionError, assertAndClaim, defineStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",