@photon-grove/evt 0.0.0 → 0.1.1

package/src/event.ts

@@ -0,0 +1,117 @@
+// Serialized events and snapshots: the stored form every repository reads and writes, and their
+// JSON encodings, which match Go's evt.SerializedEvent and evt.SerializedSnapshot.
+
+import {
+  DOCUMENT,
+  bytesField,
+  int64Argument,
+  int64Field,
+  objectOrNull,
+  safeIntegerArgument,
+  safeIntegerField,
+  stringField,
+  type JsonObject,
+} from './fields.js'
+import {parseJson, stringifyJson} from './json.js'
+import {type Metadata, metadataFromJson, metadataJson} from './metadata.js'
+
+/** An event as it is stored. Its JSON is the `detail` of a stream envelope. */
+export interface SerializedEvent {
+  /** `{entityId}:{sequence}`. */
+  id: string
+  /** The 1-based position of the event in its stream. */
+  sequence: bigint
+  /** The event kind, such as `account:opened`. */
+  type: string
+  /** The payload's schema version. */
+  version: number
+  /** The stream the event belongs to. */
+  entityId: string
+  /** The aggregate type of the entity. */
+  entityType: string
+  /**
+   * The payload bytes, stored verbatim. Null only when decoded from a JSON `null`, which is
+   * written back as `null`, as Go does.
+   */
+  payload: Uint8Array | null
+  metadata: Metadata
+}
+
+/** A snapshot of aggregate state. A stream keeps at most one, its latest. */
+export interface SerializedSnapshot {
+  entityType: string
+  entityId: string
+  /** 1 for an entity's first snapshot, then one more for each. */
+  sequence: bigint
+  /** The last event sequence folded into the snapshot. */
+  eventSequence: bigint
+  /** The state's bytes, stored verbatim. Null only when decoded from a JSON `null`. */
+  payload: Uint8Array | null
+}
+
+/** The event ID for a sequence of a stream: `{entityId}:{sequence}`. */
+export function eventId(entityId: string, sequence: bigint): string {
+  return `${entityId}:${sequence}`
+}
+
+/** Encodes an event as the JSON Go writes for it. */
+export function encodeEvent(event: SerializedEvent): string {
+  return stringifyJson(eventJson(event))
+}
+
+/** Decodes an event's JSON leniently, as Go does. */
+export function decodeEvent(json: string): SerializedEvent {
+  return eventFromJson(objectOrNull(parseJson(json, DOCUMENT), 'event'))
+}
+
+/** Encodes a snapshot as the JSON Go writes for it. Its entity ID key is `entityID`. */
+export function encodeSnapshot(snapshot: SerializedSnapshot): string {
+  return stringifyJson({
+    entityType: snapshot.entityType,
+    entityID: snapshot.entityId,
+    sequence: int64Argument(snapshot.sequence, 'snapshot.sequence'),
+    eventSequence: int64Argument(snapshot.eventSequence, 'snapshot.eventSequence'),
+    payload: snapshot.payload,
+  })
+}
+
+/** Decodes a snapshot's JSON leniently, as Go does. */
+export function decodeSnapshot(json: string): SerializedSnapshot {
+  const object = objectOrNull(parseJson(json, DOCUMENT), 'snapshot') ?? new Map()
+
+  return {
+    entityType: stringField(object, 'entityType', 'snapshot'),
+    entityId: stringField(object, 'entityID', 'snapshot'),
+    sequence: int64Field(object, 'sequence', 'snapshot'),
+    eventSequence: int64Field(object, 'eventSequence', 'snapshot'),
+    payload: bytesField(object, 'payload', 'snapshot'),
+  }
+}
+
+export function eventJson(event: SerializedEvent): object {
+  return {
+    id: event.id,
+    sequence: int64Argument(event.sequence, 'event.sequence'),
+    type: event.type,
+    version: safeIntegerArgument(event.version, 'event.version'),
+    entityId: event.entityId,
+    entityType: event.entityType,
+    payload: event.payload,
+    metadata: metadataJson(event.metadata),
+  }
+}
+
+export function eventFromJson(value: JsonObject | null): SerializedEvent {
+  const object = value ?? new Map()
+
+  return {
+    id: stringField(object, 'id', 'event'),
+    sequence: int64Field(object, 'sequence', 'event'),
+    type: stringField(object, 'type', 'event'),
+    version: safeIntegerField(object, 'version', 'event'),
+    entityId: stringField(object, 'entityId', 'event'),
+    entityType: stringField(object, 'entityType', 'event'),
+    payload: bytesField(object, 'payload', 'event'),
+    metadata: metadataFromJson(object.get('metadata')),
+  }
+}

