turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/dialect.d.ts

@@ -220,6 +220,51 @@ export interface LimitOffsetInput {
     /** Whether the outer SELECT already carries an ORDER BY (so none must be injected). */
     hasOrderBy: boolean;
 }
+/**
+ * Inputs for {@link Dialect.buildPartitionLimit}, the per-correlation-key row
+ * bound the batched relation loader pushes into its follow-up query.
+ *
+ * The follow-up is one flat `WHERE fk = ANY($1)` over EVERY parent's children,
+ * so a trailing `LIMIT n` would cap the TOTAL rather than the per-parent count.
+ * A window function is the portable-in-shape way to say "at most n rows per
+ * key": rank inside the partition, then keep the ranks at or below the bound.
+ *
+ * The loader hands over the compiled child SELECT and the pieces it cannot
+ * spell engine-independently; the dialect owns the SQL text (and its aliases),
+ * exactly like {@link buildLimitOffset} and {@link buildRelationSubquery}.
+ */
+export interface PartitionLimitInput {
+    /** The compiled child SELECT, to be wrapped as a derived table. */
+    innerSql: string;
+    /** RAW (unquoted) correlation column to partition by. */
+    partitionColumn: string;
+    /**
+     * The window's (and the outer result's) ordering, as RAW column names.
+     *
+     * NEVER EMPTY, and never a partial order: the loader only asks for this
+     * rewrite when the relation's `orderBy` covers a NOT NULL unique key of the
+     * target table, so no two rows of a partition can tie. That precondition is
+     * the whole licence for the rewrite. The join plan takes its `limit` with a
+     * per-parent `ORDER BY … LIMIT n` and this takes it with a rank over one flat
+     * result, and where ties exist the two are each free to keep different rows,
+     * which was measured happening (see `partitionOrderBy` in
+     * query/batched-loader.ts). Anything short of a total order therefore keeps
+     * the client-side slice instead of arriving here.
+     */
+    orderBy: readonly {
+        column: string;
+        direction: 'ASC' | 'DESC';
+        nulls?: 'FIRST' | 'LAST';
+    }[];
+    /** SQL-ready placeholder for the bound (`$3`, `?`, …). */
+    limitPlaceholder: string;
+    /**
+     * RAW name of the rank column the wrapper adds. It is part of the projection
+     * (`SELECT <outer>.*`), so the CALLER must remove it from each raw row before
+     * parsing, or it would surface as an extra field on every child entity.
+     */
+    rankColumn: string;
+}
 /**
  * Everything an engine needs to OVERRIDE nested-relation subquery generation, for
  * dialects whose JSON-aggregation shape is fundamentally different from PostgreSQL's
@@ -345,6 +390,37 @@ export interface Dialect {
     readonly supportsUpsertUpdateWhere?: boolean;
     /** Whether this dialect/engine supports pgvector distance ops (KNN / distance WHERE). */
     readonly supportsVector: boolean;
+    /**
+     * Whether this dialect/engine can actually answer JSON CONTAINMENT, i.e. the
+     * pathless `{ contains }` and `{ equals }` JSON filters that compile through
+     * {@link buildJsonContains}.
+     *
+     * A capability flag rather than a per-operand hook, because the answer turned
+     * out not to vary by operand. SQLite emulates containment as
+     * `EXISTS (SELECT 1 FROM json_each(col) WHERE value = $1)` while the param is
+     * bound as JSON TEXT, and `json_each.value` yields the DECODED SQL value, so
+     * the comparison is between two different encodings and never holds. Measured
+     * against a real in-process SQLite, every operand type returned zero rows:
+     *
+     *   stored              filter                PG        SQLite
+     *   ["gold"]            contains: 'gold'      match     none   ('gold' = '"gold"')
+     *   [1]                 contains: 1           match     none   (INTEGER 1 = TEXT '1')
+     *   {"a":1,"t":"gold"}  contains: { a: 1 }    match     none   (no structural walk)
+     *
+     * So the feature has never worked on that engine at all, and refusing it
+     * removes nothing that functioned. Fewer-rows-with-no-error is the exact
+     * degrade the capability contract exists to convert into a refusal.
+     *
+     * Repairing it rather than refusing it is possible and deliberately not done
+     * here: `json_each` exposes a `type` column ('text' / 'integer' / 'real' /
+     * 'true' / 'false' / 'null'), so a faithful scalar test is
+     * `type = $1 AND value IS $2`. That is a param-COUNT change on a path whose
+     * build and collect sides must stay in lockstep, which is a different change
+     * from this one. Until then the flag is honest and the error names the
+     * alternative that is exact today (`{ path: [...], equals }`, which compiles
+     * to `json_extract`).
+     */
+    readonly supportsJsonContains: boolean;
     /**
      * Whether this dialect/engine supports the PostgreSQL full-text `search`
      * filter (`to_tsvector(...) @@ to_tsquery(...)`). Optional: absent is treated
@@ -454,6 +530,28 @@ export interface Dialect {
     readonly supportsILike: boolean;
     /** Build a case-insensitive LIKE equivalent. */
     buildInsensitiveLike(column: string, paramRef: string): string;
