@kairos-es/codec 0.0.0

package/src/projection.ts

@@ -0,0 +1,163 @@
+/**
+ * The typed slice path (primary): a schema-backed projection and the fluent
+ * builder that produces it.
+ *
+ * A `SliceProjection<S, R>` is a core `AnyProjection<S>` (directly composable —
+ * its `evolve` folds a `DecodedEvent`) enriched with the `type -> Schema` map
+ * `decodeSlices` merges and decodes through. That map's value type carries `R`
+ * covariantly (`Schema<unknown, unknown, R>`), so the union of the defs'
+ * requirements flows to the decision model with no cast (and no phantom marker).
+ * Because `evolve` is already erased, a built slice drops straight into
+ * `composeProjections` — no `AnyProjection.of` ceremony.
+ *
+ * `projection(initialState).on(def, fold)...build()` infers the state `S` and
+ * the union `R` of the `.on`-ed defs' requirements, derives the read `Query`'s
+ * event-types from the defs' branded type literals (no `as EventType`), and
+ * hands each `fold` its decoded, typed payload. A handler for an un-imported
+ * event is therefore a compile error, and a mistyped type cannot silently match
+ * nothing.
+ */
+import {
+  type AnyProjection,
+  type DecodedEvent,
+  EventType,
+  type Query,
+  type Tag,
+} from '@kairos-es/core'
+import type { Schema } from 'effect'
+import type { EventDef } from './event'
+
+/**
+ * A schema-backed, directly-composable projection: an `AnyProjection<S>` plus
+ * the `type -> Schema` map for decode. The map's value type carries the union
+ * `R` of its defs' requirements covariantly, so `RequirementOf` recovers `R`
+ * (and the `out R` annotation keeps union-widening sound) with no phantom marker.
+ */
+export interface SliceProjection<out S = unknown, out R = unknown>
+  extends AnyProjection<S> {
+  readonly schemas: ReadonlyMap<string, Schema.Schema<unknown, unknown, R>>
+}
+
+/** The fluent builder: accumulate `.on(def, fold)` steps, then `.build()`. */
+export interface ProjectionBuilder<S, R = never> {
+  /**
+   * Fold events of `def`'s type: `fold` receives the decoded, typed `payload`.
+   * Adds `def`'s requirement `R2` to the accumulated `R`.
+   *
+   * Throws if this chain has already `.on`-ed that event type — see the guard in
+   * `projection` for why a repeat is always a mistake here, where across two
+   * slices it need not be.
+   */
+  on<A, I, R2>(
+    def: EventDef<A, I, R2>,
+    fold: (state: S, payload: A) => S,
+  ): ProjectionBuilder<S, R | R2>
+  /**
+   * Materialise the slice. The query is a single item over the `.on`-ed defs'
+   * types (branded via `EventType.make`) and `options.tags` (default none).
+   */
+  build(options?: { readonly tags?: ReadonlyArray<Tag> }): SliceProjection<S, R>
+}
+
+/**
+ * Start a slice for `initialState`. Returns a builder with no defs yet
+ * (`R = never`); each `.on(def, fold)` widens `R` by the def's requirement.
+ */
+export const projection = <S>(initialState: S): ProjectionBuilder<S, never> => {
+  // Persistent builder: `make` closes over the accumulated maps, and each
+  // `.on` copies them into a fresh builder rather than mutating in place, so
+  // no two derived builders ever share mutable state (reusing an intermediate
+  // builder can't cross-contaminate slices).
+  //
+  // `make` is generic in the accumulated requirement `R` — the parameter the
+  // builder is *about*. Pinning it to `never` and casting the result back would
+  // make the recursion typecheck by discarding the very thing each `.on` adds;
+  // threading `R` means the implementation states the same widening the
+  // `ProjectionBuilder` interface promises, and `on` returns without a cast.
+  const make = <R>(
+    schemas: ReadonlyMap<string, Schema.Schema<unknown, unknown, R>>,
+    folds: ReadonlyMap<string, (state: S, payload: unknown) => S>,
+  ): ProjectionBuilder<S, R> => ({
+    on: <A, I, R2>(
+      def: EventDef<A, I, R2>,
+      fold: (state: S, payload: A) => S,
+    ): ProjectionBuilder<S, R | R2> => {
+      // A repeated type WITHIN one chain is unambiguously a mistake, so this is
+      // a plain `has` rather than the reference-equality rule `mergeSliceSchemas`
+      // applies ACROSS slices. There, two entries for one type are the intended
+      // way to feed one event into two views, and the schemas being one object is
+      // what makes the collision harmless. Here there is only ever one fold per
+      // type — `evolve` dispatches by type into a single map — so a second `.on`
+      // cannot mean "as well as", only "instead of", and it silently discards
+      // the author's first fold along with its schema. The asymmetry is the
+      // point: the same `has` up there would outlaw the legitimate case.
+      if (schemas.has(def.type)) {
+        throw new Error(
+          `duplicate event type '${def.type}' in slice: .on was called twice ` +
+            'for it, and the second fold would silently replace the first. ' +
+            'Handle both cases in one fold.',
+        )
+      }
+      // The entry type is annotated `R | R2` rather than inferred, and that
+      // annotation is what carries the requirement forward — `build` reads `R`
+      // straight off this map, so `RequirementOf` ultimately reads it from here.
+      // Widening the copied `R` entries into it costs nothing: `Schema` is
+      // declared `<in out A, in out I, out R>` upstream, hence covariant in its
+      // requirement.
+      const nextSchemas = new Map<
+        string,
+        Schema.Schema<unknown, unknown, R | R2>
+      >(schemas)
+      // Erasing `A`/`I` is the one unavoidable cast, and `as unknown as` is what
+      // it takes: `Schema` is INVARIANT in both, so `Schema<A, I, R2>` and
+      // `Schema<unknown, unknown, R2>` are unrelated in either direction. It is
+      // sound because the payload is only ever read back through `evolve`, which
+      // re-narrows by event type via the matching `fold`. The target names `R2`
+      // and not `never` because `R2` is what the def actually requires — an
+      // `Encrypted` field's `CipherKey` is not nothing — so the cast erases only
+      // what it has to and states the rest truthfully.
+      nextSchemas.set(
+        def.type,
+        def.schema as unknown as Schema.Schema<unknown, unknown, R2>,
+      )
+      const nextFolds = new Map(folds)
+      // Contravariance in the payload parameter, so this one is a cast too: the
+      // map holds folds over `unknown`, and `evolve` supplies the payload the
+      // matching def decoded, which is the `A` this fold was written against.
+      nextFolds.set(def.type, fold as (state: S, payload: unknown) => S)
+      return make<R | R2>(nextSchemas, nextFolds)
+    },
+    build: (options) => {
+      // Internal-layer Query assembly from plain data (see core's Projection.ts
+      // note): a type-only-plus-optional-tags item the public surface withholds.
+      const types = [...schemas.keys()].map((t) => EventType.make(t))
+      const query: Query = {
+        items: [{ types, tags: options?.tags ?? [] }],
+      }
+      return {
+        initialState,
+        query,
+        // Defensive copy: hand out a fresh Map, not the builder's own. `schemas`
+        // is typed `ReadonlyMap`, but that is a compile-time guard only — a
+        // caller who casts it back to `Map` could otherwise mutate the slice's
+        // live decode table after `build`, desyncing it from `query` (whose
+        // event-types were snapshotted from these keys just above). The copy is
+        // cheap (a handful of keys) and makes the slice genuinely immutable.
+        schemas: new Map(schemas),
+        // Erased evolve: dispatch by the sequenced event's type to the matching
+        // fold over the decoded payload. Per the `AnyProjection.evolve` contract
+        // (core), a projection is only ever handed events matching its `query` —
+        // `composeProjections` gates each sub before dispatch — so this needs no
+        // second `matchesSequenced` check; the `fold === undefined` fallback is
+        // the honest total-function guard (evolve is typed over any DecodedEvent).
+        evolve: (state, decoded: DecodedEvent) => {
+          const fold = folds.get(decoded.sequenced.event.type)
+          return fold === undefined ? state : fold(state as S, decoded.payload)
+        },
+      }
+    },
+  })
+  // Explicit `never`: an empty `Map` literal gives inference nothing to read the
+  // requirement off, and "no defs yet" is exactly `never`, not `unknown`.
+  return make<never>(new Map(), new Map())
+}