package/src/features.ts

@@ -0,0 +1,175 @@
+// The feature manifest a store keeps on its SYSTEM#FEATURES marker row (storage format, "Feature
+// marker"): the extensions it declares, each at a stored-format version, and the entity types
+// declared history-dependent or retained. A writer refuses a store that declares a pair it doesn't
+// model, and every writer requires stream-heads.
+
+import {
+  EvtError,
+  type FeaturePair,
+  StreamHeadsNotMigratedError,
+  UnsupportedFeatureError,
+} from './errors.js'
+import {DOCUMENT, int64, invalid} from './fields.js'
+import {type JsonValue, parseJson, stringifyJson} from './json.js'
+import {compareUtf8} from './utf8.js'
+
+/** The feature every writer models and requires: per-stream head items (ADR 0007). */
+export const STREAM_HEADS_FEATURE = 'stream-heads'
+
+/** The stored-format version of {@link STREAM_HEADS_FEATURE} this package reads and writes. */
+export const STREAM_HEADS_VERSION = 1
+
+/**
+ * The `(feature, stored-format version)` pairs this package models. The other features the
+ * storage format defines (`journal`, `journal-compaction`, `postgres-views`) are Rust-first, so a
+ * store that declares any of them is refused.
+ */
+export const SUPPORTED_FEATURES: readonly FeaturePair[] = Object.freeze([
+  Object.freeze({name: STREAM_HEADS_FEATURE, version: STREAM_HEADS_VERSION}),
+])
+
+// What validation reads. Private, so no caller can add a pair to it.
+const supported = new Map(SUPPORTED_FEATURES.map((pair) => [pair.name, pair.version]))
+
+/** The parsed marker row. A store with no marker row has no manifest. */
+export interface FeatureManifest {
+  /** Bumped by exactly one on every declaration. */
+  readonly version: bigint
+  /** Each declared feature's stored-format version. */
+  readonly features: ReadonlyMap<string, number>
+  /** The entity types whose commit-wide projectors are history-dependent: never compacted. */
+  readonly historyDependent: readonly string[]
+  /** The entity types configured with retention: never fenced. */
+  readonly retention: readonly string[]
+}
+
+/**
+ * Refuses a manifest that declares a pair this package doesn't model, listing every such pair,
+ * with an {@link UnsupportedFeatureError}.
+ */
+export function checkSupported(manifest: FeatureManifest | null): void {
+  const unsupported: FeaturePair[] = []
+  for (const [name, version] of sortedFeatures(manifest?.features ?? new Map())) {
+    if (supported.get(name) !== version) {
+      unsupported.push({name, version})
+    }
+  }
+
+  if (unsupported.length > 0) {
+    throw new UnsupportedFeatureError(unsupported)
+  }
+}
+
+/** Whether the manifest declares stream-heads at the version this package models. */
+export function declaresStreamHeads(manifest: FeatureManifest | null): boolean {
+  return manifest?.features.get(STREAM_HEADS_FEATURE) === STREAM_HEADS_VERSION
+}
+
+/**
+ * Refuses a write to a store whose manifest declares an unsupported pair, or doesn't declare
+ * stream-heads, without declaring anything.
+ */
+export function checkWritable(manifest: FeatureManifest | null): void {
+  checkSupported(manifest)
+  if (!declaresStreamHeads(manifest)) {
+    throw new StreamHeadsNotMigratedError()
+  }
+}
+
+/** The manifest with stream-heads declared and its version bumped: a first writer's declaration. */
+export function withStreamHeads(manifest: FeatureManifest | null): FeatureManifest {
+  const features = new Map(manifest?.features)
+  features.set(STREAM_HEADS_FEATURE, STREAM_HEADS_VERSION)
+
+  return {
+    version: (manifest?.version ?? 0n) + 1n,
+    features,
+    historyDependent: manifest?.historyDependent ?? [],
+    retention: manifest?.retention ?? [],
+  }
+}
+
+/** A manifest's stored JSON texts, as the marker row holds them. */
+export interface ManifestTexts {
+  /** A JSON object, feature name to stored-format version, keys sorted. `{}` when empty. */
+  features: string
+  /** A JSON array of entity types, sorted by UTF-8 bytes and deduplicated. `[]` when empty. */
+  historyDependent: string
+  /** Like `historyDependent`. */
+  retention: string
+}
+
+/** Encodes a manifest's declarable parts as the marker row stores them. */
+export function encodeManifest(manifest: FeatureManifest): ManifestTexts {
+  return {
+    features: stringifyJson(new Map(manifest.features)),
+    historyDependent: stringifyJson(entityTypeSet(manifest.historyDependent)),
+    retention: stringifyJson(entityTypeSet(manifest.retention)),
+  }
+}
+
+/**
+ * Decodes a marker row's stored texts. An empty text is an empty map or set, as an absent
+ * attribute is.
+ */
+export function decodeManifest(version: bigint, texts: ManifestTexts): FeatureManifest {
+  return {
+    version,
+    features: texts.features === '' ? new Map() : parseFeatures(texts.features),
+    historyDependent: parseEntityTypes(texts.historyDependent, 'historyDependent'),
+    retention: parseEntityTypes(texts.retention, 'retention'),
+  }
+}
+
+/** An entity-type set in its stored order: sorted by UTF-8 bytes and deduplicated. */
+export function entityTypeSet(types: readonly string[]): string[] {
+  // A fresh array, sorted in place: ES2022 has no toSorted.
+  const set = Array.from(new Set(types))
+  set.sort(compareUtf8)
+
+  return set
+}
+
+function parseFeatures(text: string): Map<string, number> {
+  const parsed = parseStored(text, 'features')
+  if (!(parsed instanceof Map)) {
+    throw invalid('the feature manifest is not a JSON object')
+  }
+
+  // Go and Rust read a version as an int64. One past the safe integers is no version this
+  // package models, so rounding it changes only the refusal's text.
+  const features = new Map<string, number>()
+  for (const [name, version] of parsed) {
+    features.set(name, Number(int64(version, `the feature manifest's ${name} version`)))
+  }
+
+  return features
+}
+
+function parseEntityTypes(text: string, what: string): string[] {
+  if (text.trim() === '') {
+    return []
+  }
+
+  const parsed = parseStored(text, what)
+  if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== 'string')) {
+    throw invalid(`the ${what} set is not a JSON array of strings`)
+  }
+
+  return entityTypeSet(parsed as string[])
+}
+
+function parseStored(text: string, what: string): JsonValue {
+  try {
+    return parseJson(text, DOCUMENT)
+  } catch (error) {
+    throw new EvtError('invalidRecord', `the stored ${what} is not JSON`, {cause: error})
+  }
+}
+
+function sortedFeatures(features: ReadonlyMap<string, number>): [string, number][] {
+  const sorted = Array.from(features)
+  sorted.sort(([a], [b]) => compareUtf8(a, b))
+
+  return sorted
+}

