@photon-grove/evt 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@photon-grove/evt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Event sourcing for TypeScript, wire-compatible with the Go and Rust evt implementations.",
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "dynamodb",
+    "postgresql"
+  ],
+  "homepage": "https://github.com/photon-grove/evt/tree/main/packages/evt#readme",
+  "bugs": "https://github.com/photon-grove/evt/issues",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-grove/evt.git",
+    "directory": "packages/evt"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dynamodb": {
+      "types": "./dist/dynamodb/index.d.ts",
+      "default": "./dist/dynamodb/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "default": "./dist/memory/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json && oxlint --deny-warnings && node scripts/check-imports.ts",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.9",
+    "oxlint": "1.88.0",
+    "typescript": "^7.0.2",
+    "vitest": "5.0.5"
+  }
+}

package/src/aggregate.ts

@@ -0,0 +1,196 @@
+// Aggregates: an entity's state folded from its events, the commands it decides on, and the typed
+// events it records, each with its stored version, payload codec and upcasters.
+
+import type {Codec} from './codec.js'
+import {EvtError, ReplayError, messageOf} from './errors.js'
+import type {SerializedEvent} from './event.js'
+import {type JsonValue, parseJson, stringifyJson} from './json.js'
+import {utf8Decode, utf8Encode} from './utf8.js'
+
+/**
+ * Migrates a stored payload of its event type before it is decoded, taking an event at the
+ * upcaster's from version to its to version. An event type's upcasters run in declaration order,
+ * each once, and each sees the output of the ones before it, so a 1 → 2 upcaster followed by a
+ * 2 → 3 one takes a version 1 event to version 3. Stored events are never rewritten.
+ */
+export interface Upcaster {
+  readonly from: number
+  readonly to: number
+  upcast(payload: Uint8Array): Uint8Array
+}
+
+/**
+ * An upcaster that rewrites a JSON payload. `migrate` gets it losslessly, as {@link parseJson}
+ * reads it (objects as `Map`s in their stored order, numbers as {@link JsonNumber}s), and returns
+ * the new payload, which is written with {@link stringifyJson}. What the migration doesn't touch
+ * is written back exactly, whatever its integers or keys.
+ */
+export function jsonUpcaster(
+  from: number,
+  to: number,
+  migrate: (payload: JsonValue) => unknown,
+): Upcaster {
+  return {
+    from,
+    to,
+    upcast(payload) {
+      const migrated = migrate(parseJson(utf8Decode(payload, 'payload')))
+
+      return utf8Encode(stringifyJson(migrated))
+    },
+  }
+}
+
+/** How one event type is stored: its current version, its payload codec, and its upcasters. */
+export interface EventDefinition<T> {
+  /** The version new events are written with, and the one stored events are upcast to. */
+  readonly version: number
+  readonly codec: Codec<T>
+  readonly upcasters?: readonly Upcaster[] | undefined
+}
+
+// oxlint-disable-next-line typescript/no-explicit-any -- each entry has its own data type.
+export type EventDefinitions = Readonly<Record<string, EventDefinition<any>>>
+
+/** The events a set of definitions describes: `{type, data}` for each event type. */
+export type EventOf<D extends EventDefinitions> = {
+  [K in keyof D & string]: {
+    type: K
+    data: D[K] extends EventDefinition<infer T> ? T : never
+  }
+}[keyof D & string]
+
+/** Declares an aggregate's event types, checking each version and upcaster. */
+export function defineEvents<const D extends EventDefinitions>(definitions: D): D {
+  for (const [type, definition] of Object.entries(definitions)) {
+    positive(definition.version, `${type} version`)
+    for (const upcaster of definition.upcasters ?? []) {
+      positive(upcaster.from, `${type} upcaster from`)
+      positive(upcaster.to, `${type} upcaster to`)
+    }
+  }
+
+  return definitions
+}
+
+/** A domain refusal of a command: a code to branch on, a message, and optional JSON details. */
+export interface Rejection {
+  code: string
+  message: string
+  details?: unknown
+}
+
+/** What a command handler decides: accept with events (possibly none), or reject. */
+export type Decision<E> =
+  | {kind: 'accept'; events: readonly E[]}
+  | {kind: 'reject'; rejection: Rejection}
+
+/** An aggregate type, as {@link defineAggregate} takes it. */
+export interface AggregateDefinition<S, C, D extends EventDefinitions> {
+  /** The stored entity type, such as `account`. */
+  readonly type: string
+  readonly events: D
+  /** The snapshot codec: how the state is stored. */
+  readonly state: Codec<S>
+  /** The state of an entity with no events. */
+  initial(): S
+  /** Decides what a command does. It must not change `state`. */
+  handle(state: S, command: C): Decision<EventOf<D>> | Promise<Decision<EventOf<D>>>
+  /** Folds one event into the state, returning the next state. It must not fail. */
+  apply(state: S, event: EventOf<D>): S
+  /**
+   * This type's own number of events between snapshots, overriding the store's. 0 disables its
+   * snapshots.
+   */
+  readonly snapshotInterval?: number | undefined
+}
+
+/** A checked aggregate type. */
+export type Aggregate<S, C, D extends EventDefinitions> = Readonly<AggregateDefinition<S, C, D>>
+
+/** Declares an aggregate type. */
+export function defineAggregate<S, C, D extends EventDefinitions>(
+  definition: AggregateDefinition<S, C, D>,
+): Aggregate<S, C, D> {
+  if (definition.type === '') {
+    throw new EvtError('invalidArgument', 'an aggregate type must have a name')
+  }
+  if (definition.snapshotInterval !== undefined) {
+    const interval = definition.snapshotInterval
+    if (!Number.isSafeInteger(interval) || interval < 0) {
+      throw new EvtError(
+        'invalidArgument',
+        `${definition.type} snapshot interval must be a whole number of events: ${interval}`,
+      )
+    }
+  }
+
+  return definition
+}
+
+/** Encodes one event's data with its type's codec, as the payload and version to store. */
+export function encodeEventData<D extends EventDefinitions>(
+  events: D,
+  event: EventOf<D>,
+): {version: number; payload: Uint8Array} {
+  const definition = definitionOf(events, event.type)
+  if (definition === undefined) {
+    throw new EvtError('invalidArgument', `${event.type} is not one of the aggregate's event types`)
+  }
+
+  return {version: definition.version, payload: definition.codec.encode(event.data)}
+}
+
+/** Upcasts and decodes a stored event, failing closed with a {@link ReplayError}. */
+export function replayEvent<D extends EventDefinitions>(
+  events: D,
+  stored: SerializedEvent,
+): EventOf<D> {
+  const definition = definitionOf(events, stored.type)
+  if (definition === undefined) {
+    throw new ReplayError(stored.type, stored.version, 'decode', 'unknown event type')
+  }
+
+  let payload = stored.payload ?? new Uint8Array()
+  let version = stored.version
+  for (const upcaster of definition.upcasters ?? []) {
+    if (upcaster.from !== version) {
+      continue
+    }
+
+    try {
+      payload = upcaster.upcast(payload)
+    } catch (error) {
+      throw new ReplayError(stored.type, version, 'upcast', messageOf(error), error)
+    }
+    version = upcaster.to
+  }
+
+  if (version !== definition.version) {
+    throw new ReplayError(
+      stored.type,
+      version,
+      'decode',
+      `no upcaster takes it to version ${definition.version}`,
+    )
+  }
+
+  try {
+    return {type: stored.type, data: definition.codec.decode(payload)} as EventOf<D>
+  } catch (error) {
+    throw new ReplayError(stored.type, version, 'decode', messageOf(error), error)
+  }
+}
+
+function definitionOf<D extends EventDefinitions>(
+  events: D,
+  type: string,
+): EventDefinition<unknown> | undefined {
+  return Object.hasOwn(events, type) ? events[type] : undefined
+}
+
+function positive(value: number, what: string): void {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new EvtError('invalidArgument', `${what} must be a whole number of at least 1: ${value}`)
+  }
+}

