uql-orm 0.34.1 → 0.36.0

package/README.md

@@ -7,7 +7,7 @@
   </picture>
 </a>
 
-<h3>The JSON-native TypeScript ORM</h3>
+<h3>The JSON-native ORM</h3>
 
 <p>Queries are plain JSON, typed to the leaf. Unified across SQL databases and MongoDB.</p>
 

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

@@ -1,86 +1,65 @@
+import type { AbstractSqlDialect } from '../../dialect/index.js';
+import type { SqlDialectName } from '../../type/index.js';
 /**
- * SQL Expressions
- *
- * Type-safe SQL expressions for default values and other uses.
- * Provides a `t` helper with common expressions.
+ * A {@link ColumnSchema.defaultValue} that is SQL rather than a literal. Kinds are symbolic: the
+ * dialect names the spelling and {@link formatDefaultValue} renders one at DDL time.
  */
+export type SqlExpressionKind = 'now' | 'currentDate' | 'currentTime' | 'uuid' | 'uuidv7' | 'onUpdateNow' | 'raw';
+/** Every kind's DDL spelling, `null` where an engine has none. `raw` carries its own text instead. */
+export type SqlExpressionMap = Readonly<Record<Exclude<SqlExpressionKind, 'raw'>, string | null>>;
+/** How one engine renders a DDL default. A new per-dialect rule is a field here, not a second table. */
+export type DialectDefaults = {
+    /** Spelling of each kind, `null` where the engine has none. */
+    readonly expressions: SqlExpressionMap;
+    /** Column types whose `DEFAULT` this engine takes only as a parenthesized expression. */
+    readonly wrapTypes?: RegExp;
+};
 /**
- * Represents a raw SQL expression (not a literal value).
+ * 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
+ * Postgres 18+ and `UUID_v7()` MariaDB 11.7+; a server below those rejects it itself, the version
+ * not being knowable here.
+ */
+export declare const DIALECT_DEFAULTS: Readonly<Record<SqlDialectName, DialectDefaults>>;
+/**
+ * A DDL default that is SQL rather than a literal. A class, not a plain object, so a JSON default
+ * cannot masquerade as one: `defaultValue` accepts `unknown`.
  */
 export declare class SqlExpression {
-    readonly sql: string;
-    constructor(sql: string);
-    toString(): string;
-    /**
-     * Check if a value is a SQL expression.
-     */
+    readonly kind: SqlExpressionKind;
+    readonly sql?: string | undefined;
+    /** `sql` is set only for the `raw` kind, which carries its own text verbatim. */
+    constructor(kind: SqlExpressionKind, sql?: string | undefined);
     static isExpression(value: unknown): value is SqlExpression;
 }
 /**
- * Helper object for common SQL expressions.
- * Use in migrations: `table.timestamp('createdAt').defaultValue(t.now())`
+ * Symbolic DDL defaults. Each builds a token the dialect spells at DDL time, so `expr.uuid()` is
+ * `gen_random_uuid()` on Postgres and `UUID()` on MySQL from one migration.
+ *
+ * Use in migrations: `t.timestamp('createdAt', { defaultValue: expr.now() })`
  */
