@spine-event-engine/core 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/dist/query/entity-query.js

@@ -0,0 +1,841 @@
+/*
+ * 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, create, fromBinary, getOption, hasOption, ScalarType, toBinary, } from "@bufbuild/protobuf";
+import { BoolValueSchema, AnySchema, BytesValueSchema, DoubleValueSchema, FloatValueSchema, Int32ValueSchema, Int64ValueSchema, StringValueSchema, UInt32ValueSchema, UInt64ValueSchema, } from "@bufbuild/protobuf/wkt";
+import { ActorContextSchema, VersionSchema, type_url_prefix, } from "@spine-event-engine/proto";
+import { CompositeFilterSchema, CompositeFilter_CompositeOperator, FilterSchema, Filter_Operator, IdFilterSchema, OrderBySchema, OrderBy_Direction, QueryIdSchema, QuerySchema, ResponseFormatSchema, TargetFiltersSchema, TargetSchema, } from "@spine-event-engine/proto/client";
+import { EntityColumn, } from "../entity/entity-column.js";
+import { EntityFieldClassification } from "./entity-field-classification.js";
+const maximumPredicateDepth = 64;
+const maximumPredicateNodes = 10_000;
+const queryHost = globalThis;
+/**
+ * Builds a typed Entity query for the frozen Spine wire contract.
+ *
+ * @typeParam Schema Generated Entity state schema selected by the query.
+ * @typeParam Columns Registered columns for that state schema.
+ */
+export class EntityQueryBuilder {
+    #schema;
+    #context;
+    #columns;
+    #ids = [];
+    #predicates = [];
+    #order = [];
+    #limit;
+    /**
+     * Creates a builder for one Entity query.
+     *
+     * @param input Schema, registered columns, and actor context for the query.
+     */
+    constructor(input) {
+        this.#schema = input.schema;
+        this.#columns = input.columns;
+        this.#context = clone(ActorContextSchema, input.context);
+    }
+    /**
+     * Adds Entity IDs to the query target.
+     *
+     * @param ids Entity IDs to include.
+     * @returns This builder.
+     */
+    byId(...ids) {
+        if (ids.length === 0 || ids.some((id) => id === undefined)) {
+            throw new TypeError("Entity query ID filter must not be empty.");
+        }
+        this.#ids.push(...ids);
+        return this;
+    }
+    /**
+     * Adds a typed predicate. Repeated calls are combined with `ALL`.
+     *
+     * @typeParam Predicate Predicate type checked against the registered columns.
+     * @param predicate Predicate owned by this builder's registered columns.
+     * @returns This builder.
+     */
+    where(predicate) {
+        if (this.#predicates.length >= maximumPredicateNodes) {
+            throw new TypeError(`Entity query predicate exceeds maximum node count ${String(maximumPredicateNodes)}.`);
+        }
+        this.#predicates.push(predicate);
+        return this;
+    }
+    /**
+     * Adds one ordering clause in caller order.
+     *
+     * @typeParam Column Registered ordered column type.
+     * @param column Ordered column owned by this builder's Entity schema.
+     * @param direction Sort direction, ascending by default.
+     * @returns This builder.
+     */
+    orderBy(column, direction = "asc") {
+        EntityQueryWire.requireOwnedColumn(this.#schema, this.#columns, column);
+        this.#order.push({ column, direction });
+        return this;
+    }
+    /**
+     * Sets a positive result limit that requires ordering.
+     *
+     * @param value Positive maximum number of returned entities.
+     * @returns This builder.
+     */
+    limit(value) {
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new TypeError("Entity query limit must be a positive integer.");
+        }
+        this.#limit = value;
+        return this;
+    }
+    /**
+     * Builds the `spine.client.Query` message.
+     *
+     * @returns The wire query message.
+     */
+    build() {
+        if (this.#limit !== undefined && this.#order.length === 0) {
+            throw new TypeError("Entity query limit requires ordering.");
+        }
+        const filters = this.#filters();
+        const format = this.#format();
+        return create(QuerySchema, {
+            id: create(QueryIdSchema, { value: EntityQueryWire.nextId() }),
+            target: create(TargetSchema, {
+                type: EntityQueryWire.typeUrl(this.#schema),
+                criterion: filters === undefined
+                    ? { case: "includeAll", value: true }
+                    : { case: "filters", value: filters },
+            }),
+            context: clone(ActorContextSchema, this.#context),
+            ...(format === undefined ? {} : { format }),
+        });
+    }
+    /**
+     * Builds the storage-neutral execution plan for this typed query.
+     *
+     * @returns An immutable plan equivalent to {@link build}'s wire query.
+     */
+    buildPlan() {
+        if (this.#limit !== undefined && this.#order.length === 0) {
+            throw new TypeError("Entity query limit requires ordering.");
+        }
+        const predicates = EntityQueryCompiler.compilePlanGroups(this.#predicates, this.#schema, this.#columns);
+        const all = [
+            ...(this.#ids.length === 0
+                ? []
+                : [Object.freeze({ kind: "ids", ids: Object.freeze([...this.#ids]) })]),
+            ...predicates,
+        ];
+        const predicate = all.length === 0
+            ? undefined
+            : all.length === 1
+                ? all[0]
+                : Object.freeze({ kind: "all", predicates: Object.freeze(all) });
+        return Object.freeze({
+            ...(predicate === undefined ? {} : { predicate }),
+            ...(this.#order.length === 0
+                ? {}
+                : {
+                    order: Object.freeze(this.#order.map(({ column, direction }) => Object.freeze({ column: column.name, direction }))),
+                }),
+            ...(this.#limit === undefined ? {} : { limit: this.#limit }),
+        });
+    }
+    #filters() {
+        const idField = this.#schema.fields[0];
+        if (this.#ids.length > 0 && idField === undefined) {
+            throw new TypeError("Entity query target has no ID field.");
+        }
+        const predicates = EntityQueryCompiler.compileGroups(this.#predicates, this.#schema, this.#columns);
+        if (this.#ids.length === 0 && predicates.length === 0)
+            return undefined;
+        return create(TargetFiltersSchema, {
+            ...(this.#ids.length === 0
+                ? {}
+                : {
+                    idFilter: create(IdFilterSchema, {
+                        id: this.#ids.map((id) => EntityQueryWire.packField(idField, id)),
+                    }),
+                }),
+            filter: [...predicates],
+        });
+    }
+    /**
+     * Builds wire ordering and limit settings when the query uses them.
+     */
+    #format() {
+        if (this.#order.length === 0 && this.#limit === undefined) {
+            return undefined;
+        }
+        return create(ResponseFormatSchema, {
+            orderBy: this.#order.map(({ column, direction }) => create(OrderBySchema, {
+                column: column.name,
+                direction: direction === "desc" ? OrderBy_Direction.DESCENDING : OrderBy_Direction.ASCENDING,
+            })),
+            limit: this.#limit ?? 0,
+        });
+    }
+}
+/**
+ * Context-free Entity query that can be executed by different actor and tenant scopes.
+ *
+ * @typeParam Schema Generated state schema selected by this query.
+ * @typeParam Id Identifier type declared by the state's first field.
+ */
+export class EntityQueryDescription {
+    #wire;
+    #plan;
+    #schema;
+    /**
+     * Captures the compiled wire query and storage plan without execution context.
+     *
+     * @param schema Generated state schema selected by the query.
+     * @param wire Compiled wire query without actor context or request ID.
+     * @param plan Compiled storage-neutral query plan.
+     */
+    constructor(schema, wire, plan) {
+        this.#schema = schema;
+        this.#wire = toBinary(QuerySchema, wire);
+        this.#plan = queryHost.structuredClone(plan);
+        Object.freeze(this);
+    }
+    /**
+     * Returns the generated state schema selected by this query.
+     *
+     * @returns Generated state schema.
+     */
+    get schema() {
+        return this.#schema;
+    }
+    /**
+     * Creates a fresh wire query without an actor or tenant context.
+     *
+     * @returns Wire query with a new request ID.
+     */
+    build() {
+        const wire = fromBinary(QuerySchema, this.#wire);
+        wire.id = create(QueryIdSchema, { value: EntityQueryWire.nextId() });
+        return wire;
+    }
+    /**
+     * Returns a detached storage-neutral plan for local execution.
+     *
+     * @returns Independent copy of the compiled plan.
+     */
+    buildPlan() {
+        return queryHost.structuredClone(this.#plan);
+    }
+}
+/**
+ * Builds an Entity query without selecting an actor or tenant.
+ *
+ * @typeParam Schema Generated Entity state schema.
+ * @typeParam Columns Registered columns for that schema.
+ * @typeParam Name Local name of the canonical first identifier field.
+ */
+export class EntityQueryDraft {
+    #schema;
+    #builder;
+    /**
+     * Creates a context-free draft for one registered Entity state.
+     *
+     * @param input State schema, columns, and canonical identifier field name.
+     */
+    constructor(input) {
+        if (input.schema.fields[0]?.localName !== input.idField) {
+            throw new TypeError("Entity query ID field must be the state's first declared field.");
+        }
+        this.#schema = input.schema;
+        this.#builder = new EntityQueryBuilder({
+            schema: input.schema,
+            columns: input.columns,
+            context: create(ActorContextSchema),
+        });
+    }
+    /**
+     * Adds typed identifiers to the query target.
+     *
+     * @param ids Identifier values declared by the first state field.
+     * @returns This draft.
+     */
+    byId(...ids) {
+        this.#builder.byId(...ids);
+        return this;
+    }
+    /**
+     * Adds a typed comparison or group predicate.
+     *
+     * @typeParam Predicate Predicate checked against the registered columns.
+     * @param predicate Predicate to append with conjunction.
+     * @returns This draft.
+     */
+    where(predicate) {
+        this.#builder.where(predicate);
+        return this;
+    }
+    /**
+     * Adds ordering by a registered ordered column.
+     *
+     * @typeParam Column Registered ordered column type.
+     * @param column Ordered column.
+     * @param direction Ascending or descending direction.
+     * @returns This draft.
+     */
+    orderBy(column, direction = "asc") {
+        this.#builder.orderBy(column, direction);
+        return this;
+    }
+    /**
+     * Sets a positive result limit that requires ordering.
+     *
+     * @param value Maximum number of matching states.
+     * @returns This draft.
+     */
+    limit(value) {
+        this.#builder.limit(value);
+        return this;
+    }
+    /**
+     * Builds an independent query description for later execution.
+     *
+     * @returns Context-free query value with detached wire and plan copies.
+     */
+    build() {
+        const wire = this.#builder.build();
+        wire.context = undefined;
+        wire.id = undefined;
+        return new EntityQueryDescription(this.#schema, wire, this.#builder.buildPlan());
+    }
+}
+/**
+ * Creates typed predicates and builders for Entity queries.
+ */
+export const EntityQuery = Object.freeze({
+    /**
+     * Creates a validated equality comparison for a registered column.
+     *
+     * @typeParam Column Column type used by the comparison.
+     * @param column Column to compare.
+     * @param value Value to match.
+     * @returns Immutable equality predicate.
+     */
+    eq(column, value) {
+        return EntityQueryCompiler.comparison(column, "equal", value);
+    },
+    /**
+     * Creates a validated exclusive lower-bound comparison.
+     *
+     * @typeParam Column Ordered column type used by the comparison.
+     * @param column Ordered column to compare.
+     * @param value Exclusive lower bound.
+     * @returns Immutable greater-than predicate.
+     */
+    gt(column, value) {
+        return EntityQueryCompiler.comparison(column, "greaterThan", value);
+    },
+    /**
+     * Creates a validated exclusive upper-bound comparison.
+     *
+     * @typeParam Column Ordered column type used by the comparison.
+     * @param column Ordered column to compare.
+     * @param value Exclusive upper bound.
+     * @returns Immutable less-than predicate.
+     */
+    lt(column, value) {
+        return EntityQueryCompiler.comparison(column, "lessThan", value);
+    },
+    /**
+     * Creates a validated inclusive lower-bound comparison.
+     *
+     * @typeParam Column Ordered column type used by the comparison.
+     * @param column Ordered column to compare.
+     * @param value Inclusive lower bound.
+     * @returns Immutable greater-or-equal predicate.
+     */
+    ge(column, value) {
+        return EntityQueryCompiler.comparison(column, "greaterOrEqual", value);
+    },
+    /**
+     * Creates a validated inclusive upper-bound comparison.
+     *
+     * @typeParam Column Ordered column type used by the comparison.
+     * @param column Ordered column to compare.
+     * @param value Inclusive upper bound.
+     * @returns Immutable less-or-equal predicate.
+     */
+    le(column, value) {
+        return EntityQueryCompiler.comparison(column, "lessOrEqual", value);
+    },
+    /**
+     * Combines a required predicate and the remaining predicates with conjunction.
+     *
+     * @typeParam First Type of the required first predicate.
+     * @typeParam Rest Tuple of additional predicate types.
+     * @param first Required first predicate.
+     * @param rest Additional predicates in caller order.
+     * @returns Immutable conjunction group.
+     */
+    all(first, ...rest) {
+        return EntityQueryCompiler.group("all", first, rest);
+    },
+    /**
+     * Combines a required predicate and the remaining predicates with disjunction.
+     *
+     * @typeParam First Type of the required first predicate.
+     * @typeParam Rest Tuple of additional predicate types.
+     * @param first Required first predicate.
+     * @param rest Additional predicates in caller order.
+     * @returns Immutable disjunction group.
+     */
+    either(first, ...rest) {
+        return EntityQueryCompiler.group("either", first, rest);
+    },
+    /**
+     * Creates a query builder bound to a state schema, its columns, and actor context.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @typeParam Columns Registered columns for that schema.
+     * @param input Schema, columns, and actor context for the query.
+     * @returns A mutable typed query builder.
+     */
+    select(input) {
+        return new EntityQueryBuilder(input);
+    },
+    /**
+     * Creates a context-free draft bound to the state's first identifier field.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @typeParam Columns Registered columns for that schema.
+     * @typeParam Name Local name of the state's first identifier field.
+     * @param input State schema, columns, and canonical identifier field name.
+     * @returns New context-free query draft.
+     */
+    describe(input) {
+        return new EntityQueryDraft(input);
+    },
+});
+/**
+ * Internal compiler for predicates, descriptors, and wire query messages.
+ */
+const EntityQueryCompiler = Object.freeze({
+    /**
+     * Validates predicate graphs and compiles them to storage-neutral plan nodes.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @param roots Top-level predicates in query order.
+     * @param schema State schema selected by the query.
+     * @param columns Registered columns allowed in comparisons.
+     * @returns Validated immutable plan predicates.
+     */
+    compilePlanGroups(roots, schema, columns) {
+        // Reuse the iterative wire traversal as the single validation boundary. The
+        // storage plan has the same predicate graph but must not recurse before
+        // cycle, depth, and breadth limits have been checked.
+        EntityQueryCompiler.compileGroups(roots, schema, columns);
+        return roots.map((predicate) => EntityQueryCompiler.compilePlanPredicate(predicate, schema, columns));
+    },
+    /**
+     * Converts a validated predicate tree to a storage-neutral plan node.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @param value Predicate tree to convert.
+     * @param schema State schema selected by the query.
+     * @param columns Registered columns allowed in comparisons.
+     * @returns Immutable comparison or logical group plan.
+     */
+    compilePlanPredicate(value, schema, columns) {
+        const predicate = EntityQueryWire.requirePredicate(value);
+        if (predicate.kind === "comparison") {
+            EntityQueryWire.requireOwnedColumn(schema, columns, predicate.column);
+            EntityQueryWire.requireValue(predicate.column, predicate.value);
+            return Object.freeze({
+                kind: "comparison",
+                column: predicate.column.name,
+                operator: predicate.operator,
+                value: predicate.value,
+            });
+        }
+        if (predicate.predicates.length === 0) {
+            throw new TypeError(`${predicate.kind.toUpperCase()} predicate must not be empty.`);
+        }
+        return Object.freeze({
+            kind: predicate.kind,
+            predicates: Object.freeze(predicate.predicates.map((child) => EntityQueryCompiler.compilePlanPredicate(child, schema, columns))),
+        });
+    },
+    /**
+     * Validates a comparison operator and value before freezing its predicate.
+     *
+     * @typeParam Column Column type used by the comparison.
+     * @param column Column that supports the selected operator.
+     * @param operator Comparison supported by the column.
+     * @param value Typed comparison value.
+     * @returns Immutable comparison predicate.
+     */
+    comparison(column, operator, value) {
+        if (!column.operators.includes(operator)) {
+            throw new TypeError(`Entity column "${column.name}" does not support ${operator}.`);
+        }
+        EntityQueryWire.requireValue(column, value);
+        return Object.freeze({ kind: "comparison", column, operator, value });
+    },
+    /**
+     * Builds an immutable conjunction or disjunction in caller order.
+     *
+     * @typeParam First Type of the required first predicate.
+     * @typeParam Rest Tuple of additional predicate types.
+     * @param kind Logical operation for the group.
+     * @param first Required first predicate.
+     * @param rest Additional predicates.
+     * @returns Immutable typed predicate group.
+     */
+    group(kind, first, rest) {
+        return Object.freeze({
+            kind,
+            predicates: Object.freeze([first, ...rest]),
+        });
+    },
+    /**
+     * Validates a predicate graph and encodes it as wire composite filters.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @param roots Top-level predicates in query order.
+     * @param schema State schema selected by the query.
+     * @param columns Registered columns allowed in comparisons.
+     * @returns Composite filters for the wire query.
+     */
+    compileGroups(roots, schema, columns) {
+        const compiled = new WeakMap();
+        const seen = new WeakSet();
+        const pending = [];
+        let scheduled = 0;
+        for (let index = roots.length - 1; index >= 0; index -= 1) {
+            pending.push({ predicate: roots[index], depth: 0, expanded: false });
+            scheduled += 1;
+        }
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined)
+                break;
+            const predicate = EntityQueryWire.requirePredicate(current.predicate);
+            if (current.expanded) {
+                if (predicate.kind === "comparison") {
+                    throw new TypeError("Entity query predicate compilation state is invalid.");
+                }
+                const simple = [];
+                const nested = [];
+                for (const child of predicate.predicates) {
+                    const childResult = compiled.get(child);
+                    if (childResult === undefined)
+                        throw new TypeError("Entity query predicate is incomplete.");
+                    if (childResult.kind === "comparison")
+                        simple.push(childResult.filter);
+                    else
+                        nested.push(childResult.filter);
+                }
+                compiled.set(predicate, {
+                    kind: "group",
+                    filter: create(CompositeFilterSchema, {
+                        operator: predicate.kind === "either"
+                            ? CompositeFilter_CompositeOperator.EITHER
+                            : CompositeFilter_CompositeOperator.ALL,
+                        filter: simple,
+                        compositeFilter: nested,
+                    }),
+                });
+                continue;
+            }
+            if (seen.has(predicate))
+                throw new TypeError("Entity query predicate must not contain cycles.");
+            seen.add(predicate);
+            if (current.depth > maximumPredicateDepth) {
+                throw new TypeError(`Entity query predicate exceeds maximum depth ${String(maximumPredicateDepth)}.`);
+            }
+            if (predicate.kind === "comparison") {
+                EntityQueryWire.requireOwnedColumn(schema, columns, predicate.column);
+                compiled.set(predicate, {
+                    kind: "comparison",
+                    filter: EntityQueryWire.compileComparison(predicate),
+                });
+                continue;
+            }
+            if (predicate.predicates.length === 0) {
+                throw new TypeError(`${predicate.kind.toUpperCase()} predicate must not be empty.`);
+            }
+            if (scheduled + predicate.predicates.length > maximumPredicateNodes) {
+                throw new TypeError(`Entity query predicate exceeds maximum node count ${String(maximumPredicateNodes)}.`);
+            }
+            scheduled += predicate.predicates.length;
+            pending.push({ ...current, expanded: true });
+            for (let index = predicate.predicates.length - 1; index >= 0; index -= 1) {
+                if (!Object.hasOwn(predicate.predicates, index)) {
+                    throw new TypeError("Entity query predicate entries must be defined.");
+                }
+                pending.push({
+                    predicate: predicate.predicates[index],
+                    depth: current.depth + 1,
+                    expanded: false,
+                });
+            }
+        }
+        return roots.map((root) => {
+            const result = compiled.get(root);
+            if (result === undefined)
+                throw new TypeError("Entity query predicate is incomplete.");
+            return result.kind === "group"
+                ? result.filter
+                : create(CompositeFilterSchema, {
+                    operator: CompositeFilter_CompositeOperator.ALL,
+                    filter: [result.filter],
+                });
+        });
+    },
+});
+/**
+ * Validates and compiles Entity query details.
+ */
+const EntityQueryWire = Object.freeze({
+    /**
+     * Checks the shape and kind of a predicate supplied at runtime.
+     *
+     * @param value Value to validate as a predicate.
+     * @returns Validated comparison or group predicate.
+     */
+    requirePredicate(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            throw new TypeError("Entity query predicate must be an object.");
+        }
+        const predicate = value;
+        if (predicate.kind === "comparison") {
+            if (!(predicate.column instanceof EntityColumn)) {
+                throw new TypeError("Entity query comparison column is required.");
+            }
+            return predicate;
+        }
+        if (predicate.kind !== "all" && predicate.kind !== "either") {
+            throw new TypeError("Entity query predicate kind must be recognized.");
+        }
+        if (!Array.isArray(predicate.predicates)) {
+            throw new TypeError(`${predicate.kind.toUpperCase()} predicate predicates must be an array.`);
+        }
+        return predicate;
+    },
+    /**
+     * Encodes a leaf comparison as a wire filter.
+     *
+     * @param predicate Validated column comparison.
+     * @returns Wire filter with packed value and operator.
+     */
+    compileComparison(predicate) {
+        return create(FilterSchema, {
+            fieldPath: { fieldName: [predicate.column.name] },
+            value: EntityQueryWire.packColumn(predicate.column, predicate.value),
+            operator: EntityQueryWire.wireOperator(predicate.operator),
+        });
+    },
+    /**
+     * Maps a supported column comparison to its wire enum value.
+     *
+     * @param operator Comparison operator to encode.
+     * @returns Matching wire filter operator.
+     */
+    wireOperator(operator) {
+        switch (operator) {
+            case "equal":
+                return Filter_Operator.EQUAL;
+            case "greaterThan":
+                return Filter_Operator.GREATER_THAN;
+            case "lessThan":
+                return Filter_Operator.LESS_THAN;
+            case "greaterOrEqual":
+                return Filter_Operator.GREATER_OR_EQUAL;
+            case "lessOrEqual":
+                return Filter_Operator.LESS_OR_EQUAL;
+            default:
+                throw new TypeError("Entity query comparison operator is not recognized.");
+        }
+    },
+    /**
+     * Packs a system or application column value into a wire Any message.
+     *
+     * @param column Column whose value is being encoded.
+     * @param value Typed comparison value.
+     * @returns Packed wire value for the column.
+     */
+    packColumn(column, value) {
+        if (column.source === "system") {
+            if (column.name === "version")
+                return EntityQueryWire.packMessage(VersionSchema, value);
+            return EntityQueryWire.packMessage(BoolValueSchema, create(BoolValueSchema, { value: value }));
+        }
+        if (column.descriptor === undefined) {
+            throw new TypeError("Entity query application column descriptor is required.");
+        }
+        return EntityQueryWire.packField(column.descriptor, value);
+    },
+    /**
+     * Packs a descriptor field value using its message, enum, or scalar wrapper.
+     *
+     * @param field Descriptor for the compared state field.
+     * @param value Field value to encode.
+     * @returns Packed wire value for the field.
+     */
+    packField(field, value) {
+        if (field === undefined)
+            throw new TypeError("Entity query field descriptor is required.");
+        EntityQueryWire.requireFieldValue(field, value);
+        if (field.fieldKind === "message") {
+            return EntityQueryWire.packMessage(field.message, value);
+        }
+        if (field.fieldKind === "enum") {
+            return EntityQueryWire.packMessage(Int32ValueSchema, create(Int32ValueSchema, { value: value }));
+        }
+        if (field.fieldKind !== "scalar")
+            throw new TypeError("Entity query field kind is unsupported.");
+        const schema = EntityQueryWire.scalarSchema(field.scalar);
+        return EntityQueryWire.packMessage(schema, create(schema, { value }));
+    },
+    /**
+     * Checks an ID or column operand against its declared Protobuf field kind.
+     *
+     * @param field Declared state field used by the query.
+     * @param value Operand to validate before wire packing.
+     */
+    requireFieldValue(field, value) {
+        const facts = EntityFieldClassification.classify(field);
+        if (!facts.supported)
+            throw new TypeError(`Entity query field "${field.name}" is unsupported.`);
+        const valid = facts.valueKind === "message"
+            ? typeof value === "object" &&
+                value !== null &&
+                Reflect.get(value, "$typeName") === facts.messageType
+            : facts.valueKind === "bytes"
+                ? value instanceof Uint8Array
+                : facts.valueKind === "enum" || facts.valueKind === "number"
+                    ? typeof value === "number" && Number.isFinite(value)
+                    : typeof value === facts.valueKind;
+        if (!valid)
+            throw new TypeError(`Entity query value for "${field.name}" has the wrong type.`);
+    },
+    /**
+     * Returns the Protobuf wrapper schema for a scalar field type.
+     *
+     * @param scalar Protobuf scalar type of the field.
+     * @returns Wrapper schema used for its query value.
+     */
+    scalarSchema(scalar) {
+        switch (scalar) {
+            case ScalarType.BOOL:
+                return BoolValueSchema;
+            case ScalarType.BYTES:
+                return BytesValueSchema;
+            case ScalarType.DOUBLE:
+                return DoubleValueSchema;
+            case ScalarType.FLOAT:
+                return FloatValueSchema;
+            case ScalarType.INT64:
+            case ScalarType.SFIXED64:
+            case ScalarType.SINT64:
+                return Int64ValueSchema;
+            case ScalarType.UINT64:
+            case ScalarType.FIXED64:
+                return UInt64ValueSchema;
+            case ScalarType.UINT32:
+            case ScalarType.FIXED32:
+                return UInt32ValueSchema;
+            case ScalarType.STRING:
+                return StringValueSchema;
+            default:
+                return Int32ValueSchema;
+        }
+    },
+    /**
+     * Verifies that a column is registered for the selected state schema.
+     *
+     * @typeParam Schema Generated Entity state schema.
+     * @param schema State schema selected by the query.
+     * @param columns Registered columns for that schema.
+     * @param column Column referenced by a predicate or order clause.
+     */
+    requireOwnedColumn(schema, columns, column) {
+        if (column.schema !== schema ||
+            !Object.values(columns).some((candidate) => candidate === column)) {
+            throw new TypeError("Entity query column does not belong to the selected target.");
+        }
+    },
+    /**
+     * Validates a comparison value against its column's declared value kind.
+     *
+     * @param column Column that declares the required value kind.
+     * @param value Comparison value to validate.
+     */
+    requireValue(column, value) {
+        const valid = value !== undefined &&
+            (column.valueKind === "message"
+                ? typeof value === "object" &&
+                    value !== null &&
+                    Reflect.get(value, "$typeName") === column.messageType
+                : column.valueKind === "bytes"
+                    ? value instanceof Uint8Array
+                    : column.valueKind === "enum" || column.valueKind === "number"
+                        ? typeof value === "number" && Number.isFinite(value)
+                        : typeof value === column.valueKind);
+        if (!valid)
+            throw new TypeError(`Entity query value for "${column.name}" has the wrong type.`);
+    },
+    /**
+     * Finds a generated field by wire or local name.
+     *
+     * @param schema Message schema to search.
+     * @param name Wire or local field name.
+     * @returns Matching field descriptor, if present.
+     */
+    findField(schema, name) {
+        return schema.fields.find((field) => field.name === name || field.localName === name);
+    },
+    /**
+     * Creates a time-prefixed random identifier for a wire query.
+     *
+     * @returns New query ID string.
+     */
+    nextId() {
+        return `query-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    },
+    /**
+     * Builds a type URL from a schema's configured prefix and type name.
+     *
+     * @param schema Message schema whose URL is required.
+     * @returns Fully qualified Protobuf type URL.
+     */
+    typeUrl(schema) {
+        const prefix = hasOption(schema.file, type_url_prefix)
+            ? getOption(schema.file, type_url_prefix)
+            : "type.googleapis.com";
+        return `${prefix.replace(/\/+$/u, "")}/${schema.typeName}`;
+    },
+    /**
+     * Serializes a message value into a wire Any without unknown fields.
+     *
+     * @typeParam Schema Generated schema of the message value.
+     * @param schema Schema used to serialize the value.
+     * @param value Message value matching the schema.
+     * @returns Any message containing the type URL and binary value.
+     */
+    packMessage(schema, value) {
+        return create(AnySchema, {
+            typeUrl: EntityQueryWire.typeUrl(schema),
+            value: toBinary(schema, value, { writeUnknownFields: false }),
+        });
+    },
+});
+//# sourceMappingURL=entity-query.js.map