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

package/dist/record/column-mapping.d.ts

@@ -0,0 +1,41 @@
+import type { RecordColumnType } from "./column-type.js";
+/**
+ * Converts one typed record-column value to its provider representation.
+ *
+ * @param value The typed Protobuf value.
+ * @returns The provider representation.
+ */
+export type ColumnTypeMapping<V, R> = (value: V) => R;
+/**
+ * Supplies provider conversion rules for generated Protobuf column types.
+ */
+export interface ColumnMapping<R> {
+    /**
+     * Returns the conversion rule for a declared column type.
+     * @param type The generated Protobuf column type.
+     * @returns The provider conversion rule.
+     */
+    of<V>(type: RecordColumnType<V>): ColumnTypeMapping<V, R>;
+    /**
+     * Returns the provider conversion rule for an absent column value.
+     * @returns The provider null conversion rule.
+     */
+    ofNull(): ColumnTypeMapping<null, R>;
+}
+/**
+ * Applies one provider mapping to stored and queried column values.
+ */
+export declare const ColumnMappings: {
+    /**
+     * Converts a value through its declared provider rule.
+     *
+     * Both record materialization and query planning must call this operation.
+     *
+     * @param mapping The provider mapping.
+     * @param type The declared column type.
+     * @param value The stored or queried value.
+     * @returns The provider value.
+     */
+    readonly value: <V, R>(mapping: ColumnMapping<R>, type: RecordColumnType<V>, value: V | null | undefined) => R;
+};
+//# sourceMappingURL=column-mapping.d.ts.map

package/dist/record/column-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.d.ts","sourceRoot":"","sources":["../../src/record/column-mapping.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAG9B;;;;OAIG;IACH,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE1D;;;OAGG;IACH,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IAGzB;;;;;;;;;OASG;qBACG,CAAC,EAAE,CAAC,WACC,aAAa,CAAC,CAAC,CAAC,QACnB,gBAAgB,CAAC,CAAC,CAAC,SAClB,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,CAAC;CAKI,CAAC"}

package/dist/record/column-mapping.js

@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+/**
+ * Applies one provider mapping to stored and queried column values.
+ */
+export const ColumnMappings = {
+    // prettier-ignore
+    /**
+     * Converts a value through its declared provider rule.
+     *
+     * Both record materialization and query planning must call this operation.
+     *
+     * @param mapping The provider mapping.
+     * @param type The declared column type.
+     * @param value The stored or queried value.
+     * @returns The provider value.
+     */
+    value(mapping, type, value) {
+        return value === null || value === undefined
+            ? mapping.ofNull()(null)
+            : mapping.of(type)(value);
+    },
+};
+Object.freeze(ColumnMappings);
+//# sourceMappingURL=column-mapping.js.map

package/dist/record/column-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.js","sourceRoot":"","sources":["../../src/record/column-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgCH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,kBAAkB;IAElB;;;;;;;;;OASG;IACH,KAAK,CACH,OAAyB,EACzB,IAAyB,EACzB,KAA2B;QAE3B,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAC1C,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;YACxB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;CACO,CAAC;AACX,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC"}

package/dist/record/column-type.d.ts

