uql-orm 0.53.0 → 0.54.0

package/dist/schema/schemaASTBuilder.js

@@ -7,7 +7,7 @@
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { ddlText } from '../util/ddlExpression.util.js';
-import { computedExpression, isInlinedExpression } from '../util/field.util.js';
+import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
@@ -101,7 +101,7 @@ function addTableFromEntity(ctx, meta) {
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
-            generatedAs: ddlText(computedExpression(field), `the computed column '${columnName}'`),
+            generatedAs: ddlText(field.computed, `the computed column '${columnName}'`),
             comment: field.comment,
             enum: field.enum,
             table,
@@ -202,16 +202,16 @@ function addIndexesFromEntity(ctx, meta) {
         addCompositeIndex(ctx, table, meta, idxMeta);
     }
 }
-/**
- * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
- * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
- * subset, which is what diffing and introspection compare.
- */
 /** An `include` column is named like any other, so a naming strategy has to reach it too. */
 function resolveIncludeColumn(ctx, meta, column) {
     const field = meta.fields[column];
     return field ? ctx.resolveColumnName(column, field) : column;
 }
+/**
+ * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
+ * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
+ * subset, which is what diffing and introspection compare.
+ */
 function addCompositeIndex(ctx, table, meta, idxMeta) {
     // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
     // an index left with none is dropped, the same as one naming only unknown columns always was.

package/dist/type/entity.d.ts

@@ -359,11 +359,6 @@ 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.
@@ -818,12 +813,6 @@ export type EntityMeta<E> = {
     /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
     processedAt?: number;
 };
-/**
- * Configurable options for an entity (`@Entity()` / `defineEntity`).
- *
- * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
- * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
- */
 /**
  * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
  * this is DDL, so there is no placeholder a bound value could go into.
@@ -843,6 +832,12 @@ export type EntityMembers = {
     readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
     readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
 };
+/**
+ * Configurable options for an entity (`@Entity()` / `defineEntity`).
+ *
+ * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
+ * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
+ */
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**

package/dist/type/migration.d.ts

@@ -372,9 +372,6 @@ export interface SchemaIntrospector {
      * the database side never reports it, and no migration can close the gap.
      */
     readonly indexFacets: ReadonlySet<IndexFacet>;
-    /**
-     * Introspect entire database schema and return SchemaAST.
-     */
     /** The whole database, or just the tables named. Names nothing matches are left out. */
     introspect(tables?: readonly string[]): Promise<SchemaAST>;
     /**

package/dist/type/query.d.ts

@@ -59,17 +59,17 @@ export type QueryExclude<E> = QuerySelect<E>;
 export type QueryPopulate<E> = {
     [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
 };
+/**
+ * The key a read carries its relation tallies under. One spelling for the type and the runtime that
+ * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
+ */
+export declare const COUNT_RESULT_KEY = "_count";
 /**
  * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
  * which ones count. One statement per relation named here, batched over every parent at once, so it
  * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
  * a relation of the same name that `$populate` filled with rows.
  */
-/**
- * The key a read carries its relation tallies under. One spelling for the type and the runtime that
- * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.
- */
-export declare const COUNT_RESULT_KEY = "_count";
 export type QueryCount<E> = {
     [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
 };
@@ -141,6 +141,13 @@ type ToOneRelationKey<E> = {
 }[RelationKey<E>];
 /** The relation names a parent holds many rows of, which a populated query fills with a list. */
 type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
+/**
+ * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
+ * The tally is computed per parent as a correlated count, never by loading the rows.
+ */
+export type QuerySortByCount = {
+    $count: QuerySortDirection;
+};
 /**
  * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
  * like `QueryWhere`), relation sort via nested objects, and vector similarity search on
@@ -153,13 +160,6 @@ type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
  * against an intersection is repeated per constituent, which made this the single most expensive
  * type in the package to check.
  */
-/**
- * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
- * The tally is computed per parent as a correlated count, never by loading the rows.
- */
-export type QuerySortByCount = {
-    $count: QuerySortDirection;
-};
 export type QuerySortMap<E, Vector extends boolean = true> = {
     [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E> ? IsMany<E[K]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };

package/dist/type/query.js

@@ -1,9 +1,3 @@
-/**
- * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow
- * which ones count. One statement per relation named here, batched over every parent at once, so it
- * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of
- * a relation of the same name that `$populate` filled with rows.
- */
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
  * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.

package/dist/type/universalQuerier.d.ts

@@ -126,7 +126,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
      * auto-increment keys in batches without explicit IDs - otherwise those entries are
      * `undefined` rather than potentially wrong values. A composite key is never one the statement
-     * reports, so those rows are named from the payload instead.
+     * reports, so those rows are named as written, `onInsert` columns included.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
@@ -137,7 +137,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the id and whether it was created; see {@link QueryUpsertOneResult}
      */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
     /**
@@ -145,7 +145,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param entity the entity to persist on
      * @param conflictPaths the keys to use for the unique search
      * @param payload the data to be persisted
-     * @return operation metadata; see {@link QueryUpdateResult}
+     * @return the ids, in payload order; see {@link QueryUpsertManyResult}
      */
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**

package/dist/util/dialect.util.d.ts

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
@@ -35,7 +35,8 @@ export declare function getSoftDeleteValue(field: FieldOptions): string | number
 }[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
     readonly __json?: never;
 };
-export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): EntityData<E>[];
+/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
+export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
 /**
  * The relation keys present in `payload` whose cascade configuration allows `action`. Only
  * `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,

package/dist/util/dialect.util.js

@@ -73,6 +73,7 @@ export function getFieldCallbackValue(val) {
 export function getSoftDeleteValue(field) {
     return field.softDelete === true ? new Date() : getFieldCallbackValue(field.softDelete);
 }
+/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
 export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
     const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey]);

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

@@ -1,5 +1,4 @@
 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
@@ -23,26 +22,15 @@ 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.
+ * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
+ * because an inlined field has no column to name, while a stored one is read 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.
+ * Whether the database supplies this field's value, so no insert or update may write it: a stored
+ * computed column *is* a real column, read like one, but writing to it is an error on every engine.
  */
 export declare function isDatabaseWritten(field: FieldOptions): boolean;
 /**

package/dist/util/field.util.js

@@ -46,33 +46,20 @@ 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.
+ * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
+ * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export function isInlinedExpression(field) {
-    return computedExpression(field) !== undefined && field.stored !== true;
+    return field.computed !== 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.
+ * Whether the database supplies this field's value, so no insert or update may write it: a stored
+ * computed column *is* a real column, read like one, but writing to it is an error on every engine.
  */
 export function isDatabaseWritten(field) {
-    return computedExpression(field) !== undefined;
+    return field.computed !== undefined;
 }
 /**
  * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,

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

@@ -14,7 +14,6 @@ declare const FIELD_OPTION_FAMILY: {
     readonly references: '*';
     readonly onDelete: '*';
     readonly enum: '*';
-    readonly virtual: '*';
     readonly computed: '*';
     readonly stored: '*';
     readonly updatable: '*';
@@ -39,7 +38,7 @@ 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 INLINE_READS: readonly ["type", "virtual", "computed", "stored", "enum", "eager", "distance"];
+declare const INLINE_READS: readonly ["type", "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
@@ -66,8 +65,6 @@ type FamilyOfType<T> = T extends NumericColumnType | NumberConstructor | BigIntC
 type DeadOptions<O> = (O extends {
     readonly stored: true;
 } ? GeneratedWrite : O extends {
-    readonly virtual: QueryRaw;
-} | {
     readonly computed: QueryRaw;
 } ? Exclude<keyof FieldOptions, InlineRead> : never) | (O extends {
     readonly isId: true;

package/dist/util/fieldOption.util.js

@@ -14,7 +14,6 @@ const FIELD_OPTION_FAMILY = {
     references: '*',
     onDelete: '*',
     enum: '*',
-    virtual: '*',
     computed: '*',
     stored: '*',
     updatable: '*',
@@ -41,7 +40,6 @@ const FIELD_OPTION_FAMILY = {
  */
 const INLINE_READS = [
     'type',
-    'virtual',
     'computed',
     'stored',
     'enum',

package/dist/util/logger.d.ts

@@ -12,9 +12,6 @@ export declare class DefaultLogger implements Logger {
     logMigration(message: string): void;
     logSkippedMigration(message: string): void;
 }
-/**
- * A wrapper class that implements the Logger interface and handles different logging options.
- */
 /**
  * Secondary {@link LoggerWrapper} settings, alongside the primary `options: LoggingOptions`
  * constructor argument.
@@ -28,6 +25,9 @@ export interface LoggerWrapperConfig {
     /** Threshold in milliseconds - queries exceeding this are logged as slow. */
     slowQuery?: number;
 }
+/**
+ * A wrapper class that implements the Logger interface and handles different logging options.
+ */
 export declare class LoggerWrapper implements Logger {
     private readonly levels;
     private readonly logger?;

package/dist/util/logger.js

@@ -40,6 +40,9 @@ export class DefaultLogger {
         console.info(`\x1b[33mskipped migration:\x1b[0m ${message}`);
     }
 }
+/**
+ * A wrapper class that implements the Logger interface and handles different logging options.
+ */
 export class LoggerWrapper {
     levels;
     logger;

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { QueryRaw, type QueryRawFn, type Scalar } from '../type/index.js';
+import { QueryRaw, type QueryRawFn } from '../type/index.js';
 /**
  * Create a raw SQL expression.
  *
@@ -19,18 +19,11 @@ import { QueryRaw, type QueryRawFn, type Scalar } from '../type/index.js';
  * The callback form remains for SQL a template cannot express, such as a sub-query generated through
  * `dialect.find(...)`. See {@link col} for a context-aware column reference.
  *
- * **⚠️ Security:** the tag is safe because it binds; the other two forms are not. `raw('SQL')` emits
- * its argument verbatim and a callback emits whatever it writes, so build neither from user input.
- * Inside a callback, bind with `ctx.addValue()`.
+ * **⚠️ Security:** the tag is safe because it binds; a callback is not, since it emits whatever it
+ * writes, so never build one from user input. Inside a callback, bind with `ctx.addValue()`.
  */
 export declare function raw(strings: TemplateStringsArray, ...values: readonly unknown[]): QueryRaw;
 export declare function raw(value: QueryRawFn, alias?: string): QueryRaw;
-/**
- * @deprecated Emits its argument verbatim, so it cannot bind a value. Use the tagged template:
- * `raw('"a" > 1')` becomes `` raw`"a" > 1` ``, and `raw('LOG10(x)', 'score')` becomes
- * `` raw`LOG10(x)`.as('score') ``. `npx uql-codemod` rewrites both.
- */
-export declare function raw(value: Scalar, alias?: string): QueryRaw;
 /**
  * A column of the entity being queried, alias-qualified and escaped for the dialect. This is what a
  * template cannot know on its own: the alias is decided while the statement is built, not where the

package/dist/util/sql.util.js

@@ -200,8 +200,8 @@ export function buildUpdateResult(payload) {
     // UPDATE` convention makes `changes` a per-row weighted sum (1=insert, 2=update, 0=no-op), so a
     // batch mixing an insert and an update would fabricate ids for rows that were never touched. This
     // function has no way to tell the two call sites apart (`internalRun` reports the same header
-    // shape either way), so `AbstractSqlQuerier.upsertMany` strips `ids`/`firstId`/`created` back down
-    // to just `changes` for a multi-row `firstId`-dialect upsert after calling this.
+    // shape either way), so `AbstractSqlQuerier`'s `runUpsert` discards them for a multi-row `firstId`
+    // upsert and reads the ids back by the conflict columns instead.
     let ids = [];
     if (rows?.length) {
         ids = rows.map((r) => r['id']);

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, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "type": "module",
   "engines": {
     "node": ">=24"