package/src/base64.ts

@@ -0,0 +1,80 @@
+// Standard, padded base64 (Go's base64.StdEncoding), which is how a Go []byte appears in JSON.
+// It's our own code because Buffer is Node-only and Uint8Array.fromBase64 isn't on every runtime.
+
+import {EvtError} from './errors.js'
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+const SYMBOLS = new Map(Array.from(ALPHABET, (symbol, value) => [symbol.charCodeAt(0), value]))
+
+const PAD = 0x3d // '='
+
+/** Encodes bytes as standard, padded base64. */
+export function base64Encode(bytes: Uint8Array): string {
+  let out = ''
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0
+    const b1 = bytes[i + 1] ?? 0
+    const b2 = bytes[i + 2] ?? 0
+    const triple = (b0 << 16) | (b1 << 8) | b2
+
+    out += ALPHABET.charAt((triple >> 18) & 63)
+    out += ALPHABET.charAt((triple >> 12) & 63)
+    out += i + 1 < bytes.length ? ALPHABET.charAt((triple >> 6) & 63) : '='
+    out += i + 2 < bytes.length ? ALPHABET.charAt(triple & 63) : '='
+  }
+
+  return out
+}
+
+/**
+ * Decodes standard, padded base64 the way Go does: `\r` and `\n` are skipped, and anything else
+ * outside the alphabet, missing padding, or padding before the end is refused.
+ */
+export function base64Decode(text: string): Uint8Array<ArrayBuffer> {
+  const symbols: number[] = []
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i)
+    if (unit !== 0x0d && unit !== 0x0a) {
+      symbols.push(unit)
+    }
+  }
+  if (symbols.length % 4 !== 0) {
+    throw invalid(`length ${symbols.length}`)
+  }
+
+  const quads = symbols.length / 4
+  const last = symbols.slice(-2)
+  const padding = last[1] === PAD ? (last[0] === PAD ? 2 : 1) : 0
+  const out = new Uint8Array(quads * 3 - padding)
+
+  for (let quad = 0; quad < quads; quad++) {
+    let triple = 0
+    for (let offset = 0; offset < 4; offset++) {
+      const index = quad * 4 + offset
+      const symbol = symbols[index] ?? PAD
+      const isPadding = quad === quads - 1 && offset >= 4 - padding
+      const value = isPadding ? 0 : SYMBOLS.get(symbol)
+      if (value === undefined) {
+        throw invalid(`at input byte ${index}`)
+      }
+
+      triple = (triple << 6) | value
+    }
+
+    const at = quad * 3
+    out[at] = triple >> 16
+    if (at + 1 < out.length) {
+      out[at + 1] = (triple >> 8) & 0xff
+    }
+    if (at + 2 < out.length) {
+      out[at + 2] = triple & 0xff
+    }
+  }
+
+  return out
+}
+
+function invalid(where: string): EvtError {
+  return new EvtError('invalidRecord', `illegal base64 data ${where}`)
+}

