turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/query/compound-unique.d.ts

@@ -0,0 +1,51 @@
+/**
+ * turbine-orm — Prisma-style compound-unique `where` selectors.
+ *
+ * Prisma lets a `findUnique`-family `where` address a multi-column unique
+ * constraint through a single synthetic key holding the member columns:
+ *
+ * ```ts
+ * db.members.findUnique({ where: { orgId_userId: { orgId: 1, userId: 7 } } })
+ * // ≡ where: { orgId: 1, userId: 7 }  →  WHERE "org_id" = $1 AND "user_id" = $2
+ * ```
+ *
+ * {@link expandCompoundUniqueWhere} rewrites such a selector into the equivalent
+ * column conjunction BEFORE the where is fingerprinted / SQL-compiled, so the
+ * template cache only ever sees the canonical expanded form (no new cache-key
+ * segment, and the expanded shape shares its entry with the spelled-out form).
+ *
+ * Selector NAMES come from the table metadata, in priority order:
+ *   1. a composite primary key (length ≥ 2);
+ *   2. each composite `uniqueColumns` entry (introspected composite UNIQUE
+ *      constraints);
+ *   3. each composite UNIQUE index in `indexes` (`unique && !docPath &&
+ *      !partial`, the ONLY composite-unique source a `defineSchema` code-first
+ *      client has, since `defineSchema` records single-column uniques in
+ *      `uniqueColumns` and composite uniques as declared unique indexes). A
+ *      PARTIAL unique index is skipped: it only guarantees uniqueness over its
+ *      predicate's rows, not table-wide, so it cannot address a single row.
+ *
+ * For every column set two lookup names are registered (both mapping to the same
+ * ordered FIELD list): the underscore join of the camelCase FIELD names
+ * (`orgId_userId`, Prisma's default) and, when different, the underscore join of
+ * the raw snake_case column names (`org_id_user_id`).
+ *
+ * Collision rules (deterministic, documented):
+ *   - a synthetic name equal to a real field / column / relation name is never
+ *     registered (real members always win);
+ *   - two DIFFERENT column sets producing the same name drop that name entirely.
+ *
+ * The map is pure metadata, so it is computed lazily and memoized per
+ * {@link TableMetadata} in a module-level `WeakMap`.
+ */
+import type { TableMetadata } from '../schema.js';
+/**
+ * Expand any Prisma compound-unique selector keys in `where` into their column
+ * conjunction. Returns the SAME object reference when nothing expands (the
+ * byte-identical fast path), else a shallow clone with the selector keys
+ * replaced. A selector key whose members do not exactly match the constraint's
+ * fields throws a {@link ValidationError} (E003) naming the required members; a
+ * non-selector unknown key is left untouched to fall through to the existing
+ * unknown-column error at SQL-build time.
+ */
+export declare function expandCompoundUniqueWhere(meta: TableMetadata, where: Record<string, unknown>): Record<string, unknown>;

package/dist/cjs/query/deferred.d.ts

