uql-orm 0.42.0 → 0.43.0

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.js

@@ -69,7 +69,15 @@ export function getFieldKeys(fields) {
  * is what a `$where` map and a composite key's id object both are; an array is a list of either.
  */
 export function isScalarId(value) {
-    return (typeof value !== 'object' ||
-        value === null ||
-        (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype));
+    if (typeof value !== 'object' || value === null) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    // `null` as well as `Object.prototype`: an object with no prototype is what a query-string parser
+    // hands back (`qs`, express's `req.params`), and reading one as a bare id would name one column
+    // with a map of several.
+    const proto = Object.getPrototypeOf(value);
+    return proto !== Object.prototype && proto !== null;
 }

package/dist/util/relationQuery.util.d.ts

@@ -32,6 +32,16 @@ export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | '
  * which is the mistake this module exists to prevent.
  */
 export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
+/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
+export declare function joinedColumns(joins: readonly ParentJoin[]): Record<string, true>;
+/**
+ * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
+ * columns it carries that key in. The two halves of matching children to parents: they must agree on
+ * every column, so each is read through `joins` rather than through the parent's own key list - which
+ * is the same set only for a to-many, and silently a different one otherwise.
+ */
+export declare function parentRowKey(joins: readonly ParentJoin[], parent: unknown): string;
+export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown): string;
 /**
  * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
  * children in one statement.

package/dist/util/relationQuery.util.js

@@ -1,5 +1,6 @@
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, } from '../type/query.js';
 import { getKeys, someKey } from './object.util.js';
+import { rowKey } from './rowKey.util.js';
 /**
  * Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. Takes
  * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
@@ -34,6 +35,22 @@ export function parentJoins(relOpts, parentKeyCount) {
 export function targetKeyColumns(relOpts, parentKeyCount) {
     return relOpts.references.slice(parentKeyCount).map(({ local }) => local);
 }
+/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
+export function joinedColumns(joins) {
+    return Object.fromEntries(joins.map(({ joined }) => [joined, true]));
+}
+/**
+ * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
+ * columns it carries that key in. The two halves of matching children to parents: they must agree on
+ * every column, so each is read through `joins` rather than through the parent's own key list - which
+ * is the same set only for a to-many, and silently a different one otherwise.
+ */
+export function parentRowKey(joins, parent) {
+    return rowKey(joins.map(({ parent: key }) => read(parent, key)));
+}
+export function joinedRowKey(joins, row) {
+    return rowKey(joins.map(({ joined }) => read(row, joined)));
+}
 /**
  * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
  * children in one statement.
@@ -43,7 +60,7 @@ export function targetKeyColumns(relOpts, parentKeyCount) {
  * cheaper than the row-value comparison no engine spells the same way.
  */
 export function parentsIn(joins, parents) {
-    return Object.fromEntries(joins.map(({ parent, joined }) => [joined, parents.map((it) => it[parent])]));
+    return Object.fromEntries(joins.map(({ parent, joined }) => [joined, parents.map((it) => read(it, parent))]));
 }
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
@@ -58,9 +75,12 @@ export function childrenOf(joins, parentIds) {
         return { [first.joined]: parentIds };
     }
     return {
-        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, id[parent]]))),
+        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
     };
 }
+function read(row, key) {
+    return row[key];
+}
 /**
  * What a joined relation cannot carry, and why. A to-many is loaded by a query of its own, which is
  * what gives these four a meaning there; a to-one is one row of the parent's, so every backend used

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

@@ -13,20 +13,41 @@ export declare function obtainAttrsPaths<T extends object>(row: T): {
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
  * seed for a derived identifier - an index or constraint name is a single identifier, and
- * `idx_sales.Order_total` is a syntax error.
+ * `sales.Order_total_idx` is a syntax error.
  */
 export declare function qualifyName(name: string, schema?: string): string;
 /**
- * The name a derived index or constraint gets when nothing named it: `idx_Order_total`.
+ * The name a derived index or constraint gets when nothing named it: `Order__total_idx`.
  *
- * One owner, because it is a rule two layers apply and a third has to match: the entity AST derives
- * it, the DDL generator falls back to it, and a diff compares what the database reports against it.
+ * One owner for all four kinds, because it is a rule two layers apply and a third has to match: the
+ * entity AST derives it, the DDL generator falls back to it, and a `DROP` names what it drops.
  * `table` is the table's own name, never qualified - the result is a single identifier.
+ *
+ * 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. */
+export type ConstraintKind = 'pk' | 'fk' | 'idx' | 'ck' | 'uk';
+/**
+ * The name a derived index gets when nothing named it: `Order__total_idx`, or `Order__total_uk` for a
+ * unique one - which the builder has always spelled apart, and which reads as what it enforces.
+ */
+export declare function derivedIndexName(table: string, columns: readonly string[], unique?: boolean): string;
+/**
+ * The constraint name a primary key gets when we name one: `Enrolment__studentId_courseId_pk`.
+ *
+ * Only ever used to *emit* a key. Which columns a key holds is what decides whether two keys are the
+ * same, so an existing constraint keeps whatever the engine called it - see `SchemaDiff.primaryKey`.
  */