@@ -0,0 +1,75 @@
+import type { DescEnum, DescField, DescMessage, ScalarType } from "@bufbuild/protobuf";
+declare const columnValueType: unique symbol;
+/**
+ * Generated Protobuf type retained for one materialized record column.
+ */
+export type RecordColumnType<V = unknown> = ({
+    /**
+     * Identifies a Protobuf scalar column.
+     */
+    readonly kind: "scalar";
+    /**
+     * Protobuf scalar kind retained by the column.
+     */
+    readonly scalar: ScalarType;
+    /**
+     * Whether generated code represents a 64-bit value as a string.
+     */
+    readonly longAsString: boolean;
+} | {
+    /**
+     * Identifies a Protobuf enum column.
+     */
+    readonly kind: "enum";
+    /**
+     * Generated enum descriptor retained by the column.
+     */
+    readonly enum: DescEnum;
+} | {
+    /**
+     * Identifies a Protobuf message column.
+     */
+    readonly kind: "message";
+    /**
+     * Generated message descriptor retained by the column.
+     */
+    readonly message: DescMessage;
+}) & {
+    /**
+     * Compile-time value type carried by the column declaration.
+     */
+    readonly [columnValueType]?: V;
+};
+/**
+ * Creates record-column types from generated Protobuf descriptors.
+ */
+export declare const ColumnTypes: {
+    /**
+     * Declares a scalar type for a derived column value.
+     * @param scalar The Protobuf scalar type.
+     * @param longAsString Whether a 64-bit value uses its generated string form.
+     * @returns The scalar column type.
+     */
+    readonly scalar: <V = unknown>(scalar: ScalarType, longAsString?: boolean) => RecordColumnType<V>;
+    /**
+     * Declares an enum type for a derived column value.
+     * @param schema The generated enum descriptor.
+     * @returns The enum column type.
+     */
+    readonly enum: <V = unknown>(schema: DescEnum) => RecordColumnType<V>;
+    /**
+     * Declares a message type for a derived column value.
+     * @param schema The generated message descriptor.
+     * @returns The message column type.
+     */
+    readonly message: <V = unknown>(schema: DescMessage) => RecordColumnType<V>;
+    /**
+     * Retains the singular value type declared by a generated Protobuf field.
+     * @param field The generated field descriptor.
+     * @returns The corresponding column type.
+     * @throws Error when the field is repeated or a map.
+     */
+    readonly fromField: <V = unknown>(field: DescField) => RecordColumnType<V>;
+};
+export {};
+//# sourceMappingURL=column-type.d.ts.map

package/dist/record/column-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-type.d.ts","sourceRoot":"","sources":["../../src/record/column-type.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEvF,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CACxC;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B,CACJ,GAAG;IAGF;;OAEG;IACH,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;CAChC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;IAGtB;;;;;OAKG;sBACI,CAAC,oBACE,UAAU,iBACH,OAAO,KACrB,gBAAgB,CAAC,CAAC,CAAC;IAItB;;;;OAIG;oBACE,CAAC,oBAAoB,QAAQ,KAAG,gBAAgB,CAAC,CAAC,CAAC;IAIxD;;;;OAIG;uBACK,CAAC,oBAAoB,WAAW,KAAG,gBAAgB,CAAC,CAAC,CAAC;IAI9D;;;;;OAKG;yBACO,CAAC,mBAAmB,SAAS,KAAG,gBAAgB,CAAC,CAAC,CAAC;CAiBrD,CAAC"}

package/dist/record/column-type.js

@@ -0,0 +1,69 @@
+/*
+ * 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.
+ */
+/**
+ * Creates record-column types from generated Protobuf descriptors.
+ */
+export const ColumnTypes = {
+    // prettier-ignore
+    /**
+     * Declares a scalar type for a derived column value.
+     * @param scalar The Protobuf scalar type.
+     * @param longAsString Whether a 64-bit value uses its generated string form.
+     * @returns The scalar column type.
+     */
+    scalar(scalar, longAsString) {
+        return Object.freeze({ kind: "scalar", scalar, longAsString: longAsString ?? false });
+    },
+    /**
+     * Declares an enum type for a derived column value.
+     * @param schema The generated enum descriptor.
+     * @returns The enum column type.
+     */
+    enum(schema) {
+        return Object.freeze({ kind: "enum", enum: schema });
+    },
+    /**
+     * Declares a message type for a derived column value.
+     * @param schema The generated message descriptor.
+     * @returns The message column type.
+     */
+    message(schema) {
+        return Object.freeze({ kind: "message", message: schema });
+    },
+    /**
+     * Retains the singular value type declared by a generated Protobuf field.
+     * @param field The generated field descriptor.
+     * @returns The corresponding column type.
+     * @throws Error when the field is repeated or a map.
+     */
+    fromField(field) {
+        switch (field.fieldKind) {
+            case "scalar":
+                return Object.freeze({
+                    kind: "scalar",
+                    scalar: field.scalar,
+                    longAsString: field.longAsString,
+                });
+            case "enum":
+                return Object.freeze({ kind: "enum", enum: field.enum });
+            case "message":
+                return Object.freeze({ kind: "message", message: field.message });
+            case "list":
+            case "map":
+                throw new Error(`Record column "${field.name}" must have one singular value.`);
+        }
+    },
+};
+Object.freeze(ColumnTypes);
+//# sourceMappingURL=column-type.js.map

