@sekiban/dcb-domain 0.1.0

package/dist/state.js

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import { DomainAuthoringError, DomainRegistrationError, } from "./types";
+const projectorFamilyInvariant = Symbol("projector-family-invariant");
+export function stateUnion(schema, options) {
+    const discriminator = options.discriminator ?? "kind";
+    return Object.freeze({
+        kind: "state-union",
+        discriminator,
+        schema,
+        parse: (value) => schema.parse(value),
+        initial: options.initial,
+    });
+}
+export const state = stateUnion;
+export function states(variants, options) {
+    const discriminator = options.discriminator ?? "kind";
+    // Keep the discriminator visible to Zod as well as to the authoring type.
+    // The cast is limited to the public variadic tuple surface; callers are
+    // expected to provide object variants carrying the selected discriminator.
+    const schema = z.discriminatedUnion(discriminator, variants);
+    return stateUnion(schema, { discriminator, initial: options.initial });
+}
+export function validationReject(rejectKind, reason, details) {
+    return Object.freeze({ kind: "reject", rejectKind, reason, ...(details === undefined ? {} : { details }) });
+}
+export function validate(fn) {
+    return fn;
+}
+export function evolve(fn) {
+    return fn;
+}
+export function decider(module) {
+    return Object.freeze({ validate: module.validate, evolve: module.evolve });
+}
+function initialStateOf(value) {
+    if (value === undefined)
+        throw new DomainAuthoringError("PROJECTOR_INITIAL_STATE_REQUIRED", "Projector initial state is required");
+    return typeof value === "function" ? value() : value;
+}
+function eventNameFromType(eventType) {
+    if (eventType.length === 0 || eventType.includes(":")) {
+        throw new DomainAuthoringError("CANONICAL_EVENT_IDENTITY_INVALID", `Event type ${eventType} is not an event payload name`);
+    }
+    return eventType;
+}
+export function projector(options) {
+    if (options.id.length === 0)
+        throw new DomainAuthoringError("PROJECTOR_ID_REQUIRED", "Projector id is required");
+    const events = options.events ?? options.source?.events ?? [];
+    const eventTypes = Object.freeze(events.map((definition) => definition.eventType));
+    const handlers = options.handlers;
+    for (const eventType of eventTypes) {
+        if (handlers[eventType] === undefined && handlers[eventNameFromType(eventType)] === undefined) {
+            throw new DomainRegistrationError(`Projector ${options.id} is missing handler for ${eventType}`, [eventType]);
+        }
+    }
+    const version = options.version ?? 1;
+    if (!Number.isSafeInteger(version) || version < 1)
+        throw new DomainAuthoringError("PROJECTOR_VERSION_INVALID", "Projector version must be positive");
+    const initialState = options.initialState ?? options.initial;
+    const validateState = options.state === undefined
+        ? (value) => value
+        : (value) => options.state.parse(value);
+    const serializeState = options.serializeState ?? ((state) => JSON.stringify(state));
+    const deserializeState = options.deserializeState ?? ((serialized) => JSON.parse(serialized));
+    const initial = initialStateOf(initialState);
+    const byType = new Map(events.map((definition) => [definition.eventType, definition]));
+    const apply = (state, event) => {
+        const definition = byType.get(event.eventType);
+        if (definition === undefined) {
+            throw new DomainAuthoringError("EVENT_TYPE_UNREGISTERED", `Projector ${options.id} does not subscribe to ${event.eventType}`);
+        }
+        if (!event.tags.some((tag) => tag.family === options.tag.family))
+            return state;
+        const payload = definition.make(event.payload);
+        const handler = handlers[definition.eventType] ?? handlers[definition.name];
+        if (handler === undefined)
+            throw new DomainRegistrationError(`Projector ${options.id} has no handler for ${definition.eventType}`, [definition.eventType]);
+        const next = handler(state, {
+            definition,
+            eventType: definition.eventType,
+            payload,
+            tags: event.tags,
+        });
+        return validateState(next);
+    };
+    const subscribes = (eventType) => byType.has(eventType);
+    return Object.freeze({
+        id: options.id,
+        version,
+        tag: options.tag,
+        [projectorFamilyInvariant]: (value) => value,
+        events,
+        eventTypes,
+        initialState: initial,
+        handlers,
+        subscribes,
+        apply,
+        reduce: apply,
+        validateState,
+        serializeState,
+        deserializeState,
+    });
+}
+export function projectorInitialState(definition) {
+    return typeof definition.initialState === "function"
+        ? definition.initialState()
+        : definition.initialState;
+}
+export function projectorFamily(definition) {
+    return definition.tag;
+}

