uql-orm 0.45.1 → 0.47.0

package/dist/schema/schemaASTDiffer.js

@@ -196,10 +196,14 @@ function diffColumn(tableName, source, target, opts) {
     if (source.isUnique !== target.isUnique) {
         differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
     }
-    // Auto-increment is deliberately not compared. No engine turns a column into an identity, or out of
-    // one, without rewriting the table, and there is no DDL here that does it - so a difference could
-    // only ever be reported, never settled, and the statements emitted for it (a bare `ALTER COLUMN
-    // TYPE`) do not change it. The same rule `describeIndexDifferences` follows for what it cannot read.
+    // Four things are deliberately not compared, all for one reason: a difference here could only be
+    // reported, never settled, because no statement this generator emits would change it.
+    //   - `isAutoIncrement`: no engine makes a column an identity, or unmakes one, without rewriting the
+    //     table, and the alter emitted for it is a bare `ALTER COLUMN TYPE`.
+    //   - `enum`: a check, and a database reprints one from its parse tree. See the roadmap.
+    //   - `generatedAs`: only Postgres 17 and the MySQL family can rewrite an expression in place.
+    //   - `comment`: fixable on every engine but SQLite, and the only one of the four worth revisiting.
+    // The same rule `describeIndexDifferences` follows for what it cannot read.
     // Compare default values (if both defined)
     if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
         differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);

package/dist/schema/types.d.ts

