@kronos-ts/modelling 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { type StateModule, type StateLifecycle, type IdSchema, type InferIdFromSchema, state, } from "./state.js";
+export { type StateModule, type StateLifecycle, type EvolverBuilder, type IdSchema, type InferIdFromSchema, state, } from "./state.js";
 export { type SourcingInfo, type LoadResult, type StateRepository, type StateManager, createStateManager, } from "./state-manager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,GACN,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,GACN,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,GACN,MAAM,YAAY,CAAA;AAEnB,OAAO,EAKL,kBAAkB,GACnB,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,GACN,MAAM,YAAY,CAAA;AAEnB,OAAO,EAKL,kBAAkB,GACnB,MAAM,oBAAoB,CAAA"}

package/dist/state.d.ts

@@ -1,6 +1,5 @@
 import type { z } from "zod";
-import type { EventCriteria, EventMessage } from "@kronos-ts/messaging";
-import type { EvolverRegistration } from "@kronos-ts/messaging";
+import type { EventCriteria, EventMessage, EvolverRegistration, EventDescriptor } from "@kronos-ts/messaging";
 /**
  * A named record mapping field names to Zod schemas.
  * Used to define state IDs with explicit field names.
@@ -36,6 +35,15 @@ export interface StateLifecycle<Id = unknown, S = unknown> {
     /** Predicate that detects deleted state. */
     isDeleted?: (state: S) => boolean;
 }