package/src/registry.ts

@@ -0,0 +1,87 @@
+/**
+ * The general (registry) path (minimal): decode an arbitrary wire event by its
+ * runtime type string. This is the one place a type outside the known set
+ * surfaces as a typed `UnknownEventType` — the home of ADR-0005 decode-totality.
+ *
+ * `makeRegistry(defs)` builds a `type -> Schema` map with a construction-time
+ * uniqueness guard (a duplicate type throws at wiring, not at runtime). Its
+ * requirement `R` is the union of the defs' requirements. `decode` looks the
+ * type up, then runs `deserialiseThenDecode` over the bytes, yielding
+ * `{ type, payload: unknown }`. That `unknown` is the point of the path rather
+ * than a gap in it: the type is discovered at RUNTIME off the wire event, so the
+ * caller has named no def and the return is deliberately NOT a discriminated
+ * union over `Defs`. What this path owes its caller is decode TOTALITY — every
+ * known type decodes, an unknown one fails as `UnknownEventType` — and not typed
+ * access. A caller who wants a typed payload names the def it expects and takes
+ * the typed slice path (`projection(init).on(def, fold)`), where each fold
+ * receives its payload already decoded and narrowed.
+ *
+ * What is this path's OWN and what it merely shares. The lookup is its own: a
+ * miss here is `UnknownEventType`, where the same miss on the typed path is a
+ * `CodecError` about a schema the caller did not supply — the asymmetry ADR-0005
+ * exists for. Everything after the lookup is the two-step both paths perform, so
+ * it is `deserialiseThenDecode` that owns it and fixes the `deserialise` /
+ * `decode` `reason` strings; this module holding a second copy is exactly how one
+ * of them would come to be reworded on one path only.
+ */
+import type { DcbEvent } from '@kairos-es/core'
+import { Effect, type Schema } from 'effect'
+import { deserialiseThenDecode } from './deserialiseThenDecode'
+import { type CodecError, UnknownEventType } from './errors'
+import type { EventDef, EventDefAny } from './event'
+import { Serializer } from './Serializer'
+
+/** A registry decoding arbitrary wire events; `R` is the union of def requirements. */
+export interface Registry<R> {
+  readonly decode: (
+    event: DcbEvent,
+  ) => Effect.Effect<
+    { readonly type: string; readonly payload: unknown },
+    UnknownEventType | CodecError,
+    Serializer | R
+  >
+}
+
+/**
+ * Build a `Registry` from a def barrel. Throws at construction on a duplicate
+ * type; `R` is the union of the defs' requirements.
+ */
+type RequirementOfDefs<Defs extends ReadonlyArray<EventDefAny>> =
+  // biome-ignore lint/suspicious/noExplicitAny: match the heterogeneous EventDefAny bound to infer the union of requirements R; A/I are irrelevant here.
+  Defs[number] extends EventDef<any, any, infer R> ? R : never
+
+export const makeRegistry = <Defs extends ReadonlyArray<EventDefAny>>(
+  defs: Defs,
+): Registry<RequirementOfDefs<Defs>> => {
+  const map = new Map<string, Schema.Schema<unknown, unknown, unknown>>()
+  for (const def of defs) {
+    if (map.has(def.type)) {
+      throw new Error(`duplicate event type '${def.type}' in registry`)
+    }
+    map.set(def.type, def.schema)
+  }
+  return {
+    decode: (event) =>
+      Effect.gen(function* () {
+        const schema = map.get(event.type)
+        if (schema === undefined) {
+          return yield* Effect.fail(new UnknownEventType({ type: event.type }))
+        }
+        const serializer = yield* Serializer
+        const payload = yield* deserialiseThenDecode(
+          serializer,
+          schema,
+          event.data,
+        )
+        return { type: event.type, payload }
+        // The schema map erases `R` to `unknown`; the declared `R` is recovered
+        // from `Defs` at the type level, so the gen block's inferred requirement
+        // (`unknown`) is re-stated as `Serializer | R` here, which is this
+        // module's only cast.
+      }) as Effect.Effect<
+        { readonly type: string; readonly payload: unknown },
+        UnknownEventType | CodecError,
+        Serializer | RequirementOfDefs<Defs>
+      >,
+  }
+}

