uql-orm 0.42.1 → 0.44.0

package/dist/util/field.util.js

@@ -1,56 +1,53 @@
-const NUMERIC_COLUMN_TYPES = {
-    int: true,
-    integer: true,
-    tinyint: true,
-    smallint: true,
-    bigint: true,
-    float: true,
-    float4: true,
-    float8: true,
-    double: true,
-    'double precision': true,
-    decimal: true,
-    numeric: true,
-    real: true,
-    serial: true,
-    smallserial: true,
-    bigserial: true,
-};
-const JSON_COLUMN_TYPES = {
-    json: true,
-    jsonb: true,
-};
-/**
- * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
- */
-export function isNumericType(type) {
-    if (type === Number || type === BigInt)
-        return true;
-    if (typeof type === 'string') {
-        return type.toLowerCase() in NUMERIC_COLUMN_TYPES;
-    }
-    return false;
-}
+import { getKeys } from './object.util.js';
 /**
- * Checks if a field type is boolean (Boolean, or an explicit boolean logical type)
+ * The runtime half of the column-type unions in `type/entity.ts`, which TypeScript erases. Each list
+ * is checked against its own union, so a type cannot be filed under the wrong family, and
+ * {@link UnplacedColumnType} refuses to compile if a new one is filed under none. Nothing here
+ * restates the unions: the compile-time side of the same question reads them directly.
  */
