uql-orm 0.24.6 → 0.25.0

package/README.md

@@ -9,7 +9,7 @@
 
 <h3>The smartest TypeScript ORM</h3>
 
-<p>Type-safe to the leaf, serializable queries, no codegen, <a href="https://uql-orm.dev/benchmark">extremely fast</a>, and unified API across Postgres, CockroachDB, MySQL, SQLite, MongoDB, MariaDB, and the edge.</p>
+<p>Type-safe to the leaf, serializable queries, no codegen, <a href="https://uql-orm.dev/benchmark">extremely fast</a>, and one API across every SQL database, MongoDB, and every runtime.</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·
@@ -37,7 +37,7 @@ and no compiler flag to turn on ([setup](https://uql-orm.dev/getting-started)),
 [imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
 
 ```ts
-await querier.findMany(User, {
+await pool.findMany(User, {
   $select: { id: true, email: true },
   $populate: { posts: { $select: { title: true } } },
   $where: { email: { $endsWith: '@uql-orm.dev' } },
@@ -50,12 +50,13 @@ from the browser to the server. The same object runs on every supported database
 
 ## Why UQL?
 
-- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.4× faster than the runner-up on average, over 4.6M ops/s on simple SELECTs.
-- **Light.** Zero runtime dependencies, 288 kB on the wire, every dialect included.
-- **Queries are data, not method chains.** Plain JSON in, typed rows out. There's no DSL to learn and nothing to compile.
-- **Type-safe to the leaf.** Operators are gated per field type, and JSON/JSONB dot-paths resolve each path's value type, so `{ age: { $like: 'x' } }` or a typo'd path is a compile error instead of a runtime surprise.
-- **No codegen.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` file to regenerate, no generated client to keep in sync.
-- **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, LibSQL, Neon, Cloudflare D1, Bun SQL, and MongoDB.
+- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.4× faster than the runner-up on average, reaching over 4.6M ops/s on simple SELECTs.
+- **Light.** Zero runtime dependencies, 305 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
+- **Queries are data (JSON), not method chains.** Plain JSON in, typed rows out. There's no DSL to learn and nothing to compile.
+- **Type-safe to the leaf.** Every key is autocompleted and checked against your entity, down to the fields of a populated relation. Operators are gated per field type, and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths resolve each path's value type, so `$like` on a numeric column, or a typo'd path, is a compile error instead of a runtime surprise.
+- **No codegen, no build step.** Entities are TypeScript classes, so your code *is* the schema. There's no `.prisma` file to regenerate and no generated client to keep in sync.
+- **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB!
+- **Runs on every runtime.** Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser). ESM-only with no native binaries on the `fetch`-based drivers, so an edge bundle needs no special build.
 - **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
 
 ## Get started

package/dist/cockroachdb/crdbQuerierPool.d.ts

@@ -9,5 +9,5 @@ import { CrdbQuerier } from './crdbQuerier.js';
 export declare class CrdbQuerierPool extends AbstractPgQuerierPool<PoolClient, CrdbQuerier, CockroachDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<CrdbQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): CrdbQuerier;
 }

package/dist/cockroachdb/crdbQuerierPool.js

@@ -1,5 +1,6 @@
-import { Pool } from 'pg';
+import { Pool, types } from 'pg';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
+import { numericTypes } from '../postgres/pgNumericTypes.js';
 import { CockroachDialect } from './cockroachDialect.js';
 import { CrdbQuerier } from './crdbQuerier.js';
 /**
@@ -7,9 +8,9 @@ import { CrdbQuerier } from './crdbQuerier.js';
  */
 export class CrdbQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new CockroachDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, ...opts }), extra);
