uql-orm 0.81.0 → 0.83.0

package/dist/entity/metadata/definition.js

@@ -1,6 +1,7 @@
 import { RelationAggregate, SOFT_DELETE_FILTER } from '../../type/index.js';
-import { isInlinedExpression } from '../../util/field.util.js';
-import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
+import { fieldKeys, isInlinedExpression } from '../../util/field.util.js';
+import { entitySql, entityWhere, fieldOptionConflict, hasKeys, isToManyRelation, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, whereWith, } from '../../util/index.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -22,18 +23,18 @@ export function defineField(entity, key, opts = {}) {
     // A relation aggregate reads as a correlated subquery, which no engine accepts in a generated column:
     // keeping one on the row takes the triggers a write fires, which are not built yet.
     if (opts.stored && sql instanceof RelationAggregate) {
-        throw new TypeError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
             "engine keeps in a generated column. Drop 'stored' to have it read on each query.");
     }
     // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
     // its expression being spliced in rather than declared.
     if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
-        throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }
     const conflict = fieldOptionConflict(opts);
     if (conflict) {
-        throw new TypeError(`'${entity.name}.${key}' ${conflict}.`);
+        throw new UqlUsageError(`'${entity.name}.${key}' ${conflict}.`);
     }
     const fieldKey = key;
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
@@ -75,10 +76,10 @@ function keyMap() {
 const KEY_MAP = new Proxy({}, { get: (_, key) => key });
 function addRelation(entity, key, registration) {
     if (!registration.entity) {
-        throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
+        throw new UqlUsageError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
     if (registration.through && registration.references) {
-        throw new TypeError(`'${entity.name}.${key}' joins through a junction, whose column referencing each side is the join; ` +
+        throw new UqlUsageError(`'${entity.name}.${key}' joins through a junction, whose column referencing each side is the join; ` +
             "'references' pairs the declaring entity's columns with the target's instead.");
     }
     const meta = ensureWritableMeta(entity);
@@ -120,10 +121,10 @@ export function defineTrigger(entity, trigger) {
     const meta = ensureWritableMeta(entity);
     // The type already refuses an empty map; this is the same answer for plain JavaScript.
     if (typeof trigger.run !== 'function' && !hasKeys(trigger.run)) {
-        throw new TypeError(`'${entity.name}' has a trigger whose body names at least one engine to run on`);
+        throw new UqlUsageError(`'${entity.name}' has a trigger whose body names at least one engine to run on`);
     }
     if (trigger.name && meta.triggers?.some((it) => it.name === trigger.name)) {
-        throw new TypeError(`'${entity.name}' already has a trigger named '${trigger.name}'`);
+        throw new UqlUsageError(`'${entity.name}' already has a trigger named '${trigger.name}'`);
     }
     (meta.triggers ??= []).push({ ...trigger, of: trigger.of?.(memberRefs()).map((ref) => ref.key) });
     return meta;
@@ -131,12 +132,12 @@ export function defineTrigger(entity, trigger) {
 export function defineFilter(entity, name, opts) {
     const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
-        throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
+        throw new UqlUsageError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
     // Widened for a caller the types did not reach, which is the only one this can refuse.
     const { security, onMissing } = opts;
     if (security && onMissing === 'skip') {
-        throw TypeError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
+        throw new UqlUsageError(`'${entity.name}' security filter '${name}' cannot use onMissing: 'skip' (it must fail closed)`);
     }
     (meta.filters ??= {})[name] = opts;
     return meta;
@@ -173,7 +174,7 @@ export function defineEntity(entity, opts = {}) {
     // statement builds and then fails at the database. `schema` is the way to say it.
     if (opts.name?.includes('.')) {
         const [schema, ...rest] = opts.name.split('.');
-        throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
+        throw new UqlUsageError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
             `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
     }
     const meta = ensureWritableMeta(entity);
@@ -201,7 +202,7 @@ export function defineEntity(entity, opts = {}) {
         defineFilter(entity, name, filter);
     }
     if (!hasKeys(meta.fields)) {
-        throw TypeError(`'${entity.name}' must have fields`);
+        throw new UqlUsageError(`'${entity.name}' must have fields`);
     }
     // A later call composes onto the entity, so a name is only ever set, and `derivedName` records that
     // the class name stood in, which is what a naming strategy derives from.
@@ -221,21 +222,18 @@ export function defineEntity(entity, opts = {}) {
     // Derive soft-delete from the (inheritance-merged) fields, so own and inherited markers are handled
     // uniformly. Exactly one field may be marked; it auto-registers the built-in `softDelete` read
     // filter (a reserved name - see defineFilter - so it never clobbers a user filter).
-    const softDeleteKeys = getKeys(meta.fields).filter((key) => {
-        const softDelete = meta.fields[key]?.softDelete;
-        return softDelete !== undefined && softDelete !== false;
-    });
+    const softDeleteKeys = fieldKeys(meta, ({ softDelete }) => softDelete !== undefined && softDelete !== false);
     if (softDeleteKeys.length > 1) {
-        throw TypeError(`'${entity.name}' must have at most one field with 'softDelete'`);
+        throw new UqlUsageError(`'${entity.name}' must have at most one field with 'softDelete'`);
     }
     if (softDeleteKeys.length) {
         meta.softDelete = softDeleteKeys[0];
-        (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
+        (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: whereWith(meta.softDelete, null), default: true };
     }
     // The optimistic lock, derived the same way and just as singular: one row has one version.
-    const versionKeys = getKeys(meta.fields).filter((key) => meta.fields[key]?.version);
+    const versionKeys = fieldKeys(meta, (field) => field.version);
     if (versionKeys.length > 1) {
-        throw TypeError(`'${entity.name}' must have at most one field with 'version'`);
+        throw new UqlUsageError(`'${entity.name}' must have at most one field with 'version'`);
     }
     if (versionKeys.length) {
         meta.version = versionKeys[0];
@@ -246,7 +244,7 @@ export function defineEntity(entity, opts = {}) {
     }
     const ids = getIdKeys(meta);
     if (!ids.length) {
-        throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
+        throw new UqlUsageError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
     }
     meta.ids = ids;
     return meta;
@@ -262,7 +260,7 @@ export function assertSoleId(meta, what) {
     if (ids.length === 1) {
         return;
     }
-    throw new TypeError(ids.length
+    throw new UqlUsageError(ids.length
         ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support yet.`
         : // An entity registered with `@Field` but no `@Entity` never ran the check in `defineEntity`.
             `'${meta.entity.name}' has no primary key, which ${what} needs.`);
@@ -276,7 +274,7 @@ export function soleIdOf(meta, what) {
 export function fieldOf(meta, key) {
     const field = meta.fields[key];
     if (!field) {
-        throw new TypeError(`'${meta.entity.name}' has no field '${key}'`);
+        throw new UqlUsageError(`'${meta.entity.name}' has no field '${key}'`);
     }
     return field;
 }
@@ -284,7 +282,7 @@ export function fieldOf(meta, key) {
 export function relationOf(meta, key) {
     const relation = meta.relations[key];
     if (!relation) {
-        throw new TypeError(`'${meta.entity.name}' has no relation '${key}'`);
+        throw new UqlUsageError(`'${meta.entity.name}' has no relation '${key}'`);
     }
     return relation;
 }
@@ -342,7 +340,7 @@ export function getMeta(entity) {
 function registeredMeta(entity) {
     const meta = metas.get(entity);
     if (!meta) {
-        throw TypeError(`'${entity.name}' is not an entity`);
+        throw new UqlUsageError(`'${entity.name}' is not an entity`);
     }
     return meta;
 }
@@ -351,7 +349,7 @@ function fillRelations(meta) {
         const at = `'${meta.entity.name}.${relKey}'`;
         const references = settledReferences(at, meta, relKey, relation);
         if (!references.length) {
-            throw new TypeError(`${at} has no columns to join on.`);
+            throw new UqlUsageError(`${at} has no columns to join on.`);
         }
         if (!relation.through) {
             assertJoins(at, meta, relation, references);
@@ -371,7 +369,7 @@ function settledReferences(at, meta, relKey, relOpts) {
     if (typeof references === 'string') {
         const target = ensureMeta(relOpts.entity());
         if (mappedBy || isToManyRelation(relOpts) || target.ids.length > 1) {
-            throw new TypeError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
+            throw new UqlUsageError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
                 'can: pair the columns, [{ local, foreign }].');
         }
         relOpts.references = [{ local: references, foreign: soleIdOf(target, 'a foreign key') }];
@@ -383,7 +381,7 @@ function settledReferences(at, meta, relKey, relOpts) {
         return fillInverseSide(at, meta, relOpts, mappedBy);
     if (through)
         return fillThrough(at, meta, relOpts, through);
-    throw new TypeError(isToManyRelation(relOpts)
+    throw new UqlUsageError(isToManyRelation(relOpts)
         ? `${at} is a to-many relation with no way to join: it needs 'mappedBy' (the member on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns)."
         : `${at} needs 'references', the foreign key column it joins by, or 'mappedBy', the member on the other ` +
@@ -407,7 +405,7 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     const other = `'${relMeta.entity.name}.${mappedBy}'`;
     if (relMeta.fields[mappedBy]) {
         if (meta.ids.length > 1) {
-            throw new TypeError(`${at} is mapped by ${other}, one column, but the primary key of ` +
+            throw new UqlUsageError(`${at} is mapped by ${other}, one column, but the primary key of ` +
                 `'${meta.entity.name}' is composite (${meta.ids.join(', ')}). Map it by the relation on the other side ` +
                 'instead, which joins every column of the key.');
         }
@@ -417,14 +415,14 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     }
     const owner = relMeta.relations[mappedBy];
     if (!owner) {
-        throw new TypeError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relMeta.entity.name}'.`);
+        throw new UqlUsageError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relMeta.entity.name}'.`);
     }
     if (owner.mappedBy) {
-        throw new TypeError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
+        throw new UqlUsageError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
     }
     const ownerTarget = owner.entity();
     if (!isA(meta.entity, ownerTarget)) {
-        throw new TypeError(`${at} is mapped by ${other}, a relation to '${ownerTarget.name}', not to '${meta.entity.name}'.`);
+        throw new UqlUsageError(`${at} is mapped by ${other}, a relation to '${ownerTarget.name}', not to '${meta.entity.name}'.`);
     }
     const ownerReferences = settledReferences(other, relMeta, mappedBy, owner);
     // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
@@ -454,11 +452,11 @@ function assertJoins(at, meta, relOpts, pairs) {
             const column = `'${side.meta.entity.name}.${key}'`;
             const field = side.meta.fields[key];
             if (!field || isInlinedExpression(field)) {
-                throw new TypeError(`${at} joins ${column}, which is not a column: declare it with '@Field'.`);
+                throw new UqlUsageError(`${at} joins ${column}, which is not a column: declare it with '@Field'.`);
             }
             const referenced = side.holds && pairs.length === 1 ? field.references?.() : undefined;
             if (referenced && !isA(side.joins, referenced)) {
-                throw new TypeError(`${at} joins ${column}, a foreign key to '${referenced.name}', not to '${side.joins.name}'.`);
+                throw new UqlUsageError(`${at} joins ${column}, a foreign key to '${referenced.name}', not to '${side.joins.name}'.`);
             }
         }
     }
@@ -491,7 +489,7 @@ export function foreignKeysOf(meta) {
         if (!target.ids.length)
             return [];
         if (target.ids.length > 1) {
-            throw new TypeError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
+            throw new UqlUsageError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
                 `(${target.ids.join(', ')}): a column points at one. Declare a column per key and pair each with it ` +
                 `in a '@ManyToOne' to '${target.entity.name}'.`);
         }
@@ -509,11 +507,11 @@ function junctionReferences(at, junction, side) {
             const declare = side.ids.length > 1
                 ? `a column per key, paired in a '@ManyToOne' to '${side.entity.name}'`
                 : `'@Field({ references: () => ${side.entity.name} })'`;
-            throw new TypeError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare ${declare}.`);
+            throw new UqlUsageError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare ${declare}.`);
         }
         if (others.length) {
             const columns = [pair, ...others].map(({ local }) => `'${local}'`).join(' and ');
-            throw new TypeError(`${at} joins through '${junction.entity.name}', where ${columns} each reference ${referenced}: a junction ` +
+            throw new UqlUsageError(`${at} joins through '${junction.entity.name}', where ${columns} each reference ${referenced}: a junction ` +
                 'needs exactly one column per key of each side.');
         }
         return { local: pair.local, foreign: key };
@@ -521,7 +519,7 @@ function junctionReferences(at, junction, side) {
 }
 /** Every key the entity marks, in declaration order. More than one is a composite primary key. */
 function getIdKeys(meta) {
-    return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);
+    return fieldKeys(meta, (field) => field.isId);
 }
 /**
  * Merges `ancestor` and its ancestors into `meta`, nearest first, draining an undecorated base's

package/dist/http/handler.js

@@ -1,6 +1,7 @@
 import { withContext } from '../context/context.js';
 import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
-import { whereIds } from '../util/dialect.util.js';
+import { whereIds, whereWith } from '../util/dialect.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
@@ -16,14 +17,14 @@ export function createRequestHandler(opts) {
         entities = entities.filter((entity) => !exclude.includes(entity));
     }
     if (!entities.length) {
-        throw new TypeError('no entities for the uql middleware');
+        throw new UqlUsageError('no entities for the uql middleware');
     }
     // All of them at once, so fixing the first collision does not just reveal the next.
     const byPath = Map.groupBy(entities, pathOf);
     const collisions = [...byPath].filter(([, clashing]) => clashing.length > 1);
     if (collisions.length) {
         const lines = collisions.map(([path, clashing]) => `  /${path} <- ${clashing.map(tableOf).join(', ')}`);
-        throw new TypeError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
+        throw new UqlUsageError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
             "A route is the kebab-cased class name unless 'entityPath' says otherwise. Name them apart, " +
             "pass an 'entityPath', or pass only one of them in 'include'.");
     }
@@ -157,6 +158,6 @@ function ok(body) {
     return { status: 200, body };
 }
 function buildIdQuery(meta, id, query) {
-    query.$where = { ...query.$where, [soleIdOf(meta, 'the HTTP handler')]: id };
+    query.$where = whereWith(soleIdOf(meta, 'the HTTP handler'), id, query.$where);
     return query;
 }

package/dist/http/query.d.ts

@@ -3,7 +3,7 @@ import type { WireQuery } from '../type/index.js';
  * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
  * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
-export declare function parseQueryParams(params?: Record<string, unknown>): WireQuery<unknown>;
+export declare function parseQueryParams<E = unknown>(params?: Record<string, unknown>): WireQuery<E>;
 /**
  * Serialize a UQL query object into a percent-encoded query string where object values
  * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.

package/dist/http/query.js

@@ -105,11 +105,11 @@ export function wireJson(value) {
             return held;
         }
         if (RAW_VALUE in held) {
-            throw new TypeError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
+            throw new UqlUsageError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
         }
         // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.
         if (held instanceof ArrayBuffer || ArrayBuffer.isView(held)) {
-            throw new TypeError('binary cannot travel over HTTP: what leaves the browser is JSON');
+            throw new UqlUsageError('binary cannot travel over HTTP: what leaves the browser is JSON');
         }
         return held;
     });

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export { withDeleted } from './util/filters.util.js';
 export type { HookContext } from './util/hook.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export { deleteFrom, insertInto, updateTable } from './util/triggerWrite.js';
 export * from './util/uqlError.js';

package/dist/index.js

@@ -7,4 +7,5 @@ export * from './type/index.js';
 export { withDeleted } from './util/filters.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export { deleteFrom, insertInto, updateTable } from './util/triggerWrite.js';
 export * from './util/uqlError.js';

package/dist/maria/mariadbQuerierPool.js

@@ -9,8 +9,10 @@ export class MariadbQuerierPool extends AbstractSqlQuerierPool {
     constructor(opts, extra) {
         super(new MariaDialect(dialectOptionsFrom(extra)), extra);
         // BIGINT stays the driver's `bigint`, which `MariadbQuerier` decodes by the rule every driver here
-        // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word.
-        this.pool = createPool(opts);
+        // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word. A date
+        // reads as its UTC text, which hydration decodes, since the connector would take it for local time
+        // whatever `timezone` says; that only sets the session's zone, UTC, so `NOW()` agrees.
+        this.pool = createPool({ timezone: 'Z', dateStrings: true, ...opts });
         // `mariadb` fires 'error' at runtime without declaring it, hence the cast; this makes it visible.
         attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error', extra?.logger);
     }

package/dist/migrate/acquireQuerierForMigrations.js

@@ -1,4 +1,5 @@
 import { isMongoQuerier, isSqlQuerier, } from '../type/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Querier used for schema migrations and the migration journal.
  *
@@ -34,7 +35,7 @@ export function withMongoQuerierForMigrations(pool, requiredBy, task) {
 function withQuerierOfKind(pool, isKind, error, task) {
     return withQuerierForMigrations(pool, (querier) => {
         if (!isKind(querier)) {
-            throw new TypeError(error);
+            throw new UqlUsageError(error);
         }
         return task(querier);
     });

package/dist/migrate/assertCliConfig.js

@@ -1,30 +1,31 @@
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Validates shape required for the migrations CLI (real `QuerierPool`, not config stubs).
  */
 export function assertCliConfig(config) {
     if (config === null || typeof config !== 'object') {
-        throw new TypeError('Config must be a non-null object');
+        throw new UqlUsageError('Config must be a non-null object');
     }
     const c = config;
     const pool = c['pool'];
     if (pool === null || typeof pool !== 'object') {
-        throw new TypeError('Config.pool is required and must be an object');
+        throw new UqlUsageError('Config.pool is required and must be an object');
     }
     const p = pool;
     for (const key of ['getQuerier', 'transaction', 'withQuerier']) {
         if (typeof p[key] !== 'function') {
-            throw new TypeError(`Config.pool.${key} must be a function`);
+            throw new UqlUsageError(`Config.pool.${key} must be a function`);
         }
     }
     if (p['end'] !== undefined && typeof p['end'] !== 'function') {
-        throw new TypeError('Config.pool.end must be a function when provided');
+        throw new UqlUsageError('Config.pool.end must be a function when provided');
     }
     const dialect = p['dialect'];
     if (dialect === null || typeof dialect !== 'object') {
-        throw new TypeError('Config.pool.dialect is required and must be an object');
+        throw new UqlUsageError('Config.pool.dialect is required and must be an object');
     }
     const dialectName = dialect['dialectName'];
     if (typeof dialectName !== 'string') {
-        throw new TypeError('Config.pool.dialect.dialectName must be a string');
+        throw new UqlUsageError('Config.pool.dialect.dialectName must be a string');
     }
 }

package/dist/migrate/builder/expressions.d.ts

@@ -13,6 +13,8 @@ export type DialectDefaults = {
     readonly expressions: SqlExpressionMap;
     /** Column types whose `DEFAULT` this engine takes only as a parenthesized expression. */
     readonly wrapTypes?: RegExp;
+    /** Column types whose `CURRENT_TIMESTAMP` default must repeat their precision, captured by the pattern. */
+    readonly preciseTypes?: RegExp;
 };
 /**
  * Looked up by name rather than carried on the dialect, which keeps DDL data out of the query

package/dist/migrate/builder/expressions.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../../util/uqlError.js';
 const ANSI = {
     now: 'CURRENT_TIMESTAMP',
     currentDate: 'CURRENT_DATE',
@@ -14,6 +15,8 @@ const MYSQL = {
 };
 /** MySQL 8.0.13+ rejects `DEFAULT 'x'` on these but accepts `DEFAULT ('x')`, whatever the value. */
 const MYSQL_LARGE_TYPES = /^\s*(TINY|MEDIUM|LONG)?(TEXT|BLOB)|^\s*(JSON|GEOMETRY)\b/i;
+/** A `DATETIME(3)` or `TIMESTAMP(3)`, whose fractional-second precision is captured. */
+const MYSQL_PRECISE_TYPES = /^\s*(?:DATETIME|TIMESTAMP)\((\d)\)/i;
 /**
  * Looked up by name rather than carried on the dialect, which keeps DDL data out of the query
  * bundle - the same split that keeps `CANONICAL_TO_SQL` in `schema/canonicalType.ts`. `uuidv7()` is
@@ -23,8 +26,12 @@ const MYSQL_LARGE_TYPES = /^\s*(TINY|MEDIUM|LONG)?(TEXT|BLOB)|^\s*(JSON|GEOMETRY
 export const DIALECT_DEFAULTS = {
     postgres: { expressions: { ...PG, uuidv7: 'uuidv7()' } },
     cockroachdb: { expressions: PG },
-    mysql: { expressions: MYSQL, wrapTypes: MYSQL_LARGE_TYPES },
-    mariadb: { expressions: { ...MYSQL, uuidv7: 'UUID_v7()' }, wrapTypes: MYSQL_LARGE_TYPES },
+    mysql: { expressions: MYSQL, wrapTypes: MYSQL_LARGE_TYPES, preciseTypes: MYSQL_PRECISE_TYPES },
+    mariadb: {
+        expressions: { ...MYSQL, uuidv7: 'UUID_v7()' },
+        wrapTypes: MYSQL_LARGE_TYPES,
+        preciseTypes: MYSQL_PRECISE_TYPES,
+    },
     sqlite: { expressions: ANSI },
     // `SYSUTCDATETIME()` over `CURRENT_TIMESTAMP`, which is local time in the server's zone. No
     // `uuidv7`: `NEWSEQUENTIALID()` is an ordered v4 GUID, so it carries no readable timestamp and
@@ -79,7 +86,7 @@ export const expr = {
  * the result needs wrapping, which MySQL demands on its large types whatever the value.
  */
 export function formatDefaultValue(value, dialect, columnType) {
-    const sql = defaultLiteral(value, dialect);
+    const sql = defaultLiteral(value, dialect, columnType);
     const { wrapTypes } = DIALECT_DEFAULTS[dialect.dialectName];
     return columnType !== undefined && wrapTypes?.test(columnType) ? `(${sql})` : sql;
 }
@@ -113,23 +120,26 @@ export function sameDefault(desired, current, dialect) {
  * cannot serve stay here: a boolean is `1` where booleans are integers, and a plain object or array
  * is JSON rather than the throw and the IN-list `escape` gives them.
  */
-function defaultLiteral(value, dialect) {
+function defaultLiteral(value, dialect, columnType) {
     if (value === undefined || value === null) {
         return 'NULL';
     }
     if (SqlExpression.isExpression(value)) {
-        return expressionSql(value, dialect);
+        return expressionSql(value, dialect, columnType);
     }
     if (typeof value === 'boolean') {
         return dialect.booleanLiteral === 'native' ? (value ? 'TRUE' : 'FALSE') : value ? '1' : '0';
     }
     return dialect.escape(typeof value === 'object' && !(value instanceof Date) ? JSON.stringify(value) : value);
 }
-function expressionSql(expression, dialect) {
-    const { expressions } = DIALECT_DEFAULTS[dialect.dialectName];
-    const sql = expression.kind === 'raw' ? expression.sql : expressions[expression.kind];
+function expressionSql(expression, dialect, columnType) {
+    const { expressions, preciseTypes } = DIALECT_DEFAULTS[dialect.dialectName];
+    const raw = expression.kind === 'raw';
+    const sql = raw ? expression.sql : expressions[expression.kind];
     if (sql == null) {
-        throw new TypeError(`${dialect.dialectName} has no '${expression.kind}' default; pass expr.raw(...) with SQL this engine accepts`);
+        throw new UqlUsageError(`${dialect.dialectName} has no '${expression.kind}' default; pass expr.raw(...) with SQL this engine accepts`);
     }
-    return sql;
+    // A raw default is the caller's SQL, never rewritten.
+    const precision = raw || columnType === undefined ? undefined : preciseTypes?.exec(columnType)?.[1];
+    return precision === undefined ? sql : sql.replaceAll('CURRENT_TIMESTAMP', `CURRENT_TIMESTAMP(${precision})`);
 }

package/dist/migrate/builder/tableBuilder.js

@@ -144,7 +144,7 @@ export class TableBuilder {
         return this.timestampNow('updatedAt');
     }
     timestampNow(name) {
-        return this.add(name, { category: 'timestamp' }, { defaultValue: expr.now() });
+        return this.timestamptz(name, { defaultValue: expr.now() });
     }
     timestamps() {
         this.createdAt();

package/dist/migrate/cli-config.js

@@ -1,13 +1,14 @@
 import { stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Loads the config with a plain `import()`, leaving TypeScript to the runtime: uql bundles no transpiler,
  * since only the project knows its decorator spec. Node's type stripping handles no decorators.
  */
 async function importConfig(path) {
     const mod = (await import(pathToFileURL(path).href).catch((cause) => {
-        throw new TypeError(`Could not import ${path}: ${cause?.message}\n` +
+        throw new UqlUsageError(`Could not import ${path}: ${cause?.message}\n` +
             'If it reaches entity classes, their decorators need a runtime that transforms TypeScript, not ' +
             'just one that strips its types. Run the CLI with `bun`, or with `node --import tsx` ' +
             '(`npm i -D tsx`). A JavaScript config, or passing the config inline, needs neither.', { cause });
@@ -21,14 +22,14 @@ export async function loadConfig(customPath) {
             .then(() => true)
             .catch(() => false);
         if (!exists) {
-            throw new TypeError(`Could not find uql configuration file at ${customPath}`);
+            throw new UqlUsageError(`Could not find uql configuration file at ${customPath}`);
         }
         try {
             const config = await importConfig(fullPath);
             return config;
         }
         catch (error) {
-            throw new TypeError(`Could not load configuration file at ${customPath}: ${error.message}`);
+            throw new UqlUsageError(`Could not load configuration file at ${customPath}: ${error.message}`);
         }
     }
     const configPaths = ['uql.config.ts', 'uql.config.js', 'uql.config.mjs', '.uqlrc.ts', '.uqlrc.js'];
@@ -42,5 +43,5 @@ export async function loadConfig(customPath) {
             return config;
         }
     }
-    throw new TypeError('Could not find uql configuration file. Create a uql.config.ts or uql.config.js file in your project root.');
+    throw new UqlUsageError('Could not find uql configuration file. Create a uql.config.ts or uql.config.js file in your project root.');
 }

package/dist/migrate/ddl/indexDdl.js

@@ -2,6 +2,7 @@ import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { INDEX_TYPES } from '../../schema/types.js';
 import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
 import { fulltextConfig, getKeys } from '../../util/index.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 /**
  * What in an index asks for each feature. A `Record` over the feature union rather than a list, so a
  * feature added to {@link INDEX_FEATURE_LABELS} cannot reach a dialect without the test that decides
@@ -20,14 +21,14 @@ const INDEX_FEATURE_PROBES = {
 /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
 export function assertIndexType(index, types, dialectName, hints = new Map()) {
     if (index.type && !types.has(index.type)) {
-        throw new TypeError(`${dialectName} has no ${index.type} index (index "${index.name}")` + (hints.get(index.type) ?? ''));
+        throw new UqlUsageError(`${dialectName} has no ${index.type} index (index "${index.name}")` + (hints.get(index.type) ?? ''));
     }
 }
 /** Refuses an index asking for a feature `features` lacks. */
 export function assertIndexFeatures(index, features, dialectName) {
     for (const feature of getKeys(INDEX_FEATURE_PROBES)) {
         if (INDEX_FEATURE_PROBES[feature](index) && !features.has(feature)) {
-            throw new TypeError(`${dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
+            throw new UqlUsageError(`${dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
         }
     }
 }
@@ -122,7 +123,7 @@ export class IndexDdl {
      * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
      */
     jsonArrayIndexExpr(_escapedColumn, _json) {
-        throw new TypeError(`${this.dialect.dialectName} has no multi-valued index`);
+        throw new UqlUsageError(`${this.dialect.dialectName} has no multi-valued index`);
     }
     /** Postgres-wire dialects put a vector or user-declared operator class here. */
     indexColumnOpsClass(_entry, _index) {

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -1,5 +1,6 @@
 import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { indexDistance, isVectorIndexType, unsupportedVectorMetric, VECTOR_INDEX_TYPES } from '../../type/vector.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { IndexDdl } from './indexDdl.js';
 /**
  * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext` is
@@ -38,14 +39,14 @@ export class MySqlIndexDdl extends MysqlLikeIndexDdl {
     jsonPathIndexExpr(escapedColumn, json) {
         const mode = jsonTypeMode(json.type);
         if (mode === 'json') {
-            throw new TypeError(`mysql cannot index the boolean JSON path '${json.path}', which compares as JSON`);
+            throw new UqlUsageError(`mysql cannot index the boolean JSON path '${json.path}', which compares as JSON`);
         }
         const expr = super.jsonPathIndexExpr(escapedColumn, json);
         if (mode === 'numeric') {
             return expr;
         }
         if (!json.length) {
-            throw new TypeError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
+            throw new UqlUsageError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
         }
         return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
     }
@@ -132,13 +133,13 @@ function arrayCastType(json) {
     const type = json.type;
     const cast = ARRAY_CASTS.get(typeof type === 'string' ? type.toLowerCase() : type);
     if (!cast) {
-        throw new TypeError(`mysql has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
+        throw new UqlUsageError(`mysql has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
     }
     if (cast !== 'CHAR' && cast !== 'BINARY') {
         return cast;
     }
     if (!json.length) {
-        throw new TypeError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
+        throw new UqlUsageError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
     }
     return `${cast}(${json.length})`;
 }

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,4 +1,5 @@
 import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export class PgIndexDdl extends IndexDdl {
@@ -49,7 +50,7 @@ export class PgIndexDdl extends IndexDdl {
         const opsClass = `${vectorType}_${metric}_ops`;
         // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
         if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || distance === 'l1')) {
-            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+            throw new UqlUsageError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
         }
         return ` ${opsClass}`;
     }