package/dist/record/column-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-type.js","sourceRoot":"","sources":["../../src/record/column-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+DH;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,kBAAkB;IAElB;;;;;OAKG;IACH,MAAM,CACJ,MAAkB,EAClB,YAAsB;QAEtB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,IAAI,KAAK,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAc,MAAgB;QAChC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAc,MAAmB;QACtC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAc,KAAgB;QACrC,QAAQ,KAAK,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,QAAQ;gBACX,OAAO,MAAM,CAAC,MAAM,CAAC;oBACnB,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,YAAY,EAAE,KAAK,CAAC,YAAY;iBACjC,CAAC,CAAC;YACL,KAAK,MAAM;gBACT,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3D,KAAK,SAAS;gBACZ,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,KAAK,MAAM,CAAC;YACZ,KAAK,KAAK;gBACR,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,CAAC,IAAI,iCAAiC,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;CACO,CAAC;AACX,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { RecordColumnType } from "./column-type.js";
+/**
+ * Queryable column calculated from a stored record.
+ */
+export declare class RecordColumn<R extends object, V = unknown> {
+    #private;
+    readonly name: string;
+    readonly type: RecordColumnType<V>;
+    /**
+     * Creates a named column reader.
+     * @param name The stable column name.
+     * @param type The generated Protobuf value type.
+     * @param read The record value reader.
+     */
+    constructor(name: string, type: RecordColumnType<V>, read: (record: R) => V);
+    /**
+     * Reads the stored column value from a record snapshot.
+     * @param record The record snapshot.
+     * @returns The column value.
+     */
+    valueIn(record: R): V;
+}
+//# sourceMappingURL=record-column.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-column.d.ts","sourceRoot":"","sources":["../../src/record/record-column.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;GAEG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO;;IAUnD,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;IARpC;;;;;OAKG;gBAEQ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAClC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC;IAKxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC;CAGtB"}

package/dist/record/record-column.js

@@ -0,0 +1,41 @@
+/*
+ * 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.
+ */
+/**
+ * Queryable column calculated from a stored record.
+ */
+export class RecordColumn {
+    name;
+    type;
+    #read;
+    /**
+     * Creates a named column reader.
+     * @param name The stable column name.
+     * @param type The generated Protobuf value type.
+     * @param read The record value reader.
+     */
+    constructor(name, type, read) {
+        this.name = name;
+        this.type = type;
+        this.#read = read;
+    }
+    /**
+     * Reads the stored column value from a record snapshot.
+     * @param record The record snapshot.
+     * @returns The column value.
+     */
+    valueIn(record) {
+        return this.#read(record);
+    }
+}
+//# sourceMappingURL=record-column.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-column.js","sourceRoot":"","sources":["../../src/record/record-column.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;GAEG;AACH,MAAM,OAAO,YAAY;IAUZ;IACA;IAVF,KAAK,CAAmB;IAEjC;;;;;OAKG;IACH,YACW,IAAY,EACZ,IAAyB,EAClC,IAAsB;QAFb,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAqB;QAGlC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAS;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;CACF"}

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

@@ -0,0 +1,11 @@
+/**
+ * Represents dotted record paths retained by a masked read.
+ */
+export type RecordMask = readonly string[];
+/**
+ * Provides record-mask operations.
+ */
+export declare const RecordMask: Readonly<{
+    apply<R>(record: R, mask: RecordMask | undefined): R;
+}>;
+//# sourceMappingURL=record-mask.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-mask.d.ts","sourceRoot":"","sources":["../../src/record/record-mask.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,MAAM,EAAE,CAAC;AAM3C;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC;IAChC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,CAAC,CAAC;CACtD,CAkBC,CAAC"}

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