+        super(new CockroachDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new CrdbQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new CrdbQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,7 +1,11 @@
 import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import type { HydrateKind } from './hydrateColumn.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
 type PersistKind = 'plain' | 'json' | 'vector';
+/** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
+type HydratableField = readonly [string, HydrateKind];
+export type { HydrateKind };
 export declare abstract class AbstractSqlDialect extends IndexSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
     abstract readonly escapeIdChar: '"' | '`';
@@ -99,6 +103,20 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     protected resolveOperandField<E>(ctx: QueryContext, entity: Type<E>, key: string, opts: QueryOptions): string | undefined;
     private appendFieldSql;
     compareFieldOperator<E, K extends keyof QueryWhereFieldOperatorMap<E>>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, op: K, val: QueryWhereFieldOperatorMap<E>[K], opts?: QueryOptions): void;
+    /**
+     * Render `<operand> <op> <value>` for every operator that needs nothing but its left-hand SQL, and
+     * report whether `op` was one of them.
+     *
+     * One implementation for three callers that each had their own: a WHERE column, a HAVING aggregate
+     * expression, and a `$size` count (which passes no operand, since its expression is already in the
+     * context). They previously disagreed - HAVING carried a second comparison-operator map and threw
+     * `unsupported HAVING operator` on the `$like` that `QueryHavingMap` accepts, and neither of the
+     * other two turned `$eq: null` into `IS NULL` the way the WHERE path does.
+     *
+     * The operators kept out are the ones that need more than an operand: `$not` recurses through the
+     * entity, and `$all`/`$size`/`$elemMatch` address a JSON document.
+     */
+    protected appendOperatorCondition(ctx: QueryContext, operand: string | undefined, op: string, val: unknown): boolean;
     private appendLikeOp;
     private appendEqNe;
     private appendInNin;
@@ -116,19 +134,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * {@link jsonCompareMode} for why each mode exists.
      */
     protected jsonComparand(jsonField: string, value: unknown): string;
-    /**
-     * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
-     * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
-     * compared in the representation every engine agrees on:
-     * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
-     *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
-     * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
-     *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
-     * - `text` - compare as extracted, which is also what the string operators need.
-     *
-     * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
-     */
-    protected jsonCompareMode(value: unknown): 'json' | 'numeric' | 'text';
     /** `$all`: the JSON array at `jsonField` contains every value (also serves element containment). */
     protected abstract jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
     /** `$size`: the length of the JSON array at `jsonField`, compared against `value`. */
@@ -171,17 +176,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * - otherwise - per-field conditions over the exploded objects.
      */
     protected jsonElemMatch(ctx: QueryContext, jsonField: string, match: Record<string, unknown>): string;
-    /**
-     * Whether the operator reads the JSON *value* instead of its text form. The array operators always
-     * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
-     * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
-     * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
-     * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
-     *
-     * Numbers stay on the text accessor with a numeric cast ({@link jsonComparand}), which keeps
-     * `1` equal to `1.0` - JSON equality would not.
-     */
-    protected isJsonbOp(op: string, value?: unknown): boolean;
     /**
      * A JSON-encoded bound parameter, cast to the dialect's JSON type. Only the positional-placeholder
      * dialects use this - PostgreSQL binds JSON through {@link PgLikeSqlDialect.jsonScalarParam} instead.
@@ -204,7 +198,6 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     private static readonly SORT_DIRECTION_MAP;
     private resolveSortDirection;
     /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
-    private static readonly comparisonOpMap;
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
@@ -232,6 +225,15 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * bind into the main context and skip the second one.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    /**
+     * Whether the upsert's update assignments can bind straight into the statement's own context.
+     *
+     * They cannot on a `?`-placeholder dialect: the assignments are built before the insert but read
+     * after it, so their values have to be pushed afterwards to land in the right positional order.
+     * A `$n` placeholder carries its own index, so there is nothing to reorder - but it also cannot use
+     * the scratch context, whose numbering would restart at `$1` and collide with the insert's.
+     */
+    protected readonly upsertUpdateBindsInPlace: boolean;
     /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
     protected readonly upsertExcluded: (columnName: string) => string;
     protected getUpsertUpdateAssignments<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], callback?: (columnName: string) => string): string;
