uql-orm 0.52.0 → 0.54.0

package/dist/util/dialect.util.js

@@ -3,7 +3,7 @@ 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';
+import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isWhereMap, someKey } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -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]);
@@ -234,37 +235,24 @@ const JSON_UPDATE_OPS = [
 export function isJsonUpdateOp(value) {
     return value !== null && typeof value === 'object' && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
 }
-export function augmentWhere(meta, target = {}, source = {}) {
-    const targetComparison = buildQueryWhereAsMap(meta, target);
-    const sourceComparison = buildQueryWhereAsMap(meta, source);
-    return {
-        ...targetComparison,
-        ...sourceComparison,
-    };
-}
 /**
- * Normalizes any `$where` shape (id, id[], raw, or map) to a `QueryWhereMap`. Read-only: for a map
- * input it returns that same object by reference (no copy), so callers must not mutate the result -
- * {@link applyFilters} and {@link augmentWhere} return new objects instead.
+ * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
+ * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
  */
-export function buildQueryWhereAsMap(meta, filter = {}) {
-    if (filter instanceof QueryRaw) {
-        return { $and: [filter] };
-    }
-    if (Array.isArray(filter)) {
-        // A list of bare ids is an `IN` over the one key column; a list of anything else is a list of
-        // `$where`s, which is an OR - and that is how a composite's id objects name a settled set of rows.
-        return filter.every(isScalarId)
-            ? { [soleIdOf(meta, 'addressing by a bare id value')]: filter }
-            : { $or: filter };
+export function whereIds(meta, ids) {
+    if (Array.isArray(ids) ? ids.every(isScalarId) : isScalarId(ids)) {
+        return { [soleIdOf(meta, 'addressing by a bare id value')]: ids };
     }
-    if (isScalarId(filter)) {
-        // A scalar can only name one column, so on a composite it would address every row agreeing on
-        // that one. A composite is addressed by a map, which falls through below as the `$where` it
-        // already is - an id object and a where map are the same shape by design.
-        return { [soleIdOf(meta, 'addressing by a bare id value')]: filter };
+    return (Array.isArray(ids) ? { $or: ids } : ids);
+}
+/**
+ * Refuses a `$where` that is not a map. Untyped JS and parsed JSON can still pass an id or a list of
+ * them, and a scalar read as a map has no keys: the statement would address every row.
+ */
+export function assertWhere(meta, where) {
+    if (!isWhereMap(where)) {
+        throw new TypeError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
     }
-    return filter;
 }
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
 export function withoutSoftDeleteFilter(filters) {
@@ -314,7 +302,7 @@ export function applyFilters(meta, whereMap, opts) {
             }
             continue;
         }
-        const conditionMap = buildQueryWhereAsMap(meta, condition);
+        const conditionMap = condition;
         if (!hasKeys(conditionMap)) {
             continue; // resolved to "no restriction" (e.g. a trusted system context) - nothing to merge
         }

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/object.util.d.ts

@@ -35,3 +35,5 @@ export declare function getFieldKeys<E>(fields: {
  * is what a `$where` map and a composite key's id object both are; an array is a list of either.
  */
 export declare function isScalarId(value: unknown): boolean;
+/** Whether `value` is a plain object naming columns, the one shape a `$where` takes. */
+export declare function isWhereMap(value: unknown): value is Record<string, unknown>;

package/dist/util/object.util.js

@@ -81,3 +81,7 @@ export function isScalarId(value) {
     const proto = Object.getPrototypeOf(value);
     return proto !== Object.prototype && proto !== null;
 }
+/** Whether `value` is a plain object naming columns, the one shape a `$where` takes. */
+export function isWhereMap(value) {
+    return !Array.isArray(value) && !isScalarId(value);
+}

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.52.0",
+  "version": "0.54.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -151,7 +151,7 @@
     "express": "^5.2.1",
     "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
-    "mssql": "^11",
+    "mssql": "^12",
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",