+/**
+ * The state-scoped `on` handed to an `evolve` builder.
+ *
+ * It is the same `on` as the top-level export, but with the state type `S`
+ * already bound. Because `S` is fixed before the evolver callbacks are
+ * checked, each callback receives `state: S` contextually — no `(s: S)`
+ * annotation, and a wrong return is still rejected against `S`.
+ */
+export type EvolverBuilder<S> = <P extends z.ZodType>(descriptor: EventDescriptor<P>, evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>) => EvolverRegistration<S, P>;
 /**
  * A state module — a self-contained definition of state sourced from events.
  *
@@ -64,14 +72,21 @@ export interface StateModule<Id = unknown, S = unknown> {
  * The state type is inferred from the `initial` function's return type —
  * no separate type definition needed.
  *
+ * Evolvers are registered through a builder: `evolve: (on) => [...]`, where
+ * `on` is bound to the state type. Because `S` is fixed by `initial` before
+ * the evolvers are checked, each callback receives `state: S` contextually —
+ * no `(s: S)` annotation, and a wrong return is still rejected against `S`.
+ * When `initial` under-specifies `S` (empty arrays, unions), annotate the one
+ * source of truth: `initial: (id): CourseState => (...)`.
+ *
  * ```typescript
  * const Course = state({
  *   name: "Course",
  *   id: { courseId: z.string() },
  *   initial: () => ({ created: false, name: "", capacity: 0 }),
  *   criteria: (id) => EventCriteria.havingTags({ courseId: id.courseId }),
- *   evolve: [
- *     on(CourseCreated, (s, event) => ({ ...s, created: true })),
+ *   evolve: (on) => [
+ *     on(CourseCreated, (s, { payload: event }) => ({ ...s, created: true })),
  *   ],
  * })
  * ```
@@ -81,7 +96,7 @@ export declare function state<IS extends IdSchema, S>(def: {
     id: IS;
     initial: (id: InferIdFromSchema<IS>) => S;
     criteria: (id: InferIdFromSchema<IS>) => EventCriteria;
-    evolve: Array<EvolverRegistration<S, any>>;
+    evolve: (on: EvolverBuilder<S>) => Array<EvolverRegistration<S, any>>;
     lifecycle?: StateLifecycle<InferIdFromSchema<IS>, S>;
 }): StateModule<InferIdFromSchema<IS>, S>;
 //# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI;KACjD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9B,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACvD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,gEAAgE;IAChE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrF,4CAA4C;IAC5C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW,CAC1B,EAAE,GAAG,OAAO,EACZ,CAAC,GAAG,OAAO;IAEX,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,aAAa,CAAA;IAC5C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,EAAE,CAAA;IACN,OAAO,EAAE,CAAC,EAAE,EAAE,iBAAiB,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;IACzC,QAAQ,EAAE,CAAC,EAAE,EAAE,iBAAiB,CAAC,EAAE,CAAC,KAAK,aAAa,CAAA;IACtD,MAAM,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC1C,SAAS,CAAC,EAAE,cAAc,CAAC,iBAAiB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;CACrD,GAAG,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/state.js

@@ -1,3 +1,33 @@
+import { on } from "@kronos-ts/messaging";
+/**
+ * Defines a state module — state sourced from events, scoped by an ID.
+ *
+ * The `id` parameter must be a named record mapping field names to Zod types.
+ * A bare Zod type (e.g., `z.string()`) will not compile — you must name
+ * the field (e.g., `{ courseId: z.string() }`).
+ *
+ * The state type is inferred from the `initial` function's return type —
+ * no separate type definition needed.
+ *
+ * Evolvers are registered through a builder: `evolve: (on) => [...]`, where
+ * `on` is bound to the state type. Because `S` is fixed by `initial` before
+ * the evolvers are checked, each callback receives `state: S` contextually —
+ * no `(s: S)` annotation, and a wrong return is still rejected against `S`.
+ * When `initial` under-specifies `S` (empty arrays, unions), annotate the one
+ * source of truth: `initial: (id): CourseState => (...)`.
+ *
+ * ```typescript
+ * const Course = state({
+ *   name: "Course",
+ *   id: { courseId: z.string() },
+ *   initial: () => ({ created: false, name: "", capacity: 0 }),
+ *   criteria: (id) => EventCriteria.havingTags({ courseId: id.courseId }),
+ *   evolve: (on) => [
+ *     on(CourseCreated, (s, { payload: event }) => ({ ...s, created: true })),
+ *   ],
+ * })
+ * ```
+ */
 export function state(def) {
     return {
         kind: "state-module",
@@ -5,7 +35,7 @@ export function state(def) {
         idSchema: def.id,
         create: def.initial,
         criteria: def.criteria,
-        evolvers: def.evolve,
+        evolvers: def.evolve(on),
         lifecycle: def.lifecycle,
     };
 }

package/dist/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AA+FA,MAAM,UAAU,KAAK,CAAyB,GAO7C;IACC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,QAAQ,EAAE,GAAG,CAAC,EAAE;QAChB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,MAAM;QACpB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAA;AACH,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAA;AAiFzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,KAAK,CAAyB,GAO7C;IACC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,QAAQ,EAAE,GAAG,CAAC,EAAE;QAChB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EAAkC,CAAC;QACxD,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/modelling",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "State modelling for Kronos — event-sourced state definitions and evolution.",
   "license": "Apache-2.0",
   "type": "module",

package/src/index.ts

@@ -1,6 +1,7 @@
 export {
   type StateModule,
   type StateLifecycle,
+  type EvolverBuilder,
   type IdSchema,
   type InferIdFromSchema,
   state,

package/src/state.ts

@@ -1,6 +1,11 @@
 import type { z } from "zod"
-import type { EventCriteria, EventMessage } from "@kronos-ts/messaging"
-import type { EvolverRegistration } from "@kronos-ts/messaging"
+import { on } from "@kronos-ts/messaging"
+import type {
+  EventCriteria,
+  EventMessage,
+  EvolverRegistration,
+  EventDescriptor,
+} from "@kronos-ts/messaging"
 
 /**
  * A named record mapping field names to Zod schemas.
@@ -40,6 +45,19 @@ export interface StateLifecycle<Id = unknown, S = unknown> {
   isDeleted?: (state: S) => boolean
 }
 
+/**
+ * The state-scoped `on` handed to an `evolve` builder.
+ *
+ * It is the same `on` as the top-level export, but with the state type `S`
+ * already bound. Because `S` is fixed before the evolver callbacks are
+ * checked, each callback receives `state: S` contextually — no `(s: S)`
+ * annotation, and a wrong return is still rejected against `S`.
+ */
+export type EvolverBuilder<S> = <P extends z.ZodType>(
+  descriptor: EventDescriptor<P>,
+  evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>,
+) => EvolverRegistration<S, P>
+
 /**
  * A state module — a self-contained definition of state sourced from events.
  *
@@ -72,14 +90,21 @@ export interface StateModule<
  * The state type is inferred from the `initial` function's return type —
  * no separate type definition needed.
  *
+ * Evolvers are registered through a builder: `evolve: (on) => [...]`, where
+ * `on` is bound to the state type. Because `S` is fixed by `initial` before
+ * the evolvers are checked, each callback receives `state: S` contextually —
+ * no `(s: S)` annotation, and a wrong return is still rejected against `S`.
+ * When `initial` under-specifies `S` (empty arrays, unions), annotate the one
+ * source of truth: `initial: (id): CourseState => (...)`.
+ *
  * ```typescript
  * const Course = state({
  *   name: "Course",
  *   id: { courseId: z.string() },
  *   initial: () => ({ created: false, name: "", capacity: 0 }),
  *   criteria: (id) => EventCriteria.havingTags({ courseId: id.courseId }),
- *   evolve: [
- *     on(CourseCreated, (s, event) => ({ ...s, created: true })),
+ *   evolve: (on) => [
+ *     on(CourseCreated, (s, { payload: event }) => ({ ...s, created: true })),
  *   ],
  * })
  * ```
@@ -89,16 +114,7 @@ export function state<IS extends IdSchema, S>(def: {
   id: IS
   initial: (id: InferIdFromSchema<IS>) => S
   criteria: (id: InferIdFromSchema<IS>) => EventCriteria
-  evolve: Array<EvolverRegistration<S, any>>
-  lifecycle?: StateLifecycle<InferIdFromSchema<IS>, S>
-}): StateModule<InferIdFromSchema<IS>, S>
-
-export function state<IS extends IdSchema, S>(def: {
-  name: string
-  id: IS
-  initial: (id: InferIdFromSchema<IS>) => S
-  criteria: (id: InferIdFromSchema<IS>) => EventCriteria
-  evolve: Array<EvolverRegistration<S, any>>
+  evolve: (on: EvolverBuilder<S>) => Array<EvolverRegistration<S, any>>
   lifecycle?: StateLifecycle<InferIdFromSchema<IS>, S>
 }): StateModule<InferIdFromSchema<IS>, S> {
   return {
@@ -107,7 +123,7 @@ export function state<IS extends IdSchema, S>(def: {
     idSchema: def.id,
     create: def.initial,
     criteria: def.criteria,
-    evolvers: def.evolve,
+    evolvers: def.evolve(on as unknown as EvolverBuilder<S>),
     lifecycle: def.lifecycle,
   }
 }