@spooky-sync/query-builder 0.0.1-canary.37 → 0.0.1-canary.371

package/src/types.ts

@@ -23,6 +23,79 @@ export interface QueryInfo {
   query: string;
   hash: number;
   vars?: Record<string, unknown>;
+  /**
+   * Engine-neutral description of the same SELECT, used by non-SurrealQL local
+   * cache backends (e.g. SQLite) that cannot parse the `query` string. Only
+   * populated for `SELECT` (undefined for LIVE/UPDATE/DELETE). See `QueryPlan`.
+   */
+  plan?: QueryPlan;
+}
+
+/**
+ * A single WHERE comparison. `value` is the resolved value (string IDs already
+ * converted to `RecordId`); when `paramRef` is set the condition references an
+ * existing query param verbatim (`$name`) instead of an inline value. `swap`
+ * flips the operands (`value op field`), mirroring `ComparisonOp._swap`.
+ */
+export interface WhereComparison {
+  field: string;
+  op: ComparisonOp['_op'];
+  value: unknown;
+  paramRef?: string;
+  swap?: boolean;
+}
+
+/** A parenthesised `(c1 OR c2 …)` group, from a `_or` fragment. */
+export interface WhereOr {
+  or: WhereComparison[];
+}
+
+/**
+ * Engine-neutral WHERE: a top-level conjunction (AND) of comparisons and/or
+ * OR-groups. Mirrors `buildQueryFromOptions`'s condition assembly exactly.
+ */
+export type WhereNode = WhereComparison | WhereOr;
+
+/**
+ * Engine-neutral description of a SELECT query. Backends render it to their own
+ * dialect (SurrealQL, SQLite, …). Relations are resolved by the caller via
+ * level-ordered decomposition rather than nested projection, so `relations`
+ * carries the tree rather than a flattened subquery string.
+ */
+export interface QueryPlan {
+  table: string;
+  /** Projection field names; undefined means all (`*`). */
+  select?: string[];
+  where?: WhereNode[];
+  orderBy?: [field: string, direction: 'asc' | 'desc'][];
+  limit?: number;
+  offset?: number;
+  relations?: RelationPlan[];
+  /**
+   * Window materialization: when set, the base rows are EXACTLY these record
+   * ids (the window the SSP already computed), ignoring `where`/`limit`/
+   * `offset`. `orderBy`, `select` and `relations` still apply. Set by
+   * {@link buildWindowMaterializationPlan}; see `window-query.ts`.
+   */
+  ids?: unknown[];
+}
+
+/**
+ * One `.related()` edge in a {@link QueryPlan}. Correlation:
+ * - `one`  → parent[`foreignKeyField`] = child.id  (attach `bucket[0] ?? null`)
+ * - `many` → child[`foreignKeyField`] = parent.id   (attach `bucket`)
+ * `limit`/`orderBy` are applied PER PARENT during decomposition.
+ */
+export interface RelationPlan {
+  alias: string;
+  table: string;
+  cardinality: 'one' | 'many';
+  foreignKeyField: string;
+  select?: string[];
+  where?: WhereNode[];
+  orderBy?: [field: string, direction: 'asc' | 'desc'][];
+  limit?: number;
+  relations?: RelationPlan[];
 }
 
 export interface RelatedQuery {
@@ -36,17 +109,58 @@ export interface RelatedQuery {
   cardinality: 'one' | 'many';
 }
 
+/**
+ * Comparison-operator descriptor for a single WHERE field, e.g.
+ * `{ _op: '<=', _val: 5 }` → `field <= $field`. A `$`-prefixed string `_val`
+ * references an existing query param verbatim; `_swap: true` flips the operands
+ * (`$val _op field`). Plain values still mean equality (`field = $field`).
+ */
+export interface ComparisonOp {
+  _op: '=' | '!=' | '>' | '>=' | '<' | '<=' | (string & {});
+  _val: unknown;
+  _swap?: boolean;
+}
+
+/** A single WHERE field value: an equality value or a comparison descriptor. */
+export type WhereFieldValue<V> = V | ComparisonOp;
+
+/** A flat conjunction of field conditions (equality or comparison). */
+export type WhereConditions<TModel extends GenericModel> = {
+  [K in keyof TModel]?: WhereFieldValue<TModel[K]>;
+};
+
+/**
+ * WHERE input for `.where()`. Supports equality (`{ field: value }`), comparison
+ * operators (`{ field: { _op, _val } }`), and a single top-level `_or` group of
+ * condition fragments that compile to a parenthesised `(... OR ...)` conjunct —
+ * e.g. `{ _or: [{ white: x }, { black: x }] }` → `(white = $white__or0 OR black = $black__or1)`.
+ * Backward-compatible with plain `Partial<TModel>` equality objects.
+ */
+export type WhereInput<TModel extends GenericModel> = WhereConditions<TModel> & {
+  _or?: WhereConditions<TModel>[];
+};
+
 export interface QueryOptions<TModel extends GenericModel, IsOne extends boolean> {
   select?: ((keyof TModel & string) | '*')[];
-  where?: Partial<TModel>;
+  where?: WhereInput<TModel>;
   limit?: number;
   offset?: number;
   orderBy?: Partial<Record<keyof TModel, 'asc' | 'desc'>>;
   /** Related tables to include via subqueries */
   related?: RelatedQuery[];
   isOne?: IsOne;
+  /**
+   * Set by `.ignoreUnusedArgs()`: the caller knows some parts of this query
+   * are ignored where it is used (a channel only reads the `where`), so no
+   * warning is wanted. Not part of the query: never changes surql or hash.
+   */
+  ignoreUnusedArgs?: boolean;
 }
 
+/** A user a channel connects to: a record id, its string form, or nothing. */
+export type ChannelPeer = string | { toString(): string } | null | undefined;
+
+
 export type LiveQueryOptions<TModel extends GenericModel> = Omit<
   QueryOptions<TModel, boolean>,
   'orderBy'
@@ -78,7 +192,7 @@ export type SchemaAwareQueryModifier<
 
 // Simplified query builder interface for modifying subqueries
 export interface QueryModifierBuilder<TModel extends GenericModel> {
-  where(conditions: Partial<TModel>): this;
+  where(conditions: WhereInput<TModel>): this;
   select(...fields: ((keyof TModel & string) | '*')[]): this;
   limit(count: number): this;
   offset(count: number): this;
@@ -93,7 +207,7 @@ export interface SchemaAwareQueryModifierBuilder<
   TableName extends TableNames<S>,
   RelatedFields extends Record<string, any> = {},
 > {
-  where(conditions: Partial<TableModel<GetTable<S, TableName>>>): this;
+  where(conditions: WhereInput<TableModel<GetTable<S, TableName>>>): this;
   select(...fields: ((keyof TableModel<GetTable<S, TableName>> & string) | '*')[]): this;
   limit(count: number): this;
   offset(count: number): this;