experimental-a2 0.3.0 → 0.5.0

package/src/contract.ts

@@ -0,0 +1,206 @@
+/**
+ * The contract — a2's primary noun. A named event vocabulary, shared by
+ * everything: the server implements it (experimental-a2/server's `createServer`),
+ * reducers derive from it (`contract.reducer`), the browser types its
+ * pushes off it. Isomorphic by construction: this module imports
+ * nothing but schema plumbing.
+ *
+ * The contract says what can be *said*; the server says how it's
+ * *reacted to*; a reducer says how it's *seen*.
+ */
+
+import { makeReducerBuilder, type ReducerBuilder } from './reducer.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+import { assertSyncSchema } from './validate.ts'
+
+/** The event vocabulary shape: event name → payload schema. */
+export type EventDefs = Record<string, StandardSchemaV1>
+
+/** The presence vocabulary shape: field name → value schema. */
+export type PresenceDefs = Record<string, StandardSchemaV1>
+
+/** One event of a contract, narrowed to type `K`. */
+export type ContractEvent<
+  D extends EventDefs,
+  K extends keyof D & string = keyof D & string,
+> = {
+  [T in keyof D & string]: {
+    id: string
+    type: T
+    payload: StandardSchemaV1.InferOutput<D[T]>
+    index: number
+    sessionId: string
+    createdAt: Date
+  }
+}[K]
+
+/** Input to `append`/`push`, typed against the contract's schemas. */
+export type AppendInput<D extends EventDefs> = {
+  [T in keyof D & string]: {
+    type: T
+    payload: StandardSchemaV1.InferInput<D[T]>
+    id?: string
+  }
+}[keyof D & string]
+
+export type EventBatchFactory<D extends EventDefs> = <
+  const E extends readonly AppendInput<D>[],
+>(
+  ...events: E
+) => E
+
+/**
+ * One presence update: a participant's changed fields (`null` marks a
+ * cleared one), stamped with the sender's stream frontier (`seen`).
+ * This is what `stream({ presence: true })` interleaves with events.
+ */
+export type PresencePatch<P extends PresenceDefs = PresenceDefs> = {
+  participant: string
+  values: {
+    [F in keyof P & string]?: StandardSchemaV1.InferOutput<P[F]> | null
+  }
+  seen: number
+  at: Date
+}
+
+/**
+ * The replicated ephemeral map: participant → field → latest value,
+ * last-writer-wins per field. Never stored in the log; how long a
+ * value stays painted is view logic, decided at render time against
+ * `at`.
+ */
+export type PresenceMap<P extends PresenceDefs = PresenceDefs> = {
+  [participant: string]: {
+    [F in keyof P & string]?: {
+      value: StandardSchemaV1.InferOutput<P[F]>
+      seen: number
+      at: Date
+    }
+  }
+}
+
+/**
+ * The one item a presence stream yields before live patches: the
+ * current pruned map, per-field stamps exact. Discriminate
+ * structurally (`'snapshot' in item`).
+ */
+export type PresenceSnapshot<P extends PresenceDefs = PresenceDefs> = {
+  snapshot: PresenceMap<P>
+}
+
+/**
+ * Intersect into a surface type to add `Members` only when the
+ * contract declares presence fields — on presence-less contracts the
+ * members do not exist, a type error rather than a runtime throw.
+ */
+export type WithPresence<
+  P extends PresenceDefs,
+  Members,
+> = keyof P extends never ? unknown : Members
+
+export type ReducerOptions<Seed, S> = {
+  /**
+   * Identity and snapshot cache key. Rename it when the fold's logic
+   * changes — snapshots under the old name are ignored and refolded.
+   */
+  name: string
+  /**
+   * The seed the fold starts from. With a `stateSchema`, it's typed as
+   * the schema's *input*: validated at definition, and the validated
+   * output (defaults applied) is what the fold actually starts from.
+   */
+  initialState: Seed
+  /**
+   * Optional: declares the state's shape (the fold's state type becomes
+   * the schema's output) and guards cached folds — server snapshots and
+   * the browser cache reject mismatching shapes and refold.
+   */
+  stateSchema?: StandardSchemaV1<Seed, S>
+}
+
+export type Contract<
+  D extends EventDefs = EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  /** Identity — prefixes storage keys and queue messages. */
+  readonly name: string
+  /** The vocabulary. */
+  readonly events: Readonly<D>
+  /** The presence vocabulary — empty unless declared. */
+  readonly presence: Readonly<P>
+  /** Preserve literal types for a handler-returned event batch. */
+  readonly batch: EventBatchFactory<D>
+  /**
+   * Derive a view from this contract. The reducer's `name` is its
+   * identity and snapshot cache key: rename it when the fold's logic
+   * changes. Two steps by design: this call fixes the state and event
+   * types, so `.fold()` receives fully concrete types — literal unions
+   * in your state survive, with zero annotations. (A single call can't
+   * do this: TypeScript never contextually types the returns of a
+   * context-sensitive argument against generics inferred in the same
+   * call.)
+   */
+  reducer<Seed, S = Seed>(
+    options: ReducerOptions<Seed, S>,
+  ): ReducerBuilder<D, S, P>
+}
+
+/**
+ * Define a contract: a name plus the events it understands. Validators
+ * must be synchronous — async ones are rejected here, at definition
+ * time. The result is a plain, importable, isomorphic value.
+ */
+export function contract<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+>(options: {
+  /** Identity — prefixes storage keys and queue messages. */
+  name: string
+  /** The vocabulary: event name → payload schema (Standard Schema). */
+  events: D
+  /**
+   * Optional second vocabulary: presence field → value schema.
+   * Per-participant ephemeral state, replicated last-writer-wins and
+   * never stored in the log — reducers cannot see it.
+   */
+  presence?: P
+}): Contract<D, P> {
+  const { name } = options
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('contract name must be a non-empty string')
+  }
+  if (name.includes('\u001f')) {
+    throw new TypeError('contract name contains a reserved control character')
+  }
+  const defs = options.events
+  for (const [type, schema] of Object.entries(defs)) {
+    if (typeof schema?.['~standard']?.validate !== 'function') {
+      throw new TypeError(
+        `contract '${name}': the value for '${type}' is not a Standard Schema (expected an object with '~standard')`,
+      )
+    }
+    assertSyncSchema(schema, `event '${type}'`)
+  }
+  const events = Object.freeze({ ...defs })
+
+  const presenceDefs = options.presence ?? ({} as P)
+  for (const [field, schema] of Object.entries(presenceDefs)) {
+    if (typeof schema?.['~standard']?.validate !== 'function') {
+      throw new TypeError(
+        `contract '${name}': the value for presence field '${field}' is not a Standard Schema (expected an object with '~standard')`,
+      )
+    }
+    assertSyncSchema(schema, `presence field '${field}'`)
+  }
+  const presence = Object.freeze({ ...presenceDefs })
+
+  return {
+    name,
+    events,
+    presence,
+    batch: (...items) => items,
+    reducer(reducerOptions) {
+      return makeReducerBuilder(events, presence, reducerOptions)
+    },
+  }
+}