package/src/fields.ts

@@ -0,0 +1,134 @@
+// Lenient decoding of engine documents by Go's rules: a missing field or null is the zero value,
+// unknown fields are ignored, and a value of the wrong JSON type is an error. Field names match
+// exactly, as in Rust (Go also matches them case-insensitively).
+
+import {base64Decode} from './base64.js'
+import {EvtError} from './errors.js'
+import {JsonNumber, type JsonValue, type ParseOptions} from './json.js'
+
+export type JsonObject = Map<string, JsonValue>
+
+const INT64_MIN = -(2n ** 63n)
+
+const INT64_MAX = 2n ** 63n - 1n
+
+/** How evt parses its own documents: a repeated key is refused. */
+export const DOCUMENT: ParseOptions = {duplicateKeys: 'refuse'}
+
+export function invalid(message: string): EvtError {
+  return new EvtError('invalidRecord', message)
+}
+
+/** An object, or null for JSON null. */
+export function objectOrNull(value: JsonValue | undefined, what: string): JsonObject | null {
+  if (value === undefined || value === null) {
+    return null
+  }
+  if (!(value instanceof Map)) {
+    throw invalid(`${what} is not an object`)
+  }
+
+  return value
+}
+
+/** A string field, `""` when missing or null. */
+export function stringField(object: JsonObject, name: string, what: string): string {
+  return nullableString(object, name, what) ?? ''
+}
+
+/** A string field that may be null (a Go `*string`). */
+export function nullableString(object: JsonObject, name: string, what: string): string | null {
+  const value = object.get(name)
+  if (value === undefined || value === null) {
+    return null
+  }
+  if (typeof value !== 'string') {
+    throw invalid(`${what}.${name} is not a string`)
+  }
+
+  return value
+}
+
+/** An int64 field, `0n` when missing or null. `1.0`, `1e3` and `"1"` are refused, as in Go. */
+export function int64Field(object: JsonObject, name: string, what: string): bigint {
+  const value = object.get(name)
+  if (value === undefined || value === null) {
+    return 0n
+  }
+
+  return int64(value, `${what}.${name}`)
+}
+
+/** A small integer field, `0` when missing or null, refused if it isn't a safe integer. */
+export function safeIntegerField(object: JsonObject, name: string, what: string): number {
+  const value = int64Field(object, name, what)
+  if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw invalid(`${what}.${name} is ${value}, past the integers this field holds`)
+  }
+
+  return Number(value)
+}
+
+/** Reads a JSON number as an int64. */
+export function int64(value: JsonValue, what: string): bigint {
+  if (!(value instanceof JsonNumber) || !value.isInteger) {
+    throw invalid(`${what} is not an integer`)
+  }
+
+  return checkInt64(BigInt(value.text), what)
+}
+
+/** Refuses an integer outside int64. */
+export function checkInt64(value: bigint, what: string): bigint {
+  if (value < INT64_MIN || value > INT64_MAX) {
+    throw invalid(`${what} is ${value}, outside int64`)
+  }
+
+  return value
+}
+
+/** Refuses to write an integer that no reader would read back as an int64. */
+export function int64Argument(value: bigint, what: string): bigint {
+  if (value < INT64_MIN || value > INT64_MAX) {
+    throw new EvtError('invalidArgument', `${what} is ${value}, outside int64`)
+  }
+
+  return value
+}
+
+/** Refuses to write a small integer that isn't a safe integer, such as 1.5 or NaN. */
+export function safeIntegerArgument(value: number, what: string): number {
+  if (!Number.isSafeInteger(value)) {
+    throw new EvtError('invalidArgument', `${what} is ${value}, not a safe integer`)
+  }
+
+  return value
+}
+
+/** A base64 field (a Go `[]byte`), null when missing or null. */
+export function bytesField(object: JsonObject, name: string, what: string): Uint8Array | null {
+  const text = nullableString(object, name, what)
+
+  return text === null ? null : base64Decode(text)
+}
+
+/**
+ * A Go `map[string]string`: null for a missing or null map, and `""` for a null value.
+ */
+export function stringMap(value: JsonValue | undefined, what: string): Map<string, string> | null {
+  const object = objectOrNull(value, what)
+  if (object === null) {
+    return null
+  }
+
+  const map = new Map<string, string>()
+  for (const [key, entry] of object) {
+    if (entry !== null && typeof entry !== 'string') {
+      throw invalid(`${what}.${key} is not a string`)
+    }
+
+    map.set(key, entry ?? '')
+  }
+
+  return map
+}

