uql-orm 0.53.0 → 0.55.0

package/dist/sqlite/sqliteQuerierPool.js

@@ -10,11 +10,6 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
         super(opts, extra);
         this.filename = filename;
     }
-    /**
-     * SQLite ships with foreign keys unenforced, per connection, for backward compatibility. UQL emits the
-     * constraints in its DDL, so leaving them off means a declared `onDelete: 'CASCADE'` silently does
-     * nothing and a dangling reference is accepted. Enabled here on every driver, as TypeORM also does.
-     */
     async createDb() {
         // `bun:sqlite` rejects option keys it does not know, and rejects an options object carrying no
         // open flags, so `extensions` is stripped out and what remains of it collapses back to nothing.
@@ -23,15 +18,9 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
         if (typeof Bun !== 'undefined') {
             const { Database: BunDatabase } = await import('bun:sqlite');
             const { adaptBunSqlite } = await import('./bunSqliteAdapter.bun.js');
-            const bunDb = new BunDatabase(this.filename, opts);
-            bunDb.run('PRAGMA journal_mode = WAL');
-            bunDb.run('PRAGMA foreign_keys = ON');
-            return adaptBunSqlite(bunDb);
+            return adaptBunSqlite(new BunDatabase(this.filename, opts));
         }
         const { default: BetterSqlite3 } = await import('better-sqlite3');
-        const db = new BetterSqlite3(this.filename, opts);
-        db.pragma('journal_mode = WAL');
-        db.pragma('foreign_keys = ON');
-        return db;
+        return new BetterSqlite3(this.filename, opts);
     }
 }

package/dist/turso/index.d.ts

@@ -1,3 +1,2 @@
 export * from './tursoDialect.js';
-export * from './tursoQuerier.js';
 export * from './tursoQuerierPool.js';

package/dist/turso/index.js

@@ -1,3 +1,2 @@
 export * from './tursoDialect.js';
-export * from './tursoQuerier.js';
 export * from './tursoQuerierPool.js';

package/dist/turso/tursoLocalQuerier.d.ts

@@ -7,7 +7,6 @@ import type { ExtraOptions } from '../type/index.js';
  */
 export type TursoDatabase = {
     prepare(sql: string): Promise<SqlitePreparedStatement>;
-    pragma(source: string, options?: unknown): Promise<unknown[]>;
     close(): Promise<void>;
 };
 /**

package/dist/turso/tursoLocalQuerierPool.js

@@ -1,5 +1,6 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import { applySqlitePragmas } from '../sqlite/sqlitePragmas.js';
 import { TursoDialect } from './tursoDialect.js';
 import { TursoLocalQuerier } from './tursoLocalQuerier.js';
 /**
@@ -21,8 +22,7 @@ export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
         const { connect } = await import('@tursodatabase/database');
         // Annotated rather than cast, so the structural contract is checked against the real driver.
         const db = await connect(this.filename, this.opts);
-        await db.pragma('journal_mode = WAL');
-        await db.pragma('foreign_keys = ON');
+        await applySqlitePragmas(db);
         return db;
     }
     buildQuerier(db) {

package/dist/turso/tursoQuerierPool.d.ts

@@ -2,7 +2,6 @@ import type { HranaClient } from '../sqlite/hranaQuerier.js';
 import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { TursoDialect } from './tursoDialect.js';
-import { TursoQuerier } from './tursoQuerier.js';
 /**
  * Connection settings for Turso Cloud, mirroring `@tursodatabase/serverless`.
  *
@@ -26,7 +25,7 @@ export type TursoConfig = {
  * because over plain HTTP consecutive requests need not share a connection. Compat's session-backed
  * transaction handle is the piece that makes it work.
  */
-export declare class TursoQuerierPool extends AbstractHranaQuerierPool<TursoQuerier, TursoDialect> {
+export declare class TursoQuerierPool extends AbstractHranaQuerierPool<TursoDialect> {
     protected readonly ownsClient: boolean;
     private readonly conf;
     /**
@@ -35,5 +34,4 @@ export declare class TursoQuerierPool extends AbstractHranaQuerierPool<TursoQuer
      */
     constructor(conf: TursoConfig | HranaClient, extra?: ExtraOptions);
     protected openClient(): Promise<HranaClient>;
-    protected buildQuerier(client: HranaClient): TursoQuerier;
 }

package/dist/turso/tursoQuerierPool.js

@@ -1,7 +1,6 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import { TursoDialect } from './tursoDialect.js';
-import { TursoQuerier } from './tursoQuerier.js';
 function isClient(conf) {
     return typeof conf.execute === 'function';
 }
@@ -33,7 +32,4 @@ export class TursoQuerierPool extends AbstractHranaQuerierPool {
         const { createClient } = await import('@tursodatabase/serverless/compat');
         return createClient(this.conf);
     }
-    buildQuerier(client) {
-        return new TursoQuerier(client, this.dialect, this.extra);
-    }
 }

