uql-orm 0.26.3 → 0.28.0

package/dist/type/entity.d.ts

@@ -1,7 +1,7 @@
 import type { ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { DistributiveOmit, Json, Scalar, Type, Unpacked } from './utility.js';
+import type { Except, Json, Scalar, Type, Unpacked } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /**
  * Allow to customize the name of the property that identifies an entity
@@ -579,10 +579,10 @@ export type EntityOptions<E = unknown> = {
 };
 /**
  * Everything an index carries beyond its columns, shared by `@Index`, `defineEntity` and the
- * migration builder's `table.index(...)`. `DistributiveOmit` (not plain `Omit`) keeps `type`/
- * `distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
+ * migration builder's `table.index(...)`. `Except` (not plain `Omit`) keeps `type`/`distance` a
+ * discriminated pair: omitting `distance` on a vector index type is a compile error.
  */
-export type IndexOptions = DistributiveOmit<EntityIndexMeta, 'columns'>;
+export type IndexOptions = Except<EntityIndexMeta, 'columns'>;
 /**
  * An index as authored, before `defineIndex` normalizes its columns.
  */

package/dist/type/index.d.ts

@@ -9,6 +9,7 @@ export * from './querier.js';
 export * from './querierPool.js';
 export * from './query.js';
 export * from './queryAggregate.js';
+export * from './queryLock.js';
 export * from './queryRaw.js';
 export * from './queryWhere.js';
 export * from './universalQuerier.js';

package/dist/type/index.js

@@ -9,6 +9,7 @@ export * from './querier.js';
 export * from './querierPool.js';
 export * from './query.js';
 export * from './queryAggregate.js';
+export * from './queryLock.js';
 export * from './queryRaw.js';
 export * from './queryWhere.js';
 export * from './universalQuerier.js';

package/dist/type/query.d.ts

@@ -1,7 +1,8 @@
 import type { FieldKey, JsonFieldPaths, RelationKey } from './entity.js';
+import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
-import type { BooleanLike, PrimaryKey, Unpacked } from './utility.js';
+import type { BooleanLike, Except, PrimaryKey, Unpacked } from './utility.js';
 import type { QueryVectorSearch } from './vector.js';
 export type QueryOptions = {
     /**
@@ -65,7 +66,7 @@ export type QueryConflictPaths<E> = {
 /**
  * options to populate a relation.
  */
-export type QueryPopulateRelationOptions<E> = (E extends unknown[] ? Query<Unpacked<E>> : QueryUnique<Unpacked<E>>) & {
+export type QueryPopulateRelationOptions<E> = (E extends unknown[] ? Except<Query<Unpacked<E>>, '$lock'> : QueryUnique<Unpacked<E>>) & {
     $required?: boolean;
 };
 /**
@@ -125,7 +126,7 @@ export type QuerySortMap<E> = {
 } & {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
 } & {
-    [K in RelationKey<E>]?: QuerySortMap<NonNullable<Unpacked<E[K]>>>;
+    [K in RelationKey<E> as NonNullable<E[K]> extends readonly unknown[] ? never : K]?: QuerySortMap<NonNullable<E[K]>>;
 };
 /**
  * pager options.
@@ -180,11 +181,21 @@ export type Query<E> = {
      * whether to return only distinct rows.
      */
     $distinct?: boolean;
+    /**
+     * take a row-level lock on the rows this query returns (`SELECT ... FOR UPDATE`). Needs an open
+     * transaction: outside one the statement commits and drops the lock before the caller can act on
+     * the rows, so it is rejected rather than emitted. Locks only the queried entity, never anything
+     * reached through `$populate`. SQL only; MongoDB and the SQLite family reject it.
+     *
+     * Deliberately declared here rather than on `QuerySearch`, which `count`/`update`/`delete` take:
+     * that placement is what keeps the clause off those statements at the type level.
+     */
+    $lock?: QueryLock;
 } & QuerySearch<E>;
 /**
  * options to get a single record.
  */
-export type QueryOne<E> = Omit<Query<E>, '$limit'>;
+export type QueryOne<E> = Except<Query<E>, '$limit'>;
 /**
  * options to get an unique record.
  */

package/dist/type/queryLock.d.ts

@@ -0,0 +1,21 @@
+declare const QUERY_LOCK_WAITS: readonly ['block', 'nowait', 'skip'];
+/**
+ * What to do about a row someone else already holds. `block` (the default) waits for them; `nowait`
+ * fails the statement at once; `skip` leaves the row out of the result, which is what makes a
+ * work-queue possible: each worker takes rows nobody else has.
+ */
+export type QueryLockWait = (typeof QUERY_LOCK_WAITS)[number];
+/**
+ * `true` takes the lock and waits for anyone holding the rows; the object form chooses what to do
+ * instead of waiting. `false` takes none, so a query built conditionally needs no branch.
+ */
+export type QueryLock = boolean | {
+    readonly wait?: QueryLockWait;
+};
+/**
+ * The wait policy this lock resolves to, or `undefined` when there is no lock. An unknown policy
+ * throws here rather than reaching a dialect, so the message names what the caller wrote instead of
+ * the SQL it would have produced.
+ */
+export declare function parseQueryLock(lock: QueryLock | undefined): QueryLockWait | undefined;
+export {};

package/dist/type/queryLock.js

@@ -0,0 +1,19 @@
+const QUERY_LOCK_WAITS = ['block', 'nowait', 'skip'];
+function isOneOf(vals, val) {
+    return vals.includes(val);
+}
+/**
+ * The wait policy this lock resolves to, or `undefined` when there is no lock. An unknown policy
+ * throws here rather than reaching a dialect, so the message names what the caller wrote instead of
+ * the SQL it would have produced.
+ */
+export function parseQueryLock(lock) {
+    if (lock === undefined || lock === false) {
+        return undefined;
+    }
+    const wait = lock === true ? 'block' : (lock?.wait ?? 'block');
+    if (!isOneOf(QUERY_LOCK_WAITS, wait)) {
+        throw new TypeError(`unknown $lock wait policy: ${String(wait)}`);
+    }
+    return wait;
+}

package/dist/type/utility.d.ts

@@ -47,10 +47,14 @@ export type Writable<T> = {
     -readonly [K in keyof T]: T[K];
 };
 /**
- * `Omit`, but distributed over `T`'s union members before recombining. Plain `Omit<T, K>` computes
- * `keyof T` up front, which for a union takes the intersection of each member's keys and flattens
- * their property types together - collapsing a discriminated union (e.g. `EntityIndexMeta`'s
- * `type`/`distance` pairing) into a single, non-discriminated shape.
+ * `Omit`, fixed on three counts. Its key has to exist, where `Omit<T, K extends keyof any>` lets a
+ * typo or a renamed property silently omit nothing. Being a homomorphic mapped type it distributes
+ * over unions, where `Omit` intersects each member's keys and flattens a discriminated union (e.g.
+ * `EntityIndexMeta`'s `type`/`distance` pairing) into one non-discriminated shape. And it removes
+ * the key from types carrying an index signature, where `Exclude<keyof T, K>` widens back to
+ * `string | number` and leaves the key in place.
  */
-export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type Except<T, K extends keyof T> = {
+    [P in keyof T as P extends K ? never : P]: T[P];
+};
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;

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

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
+import { type CascadeType, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: E, callbackKey: CallbackKey): FieldKey<E>[];
 /**
@@ -47,7 +47,6 @@ export declare function isCascadable(action: CascadeType, configuration?: boolea
  */
 export declare function asSelectMap<E>(select: QuerySelectValue<E> | undefined): QuerySelect<E> | undefined;
 export declare function normalizeScalarFieldSelection<E>(meta: EntityMeta<E>, select?: QuerySelect<E>, exclude?: QueryExclude<E>): FieldKey<E>[];
-export declare function buildSortMap<E>(sort: QuerySortMap<E> | undefined): QuerySortMap<E>;
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export declare function isVectorSearch(value: unknown): value is QueryVectorSearch;
 /** Type guard: checks whether an update payload value is a JSON operator object. */

package/dist/util/dialect.util.js

@@ -141,9 +141,6 @@ export function normalizeScalarFieldSelection(meta, select, exclude) {
     const excluded = excludedFields;
     return allFields.filter((it) => !excluded.has(it));
 }
-export function buildSortMap(sort) {
-    return (sort ?? {});
-}
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export function isVectorSearch(value) {
     return value !== null && typeof value === 'object' && '$vector' in value;

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

@@ -1,13 +1,24 @@
-import type { EntityMeta, Query, QueryPopulate, RelationKey } from '../type/index.js';
+import type { EntityMeta, Except, Query, QueryPopulate, RelationKey, RelationMeta } from '../type/index.js';
 export type RelationRequestSummary<E> = {
     readonly requestedKeys: RelationKey<E>[];
     readonly joinableKeys: RelationKey<E>[];
     readonly toManyKeys: RelationKey<E>[];
 };
+/** Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. */
+export declare function isToManyRelation(relation: RelationMeta): boolean;
+/**
+ * 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
+ * to drop them without a word. `satisfies` ties each key to {@link RelationQuery}, so renaming one
+ * breaks this list at compile time rather than quietly stopping the check.
+ */
+declare const JOINED_RELATION_REJECTIONS: readonly [readonly ["$sort", "a join brings one row per parent, so there is nothing to order"], readonly ["$limit", "a join brings one row per parent, so there is nothing to page"], readonly ["$skip", "a join brings one row per parent, so there is nothing to page"], readonly ["$distinct", "it applies to the whole statement, not to one of its joins"]];
+/** A key only a to-many's own query can carry, and that a joined relation therefore rejects. */
+export type JoinedRelationRejectedKey = (typeof JOINED_RELATION_REJECTIONS)[number][0];
 export declare function getRelationRequestSummary<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): RelationRequestSummary<E>;
 /** True when `$populate` includes at least one relation key. */
-export declare function isPopulatingRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
-export type RelationQuery<E extends object = object> = Query<E> & {
+export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: QueryPopulate<E>): boolean;
+export type RelationQuery<E extends object = object> = Except<Query<E>, '$lock'> & {
     $required?: boolean;
 };
 export type ParsedRelationQuery<E extends object = object> = {
@@ -20,3 +31,4 @@ export declare function parseRelationQueryValue<E extends object = object>(value
 /** Parses the relation payload for `relKey` */
 export declare function parseRelationAtKey<E>(relKey: RelationKey<E>, populate?: QueryPopulate<E>): ParsedRelationQuery;
 export declare function forEachRequestedRelation<E extends object>(meta: EntityMeta<E>, populate: QueryPopulate<E> | undefined, fn: (relKey: RelationKey<E>, rawValue: unknown) => void): void;
+export {};

package/dist/util/relationQuery.util.js

@@ -1,4 +1,31 @@
 import { getKeys } from './object.util.js';
+/** Whether a relation holds many rows per parent, so it cannot be joined into the parent's row. */
+export function isToManyRelation(relation) {
+    return relation.cardinality === '1m' || relation.cardinality === 'mm';
+}
+/**
+ * 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
+ * to drop them without a word. `satisfies` ties each key to {@link RelationQuery}, so renaming one
+ * breaks this list at compile time rather than quietly stopping the check.
+ */
+const JOINED_RELATION_REJECTIONS = [
+    ['$sort', 'a join brings one row per parent, so there is nothing to order'],
+    ['$limit', 'a join brings one row per parent, so there is nothing to page'],
+    ['$skip', 'a join brings one row per parent, so there is nothing to page'],
+    ['$distinct', 'it applies to the whole statement, not to one of its joins'],
+];
+const JOINED_RELATION_REJECTED_KEYS = new Map(JOINED_RELATION_REJECTIONS);
+function assertJoinableRelationQuery(relKey, value) {
+    if (!value || typeof value !== 'object') {
+        return;
+    }
+    for (const [key, reason] of JOINED_RELATION_REJECTED_KEYS) {
+        if (key in value) {
+            throw new TypeError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
+        }
+    }
+}
 export function getRelationRequestSummary(meta, populate) {
     const requestedKeys = [];
     const joinableKeys = [];
@@ -12,17 +39,20 @@ export function getRelationRequestSummary(meta, populate) {
         if (!relOpts)
             continue;
         requestedKeys.push(key);
-        if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
+        if (isToManyRelation(relOpts)) {
             toManyKeys.push(key);
         }
         else {
+            // Validated where the cardinality is decided, so every backend and every nesting level rejects
+            // the same shapes - the SQL dialects, MongoDB's lookups, and whatever reads this summary next.
+            assertJoinableRelationQuery(key, populate[key]);
             joinableKeys.push(key);
         }
     }
     return { requestedKeys, joinableKeys, toManyKeys };
 }
 /** True when `$populate` includes at least one relation key. */
-export function isPopulatingRelations(meta, populate) {
+export function populatesRelations(meta, populate) {
     if (!populate)
         return false;
     return getKeys(populate).some((key) => populate[key] && key in meta.relations);
@@ -41,6 +71,11 @@ function isRelationQueryObject(value) {
     return isRecord(value) && isValidRelationQueryShape(value);
 }
 export function parseRelationQueryValue(value) {
+    // Caught before the shape check so the message names the key, rather than reporting the whole
+    // object as an unrecognized relation query value.
+    if (isRecord(value) && '$lock' in value) {
+        throw new TypeError("'$lock' applies to the whole statement, not to a populated relation. Move it to the top level of the query.");
+    }
     if (isRelationQueryObject(value)) {
         return { query: value, required: value.$required === true, nested: true };
     }

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

@@ -1,6 +1,5 @@
 import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
 import type { PrimaryKey } from '../type/utility.js';
-export declare function flatObject<E extends object>(obj: E, pre?: string): E;
 export declare function unflatObjects<T extends object>(objects: RawRow[]): T[];
 /**
  * Unflattens a single raw row using pre-computed attribute paths.
@@ -17,7 +16,7 @@ export declare function obtainAttrsPaths<T extends object>(row: T): {
  * @param forbidQualified whether to forbid qualified identifiers (containing dots)
  * @param addDot whether to add a dot suffix
  */
-export declare function escapeSqlId(val: string, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
+export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
 /**
  * Payload for building a QueryUpdateResult.
  */

package/dist/util/sql.util.js

@@ -1,17 +1,6 @@
-import { getKeys, hasKeys } from './object.util.js';
+import { hasKeys } from './object.util.js';
 /** Pre-computed regex for each SQL identifier escape character to avoid per-call allocation. */
 const escapeIdRegexCache = { '`': /`/g, '"': /"/g };
-export function flatObject(obj, pre) {
-    return getKeys(obj).reduce((acc, key) => flatObjectEntry(acc, key, obj[key], typeof obj[key] === 'object' ? '' : pre), {});
-}
-function flatObjectEntry(map, key, val, pre) {
-    const prefix = pre ? `${pre}.${key}` : key;
-    if (typeof val === 'object' && val !== null) {
-        return getKeys(val).reduce((acc, prop) => flatObjectEntry(acc, prop, val[prop], prefix), map);
-    }
-    map[prefix] = val;
-    return map;
-}
 export function unflatObjects(objects) {
     if (!Array.isArray(objects) || !objects.length) {
         return objects;

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
   "license": "MIT",
-  "version": "0.26.3",
+  "version": "0.28.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -127,9 +127,9 @@
   "devDependencies": {
     "@libsql/client": "^0.17.4",
     "@neondatabase/serverless": "^1.1.0",
-    "@nestjs/common": "^11.1.29",
-    "@nestjs/core": "^11.1.29",
-    "@nestjs/testing": "^11.1.29",
+    "@nestjs/common": "^11.2.1",
+    "@nestjs/core": "^11.2.1",
+    "@nestjs/testing": "^11.2.1",
     "@tursodatabase/database": "^0.7.2",
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",