package/src/globals.d.ts

@@ -0,0 +1,39 @@
+// The only runtime globals the published code may use: web-standard APIs that Node, Bun, Deno,
+// edge runtimes and browsers all provide (ADR 0009, section 3). tsconfig.json loads no DOM or Node
+// types, so anything else, such as Buffer, process or document, is a type error. Declare a global
+// here only when the code needs it and every target runtime has it, typed no looser than the
+// runtimes' own declarations: tsconfig.test.json checks src/ against Node's types instead.
+
+declare class TextEncoder {
+  readonly encoding: string
+  encode(input?: string): Uint8Array<ArrayBuffer>
+}
+
+declare class TextDecoder {
+  constructor(label?: string, options?: {fatal?: boolean; ignoreBOM?: boolean})
+  readonly encoding: string
+  readonly fatal: boolean
+  decode(input?: ArrayBuffer | ArrayBufferView, options?: {stream?: boolean}): string
+}
+
+interface AbortSignal {
+  readonly aborted: boolean
+  readonly reason: unknown
+  throwIfAborted(): void
+  addEventListener(type: 'abort', listener: () => void, options?: {once?: boolean}): void
+  removeEventListener(type: 'abort', listener: () => void): void
+}
+
+// Browsers define crypto.subtle only in secure contexts (HTTPS or localhost).
+declare var crypto: {
+  getRandomValues<T extends Uint8Array>(array: T): T
+  readonly subtle: {
+    digest(algorithm: 'SHA-256', data: Uint8Array<ArrayBuffer>): Promise<ArrayBuffer>
+  }
+}
+
+declare function setTimeout(callback: () => void, ms?: number): unknown
+
+declare function clearTimeout(id: unknown): void
+
+declare function queueMicrotask(callback: () => void): void