package/dist/testing.d.ts

@@ -0,0 +1,32 @@
+import type { EventRecord, FixedNow, JsonValue, Tag } from "./types.js";
+import type { CommandDefinition } from "./command.js";
+import type { EventDefinition } from "./event.js";
+import type { ProjectorDefinition } from "./state.js";
+export interface TestingEvent extends EventRecord {
+    readonly payload: JsonValue;
+}
+export interface Expectation {
+    readonly kind: "done" | "none" | "reject" | "accepted" | "discarded" | "rejected";
+    readonly code?: string;
+}
+export interface GivenWhen {
+    readonly expect: (expectation: Expectation | Expectation["kind"]) => Promise<unknown>;
+}
+export interface GivenBuilder {
+    readonly when: (command: CommandDefinition, input: unknown) => GivenWhen;
+}
+export declare function given<State, Family extends string, Events extends readonly EventDefinition[]>(projector: ProjectorDefinition<State, Family, Events>, events?: readonly TestingEvent[], options?: {
+    readonly now?: FixedNow;
+    readonly tag?: Tag;
+}): GivenBuilder;
+export interface EvolveTableCase<State> {
+    readonly name: string;
+    readonly state: State;
+    readonly event: TestingEvent;
+    readonly expected: State;
+}
+export declare function evolveTable<State, Family extends string, Events extends readonly EventDefinition[]>(projector: ProjectorDefinition<State, Family, Events>, cases: readonly EvolveTableCase<NoInfer<State>>[]): readonly {
+    readonly name: string;
+    readonly state: State;
+}[];
+export declare const evolve: typeof evolveTable;

package/dist/testing.js