@@ -0,0 +1,223 @@
+/**
+ * turbine-orm — Deferred query + QueryInterface option types
+ *
+ * Split from builder.ts so the class file focuses on SQL assembly / execution.
+ */
+import type pg from 'pg';
+import type { Dialect } from '../dialect.js';
+import type { SchemaMetadata } from '../schema.js';
+import type { QueryInterface } from './builder.js';
+import type { GlobalFilters, RelationLoadStrategy } 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;
+    /** Bound parameter values */
+    params: unknown[];
+    /** How to transform the raw pg.QueryResult into the final value */
+    transform: (result: pg.QueryResult) => T;
+    /** Tag for debugging / logging */
+    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: {
+    model: string;
+    action: string;
+    args: Record<string, unknown>;
+}, next: (params: {
+    model: string;
+    action: string;
+    args: Record<string, unknown>;
+}) => Promise<unknown>) => Promise<unknown>;
+/** Emitted after every query execution (success or failure). */
+export interface QueryEvent {
+    sql: string;
+    params: unknown[];
+    duration: number;
+    model: string;
+    action: string;
+    rows: number;
+    timestamp: Date;
+    error?: Error;
+    /**
+     * Set to `'auto-batched'` on the statements of a query whose
+     * `relationLoadStrategy: 'auto'` engaged the per-relation batched fallback
+     * (the base statement and every batched follow-up). Absent for the plain join
+     * path, explicit `'join'`/`'batched'`, and non-auto queries, so production
+     * observability can see exactly which queries the auto default re-planned.
+     */
+    strategy?: 'auto-batched';
+}
+export type QueryEventListener = (event: QueryEvent) => void;
+/** Options passed from TurbineClient to QueryInterface */
+export interface QueryInterfaceOptions {
+    /** Default LIMIT applied to findMany() when no limit is specified */
+    defaultLimit?: number;
+    /**
+     * Log a one-time warning when {@link QueryInterface.findMany} is called
+     * without a `limit`. Defaults to `true` so that accidental unbounded
+     * queries are surfaced loudly during development. Pass `false` to silence
+     * the warning entirely (e.g. for CLI tooling that intentionally streams
+     * full tables), or a per-table map (`{ userProfiles: false }`) to silence
+     * only the tables that intentionally read full sets — unlisted tables keep
+     * the default. Map keys accept BOTH the camelCase accessor name
+     * (`userProfiles`) and the snake_case table name (`user_profiles`); the
+     * snake_case entry wins if both are present. Individual calls can also
+     * override via `findMany({ warnOnUnlimited: false })`.
+     */
+    warnOnUnlimited?: boolean | Record<string, boolean>;
+    /**
+     * Enable prepared statements. When true, queries are submitted with a
+     * `{ name, text, values }` object to the pg driver, which caches the
+     * parse+plan on the server per connection.
+     *
+     * Default: `true` for Turbine-owned pools, `false` for external pools
+     * (serverless drivers may not support named statements).
+     */
+    preparedStatements?: boolean;
+    /**
+     * Enable the SQL template cache. When true, repeated queries with the
+     * same shape (same keys, operators, relations, different values) reuse
+     * cached SQL text instead of rebuilding from scratch.
+     *
+     * Default: `true`. Set to `false` as a nuclear kill switch.
+     *
+     * Dev-mode safety net: when `NODE_ENV !== 'production'`, every cache HIT is
+     * cross-checked by rebuilding the SQL + params fresh and comparing them
+     * against the cache-hit result, catching any drift between the fingerprint,
+     * SQL-build, and param-collect paths (which has silently corrupted results
+     * before). A mismatch throws a `ValidationError` (E003). This runs only
+     * outside production, so it never touches the production hot path. Set the
+     * env var `TURBINE_DISABLE_CACHE_CHECK=1` to opt out when dev traffic is
+     * perf-sensitive.
+     *
+     * Production sampling: the check is off in production by default. Set
+     * `TURBINE_CACHE_CHECK_SAMPLE` to a float in `(0,1]` to re-verify that
+     * fraction of cache hits under real load (e.g. `0.001` for one in a
+     * thousand). A sampled mismatch logs `console.error` once per distinct
+     * fingerprint AND throws the same `ValidationError` (E003). `0`, unset, or an
+     * unparseable value keeps the check fully off.
+     */
+    sqlCache?: boolean;
+    /**
+     * Maximum number of distinct SQL templates the per-table LRU cache retains.
+     *
+     * Default: `1000`. Raise it for apps with a very large number of distinct
+     * query SHAPES (not values, since values are parameterized and never fragment the
+     * cache) to lift the hit rate at the cost of memory; lower it to cap memory.
+     * `0` disables the cache entirely, exactly like `sqlCache: false`. A negative
+     * value is ignored (treated as the default). Applied per QueryInterface (one
+     * per table).
+     */
+    sqlCacheSize?: number;
+    /** SQL dialect implementation. Defaults to PostgreSQL. */
+    dialect?: Dialect;
+    /**
+     * Interpret offset-less timestamp strings (Postgres `timestamp` without
+     * time zone, and the JSON emitted by nested-relation subqueries) as UTC.
+     * This is the Prisma/Rails/Django convention and makes results independent
+     * of the server's local time zone. Default: `true`. Set `false` to restore
+     * the pre-0.26 behavior (JS local-time interpretation).
+     */
+    utcTimestamps?: boolean;
+    /**
+     * Client-level default relation-loading strategy for `with` clauses; a
+     * per-query `relationLoadStrategy` arg overrides it. On SQL engines the default
+     * is `'join'` (one single-statement `json_agg` query). On PowDB the default is
+     * the batched loaders, and `'join'` opts INTO native server-side joins where
+     * eligible (ineligible relations fall back to the loaders per-relation and
+     * silently; see the PowDB docs).
+     */
+    relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * When `true`, every to-many `with` relation that carries no explicit
+     * `orderBy` is loaded ordered by the target table's primary key ascending, so
+     * unordered child arrays come back in a deterministic order (json_agg / batched
+     * loaders otherwise leave child-array order engine-dependent). An explicit
+     * per-relation `orderBy` always wins, and a per-query `stableRelationOrder`
+     * overrides this default. Default `false`; when off the emitted SQL is
+     * byte-identical to before. SQL engines only (PowDB keeps its own defaults).
+     */
+    stableRelationOrder?: boolean;
+    /**
+     * When `true`, a `findMany` that paginates (`limit` / `take` / `offset`) but
+     * declares no `orderBy` is ordered by the table's primary key ascending
+     * (every column of a composite PK, in declaration order), making its pages
+     * deterministic. An explicit `orderBy` always wins, PK-less tables are left
+     * alone, and `distinct` / `cursor` shapes are skipped.
+     *
+     * Default `false` in core: an unordered `LIMIT` is non-deterministic, but
+     * adding an `ORDER BY` to SQL that existing applications already emit changes
+     * both the rows a page returns and the plan the engine picks, so the fix is
+     * opt-in until a major. `turbine-orm/prisma-compat` defaults it ON, since
+     * matching Prisma's semantics is that layer's contract. When off, the emitted
+     * SQL is byte-identical to before.
+     */
+    implicitPkOrdering?: boolean;
+    /**
+     * Parent-row ceiling for the `relationLoadStrategy: 'auto'` to-one rule: a
+     * to-one relation stays in the single-statement join when the query's `limit`
+     * bounds the parent set at or under this many rows, and loads batched when the
+     * query is unbounded or bounded above it (a correlated to-one subquery is
+     * re-evaluated per parent row regardless of indexing). Defaults to
+     * `AUTO_TO_ONE_JOIN_MAX_ROWS` (1000); `0` sends every unbounded-or-limited
+     * to-one relation batched. Ignored under an explicit `'join'` / `'batched'`.
+     */
+    autoToOneJoinMaxRows?: number;
+    /**
+     * Round-trip time to the database, in milliseconds, used to DERIVE the
+     * `relationLoadStrategy: 'auto'` to-one threshold instead of guessing a row
+     * count. Prefer this over `autoToOneJoinMaxRows`: the break-even between the
+     * single-statement join and the batched follow-up is
+     * `roundTripMs / AUTO_JOIN_PENALTY_MS_PER_ROW`, and measurement shows the
+     * per-row penalty is a constant of the plan while the break-even moves ~17x
+     * between a loopback link and a 2.7ms one. Set it to what `ping` says (a
+     * Unix socket is ~0.05, same-region managed Postgres ~0.5-2, cross-region
+     * ~30-60). Defaults to `AUTO_ASSUMED_ROUND_TRIP_MS` (0.7ms, same-region),
+     * which reproduces the historical 1000-row threshold exactly. Overridden by
+     * an explicit `autoToOneJoinMaxRows`; only consulted under `'auto'`.
+     */
+    autoRoundTripMs?: number;
+    /**
+     * How nested-relation subqueries encode each row's JSON: `'object'` (default,
+     * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see
+     * {@link Dialect.buildJsonArray}). Positional is Postgres-only in v1; a
+     * `with` clause on any other dialect throws `UnsupportedFeatureError` (E017).
+     */
+    jsonEncoding?: 'object' | 'positional';
+    /**
+     * Automatic WHERE filters keyed by table accessor, AND-merged into every
+     * query on that table and every relation subquery targeting it (soft-delete /
+     * multi-tenancy). Function values are evaluated at query-build time. See
+     * {@link GlobalFilters}.
+     */
+    globalFilters?: GlobalFilters;
+    /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
+    _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>;
+}