package/src/index.ts

@@ -0,0 +1,98 @@
+// @photon-grove/evt: event sourcing for TypeScript, wire-compatible with the Go and Rust evt
+// implementations (docs/adr/0009-typescript-implementation.md). The storage contract is
+// docs/reference/storage-format.md, and compat/fixtures holds its executable form.
+
+export {
+  type Aggregate,
+  type AggregateDefinition,
+  type Decision,
+  type EventDefinition,
+  type EventDefinitions,
+  type EventOf,
+  type Rejection,
+  type Upcaster,
+  defineAggregate,
+  defineEvents,
+  jsonUpcaster,
+} from './aggregate.js'
+export {base64Decode, base64Encode} from './base64.js'
+export {
+  type Codec,
+  type JsonOptions,
+  type StandardResult,
+  type StandardSchemaV1,
+  json,
+} from './codec.js'
+export {encodeEnvelope, decodeEnvelope, messageAttributes} from './envelope.js'
+export {
+  CommitTooLargeError,
+  CompactionUncoveredError,
+  ConflictError,
+  EvtError,
+  type EvtErrorCode,
+  FeatureManifestChangedError,
+  HistoryDependentProjectionError,
+  RebuildInProgressError,
+  ReplayError,
+  ReservedEntityIdError,
+  SequenceGapError,
+  SnapshotError,
+  StoreNotInitializedError,
+  StreamHeadDriftError,
+  StreamHeadsNotMigratedError,
+  TransientError,
+  UnsupportedFeatureError,
+  type FeaturePair,
+  isConflict,
+  isRetryable,
+} from './errors.js'
+export {
+  type SerializedEvent,
+  type SerializedSnapshot,
+  decodeEvent,
+  decodeSnapshot,
+  encodeEvent,
+  encodeSnapshot,
+  eventId,
+} from './event.js'
+export {
+  type FeatureManifest,
+  type ManifestTexts,
+  STREAM_HEADS_FEATURE,
+  STREAM_HEADS_VERSION,
+  SUPPORTED_FEATURES,
+  decodeManifest,
+  encodeManifest,
+} from './features.js'
+export {JsonNumber, type JsonValue, parseJson, stringifyJson} from './json.js'
+export {
+  type Metadata,
+  type Origin,
+  decodeMetadata,
+  effectiveCausationId,
+  emptyMetadata,
+  encodeMetadata,
+} from './metadata.js'
+export type {
+  CallOptions,
+  Commit,
+  NewSnapshot,
+  Repository,
+  StoreInitializer,
+} from './repository.js'
+export {
+  DEFAULT_RETRY_POLICY,
+  type RetryPolicy,
+  retryDelay,
+} from './retry.js'
+export {MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue} from './snapshots.js'
+export {compareUtf8, utf8Length} from './utf8.js'
+export {
+  DEFAULT_SNAPSHOT_INTERVAL,
+  type ExecuteOptions,
+  type ExecuteResult,
+  type Loaded,
+  type RetryOptions,
+  Store,
+  type StoreOptions,
+} from './store.js'