-export function isBooleanType(type) {
-    if (type === Boolean)
-        return true;
-    if (typeof type === 'string') {
-        const lowered = type.toLowerCase();
-        return lowered === 'bool' || lowered === 'boolean';
+export const COLUMN_TYPES_BY_FAMILY = {
+    numeric: [
+        'int',
+        'integer',
+        'tinyint',
+        'smallint',
+        'bigint',
+        'float',
+        'float4',
+        'float8',
+        'double',
+        'double precision',
+        'decimal',
+        'numeric',
+        'real',
+        'serial',
+        'smallserial',
+        'bigserial',
+    ],
+    string: ['char', 'varchar', 'text', 'uuid'],
+    date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
+    json: ['json', 'jsonb'],
+    blob: ['blob', 'bytea'],
+    boolean: ['bool', 'boolean'],
+    vector: ['vector', 'halfvec', 'sparsevec'],
+};
+// Constructors and type strings in one map: a logical type is either, and every caller asks the same
+// question of both.
+const FAMILY_OF = new Map([
+    [String, 'string'],
+    [Number, 'numeric'],
+    [BigInt, 'numeric'],
+    [Boolean, 'boolean'],
+    [Date, 'date'],
+]);
+for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
+    for (const columnType of COLUMN_TYPES_BY_FAMILY[family]) {
+        FAMILY_OF.set(columnType, family);
     }
-    return false;
 }
-/**
- * Checks if a field type is JSON
- */
-export function isJsonType(type) {
-    if (typeof type === 'string') {
-        return type.toLowerCase() in JSON_COLUMN_TYPES;
-    }
-    return false;
+/** The family of a logical field type, or `undefined` where it names none. */
+export function columnFamily(type) {
+    return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
 /**
  * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
@@ -75,6 +72,5 @@ export function isAutoIncrement(field, isPrimaryKey) {
     const colType = field.columnType?.toLowerCase();
     if (colType === 'serial' || colType === 'smallserial' || colType === 'bigserial')
         return true;
-    const isNumeric = isNumericType(field.type);
-    return isPrimaryKey && isNumeric && !field.onInsert && !field.columnType;
+    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.columnType;
 }

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

@@ -0,0 +1,79 @@
+import type { BlobColumnType, BooleanColumnType, DateColumnType, FieldOptions, JsonColumnType, NumericColumnType, QueryRaw, StringColumnType, VectorColumnType } from '../type/index.js';
+import { type ColumnFamily } from './field.util.js';
+/**
+ * The column family 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.
+ */
+declare const FIELD_OPTION_FAMILY: {
+    readonly name: '*';
+    readonly isId: '*';
+    readonly type: '*';
+    readonly dimensions: 'vector';
+    readonly distance: 'vector';
+    readonly references: '*';
+    readonly onDelete: '*';
+    readonly enum: '*';
+    readonly virtual: '*';
+    readonly updatable: '*';
+    readonly eager: '*';
+    readonly onInsert: '*';
+    readonly onUpdate: '*';
+    readonly softDelete: '*';
+    readonly columnType: '*';
+    readonly length: 'string';
+    readonly precision: 'numeric';
+    readonly scale: 'numeric';
+    readonly nullable: '*';
+    readonly unique: '*';
+    readonly defaultValue: '*';
+    readonly autoIncrement: 'numeric';
+    readonly index: '*';
+    readonly comment: '*';
+};
+/**
+ * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * update, so the whole persistence half of the options above is dead on one. Stated as what survives
+ * rather than on each option that dies, because it is one fact rather than nineteen - and because an
+ * option added without a thought then lands on the safe side of it.
+ */
+declare const VIRTUAL_READS: readonly ["type", "virtual", "enum", "eager", "distance"];
+type VirtualRead = (typeof VIRTUAL_READS)[number];
+/**
+ * The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
+ * where every option applies. The runtime half of the decorators' check, so the imperative API and
+ * plain JavaScript reach the same answer.
+ */
+export declare function fieldOptionConflict(opts: FieldOptions): string | undefined;
+/** The family the options put the column in; every family where they name no type to put it in. */
+type FamilyOf<O> = O extends {
+    readonly columnType: infer C;
+} ? FamilyOfType<C> : O extends {
+    readonly type: infer T;
+} ? FamilyOfType<T> : ColumnFamily;
+/** Read off the column-type unions themselves, which is what `COLUMN_TYPES_BY_FAMILY` is checked against. */
+type FamilyOfType<T> = T extends NumericColumnType | NumberConstructor | BigIntConstructor ? 'numeric' : T extends StringColumnType | StringConstructor ? 'string' : T extends VectorColumnType ? 'vector' : T extends JsonColumnType ? 'json' : T extends DateColumnType | DateConstructor ? 'date' : T extends BooleanColumnType | BooleanConstructor ? 'boolean' : T extends BlobColumnType ? 'blob' : ColumnFamily;
+/** What the field's own values leave unread, matching {@link deadOn} line for line. */
+type DeadOptions<O> = (O extends {
+    readonly virtual: QueryRaw;
+} ? Exclude<keyof FieldOptions, VirtualRead> : never) | (O extends {
+    readonly isId: true;
+    readonly nullable: true;
+} ? 'nullable' : never) | (O extends {
+    readonly updatable: false;
+} ? 'onUpdate' : never);
+type Given<O> = Extract<keyof O, keyof FieldOptions>;
+type Offending<O> = {
+    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends FamilyOf<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
+}[Given<O>];
+/**
+ * Maps every option `O` states but cannot use to `never`, the way `RejectUnknown` maps a typo'd one,
+ * so an option that would be silently ignored reads as the same compile error. Resolves to `unknown`
+ * - an inert intersection member - when there are none.
+ *
+ * `@Id` adds `{ nullable?: false }` of its own rather than passing the `isId` it stamps on, which
+ * would have to reach `O` as an intersection - and a non-naked `O` in its own constraint stops it
+ * inferring from the options at all.
+ */
+export type RejectIncompatible<O> = [Offending<O>] extends [never] ? unknown : Record<Offending<O> & string, never>;
+export {};

package/dist/util/fieldOption.util.js

@@ -0,0 +1,84 @@
+import { columnFamily } from './field.util.js';
+import { getKeys } from './object.util.js';
+/**
+ * The column family 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.
+ */
+const FIELD_OPTION_FAMILY = {
+    name: '*',
+    isId: '*',
+    type: '*',
+    dimensions: 'vector',
+    distance: 'vector',
+    references: '*',
+    onDelete: '*',
+    enum: '*',
+    virtual: '*',
+    updatable: '*',
+    eager: '*',
+    onInsert: '*',
+    onUpdate: '*',
+    softDelete: '*',
+    columnType: '*',
+    length: 'string',
+    precision: 'numeric',
+    scale: 'numeric',
+    nullable: '*',
+    unique: '*',
+    defaultValue: '*',
+    autoIncrement: 'numeric',
+    index: '*',
+    comment: '*',
+};
+/**
+ * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * update, so the whole persistence half of the options above is dead on one. Stated as what survives
+ * rather than on each option that dies, because it is one fact rather than nineteen - and because an
+ * option added without a thought then lands on the safe side of it.
+ */
+const VIRTUAL_READS = [
+    'type',
+    'virtual',
+    'enum',
+    'eager',
+    'distance',
+];
+/**
+ * Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. Only
+ * `nullable: true` contradicts a key: `nullable: false` says what the key already is, and rejecting
+ * an accurate statement teaches an author to distrust the check.
+ */
+function deadOn(opts, key) {
+    if (opts.virtual !== undefined && !VIRTUAL_READS.some((read) => read === key))
+        return 'a virtual field';
+    if (opts.isId === true && key === 'nullable' && opts.nullable === true)
+        return 'a primary key';
+    if (opts.updatable === false && key === 'onUpdate')
+        return "a field declared 'updatable: false'";
+    return undefined;
+}
+/**
+ * The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
+ * where every option applies. The runtime half of the decorators' check, so the imperative API and
+ * plain JavaScript reach the same answer.
+ */
+export function fieldOptionConflict(opts) {
+    const family = columnFamily(opts.columnType ?? opts.type);
+    // Walked in table order, not in the order the field happened to be written, so a field with two
+    // conflicts always reports the same one. An option no rule knows is a typo, which `RejectUnknown`
+    // reports where it can still be spelled right.
+    for (const key of getKeys(FIELD_OPTION_FAMILY)) {
+        const applies = FIELD_OPTION_FAMILY[key];
+        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`;
+        }
+        const dead = deadOn(opts, key);
+        if (dead) {
+            return `cannot use '${key}': it is ignored on ${dead}`;
+        }
+    }
+    return undefined;
+}

package/dist/util/index.d.ts

@@ -1,5 +1,6 @@
 export * from './dialect.util.js';
 export * from './field.util.js';
+export * from './fieldOption.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
 export * from './ddlExpression.util.js';

package/dist/util/index.js

@@ -1,5 +1,6 @@
 export * from './dialect.util.js';
 export * from './field.util.js';
+export * from './fieldOption.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
 export * from './ddlExpression.util.js';

package/dist/util/object.util.d.ts

@@ -21,9 +21,9 @@ export declare function isOperatorObject(value: unknown): value is Record<string
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
 export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
 /**
- * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
- * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
- * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
+ * the fallback is what an entity that named no table is called - which is why the sites spelling this
+ * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export declare function entityName<E>(meta: EntityMeta<E>): string;
 export declare function getFieldKeys<E>(fields: {

package/dist/util/object.util.js

@@ -53,9 +53,9 @@ export function getKeys(obj) {
     return obj ? Object.keys(obj) : [];
 }
 /**
- * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
- * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
- * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
+ * the fallback is what an entity that named no table is called - which is why the sites spelling this
+ * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export function entityName(meta) {
     return meta.name ?? meta.entity.name;

package/dist/util/sql.util.d.ts

@@ -25,6 +25,10 @@ export declare function qualifyName(name: string, schema?: string): string;
  *
  * The kind goes last, as Postgres spells its own (`users_pkey`, `users_email_idx`), so a table's
  * constraints sort together under the table they belong to.
+ *
+ * Not overridable, deliberately: a `NamingStrategy` hook would have to reach the eight call sites
+ * these have, an introspector and two builders among them, to replace a name any declaration can
+ * already set outright with `name:`. Worth revisiting only for a case that option cannot express.
  */
 export declare function derivedConstraintName(table: string, parts: readonly (string | number)[], kind: ConstraintKind): string;
 /** The kinds of derived name, which is also what `indexNameStem` strips to compare them. */

package/dist/util/sql.util.js

@@ -74,6 +74,10 @@ const NAME_HASH_LENGTH = 6;
  *
  * The kind goes last, as Postgres spells its own (`users_pkey`, `users_email_idx`), so a table's
  * constraints sort together under the table they belong to.
+ *
+ * Not overridable, deliberately: a `NamingStrategy` hook would have to reach the eight call sites
+ * these have, an introspector and two builders among them, to replace a name any declaration can
+ * already set outright with `name:`. Worth revisiting only for a case that option cannot express.
  */
 export function derivedConstraintName(table, parts, kind) {
     const body = parts.length ? `${table}${TABLE_SEPARATOR}${parts.join('_')}` : table;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "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.",
+  "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.",
   "license": "MIT",
-  "version": "0.42.1",
+  "version": "0.44.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -145,7 +145,7 @@
     "express": "^5.2.1",
     "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
-    "mysql2": "^3.24.3",
+    "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",