turbine-orm 0.81.0 → 0.90.0

package/dist/query/utils.d.ts

@@ -3,6 +3,7 @@
  *
  * Standalone utility functions and classes used by the query builder.
  */
+import { type TurbineLogger } from '../logger.js';
 /**
  * Quote a SQL identifier (table name, column name) using Postgres double-quote
  * rules: wrap in double quotes, escape internal double quotes by doubling them.
@@ -243,6 +244,14 @@ export interface SqlCacheEntry {
      * a warmed template cannot regain one. See `buildCacheEntry` in builder.ts.
      */
     name: string;
+    /**
+     * How many params the build pushed, i.e. the statement's placeholder count.
+     * A cache hit whose collect path produces a different count is refused with
+     * an InvariantError before anything is sent. Optional so an entry built
+     * outside the cache (a test fixture) still type-checks; such an entry skips
+     * the count check.
+     */
+    paramCount?: number;
 }
 /**
  * FNV-1a 64-bit hash returning 16 lowercase hex chars.
@@ -258,6 +267,81 @@ export declare function fnv1a64Hex(s: string): string;
  * @internal Exported for testing only.
  */
 export declare function sqlToPreparedName(sql: string): string;
+/**
+ * How many distinct statement names one process hands out. Every connection
+ * keeps each named statement it has prepared, at 9 to 45 KB of server memory
+ * apiece, until the connection closes, so the number of names is what bounds
+ * that memory. A statement past the budget is sent unnamed: parsed on every
+ * execution and never kept, which costs a few microseconds on a cheap query.
+ */
+export declare const PREPARED_STATEMENT_BUDGET = 200;
+/**
+ * The prepared-statement name for `sql`, or `''` (send it unnamed) once the
+ * process has named {@link PREPARED_STATEMENT_BUDGET} other statements.
+ *
+ * The first shapes a process runs keep their names for its lifetime, which in
+ * practice are its hot shapes. A server-side `DEALLOCATE` cannot replace this:
+ * a pooled query does not know which connection it will run on, and a
+ * connection keeps every name it ever prepared.
+ */
+export declare function boundedPreparedName(sql: string): string;
+/**
+ * Claim an already derived statement name from the same budget as
+ * {@link boundedPreparedName}: `name` itself, or `''` (send it unnamed) once
+ * the budget is spent. `sqlComment`'s `c_` names (query/sql-comment.ts) are
+ * claimed here, so a commented statement costs one slot like any other.
+ */
+export declare function claimPreparedName(name: string): string;
+/** @internal Tests only: forget every name handed out. */
+export declare function resetPreparedNameBudget(): void;
+/** The `params` object a middleware receives. */
+export interface MiddlewareParams {
+    model: string;
+    action: string;
+    args: Record<string, unknown>;
+}
+/**
+ * The `params` a middleware receives. `params.args` is a plain copy of the
+ * caller's args, made when it is first read, so middleware can read it, spread
+ * it, serialize it and `structuredClone` it, and one that never reads it pays
+ * nothing.
+ *
+ * It is a copy because the query is compiled from the caller's args, not from
+ * what middleware sees. A change to the copy would never reach the query, so
+ * {@link assertMiddlewareArgsKept} refuses it, naming the path, when the
+ * middleware calls `next`. That check compares contents, which is why the copy
+ * is not frozen: a frozen object ignores a write silently in a script that is
+ * not in strict mode, and a filter added there would be dropped without a word.
+ * Assigning to `params.args` itself throws at once.
+ */
+export declare function readOnlyMiddlewareParams(model: string, action: string, args: Record<string, unknown>): MiddlewareParams;
+/**
+ * Refuse a `next(p)` whose `p.args` is not the caller's args: one that
+ * middleware changed in place, or replaced with an object that differs from
+ * them. A copy that is structurally equal passes (`structuredClone(params.args)`,
+ * `{ ...params.args }`), because nothing it would change is lost. Throws a
+ * TypeError naming the first path that differs.
+ */
+export declare function assertMiddlewareArgsKept(handedOut: MiddlewareParams, passed: {
+    args?: unknown;
+} | undefined): void;
+/** Whether `pool` is a node-postgres `Pool`, whose checkouts are real backend connections. */
+export declare function isNodePostgresPool(pool: unknown): boolean;
+/** Whether `client` is a node-postgres connection a cancel request can reach. */
+export declare function canCancelBackend(client: unknown): boolean;
+/**
+ * Ask the server to cancel whatever `client`'s backend is running, with the
+ * protocol's CancelRequest: a separate short connection carrying the backend's
+ * process id and secret key. No login, no session state, and a pooler forwards
+ * it to the right server backend, which `pg_cancel_backend(pid)` through a
+ * pooler would not.
+ *
+ * Resolves `true` once the server has closed the cancel connection, i.e. has
+ * signalled the backend; `false` when the request could not be delivered
+ * within `waitMs`. A cancel that arrives after the statement finished is
+ * ignored by the server.
+ */
+export declare function sendCancelRequest(client: unknown, waitMs: number): Promise<boolean>;
 /** Known operator keys, used to detect operator objects vs plain values */
 export declare const OPERATOR_KEYS: Set<string>;
 /**
@@ -339,6 +423,20 @@ export declare function coerceTemporalValue(dbType: string | undefined, value: u
  * as-is.
  */
 export declare function parseDbDate(value: string): Date;
