turbine-orm 0.19.2 → 0.22.0

package/dist/powql.d.ts

@@ -0,0 +1,153 @@
+/**
+ * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * {@link QueryInterface}). It exposes the same public method surface as the SQL
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
+ * pipeline language, not SQL — executed through {@link PowdbPool}.
+ *
+ * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
+ * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
+ * `SELECT … FROM … WHERE`, so the SQL `Dialect` seam cannot express it. Keeping
+ * it separate also means the four SQL engines are untouched.
+ *
+ * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
+ * `docs/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * server):
+ *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
+ *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
+ *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     accept `returning`, so it reselects the row by PK.
+ *   - The PK is generated client-side (UUID) when the column has a default.
+ *   - `with` (nested relations) degrades to **batched N+1 loaders** — D
+ *     round-trips for depth D, not one query. manyToMany is Phase B.
+ *   - pgvector / JSON / array filters and cursor streaming throw
+ *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *
+ * @module
+ */
+import { type PowdbPool } from './powdb.js';
+import type { MiddlewareFn, QueryInterfaceOptions } from './query/index.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
+import { type SchemaMetadata } from './schema.js';
+/**
+ * The PowQL query interface. Constructed by `turbinePowDB` via the
+ * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
+ * `TurbineClient.table()` can return it transparently.
+ */
+export declare class PowqlInterface<T extends object = Record<string, unknown>> {
+    private readonly pool;
+    private readonly table;
+    private readonly schema;
+    private readonly middlewares;
+    private readonly options;
+    private readonly meta;
+    private readonly defaultLimit?;
+    private readonly warnOnUnlimited;
+    private readonly onQuery?;
+    private currentAction;
+    private warnedUnlimited;
+    constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /** Resolve a camelCase field name (or raw snake) to its column metadata. */
+    private column;
+    /** PowQL column reference (`.snake_name`) for a field. */
+    private ref;
+    /**
+     * Push a value into the param array and return its `$N` placeholder. When the
+     * value targets a `float` column it is wrapped in {@link PowdbFloatParam} so
+     * the *embedded* literal encoder emits a float-form literal even for an
+     * integer value (PowQL's `42` is an int literal, `42.0` a float). The
+     * networked driver unwraps the marker back to the plain number in
+     * {@link toPowdbParam}, so the wire param is unchanged.
+     */
+    private param;
+    /**
+     * Render a value for a write *assignment* (`col := …`). Every value — float
+     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * the int→float UPDATE coercion bug (`score := $n` with an integer param now
+     * reads back the integer value, not the raw i64 bits), so the float-literal
+     * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
+     * float-typed for the *embedded* literal encoder (which materializes params
+     * into PowQL text) so an integer-valued float still encodes as a float literal
+     * and coercion stays unambiguous. Non-finite floats are still rejected.
+     */
+    private writeRef;
+    private isFloatCol;
+    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    private alwaysFalse;
+    /**
+     * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
+     * value as a positional `$N` param. Returns `''` when there are no conditions.
+     */
+    private buildWhere;
+    /** Build a single `field: value | operator` condition. */
+    private buildFieldCondition;
+    /** Bind a value, lowercasing for case-insensitive comparisons. */
+    private bind;
+    /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
+    private bindLike;
+    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    private buildInList;
+    /**
+     * Relation filter (`some`/`none`/`every`) via the verified IN-subquery form
+     * `Outer filter .localKey in (Target filter <e> { .targetKey })`. `exists`
+     * correlation is unreliable on PowDB, so it is never used.
+     */
+    private buildRelationFilter;
+    /** Resolve the set of columns to project, honouring `select` / `omit`. */
+    private projectedColumns;
+    /** `{ .c1, .c2, … }` projection clause. */
+    private projection;
+    /** `order .c1 asc, .c2 desc` clause (empty string when no orderBy). */
+    private buildOrder;
+    /** Run PowQL with optional timeout, emitting a query event either way. */
+    private exec;
+    private emit;
+    /** Run a method body through the middleware chain (mirrors QueryInterface). */
+    private withMiddleware;
+    /** Map raw rows to typed entities. */
+    private shape;
+    findMany(args?: FindManyArgs<T>): Promise<T[]>;
+    /** Build + run the flat findMany select; returns raw rows. */
+    private runFind;
+    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
+    findFirst(args?: FindManyArgs<T>): Promise<T | null>;
+    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
+    findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
+    /** Load each requested relation for `parents` and attach it onto each row. */
+    private loadRelations;
+    /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
+    private scalarData;
+    /** Fill in a client-generated UUID for a defaulted PK that wasn't supplied. */
+    private applyPkDefault;
+    create(args: CreateArgs<T>): Promise<T>;
+    createMany(args: CreateManyArgs<T>): Promise<T[]>;
+    update(args: UpdateArgs<T>): Promise<T>;
+    updateMany(args: UpdateManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    /** Compile `data` into PowQL update assignments, including atomic operators. */
+    private buildUpdateAssignments;
+    delete(args: DeleteArgs<T>): Promise<T>;
+    deleteMany(args: DeleteManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    count(args?: CountArgs<T>): Promise<number>;
+    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
+    /** `having <expr>` over group aggregates (count/sum/avg/min/max). */
+    private buildHaving;
+    findManyStream(): AsyncGenerator<T>;
+    /** Reselect a single row by its single-column primary key value. */
+    private reselectByPk;
+    /**
+     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
+     * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
+     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
+     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * because emitting a filter-less write would hit every row.
+     */
+    private assertCompiledWhere;
+}
+//# sourceMappingURL=powql.d.ts.map