@photon-grove/evt 0.0.0 → 0.1.1

package/dist/fields.js

@@ -0,0 +1,105 @@
+// 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 } from './json.js';
+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 = { duplicateKeys: 'refuse' };
+export function invalid(message) {
+    return new EvtError('invalidRecord', message);
+}
+/** An object, or null for JSON null. */
+export function objectOrNull(value, what) {
+    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, name, what) {
+    return nullableString(object, name, what) ?? '';
+}
+/** A string field that may be null (a Go `*string`). */
+export function nullableString(object, name, what) {
+    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, name, what) {
+    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, name, what) {
+    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, what) {
+    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, what) {
+    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, what) {
+    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, what) {
+    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, name, what) {
+    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, what) {
+    const object = objectOrNull(value, what);
+    if (object === null) {
+        return null;
+    }
+    const map = new Map();
+    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;
+}
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,aAAa,CAAA;AACtD,OAAO,EACL,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,IAAI,GACL,MAAM,YAAY,CAAA;AACnB,OAAO,EAAC,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AAC/E,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,QAAQ,EACR,KAAK,YAAY,EACjB,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,cAAc,EACd,uBAAuB,EACvB,KAAK,WAAW,EAChB,UAAU,EACV,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,OAAO,GACR,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAC,UAAU,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,aAAa,EAAC,MAAM,WAAW,CAAA;AAC9E,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,WAAW,EACX,MAAM,EACN,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,oBAAoB,EACpB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EAAC,qBAAqB,EAAE,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAC3F,OAAO,EAAC,WAAW,EAAE,UAAU,EAAC,MAAM,WAAW,CAAA;AACjD,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,17 @@
+// @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 { defineAggregate, defineEvents, jsonUpcaster, } from './aggregate.js';
+export { base64Decode, base64Encode } from './base64.js';
+export { json, } from './codec.js';
+export { encodeEnvelope, decodeEnvelope, messageAttributes } from './envelope.js';
+export { CommitTooLargeError, CompactionUncoveredError, ConflictError, EvtError, FeatureManifestChangedError, HistoryDependentProjectionError, RebuildInProgressError, ReplayError, ReservedEntityIdError, SequenceGapError, SnapshotError, StoreNotInitializedError, StreamHeadDriftError, StreamHeadsNotMigratedError, TransientError, UnsupportedFeatureError, isConflict, isRetryable, } from './errors.js';
+export { decodeEvent, decodeSnapshot, encodeEvent, encodeSnapshot, eventId, } from './event.js';
+export { STREAM_HEADS_FEATURE, STREAM_HEADS_VERSION, SUPPORTED_FEATURES, decodeManifest, encodeManifest, } from './features.js';
+export { JsonNumber, parseJson, stringifyJson } from './json.js';
+export { decodeMetadata, effectiveCausationId, emptyMetadata, encodeMetadata, } from './metadata.js';
+export { DEFAULT_RETRY_POLICY, retryDelay, } from './retry.js';
+export { MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue } from './snapshots.js';
+export { compareUtf8, utf8Length } from './utf8.js';
+export { DEFAULT_SNAPSHOT_INTERVAL, Store, } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,wFAAwF;AACxF,mFAAmF;AAEnF,OAAO,EASL,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,aAAa,CAAA;AACtD,OAAO,EAKL,IAAI,GACL,MAAM,YAAY,CAAA;AACnB,OAAO,EAAC,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AAC/E,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,QAAQ,EAER,2BAA2B,EAC3B,+BAA+B,EAC/B,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,cAAc,EACd,uBAAuB,EAEvB,UAAU,EACV,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EAGL,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,OAAO,GACR,MAAM,YAAY,CAAA;AACnB,OAAO,EAGL,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAC,UAAU,EAAkB,SAAS,EAAE,aAAa,EAAC,MAAM,WAAW,CAAA;AAC9E,OAAO,EAGL,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AAQtB,OAAO,EACL,oBAAoB,EAEpB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EAAC,qBAAqB,EAAE,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,gBAAgB,CAAA;AAC3F,OAAO,EAAC,WAAW,EAAE,UAAU,EAAC,MAAM,WAAW,CAAA;AACjD,OAAO,EACL,yBAAyB,EAKzB,KAAK,GAEN,MAAM,YAAY,CAAA"}

package/dist/json.d.ts