+    /**
+     * Escape the LIKE metacharacters of this engine in a bound `contains` /
+     * `startsWith` / `endsWith` / `stringContains` operand. Optional: when a
+     * dialect omits it the shared {@link escapeLike} is used, which escapes the
+     * SQL-standard set (`\`, `%`, `_`) and pairs with the `ESCAPE '\'` clause the
+     * builders always emit.
+     *
+     * It exists because the standard set is not the whole set everywhere:
+     * T-SQL's `LIKE` also treats `[` as opening a character CLASS, so
+     * `{ contains: '[draft]' }` becomes "contains any one of d, r, a, f, t" on
+     * SQL Server, a silently over-broad predicate on an engine where every other
+     * dialect agrees the value is a literal. That is not injection (the operand
+     * is still bound), but it is a wrong answer, and the difference is a property
+     * of the ENGINE's pattern grammar, not of the SQL text, which is why it is a
+     * dialect hook rather than a branch in the where builder.
+     *
+     * Whatever a dialect returns MUST be escaped for the same `ESCAPE '\'`
+     * clause, i.e. a backslash prefix, and MUST be identical on the SQL-build and
+     * the cache-hit param-collect paths (both call this one hook, so they cannot
+     * drift).
+     */
+    escapeLikePattern?(value: string): string;
     /** JSON operator support level for this dialect. */
     readonly jsonPathSupport: 'native' | 'function' | 'limited';
     /** Build a JSON containment check. */