package/dist/cjs/query/filters.d.ts

@@ -0,0 +1,201 @@
+/**
+ * turbine-orm — Where-filter type guards and shape helpers
+ *
+ * Pure detection / fingerprint utilities used by the query builder's WHERE
+ * compiler. Kept out of builder.ts so the class file stays about SQL assembly
+ * and execution rather than filter-shape bookkeeping.
+ */
+import type { ArrayFilter, ColumnRef, JsonFilter, JsonPathOrderBy, OrderBySpec, OrderDirection, RelationPickOrderBy, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
+/** Check if a value is a where operator object (has at least one known operator key) */
+export declare function isWhereOperator(value: unknown): value is WhereOperator;
+/**
+ * True for a *plain object literal* that reached an equality fallthrough
+ * without matching any known filter shape — the misspelled-operator case.
+ * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
+ * bind values and return false, as do arrays and Dates.
+ */
+export declare function isUnmatchedPlainObject(value: unknown): boolean;
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+export declare const COLUMN_REF_OPERATORS: Set<string>;
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+export declare function isColumnRef(value: unknown): value is ColumnRef;
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
+ */
+export declare function fingerprintOperatorShape(value: WhereOperator): string;
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+export declare function assertBindableEqualsOperand(value: unknown, column: string): void;
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+export declare function sortedKeys(obj: Record<string, unknown>): string[];
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+export declare function sortedEntries<V>(obj: Record<string, V>): [string, V][];
+/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
+export declare const UPDATE_OPERATOR_KEYS: Set<string>;
+/** Known JSONB operator keys */
+export declare const JSONB_OPERATOR_KEYS: Set<string>;
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+export declare const JSON_RANGE_OPERATORS: Record<'gt' | 'gte' | 'lt' | 'lte', string>;
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+export declare function fingerprintJsonFilterShape(filter: JsonFilter): string;
+/**
+ * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * appear in any other where-filter shape, so the presence of one of these is
+ * an unambiguous signal that the user meant a JSON filter. Used by the
+ * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
+ */
+export declare const JSONB_UNIQUE_KEYS: Set<string>;
+/** Check if a value is a JSONB filter object */
+export declare function isJsonFilter(value: unknown): value is JsonFilter;
+/**
+ * Returns the first JSON-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+export declare function findJsonUniqueKey(value: object): string | null;
+/** Known Array operator keys */
+export declare const ARRAY_OPERATOR_KEYS: Set<string>;
+/**
+ * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
+ * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
+ * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
+ * constant so a future overlap (e.g. a `contains` for arrays) is easy to
+ * carve out.
+ */
+export declare const ARRAY_UNIQUE_KEYS: Set<string>;
+/**
+ * Value-invariant shape fingerprint for an {@link ArrayFilter} (the INNER part,
+ * without the `arr(...)` wrapper the where fingerprint adds). The boolean
+ * `isEmpty` operator changes the SQL shape (`= '{}'` vs `<> '{}'`), so its
+ * concrete value is part of the shape; the other operators are value-invariant.
+ */
+export declare function fingerprintArrayFilterShape(filter: ArrayFilter): string;
+/** Check if a value is an Array filter object */
+export declare function isArrayFilter(value: unknown): value is ArrayFilter;
+/**
+ * Returns the first array-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+export declare function findArrayUniqueKey(value: object): string | null;
+/** Known text search operator keys */
+export declare const TEXT_SEARCH_KEYS: Set<string>;
+/** Check if a value is a TextSearchFilter object */
+export declare function isTextSearchFilter(value: unknown): value is TextSearchFilter;
+/**
+ * Validate a text search config name. Only alphanumeric characters and
+ * underscores are allowed to prevent SQL injection via the config parameter.
+ */
+export declare function validateTextSearchConfig(config: string): boolean;
+/**
+ * pgvector distance metric → operator allow-list. This is the ONLY mapping
+ * from a user-supplied metric token to a SQL operator; any token not present
+ * here is rejected, so a user value can never become an arbitrary operator.
+ *
+ *  - `l2`     → `<->` (Euclidean / L2 distance)
+ *  - `cosine` → `<=>` (cosine distance)
+ *  - `ip`     → `<#>` (negative inner product)
+ */
+export declare const VECTOR_METRIC_OPERATORS: Record<string, string>;
+/** Comparison keys allowed on a {@link VectorDistanceFilter}. */
+export declare const VECTOR_DISTANCE_COMPARATORS: Record<string, string>;
+/** Check if a value is a vector distance WHERE filter: `{ distance: { to, metric } }` */
+export declare function isVectorFilter(value: unknown): value is VectorFilter;
+/** Check if an orderBy value is a vector KNN ordering: `{ distance: { to, metric } }` */
+export declare function isVectorOrderBy(value: unknown): value is VectorOrderBy;
+/** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
+export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
+/**
+ * Check if an orderBy value is a pick-row relation ordering:
+ * `{ pick: { orderBy, ... }, by, direction?, nulls?, plan? }`. The full shape
+ * is required (`pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls, plan }`), so a to-one
+ * relation whose target has real columns literally named `pick` and `by`
+ * (whose values are direction strings or `{ sort, nulls }` specs, never an
+ * object with `orderBy`) still falls through to column ordering. `distance`
+ * (vector), `sort` (OrderBySpec), and a top-level array `path` (JSON-path
+ * ordering) are excluded up front.
+ */
+export declare function isRelationPickOrderBy(value: unknown): value is RelationPickOrderBy;
+/**
+ * Flatten an orderBy input into an ordered list of `[field, value]` entries.
+ *
+ * Accepts BOTH the classic single-object form (`{ a: 'asc', b: 'desc' }`,
+ * whose insertion order is authoritative) and the Prisma-style array form
+ * (`[{ a: 'asc' }, { b: 'desc' }]`, whose array order is authoritative). The
+ * array form removes the reliance on JS object key iteration order for
+ * multi-key sorts. Each array element may carry one or more keys; they expand
+ * left-to-right. `undefined`/non-object elements are skipped.
+ *
+ * Undefined-VALUED entries are preserved (mirroring `Object.entries`) so each
+ * consumer keeps its own `dir !== undefined` filtering exactly as before. This
+ * is THE single flattening authority: every ORDER BY compile / collect /
+ * fingerprint path routes through it so the array and object forms stay in
+ * lockstep across build, param-collect, and cache-key fingerprint.
+ */
+export declare function orderByEntries(orderBy: unknown): [string, unknown][];
+/**
+ * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
+ * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile
+ * path (findMany, groupBy, relation inner subqueries).
+ */
+export declare function normalizeOrderBy(value: OrderDirection | OrderBySpec): {
+    dir: 'ASC' | 'DESC';
+    nulls?: 'first' | 'last';
+};

package/dist/cjs/query/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * turbine-orm — Query builder barrel
+ *
+ * Re-exports every public symbol from the query submodules so that
+ * `import { … } from './query/index.js'` is a drop-in replacement for the
+ * former monolithic `import { … } from './query.js'`.
+ */
+export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationPickBy, RelationPickOrderBy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
+export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
+export { postgresDialect } from '../dialect.js';
+export type { SqlCacheEntry } from './utils.js';
+export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './builder.js';
+export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/cjs/query/index.js

@@ -7,7 +7,7 @@
  * former monolithic `import { … } from './query.js'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryInterface = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = exports.postgresDialect = void 0;
+exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = exports.postgresDialect = void 0;
 var dialect_js_1 = require("../dialect.js");
 Object.defineProperty(exports, "postgresDialect", { enumerable: true, get: function () { return dialect_js_1.postgresDialect; } });
 var utils_js_1 = require("./utils.js");
@@ -20,4 +20,9 @@ Object.defineProperty(exports, "OPERATOR_KEYS", { enumerable: true, get: functio
 Object.defineProperty(exports, "quoteIdent", { enumerable: true, get: function () { return utils_js_1.quoteIdent; } });
 Object.defineProperty(exports, "sqlToPreparedName", { enumerable: true, get: function () { return utils_js_1.sqlToPreparedName; } });
 var builder_js_1 = require("./builder.js");
+Object.defineProperty(exports, "AUTO_ASSUMED_ROUND_TRIP_MS", { enumerable: true, get: function () { return builder_js_1.AUTO_ASSUMED_ROUND_TRIP_MS; } });
+Object.defineProperty(exports, "AUTO_JOIN_PENALTY_MS_PER_ROW", { enumerable: true, get: function () { return builder_js_1.AUTO_JOIN_PENALTY_MS_PER_ROW; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_MAX_ROWS", { enumerable: true, get: function () { return builder_js_1.AUTO_TO_ONE_JOIN_MAX_ROWS; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MAX", { enumerable: true, get: function () { return builder_js_1.AUTO_TO_ONE_JOIN_ROWS_MAX; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MIN", { enumerable: true, get: function () { return builder_js_1.AUTO_TO_ONE_JOIN_ROWS_MIN; } });
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return builder_js_1.QueryInterface; } });