package/src/toEvent.ts

@@ -0,0 +1,63 @@
+/**
+ * Event production (codec edge-helper): turn a typed payload into a wire
+ * `DcbEvent`. Encode is `Schema.encode(def.schema)` (a `ParseError` becomes a
+ * `CodecError`; any encryption transform runs here, *before* serialisation)
+ * then `serialiser.serialise`. The wire `tags` are derived from the def's
+ * required `tagsFor` mapper (ADR-0006) — they are never hand-passed, so two
+ * command sites emitting the same event type cannot tag it differently. A mapper
+ * that throws (e.g. an ill-formed `key:value` rejected by `Tag.make`) is
+ * surfaced on the `CodecError` channel, not as a defect. `uuid`
+ * comes from `options.uuid` or the `Uuid` service; `occurredAt` from
+ * `options.occurredAt` or the Effect clock (`DateTime.now`), keeping `core`
+ * clock- and RNG-free while staying overridable for backdated imports.
+ */
+import type { DcbEvent } from '@kairos-es/core'
+import { DateTime, Effect, Schema } from 'effect'
+import { CodecError } from './errors'
+import type { EventDef } from './event'
+import { Serializer } from './Serializer'
+import { Uuid } from './Uuid'
+
+/**
+ * Encode `payload` under `def` and stamp it into a wire `DcbEvent`, deriving its
+ * `tags` from `def.tagsFor(payload)` (a throwing mapper surfaces as a
+ * `CodecError`, not a defect). The tags are stamped exactly as the mapper
+ * returns them — no dedup or reordering. `type` and `tags` are cleartext
+ * wire-envelope fields (the query surface), so a `tagsFor` mapper may only key
+ * off cleartext payload fields (ADR-0006). `uuid` / `occurredAt` are
+ * exact-optional overrides; absent, they come from the `Uuid` service and the
+ * Effect clock.
+ */
+export const toEvent = <A, I, R>(
+  def: EventDef<A, I, R>,
+  payload: A,
+  options?: {
+    readonly uuid?: string
+    readonly occurredAt?: DateTime.Utc
+  },
+): Effect.Effect<DcbEvent, CodecError, Serializer | Uuid | R> =>
+  Effect.gen(function* () {
+    // Derive tags first. A mapper is app code that can throw (e.g. `Tag.make`
+    // rejects an ill-formed `key:value`), and the codec's contract is that such
+    // failures are values on the `CodecError` channel, never defects (errors.ts).
+    // Deriving before the uuid/clock effects also means a bad tag fails without
+    // consuming the `Uuid` sequence.
+    const tags = yield* Effect.try({
+      try: () => def.tagsFor(payload),
+      catch: (cause) => new CodecError({ reason: 'tags', cause }),
+    })
+    const serializer = yield* Serializer
+    const encoded = yield* Schema.encode(def.schema)(payload).pipe(
+      Effect.mapError((cause) => new CodecError({ reason: 'encode', cause })),
+    )
+    const data = serializer.serialise(encoded)
+    const uuid = options?.uuid ?? (yield* (yield* Uuid).generate)
+    const occurredAt = options?.occurredAt ?? (yield* DateTime.now)
+    return {
+      type: def.type,
+      data,
+      tags,
+      uuid,
+      occurredAt,
+    }
+  })