package/src/codec.ts

@@ -0,0 +1,139 @@
+// Payload codecs: how an application turns event data and aggregate state into stored bytes and
+// back. evt stores the bytes verbatim, so a codec owns their format.
+
+import {EvtError, messageOf} from './errors.js'
+import {JsonNumber, type JsonValue, parseJson, stringifyJson} from './json.js'
+import {utf8Decode, utf8Encode} from './utf8.js'
+
+/** Encodes values of `T` to stored bytes and decodes them back. */
+export interface Codec<T> {
+  encode(value: T): Uint8Array
+  decode(bytes: Uint8Array): T
+}
+
+/**
+ * The part of a [Standard Schema](https://standardschema.dev) validator evt calls, so Zod,
+ * Valibot, ArkType and the rest work without evt depending on any of them.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>
+    readonly types?: {readonly input: Input; readonly output: Output} | undefined
+  }
+}
+
+/** A Standard Schema validation result: the value, or the issues that refused it. */
+export type StandardResult<Output> =
+  | {readonly value: Output; readonly issues?: undefined}
+  | {readonly issues: readonly {readonly message: string}[]}
+
+/** Options for {@link json}. */
+export interface JsonOptions<T> {
+  /** Validates each value before it's encoded and after it's decoded, synchronously. */
+  schema?: StandardSchemaV1<unknown, T> | undefined
+}
+
+/**
+ * A JSON codec written with evt's encoder (the one Go's `encoding/json` output is reproduced
+ * with). Plain objects encode in property order.
+ *
+ * Decoding gives plain objects, arrays and numbers, so `T` must be plain JSON: a `Map`, a `bigint`
+ * or a `Date` doesn't decode back to itself. A domain that must match a Go or Rust one byte for
+ * byte, with a map whose keys are written sorted, needs a codec of its own that decodes the map as
+ * a `Map`. An integer past `Number.MAX_SAFE_INTEGER` is refused rather than rounded.
+ *
+ * Encoding refuses a value decoding would refuse, and with a `schema`, each value is validated
+ * before it's encoded and after it's decoded, so an event or a snapshot that couldn't be read back
+ * fails its commit instead of every later load. The schema must not transform values: the value
+ * is encoded as given.
+ */
+export function json<T>(options: JsonOptions<T> = {}): Codec<T> {
+  const schema = options.schema
+
+  return {
+    encode(value) {
+      if (schema) {
+        validate(schema, value, 'invalidArgument')
+      }
+
+      const text = stringifyJson(value)
+      readable(text)
+
+      return utf8Encode(text)
+    },
+    decode(bytes) {
+      const value = plainJson(parseJson(utf8Decode(bytes, 'payload')))
+
+      return schema ? validate(schema, value, 'invalidRecord') : (value as T)
+    },
+  }
+}
+
+/**
+ * A JSON value as plain JavaScript: objects as plain objects, numbers as `number`. An integer past
+ * the safe range is refused, because `number` would round it.
+ */
+export function plainJson(value: JsonValue): unknown {
+  if (value instanceof JsonNumber) {
+    const number = Number(value.text)
+    if (value.isInteger && !Number.isSafeInteger(number)) {
+      throw new EvtError(
+        'invalidRecord',
+        `the integer ${value.text} is past the integers a number holds; decode it with a codec ` +
+          'of its own',
+      )
+    }
+
+    return number
+  }
+  if (Array.isArray(value)) {
+    return value.map(plainJson)
+  }
+  if (value instanceof Map) {
+    const object: Record<string, unknown> = {}
+    for (const [key, entry] of value) {
+      // defineProperty, so a "__proto__" key is a plain property and never a prototype.
+      Object.defineProperty(object, key, {
+        value: plainJson(entry),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      })
+    }
+
+    return object
+  }
+
+  return value
+}
+
+// Refuses JSON that decode would refuse, such as an integer past the safe range, so the value
+// fails its commit instead of every later load.
+function readable(text: string): void {
+  try {
+    plainJson(parseJson(text))
+  } catch (error) {
+    throw new EvtError('invalidArgument', messageOf(error), {cause: error})
+  }
+}
+
+function validate<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  value: unknown,
+  code: 'invalidArgument' | 'invalidRecord',
+): T {
+  const result = schema['~standard'].validate(value)
+  if ('then' in result && typeof result.then === 'function') {
+    throw new EvtError('invalidArgument', 'a codec schema must validate synchronously')
+  }
+
+  const settled = result as StandardResult<T>
+  if (settled.issues) {
+    const issues = settled.issues.map((issue) => issue.message).join('; ')
+    throw new EvtError(code, `the payload does not match its schema: ${issues}`)
+  }
+
+  return settled.value
+}

