@classytic/primitives 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 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.2.0]
+
+### Added
+
+- **`/state-machine` subpath** — `defineStateMachine<TStatus>({ name, transitions, errorFactory? })`
+  declarative state-transition primitive. Replaces hand-rolled
+  `if (status === 'X') throw` blocks across kernels:
+
+  ```typescript
+  import { defineStateMachine } from '@classytic/primitives/state-machine';
+
+  const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+    name: 'Order',
+    transitions: {
+      draft: ['approved', 'cancelled'],
+      approved: ['shipped', 'cancelled'],
+      shipped: [],
+      cancelled: [],
+    },
+  });
+
+  ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+  ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+  ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+  ORDER_MACHINE.isTerminal('shipped');                            // true
+  ```
+
+  Generic over the status string-union — `Record<TStatus, readonly TStatus[]>`
+  on `transitions` enforces exhaustiveness at the call site. Kernels with their
+  own typed transition error class (e.g. flow's `InvalidTransitionError`) wire
+  it via `errorFactory` so the thrown type stays domain-consistent. Standalone
+  callers get the bundled `IllegalTransitionError` (carries `entityType` /
+  `entityId` / `from` / `to` + `code: 'illegal_transition'` + `status: 422`).
+
+  First consumer: `@classytic/flow` `PROCUREMENT_MACHINE` (procurement-order
+  approve / cancel transitions).
+
+## [0.1.1]
+
+### Added
+
+- **`MinorUnits<C>` branded type on `/money`** — wire-format monetary amount
+  (integer minor units, branded with phantom currency) for HTTP/JSON fields
+  where a full `Money` struct is overkill. Erases at runtime; `MinorUnits<'BDT'>`
+  vs `MinorUnits<'USD'>` collide at compile time. Pair with structured `Money`
+  for in-process arithmetic. Constructor: `MinorUnits(amount, currency?)`.
+
+### Changed
+
+- **`/tenant` `contextKey` cascade default** — `resolveTenantConfig({ tenantField: 'branchId' })`
+  now defaults `contextKey` to `'branchId'` instead of `'organizationId'`.
+  When a host renames `tenantField`, their `OperationContext` carries the id
+  under the same key in the overwhelming majority of cases; mirroring the
+  rename is the least-surprise default. Explicit `contextKey` still overrides
+  (set when the doc field and context key genuinely diverge). Existing call
+  sites that supplied both `tenantField` and `contextKey` are unaffected.
+
 ## [0.1.0]
 
 Initial release. Framework-agnostic TypeScript primitives shared across

package/dist/money.d.mts

@@ -1,6 +1,38 @@
 import { CurrencyCode } from "./currency.mjs";
 
 //#region src/money.d.ts
+/**
+ * Wire-format monetary amount: integer minor units, branded with a phantom
+ * currency type so calls like `formatBdt(usdValue)` fail at compile time.
+ *
+ * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
+ * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
+ * with the structured {@link Money} for in-process arithmetic.
+ *
+ * Erases at runtime — branded types have zero cost.
+ *
+ * @example
+ * type Paisa = MinorUnits<'BDT'>;
+ * type UsdCents = MinorUnits<'USD'>;
+ * const p: Paisa = MinorUnits(489900, 'BDT');
+ * const c: UsdCents = p; // ❌ type error: BDT vs USD
+ */
+declare const __unitBrand: unique symbol;
+declare const __currencyBrand: unique symbol;
+type MinorUnits<C extends string = string> = number & {
+  readonly [__unitBrand]: 'minor';
+  readonly [__currencyBrand]: C;
+};
+/**
+ * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+ * argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+ * — useful for generic SDK boundaries that don't know the currency yet.
+ *
+ * @example
+ * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+ * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+ */
+declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
 /**
  * A monetary amount stored as an integer in the currency's minor unit.
  *
@@ -75,4 +107,4 @@ declare function absMoney(m: Money): Money;
 /** Structural type guard. */
 declare function isMoney(value: unknown): value is Money;
 //#endregion
-export { CurrencyMismatchError, Money, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };

package/dist/money.mjs

@@ -1,5 +1,17 @@
 import { minorUnitFactor } from "./currency.mjs";
 //#region src/money.ts
+/**
+* Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+* argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+* — useful for generic SDK boundaries that don't know the currency yet.
+*
+* @example
+* MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+* MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+*/
+function MinorUnits(amount, _currency) {
+	return amount;
+}
 var CurrencyMismatchError = class extends Error {
 	name = "CurrencyMismatchError";
 	left;
@@ -128,4 +140,4 @@ function isMoney(value) {
 	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && typeof value.currency === "string";
 }
 //#endregion
-export { CurrencyMismatchError, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };

package/dist/state-machine.d.mts

@@ -0,0 +1,103 @@
+//#region src/state-machine.d.ts
+/**
+ * Declarative state-machine primitive.
+ *
+ * Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+ * across domain services. Each aggregate declares one transition table;
+ * the helper provides `canTransition` / `assertTransition` / `isTerminal`
+ * accessors that the services share.
+ *
+ * Generic over the status string-union so calls stay type-safe:
+ *   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+ * The TS compiler enforces exhaustiveness — every status string in the
+ * union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+ *
+ * @example
+ * import { defineStateMachine } from '@classytic/primitives/state-machine';
+ *
+ * type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+ * const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+ *   name: 'Order',
+ *   transitions: {
+ *     draft: ['approved', 'cancelled'],
+ *     approved: ['shipped', 'cancelled'],
+ *     shipped: [],
+ *     cancelled: [],
+ *   },
+ * });
+ *
+ * ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+ * ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+ * ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+ * ORDER_MACHINE.isTerminal('shipped');                            // true
+ *
+ * Hosts that already have their own typed transition error can swap it
+ * in via `errorFactory`:
+ *
+ * @example
+ * import { InvalidTransitionError } from './errors.js';
+ * const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+ *   name: 'StockMove',
+ *   transitions: { … },
+ *   errorFactory: ({ entityType, entityId, from, to }) =>
+ *     new InvalidTransitionError(entityType, entityId, from, to),
+ * });
+ */
+/**
+ * Default error thrown by `assertTransition` when no `errorFactory` is
+ * supplied. Carries the structured fields (`entityType`, `entityId`,
+ * `from`, `to`) plus a stable `code` so hosts can pattern-match on
+ * either `instanceof` or `error.code === 'illegal_transition'`.
+ */
+declare class IllegalTransitionError extends Error {
+  readonly code: "illegal_transition";
+  readonly status = 422;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+  constructor(entityType: string, entityId: string, from: string, to: string);
+}
+interface TransitionErrorContext {
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+}
+interface StateMachineDefinition<TStatus extends string> {
+  /** Aggregate name surfaced in the thrown error's `entityType`. */
+  name: string;
+  /**
+   * Adjacency list — for each status, the set of statuses you can
+   * legally transition TO. Terminal statuses map to an empty array.
+   * `Record<TStatus, …>` enforces exhaustiveness at the call site.
+   */
+  transitions: Record<TStatus, readonly TStatus[]>;
+  /**
+   * Optional custom error factory. When omitted, `assertTransition`
+   * throws `IllegalTransitionError`. Hosts that own a domain error
+   * (e.g. flow's `InvalidTransitionError`) wire their own here so the
+   * thrown type stays consistent with the rest of the package.
+   */
+  errorFactory?: (ctx: TransitionErrorContext) => Error;
+}
+interface StateMachine<TStatus extends string> {
+  /** The aggregate name (`StockMove`, `ProcurementOrder`, etc.). */
+  readonly name: string;
+  /** All terminal statuses (no outgoing transitions). */
+  readonly terminal: ReadonlySet<TStatus>;
+  /** True when `from → to` is in the transition table. */
+  canTransition(from: TStatus, to: TStatus): boolean;
+  /** True when `status` is terminal. */
+  isTerminal(status: TStatus): boolean;
+  /**
+   * Throw a transition error when `from → to` isn't allowed.
+   * `entityId` is included in the error for traceability.
+   */
+  assertTransition(entityId: string, from: TStatus, to: TStatus): void;
+  /** 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>;
+//#endregion
+export { IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, defineStateMachine };

package/dist/state-machine.mjs

@@ -0,0 +1,94 @@
+//#region src/state-machine.ts
+/**
+* Declarative state-machine primitive.
+*
+* Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+* across domain services. Each aggregate declares one transition table;
+* the helper provides `canTransition` / `assertTransition` / `isTerminal`
+* accessors that the services share.
+*
+* Generic over the status string-union so calls stay type-safe:
+*   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+* The TS compiler enforces exhaustiveness — every status string in the
+* union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+*
+* @example
+* import { defineStateMachine } from '@classytic/primitives/state-machine';
+*
+* type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+* const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+*   name: 'Order',
+*   transitions: {
+*     draft: ['approved', 'cancelled'],
+*     approved: ['shipped', 'cancelled'],
+*     shipped: [],
+*     cancelled: [],
+*   },
+* });
+*
+* ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+* ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+* ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+* ORDER_MACHINE.isTerminal('shipped');                            // true
+*
+* Hosts that already have their own typed transition error can swap it
+* in via `errorFactory`:
+*
+* @example
+* import { InvalidTransitionError } from './errors.js';
+* const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+*   name: 'StockMove',
+*   transitions: { … },
+*   errorFactory: ({ entityType, entityId, from, to }) =>
+*     new InvalidTransitionError(entityType, entityId, from, to),
+* });
+*/
+/**
+* Default error thrown by `assertTransition` when no `errorFactory` is
+* supplied. Carries the structured fields (`entityType`, `entityId`,
+* `from`, `to`) plus a stable `code` so hosts can pattern-match on
+* either `instanceof` or `error.code === 'illegal_transition'`.
+*/
+var IllegalTransitionError = class extends Error {
+	code = "illegal_transition";
+	status = 422;
+	entityType;
+	entityId;
+	from;
+	to;
+	constructor(entityType, entityId, from, to) {
+		super(`Invalid transition for ${entityType} ${entityId}: ${from} → ${to}`);
+		this.name = "IllegalTransitionError";
+		this.entityType = entityType;
+		this.entityId = entityId;
+		this.from = from;
+		this.to = to;
+	}
+};
+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 buildError = errorFactory ? errorFactory : (ctx) => new IllegalTransitionError(ctx.entityType, ctx.entityId, ctx.from, ctx.to);
+	return {
+		name,
+		terminal,
+		transitions,
+		canTransition(from, to) {
+			return transitions[from]?.includes(to) ?? false;
+		},
+		isTerminal(status) {
+			return terminal.has(status);
+		},
+		assertTransition(entityId, from, to) {
+			if (!transitions[from]?.includes(to)) throw buildError({
+				entityType: name,
+				entityId,
+				from,
+				to
+			});
+		}
+	};
+}
+//#endregion
+export { IllegalTransitionError, defineStateMachine };

package/dist/tenant.d.mts

@@ -71,7 +71,14 @@ interface TenantConfig {
   /**
    * Which key on `OperationContext` to read the tenant id from.
    *
-   * @default 'organizationId'
+   * Defaults cascade: if omitted, falls back to the caller's `tenantField`
+   * (if supplied), else to `'organizationId'`. Rationale: when a host renames
+   * `tenantField` to e.g. `'branchId'`, their `OperationContext` almost always
+   * carries the value under the same key — so mirroring `tenantField` is the
+   * least-surprise behavior. Override explicitly if the context key diverges
+   * from the document field (e.g. `tenantField: 'branchId'`, `contextKey: 'organizationId'`).
+   *
+   * @default tenantField ?? 'organizationId'
    */
   contextKey?: string;
   /**

package/dist/tenant.mjs

@@ -26,9 +26,11 @@ function resolveTenantConfig(config) {
 	};
 	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
 	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
+	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
 	if (strategy === "none") return {
 		...DEFAULT_TENANT_CONFIG,
 		...config,
+		contextKey,
 		strategy: "none",
 		enabled: false,
 		required: false
@@ -38,6 +40,7 @@ function resolveTenantConfig(config) {
 		return {
 			...DEFAULT_TENANT_CONFIG,
 			...config,
+			contextKey,
 			strategy: "custom",
 			enabled: config.enabled ?? true,
 			resolve: config.resolve
@@ -46,6 +49,7 @@ function resolveTenantConfig(config) {
 	return {
 		...DEFAULT_TENANT_CONFIG,
 		...config,
+		contextKey,
 		strategy: "field",
 		enabled: config.enabled ?? true
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -97,6 +97,10 @@
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
+    "./state-machine": {
+      "types": "./dist/state-machine.d.mts",
+      "default": "./dist/state-machine.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -117,11 +121,13 @@
     "test:all": "vitest run",
     "test:watch": "vitest --project unit --project integration",
     "test:smoke": "node tests/smoke/smoke.mjs",
+    "push": "classytic-push",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build && npm run test:smoke",
     "release": "npm run build && npm run typecheck && npm publish --access public"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",
+    "@classytic/dev-tools": "^0.2.0",
     "@types/node": "^25.5.0",
     "tsdown": "^0.21.7",
     "typescript": "^5.7.0",