@@ -0,0 +1,47 @@
+/** A value read by {@link parseJson}. Objects are Maps, so integer-like keys keep their order. */
+export type JsonValue = null | boolean | string | JsonNumber | JsonValue[] | Map<string, JsonValue>;
+/** A JSON number kept as its literal text, so 2^53 + 1 or a 40-digit decimal stays exact. */
+export declare class JsonNumber {
+    readonly text: string;
+    constructor(text: string);
+    /** Whether the literal is an integer: no fraction and no exponent, as Go's int64 requires. */
+    get isInteger(): boolean;
+}
+/** Already-encoded JSON the writer copies as it is. The caller vouches for its bytes. */
+export declare class RawJson {
+    readonly text: string;
+    constructor(text: string);
+}
+/**
+ * Encodes a value the way Go's `json.Marshal` encodes the same shape:
+ *
+ * - A plain object is a struct: its own properties in order, skipping `undefined` ones. An
+ *   integer-like key (`"10"`) is refused, because the engine has already moved it to the front.
+ * - A `Map` is a Go map, written with its keys sorted by their UTF-8 bytes. Keys are strings, or
+ *   integers (`number` or `bigint`), which are written as text and sorted as text, like Go's.
+ * - A `bigint` is an integer, a `Uint8Array` is a `[]byte` (padded base64), and a
+ *   {@link JsonNumber} is written as its text.
+ * - Strings escape `<`, `>`, `&`, U+2028 and U+2029, and a lone surrogate becomes `\ufffd`, as Go
+ *   writes invalid UTF-8.
+ *
+ * Anything else, such as a `Date`, a class instance or a number that isn't finite, is refused.
+ */
+export declare function stringifyJson(value: unknown): string;
+/** Quotes a string with Go's escaping. */
+export declare function quote(text: string): string;
+/** How {@link parseJson} treats an object that repeats a key. */
+export interface ParseOptions {
+    /**
+     * `last` (the default) keeps the key's first place and its last value. `refuse` refuses the
+     * document, which is how evt reads its own documents: Go merges a repeated key into the earlier
+     * value and Rust refuses a repeated field, so no reading of one matches both.
+     */
+    duplicateKeys?: 'last' | 'refuse';
+}
+/**
+ * Parses JSON without losing anything `JSON.parse` loses. Objects come back as Maps in written
+ * order, and numbers come back as {@link JsonNumber}. An escaped lone surrogate reads as U+FFFD,
+ * as it does in Go.
+ */
+export declare function parseJson(text: string, options?: ParseOptions): JsonValue;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAQA,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAMnG,6FAA6F;AAC7F,qBAAa,UAAU;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,YAAY,IAAI,EAAE,MAAM,EAMvB;IAED,8FAA8F;IAC9F,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED,yFAAyF;AACzF,qBAAa,OAAO;IACN,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAjC,YAAqB,IAAI,EAAE,MAAM,EAAI;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA8CpD;AAqJD,0CAA0C;AAC1C,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsB1C;AAMD,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,SAAS,CAU7E"}

package/dist/json.js