+/**
+ * A float column's value as the driver reads it. JSON has no NaN or infinity,
+ * so `json_build_object` renders them as the strings "NaN", "Infinity" and
+ * "-Infinity"; every other value passes through.
+ */
+export declare function readJsonFloat(value: unknown): unknown;
+/** {@link readJsonFloat} over a float array (at any depth); the input when nothing changes. */
+export declare function readJsonFloatArray(value: unknown): unknown;
+/**
+ * An array column the driver has no parser for (an enum array) arrives as
+ * Postgres array text, `{ok,sad}`; read it into an array of strings, as the
+ * same column reads through a relation. The input when it cannot be parsed.
+ */
+export declare function readTextArray(value: unknown): unknown;
 /**
  * Is `value` one of the two representations a Postgres temporal `infinity` /
  * `-infinity` reaches the ORM row parser in?
@@ -547,7 +645,7 @@ export declare function isDefaultTextParser(oid: number, parser: (text: string)
  * construction, and only when somebody else's non-default parser is actually
  * being replaced.
  */
-export declare function warnParserOverwrite(oid: number, typeName: string): void;
+export declare function warnParserOverwrite(oid: number, typeName: string, logger?: TurbineLogger): void;
 /**
  * Register Turbine's temporal text parsers on the pg module. SIX OIDs, doing
  * two different jobs:
@@ -582,7 +680,7 @@ export declare function warnParserOverwrite(oid: number, typeName: string): void
  * per row at decode time, not captured per pool). If any of the four OIDs is
  * already on a NON-default parser, {@link warnParserOverwrite} says so once.
  */
-export declare function registerUtcTemporalParsers(): void;
+export declare function registerUtcTemporalParsers(logger?: TurbineLogger): void;
 /**
  * Postgres type name → OID, for every type family whose `json_build_object`
  * rendering is NOT the value the pg driver produces for the same column.
@@ -707,7 +805,7 @@ export declare function availableClause(names: readonly string[], emptySentence:
  */
 export declare function relationInProjectionMessage(table: string, field: string, clause: 'select' | 'omit'): string;
 /**
- * Dev-only advisory for a sort/grouping term Turbine dropped as redundant
+ * Advice (`diagnostics.advice`) for a sort/grouping term Turbine dropped as redundant
  * (`filters.ts` `dedupeOrderEntries` / `dedupeColumnList`).
  *
  * Deliberately a WARNING and not an error, and deliberately not silent either.
@@ -716,14 +814,15 @@ export declare function relationInProjectionMessage(table: string, field: string
  * plus an unconditional primary-key tiebreak, which collide exactly when the
  * caller sorts by the primary key). But a caller who wrote the duplicate by
  * hand, or who believes a second key is doing something, should hear about it
- * once. Dev-only for the usual reason: it describes the QUERY the application
+ * once. Advice for the usual reason: it describes the QUERY the application
  * sends, which does not vary with the environment, so a production process
- * learns nothing from repeating it.
+ * learns nothing from repeating it. The caller passes its advice logger, or
+ * `undefined` when advice is off.
  *
  * Keyed per dropped key, so a sort assembled per request from the same UI says
  * it once rather than once per request.
  */
-export declare function warnRedundantSortTerm(table: string, clause: string, dropped: readonly {
+export declare function warnRedundantSortTerm(advice: TurbineLogger | undefined, table: string, clause: string, dropped: readonly {
     key: string;
     first: string;
     resolved: string;