@spine-event-engine/storage 2.0.0-snapshot.2

package/dist/record/record-spec.d.ts

@@ -0,0 +1,101 @@
+import type { Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { RecordColumn } from "./record-column.js";
+/**
+ * Configures one direct Protobuf record family and its identity.
+ */
+export type RecordSpecOptions<I, R extends Message> = {
+    /**
+     * Original message type represented by the stored records.
+     */
+    readonly sourceType?: GenMessage<Message>;
+    /**
+     * Protobuf record type stored by the family.
+     */
+    readonly recordType: GenMessage<R>;
+    /**
+     * Returns the authoritative identity extracted from a direct record.
+     *
+     * @param record Supplies the direct record.
+     * @returns The authoritative record identity.
+     */
+    readonly extractId: (record: R) => I;
+    /**
+     * Declared query columns materialized from each record.
+     */
+    readonly columns?: readonly RecordColumn<R>[];
+} & ([I] extends [Message] ? {
+    /**
+     * Generated schema for a message-valued identity.
+     */
+    readonly idSchema: GenMessage<I & Message>;
+    readonly idKind?: never;
+} : {
+    readonly idSchema?: never;
+    /**
+     * Stable kind name for a primitive identity.
+     */
+    readonly idKind: string;
+});
+/**
+ * Declarative specification for one identified Protobuf record type.
+ */
+export declare class RecordSpec<I, R extends Message> {
+    #private;
+    /**
+     * Creates a record specification.
+     *
+     * @throws Error if the ID type is invalid or two declared columns have the same name.
+     * @param input The source, record, identity, and column definitions.
+     */
+    constructor(input: RecordSpecOptions<I, R>);
+    /**
+     * Returns the original message type represented by these records.
+     * @returns The source message type.
+     */
+    get sourceType(): GenMessage<Message>;
+    /**
+     * Returns the type used to identify stored records.
+     * @returns The message ID type or primitive ID kind.
+     */
+    get idType(): I extends Message ? GenMessage<I> : string;
+    /**
+     * Returns the Protobuf record type stored by this specification.
+     * @returns The managed record type.
+     */
+    get recordType(): GenMessage<R>;
+    /**
+     * Returns the columns materialized from stored records.
+     * @returns The declared record columns.
+     */
+    get columns(): readonly RecordColumn<R>[];
+    /**
+     * Copies an ID value according to this specification.
+     * @param id The ID to clone.
+     * @returns The cloned ID.
+     */
+    cloneId(id: I): I;
+    /**
+     * Copies one record value according to this specification.
+     * @param record The record to clone.
+     * @returns The cloned record.
+     */
+    cloneRecord(record: R): R;
+    /**
+     * Gets the identifier from one stored record.
+     * @param record The stored record.
+     * @returns The logical record identifier.
+     */
+    idValueIn(record: R): I;
+    /**
+     * Creates materialized record values with cloned identifiers and columns.
+     * @param record The record to materialize.
+     * @returns The materialized record values.
+     */
+    materialize(record: R): {
+        readonly columns: ReadonlyMap<string, unknown>;
+        readonly id: I;
+        readonly record: R;
+    };
+}
+//# sourceMappingURL=record-spec.d.ts.map

package/dist/record/record-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-spec.d.ts","sourceRoot":"","sources":["../../src/record/record-spec.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMlD;;GAEG;AAEH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,IAAI;IAEpD;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;CAC/C,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,GACtB;IAEE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC,CAAC;AAOP;;GAEG;AACH,qBAAa,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;;IAQ1C;;;;;OAKG;gBACS,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;IA8B1C;;;OAGG;IACH,IAAI,UAAU,IAAI,UAAU,CAAC,OAAO,CAAC,CAEpC;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,CAAC,SAAS,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAEvD;IAED;;;OAGG;IACH,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,CAE9B;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAExC;IAED;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;IAMjB;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;IAIzB;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;IAIvB;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,CAAC,GAAG;QACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/C,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QACf,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;KACpB;CAeF"}

package/dist/record/record-spec.js

@@ -0,0 +1,159 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { clone } from "@bufbuild/protobuf";
+import { RecordColumn } from "./record-column.js";
+const storageHost = globalThis;
+/**
+ * Declarative specification for one identified Protobuf record type.
+ */
+export class RecordSpec {
+    #columns;
+    #extractId;
+    #idSchema;
+    #idKind;
+    #recordType;
+    #sourceType;
+    /**
+     * Creates a record specification.
+     *
+     * @throws Error if the ID type is invalid or two declared columns have the same name.
+     * @param input The source, record, identity, and column definitions.
+     */
+    constructor(input) {
+        const runtimeInput = input;
+        this.#columns = input.columns ?? [];
+        const names = new Set();
+        for (const column of this.#columns) {
+            if (names.has(column.name)) {
+                throw new Error(`Storage record specification has duplicate record column "${column.name}".`);
+            }
+            names.add(column.name);
+        }
+        this.#extractId = input.extractId;
+        if (runtimeInput.idSchema === undefined &&
+            (runtimeInput.idKind === undefined || runtimeInput.idKind.trim().length === 0)) {
+            throw new Error("Storage record specification requires a non-blank primitive ID kind.");
+        }
+        if (runtimeInput.idSchema !== undefined && runtimeInput.idKind !== undefined) {
+            throw new Error("Storage record specification must not declare both an ID schema and primitive ID kind.");
+        }
+        this.#idSchema = input.idSchema;
+        this.#idKind = input.idKind ?? "";
+        this.#recordType = input.recordType;
+        this.#sourceType = input.sourceType ?? input.recordType;
+    }
+    /**
+     * Returns the original message type represented by these records.
+     * @returns The source message type.
+     */
+    get sourceType() {
+        return this.#sourceType;
+    }
+    /**
+     * Returns the type used to identify stored records.
+     * @returns The message ID type or primitive ID kind.
+     */
+    get idType() {
+        return (this.#idSchema ?? this.#idKind);
+    }
+    /**
+     * Returns the Protobuf record type stored by this specification.
+     * @returns The managed record type.
+     */
+    get recordType() {
+        return this.#recordType;
+    }
+    /**
+     * Returns the columns materialized from stored records.
+     * @returns The declared record columns.
+     */
+    get columns() {
+        return this.#columns;
+    }
+    /**
+     * Copies an ID value according to this specification.
+     * @param id The ID to clone.
+     * @returns The cloned ID.
+     */
+    cloneId(id) {
+        const idSchema = this.#idSchema;
+        return idSchema === undefined ? RecordCloner.value(id) : RecordCloner.message(idSchema, id);
+    }
+    /**
+     * Copies one record value according to this specification.
+     * @param record The record to clone.
+     * @returns The cloned record.
+     */
+    cloneRecord(record) {
+        return RecordCloner.message(this.#recordType, record);
+    }
+    /**
+     * Gets the identifier from one stored record.
+     * @param record The stored record.
+     * @returns The logical record identifier.
+     */
+    idValueIn(record) {
+        return this.#extractId(record);
+    }
+    /**
+     * Creates materialized record values with cloned identifiers and columns.
+     * @param record The record to materialize.
+     * @returns The materialized record values.
+     */
+    materialize(record) {
+        const storedRecord = this.cloneRecord(record);
+        const id = this.cloneId(this.idValueIn(storedRecord));
+        return {
+            id,
+            record: storedRecord,
+            columns: new Map(this.#columns.map((column) => [
+                column.name,
+                RecordCloner.value(column.valueIn(storedRecord)),
+            ])),
+        };
+    }
+}
+const RecordCloner = Object.freeze({
+    message(schema, record) {
+        const cloneMethod = this.findCloneMethod(record);
+        if (cloneMethod !== undefined) {
+            return Reflect.apply(cloneMethod, record, []);
+        }
+        try {
+            return clone(schema, record);
+        }
+        catch {
+            throw new Error("Storage record could not be cloned.");
+        }
+    },
+    value(value) {
+        const cloneMethod = this.findCloneMethod(value);
+        if (cloneMethod !== undefined) {
+            return Reflect.apply(cloneMethod, value, []);
+        }
+        try {
+            return storageHost.structuredClone(value);
+        }
+        catch {
+            throw new Error("Storage value could not be cloned.");
+        }
+    },
+    findCloneMethod(value) {
+        if (typeof value !== "object" || value === null)
+            return undefined;
+        const candidate = Reflect.get(value, "clone");
+        return typeof candidate === "function" ? candidate : undefined;
+    },
+});
+//# sourceMappingURL=record-spec.js.map

package/dist/record/record-spec.js.map

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

package/dist/record/record-storage.d.ts

@@ -0,0 +1,202 @@
+import type { Message } from "@bufbuild/protobuf";
+import { RecordQuery } from "./record-query.js";
+import type { RecordReadOptions } from "./record-query.js";
+import type { RecordSpec } from "./record-spec.js";
+import type { Storage, StorageContext } from "../storage/storage.js";
+import type { NormalizedQueryPlan, StorageQueryCapabilities } from "../query/query-policy.js";
+/**
+ * Common record-oriented storage contract for identified Protobuf messages.
+ */
+export declare abstract class RecordStorage<I, R extends Message> implements Storage {
+    #private;
+    /**
+     * Declares whether this handle provides atomic compare-and-set mutations.
+     *
+     * The base contract defaults to `false`. An adapter sets this to `true` only
+     * when its `compareAndSet()` implementation is atomic across compatible
+     * handles. Registry and delivery code must reject a handle that leaves this
+     * capability disabled rather than treating a failed conditional write as a
+     * collision.
+     */
+    readonly atomicCompareAndSet: boolean;
+    /**
+     * Creates storage for one context and record specification.
+     * @param context The storage and tenant context.
+     * @param recordSpec The records managed by this storage.
+     */
+    constructor(context: StorageContext, recordSpec: RecordSpec<I, R>);
+    /**
+     * Returns the context that scopes this storage and its tenant slices.
+     * @returns The storage context.
+     */
+    protected get context(): StorageContext;
+    /**
+     * Returns the declarative record specification for this storage.
+     * @returns The managed record specification.
+     */
+    get recordSpec(): RecordSpec<I, R>;
+    /**
+     * Closes this record storage. Future operations fail.
+     */
+    close(): void;
+    /**
+     * Returns whether this record storage still accepts operations.
+     * @returns Whether the storage is open.
+     */
+    isOpen(): boolean;
+    /**
+     * Deletes one stored record by actual storage slot ID.
+     * @param id The storage slot identifier.
+     * @returns Whether a record was deleted.
+     */
+    delete(id: I): Promise<boolean>;
+    /**
+     * Reads one record by actual storage slot ID, optionally applying a mask.
+     * @param id The storage slot identifier.
+     * @param options The read options.
+     * @returns The matching record, if present.
+     */
+    read(id: I, options?: RecordReadOptions): Promise<R | undefined>;
+    /**
+     * Reads matching logical record identifiers derived from stored record bodies
+     * in deterministic query order.
+     * @param query The record query.
+     * @returns The matching logical identifiers.
+     */
+    index(query?: RecordQuery<I>): Promise<readonly I[]>;
+    /**
+     * Processes records by actual storage slot IDs, columns, sorting,
+     * continuations, limits, and optional masks.
+     *
+     * `RecordQuery.ids`, when present, filters storage slot IDs rather than
+     * logical IDs derived from record bodies.
+     * @param query The record query.
+     * @returns The matching records.
+     */
+    query(query?: RecordQuery<I>): Promise<readonly R[]>;
+    /**
+     * Processes stored records together with the actual storage slot IDs they
+     * currently occupy in the requested sorted and continued order.
+     *
+     * `RecordQuery.ids`, when present, filters those storage slot IDs rather
+     * than logical IDs derived from record bodies.
+     * @param query The record query.
+     * @returns The matching storage entries.
+     */
+    queryEntries(query?: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Executes one provider-independent normalized query plan.
+     * @param plan The validated normalized plan.
+     * @returns The matching records.
+     */
+    queryPlan(plan: NormalizedQueryPlan<I>): Promise<readonly R[]>;
+    /**
+     * Executes a normalized plan and retains actual storage slot IDs.
+     * @param plan The validated normalized plan.
+     * @returns The matching storage entries.
+     */
+    queryPlanEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Writes one record, replacing any previous value with the same ID.
+     * @param record The record to write.
+     * @returns Completes when the record is written.
+     */
+    write(record: R): Promise<void>;
+    /**
+     * Compares the current stored record for one ID with an expected value and
+     * write or delete only when they still match.
+     *
+     * Implementations must apply this atomically across independently opened
+     * storage handles that share the same logical backing store. Passing
+     * `undefined` as `next` performs a conditional delete. A `false` result means
+     * the current stored value did not match `expected`, so no mutation was
+     * applied. The `id` argument names an actual storage slot, not a logical ID
+     * derived from a record body. Adapters that cannot guarantee this behavior
+     * are not valid for delivery leasing or deduplication.
+     * @param id The storage slot identifier.
+     * @param expected The expected current record.
+     * @param next The record to write, or undefined to delete.
+     * @returns Whether the conditional mutation was applied.
+     */
+    compareAndSet(id: I, expected: R | undefined, next: R | undefined): Promise<boolean>;
+    /**
+     * Writes records in order, materializing all values before persistence.
+     * @param records The records to write.
+     * @returns Completes when the records are written.
+     */
+    writeAll(records: Iterable<R>): Promise<void>;
+    /**
+     * Deletes the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @returns Whether a record was deleted.
+     */
+    protected abstract deleteRecord(id: I): Promise<boolean>;
+    /**
+     * Returns stored records together with their actual storage slot IDs.
+     *
+     * Implementations must return `RecordEntry.id` as the concrete storage slot
+     * identifier for the row or document that currently stores the record.
+     * `RecordStorage.index()` derives logical record identifiers from
+     * `RecordEntry.record`, so adapters must not substitute logical IDs into
+     * `RecordEntry.id` here.
+     * @param query The record query.
+     * @returns The matching storage entries.
+     */
+    protected abstract queryRecordEntries(query: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Returns logical normalized features admitted before provider access.
+     * @returns The supported query capabilities.
+     */
+    protected queryCapabilities(): StorageQueryCapabilities;
+    /**
+     * Returns provider candidates for a normalized plan; shared evaluation applies the complete plan afterward.
+     * @param plan The normalized query plan.
+     * @returns The candidate storage entries.
+     */
+    protected queryPlanRecordEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Reads the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @returns The stored record, if present.
+     */
+    protected abstract readRecord(id: I): Promise<R | undefined>;
+    /**
+     * Compares and conditionally replaces the record at one storage slot.
+     * @param id The storage slot identifier.
+     * @param expected The expected materialized record.
+     * @param next The replacement materialized record, if any.
+     * @returns Whether the conditional mutation was applied.
+     */
+    protected abstract compareAndSetRecord(id: I, expected: ReturnType<RecordSpec<I, R>["materialize"]> | undefined, next: ReturnType<RecordSpec<I, R>["materialize"]> | undefined): Promise<boolean>;
+    /**
+     * Writes materialized records.
+     * @param records The materialized records to write.
+     * @returns Completes when the records are written.
+     */
+    protected abstract writeAllRecords(records: readonly ReturnType<RecordSpec<I, R>["materialize"]>[]): Promise<void>;
+    /**
+     * Writes one materialized record.
+     * @param record The materialized record to write.
+     * @returns Completes when the record is written.
+     */
+    protected abstract writeRecord(record: ReturnType<RecordSpec<I, R>["materialize"]>): Promise<void>;
+    private requireOpen;
+}
+/**
+ * One queried storage row or document.
+ *
+ * `id` is the actual storage slot identifier. `record` is the stored record
+ * value whose logical identifier may differ and is derived through
+ * `RecordSpec.idValueIn(...)`.
+ */
+export interface RecordEntry<I, R extends Message> {
+    /**
+     * Identifies the actual storage slot.
+     */
+    readonly id: I;
+    /**
+     * Holds the stored record value.
+     */
+    readonly record: R;
+}
+//# sourceMappingURL=record-storage.d.ts.map

package/dist/record/record-storage.d.ts.map

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