@@ -0,0 +1,458 @@
+// evt's JSON reader and writer. The writer produces Go's encoding/json bytes, which every stored
+// document must match, and the reader keeps what JSON.parse loses: each number's text, and object
+// keys in the order they were written.
+import { base64Encode } from './base64.js';
+import { EvtError } from './errors.js';
+import { compareUtf8, isHighSurrogate, isLowSurrogate } from './utf8.js';
+const NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const INTEGER = /^-?(?:0|[1-9]\d*)$/;
+/** A JSON number kept as its literal text, so 2^53 + 1 or a 40-digit decimal stays exact. */
+export class JsonNumber {
+    text;
+    constructor(text) {
+        if (!NUMBER.test(text)) {
+            throw new EvtError('invalidArgument', `not a JSON number: ${text}`);
+        }
+        this.text = text;
+    }
+    /** Whether the literal is an integer: no fraction and no exponent, as Go's int64 requires. */
+    get isInteger() {
+        return INTEGER.test(this.text);
+    }
+}
+/** Already-encoded JSON the writer copies as it is. The caller vouches for its bytes. */
+export class RawJson {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+}
+/**
+ * Encodes a value the way Go's `json.Marshal` encodes the same shape:
+ *
+ * - A plain object is a struct: its own properties in order, skipping `undefined` ones. An
+ *   integer-like key (`"10"`) is refused, because the engine has already moved it to the front.
+ * - A `Map` is a Go map, written with its keys sorted by their UTF-8 bytes. Keys are strings, or
+ *   integers (`number` or `bigint`), which are written as text and sorted as text, like Go's.
+ * - A `bigint` is an integer, a `Uint8Array` is a `[]byte` (padded base64), and a
+ *   {@link JsonNumber} is written as its text.
+ * - Strings escape `<`, `>`, `&`, U+2028 and U+2029, and a lone surrogate becomes `\ufffd`, as Go
+ *   writes invalid UTF-8.
+ *
+ * Anything else, such as a `Date`, a class instance or a number that isn't finite, is refused.
+ */
+export function stringifyJson(value) {
+    const out = [];
+    // The arrays and objects being written, innermost last. The writer keeps its own stack, as the
+    // reader does, so a deep value is written without overflowing the call stack.
+    const open = [];
+    const writing = new Set();
+    let next = value;
+    for (;;) {
+        const opened = writeValue(next, out);
+        if (opened !== undefined) {
+            if (writing.has(opened.value)) {
+                throw new EvtError('invalidArgument', 'cannot encode a cyclic value as JSON');
+            }
+            writing.add(opened.value);
+            open.push(opened);
+        }
+        // Move to the next entry of the innermost open container, closing each one that is done.
+        for (;;) {
+            const top = open.at(-1);
+            if (top === undefined) {
+                return out.join('');
+            }
+            const entry = top.entries[top.next];
+            if (entry === undefined) {
+                out.push(top.close);
+                writing.delete(top.value);
+                open.pop();
+                continue;
+            }
+            if (top.next > 0) {
+                out.push(',');
+            }
+            top.next++;
+            const [key, entryValue] = entry;
+            if (key !== undefined) {
+                out.push(quote(key), ':');
+            }
+            next = entryValue;
+            break;
+        }
+    }
+}
+// Writes a scalar, or the opening of an array or object, which it returns for the caller to fill.
+function writeValue(value, out) {
+    switch (typeof value) {
+        case 'string':
+            out.push(quote(value));
+            return undefined;
+        case 'boolean':
+            out.push(value ? 'true' : 'false');
+            return undefined;
+        case 'bigint':
+            out.push(value.toString());
+            return undefined;
+        case 'number':
+            out.push(formatNumber(value));
+            return undefined;
+        case 'object':
+            if (value === null) {
+                out.push('null');
+                return undefined;
+            }
+            return writeObject(value, out);
+        default:
+            throw new EvtError('invalidArgument', `cannot encode a ${typeof value} as JSON`);
+    }
+}
+function writeObject(value, out) {
+    if (value instanceof JsonNumber || value instanceof RawJson) {
+        out.push(value.text);
+        return undefined;
+    }
+    if (value instanceof Uint8Array) {
+        out.push('"', base64Encode(value), '"');
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        out.push('[');
+        return { value, entries: arrayEntries(value), next: 0, close: ']' };
+    }
+    const entries = value instanceof Map ? mapEntries(value) : structEntries(value);
+    out.push('{');
+    return { value, entries, next: 0, close: '}' };
+}
+function arrayEntries(value) {
+    return Array.from(value, (entry) => {
+        if (entry === undefined) {
+            throw new EvtError('invalidArgument', 'cannot encode undefined in an array as JSON');
+        }
+        return [undefined, entry];
+    });
+}
+function mapEntries(value) {
+    const entries = [];
+    const seen = new Set();
+    for (const [key, entry] of value) {
+        const text = mapKey(key);
+        if (seen.has(text)) {
+            throw new EvtError('invalidArgument', `map key ${text} appears twice once written as text`);
+        }
+        seen.add(text);
+        entries.push([text, entry]);
+    }
+    entries.sort(([a], [b]) => compareUtf8(a, b));
+    return entries;
+}
+function mapKey(key) {
+    if (typeof key === 'string') {
+        return key;
+    }
+    if (typeof key === 'bigint' || (typeof key === 'number' && Number.isSafeInteger(key))) {
+        return key.toString();
+    }
+    throw new EvtError('invalidArgument', 'map keys must be strings or integers');
+}
+function structEntries(value) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        const name = value.constructor.name || 'object';
+        throw new EvtError('invalidArgument', `cannot encode a ${name} as JSON`);
+    }
+    const entries = [];
+    for (const [key, entry] of Object.entries(value)) {
+        if (isArrayIndex(key)) {
+            throw new EvtError('invalidArgument', `object key "${key}" is integer-like, so its order is lost: use a Map`);
+        }
+        if (entry !== undefined) {
+            entries.push([key, entry]);
+        }
+    }
+    return entries;
+}
+// The keys an engine enumerates first, in numeric order: canonical integers below 2^32 - 1.
+function isArrayIndex(key) {
+    return /^(?:0|[1-9]\d{0,9})$/.test(key) && Number(key) < 4294967295;
+}
+function formatNumber(value) {
+    if (!Number.isFinite(value)) {
+        throw new EvtError('invalidArgument', `cannot encode ${value} as JSON`);
+    }
+    // Both write the shortest text that reads back, with an exponent below 1e-6 and from 1e21. A
+    // number is usually an integer in a payload, so negative zero (from 0 * -1, say) is written as
+    // 0, as a Go int is, not as the -0 of a Go float64.
+    return value.toString();
+}
+const SHORT_ESCAPES = {
+    0x08: '\\b',
+    0x09: '\\t',
+    0x0a: '\\n',
+    0x0c: '\\f',
+    0x0d: '\\r',
+    0x22: '\\"',
+    0x5c: '\\\\',
+};
+// <, > and &, which Go escapes so the output is safe in HTML, and the two line separators.
+const HTML_ESCAPES = new Set([0x26, 0x3c, 0x3e, 0x2028, 0x2029]);
+/** Quotes a string with Go's escaping. */
+export function quote(text) {
+    let out = '"';
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        let escaped;
+        if (isHighSurrogate(unit) && isLowSurrogate(text.charCodeAt(i + 1))) {
+            i++;
+            continue;
+        }
+        else if (unit >= 0xd800 && unit <= 0xdfff) {
+            escaped = '\\ufffd';
+        }
+        else if (unit < 0x20 || unit === 0x22 || unit === 0x5c || HTML_ESCAPES.has(unit)) {
+            escaped = SHORT_ESCAPES[unit] ?? `\\u${unit.toString(16).padStart(4, '0')}`;
+        }
+        else {
+            continue;
+        }
+        out += text.slice(start, i) + escaped;
+        start = i + 1;
+    }
+    return out + text.slice(start) + '"';
+}
+// Go's decoder refuses documents nested deeper than this. The parser keeps its own stack, so a
+// deep document is refused cleanly instead of overflowing the call stack.
+const MAX_DEPTH = 10_000;
+/**
+ * Parses JSON without losing anything `JSON.parse` loses. Objects come back as Maps in written
+ * order, and numbers come back as {@link JsonNumber}. An escaped lone surrogate reads as U+FFFD,
+ * as it does in Go.
+ */
+export function parseJson(text, options = {}) {
+    const parser = new Parser(text, options.duplicateKeys === 'refuse');
+    parser.skipWhitespace();
+    const value = parser.value();
+    parser.skipWhitespace();
+    if (parser.pos < text.length) {
+        throw parser.error('unexpected text after the value');
+    }
+    return value;
+}
+class Parser {
+    text;
+    refuseDuplicates;
+    pos = 0;
+    constructor(text, refuseDuplicates) {
+        this.text = text;
+        this.refuseDuplicates = refuseDuplicates;
+    }
+    value() {
+        const open = [];
+        for (;;) {
+            let value;
+            const unit = this.text.charCodeAt(this.pos);
+            if (unit === 0x7b || unit === 0x5b) {
+                // { or [
+                if (open.length >= MAX_DEPTH) {
+                    throw this.error('exceeded max depth');
+                }
+                this.pos++;
+                this.skipWhitespace();
+                const empty = this.text.charCodeAt(this.pos) === unit + 2;
+                if (!empty) {
+                    open.push(unit === 0x5b ? { array: [] } : { object: new Map(), key: this.key() });
+                    continue;
+                }
+                this.pos++;
+                value = unit === 0x5b ? [] : new Map();
+            }
+            else {
+                value = this.scalar(unit);
+            }
+            // Add the value to the innermost open container, and close each container that ends here.
+            for (;;) {
+                const top = open.at(-1);
+                if (top === undefined) {
+                    return value;
+                }
+                if ('array' in top) {
+                    top.array.push(value);
+                }
+                else if (this.refuseDuplicates && top.object.has(top.key)) {
+                    throw this.error(`the key "${top.key}" appears twice`);
+                }
+                else {
+                    top.object.set(top.key, value);
+                }
+                this.skipWhitespace();
+                if (this.text.charCodeAt(this.pos) === 0x2c) {
+                    this.pos++;
+                    this.skipWhitespace();
+                    if ('object' in top) {
+                        top.key = this.key();
+                    }
+                    break;
+                }
+                if ('array' in top) {
+                    this.expect(0x5d, "',' or ']'");
+                    value = top.array;
+                }
+                else {
+                    this.expect(0x7d, "',' or '}'");
+                    value = top.object;
+                }
+                open.pop();
+            }
+        }
+    }
+    scalar(unit) {
+        switch (unit) {
+            case 0x22: // "
+                return this.string();
+            case 0x74: // t
+                return this.literal('true', true);
+            case 0x66: // f
+                return this.literal('false', false);
+            case 0x6e: // n
+                return this.literal('null', null);
+            default:
+                return this.number();
+        }
+    }
+    // An object key and its colon, leaving the position at the value.
+    key() {
+        if (this.text.charCodeAt(this.pos) !== 0x22) {
+            throw this.error('expected an object key');
+        }
+        const key = this.string();
+        this.skipWhitespace();
+        this.expect(0x3a, "':'");
+        this.skipWhitespace();
+        return key;
+    }
+    string() {
+        let out = '';
+        this.pos++;
+        let start = this.pos;
+        for (;;) {
+            if (this.pos >= this.text.length) {
+                throw this.error('unterminated string');
+            }
+            const unit = this.text.charCodeAt(this.pos);
+            if (unit === 0x22) {
+                out += this.text.slice(start, this.pos);
+                this.pos++;
+                return out;
+            }
+            if (unit < 0x20) {
+                throw this.error('control character in string');
+            }
+            if (unit === 0x5c) {
+                out += this.text.slice(start, this.pos) + this.escape();
+                start = this.pos;
+                continue;
+            }
+            if (unit >= 0xd800 && unit <= 0xdfff) {
+                // A raw surrogate that isn't half of a pair is invalid UTF-8 to Go.
+                if (isHighSurrogate(unit) && isLowSurrogate(this.text.charCodeAt(this.pos + 1))) {
+                    this.pos += 2;
+                    continue;
+                }
+                out += this.text.slice(start, this.pos) + '\ufffd';
+                this.pos++;
+                start = this.pos;
+                continue;
+            }
+            this.pos++;
+        }
+    }
+    escape() {
+        const unit = this.text.charCodeAt(this.pos + 1);
+        this.pos += 2;
+        switch (unit) {
+            case 0x22:
+                return '"';
+            case 0x5c:
+                return '\\';
+            case 0x2f:
+                return '/';
+            case 0x62:
+                return '\b';
+            case 0x66:
+                return '\f';
+            case 0x6e:
+                return '\n';
+            case 0x72:
+                return '\r';
+            case 0x74:
+                return '\t';
+            case 0x75: {
+                const high = this.hex();
+                if (!isHighSurrogate(high)) {
+                    return isLowSurrogate(high) ? '\ufffd' : String.fromCharCode(high);
+                }
+                // A high surrogate pairs only with an escaped low surrogate right after it.
+                if (this.text.startsWith('\\u', this.pos)) {
+                    const save = this.pos;
+                    this.pos += 2;
+                    const low = this.hex();
+                    if (isLowSurrogate(low)) {
+                        return String.fromCharCode(high, low);
+                    }
+                    this.pos = save;
+                }
+                return '\ufffd';
+            }
+            default:
+                this.pos -= 2;
+                throw this.error('invalid escape');
+        }
+    }
+    hex() {
+        const digits = this.text.slice(this.pos, this.pos + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(digits)) {
+            throw this.error('invalid \\u escape');
+        }
+        this.pos += 4;
+        return Number.parseInt(digits, 16);
+    }
+    number() {
+        const match = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+        match.lastIndex = this.pos;
+        const found = match.exec(this.text);
+        if (found === null) {
+            throw this.error('unexpected character');
+        }
+        this.pos += found[0].length;
+        return new JsonNumber(found[0]);
+    }
+    literal(word, value) {
+        if (!this.text.startsWith(word, this.pos)) {
+            throw this.error('unexpected character');
+        }
+        this.pos += word.length;
+        return value;
+    }
+    expect(unit, what) {
+        if (this.text.charCodeAt(this.pos) !== unit) {
+            throw this.error(`expected ${what}`);
+        }
+        this.pos++;
+    }
+    skipWhitespace() {
+        for (;;) {
+            const unit = this.text.charCodeAt(this.pos);
+            if (unit !== 0x20 && unit !== 0x09 && unit !== 0x0a && unit !== 0x0d) {
+                return;
+            }
+            this.pos++;
+        }
+    }
+    error(message) {
+        const where = this.pos >= this.text.length ? 'at the end' : `at offset ${this.pos}`;
+        return new EvtError('invalidJson', `invalid JSON ${where}: ${message}`);
+    }
+}
+//# sourceMappingURL=json.js.map