-export declare function derivedIndexName(table: string, columns: readonly string[]): string;
-/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+export declare function derivedPrimaryKeyName(table: string, columns: readonly string[]): string;
+/** The constraint name a check gets when nothing named it: `Order__1_ck`, by declaration order. */
 export declare function derivedCheckName(table: string, position: number): string;
-/** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
+/** The constraint name a foreign key gets when nothing named it: `Order__customerId_fk`. */
 export declare function derivedForeignKeyName(table: string, columns: readonly string[]): string;
 /**
  * Escape a SQL identifier (table name, column name, etc.)

package/dist/util/sql.util.js

@@ -52,28 +52,97 @@ export function obtainAttrsPaths(row) {
  * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
  * table's key, its statement operand and its escaped form cannot spell it differently. Never the
  * seed for a derived identifier - an index or constraint name is a single identifier, and
- * `idx_sales.Order_total` is a syntax error.
+ * `sales.Order_total_idx` is a syntax error.
  */
 export function qualifyName(name, schema) {
     return schema ? `${schema}.${name}` : name;
 }
 /**
- * The name a derived index or constraint gets when nothing named it: `idx_Order_total`.
+ * The longest identifier every engine here accepts. Postgres truncates silently at 63 bytes and
+ * MySQL errors at 64, so one conservative limit needs no per-dialect plumbing to be safe on both -
+ * and SQLite, which has no limit, loses nothing by observing it.
+ */
+const MAX_IDENTIFIER_LENGTH = 63;
+/** Hex chars of hash kept when a name has to be shortened. 24 bits over one table's constraints. */
+const NAME_HASH_LENGTH = 6;
+/**
+ * The name a derived index or constraint gets when nothing named it: `Order__total_idx`.
  *
- * One owner, because it is a rule two layers apply and a third has to match: the entity AST derives
- * it, the DDL generator falls back to it, and a diff compares what the database reports against it.
+ * One owner for all four kinds, because it is a rule two layers apply and a third has to match: the
+ * entity AST derives it, the DDL generator falls back to it, and a `DROP` names what it drops.
  * `table` is the table's own name, never qualified - the result is a single identifier.
+ *
+ * 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;
+    return clampIdentifier(`${body}_${kind}`);
+}
+/**
+ * What separates the table from the columns, doubled where every other join is single.
+ *
+ * Postgres and SQLite keep index and constraint names in one flat namespace across the whole
+ * database rather than scoping them to a table, so a single underscore lets two tables collide:
+ * `user` + `profile_id` and `user_profile` + `id` both reduce to `user_profile_id_idx`. Doubling the
+ * one ambiguous boundary settles it, on the same assumption Drupal made for the same engines - that
+ * nothing sane carries `__` in a table or column name.
+ */
+const TABLE_SEPARATOR = '__';
+/**
+ * A name the engine will store whole, shortened around a hash of the full one when it is too long.
+ *
+ * Truncating alone collides - two long names over the same table differ only in their tail - and a
+ * collision means one constraint silently replacing another. The hash is of the *whole* name, so it
+ * stays the same on every run, which is what lets a later migration still recognise what it made.
+ */
+function clampIdentifier(name) {
+    if (name.length <= MAX_IDENTIFIER_LENGTH) {
+        return name;
+    }
+    const suffix = `_${hashIdentifier(name)}`;
+    return name.slice(0, MAX_IDENTIFIER_LENGTH - suffix.length) + suffix;
+}
+/**
+ * FNV-1a, by hand: the package ships zero runtime dependencies, and `node:crypto` is not reachable
+ * from the browser and edge entries this module is bundled into. Not a security hash - it only has
+ * to spread the names of one table's constraints.
+ */
+function hashIdentifier(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(NAME_HASH_LENGTH, '0').slice(-NAME_HASH_LENGTH);
+}
+/**
+ * The name a derived index gets when nothing named it: `Order__total_idx`, or `Order__total_uk` for a
+ * unique one - which the builder has always spelled apart, and which reads as what it enforces.
+ */
+export function derivedIndexName(table, columns, unique = false) {
+    return derivedConstraintName(table, columns, unique ? 'uk' : 'idx');
+}
+/**
+ * The constraint name a primary key gets when we name one: `Enrolment__studentId_courseId_pk`.
+ *
+ * Only ever used to *emit* a key. Which columns a key holds is what decides whether two keys are the
+ * same, so an existing constraint keeps whatever the engine called it - see `SchemaDiff.primaryKey`.
  */
-export function derivedIndexName(table, columns) {
-    return `idx_${table}_${columns.join('_')}`;
+export function derivedPrimaryKeyName(table, columns) {
+    return derivedConstraintName(table, columns, 'pk');
 }
-/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+/** The constraint name a check gets when nothing named it: `Order__1_ck`, by declaration order. */
 export function derivedCheckName(table, position) {
-    return `ck_${table}_${position}`;
+    return derivedConstraintName(table, [position], 'ck');
 }
-/** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
+/** The constraint name a foreign key gets when nothing named it: `Order__customerId_fk`. */
 export function derivedForeignKeyName(table, columns) {
-    return `fk_${table}_${columns.join('_')}`;
+    return derivedConstraintName(table, columns, 'fk');
 }
 /**
  * Escape a SQL identifier (table name, column name, etc.)

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.0",
+  "version": "0.43.0",
   "type": "module",
   "engines": {
     "node": ">=24"