package/dist/type/dialect.d.ts

@@ -59,7 +59,7 @@ export interface DriverCapabilities {
     readonly explicitJsonCast: boolean;
     /**
      * Whether the driver natively supports JS arrays for the underlying database type.
-     * `PgDialect` keeps this `true` for node-postgres; Bun SQL PostgreSQL uses `false` and
+     * `PgQuerierPool` keeps this `true` for node-postgres; `BunSqlQuerierPool` sets `false` and binds
      * `toPgArray` string literals instead.
      */
     readonly nativeArrays: boolean;

package/dist/type/entity.d.ts

@@ -359,11 +359,6 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * @example `@Field({ type: String, enum: ['draft', 'paid'] as const })`
      */
     readonly enum?: EnumValues;
-    /**
-     * @deprecated Renamed to {@link FieldOptions.computed}, which also takes `stored`. `npx uql-codemod`
-     * rewrites it. Giving both throws.
-     */
-    readonly virtual?: QueryRaw;
     /**
      * An expression the database computes, rather than a value the caller writes. Never part of an
      * insert or update either way.
@@ -818,12 +813,6 @@ export type EntityMeta<E> = {
     /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
     processedAt?: number;
 };
-/**
- * Configurable options for an entity (`@Entity()` / `defineEntity`).
- *
- * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
- * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
- */
 /**
  * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
  * this is DDL, so there is no placeholder a bound value could go into.
@@ -843,6 +832,12 @@ export type EntityMembers = {
     readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
     readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
 };
+/**
+ * Configurable options for an entity (`@Entity()` / `defineEntity`).
+ *
+ * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
+ * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
+ */
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**

package/dist/type/migration.d.ts

@@ -372,9 +372,6 @@ export interface SchemaIntrospector {
      * the database side never reports it, and no migration can close the gap.
      */
     readonly indexFacets: ReadonlySet<IndexFacet>;
-    /**
-     * Introspect entire database schema and return SchemaAST.
-     */
     /** The whole database, or just the tables named. Names nothing matches are left out. */
     introspect(tables?: readonly string[]): Promise<SchemaAST>;
     /**

package/dist/type/query.d.ts

@@ -59,17 +59,17 @@ export type QueryExclude<E> = QuerySelect<E>;
 export type QueryPopulate<E> = {
     [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
 };
+/**
+ * The key a read carries its relation tallies under. One spelling for the type and the runtime that
+ * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
+ */
+export declare const COUNT_RESULT_KEY = "_count";
 /**
  * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
  * which ones count. One statement per relation named here, batched over every parent at once, so it
  * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
  * a relation of the same name that `$populate` filled with rows.
  */
-/**
- * The key a read carries its relation tallies under. One spelling for the type and the runtime that
- * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
- */
-export declare const COUNT_RESULT_KEY = "_count";
 export type QueryCount<E> = {
     [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
 };
@@ -141,6 +141,13 @@ type ToOneRelationKey<E> = {
 }[RelationKey<E>];
 /** The relation names a parent holds many rows of, which a populated query fills with a list. */
 type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
+/**
+ * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
+ * The tally is computed per parent as a correlated count, never by loading the rows.
+ */
+export type QuerySortByCount = {
+    $count: QuerySortDirection;
+};
 /**
  * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
  * like `QueryWhere`), relation sort via nested objects, and vector similarity search on
@@ -153,13 +160,6 @@ type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
  * against an intersection is repeated per constituent, which made this the single most expensive
  * type in the package to check.
  */
-/**
- * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
- * The tally is computed per parent as a correlated count, never by loading the rows.
- */
-export type QuerySortByCount = {
-    $count: QuerySortDirection;
-};
 export type QuerySortMap<E, Vector extends boolean = true> = {
     [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E> ? IsMany<E[K]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };

package/dist/type/query.js

@@ -1,9 +1,3 @@
-/**
- * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
- * which ones count. One statement per relation named here, batched over every parent at once, so it
- * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
- * a relation of the same name that `$populate` filled with rows.
- */
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
  * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.

package/dist/type/universalQuerier.d.ts

@@ -126,7 +126,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
      * auto-increment keys in batches without explicit IDs - otherwise those entries are
      * `undefined` rather than potentially wrong values. A composite key is never one the statement
-     * reports, so those rows are named from the payload instead.
+     * reports, so those rows are named as written, `onInsert` columns included.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
@@ -137,7 +137,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the id and whether it was created; see {@link QueryUpsertOneResult}
      */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
     /**
@@ -145,7 +145,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the ids, in payload order; see {@link QueryUpsertManyResult}
      */
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
@@ -35,7 +35,8 @@ export declare function getSoftDeleteValue(field: FieldOptions): string | number
 }[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
     readonly __json?: never;
 };
-export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): EntityData<E>[];
+/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
+export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
 /**
  * The relation keys present in `payload` whose cascade configuration allows `action`. Only
  * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
@@ -169,4 +170,4 @@ export declare function assertNonNegativeInteger(value: number, clause: string):
  */
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
-export declare function assertAggregateColumns(clauseMap: object | undefined, emitted: ReadonlySet<string>, clause: string): void;
+export declare function assertAggregateColumns(clauseMap: object, emitted: ReadonlySet<string>, clause: string): void;

package/dist/util/dialect.util.js

@@ -73,6 +73,7 @@ export function getFieldCallbackValue(val) {
 export function getSoftDeleteValue(field) {
     return field.softDelete === true ? new Date() : getFieldCallbackValue(field.softDelete);
 }
+/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
 export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
     const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey]);
@@ -417,7 +418,7 @@ export function throwUnknownAggregateColumn(key, clause) {
 }
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export function assertAggregateColumns(clauseMap, emitted, clause) {
-    for (const key of getKeys(clauseMap ?? {})) {
+    for (const key of getKeys(clauseMap)) {
         if (!emitted.has(key)) {
             throwUnknownAggregateColumn(key, clause);
         }

package/dist/util/field.util.d.ts

@@ -1,5 +1,4 @@
 import type { EntityMeta, FieldOptions } from '../type/index.js';
-import type { QueryRaw } from '../type/queryRaw.js';
 /**
  * The kind of column a field lands on, which is what decides whether an option means anything on it:
  * `length` is a string's, `precision` a number's, `dimensions` a vector's. Named in the words an
@@ -23,26 +22,15 @@ export declare const COLUMN_TYPES_BY_FAMILY: {
 };
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
-/**
- * The expression the database computes for this field, whichever key declared it.
- *
- * `virtual` is `computed` under its old name and is read here so both spell one behaviour. Giving
- * both is refused at registration rather than resolved, since only the author knows which was meant.
- */
-export declare function computedExpression(field: FieldOptions): QueryRaw | undefined;
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
- *
- * One of the two questions `virtual` used to answer alone. Every read site asks this - the DDL skip,
- * the projection, the `$where` operand, the `ORDER BY` operand - because an inlined field has no
- * column to name, while a stored one is read exactly like any other.
+ * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
+ * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export declare function isInlinedExpression(field: FieldOptions): boolean;
 /**
- * Whether the database supplies this field's value, so no insert or update may write it.
- *
- * The other question, and the one that makes `stored` more than a rename: a stored computed column
- * *is* a real column, so it is read like one - but writing to it is an error on every engine.
+ * Whether the database supplies this field's value, so no insert or update may write it: a stored
+ * computed column *is* a real column, read like one, but writing to it is an error on every engine.
  */
 export declare function isDatabaseWritten(field: FieldOptions): boolean;
 /**

package/dist/util/field.util.js

@@ -46,33 +46,20 @@ for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
 export function columnFamily(type) {
     return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
-/**
- * The expression the database computes for this field, whichever key declared it.
- *
- * `virtual` is `computed` under its old name and is read here so both spell one behaviour. Giving
- * both is refused at registration rather than resolved, since only the author knows which was meant.
- */
-export function computedExpression(field) {
-    return field.computed ?? field.virtual;
-}
 /**
  * Whether the field's expression is spliced into each statement that reads it, rather than stored.
- *
- * One of the two questions `virtual` used to answer alone. Every read site asks this - the DDL skip,
- * the projection, the `$where` operand, the `ORDER BY` operand - because an inlined field has no
- * column to name, while a stored one is read exactly like any other.
+ * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
+ * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export function isInlinedExpression(field) {
-    return computedExpression(field) !== undefined && field.stored !== true;
+    return field.computed !== undefined && field.stored !== true;
 }
 /**
- * Whether the database supplies this field's value, so no insert or update may write it.
- *
- * The other question, and the one that makes `stored` more than a rename: a stored computed column
- * *is* a real column, so it is read like one - but writing to it is an error on every engine.
+ * Whether the database supplies this field's value, so no insert or update may write it: a stored
+ * computed column *is* a real column, read like one, but writing to it is an error on every engine.
  */
 export function isDatabaseWritten(field) {
-    return computedExpression(field) !== undefined;
+    return field.computed !== undefined;
 }
 /**
  * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,

package/dist/util/fieldOption.util.d.ts

@@ -14,7 +14,6 @@ declare const FIELD_OPTION_FAMILY: {
     readonly references: '*';
     readonly onDelete: '*';
     readonly enum: '*';
-    readonly virtual: '*';
     readonly computed: '*';
     readonly stored: '*';
     readonly updatable: '*';
@@ -39,7 +38,7 @@ declare const FIELD_OPTION_FAMILY: {
  * rather than on each option that dies, because it is one fact rather than nineteen - and because an
  * option added without a thought then lands on the safe side of it.
  */
-declare const INLINE_READS: readonly ["type", "virtual", "computed", "stored", "enum", "eager", "distance"];
+declare const INLINE_READS: readonly ["type", "computed", "stored", "enum", "eager", "distance"];
 type InlineRead = (typeof INLINE_READS)[number];
 /**
  * What a column the *database* writes cannot use. A stored computed column is a real column - it has
@@ -66,8 +65,6 @@ type FamilyOfType<T> = T extends NumericColumnType | NumberConstructor | BigIntC
 type DeadOptions<O> = (O extends {
     readonly stored: true;
 } ? GeneratedWrite : O extends {
-    readonly virtual: QueryRaw;
-} | {
     readonly computed: QueryRaw;
 } ? Exclude<keyof FieldOptions, InlineRead> : never) | (O extends {
     readonly isId: true;

package/dist/util/fieldOption.util.js

@@ -14,7 +14,6 @@ const FIELD_OPTION_FAMILY = {
     references: '*',
     onDelete: '*',
     enum: '*',
-    virtual: '*',
     computed: '*',
     stored: '*',
     updatable: '*',
@@ -41,7 +40,6 @@ const FIELD_OPTION_FAMILY = {
  */
 const INLINE_READS = [
     'type',
-    'virtual',
     'computed',
     'stored',
     'enum',

package/dist/util/logger.d.ts

@@ -12,9 +12,6 @@ export declare class DefaultLogger implements Logger {
     logMigration(message: string): void;
     logSkippedMigration(message: string): void;
 }
-/**
- * A wrapper class that implements the Logger interface and handles different logging options.
- */
 /**
  * Secondary {@link LoggerWrapper} settings, alongside the primary `options: LoggingOptions`
  * constructor argument.
@@ -28,6 +25,9 @@ export interface LoggerWrapperConfig {
     /** Threshold in milliseconds - queries exceeding this are logged as slow. */
     slowQuery?: number;
 }
+/**
+ * A wrapper class that implements the Logger interface and handles different logging options.
+ */
 export declare class LoggerWrapper implements Logger {
     private readonly levels;
     private readonly logger?;
@@ -54,12 +54,11 @@ export interface ErrorEmittingPool {
     on(event: 'error', listener: (err: Error) => void): unknown;
 }
 /**
- * Attaches an error listener to a connection pool so a dropped connection is
- * logged instead of left unhandled - which crashes the process for drivers
- * that don't guard against it themselves (node-postgres), or silently
- * swallowed with zero visibility for drivers that already install their own
- * no-op safety net (`mariadb`'s `createPool`). Always logs via a dedicated
- * logger (ignoring the consumer's configured log level) since a silently
- * swallowed pool error is exactly the failure mode this guards against.
+ * Attaches an error listener to a connection pool so a dropped connection is logged instead of left
+ * unhandled - which crashes the process for drivers that don't guard against it themselves
+ * (node-postgres, `mssql`), or is silently swallowed by those that install a no-op of their own
+ * (`mariadb`). Reported through the pool's own logger when it has one, and through the default one
+ * otherwise: never dropped, whatever levels were configured, since a swallowed pool error is exactly
+ * the failure this guards against.
  */
-export declare function attachPoolErrorHandler(pool: ErrorEmittingPool, message: string): void;
+export declare function attachPoolErrorHandler(pool: ErrorEmittingPool, message: string, logging?: LoggingOptions): void;

package/dist/util/logger.js

@@ -7,18 +7,22 @@ const DEFAULT_LOG_LEVELS = [
     'migration',
     'skippedMigration',
 ];
+/** Bound values as JSON, a `bigint` by its digits: `JSON.stringify` refuses one outright. */
+function renderValues(values) {
+    return JSON.stringify(values, (_key, value) => (typeof value === 'bigint' ? value.toString() : value));
+}
 /**
  * Default implementation of the Logger interface using console methods.
  */
 export class DefaultLogger {
     logQuery(query, values, duration) {
         const time = duration !== undefined ? ` [${duration}ms]` : '';
-        const params = values?.length ? ` -- ${JSON.stringify(values)}` : '';
+        const params = values?.length ? ` -- ${renderValues(values)}` : '';
         console.log(`\x1b[36mquery:\x1b[0m ${query}${params}\x1b[32m${time}\x1b[0m`);
     }
     logSlowQuery(query, values, duration) {
         const time = duration !== undefined ? ` [${duration}ms]` : '';
-        const params = values?.length ? ` -- ${JSON.stringify(values)}` : '';
+        const params = values?.length ? ` -- ${renderValues(values)}` : '';
         console.warn(`\x1b[33mslow query:\x1b[0m ${query}${params}\x1b[31m${time}\x1b[0m`);
     }
     logWarn(message) {
@@ -40,6 +44,9 @@ export class DefaultLogger {
         console.info(`\x1b[33mskipped migration:\x1b[0m ${message}`);
     }
 }
+/**
+ * A wrapper class that implements the Logger interface and handles different logging options.
+ */
 export class LoggerWrapper {
     levels;
     logger;
@@ -130,17 +137,20 @@ export class LoggerWrapper {
     }
 }
 /**
- * Attaches an error listener to a connection pool so a dropped connection is
- * logged instead of left unhandled - which crashes the process for drivers
- * that don't guard against it themselves (node-postgres), or silently
- * swallowed with zero visibility for drivers that already install their own
- * no-op safety net (`mariadb`'s `createPool`). Always logs via a dedicated
- * logger (ignoring the consumer's configured log level) since a silently
- * swallowed pool error is exactly the failure mode this guards against.
+ * Attaches an error listener to a connection pool so a dropped connection is logged instead of left
+ * unhandled - which crashes the process for drivers that don't guard against it themselves
+ * (node-postgres, `mssql`), or is silently swallowed by those that install a no-op of their own
+ * (`mariadb`). Reported through the pool's own logger when it has one, and through the default one
+ * otherwise: never dropped, whatever levels were configured, since a swallowed pool error is exactly
+ * the failure this guards against.
  */
-export function attachPoolErrorHandler(pool, message) {
-    const logger = new LoggerWrapper(true);
+export function attachPoolErrorHandler(pool, message, logging) {
+    const logger = new LoggerWrapper(isOwnLogger(logging) ? logging : true);
     pool.on('error', (err) => {
         logger.logError(message, err);
     });
 }
+/** A logger the consumer wrote, as opposed to a switch or a level list for the default one. */
+function isOwnLogger(logging) {
+    return typeof logging === 'function' || (typeof logging === 'object' && !Array.isArray(logging));
+}

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { QueryRaw, type QueryRawFn, type Scalar } from '../type/index.js';
+import { QueryRaw, type QueryRawFn } from '../type/index.js';
 /**
  * Create a raw SQL expression.
  *
@@ -19,18 +19,11 @@ import { QueryRaw, type QueryRawFn, type Scalar } from '../type/index.js';
  * The callback form remains for SQL a template cannot express, such as a sub-query generated through
  * `dialect.find(...)`. See {@link col} for a context-aware column reference.
  *
- * **⚠️ Security:** the tag is safe because it binds; the other two forms are not. `raw('SQL')` emits
- * its argument verbatim and a callback emits whatever it writes, so build neither from user input.
- * Inside a callback, bind with `ctx.addValue()`.
+ * **⚠️ Security:** the tag is safe because it binds; a callback is not, since it emits whatever it
+ * writes, so never build one from user input. Inside a callback, bind with `ctx.addValue()`.
  */
 export declare function raw(strings: TemplateStringsArray, ...values: readonly unknown[]): QueryRaw;
 export declare function raw(value: QueryRawFn, alias?: string): QueryRaw;
-/**
- * @deprecated Emits its argument verbatim, so it cannot bind a value. Use the tagged template:
- * `raw('"a" > 1')` becomes `` raw`"a" > 1` ``, and `raw('LOG10(x)', 'score')` becomes
- * `` raw`LOG10(x)`.as('score') ``. `npx uql-codemod` rewrites both.
- */
-export declare function raw(value: Scalar, alias?: string): QueryRaw;
 /**
  * A column of the entity being queried, alias-qualified and escaped for the dialect. This is what a
  * template cannot know on its own: the alias is decided while the statement is built, not where the

package/dist/util/raw.js

@@ -7,11 +7,11 @@ export function raw(value, ...rest) {
     if (!rest.length) {
         // Nothing to bind, so this is the string form: keep it one, for the DDL paths that need to read
         // the expression back as text (an index expression cannot carry a parameter).
-        return new QueryRaw(value[0] ?? '');
+        return new QueryRaw(value[0]);
     }
     return new QueryRaw((opts) => {
         const { ctx } = opts;
-        ctx.append(value[0] ?? '');
+        ctx.append(value[0]);
         rest.forEach((interpolated, i) => {
             if (interpolated instanceof QueryRaw) {
                 interpolated.render(opts);
@@ -19,7 +19,7 @@ export function raw(value, ...rest) {
             else {
                 ctx.addValue(interpolated);
             }
-            ctx.append(value[i + 1] ?? '');
+            ctx.append(value[i + 1]);
         });
     });
 }

package/dist/util/sql.util.js

@@ -200,8 +200,8 @@ export function buildUpdateResult(payload) {
     // UPDATE` convention makes `changes` a per-row weighted sum (1=insert, 2=update, 0=no-op), so a
     // batch mixing an insert and an update would fabricate ids for rows that were never touched. This
     // function has no way to tell the two call sites apart (`internalRun` reports the same header
-    // shape either way), so `AbstractSqlQuerier.upsertMany` strips `ids`/`firstId`/`created` back down
-    // to just `changes` for a multi-row `firstId`-dialect upsert after calling this.
+    // shape either way), so `AbstractSqlQuerier`'s `runUpsert` discards them for a multi-row `firstId`
+    // upsert and reads the ids back by the conflict columns instead.
     let ids = [];
     if (rows?.length) {
         ids = rows.map((r) => r['id']);

package/dist/util/sqlLiteral.js

@@ -33,9 +33,6 @@ const MYSQL_ESCAPES = {
 };
 const mysqlStringLiteral = (val) => `'${val.replace(MYSQL_SPECIALS, (char) => MYSQL_ESCAPES[char])}'`;
 const pad = (value, len) => String(value).padStart(len, '0');
-function isByteSource(val) {
-    return (typeof Buffer !== 'undefined' && Buffer.isBuffer(val)) || val instanceof Uint8Array;
-}
 const HEX_BYTES = Array.from({ length: 256 }, (_, byte) => byte.toString(16).padStart(2, '0'));
 /** Native hex encoder where available (~130x faster on 4 KB); lookup table for browsers. */
 function bytesToHexLiteral(bytes) {
@@ -72,7 +69,8 @@ function createEscaper(escapeString) {
         if (Array.isArray(value)) {
             return sqlList(value);
         }
-        if (isByteSource(value)) {
+        // A Node `Buffer` is a `Uint8Array` too.
+        if (value instanceof Uint8Array) {
             return bytesToHexLiteral(value);
         }
         if ('toSqlString' in value && typeof value.toSqlString === 'function') {
@@ -95,11 +93,8 @@ function createEscaper(escapeString) {
                 return escapeString(value);
             case 'object':
                 return escapeObject(value);
-            case 'symbol':
-            case 'function':
-                throw new TypeError('escapeSqlLiteral: symbol and function values are not supported; use bound parameters.');
             default:
-                // Unreachable today; throwing keeps a future JS type from silently becoming SQL.
+                // A symbol or a function, or a future JS type: none of them may silently become SQL.
                 throw new TypeError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);
         }
     };