@photon-grove/evt 0.0.0-stage → 0.1.0

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/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,75 @@
+// @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,
+  ReplayError,
+  ReservedEntityIdError,
+  SequenceGapError,
+  SnapshotError,
+  StreamHeadDriftError,
+  isConflict,
+  isRetryable,
+} from './errors.js'
+export {
+  type SerializedEvent,
+  type SerializedSnapshot,
+  decodeEvent,
+  decodeSnapshot,
+  encodeEvent,
+  encodeSnapshot,
+  eventId,
+} from './event.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} 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'