@@ -106,6 +106,8 @@ export interface ColumnNode {
     readonly isUnique: boolean;
     /** The values the column accepts. See {@link EnumValues}. */
     readonly enum?: EnumValues;
+    /** The SQL an engine-generated column is computed from, as `GENERATED ALWAYS AS (...) STORED`. */
+    readonly generatedAs?: string;
     /** Column comment/description */
     readonly comment?: string;
     /** Reference to the parent table */

package/dist/sqlite/sqliteDialect.js

@@ -14,7 +14,8 @@ export class SqliteDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
         primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
-        columnComment: false, // SQLite does not support column comments
+        generatedColumnAdd: false, // accepted in a CREATE TABLE, rejected in an ALTER
+        commentSyntax: 'none',
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,

package/dist/type/dialect.d.ts

@@ -97,8 +97,27 @@ export interface EngineFeatures {
      * than emitting DDL the engine rejects.
      */
     readonly primaryKeyAlter: boolean;
-    /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
-    readonly columnComment: boolean;
+    /**
+     * Whether a stored generated column can be added to a table that already exists. False on SQLite,
+     * which takes one in a `CREATE TABLE` and rejects the same column in an `ALTER` ("cannot add a
+     * STORED column"), since filling it would rewrite every row - so a sync that would add one is
+     * refused by name rather than by the driver.
+     *
+     * A boolean rather than a mode: SQLite would accept a `VIRTUAL` column here, but emitting one where
+     * the entity said `stored` makes the same entity a stored column on a new database and a virtual one
+     * on an old, which nothing diffs and no one can see. Refusal has one form; only what UQL *emits*
+     * earns a mode, which is what makes {@link EngineFeatures.commentSyntax} three-way.
+     */
+    readonly generatedColumnAdd: boolean;
+    /**
+     * How this engine carries a comment on a table or a column, if at all: `inline` writes it into the
+     * declaration (MySQL, MariaDB), `statement` needs a `COMMENT ON` of its own (Postgres, CockroachDB),
+     * `none` has no such thing (SQLite, MongoDB).
+     *
+     * One knob rather than a boolean because the answer is three-way. Read as a boolean, Postgres landed
+     * on the same branch as SQLite and a documented column silently lost its comment.
+     */
+    readonly commentSyntax: 'inline' | 'statement' | 'none';
     /**
      * Whether every column of a vector index has to be `NOT NULL`, which MariaDB 12.3 enforces ("All
      * parts of a VECTOR index must be NOT NULL") and CockroachDB 26.3 does not - so being indexed, not

package/dist/type/entity.d.ts

@@ -344,7 +344,28 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * @example `@Field({ type: String, enum: ['draft', 'paid'] as const })`
      */
     readonly enum?: EnumValues;
+    /**
+     * @deprecated Renamed to {@link FieldOptions.computed}, which also takes `stored`. `npx uql-codemod`
+     * rewrites it. Giving both throws.
+     */
     readonly virtual?: QueryRaw;
+    /**
+     * An expression the database computes, rather than a value the caller writes. Never part of an
+     * insert or update either way.
+     *
+     * Unstored, it is spliced into each statement that reads the field, so nothing is persisted and any
+     * expression will do. With `stored`, it becomes a real column - `GENERATED ALWAYS AS (...) STORED` -
+     * which the engine keeps up to date, so it can be indexed and read like any other.
+     *
+     * @example `@Field({ type: String, computed: raw`"first" || ' ' || "last"`, stored: true })`
+     */
+    readonly computed?: QueryRaw;
+    /**
+     * Whether {@link FieldOptions.computed} is a column the database keeps, rather than an expression
+     * spliced into each statement. The dial to flip after profiling: `$select`, `$where` and `$sort`
+     * read the field the same way either side of it, so no call site changes.
+     */
+    readonly stored?: boolean;
     readonly updatable?: boolean;
     readonly eager?: boolean;
     readonly onInsert?: OnFieldCallback<V>;

package/dist/type/migration.d.ts

@@ -2,7 +2,7 @@ import type { VectorCast } from '../dialect/vectorCast.js';
 import type { FullColumnDefinition, TableDefinition } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
-import type { EnumValues, ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
+import type { ColumnNode, ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
 import type { EntityMeta, FieldOptions, IndexColumnSchema, LoggingOptions, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
  * Defines a migration using a simple object literal
@@ -95,10 +95,14 @@ export interface MigrationResult {
     readonly error?: Error;
 }
 /**
- * Represents a column in a database table schema
+ * A column as a statement describes one: {@link ColumnNode} with the engine's type spelling in place
+ * of the canonical one, and without the graph links.
+ *
+ * Derived so a field the node gains reaches every path that renders a column. Listed field by field,
+ * this dropped `enum` and then `generatedAs`, and a column added to an existing table arrived without
+ * the constraint or the expression the entity declared.
  */
-export interface ColumnSchema {
-    readonly name: string;
+export interface ColumnSchema extends Omit<ColumnNode, 'type' | 'table' | 'referencedBy' | 'references'> {
     /**
      * The engine's own type spelling, as introspection read it (`tinyint(1)`, `DATETIME`, `VARCHAR`).
      * Deliberately not a {@link CanonicalType}: the diff has to compare what the engine would *store*,
@@ -107,22 +111,10 @@ export interface ColumnSchema {
      * every sync for those columns. Use `sqlToCanonical` to interpret it.
      */
     readonly type: string;
-    readonly nullable: boolean;
-    readonly defaultValue?: unknown;
-    readonly isPrimaryKey: boolean;
-    readonly isAutoIncrement: boolean;
-    readonly isUnique: boolean;
+    /** Bounds introspection reports beside the type, where the engine states them separately. */
     readonly length?: number;
     readonly precision?: number;
     readonly scale?: number;
-    readonly comment?: string;
-    /**
-     * The values the column accepts, rendered as an inline `CHECK`. Carried only so a column *added* to
-     * an existing table is constrained the way one created with its table is; an alter drops it, since
-     * MySQL adds a second check rather than replacing the first. Introspection never sets it: a database
-     * reports a check as a constraint, not as a property of the column.
-     */
-    readonly enum?: EnumValues;
 }
 /**
  * Represents a database table schema
@@ -383,7 +375,8 @@ export interface SchemaIntrospector {
     /**
      * Introspect entire database schema and return SchemaAST.
      */
-    introspect(): Promise<SchemaAST>;
+    /** The whole database, or just the tables named. Names nothing matches are left out. */
+    introspect(tables?: readonly string[]): Promise<SchemaAST>;
     /**
      * Get all table names in the database
      */

package/dist/util/dialect.util.js

@@ -2,19 +2,20 @@ import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
+import { isDatabaseWritten } from './field.util.js';
 import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, someKey } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
-        return fieldOpts && !fieldOpts.virtual && (callbackKey !== 'onUpdate' || fieldOpts.updatable !== false);
+        return fieldOpts && !isDatabaseWritten(fieldOpts) && (callbackKey !== 'onUpdate' || fieldOpts.updatable !== false);
     });
 }
-/** Whether `key` is a real, non-virtual field that `record` provides a defined value for. */
+/** Whether `key` is a field the caller writes, and `record` provides a defined value for. */
 function isInsertableField(meta, record, key) {
     const field = meta.fields[key];
-    return !!field && !field.virtual && record[key] !== undefined;
+    return !!field && !isDatabaseWritten(field) && record[key] !== undefined;
 }
-/** Appends `record`'s not-yet-`seen` insertable keys (real, non-virtual, defined value) to `keys`. */
+/** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
 function addInsertFieldKeys(meta, record, seen, keys) {
     for (const key of getKeys(record)) {
         if (!seen.has(key) && isInsertableField(meta, record, key)) {

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

@@ -1,4 +1,5 @@
 import type { EntityMeta, FieldOptions } from '../type/index.js';
+import type { QueryRaw } from '../type/queryRaw.js';
 /**
  * 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
@@ -22,6 +23,28 @@ export declare const COLUMN_TYPES_BY_FAMILY: {
 };
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
+/**
+ * The expression the database computes for this field, whichever key declared it.
+ *
+ * `virtual` is `computed` under its old name and is read here so both spell one behaviour. Giving
+ * both is refused at registration rather than resolved, since only the author knows which was meant.
+ */
+export declare function computedExpression(field: FieldOptions): QueryRaw | undefined;
+/**
+ * Whether the field's expression is spliced into each statement that reads it, rather than stored.
+ *
+ * One of the two questions `virtual` used to answer alone. Every read site asks this - the DDL skip,
+ * the projection, the `$where` operand, the `ORDER BY` operand - because an inlined field has no
+ * column to name, while a stored one is read exactly like any other.
+ */
+export declare function isInlinedExpression(field: FieldOptions): boolean;
+/**
+ * Whether the database supplies this field's value, so no insert or update may write it.
+ *
+ * The other question, and the one that makes `stored` more than a rename: a stored computed column
+ * *is* a real column, so it is read like one - but writing to it is an error on every engine.
+ */
+export declare function isDatabaseWritten(field: FieldOptions): boolean;
 /**
  * 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

@@ -46,6 +46,34 @@ for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
 export function columnFamily(type) {
     return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
+/**
+ * The expression the database computes for this field, whichever key declared it.
+ *
+ * `virtual` is `computed` under its old name and is read here so both spell one behaviour. Giving
+ * both is refused at registration rather than resolved, since only the author knows which was meant.
+ */
+export function computedExpression(field) {
+    return field.computed ?? field.virtual;
+}
+/**
+ * Whether the field's expression is spliced into each statement that reads it, rather than stored.
+ *
+ * One of the two questions `virtual` used to answer alone. Every read site asks this - the DDL skip,
+ * the projection, the `$where` operand, the `ORDER BY` operand - because an inlined field has no
+ * column to name, while a stored one is read exactly like any other.
+ */
+export function isInlinedExpression(field) {
+    return computedExpression(field) !== undefined && field.stored !== true;
+}
+/**
+ * Whether the database supplies this field's value, so no insert or update may write it.
+ *
+ * The other question, and the one that makes `stored` more than a rename: a stored computed column
+ * *is* a real column, so it is read like one - but writing to it is an error on every engine.
+ */
+export function isDatabaseWritten(field) {
+    return computedExpression(field) !== 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/fieldOption.util.d.ts

@@ -15,6 +15,8 @@ declare const FIELD_OPTION_FAMILY: {
     readonly onDelete: '*';
     readonly enum: '*';
     readonly virtual: '*';
+    readonly computed: '*';
+    readonly stored: '*';
     readonly updatable: '*';
     readonly eager: '*';
     readonly onInsert: '*';
@@ -37,8 +39,15 @@ declare const FIELD_OPTION_FAMILY: {
  * 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];
+declare const INLINE_READS: readonly ["type", "virtual", "computed", "stored", "enum", "eager", "distance"];
+type InlineRead = (typeof INLINE_READS)[number];
+/**
+ * What a column the *database* writes cannot use. A stored computed column is a real column - it has
+ * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
+ * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
+ */
+declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement"];
+type GeneratedWrite = (typeof GENERATED_WRITES)[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
@@ -55,8 +64,12 @@ type FamilyOf<O> = O extends {
 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 stored: true;
+} ? GeneratedWrite : O extends {
     readonly virtual: QueryRaw;
-} ? Exclude<keyof FieldOptions, VirtualRead> : never) | (O extends {
+} | {
+    readonly computed: QueryRaw;
+} ? Exclude<keyof FieldOptions, InlineRead> : never) | (O extends {
     readonly isId: true;
     readonly nullable: true;
 } ? 'nullable' : never) | (O extends {

package/dist/util/fieldOption.util.js

@@ -1,4 +1,4 @@
-import { columnFamily } from './field.util.js';
+import { columnFamily, isInlinedExpression } 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.
@@ -15,6 +15,8 @@ const FIELD_OPTION_FAMILY = {
     onDelete: '*',
     enum: '*',
     virtual: '*',
+    computed: '*',
+    stored: '*',
     updatable: '*',
     eager: '*',
     onInsert: '*',
@@ -37,21 +39,38 @@ const FIELD_OPTION_FAMILY = {
  * 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 = [
+const INLINE_READS = [
     'type',
     'virtual',
+    'computed',
+    'stored',
     'enum',
     'eager',
     'distance',
 ];
+/**
+ * What a column the *database* writes cannot use. A stored computed column is a real column - it has
+ * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
+ * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
+ */
+const GENERATED_WRITES = [
+    'updatable',
+    'onInsert',
+    'onUpdate',
+    'softDelete',
+    'defaultValue',
+    'autoIncrement',
+];
 /**
  * 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 (isInlinedExpression(opts) && !INLINE_READS.some((read) => read === key))
+        return 'an inlined computed field';
+    if (opts.stored === true && GENERATED_WRITES.some((write) => write === key))
+        return 'a stored computed column';
     if (opts.isId === true && key === 'nullable' && opts.nullable === true)
         return 'a primary key';
     if (opts.updatable === false && key === 'onUpdate')

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

@@ -1,4 +1,4 @@
-import type { EntityMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
+import type { EntityMeta, FieldMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: RelationKey<E>[];
     readonly joinableKeys: RelationKey<E>[];
@@ -51,6 +51,39 @@ export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown)
  * cheaper than the row-value comparison no engine spells the same way.
  */
 export declare function parentsIn(joins: readonly ParentJoin[], parents: readonly unknown[]): Record<string, unknown[]>;
+/**
+ * The parents a bounded to-many read fans out over: the rows themselves, the columns matching them to
+ * their children.
+ */
+export type ParentPartition = {
+    readonly joins: readonly ParentJoin[];
+    readonly parents: readonly unknown[];
+    /** The parent's own fields: a `LATERAL` row source has to spell its key column's type. */
+    readonly parentFields: Readonly<Record<string, FieldMeta | undefined>>;
+};
+/**
+ * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
+ * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
+ * correct and cheaper.
+ */
+export declare function isBoundedPerParent(query: Pick<RelationQuery, '$limit' | '$skip'>): boolean;
+/**
+ * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
+ * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
+ * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
+ */
+export declare function queryChildrenOf<E>(query: Query<E>, joins: readonly ParentJoin[], parent: unknown): Query<E>;
+/**
+ * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
+ * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
+ */
+export declare function queryChildrenOfAll<E>(query: Query<E>, joins: readonly ParentJoin[], parents: readonly unknown[]): Query<E>;
+/**
+ * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
+ * the parents it is being read for, whether the filter names their keys as values or, for a correlated
+ * shape, as a reference to a row source.
+ */
+export declare function queryNarrowedTo<E>(query: Query<E>, filter: Record<string, unknown>): Query<E>;
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
  * column a single key contributes, an OR of key maps for several.

package/dist/util/relationQuery.util.js

@@ -62,6 +62,45 @@ export function joinedRowKey(joins, row) {
 export function parentsIn(joins, parents) {
     return Object.fromEntries(joins.map(({ parent, joined }) => [joined, parents.map((it) => read(it, parent))]));
 }
+/**
+ * Whether a to-many's own query asks for a share *per parent* rather than a slice of the whole page.
+ * Only `$limit`/`$skip` do: without one, a single flat statement over an `IN (...)` list is both
+ * correct and cheaper.
+ */
+export function isBoundedPerParent(query) {
+    return query.$limit !== undefined || query.$skip !== undefined;
+}
+/**
+ * The `$where` naming exactly one parent's children: every joined column equal to that parent's value.
+ * What a per-parent bounded read filters each of its branches by, and the composite half of
+ * {@link childrenOf}.
+ */
+function childOf(joins, parent) {
+    return Object.fromEntries(joins.map(({ parent: key, joined }) => [joined, read(parent, key)]));
+}
+/**
+ * `query` narrowed to one parent's children: what a single branch of a bounded per-parent read asks
+ * for. Shared by the backends so how the parent's filter merges into the relation's own is decided
+ * once - both spelled it out, and a rule that ever needs more than a spread would have to change twice.
+ */
+export function queryChildrenOf(query, joins, parent) {
+    return queryNarrowedTo(query, childOf(joins, parent));
+}
+/**
+ * `query` narrowed to the children of a whole page of parents, which is the flat read a relation with
+ * no share of its own takes. Over-selects on a composite key exactly as {@link parentsIn} does.
+ */
+export function queryChildrenOfAll(query, joins, parents) {
+    return queryNarrowedTo(query, parentsIn(joins, parents));
+}
+/**
+ * `query` with `filter` merged into its own `$where`: the one rule for narrowing a relation's query to
+ * the parents it is being read for, whether the filter names their keys as values or, for a correlated
+ * shape, as a reference to a row source.
+ */
+export function queryNarrowedTo(query, filter) {
+    return { ...query, $where: { ...query.$where, ...filter } };
+}
 /**
  * The `$where` naming exactly the children of the rows `parentIds` identifies: an `IN` over the one
  * column a single key contributes, an OR of key maps for several.
@@ -74,9 +113,7 @@ export function childrenOf(joins, parentIds) {
     if (joins.length === 1) {
         return { [first.joined]: parentIds };
     }
-    return {
-        $or: parentIds.map((id) => Object.fromEntries(joins.map(({ parent, joined }) => [joined, read(id, parent)]))),
-    };
+    return { $or: parentIds.map((id) => childOf(joins, id)) };
 }
 function read(row, key) {
     return row[key];

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. 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.45.1",
+  "version": "0.47.0",
   "type": "module",
   "engines": {
     "node": ">=24"