package/src/commit-id.ts

@@ -0,0 +1,50 @@
+// Commit IDs for commits whose command carries none: ULID-format identifiers, 26 Crockford base32
+// characters for a 48-bit millisecond timestamp and 80 random bits. IDs one generator makes in one
+// millisecond increase, so they sort by creation time.
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const ENTROPY_MAX = (1n << 80n) - 1n
+const TIMESTAMP_MASK = (1n << 48n) - 1n
+
+/** Makes a ULID-format commit ID generator that reads `clock` (Unix milliseconds). */
+export function commitIds(clock: () => number): () => string {
+  let lastMs = -1n
+  let entropy = 0n
+
+  return () => {
+    // A clock that steps backwards keeps the last timestamp, so IDs never decrease.
+    let ms = BigInt(Math.max(0, Math.floor(clock()))) & TIMESTAMP_MASK
+    if (ms < lastMs) {
+      ms = lastMs
+    }
+
+    if (ms === lastMs && entropy < ENTROPY_MAX) {
+      entropy++
+    } else {
+      // A new millisecond, or 2^80 IDs in this one.
+      if (ms === lastMs) {
+        ms = (ms + 1n) & TIMESTAMP_MASK
+      }
+      lastMs = ms
+      entropy = randomEntropy()
+    }
+
+    return encode((ms << 80n) | entropy)
+  }
+}
+
+function randomEntropy(): bigint {
+  const bytes = crypto.getRandomValues(new Uint8Array(10))
+
+  return bytes.reduce((value, byte) => (value << 8n) | BigInt(byte), 0n)
+}
+
+function encode(value: bigint): string {
+  let text = ''
+  for (let i = 0; i < 26; i++) {
+    text = ALPHABET[Number(value & 31n)]! + text
+    value >>= 5n
+  }
+
+  return text
+}

package/src/dynamodb/head.ts