package/src/deterministic-id.ts

@@ -0,0 +1,72 @@
+/**
+ * Deterministic default ids for handler `session.append` calls. A handler
+ * re-run after a crash calls `session.append` again; giving
+ * each call a deterministic id — derived from the triggering event's id
+ * and the caller's stable name — makes the re-run a no-op via the store's
+ * unique index on event ids.
+ *
+ * The id is a UUIDv5-shaped SHA-1 over
+ * `(namespace, triggerEventId, name, itemOrdinal)`, computed with
+ * WebCrypto so it runs on any platform a2 core targets.
+ */
+
+const APPEND_NAMESPACE = 'a2:handler-append:v2'
+const RETURN_NAMESPACE = 'a2:handler-return:v1'
+const SCHEDULE_NAMESPACE = 'a2:schedule:v1'
+const SCHEDULED_EVENT_NAMESPACE = 'a2:scheduled-event:v1'
+
+async function deterministicIdFromInput(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-1',
+    new TextEncoder().encode(input),
+  )
+  const bytes = new Uint8Array(digest).slice(0, 16)
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+async function deterministicId(parts: Array<string | number>): Promise<string> {
+  return deterministicIdFromInput(parts.join('\u0000'))
+}
+
+export async function deterministicEventId(
+  triggerEventId: string,
+  name: string,
+  itemOrdinal: number,
+): Promise<string> {
+  if (name.length === 0) throw new TypeError('append name must not be empty')
+  return deterministicId([APPEND_NAMESPACE, triggerEventId, name, itemOrdinal])
+}
+
+export async function deterministicReturnedEventId(
+  triggerEventId: string,
+  itemOrdinal: number,
+): Promise<string> {
+  return deterministicId([RETURN_NAMESPACE, triggerEventId, itemOrdinal])
+}
+
+export async function deterministicScheduleId(
+  contract: string,
+  sessionId: string,
+  triggerEventId: string | null,
+  name: string,
+): Promise<string> {
+  return deterministicIdFromInput(
+    JSON.stringify([
+      SCHEDULE_NAMESPACE,
+      contract,
+      sessionId,
+      triggerEventId,
+      name,
+    ]),
+  )
+}
+
+export async function deterministicScheduledEventId(
+  scheduleId: string,
+  itemOrdinal: number,
+): Promise<string> {
+  return deterministicId([SCHEDULED_EVENT_NAMESPACE, scheduleId, itemOrdinal])
+}