turbine-orm 0.21.0 → 0.23.0

package/dist/powql.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 (a composite-PK upsert
+ *     reselects-or-writes inside one flat transaction).
+ *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
+ *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     generated client-side (UUID).
+ *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
+ *     depth D, not one query — including manyToMany (junction → targets).
+ *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
+ *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
+ *     PowDB's executor caches a subquery's result by plan shape and would return
+ *     a stale prior result for a later subquery of the same shape.
+ *   - **Nested writes** (relation ops in `create`/`update` data) run through the
+ *     shared nested-write engine as one flat top-level transaction (PowDB is
+ *     single-writer, no savepoints).
+ *   - 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;
+    /**
+     * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
+     * into a plain scalar `in`/`notIn` condition on the **local key**, by running
+     * the inner predicate as its own query and materializing the matching keys as
+     * a literal list. The compiled where is then relation-free and `buildWhere`
+     * emits only `in (<literal list>)`.
+     *
+     * Why not an IN-subquery (`.k in (Target filter <e> { .fk })`)? PowDB's
+     * executor caches a subquery's result by **plan shape, ignoring the literal**,
+     * so a second subquery of the same shape with a different value returns the
+     * first one's stale rows (reproduced live on the embedded engine; the
+     * single-statement literal `in (list)` form is always correct). Resolving
+     * client-side trades extra round-trips for correctness, and recurses — nested
+     * relation filters in the inner predicate resolve when the target query runs.
+     */
+    private resolveRelationFilters;
+    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    private resolveRelationCondition;
+    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
+    private resolveManyToManyCondition;
+    /** 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;
+    /**
+     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
+     * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
+     * each parent → its junction rows → its targets in memory. Mirrors the
+     * single-key N+1 loaders; the junction's source/target columns must be single
+     * (composite junction keys would need PowQL tuple-`in`, which it lacks).
+     */
+    private loadManyToMany;
+    /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
+    private scalarData;
+    /**
+     * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
+     * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
+     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
+     * it and the trailing `returning` reads it back — as is any non-string PK.
+     */
+    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;
+    private isTxScoped;
+    private nestedCreate;
+    private nestedUpdate;
+    /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
+    private runInImplicitTx;
+    /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
+    private buildNestedCtx;
+    delete(args: DeleteArgs<T>): Promise<T>;
+    deleteMany(args: DeleteManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    /**
+     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
+     * column, so reselect by the full composite PK and update-or-create inside one
+     * flat transaction (PowDB single-writer makes the read-then-write safe from
+     * concurrent writers; the transaction makes it atomic with the write).
+     */
+    private upsertComposite;
+    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