@@ -0,0 +1,93 @@
+// The DynamoDB actions on a stream's head item (ADR 0007), independent of any SDK: the one source
+// of the head's expression strings, which the writer builds its actions from and the commit
+// budget sizes. The fence and snapshot-guard forms join them with the DynamoDB backend.
+
+import {safeIntegerArgument} from '../fields.js'
+import {utf8Length} from '../utf8.js'
+import {HEAD_SORT_KEY, itemSize} from './item.js'
+
+/** The update expression of a head update on a stream without retention. */
+export const HEAD_UPDATE = 'SET head = :last'
+
+/** The update expression of a head update on a stream with retention, which raises `ttl` too. */
+export const HEAD_UPDATE_RETAINED = 'SET head = :last, #ttl = :t'
+
+/** The condition of the head update of a stream the commit creates (first sequence 1). */
+export const HEAD_CREATE_CONDITION = 'attribute_not_exists(head)'
+
+/** The condition of the head update of an append: the head is the sequence before the first. */
+export const HEAD_APPEND_CONDITION = 'head = :prev'
+
+/** {@link HEAD_APPEND_CONDITION} with retention: `ttl` is raised, never lowered. */
+export const HEAD_APPEND_RETAINED_CONDITION =
+  'head = :prev AND (attribute_not_exists(#ttl) OR #ttl <= :t)'
+
+/** An `Update` or `ConditionCheck` on a stream's head item. */
+export interface HeadAction {
+  entityId: string
+  /** The update expression, or null for a `ConditionCheck`. */
+  updateExpression: string | null
+  conditionExpression: string
+  /** `ExpressionAttributeNames`: placeholder and attribute name. */
+  names: [string, string][]
+  /** `ExpressionAttributeValues`: placeholder and number. */
+  values: [string, bigint][]
+}
+
+/**
+ * The head update of a stream whose commit writes events `first` to `last`. A first sequence of 1
+ * creates the head. `ttl` is the `:t` of the never-lower rule, given only for a stream with
+ * retention.
+ */
+export function headUpdate(
+  entityId: string,
+  first: bigint,
+  last: bigint,
+  ttl?: number,
+): HeadAction {
+  const create = first <= 1n
+  const values: [string, bigint][] = [[':last', last]]
+  const names: [string, string][] = []
+
+  if (!create) {
+    values.push([':prev', first - 1n])
+  }
+  if (ttl !== undefined) {
+    names.push(['#ttl', 'ttl'])
+    values.push([':t', BigInt(safeIntegerArgument(ttl, 'ttl'))])
+  }
+
+  let conditionExpression = HEAD_CREATE_CONDITION
+  if (!create) {
+    conditionExpression =
+      ttl === undefined ? HEAD_APPEND_CONDITION : HEAD_APPEND_RETAINED_CONDITION
+  }
+
+  return {
+    entityId,
+    updateExpression: ttl === undefined ? HEAD_UPDATE : HEAD_UPDATE_RETAINED,
+    conditionExpression,
+    names,
+    values,
+  }
+}
+
+/**
+ * An action's size in the commit budget, by the rule for any update, delete or condition check:
+ * its key attributes plus its expression strings, name placeholders (the placeholder and the
+ * name), and attribute values (the placeholder and the number's text).
+ */
+export function headActionSize(action: HeadAction): number {
+  const key = itemSize({pk: {S: action.entityId}, sk: {N: HEAD_SORT_KEY.toString()}})
+  let size =
+    key + utf8Length(action.updateExpression ?? '') + utf8Length(action.conditionExpression)
+
+  for (const [placeholder, name] of action.names) {
+    size += utf8Length(placeholder) + utf8Length(name)
+  }
+  for (const [placeholder, number] of action.values) {
+    size += utf8Length(placeholder) + number.toString().length
+  }
+
+  return size
+}

package/src/dynamodb/index.ts

@@ -0,0 +1,21 @@
+// @photon-grove/evt/dynamodb: the DynamoDB backend. So far it holds the item codec, which imports
+// nothing from the AWS SDK.
+
+export {
+  type AttributeValue,
+  type Item,
+  DEFAULT_VIEW_SORT_KEY,
+  HEAD_SORT_KEY,
+  SNAPSHOT_SORT_KEY,
+  eventFromItem,
+  eventItem,
+  expiry,
+  headFromItem,
+  headItem,
+  isSnapshotItem,
+  itemSize,
+  snapshotFromItem,
+  snapshotItem,
+  sortKey,
+  viewItem,
+} from './item.js'