@@ -0,0 +1,416 @@
+// src/types.ts
+var DomainAuthoringError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "DomainAuthoringError";
+    this.code = code;
+  }
+};
+function tagFamily(family) {
+  if (family.length === 0) throw new DomainAuthoringError("TAG_FAMILY_INVALID", "Tag family must not be empty");
+  const make = (value) => {
+    if (value.length === 0) throw new DomainAuthoringError("TAG_VALUE_INVALID", "Tag value must not be empty");
+    const id = `${family}:${value}`;
+    return Object.freeze({
+      family,
+      group: family,
+      value,
+      content: value,
+      id,
+      tag: id
+    });
+  };
+  return Object.freeze({ family, group: family, of: make, create: make });
+}
+function normalizeTag(input) {
+  if (typeof input === "string") {
+    const separator = input.indexOf(":");
+    if (separator <= 0 || separator === input.length - 1) {
+      throw new DomainAuthoringError("TAG_INVALID", "A tag string must be family:value");
+    }
+    return tagFamily(input.slice(0, separator)).of(input.slice(separator + 1));
+  }
+  if (input.id.length === 0 || input.family.length === 0 || input.value.length === 0) {
+    throw new DomainAuthoringError("TAG_INVALID", "Tag family, value, and id are required");
+  }
+  return input;
+}
+var V1_REJECT_ERROR_CODES = Object.freeze({
+  validation: "validation_error",
+  "not-found": "not_found",
+  conflict: "consistency_conflict",
+  forbidden: "forbidden",
+  "invalid-state": "invalid_state",
+  internal: "internal_error"
+});
+
+// src/command.ts
+function none(reason) {
+  return Object.freeze({ kind: "none", ...reason === void 0 ? {} : { reason } });
+}
+
+// src/session.ts
+var SessionStateError = class extends DomainAuthoringError {
+  constructor(message) {
+    super("SESSION_STATE_INVALID", message);
+    this.name = "SessionStateError";
+  }
+};
+var UndeclaredReadError = class extends DomainAuthoringError {
+  projectorId;
+  tag;
+  constructor(projectorId, tag) {
+    super("UNDECLARED_DYNAMIC_READ", `Read of ${projectorId ?? "exists"}/${tag.id} was not declared`);
+    this.name = "UndeclaredReadError";
+    this.projectorId = projectorId;
+    this.tag = tag;
+  }
+};
+var IncoherentSnapshotError = class extends DomainAuthoringError {
+  constructor(tag, firstHead, secondHead) {
+    super("INCOHERENT_SNAPSHOT", `Tag ${tag.id} was supplied with heads ${firstHead ?? "null"} and ${secondHead ?? "null"}`);
+    this.name = "IncoherentSnapshotError";
+  }
+};
+function cellKey(projector, tag) {
+  return `${projector.id}\0${tag.id}`;
+}
+function initialState(projector) {
+  return typeof projector.initialState === "function" ? projector.initialState() : projector.initialState;
+}
+function eventEligible(projector, cellTag, event) {
+  return event.tags.some((tag) => tag.id === cellTag.id && tag.family === projector.tag.family) && projector.subscribes(event.eventType);
+}
+function asRecord(event) {
+  return Object.freeze({
+    eventType: event.eventType,
+    eventName: event.event.eventPayloadName,
+    payload: event.payload,
+    tags: Object.freeze([...event.tags]),
+    ordinal: event.ordinal
+  });
+}
+var Session = class {
+  now;
+  statusValue = "OPEN";
+  readSet;
+  snapshots;
+  onPropagation;
+  snapshotByCell = /* @__PURE__ */ new Map();
+  overlayByCell = /* @__PURE__ */ new Map();
+  headByTag = /* @__PURE__ */ new Map();
+  claimsByKey = /* @__PURE__ */ new Map();
+  staged = [];
+  observations = [];
+  constructor(options) {
+    this.now = options.now;
+    this.readSet = options.readSet;
+    this.snapshots = options.snapshots;
+    this.onPropagation = options.onPropagation;
+  }
+  get status() {
+    return this.statusValue;
+  }
+  get stagedEvents() {
+    return Object.freeze([...this.staged]);
+  }
+  get propagation() {
+    return Object.freeze([...this.observations]);
+  }
+  get readClaims() {
+    return Object.freeze([...this.claimsByKey.values()]);
+  }
+  observe(observation) {
+    const frozen = Object.freeze({ ...observation, tags: Object.freeze([...observation.tags]) });
+    this.observations.push(frozen);
+    this.onPropagation?.(frozen);
+  }
+  assertOpen() {
+    if (this.statusValue !== "OPEN") throw new SessionStateError(`Session is ${this.statusValue}`);
+  }
+  assertDeclared(kind, projectorId, tag) {
+    if (!this.readSet.has(kind, projectorId, tag)) throw new UndeclaredReadError(projectorId, tag);
+  }
+  rememberClaim(declaration, head) {
+    const key = `${declaration.kind}\0${declaration.projectorId ?? ""}\0${declaration.tag.id}`;
+    this.claimsByKey.set(key, Object.freeze({
+      kind: declaration.kind,
+      ...declaration.projectorId === void 0 ? {} : { projectorId: declaration.projectorId },
+      tag: declaration.tag,
+      head
+    }));
+  }
+  async loadSnapshot(projector, tag) {
+    const key = cellKey(projector, tag);
+    const cached = this.snapshotByCell.get(key);
+    if (cached !== void 0) return cached;
+    const supplied = this.snapshots === void 0 ? { projectorId: projector.id, tag, head: null, state: initialState(projector), exists: false } : await this.snapshots.read(projector, tag);
+    const suppliedTag = normalizeTag(supplied.tag);
+    if (suppliedTag.id !== tag.id || supplied.projectorId !== projector.id) {
+      throw new DomainAuthoringError("SNAPSHOT_IDENTITY_INVALID", `Snapshot identity did not match ${projector.id}/${tag.id}`);
+    }
+    const suppliedHead = supplied.head ?? "";
+    const existingHead = this.headByTag.get(tag.id);
+    if (existingHead !== void 0 && existingHead !== suppliedHead) {
+      throw new IncoherentSnapshotError(tag, existingHead, suppliedHead);
+    }
+    this.headByTag.set(tag.id, suppliedHead);
+    this.snapshotByCell.set(key, supplied);
+    return supplied;
+  }
+  async stateFor(projector, tag) {
+    this.assertOpen();
+    this.assertDeclared("state", projector.id, tag);
+    this.attachProjector(projector);
+    const key = cellKey(projector, tag);
+    const overlay = this.overlayByCell.get(key);
+    if (overlay !== void 0) return overlay;
+    const snapshot = await this.loadSnapshot(projector, tag);
+    let state = snapshot.state;
+    for (const staged of this.staged) {
+      const record = asRecord(staged);
+      if (!eventEligible(projector, tag, record)) continue;
+      state = projector.apply(state, record);
+      this.observe({ point: "eligible-cells", eventType: record.eventType, tags: record.tags });
+    }
+    this.overlayByCell.set(key, state);
+    this.rememberClaim({ kind: "state", projectorId: projector.id, tag }, snapshot.head ?? "");
+    return state;
+  }
+  async existsFor(tag) {
+    this.assertOpen();
+    this.assertDeclared("exists", void 0, tag);
+    const snapshotExists = this.snapshots?.exists === void 0 ? void 0 : await this.snapshots.exists(tag);
+    const stagedExists = this.staged.some((event) => event.tags.some((candidate) => candidate.id === tag.id));
+    const result = (snapshotExists ?? this.snapshotByCellHasTag(tag)) || stagedExists;
+    let head = this.headByTag.get(tag.id);
+    if (snapshotExists === false) {
+      head = "";
+      this.headByTag.set(tag.id, head);
+    } else if (snapshotExists === true && this.snapshots?.head !== void 0) {
+      head = await this.snapshots.head(tag);
+      this.headByTag.set(tag.id, head);
+    }
+    this.rememberClaim({ kind: "exists", tag }, head ?? null);
+    return result;
+  }
+  snapshotByCellHasTag(tag) {
+    return [...this.snapshotByCell.values()].some((snapshot) => snapshot.tag.id === tag.id && snapshot.exists);
+  }
+  async preload() {
+    this.assertOpen();
+    for (const declaration of this.readSet.claims) {
+      if (declaration.kind === "state") {
+        const projector = this.findProjector(declaration.projectorId);
+        await this.stateFor(projector, declaration.tag);
+      } else {
+        await this.existsFor(declaration.tag);
+      }
+    }
+  }
+  findProjector(projectorId) {
+    if (projectorId === void 0) throw new DomainAuthoringError("PROJECTOR_ID_REQUIRED", "A state read requires a projector");
+    const declaration = this.readSet.claims.find((claim) => claim.projectorId === projectorId && claim.projector !== void 0);
+    if (declaration?.projector !== void 0) return declaration.projector;
+    throw new DomainAuthoringError("PROJECTOR_NOT_IN_READ_SET", `Projector ${projectorId} was not attached to this session`);
+  }
+  readSetProjectors = /* @__PURE__ */ new Map();
+  attachProjector(projector) {
+    this.readSetProjectors.set(projector.id, {
+      id: projector.id,
+      tag: projector.tag,
+      subscribes: projector.subscribes,
+      apply: (state, event) => projector.apply(state, event)
+    });
+  }
+  attachProjectors(projectors) {
+    for (const projector of projectors) this.attachProjector(projector);
+  }
+  context(projectors = []) {
+    this.attachProjectors(projectors);
+    return Object.freeze({
+      state: (projector, tag) => this.stateFor(projector, tag),
+      exists: (tag) => this.existsFor(tag),
+      now: () => this.now,
+      append: (event, payload) => this.append(event, payload)
+    });
+  }
+  append(event, payload) {
+    this.assertOpen();
+    const parsed = event.make(payload);
+    const derivedTags = event.tags(parsed).map(normalizeTag);
+    const ordinal = String(this.staged.length);
+    const staged = Object.freeze({
+      event,
+      eventType: event.eventType,
+      payload: parsed,
+      tags: Object.freeze(derivedTags),
+      ordinal
+    });
+    this.staged.push(staged);
+    this.observe({ point: "staged-log", eventType: event.eventType, tags: derivedTags });
+    const record = asRecord(staged);
+    for (const [key, snapshot] of this.snapshotByCell) {
+      const separator = key.indexOf("\0");
+      const projectorId = key.slice(0, separator);
+      const tagId = key.slice(separator + 1);
+      if (!record.tags.some((tag) => tag.id === tagId)) continue;
+      const projector = this.readSetProjectors.get(projectorId);
+      if (projector === void 0 || !eventEligible(projector, snapshot.tag, record)) continue;
+      const previous = this.overlayByCell.get(key) ?? snapshot.state;
+      const next = projector.apply(previous, record);
+      this.overlayByCell.set(key, next);
+      this.observe({ point: "eligible-cells", eventType: event.eventType, tags: record.tags });
+    }
+  }
+  candidateTags() {
+    const tags = /* @__PURE__ */ new Map();
+    for (const event of this.staged) for (const tag of event.tags) tags.set(tag.id, tag);
+    for (const tag of this.readSet.tags) tags.set(tag.id, tag);
+    return Object.freeze([...tags.values()]);
+  }
+  seal(decision) {
+    this.assertOpen();
+    const tags = this.candidateTags();
+    this.observe({ point: "claim-candidate-preflight", tags });
+    const envelope = Object.freeze({
+      kind: "candidate-envelope",
+      now: this.now,
+      events: Object.freeze(this.staged.map(asRecord)),
+      tags,
+      readClaims: this.readClaims,
+      decision
+    });
+    this.observe({ point: "sealed-envelope", tags });
+    this.statusValue = "SEALED";
+    return envelope;
+  }
+  discard(reason = "discarded") {
+    this.assertOpen();
+    this.staged.splice(0, this.staged.length);
+    this.overlayByCell.clear();
+    this.statusValue = "DISCARDED";
+    return reason.length === 0 ? none() : none(reason);
+  }
+  finish(decision) {
+    if (decision.kind === "done") return this.seal(decision);
+    this.discard(decision.kind === "none" ? decision.reason ?? "none" : decision.reason);
+    return void 0;
+  }
+  decisionLog(decision) {
+    return Object.freeze({
+      now: this.now,
+      events: Object.freeze(this.staged.map(asRecord)),
+      readClaims: this.readClaims,
+      terminal: decision
+    });
+  }
+};
+function classifyCommitResult(value) {
+  if (value === void 0 || value === true) return { kind: "accepted" };
+  if (typeof value !== "object" || value === null) return { kind: "accepted" };
+  const record = value;
+  if (record.kind === "consistency-conflict" || record.kind === "conflict" || record.code === "consistency_conflict") {
+    return { kind: "consistency-conflict" };
+  }
+  if (record.kind === "unknown" || record.kind === "timeout" || record.code === "unknown_outcome") {
+    return { kind: "unknown", error: value };
+  }
+  if (record.kind === "rejected" || record.kind === "invalid") return { kind: "rejected", error: value };
+  return { kind: "accepted" };
+}
+async function executeCommand(command, input, options = {}) {
+  const fixedNow = options.timeProvider?.now() ?? 0;
+  const maxRetries = Math.max(0, Math.floor(options.maxConflictRetries ?? 1));
+  const parsed = command.parseInput(input);
+  let attempts = 0;
+  for (; ; ) {
+    attempts += 1;
+    const readSet = command.reads(parsed);
+    const session = new Session({
+      now: fixedNow,
+      readSet,
+      snapshots: options.snapshots,
+      onPropagation: options.onPropagation
+    });
+    try {
+      await session.preload();
+      const context = session.context([]);
+      const decision = await command.handle(parsed, context);
+      const envelope = session.finish(decision);
+      const log = session.decisionLog(decision);
+      if (envelope === void 0) {
+        return Object.freeze({ status: decision.kind === "reject" ? "rejected" : "discarded", attempts, now: fixedNow, decision, log, session });
+      }
+      if (options.commit === void 0) {
+        return Object.freeze({ status: "accepted", attempts, now: fixedNow, decision, envelope, log, session });
+      }
+      const commitResult = classifyCommitResult(await options.commit(envelope));
+      if (commitResult.kind === "consistency-conflict" && attempts <= maxRetries) continue;
+      if (commitResult.kind === "unknown") return Object.freeze({ status: "unknown", attempts, now: fixedNow, decision, envelope, log, session, error: commitResult.error });
+      if (commitResult.kind === "rejected") return Object.freeze({ status: "rejected", attempts, now: fixedNow, decision, envelope, log, session, error: commitResult.error });
+      return Object.freeze({ status: "accepted", attempts, now: fixedNow, decision, envelope, log, session });
+    } catch (error) {
+      if (session.status === "OPEN") session.discard("throw");
+      throw error;
+    }
+  }
+}
+
+// src/testing.ts
+function stateFor(projector, events) {
+  let state = typeof projector.initialState === "function" ? projector.initialState() : projector.initialState;
+  for (const event of events) state = projector.apply(state, event);
+  return state;
+}
+function expectationMatches(result, expectation) {
+  const expected = typeof expectation === "string" ? { kind: expectation } : expectation;
+  if (expected.kind === "done") return result.decision.kind === "done";
+  if (expected.kind === "none") return result.decision.kind === "none";
+  if (expected.kind === "reject") return result.decision.kind === "reject" && (expected.code === void 0 || result.decision.code === expected.code);
+  if (expected.kind === "accepted") return result.status === "accepted";
+  if (expected.kind === "discarded") return result.status === "discarded";
+  return result.status === "rejected";
+}
+function given(projector, events = [], options = {}) {
+  const tag = options.tag ?? projector.tag.of("test");
+  const state = stateFor(projector, events);
+  return {
+    when: (command, input) => ({
+      expect: async (expectation) => {
+        const result = await executeCommand(command, input, {
+          timeProvider: { now: () => options.now ?? 0 },
+          snapshots: {
+            read: (requestedProjector, requestedTag) => ({
+              projectorId: requestedProjector.id,
+              tag: requestedTag,
+              head: "test-head",
+              state: requestedProjector.id === projector.id && requestedTag.id === tag.id ? state : requestedProjector.initialState,
+              exists: events.length > 0
+            })
+          }
+        });
+        if (!expectationMatches(result, expectation)) {
+          throw new Error(`Expected ${typeof expectation === "string" ? expectation : expectation.kind}, received ${result.decision.kind}/${result.status}`);
+        }
+        return result;
+      }
+    })
+  };
+}
+function evolveTable(projector, cases) {
+  return Object.freeze(cases.map((testCase) => {
+    const actual = projector.apply(testCase.state, testCase.event);
+    if (JSON.stringify(actual) !== JSON.stringify(testCase.expected)) {
+      throw new Error(`Evolve table case ${testCase.name} failed`);
+    }
+    return Object.freeze({ name: testCase.name, state: actual });
+  }));
+}
+var evolve = evolveTable;
+export {
+  evolve,
+  evolveTable,
+  given
+};