@@ -251,6 +253,49 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
      */
     protected persistKind(field: FieldOptions | undefined): PersistKind;
+    /**
+     * Which of an entity's columns need decoding on READ, and how: the inverse of {@link persistKind},
+     * cached per entity for the same reason it classifies per column. A 1000-row read of a 10-field
+     * entity otherwise asks `isJsonType` (which lowercases a string on every call) 10,000 times to get
+     * the same ten answers. Most entities land here for their numeric columns alone, where the per-row
+     * cost is one `typeof` against a value the driver usually decoded already.
+     *
+     * Dialect-aware exactly like {@link supportedVectorType}, because it has to be: a `sparsevec` field
+     * is written as a plain dense vector everywhere but Postgres, so reading it back by the field's own
+     * declared cast would look for a sparse literal that was never stored.
+     *
+     * A type lands here rather than at the driver when the wire type alone cannot decide it, and only
+     * the declaration can: `Boolean` is 0/1 in a SQLite INTEGER and a MySQL `TINYINT(1)`, both
+     * indistinguishable from a genuine small integer; a decimal is text from pg *and* mysql2, and only
+     * the field says it was meant as a number; and `type: BigInt` shares BIGINT with `type: Number`, so
+     * the wire decode has to be undone for it. All are no-ops where the driver already decoded.
+     *
+     * Classified through the same `isNumericType`/`isBooleanType`/`isJsonType` the rest of the library
+     * uses, not against the constructors: `type` accepts a string logical type for every one of these
+     * (`@Field({ type: 'decimal' })`), and matching `=== Number` alone left those reading back as text.
+     */
+    hydratableFields<E>(entity: Type<E>): readonly HydratableField[];
+    /**
+     * The same classification for an aggregate row. Not cached, because these columns are a shape of the
+     * query rather than of the entity, and it is computed once per call either way.
+     *
+     * Mirrors `QueryAggregateFnResult`, which is the contract callers already compile against:
+     * `$count`/`$sum`/`$avg` are a number whatever they aggregate, while `$min`/`$max` and every
+     * `$group` column keep the aggregated field's own type, so they decode as that field would. Without
+     * it a `$sum` over a BIGINT column came back as `'500'` from a result type that says `number`, since
+     * Postgres widens that sum to NUMERIC and no driver can know it was meant as a JS number.
+     */
+    hydratableAggregates<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>): readonly HydratableField[];
+    /**
+     * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode.
+     *
+     * Ordered for correctness, not for speed - this runs once per entity, cached, never per row. The
+     * one order that is load-bearing is `BigInt` before {@link isNumericType}, which answers true for
+     * `BigInt` as well as `Number`: swap them and every `type: BigInt` property silently decodes to a
+     * JS number again.
+     */
+    protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
+    private readonly hydratable;
     /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
     private writePersistableValue;
     protected appendJsonValue(ctx: QueryContext, value: unknown, _type: JsonColumnType): void;
@@ -348,8 +393,15 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      * @param sizeExprFn - function that appends the size expression to ctx (e.g. `jsonb_array_length("col")`)
      */
     protected buildSizeComparison(ctx: QueryContext, sizeExprFn: () => void, sizeVal: number | QuerySizeComparisonOps): void;
+    /** The runtime half of {@link QuerySizeComparisonOps}: what a count can sensibly be compared with. */
+    private static readonly SIZE_COMPARE_OPS;
     /**
-     * Append a single size comparison operator and value to the context.
+     * Append a single size comparison operator and value. No operand: the count expression is already
+     * in the context, so this contributes only the ` <op> <value>` tail.
+     *
+     * Gated on {@link SIZE_COMPARE_OPS} rather than on whatever the shared renderer accepts, because
+     * that renderer also knows `$like`, `$regex` and `$in`, none of which mean anything against a
+     * count. `$size: { $like: 5 }` has to stay the error it always was.
      */
     private appendSizeOp;
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
@@ -371,4 +423,3 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     protected numericCast(expr: string): string;
     toString(): string;
 }
-export {};