uql-orm 0.42.1 → 0.43.0

package/dist/type/entity.d.ts

@@ -49,6 +49,8 @@ export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
  * inferring junk like `T = string`), while the marker key only exists on branded types.
  */
 type IsJson<T> = '__json' extends keyof T ? true : false;
+/** Whether `T` is what a JSON column holds: the branded payload, or an array of them. */
+type IsJsonColumn<T> = IsJson<T> extends true ? true : IsJson<NonNullable<Unpacked<T>>>;
 /** The payload `P` of a branded `Json<P>`, or `never` for any non-JSON type. */
 type UnwrapJson<T> = IsJson<T> extends true ? (T extends Json<infer P> ? P : never) : never;
 /**
@@ -276,7 +278,7 @@ export type FieldType = StringConstructor | NumberConstructor | BooleanConstruct
  * Both `Json<T>` and `Json<T>[]` have to be recognised, and the array check has to precede the scalar
  * arms so a `number[]` vector is not read as a `number`.
  */
-export type TypeFor<V, T = NonNullable<V>> = IsJson<T> extends true ? JsonColumnType : IsJson<NonNullable<Unpacked<T>>> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
+export type TypeFor<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
 /**
  * A field as the registry holds it: what the user authored, plus what registration worked out.
  *
@@ -384,11 +386,9 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      */
     readonly unique?: boolean;
     /**
-     * The column's DDL default, rendered into `CREATE TABLE` by `formatDefaultValue` - not `V`, unlike
-     * the generators above. A JSONB column defaults with the SQL literal it stores, `defaultValue: '{}'`,
-     * which is a string whatever the field's TypeScript type is.
+     * The column's DDL default, rendered into `CREATE TABLE` by `formatDefaultValue`.
      */
-    readonly defaultValue?: Scalar | Record<string, unknown>;
+    readonly defaultValue?: DdlDefault<V>;
     /**
      * Whether the column is auto-incrementing (for integer IDs).
      */
@@ -403,6 +403,17 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
     readonly comment?: string;
 };
 export type OnFieldCallback<V = TsTypeOf<FieldType>> = V | QueryRaw | (() => V | QueryRaw);
+/**
+ * What a column may default to: the value it holds, except on a JSON column, which defaults with the
+ * SQL literal it stores (`defaultValue: '{}'`) whatever the property's TypeScript type is. Opening
+ * that exception to every field is what let `@Field({ type: Number, defaultValue: 'hello' })` compile.
+ *
+ * The erased shape - `FieldOptions` with no field in mind - admits every column's default at once, or
+ * no `FieldOptions<V>` would be assignable to the one the registry and the dialects read.
+ */
+type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonDdlDefault : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
+/** What a JSON column, and the field-less `FieldOptions`, may default to. */
+type JsonDdlDefault = Scalar | Record<string, unknown>;
 /**
  * The TypeScript types a field may be declared as, given the `type` it registers: the inverse of
  * {@link TypeFor}.
@@ -760,7 +771,13 @@ export type EntityMeta<E> = {
     checks?: CheckSchema[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
-    processed?: boolean;
+    /**
+     * Bumped by every `define*` call, so anything derived from this metadata can tell that it changed.
+     * A content type registered at runtime keeps adding to an entity that has already been read.
+     */
+    revision: number;
+    /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
+    processedAt?: number;
 };
 /**
  * Configurable options for an entity (`@Entity()` / `defineEntity`).

package/dist/type/migration.d.ts

@@ -262,7 +262,7 @@ export interface SchemaGenerator {
     /**
      * Get the SQL type for a field based on its options
      */
-    getSqlType(fieldOptions: FieldOptions, fieldType?: unknown): string;
+    getSqlType(fieldOptions: FieldOptions): string;
     /**
      * Compare an entity with a database table node and return the differences.
      */

package/dist/type/query.d.ts

@@ -394,12 +394,8 @@ type CountedRelations<C extends PropertyKey> = [C] extends [never] ? unknown : {
     };
 };
 /** @internal */
-type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? {
-    [K in keyof E as K extends ProjectedKeys<E, S, V, X, P, C> ? K : never]: E[K];
-} : // A populated to-many is always a list, empty where the parent has no children, so it maps
-{
-    [K in keyof E as K extends Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> ? K : never]: E[K];
-} & {
+type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? Pick<E, ProjectedKeys<E, S, V, X, P, C> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
+Pick<E, Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> & keyof E> & {
     [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;
 } : E;
 /** The to-many relations a query populated, which come back as lists rather than as optional ones. */

package/dist/util/field.util.d.ts

@@ -1,16 +1,27 @@
 import type { EntityMeta, FieldOptions } from '../type/index.js';
 /**
- * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
+ * The kind of column a field lands on, which is what decides whether an option means anything on it:
+ * `length` is a string's, `precision` a number's, `dimensions` a vector's. Named in the words an
+ * error reports it in, so there is no second table of labels to keep in step.
  */
-export declare function isNumericType(type: unknown): boolean;
+export type ColumnFamily = 'string' | 'numeric' | 'boolean' | 'date' | 'json' | 'blob' | 'vector';
 /**
- * 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 declare function isBooleanType(type: unknown): boolean;
-/**
- * Checks if a field type is JSON
- */
-export declare function isJsonType(type: unknown): boolean;
+export declare const COLUMN_TYPES_BY_FAMILY: {
+    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real", "serial", "smallserial", "bigserial"];
+    readonly string: readonly ["char", "varchar", "text", "uuid"];
+    readonly date: readonly ["date", "time", "datetime", "timestamp", "timestamptz"];
+    readonly json: readonly ["json", "jsonb"];
+    readonly blob: readonly ["blob", "bytea"];
+    readonly boolean: readonly ["bool", "boolean"];
+    readonly vector: readonly ["vector", "halfvec", "sparsevec"];
+};
+/** The family of a logical field type, or `undefined` where it names none. */
+export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
  * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
  * and the only one that may state `PRIMARY KEY` in its own column definition.

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/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.43.0",
   "type": "module",
   "engines": {
     "node": ">=24"