-export declare const t: {
-    /**
-     * Current timestamp (NOW() or CURRENT_TIMESTAMP depending on dialect).
-     */
-    now(): SqlExpression;
-    /**
-     * Current date (CURRENT_DATE).
-     */
-    currentDate(): SqlExpression;
-    /**
-     * Current time (CURRENT_TIME).
-     */
-    currentTime(): SqlExpression;
-    /**
-     * NULL value.
-     */
-    null(): SqlExpression;
-    /**
-     * Boolean true.
-     */
-    true(): SqlExpression;
-    /**
-     * Boolean false.
-     */
-    false(): SqlExpression;
-    /**
-     * Generate UUID (Postgres: gen_random_uuid(), MySQL: UUID()).
-     */
-    uuid(): SqlExpression;
-    /**
-     * Auto-generate UUID for MySQL.
-     */
-    mysqlUuid(): SqlExpression;
-    /**
-     * Raw SQL expression.
-     * Use for custom expressions not covered by helpers.
-     */
-    raw(sql: string): SqlExpression;
-    /**
-     * String literal with proper escaping.
-     */
-    literal(value: string): SqlExpression;
-    /**
-     * Numeric literal.
-     */
-    number(value: number): SqlExpression;
-    /**
-     * Empty JSON object.
-     */
-    emptyObject(): SqlExpression;
-    /**
-     * Empty JSON array.
-     */
-    emptyArray(): SqlExpression;
+export declare const expr: {
+    /** Current timestamp. */
+    now: () => SqlExpression;
+    /** Current date. */
+    currentDate: () => SqlExpression;
+    /** Current time. */
+    currentTime: () => SqlExpression;
+    /** Generated UUID. SQLite has no built-in one and throws; pass `expr.raw` there. */
+    uuid: () => SqlExpression;
     /**
-     * MySQL: ON UPDATE CURRENT_TIMESTAMP.
+     * Time-ordered UUID, which indexes far better than a random one as a key. Postgres 18+ and
+     * MariaDB 11.7+ only; MySQL, SQLite and CockroachDB have no such function and throw.
      */
-    onUpdateNow(): SqlExpression;
+    uuidv7: () => SqlExpression;
+    /** MySQL's `ON UPDATE CURRENT_TIMESTAMP`. Throws on dialects without it. */
+    onUpdateNow: () => SqlExpression;
+    /** SQL taken verbatim, for anything the kinds above do not cover. Not portable by definition. */
+    raw: (sql: string) => SqlExpression;
 };
 /**
- * Format a default value for SQL.
- * Handles SqlExpression vs literal values.
+ * The one place a DDL default becomes SQL: an expression through the dialect's own spelling, anything
+ * else as a literal, so `true` is `1` where booleans are integers. `columnType` decides only whether
+ * the result needs wrapping, which MySQL demands on its large types whatever the value.
  */
-export declare function formatDefaultValue(value: unknown): string;
+export declare function formatDefaultValue(value: unknown, dialect: AbstractSqlDialect, columnType?: string): string;

package/dist/migrate/builder/expressions.js

@@ -1,149 +1,120 @@
+const ANSI = {
+    now: 'CURRENT_TIMESTAMP',
+    currentDate: 'CURRENT_DATE',
+    currentTime: 'CURRENT_TIME',
+    uuid: null,
+    uuidv7: null,
+    onUpdateNow: null,
+};
+const PG = { ...ANSI, uuid: 'gen_random_uuid()' };
+const MYSQL = {
+    ...ANSI,
+    uuid: 'UUID()',
+    onUpdateNow: 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP',
+};
+/** 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;
 /**
- * SQL Expressions
- *
- * Type-safe SQL expressions for default values and other uses.
- * Provides a `t` helper with common expressions.
+ * 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
+ * Postgres 18+ and `UUID_v7()` MariaDB 11.7+; a server below those rejects it itself, the version
+ * not being knowable here.
  */
+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 },
+    sqlite: { expressions: ANSI },
+};
 /**
- * Represents a raw SQL expression (not a literal value).
+ * A DDL default that is SQL rather than a literal. A class, not a plain object, so a JSON default
+ * cannot masquerade as one: `defaultValue` accepts `unknown`.
  */
 export class SqlExpression {
+    kind;
     sql;
-    constructor(sql) {
+    /** `sql` is set only for the `raw` kind, which carries its own text verbatim. */
+    constructor(kind, sql) {
+        this.kind = kind;
         this.sql = sql;
     }
-    toString() {
-        return this.sql;
-    }
-    /**
-     * Check if a value is a SQL expression.
-     */
     static isExpression(value) {
         return value instanceof SqlExpression;
     }
 }
 /**
- * Helper object for common SQL expressions.
- * Use in migrations: `table.timestamp('createdAt').defaultValue(t.now())`
+ * Symbolic DDL defaults. Each builds a token the dialect spells at DDL time, so `expr.uuid()` is
+ * `gen_random_uuid()` on Postgres and `UUID()` on MySQL from one migration.
+ *
+ * Use in migrations: `t.timestamp('createdAt', { defaultValue: expr.now() })`
  */
-export const t = {
-    /**
-     * Current timestamp (NOW() or CURRENT_TIMESTAMP depending on dialect).
-     */
-    now() {
-        return new SqlExpression('CURRENT_TIMESTAMP');
-    },
-    /**
-     * Current date (CURRENT_DATE).
-     */
-    currentDate() {
-        return new SqlExpression('CURRENT_DATE');
-    },
-    /**
-     * Current time (CURRENT_TIME).
-     */
-    currentTime() {
-        return new SqlExpression('CURRENT_TIME');
-    },
-    /**
-     * NULL value.
-     */
-    null() {
-        return new SqlExpression('NULL');
-    },
-    /**
-     * Boolean true.
-     */
-    true() {
-        return new SqlExpression('TRUE');
-    },
-    /**
-     * Boolean false.
-     */
-    false() {
-        return new SqlExpression('FALSE');
-    },
-    /**
-     * Generate UUID (Postgres: gen_random_uuid(), MySQL: UUID()).
-     */
-    uuid() {
-        return new SqlExpression('gen_random_uuid()');
-    },
+export const expr = {
+    /** Current timestamp. */
+    now: () => new SqlExpression('now'),
+    /** Current date. */
+    currentDate: () => new SqlExpression('currentDate'),
+    /** Current time. */
+    currentTime: () => new SqlExpression('currentTime'),
+    /** Generated UUID. SQLite has no built-in one and throws; pass `expr.raw` there. */
+    uuid: () => new SqlExpression('uuid'),
     /**
-     * Auto-generate UUID for MySQL.
+     * Time-ordered UUID, which indexes far better than a random one as a key. Postgres 18+ and
+     * MariaDB 11.7+ only; MySQL, SQLite and CockroachDB have no such function and throw.
      */
-    mysqlUuid() {
-        return new SqlExpression('UUID()');
-    },
-    /**
-     * Raw SQL expression.
-     * Use for custom expressions not covered by helpers.
-     */
-    raw(sql) {
-        return new SqlExpression(sql);
-    },
-    /**
-     * String literal with proper escaping.
-     */
-    literal(value) {
-        // Escape single quotes by doubling them
-        const escaped = value.replace(/'/g, "''");
-        return new SqlExpression(`'${escaped}'`);
-    },
-    /**
-     * Numeric literal.
-     */
-    number(value) {
-        return new SqlExpression(String(value));
-    },
-    /**
-     * Empty JSON object.
-     */
-    emptyObject() {
-        return new SqlExpression("'{}'::jsonb");
-    },
-    /**
-     * Empty JSON array.
-     */
-    emptyArray() {
-        return new SqlExpression("'[]'::jsonb");
-    },
-    /**
-     * MySQL: ON UPDATE CURRENT_TIMESTAMP.
-     */
-    onUpdateNow() {
-        return new SqlExpression('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP');
-    },
+    uuidv7: () => new SqlExpression('uuidv7'),
+    /** MySQL's `ON UPDATE CURRENT_TIMESTAMP`. Throws on dialects without it. */
+    onUpdateNow: () => new SqlExpression('onUpdateNow'),
+    /** SQL taken verbatim, for anything the kinds above do not cover. Not portable by definition. */
+    raw: (sql) => new SqlExpression('raw', sql),
 };
 /**
- * Format a default value for SQL.
- * Handles SqlExpression vs literal values.
+ * The one place a DDL default becomes SQL: an expression through the dialect's own spelling, anything
+ * else as a literal, so `true` is `1` where booleans are integers. `columnType` decides only whether
+ * 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 { wrapTypes } = DIALECT_DEFAULTS[dialect.dialectName];
+    return columnType !== undefined && wrapTypes?.test(columnType) ? `(${sql})` : sql;
+}
+/**
+ * Quoting is the dialect's `escape`, so a backslash in a default is escaped the way the engine reads
+ * it - MySQL takes `'a\b'` as a backspace where Postgres takes it literally. Only the cases `escape`
+ * 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.
  */
-export function formatDefaultValue(value) {
+function defaultLiteral(value, dialect) {
     if (value === undefined || value === null) {
         return 'NULL';
     }
     if (SqlExpression.isExpression(value)) {
-        return value.sql;
-    }
-    if (typeof value === 'string') {
-        // Escape single quotes for string literals
-        const escaped = value.replace(/'/g, "''");
-        return `'${escaped}'`;
-    }
-    if (typeof value === 'number') {
-        return String(value);
+        return expressionSql(value, dialect);
     }
     if (typeof value === 'boolean') {
-        return value ? 'TRUE' : 'FALSE';
+        return dialect.booleanLiteral === 'native' ? (value ? 'TRUE' : 'FALSE') : value ? '1' : '0';
     }
     if (value instanceof Date) {
-        return `'${value.toISOString()}'`;
+        return dialect.escape(ddlTimestamp(value));
     }
     if (typeof value === 'object') {
-        // JSON value
-        const json = JSON.stringify(value).replace(/'/g, "''");
-        return `'${json}'`;
+        return dialect.escape(JSON.stringify(value));
+    }
+    return dialect.escape(value);
+}
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC. Not `toISOString`, whose `T` and `Z` MySQL rejects outright
+ * ("Invalid default value"), and not `escape`'s local-time form, which would make the DDL depend on
+ * the machine that generated it.
+ */
+function ddlTimestamp(date) {
+    return date.toISOString().replace('T', ' ').replace('Z', '');
+}
+function expressionSql(expression, dialect) {
+    const { expressions } = DIALECT_DEFAULTS[dialect.dialectName];
+    const sql = expression.kind === '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`);
     }
-    return String(value);
+    return sql;
 }

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

@@ -40,6 +40,7 @@ export declare class TableBuilder implements ITableBuilder {
     private add;
     createdAt(): IColumnBuilder;
     updatedAt(): IColumnBuilder;
+    private timestampNow;
     timestamps(): void;
     primaryKey(columns: string[]): this;
     unique(columns: readonly IndexColumnInput[], options?: string | IndexOptions): this;

package/dist/migrate/builder/tableBuilder.js

@@ -6,7 +6,7 @@
 import { normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
 import { ColumnBuilder } from './columnBuilder.js';
-import { t } from './expressions.js';
+import { expr } from './expressions.js';
 /**
  * Builder for table-level foreign keys.
  */
@@ -137,10 +137,13 @@ export class TableBuilder {
         return column;
     }
     createdAt() {
-        return this.add('createdAt', { category: 'timestamp' }, { defaultValue: t.now() });
+        return this.timestampNow('createdAt');
     }
     updatedAt() {
-        return this.add('updatedAt', { category: 'timestamp' }, { defaultValue: t.now() });
+        return this.timestampNow('updatedAt');
+    }
+    timestampNow(name) {
+        return this.add(name, { category: 'timestamp' }, { defaultValue: expr.now() });
     }
     timestamps() {
         this.createdAt();

package/dist/migrate/migrator.d.ts

@@ -198,10 +198,10 @@ export interface BuilderMigrationDefinition {
  * ```ts
  * export default defineBuilderMigration({
  *   async up(m) {
- *     await m.createTable('users', (table) => {
- *       table.id();
- *       table.string('email', 255).unique();
- *       table.timestamps();
+ *     await m.createTable('users', (t) => {
+ *       t.id();
+ *       t.string('email', { length: 255 }).unique();
+ *       t.timestamps();
  *     });
  *   },
  *   async down(m) {

package/dist/migrate/migrator.js

@@ -571,10 +571,10 @@ export function defineMigration(migration) {
  * ```ts
  * export default defineBuilderMigration({
  *   async up(m) {
- *     await m.createTable('users', (table) => {
- *       table.id();
- *       table.string('email', 255).unique();
- *       table.timestamps();
+ *     await m.createTable('users', (t) => {
+ *       t.id();
+ *       t.string('email', { length: 255 }).unique();
+ *       t.timestamps();
  *     });
  *   },
  *   async down(m) {

package/dist/migrate/schemaGenerator.d.ts

@@ -76,6 +76,9 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * rules are the same everywhere, and having them written twice is how the two paths drifted.
      */
     private renderColumn;
+    /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
+     * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
+    private defaultClause;
     getSqlType(field: FieldOptions, fieldType?: unknown): string;
     /**
      * Generate ALTER COLUMN statements (database-specific)
@@ -85,10 +88,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * Generate column comment clause (if supported)
      */
     generateColumnComment(columnName: string, comment: string): string;
-    /**
-     * Format a default value for SQL
-     */
-    formatDefaultValue(value: unknown): string;
     /**
      * Compare an entity with a database table node and return the differences.
      */

package/dist/migrate/schemaGenerator.js

@@ -4,7 +4,7 @@ import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategor
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedForeignKeyName } from '../util/sql.util.js';
-import { formatDefaultValue } from './builder/expressions.js';
+import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
@@ -243,14 +243,19 @@ export class SqlSchemaGenerator {
         if (column.isUnique && !column.isPrimaryKey) {
             def += ' UNIQUE';
         }
-        if (column.defaultValue !== undefined) {
-            def += ` DEFAULT ${this.formatDefaultValue(column.defaultValue)}`;
-        }
+        def += this.defaultClause(column);
         if (column.comment) {
             def += this.generateColumnComment(column.name, column.comment);
         }
         return def;
     }
+    /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
+     * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
+    defaultClause(column) {
+        return column.defaultValue === undefined
+            ? ''
+            : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
+    }
     getSqlType(field, fieldType) {
         // If field has a reference, inherit type from the target primary key
         if (field.references) {
@@ -288,7 +293,7 @@ export class SqlSchemaGenerator {
                 statements.push(`ALTER TABLE ${table} ALTER COLUMN ${colName} SET NOT NULL;`);
             }
             if (column.defaultValue !== undefined) {
-                statements.push(`ALTER TABLE ${table} ALTER COLUMN ${colName} SET DEFAULT ${this.formatDefaultValue(column.defaultValue)};`);
+                statements.push(`ALTER TABLE ${table} ALTER COLUMN ${colName} SET${this.defaultClause(column)};`);
             }
             else {
                 statements.push(`ALTER TABLE ${table} ALTER COLUMN ${colName} DROP DEFAULT;`);
@@ -307,15 +312,6 @@ export class SqlSchemaGenerator {
         }
         return '';
     }
-    /**
-     * Format a default value for SQL
-     */
-    formatDefaultValue(value) {
-        if (this.dialect.booleanLiteral === 'integer' && typeof value === 'boolean') {
-            return value ? '1' : '0';
-        }
-        return formatDefaultValue(value);
-    }
     /**
      * Compare an entity with a database table node and return the differences.
      */
@@ -467,9 +463,12 @@ export class SqlSchemaGenerator {
             return true;
         if (current === undefined || desired === undefined)
             return current === desired;
-        const normalize = (val) => {
-            if (val === null)
+        const normalize = (value) => {
+            if (value === null)
                 return 'null';
+            // Render first: the desired side may be a symbolic expression, the current side is always the
+            // engine's own text, and `{"kind":"now"}` matches no spelling of `CURRENT_TIMESTAMP`.
+            const val = SqlExpression.isExpression(value) ? formatDefaultValue(value, this.dialect) : value;
             if (typeof val === 'string') {
                 let s = val.replace(/::[a-z_]+(\s+[a-z_]+)*(\[\])?$/i, '');
                 s = s.replace(/^'(.*)'$/, '$1');

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
+  "description": "JSON-native ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "type": "module",
   "engines": {
     "node": ">=24"