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

package/dist/record/record-mask.js

@@ -0,0 +1,82 @@
+/*
+ * 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.
+ */
+/**
+ * Provides record-mask operations.
+ */
+export const RecordMask = Object.freeze({
+    // prettier-ignore
+    /**
+     * Applies a simple field mask to a cloned record.
+     * @param record The cloned record to prune.
+     * @param mask The paths to retain.
+     * @returns The pruned record.
+     */
+    apply(record, mask) {
+        if (mask === undefined || mask.length === 0) {
+            return record;
+        }
+        const root = MaskTree.create(mask);
+        MaskTree.prune(record, root);
+        return record;
+    },
+});
+/**
+ * Builds and applies the tree used by one record-mask operation.
+ */
+const MaskTree = Object.freeze({
+    create(mask) {
+        const root = this.node();
+        for (const path of mask) {
+            if (path.trim().length === 0) {
+                continue;
+            }
+            let node = root;
+            for (const segment of path.split(".").filter((part) => part.length > 0)) {
+                let next = node.children.get(segment);
+                if (next === undefined) {
+                    next = this.node();
+                    node.children.set(segment, next);
+                }
+                node = next;
+            }
+        }
+        return root;
+    },
+    node() {
+        return { children: new Map() };
+    },
+    prune(value, node) {
+        if (typeof value !== "object" || value === null || node.children.size === 0) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                this.prune(item, node);
+            }
+            return;
+        }
+        for (const key of Object.keys(value)) {
+            if (key === "$typeName") {
+                continue;
+            }
+            const child = node.children.get(key);
+            if (child === undefined) {
+                Reflect.deleteProperty(value, key);
+                continue;
+            }
+            this.prune(Reflect.get(value, key), child);
+        }
+    },
+});
+//# sourceMappingURL=record-mask.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-mask.js","sourceRoot":"","sources":["../../src/record/record-mask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAElB,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;;;;OAKG;IACH,KAAK,CAAI,MAAS,EAAE,IAA4B;QAC9C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,CAAC,IAAgB;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAEzB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7B,SAAS;YACX,CAAC;YAED,IAAI,IAAI,GAAG,IAAI,CAAC;YAEhB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;gBACxE,IAAI,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAEtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBACnB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;gBACnC,CAAC;gBAED,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,OAAO,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAoB,EAAE,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,KAAc,EAAE,IAAc;QAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC5E,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,OAAO;QACT,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAErC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACnC,SAAS;YACX,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,102 @@
+/**
+ * Defines a deterministic record query by IDs, columns, sorting, continuations,
+ * offsets, limits, and masks.
+ */
+export interface RecordQuery<I> extends RecordReadOptions {
+    /**
+     * Exact storage slot identifier filter.
+     */
+    readonly ids?: readonly I[];
+    /**
+     * Exact column filters.
+     */
+    readonly filters?: readonly RecordFilter[];
+    /**
+     * Deterministic sort order.
+     */
+    readonly sort?: readonly RecordOrder[];
+    /**
+     * Stable ordered row key after which the query should continue.
+     */
+    readonly after?: RecordContinuation<I>;
+    /**
+     * Positive limit applied after sorting.
+     */
+    readonly limit?: number;
+    /**
+     * Non-negative row offset applied after sorting and before the limit.
+     */
+    readonly offset?: number;
+}
+/**
+ * Provides record-query validation operations.
+ */
+export declare const RecordQuery: Readonly<{
+    validate<I>(query: RecordQuery<I>): void;
+}>;
+/**
+ * Read-time options for one record fetch.
+ */
+export interface RecordReadOptions {
+    /**
+     * Optional simple mask applied to the cloned result.
+     */
+    readonly mask?: import("./record-mask.js").RecordMask;
+}
+/**
+ * Query sort order against one stored column, `id`, or a dotted record path.
+ */
+export interface RecordOrder {
+    /**
+     * Stored column name, `id`, or a dotted record path.
+     */
+    readonly field: string;
+    /**
+     * Sort direction, ascending by default.
+     */
+    readonly direction?: "asc" | "desc";
+}
+/**
+ * Stable ordered row key used to continue a sorted query after one row.
+ *
+ * `values` must name the same fields, in the same order, as `RecordQuery.sort`.
+ * `id` is the actual storage slot identifier for the row and breaks any
+ * remaining ties.
+ */
+export interface RecordContinuation<I> {
+    /**
+     * Ordered field values captured from the last row of the previous page.
+     */
+    readonly values: readonly RecordContinuationValue[];
+    /**
+     * Actual storage slot identifier captured from the last row of the previous page.
+     */
+    readonly id: I;
+}
+/**
+ * One captured sort-field value in a record continuation.
+ */
+export interface RecordContinuationValue {
+    /**
+     * Sort field this value was captured from.
+     */
+    readonly field: string;
+    /**
+     * Captured value for the sort field.
+     */
+    readonly value: unknown;
+}
+/**
+ * Equality filter against one stored column or the `id` field.
+ */
+export interface RecordFilter {
+    /**
+     * Stored column name or `id`.
+     */
+    readonly column: string;
+    /**
+     * One accepted value or a small accepted set.
+     */
+    readonly value: unknown;
+}
+//# sourceMappingURL=record-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-query.d.ts","sourceRoot":"","sources":["../../src/record/record-query.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,CAAE,SAAQ,iBAAiB;IAGvD;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1C,CA+BC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,kBAAkB,EAAE,UAAU,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IAGnC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAGtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAG3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB"}

package/dist/record/record-query.js

@@ -0,0 +1,44 @@
+/*
+ * 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.
+ */
+/**
+ * Provides record-query validation operations.
+ */
+export const RecordQuery = Object.freeze({
+    // prettier-ignore
+    /**
+     * Validate a record query before execution.
+     */
+    validate(query) {
+        if (query.limit !== undefined &&
+            (!Number.isInteger(query.limit) || !Number.isFinite(query.limit) || query.limit <= 0)) {
+            throw new Error("Record query limit must be positive.");
+        }
+        if (query.offset !== undefined &&
+            (!Number.isInteger(query.offset) || !Number.isFinite(query.offset) || query.offset < 0)) {
+            throw new Error("Record query offset must be non-negative.");
+        }
+        if (query.after !== undefined) {
+            const sort = query.sort ?? [];
+            if (query.after.values.length !== sort.length) {
+                throw new Error("Record query continuation must match the sort order.");
+            }
+            for (let index = 0; index < sort.length; index += 1) {
+                if (query.after.values[index]?.field !== sort[index]?.field) {
+                    throw new Error("Record query continuation must match the sort order.");
+                }
+            }
+        }
+    },
+});
+//# sourceMappingURL=record-query.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-query.js","sourceRoot":"","sources":["../../src/record/record-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwCH;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAEnB,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;OAEG;IACH,QAAQ,CAAI,KAAqB;QAC/B,IACE,KAAK,CAAC,KAAK,KAAK,SAAS;YACzB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,EACrF,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,IACE,KAAK,CAAC,MAAM,KAAK,SAAS;YAC1B,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EACvF,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YAC9B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;YAC1E,CAAC;YACD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;oBAC5D,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

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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"}