@@ -601,6 +699,31 @@ export interface Dialect {
      * param-push-ordering contract the override must honor.
      */
     buildRelationSubquery?(ctx: RelationSubqueryContext): string;
+    /**
+     * Bound a batched relation follow-up to at most N rows per correlation key,
+     * by wrapping the compiled child SELECT in a `ROW_NUMBER() OVER (PARTITION
+     * BY …)` filter. See {@link PartitionLimitInput} for why a trailing `LIMIT`
+     * cannot express this.
+     *
+     * OPTIONAL, and absent means "no pushdown": the batched loader then fetches
+     * every matching child and applies the per-relation `limit` client-side, the
+     * behaviour every engine had before this hook existed. That fallback is
+     * correct but unbounded in bytes over the wire (200 parents x ~505 children
+     * with `limit: 3` measured 101,000 rows fetched to keep 600, +52.9 MB peak
+     * heap against +0.5 MB for the join plan), which is why PostgreSQL
+     * implements it. Only PostgreSQL does in this release; the other engines keep
+     * the client-side slice, so their emitted SQL is byte-identical to before.
+     *
+     * The client-side slice is NOT removed when a dialect implements this: it
+     * stays as the belt-and-braces bound, and is a no-op once the engine has
+     * already limited each partition. It is also still the whole mechanism for
+     * any relation whose `orderBy` does not TOTALLY order the target table, on
+     * every engine including this one: a rewrite that reaches here has to return
+     * the same rows the join plan's per-parent `ORDER BY … LIMIT n` returns, and
+     * with ties present neither plan's choice is forced. See
+     * {@link PartitionLimitInput.orderBy}.
+     */
+    buildPartitionLimit?(input: PartitionLimitInput): string;
 }
 export interface DialectIntrospector {
     introspect(options: IntrospectOptions): Promise<SchemaMetadata>;

package/dist/cjs/dialect.js

@@ -56,6 +56,7 @@ exports.postgresDialect = {
     nullJsonLiteral: 'NULL',
     aggSupportsInlineOrderBy: true,
     supportsVector: true,
+    supportsJsonContains: true,
     supportsFullTextSearch: true,
     supportsArrayColumns: true,
     supportsListenNotify: true,
@@ -294,6 +295,38 @@ exports.postgresDialect = {
             params: [name, value],
         };
     },
+    buildPartitionLimit(input) {
+        // Two wrapper levels, and both are needed: `ROW_NUMBER()` is a window
+        // function, so it cannot appear in the same WHERE that filters on it.
+        // Aliases are deliberately not in the `t<n>` family the relation builder
+        // allocates, so a future caller that wraps a query carrying those aliases
+        // cannot shadow one.
+        const inner = this.quoteIdentifier('turbine_pl_src');
+        const outer = this.quoteIdentifier('turbine_pl_rank');
+        const rank = this.quoteIdentifier(input.rankColumn);
+        const order = (ref) => input.orderBy
+            .map((o) => `${ref}.${this.quoteIdentifier(o.column)} ${o.direction}${o.nulls ? ` NULLS ${o.nulls}` : ''}`)
+            .join(', ');
+        // The empty-list branches are defensive only: the loader never asks for
+        // this rewrite without a total order (see the note on
+        // `PartitionLimitInput.orderBy`). An unordered window numbers each
+        // partition arbitrarily, and so does the join plan's ORDER-BY-less
+        // per-parent `LIMIT`, but they are different plans over different row sets
+        // and were measured choosing differently, so that shape keeps the loader's
+        // client-side slice rather than arriving here.
+        const windowOrder = input.orderBy.length > 0 ? ` ORDER BY ${order(inner)}` : '';
+        // The OUTER ordering is not cosmetic: the loader buckets children in result
+        // order, so without re-applying it here the relation array would come back
+        // in whatever order the rank filter happened to emit. It agrees with the
+        // window's own ordering by construction, since both are this one list and
+        // that list admits no ties, so the outer sort cannot pick a different order
+        // among the ranked rows than the rank did.
+        const outerOrder = input.orderBy.length > 0 ? ` ORDER BY ${order(outer)}` : '';
+        return (`SELECT ${outer}.* FROM (SELECT ${inner}.*, ROW_NUMBER() OVER (PARTITION BY ` +
+            `${inner}.${this.quoteIdentifier(input.partitionColumn)}${windowOrder}) AS ${rank} ` +
+            `FROM (${input.innerSql}) AS ${inner}) AS ${outer} ` +
+            `WHERE ${outer}.${rank} <= ${input.limitPlaceholder}${outerOrder}`);
+    },
     async *openStream(connection, sql, params, batchSize, opts) {
         // Cursors require a single connection inside a transaction: BEGIN → DECLARE
         // … NO SCROLL CURSOR FOR → FETCH n (loop) → CLOSE → COMMIT; ROLLBACK on

package/dist/cjs/errors.d.ts

@@ -47,6 +47,40 @@ export declare class TurbineError extends Error {
  * with `{ errorMessages: 'verbose' }`.
  */
 export type ErrorMessageMode = 'safe' | 'verbose';
+/**
+ * Register a client's configured mode and report whether per-operation scoping
+ * is now required.
+ *
+ * The gate is DIVERGENCE, not "has a client been built": while every client in
+ * the process agrees (the overwhelmingly common case, including every
+ * single-client app), the module default is already the right answer for all of
+ * them and no scope has to be established, so the query path pays exactly
+ * nothing. The moment two clients disagree, every client starts scoping, which
+ * is why this is read per call rather than latched per client.
+ *
+ * @internal Used by TurbineClient; not part of the public surface.
+ */
+export declare function registerClientErrorMessageMode(mode: ErrorMessageMode): void;
+/**
+ * Whether any two clients in this process have registered different modes, so
+ * the module default can no longer speak for all of them.
+ *
+ * @internal
+ */
+export declare function errorMessageModesDiverged(): boolean;
+/**
+ * Run `fn` with `mode` in force for everything it does, awaits included.
+ *
+ * Establishing the scope around the call (rather than threading a mode
+ * parameter into every error constructor) is what makes this reachable at all:
+ * the mode-sensitive errors are built deep inside the query executor, the write
+ * builders and the nested-write engine, none of which are handed the client.
+ * The async context is captured when the operation's promise chain is created
+ * INSIDE this call, so every continuation of it resolves the same mode.
+ *
+ * @internal
+ */
+export declare function runWithErrorMessageMode<R>(mode: ErrorMessageMode, fn: () => R): R;
 /**
  * Set the global NotFoundError message mode. Called from the TurbineClient
  * constructor when `TurbineConfig.errorMessages` is provided.
@@ -70,7 +104,14 @@ export type ErrorMessageMode = 'safe' | 'verbose';
  * leak, not as a log-scrubbing boundary.
  */
 export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
-/** Returns the current NotFoundError message mode. Exported for tests. */
+/**
+ * Returns the NotFoundError message mode in effect right now.
+ *
+ * Called inside an operation issued through a client whose mode differs from
+ * another client's in the same process, that is THAT client's mode; anywhere
+ * else it is the process default {@link setErrorMessageMode} last set, which is
+ * what it has always returned. Exported for tests.
+ */
 export declare function getErrorMessageMode(): ErrorMessageMode;
 /**
  * The marker left where a driver `detail` string was removed in 'safe' mode.
@@ -78,6 +119,17 @@ export declare function getErrorMessageMode(): ErrorMessageMode;
  * assertions can match on it without hardcoding the wording.
  */
 export declare const REDACTED_DETAIL = "[redacted by turbine errorMessages:\"safe\"]";
+/**
+ * Mark a driver error as carrying row values in its `message` (see
+ * {@link VALUE_BEARING_MESSAGE}). Called by the engine error augmenters for the
+ * exact driver codes whose message grammar embeds a value; every other code is
+ * left alone so nothing is withheld that did not need to be.
+ *
+ * Non-enumerable so the flag itself never shows up in a serialized error, and
+ * best-effort so a frozen or exotic driver error cannot turn a constraint
+ * violation into a TypeError.
+ */
+export declare function markValueBearingMessage<T>(err: T): T;
 /**
  * Render a user-supplied `where` / `connect` target for a "no row found" error
  * message, honoring the global {@link ErrorMessageMode}. In 'safe' mode (the
@@ -168,6 +220,27 @@ export declare class ConnectionError extends TurbineError {
         sqlstate?: string;
     });
 }
+/**
+ * The message for "this engine's connection string could not be parsed".
+ *
+ * The one rule it exists to enforce: NEVER echo the value. A DSN carries a
+ * password, and the trigger for this error is a MALFORMED DSN, which is exactly
+ * when someone pastes the failure into a bug report, a CI log, or an error
+ * tracker. No redaction written against the URL grammar can be trusted on a
+ * string that just failed to parse as a URL, so the only safe amount of it to
+ * include is none: not the password, not the host, not a prefix.
+ *
+ * This mirrors the Postgres path (`assertUsableConnectionString` in client.ts),
+ * which reached the same conclusion first and stated the same reason; the
+ * engines used to interpolate the raw string instead, so SECURITY.md's claim of
+ * redaction "in all CLI error output" was true for one engine out of four.
+ * Shared rather than copied so the three engines cannot drift back apart.
+ *
+ * @param engine  the human engine label ("MySQL", "SQL Server", "PowDB").
+ * @param example a well-formed connection string for that engine, with a
+ *   placeholder password. Never derived from the caller's value.
+ */
+export declare function malformedConnectionStringMessage(engine: string, example: string): string;
 /** Thrown when a relation reference is invalid */
 export declare class RelationError extends TurbineError {
     constructor(message: string);