@photon-grove/evt 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @photon-grove/evt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Event sourcing for TypeScript, wire-compatible with evt's Go module and its Rust crate. Event
+sourcing means the log of events is the record of truth, and an aggregate's state is whatever you
+get by folding its events in order. This package isn't a binding to the Go or Rust code. It's a
+third native implementation of the same
+[storage format](https://github.com/photon-grove/evt/blob/main/docs/reference/storage-format.md),
+held to the fixtures Go and Rust generate, byte for byte.
+
+```sh
+npm install @photon-grove/evt
+```
+
+So far it has the core, the in-memory backend and the testing helpers. The DynamoDB and
+PostgreSQL backends, command outcomes and multi-stream transactions come in later releases, and the
+[feature matrix](https://github.com/photon-grove/evt/blob/main/docs/reference/feature-matrix.md)
+tracks each one. The
+[getting started guide](https://github.com/photon-grove/evt/blob/main/docs/guide/getting-started.md#the-same-model-in-typescript)
+builds a bank account aggregate with it, end to end.
+
+## Entry points
+
+| Import                       | Contents                                                                    |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `@photon-grove/evt`          | Aggregates, codecs, upcasters, the `Store`, retry, and the wire codecs      |
+| `@photon-grove/evt/memory`   | `MemRepository`, the in-memory backend for tests and local development      |
+| `@photon-grove/evt/testing`  | `scenario` and `Fixture`, the given/when/then helpers over `MemRepository`  |
+| `@photon-grove/evt/dynamodb` | The DynamoDB item codec, with no SDK. The repository comes with the backend |
+
+## Runtimes
+
+The package is ESM only and has no runtime dependencies. CI runs it on Node 24, Node 22.12, Bun and
+Deno. Its code uses only web-standard globals (`TextEncoder`, `TextDecoder`, Web Crypto,
+`AbortSignal`, timers), never Node's built-ins, so it should run on edge runtimes and in browsers
+too, though CI doesn't run them yet. It never uses top-level await, so CommonJS code on Node 22.12
+and later can `require()` it. Its type declarations need TypeScript 5.7 or later and a declaration
+of `AbortSignal`, which the DOM library, `@types/node`, and Bun's and Deno's types all provide.
+
+## The model
+
+- **Events.** `defineEvents` gives each event type a version, a codec and, optionally, upcasters.
+  The type string, the version and the payload bytes are the durable contract. `EventOf<typeof
+  events>` is the union of `{type, data}` objects the aggregate works with.
+- **Codecs.** `json()` writes plain objects with evt's own JSON writer, in property order, and
+  decodes them back. It refuses an integer past `Number.MAX_SAFE_INTEGER` rather than round it,
+  when encoding as well as decoding. It takes an optional synchronous
+  [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType), checked on both
+  sides. Any `{encode, decode}` pair of bytes works as a codec.
+- **Aggregates.** `defineAggregate` names the type, the events, the state's codec and its initial
+  value. `handle(state, command)` returns a decision, `{kind: 'accept', events}` or
+  `{kind: 'reject', rejection: {code, message}}`, and may be async. `apply(state, event)` returns
+  the next state and never validates.
+- **The store.** `new Store(repository, options)` loads an aggregate from its latest snapshot and
+  the events after it, runs a command, and commits the decided events with optimistic concurrency:
+  the commit fails with a `ConflictError` if another writer moved the stream first.
+  `executeWithRetry` loads and runs the command again after a conflict, with a jittered backoff
+  (`DEFAULT_RETRY_POLICY`, the same as Go's and Rust's). A rejection commits nothing.
+- **Snapshots.** The store writes a snapshot every five events by default (the `snapshotInterval`
+  option, or the aggregate's own). A snapshot too large for one DynamoDB item is skipped rather
+  than failing the commit, and later loads replay from the one before.
+- **Duplicate commands.** A command whose metadata carries a command ID already seen since the
+  latest snapshot doesn't run, and `execute` resolves to `{kind: 'duplicate'}`. The window ends at
+  the snapshot, so once a snapshot covers the first run, a retry runs the command again.
+- **Upcasting.** An event type's upcasters migrate a stored payload from older versions to the
+  current one as it's read, in the order they're declared. `jsonUpcaster(from, to, migrate)` does
+  it on the parsed JSON, losslessly. A stored version the upcasters don't bring to the declared one
+  fails the load with a `ReplayError` rather than decoding into the wrong shape.
+- **Sequences** are `bigint`s, because Go and Rust store them as 64-bit integers.
+
+Errors are `EvtError`s with a `code`. `isConflict` and `isRetryable` tell them apart.
+
+## Testing
+
+`scenario` runs one command through a real `Store` over `MemRepository` and checks what it did:
+
+```ts
+await scenario(account)
+  .given({type: 'bank_account.opened', data: {accountId: 'acct-1', balance: 100}})
+  .when({type: 'deposit', amount: 25})
+  .thenEvents({type: 'bank_account.money_deposited', data: {accountId: 'acct-1', amount: 25}})
+```
+
+The other checks are `thenNoEvents`, `thenRejected` (with a code or a predicate), `thenDuplicate`,
+`thenError` and `thenState`. `run()` resolves to the outcome itself instead. `.entity()`,
+`.metadata()` and `.options()` change the stream, the command's metadata and the store's options.
+Each returns a new scenario, so one can be the base of several tests. `.on(fixture)` runs on a
+shared `Fixture`, where every run seeds its given events and runs its command again.
+
+`Fixture` seeds streams of any aggregate (`given`), reads them back decoded (`events`,
+`assertEvents`) and loads them (`load`). After a snapshot and a compaction, seeding continues from
+the snapshot. A failed check throws an `AssertionError` with `actual` and `expected`, so it works in
+any test runner, and Vitest and Jest show a diff.
+
+## Sharing streams with Go and Rust
+
+A TypeScript writer and a Go or Rust writer can share a stream once the TypeScript backends ship, as
+long as they agree on these:
+
+- The event type strings, versions and payload JSON, and the aggregate state's JSON, because each
+  language reads the others' snapshots. `json()` writes an object's properties in order, so declare
+  them in the order of the Go struct's fields.
+- Maps whose keys Go writes sorted. A Go map is a `Map` here, and it needs a codec of its own that
+  decodes it back as a `Map`, since `json()` decodes plain objects.
+- Integral payload numbers (cents, for example), because the languages format some floats
+  differently.
+- Event versions. Like Rust, TypeScript refuses a stored version it can't upcast to the declared
+  one, and Go decodes it anyway, so deploy readers before writers when you bump a version.
+
+Until the TypeScript package has commit-wide projectors and command outcomes, two more rules apply:
+
+- Don't write an entity type that has commit-wide projectors registered in a Go or Rust service.
+  Its commits would land without their view rows.
+- Don't share a store whose Go or Rust writers record command outcomes. A command retried through
+  TypeScript would find no outcome and could run twice.
+
+The [known differences](https://github.com/photon-grove/evt/blob/main/docs/reference/storage-format.md#known-differences)
+between the languages are in the storage format, and
+[ADR 0009](https://github.com/photon-grove/evt/blob/main/docs/adr/0009-typescript-implementation.md)
+explains how this package is built and tested.
+
+## License
+
+Apache-2.0.

package/dist/aggregate.d.ts

@@ -0,0 +1,83 @@
+import type { Codec } from './codec.js';
+import type { SerializedEvent } from './event.js';
+import { type JsonValue } from './json.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 declare function jsonUpcaster(from: number, to: number, migrate: (payload: JsonValue) => unknown): Upcaster;
+/** 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;
+}
+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 declare function defineEvents<const D extends EventDefinitions>(definitions: D): D;
+/** 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 declare function defineAggregate<S, C, D extends EventDefinitions>(definition: AggregateDefinition<S, C, D>): Aggregate<S, C, D>;
+/** Encodes one event's data with its type's codec, as the payload and version to store. */
+export declare function encodeEventData<D extends EventDefinitions>(events: D, event: EventOf<D>): {
+    version: number;
+    payload: Uint8Array;
+};
+/** Upcasts and decodes a stored event, failing closed with a {@link ReplayError}. */
+export declare function replayEvent<D extends EventDefinitions>(events: D, stored: SerializedEvent): EventOf<D>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"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"}

package/dist/aggregate.js

@@ -0,0 +1,92 @@
+// 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 { EvtError, ReplayError, messageOf } from './errors.js';
+import { parseJson, stringifyJson } from './json.js';
+import { utf8Decode, utf8Encode } from './utf8.js';
+/**
+ * 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, to, migrate) {
+    return {
+        from,
+        to,
+        upcast(payload) {
+            const migrated = migrate(parseJson(utf8Decode(payload, 'payload')));
+            return utf8Encode(stringifyJson(migrated));
+        },
+    };
+}
+/** Declares an aggregate's event types, checking each version and upcaster. */
+export function defineEvents(definitions) {
+    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;
+}
+/** Declares an aggregate type. */
+export function defineAggregate(definition) {
+    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(events, event) {
+    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(events, stored) {
+    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) };
+    }
+    catch (error) {
+        throw new ReplayError(stored.type, version, 'decode', messageOf(error), error);
+    }
+}
+function definitionOf(events, type) {
+    return Object.hasOwn(events, type) ? events[type] : undefined;
+}
+function positive(value, what) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new EvtError('invalidArgument', `${what} must be a whole number of at least 1: ${value}`);
+    }
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"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"}

package/dist/base64.d.ts

@@ -0,0 +1,8 @@
+/** Encodes bytes as standard, padded base64. */
+export declare function base64Encode(bytes: Uint8Array): string;
+/**
+ * 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 declare function base64Decode(text: string): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAWA,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAetD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CA0ClE"}

package/dist/base64.js

@@ -0,0 +1,67 @@
+// 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) {
+    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) {
+    const symbols = [];
+    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) {
+    return new EvtError('invalidRecord', `illegal base64 data ${where}`);
+}
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,kGAAkG;AAElG,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAA;AAEpC,MAAM,QAAQ,GAAG,kEAAkE,CAAA;AAEnF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;AAE/F,MAAM,GAAG,GAAG,IAAI,CAAA,CAAC,MAAM;AAEvB,gDAAgD;AAChD,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAA;QAC5B,MAAM,MAAM,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,EAAE,CAAA;QAE1C,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;QAC3C,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;QAC3C,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;QACvE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;IAClE,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QAC/B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,CAAC,UAAU,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;IAE/C,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,MAAM,GAAG,CAAC,CAAA;QACd,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,MAAM,CAAA;YAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,CAAA;YACpC,MAAM,SAAS,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC,IAAI,MAAM,IAAI,CAAC,GAAG,OAAO,CAAA;YAC7D,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,OAAO,CAAC,iBAAiB,KAAK,EAAE,CAAC,CAAA;YACzC,CAAC;YAED,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAA;QAChC,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,CAAA;QACnB,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,EAAE,CAAA;QACtB,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YACxB,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,IAAI,CAAA;QACpC,CAAC;QACD,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YACxB,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,IAAI,QAAQ,CAAC,eAAe,EAAE,uBAAuB,KAAK,EAAE,CAAC,CAAA;AACtE,CAAC"}

package/dist/codec.d.ts

@@ -0,0 +1,56 @@
+import { type JsonValue } from './json.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 declare function json<T>(options?: JsonOptions<T>): Codec<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 declare function plainJson(value: JsonValue): unknown;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,SAAS,EAA2B,MAAM,WAAW,CAAA;AAG9E,mEAAmE;AACnE,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,UAAU,CAAA;IAC5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,CAAC,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;QAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAC,GAAG,SAAS,CAAA;KAC9E,CAAA;CACF;AAED,qFAAqF;AACrF,MAAM,MAAM,cAAc,CAAC,MAAM,IAC7B;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAC,GACrD;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAC,EAAE,CAAA;CAAC,CAAA;AAE5D,gCAAgC;AAChC,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,sFAAsF;IACtF,MAAM,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAoB9D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAgCnD"}