turbine-orm 0.19.2 → 0.22.0

package/dist/query/builder.d.ts

@@ -14,6 +14,12 @@ import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+/**
+ * Runs a SQL statement and resolves its raw result. Passed to a
+ * {@link DeferredQuery.reselect} plan so it can run the write and the follow-up
+ * SELECT through the same timeout/instrumentation path as the primary query.
+ */
+export type ReselectExecutor = (sql: string, params: unknown[], preparedName?: string) => Promise<pg.QueryResult>;
 export interface DeferredQuery<T> {
     /** SQL text with $1, $2 placeholders */
     sql: string;
@@ -25,6 +31,15 @@ export interface DeferredQuery<T> {
     tag: string;
     /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
     preparedName?: string;
+    /**
+     * Execution plan for dialects whose {@link Dialect.resultStrategy} is
+     * `'reselect'` (no RETURNING — e.g. MySQL). Owns the statement ordering: it
+     * runs the write and the follow-up row-fetching SELECT(s) via `exec`, and
+     * resolves the result whose rows {@link DeferredQuery.transform} consumes.
+     * Absent for `'returning'`/`'output'` dialects (the statement returns its own
+     * rows), so the PostgreSQL path never allocates or consults it.
+     */
+    reselect?: (exec: ReselectExecutor) => Promise<pg.QueryResult>;
 }
 /** Middleware function type — imported from client to avoid circular deps */
 export type MiddlewareFn = (params: {
@@ -83,6 +98,14 @@ export interface QueryInterfaceOptions {
     _txScoped?: boolean;
     /** @internal Callback from TurbineClient for query event emission. */
     _onQuery?: (event: QueryEvent) => void;
+    /**
+     * @internal Factory that builds the per-table query interface. Defaults to
+     * `new QueryInterface` (the SQL path). Non-SQL backends (PowDB) supply a
+     * factory returning a structurally-compatible interface that generates their
+     * own query language instead of SQL. The SQL dialects never set this, so their
+     * `table()` behavior is byte-identical.
+     */
+    queryInterfaceFactory?: (pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => QueryInterface<object>;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -133,6 +156,54 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private q;
     /** Return the active dialect's placeholder for a 1-indexed parameter position. */
     private p;
+    /**
+     * Cast an aggregate expression to an integer/float result type through the
+     * active dialect. PostgreSQL keeps the historical postfix cast (`expr::int` /
+     * `expr::float`); SQLite (no `::` operator) maps to `CAST(expr AS INTEGER/REAL)`.
+     * Falls back to the Postgres postfix cast for dialects without the hook.
+     */
+    private castAgg;
+    /**
+     * Build the trailing pagination clause for an OUTER SELECT. PostgreSQL/MySQL/
+     * SQLite use ` LIMIT <ph>` and/or ` OFFSET <ph>`. SQL Server has no `LIMIT`, so
+     * its dialect implements {@link Dialect.buildLimitOffset} to emit
+     * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
+     * Param-push order (limit before offset) is owned by the caller and unchanged —
+     * this only varies the SQL text, so PG output stays byte-identical.
+     */
+    private buildPagination;
+    /**
+     * The single-row limit appended to findUnique / findFirst-style lookups. ` LIMIT 1`
+     * for PG/MySQL/SQLite; SQL Server routes through {@link Dialect.buildLimitOffset}
+     * (literal `1`, no params) → ` ORDER BY (SELECT NULL) OFFSET 0 ROWS FETCH NEXT 1
+     * ROWS ONLY`. No params are pushed, so the collect path is unaffected.
+     */
+    private limitOneClause;
+    /**
+     * Validate a LIMIT/OFFSET value as a non-negative integer and return it as an
+     * inline SQL literal. Used only on `dialect.inlineLimitOffset` engines (MySQL).
+     * The input is always a Turbine-controlled pagination value, never a raw user
+     * string — and this guard guarantees the output is `String` of a validated
+     * integer, so inlining cannot inject SQL.
+     */
+    private limitOffsetLiteral;
+    /**
+     * Resolve a LIMIT/OFFSET value to either an inline literal (no param pushed, on
+     * `dialect.inlineLimitOffset` engines) or a bound placeholder (the value is
+     * pushed to `params`). Build and collect paths both gate on the same flag so
+     * the param order stays mirrored; PG/SQLite/SQL Server keep parameterizing and
+     * stay byte-identical.
+     */
+    private paginationRef;
+    /**
+     * Build an `IN` / `NOT IN` predicate through the active dialect. PostgreSQL
+     * keeps the array-param form (`expr = ANY($n)` / `expr != ALL($n)`); other
+     * engines (SQLite) use a length-independent single-placeholder form. Paired
+     * with {@link inParam}, which supplies the single bound value.
+     */
+    private inClause;
+    /** The single bound parameter for an `IN` list (PG: the array; SQLite: a JSON string). */
+    private inParam;
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -164,6 +235,33 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
     private queryWithTimeout;
+    /**
+     * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
+     * the active dialect's {@link Dialect.resultStrategy}, then apply its
+     * transform.
+     *
+     *   - `'returning'` / `'output'`: the statement returns its own affected rows
+     *     (`RETURNING *` / `OUTPUT INSERTED.*`). Byte-identical to the historical
+     *     single `queryWithTimeout` + `transform(result)` path — the PostgreSQL
+     *     route is unchanged.
+     *   - `'reselect'`: the engine cannot return rows from a write, so the build
+     *     method attached a {@link DeferredQuery.reselect} plan that runs the
+     *     write and a follow-up SELECT; the SELECT's rows feed the transform.
+     */
+    private executeMutation;
+    /**
+     * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
+     * by a write's `where` clause. Used by the `'reselect'` result strategy to
+     * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
+     * builder as reads, so no user value is interpolated.
+     */
+    private buildReselectByWhere;
+    /**
+     * Best-effort extraction of an auto-generated primary key from a write
+     * result for `'reselect'` engines (e.g. mysql2's `insertId`). Returns
+     * `undefined` when the driver exposes no such field.
+     */
+    private mutationInsertId;
     /**
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
@@ -232,6 +330,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
     create(args: CreateArgs<T, R>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
+    /**
+     * Build the `'reselect'` plan for {@link buildCreate}: run the INSERT, then
+     * `SELECT * WHERE pk = ?`. Returns `undefined` (skipped) unless the active
+     * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
+     * pays nothing. Not yet wired to a real non-RETURNING engine.
+     */
+    private makeCreateReselect;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
     update(args: UpdateArgs<T, R>): Promise<T>;