uql-orm 0.82.0 → 0.83.1

package/dist/mysql/mysql2QuerierPool.js

@@ -5,14 +5,32 @@ import { MySql2Querier } from './mysql2Querier.js';
 import { MySqlDialect } from './mysqlDialect.js';
 export class MySql2QuerierPool extends AbstractSqlQuerierPool {
     pool;
+    #utcSessions = new WeakSet();
     constructor(opts, extra) {
         super(new MySqlDialect(dialectOptionsFrom(extra)), extra);
         // A BIGINT past 2^53 as its exact text rather than a rounded number, the rule every driver here
         // decodes by (`decodeWideNumber`); within that range it stays a number, and DECIMAL is untouched.
-        this.pool = createPool({ supportBigNumbers: true, ...opts });
+        // A date reads as the UTC it holds, whichever zone the process runs in.
+        this.pool = createPool({ supportBigNumbers: true, timezone: 'Z', ...opts });
     }
     async getQuerier() {
-        return new MySql2Querier(() => this.pool.getConnection(), this.dialect, this.extra);
+        return new MySql2Querier(() => this.#connection(), this.dialect, this.extra);
+    }
+    /** A connection whose session is UTC too, so `NOW()` agrees with a bound date: set once per connection. */
+    async #connection() {
+        const connection = await this.pool.getConnection();
+        if (this.#utcSessions.has(connection.connection)) {
+            return connection;
+        }
+        try {
+            await connection.query("SET time_zone = '+00:00'");
+        }
+        catch (error) {
+            connection.release();
+            throw error;
+        }
+        this.#utcSessions.add(connection.connection);
+        return connection;
     }
     async end() {
         await this.pool.end();

package/dist/neon/neonQuerierPool.js

@@ -1,11 +1,11 @@
 import { Pool, types } from '@neondatabase/serverless';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
-import { numericTypes } from '../postgres/pgNumericTypes.js';
+import { wireTypes } from '../postgres/pgWireTypes.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/pglite/pgliteQuerierPool.js

@@ -1,6 +1,7 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { PgliteQuerier } from './pgliteQuerier.js';
 /**
@@ -18,12 +19,17 @@ export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
     }
     async openDb() {
         const { PGlite, types } = await import('@electric-sql/pglite');
-        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53; a caller's own
-        // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the
-        // real driver, so no cast is needed here or anywhere below it.
+        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53, and a zoneless
+        // TIMESTAMP or a DATE as UTC, as every pool reads one; a caller's own `parsers` still win. The declared
+        // return type is what checks {@link PgliteDatabase} against the real driver, so no cast is needed below it.
         return PGlite.create(this.dataDir, {
             ...this.opts,
-            parsers: { [types.INT8]: decodeWideNumber, ...this.opts?.parsers },
+            parsers: {
+                [types.INT8]: decodeWideNumber,
+                [types.TIMESTAMP]: decodeDate,
+                [types.DATE]: decodeDate,
+                ...this.opts?.parsers,
+            },
         });
     }
     buildQuerier(db) {

package/dist/postgres/pgQuerierPool.js

@@ -1,12 +1,12 @@
 import { Pool, types } from 'pg';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
-import { numericTypes } from './pgNumericTypes.js';
+import { wireTypes } from './pgWireTypes.js';
 import { PostgresDialect } from './postgresDialect.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/postgres/{pgNumericTypes.d.ts → pgWireTypes.d.ts}

@@ -11,8 +11,9 @@ type PgTypes = {
 };
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export declare function wireTypes(types: PgTypes): CustomTypesConfig;
 export {};

package/dist/postgres/{pgNumericTypes.js → pgWireTypes.js}

@@ -1,14 +1,18 @@
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export function numericTypes(types) {
+export function wireTypes(types) {
     // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
     const decoders = new Map([
         [types.builtins['INT8'], decodeWideNumber],
         [types.builtins['FLOAT8'], Number],
+        [types.builtins['TIMESTAMP'], decodeDate],
+        [types.builtins['DATE'], decodeDate],
     ]);
     return {
         getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),

package/dist/schema/canonicalType.d.ts

@@ -1,6 +1,7 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { VectorCast } from '../dialect/vectorCast.js';
 import type { ColumnType, EntityGetter, FieldMeta, FieldOptions } from '../type/entity.js';
+import { type DialectName } from '../type/index.js';
 import type { CanonicalType, TypeCategory } from './types.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export declare function isVectorCategory(category: TypeCategory | undefined): category is VectorCast;
@@ -29,6 +30,8 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  * Convert a canonical type to a TypeScript type string.
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export declare function defaultTimestampPrecision(dialectName: DialectName): number | undefined;
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.

package/dist/schema/canonicalType.js

@@ -120,7 +120,8 @@ const MYSQL_SCALAR_MAP = {
     boolean: 'TINYINT(1)',
     date: 'DATE',
     time: 'TIME',
-    timestamp: 'DATETIME',
+    // The milliseconds a `Date` holds, which a bare `DATETIME` rounds away.
+    timestamp: 'DATETIME(3)',
     json: 'JSON',
     uuid: 'CHAR(36)',
     blob: 'BLOB',
@@ -193,25 +194,28 @@ const ENGINE_TYPES = {
     postgres: {
         scalars: { ...PG_SCALAR_MAP, vector: 'VECTOR', halfvec: 'HALFVEC', sparsevec: 'SPARSEVEC' },
         sizes: PG_SIZES,
+        timestampPrecision: 6,
     },
     // CockroachDB's VECTOR is native, no extension needed.
-    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES },
+    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES, timestampPrecision: 6 },
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
     mysql: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     mariadb: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
     sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
     // 2025 and up; below that the server refuses the type rather than storing it as text.
-    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
+    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES, timestampPrecision: 7 },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
 };
 /**
@@ -241,8 +245,11 @@ export function sqlToCanonical(sqlType) {
     const normalized = sqlType.toLowerCase().trim();
     const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
-    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
-    const match = withoutUnsigned.match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
+    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"], and Postgres's
+    // "timestamp(3) with time zone", whose parameter sits inside the name, as "timestamp with time zone(3)".
+    const match = withoutUnsigned
+        .replace(/^(\w+)\((\d+)\)\s+(.+)$/, '$1 $3($2)')
+        .match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
     const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
     if (!match || !base) {
         return { category: 'string', raw: sqlType };
@@ -260,7 +267,7 @@ export function sqlToCanonical(sqlType) {
         size: measured && params[0] === 'max' ? 'small' : base.size,
         withTimezone: base.withTimezone,
         length: measured ? first : undefined,
-        precision: decimal ? first : undefined,
+        precision: decimal || base.category === 'timestamp' ? first : undefined,
         scale: decimal ? second : undefined,
         unsigned: unsigned || undefined,
     };
@@ -317,6 +324,9 @@ export function canonicalToSql(type, dialect) {
     if (type.category === 'timestamp' && type.withTimezone && features.supportsTimestamptz) {
         sqlType = 'TIMESTAMPTZ';
     }
+    if (type.category === 'timestamp' && type.precision !== undefined && engine.timestampPrecision !== undefined) {
+        sqlType = `${sqlType.replace(/\(\d+\)$/, '')}(${type.precision})`;
+    }
     return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
 /** See {@link DialectFeatures.stringSizing} for what each mode means. */
@@ -343,12 +353,22 @@ function formatDecimalSqlType(type, fallback, baseType) {
 export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export function defaultTimestampPrecision(dialectName) {
+    return ENGINE_TYPES[dialectName].timestampPrecision;
+}
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
-    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+    const timestampPrecision = defaultTimestampPrecision(dialect.dialectName);
+    return (type) => {
+        const stored = sqlToCanonical(canonicalToSql(type, dialect));
+        return stored.category === 'timestamp' && stored.precision === undefined
+            ? { ...stored, precision: timestampPrecision }
+            : stored;
+    };
 }
 /**
  * Convert UQL FieldOptions to a canonical type.
@@ -363,14 +383,16 @@ export function fieldOptionsToCanonical(options) {
     switch (columnFamily(options.type)) {
         case 'numeric':
             // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
-            // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
+            // to happen, and the pools decode it back to a JS number at the wire (see `pgWireTypes`).
             return isIntegerColumn(options)
                 ? { category: 'integer', size: 'big' }
                 : { category: 'decimal', precision: options.precision, scale: options.scale };
         case 'boolean':
             return { category: 'boolean' };
+        // An instant: uql reads a zoneless timestamp as UTC, but the database's own clock and every other
+        // client read one in the session's zone.
         case 'date':
-            return { category: 'timestamp' };
+            return { category: 'timestamp', withTimezone: true, precision: options.precision };
         // `String`, and anything a reflected type left unrecognised.
         default:
             return { category: 'string', length: options.length };

package/dist/schema/schemaASTDiffer.js

@@ -124,7 +124,9 @@ function diffColumn(tableName, source, target, opts) {
     // inconsistently (`BIGINT(20)`, SQLite's `notnull: 0` rowid), so neither is compared.
     const generatedType = source.isAutoIncrement && target.isAutoIncrement;
     const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
-    const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
+    const expectedType = opts.normalizeType(source.type);
+    const actualType = opts.normalizeType(target.type);
+    const typeChanged = !generatedType && !areTypesEqual(expectedType, actualType);
     if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} -> ${formatType(target.type)}`);
     }
@@ -158,7 +160,7 @@ function diffColumn(tableName, source, target, opts) {
         // Only the type this diff actually reports: a column altered for its default carries no data loss,
         // and a generated key's type - never compared above - reads as unsigned against an entity that
         // cannot say so.
-        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(target.type, source.type),
+        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(actualType, expectedType),
         description: differences.join(', '),
     };
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,4 +1,4 @@
-import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
+import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
 import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
@@ -60,8 +60,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
         vector: (expr: string) => string;
     };
     private bytesAsText;
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/sqlite/sqliteDialect.js

@@ -3,9 +3,10 @@ import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
 import { QueryRaw, } from '../type/index.js';
 import { indexDistance, isVectorIndexType } from '../type/vector.js';
+import { utcTimestamp } from '../util/date.js';
 import { declaredIndexName } from '../util/ddlExpression.util.js';
 import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
-import { columnFamily, isIntegerColumn } from '../util/field.util.js';
+import { isIntegerColumn } from '../util/field.util.js';
 /**
  * An FTS5 query over `columns` for what a person typed: each word a quoted string, which FTS5 reads as a
  * term to match and never as syntax, and every one required, as the other engines read plain words.
@@ -128,7 +129,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     }
     normalizeValue(value) {
         if (value instanceof Date)
-            return value.getTime();
+            return utcTimestamp(value);
         return super.normalizeValue(value);
     }
     /**
@@ -169,10 +170,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     bytesAsText(expr) {
         return `${this.escape(BYTES_PREFIX)} || hex(${expr})`;
     }
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    hydrateKind(field) {
-        return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
-    }
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/type/entity.d.ts

@@ -288,7 +288,7 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     readonly columnType?: ColumnType | QueryRaw;
     /** A string column's length. */
     readonly length?: number;
-    /** A decimal column's precision. */
+    /** A decimal column's digits, or a timestamp's fractional-second digits. */
     readonly precision?: number;
     /** A decimal column's scale. */
     readonly scale?: number;

package/dist/type/queryWhere.d.ts

@@ -138,35 +138,37 @@ export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
      */
     $between?: readonly [ExpandScalar<T>, ExpandScalar<T>];
     /**
-     * whether a string begins with the given string (case sensitive).
+     * whether a string begins with the given text, taken literally (case sensitive).
      */
     $startsWith?: string;
     /**
-     * whether a string begins with the given string (case insensitive).
+     * whether a string begins with the given text, taken literally (case insensitive).
      */
     $istartsWith?: string;
     /**
-     * whether a string ends with the given string (case sensitive).
+     * whether a string ends with the given text, taken literally (case sensitive).
      */
     $endsWith?: string;
     /**
-     * whether a string ends with the given string (case insensitive).
+     * whether a string ends with the given text, taken literally (case insensitive).
      */
     $iendsWith?: string;
     /**
-     * whether a string is contained within the given string (case sensitive).
+     * whether a string contains the given text, taken literally (case sensitive).
      */
     $includes?: string;
     /**
-     * whether a string is contained within the given string (case insensitive).
+     * whether a string contains the given text, taken literally (case insensitive).
      */
     $iincludes?: string;
     /**
-     * whether a string fulfills the given pattern (case sensitive).
+     * whether a whole string matches the given pattern, the same on every engine: `%` is any run of
+     * characters, `_` any one, and `\` makes the next one literal; a last `\` with nothing after it to
+     * escape, `'John\'`, is refused (case sensitive).
      */
     $like?: string;
     /**
-     * whether a string fulfills the given pattern (case insensitive).
+     * whether a whole string matches the given pattern, as `$like` reads it (case insensitive).
      */
     $ilike?: string;
     /**

package/dist/util/date.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, then `zone`: how a date is written, whichever machine writes it. Not
+ * `toISOString` as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
+ */
+export declare function utcTimestamp(date: Date, zone?: string): string;
+/**
+ * A timestamp's text as the `Date` it names, the one rule every driver and hydration read dates by: UTC
+ * where it names no zone, its own offset where it does, a bare day at UTC midnight, and the fraction cut
+ * to the milliseconds a `Date` holds. Text that is none of these, such as `infinity`, stays text.
+ */
+export declare function decodeDate(text: string): Date | string;

package/dist/util/date.js

@@ -0,0 +1,19 @@
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, then `zone`: how a date is written, whichever machine writes it. Not
+ * `toISOString` as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
+ */
+export function utcTimestamp(date, zone = '') {
+    return date.toISOString().replace('T', ' ').replace('Z', zone);
+}
+/** A time of day that names no zone, which `Date` would read in the process's own. */
+const ZONELESS_TIME = /T[\d:.]+$/;
+/**
+ * A timestamp's text as the `Date` it names, the one rule every driver and hydration read dates by: UTC
+ * where it names no zone, its own offset where it does, a bare day at UTC midnight, and the fraction cut
+ * to the milliseconds a `Date` holds. Text that is none of these, such as `infinity`, stays text.
+ */
+export function decodeDate(text) {
+    const iso = text.replace(' ', 'T').replace(/(\.\d{3})\d+/, '$1');
+    const date = new Date(ZONELESS_TIME.test(iso) ? `${iso}Z` : iso);
+    return Number.isNaN(date.getTime()) ? text : date;
+}

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

@@ -63,11 +63,8 @@ export declare function whereEach<E>(keys: readonly FieldKey<E>[], valueOf: (key
 export declare function whereAnyOf<E>(clauses: QueryWhereArray<E>): QueryWhere<E>;
 /** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export declare function idOnlyQuery<E>(meta: EntityMeta<E>, q: QuerySearch<E>): Query<E>;
-/**
- * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
- * narrowing cast: `Array.isArray` does not narrow `readonly` arrays out of a union.
- */
-export declare function asSelectMap<E>(select: QuerySelectValue<E> | undefined): QuerySelect<E> | undefined;
+/** Whether `select` is the list form `raw()` fills, narrowing both ways, which `Array.isArray` does not for a `readonly` array. */
+export declare function isSelectList<E>(select: QuerySelectValue<E> | undefined): select is readonly QueryRaw[];
 export declare function normalizeScalarFieldSelection<E>(meta: EntityMeta<E>, select?: QuerySelect<E>, exclude?: QueryExclude<E>): FieldKey<E>[];
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export declare function isVectorSearch(value: unknown): value is QueryVectorSearch;

package/dist/util/dialect.util.js

@@ -138,12 +138,9 @@ export function whereAnyOf(clauses) {
 export function idOnlyQuery(meta, q) {
     return { ...q, $select: keySet(meta.ids) };
 }
-/**
- * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
- * narrowing cast: `Array.isArray` does not narrow `readonly` arrays out of a union.
- */
-export function asSelectMap(select) {
-    return Array.isArray(select) ? undefined : select;
+/** Whether `select` is the list form `raw()` fills, narrowing both ways, which `Array.isArray` does not for a `readonly` array. */
+export function isSelectList(select) {
+    return Array.isArray(select);
 }
 export function normalizeScalarFieldSelection(meta, select, exclude) {
     // A positive `$select` (the common case) wins outright and returns

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

@@ -1,6 +1,6 @@
 import { type ColumnFamily, type FamilyOf, type FieldOptions, QueryRaw, type StampEvent } from '../type/index.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -23,7 +23,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly version: 'numeric';
     readonly columnType: '*';
     readonly length: 'string';
-    readonly precision: 'numeric';
+    readonly precision: readonly ["numeric", "date"];
     readonly scale: 'numeric';
     readonly nullable: '*';
     readonly unique: '*';
@@ -91,8 +91,10 @@ type DeadOptions<O> = (O extends {
     readonly nullable: true;
 } ? 'nullable' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
+/** The families option `K` applies to, `'*'` for every one. */
+type OptionFamilies<K extends keyof FieldOptions> = (typeof FIELD_OPTION_FAMILY)[K] extends readonly (infer F)[] ? F : (typeof FIELD_OPTION_FAMILY)[K];
 type Offending<O> = {
-    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
+    [K in Given<O>]: [Extract<OptionFamilies<K>, OptionsFamily<O> | '*'>] extends [never] ? K : K extends DeadOptions<O> ? K : never;
 }[Given<O>];
 /**
  * Every option `O` states but cannot use, mapped to `never`, so one that would be ignored does not compile.

package/dist/util/fieldOption.util.js

@@ -3,7 +3,7 @@ import { columnFamily, isInlinedExpression } from './field.util.js';
 import { getKeys } from './object.util.js';
 import { constantSql } from './raw.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -26,7 +26,8 @@ const FIELD_OPTION_FAMILY = {
     version: 'numeric',
     columnType: '*',
     length: 'string',
-    precision: 'numeric',
+    // A decimal's digits, or a timestamp's fractional-second digits.
+    precision: ['numeric', 'date'],
     scale: 'numeric',
     nullable: '*',
     unique: '*',
@@ -116,11 +117,11 @@ export function fieldOptionConflict(opts) {
     // conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check
     // reports where it can still be spelled right.
     for (const key of getKeys(FIELD_OPTION_FAMILY)) {
-        const applies = FIELD_OPTION_FAMILY[key];
+        const applies = [FIELD_OPTION_FAMILY[key]].flat();
         if (opts[key] === undefined)
             continue;
-        if (family && applies !== '*' && applies !== family) {
-            return `cannot use '${key}': it applies to a ${applies} column, not to a ${family} one`;
+        if (family && !applies.includes('*') && !applies.includes(family)) {
+            return `cannot use '${key}': it applies to a ${applies.join(' or ')} column, not to a ${family} one`;
         }
         const dead = deadOn(opts, key);
         if (dead) {

package/dist/util/sqlLiteral.d.ts

@@ -2,7 +2,14 @@
 export declare function escapeSingleQuotes(val: string): string;
 /** The text a MySQL string literal's body stands for: its backslash escapes and doubled quotes undone. */
 export declare function unescapeMysqlString(body: string): string;
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export declare const PG_UTC = "+00";
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export declare const escapeAnsiSqlLiteral: (value: unknown) => string;
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export declare const escapePgSqlLiteral: (value: unknown) => string;
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export declare const escapeMysqlSqlLiteral: (value: unknown) => string;

package/dist/util/sqlLiteral.js

@@ -1,6 +1,7 @@
 // SQL literal escaping for `Dialect.escape`: ANSI quote doubling, or MySQL's backslashes. UQL binds
 // values instead, so this is the hand-written-SQL hatch, and inline MySQL literals break under
 // `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters. Postgres arrays are separate.
+import { utcTimestamp } from './date.js';
 import { UqlUsageError } from './uqlError.js';
 const SINGLE_QUOTE = /'/g;
 /** Doubles every single quote in `val`, the ANSI escaping shared by string literals and JSON path keys. */
@@ -43,12 +44,8 @@ function bytesToHexLiteral(bytes) {
  * A factory, not a function taking `escapeString` as an argument: threading it through every call
  * measured 1.1-1.5x slower. Rejects unsupported types rather than stringifying them into SQL.
  */
-function createEscaper(escapeString) {
-    /**
-     * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, so the SQL is the same whichever machine wrote it. Not `toISOString`
-     * as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
-     */
-    const dateLiteral = (date) => escapeString(date.toISOString().replace('T', ' ').replace('Z', ''));
+function createEscaper(escapeString, zone = '') {
+    const dateLiteral = (date) => escapeString(utcTimestamp(date, zone));
     const sqlList = (arr) => {
         let sql = '';
         for (let i = 0; i < arr.length; i++) {
@@ -98,7 +95,14 @@ function createEscaper(escapeString) {
     };
     return escapeValue;
 }
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export const PG_UTC = '+00';
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export const escapeAnsiSqlLiteral = createEscaper(ansiStringLiteral);
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export const escapePgSqlLiteral = createEscaper(ansiStringLiteral, PG_UTC);
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export const escapeMysqlSqlLiteral = createEscaper(mysqlStringLiteral);

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.82.0",
+  "version": "0.83.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -74,7 +74,7 @@ export class Post {
 }
 ```
 
-- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
+- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date` (an instant, bound and read as UTC on every engine; `TIMESTAMPTZ` on Postgres and CockroachDB, `DATETIME(3)` on MySQL and MariaDB; `precision` sets its fractional-second digits), `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
 - A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
 - An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.