uql-orm 0.28.2 → 0.30.0

package/dist/type/queryWhere.d.ts

@@ -257,8 +257,11 @@ export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOpe
  * Value for a field comparison. A bare array is an implicit `$in` for scalar fields only:
  * on array-typed fields (e.g. a vector `number[]`) an array of arrays is ambiguous, so
  * membership there requires an explicit operator.
+ *
+ * `null` is accepted on a nullable field (an optional property is a nullable column), matching what
+ * `$eq: null` already took.
  */
-export type QueryWhereFieldValue<T> = T | ([NonNullable<T>] extends [readonly unknown[]] ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
+export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) | ([NonNullable<T>] extends [readonly unknown[]] ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
 /**
  * query filter array - used for `$and`, `$or`, `$not`, `$nor` operators.
  */

package/dist/type/universalQuerier.d.ts

@@ -1,5 +1,5 @@
-import type { IdValue, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
+import type { EntityData, IdValue, UpdatePayload } from './entity.js';
+import type { Query, QueryConflictPaths, QueryFilter, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
@@ -46,12 +46,12 @@ export interface UniversalQuerier {
      */
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     /**
-     * counts the number of records matching the given search parameters.
+     * counts the number of records matching the given filter.
      * @param entity the target entity
-     * @param q the search options
+     * @param q the filter
      * @return the count
      */
-    count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Insert a single record and return its ID (provided, `onInsert`-generated, or
      * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
@@ -61,7 +61,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return the ID
      */
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
     /**
      * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
      * dialect's bind-parameter limit) and return their IDs in payload order.
@@ -75,7 +75,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return the IDs
      */
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     /**
      * updates a record partially.
      * @param entity the entity to persist on
@@ -99,7 +99,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     /**
      * Insert or update many records based on the conflict paths.
      * @param entity the entity to persist on
@@ -107,21 +107,21 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on

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

@@ -1,6 +1,6 @@
-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';
+import { type CascadeType, type EntityData, 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>[];
+export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
 /**
  * Resolves the columns of an INSERT statement: the union of the persistable fields provided by
  * any record (in first-seen order), plus every `onInsert` field. Records missing one of these
@@ -13,7 +13,7 @@ export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: E, call
  * has run {@link fillOnFields} first (it stamps them on every record, but the querier's
  * chunk-size estimate inspects the raw payload).
  */
-export declare function getInsertFieldKeys<E>(meta: EntityMeta<E>, payloads: E[]): FieldKey<E>[];
+export declare function getInsertFieldKeys<E>(meta: EntityMeta<E>, payloads: EntityData<E>[]): FieldKey<E>[];
 export declare function getFieldCallbackValue(val: OnFieldCallback): string | number | bigint | boolean | Date | QueryRaw | readonly {
     readonly __json?: never;
 }[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
@@ -28,7 +28,7 @@ export declare function getSoftDeleteValue(field: FieldOptions): string | number
 }[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
     readonly __json?: never;
 };
-export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: E | E[], callbackKey: CallbackKey): E[];
+export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): EntityData<E>[];
 /**
  * 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,
@@ -100,3 +100,25 @@ export declare function parseRelationSize(val: unknown): number | QuerySizeCompa
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
 export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, agg?: QueryAggMap<E>): ParsedGroupEntry[];
+/**
+ * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
+ * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
+ * reading their keys as operators drops the condition (a `Date` has none) or throws on an array's
+ * indices. Shared by the SQL and MongoDB builders, whose `$where` and `$having` all face this.
+ */
+export declare function isOperatorMap(value: unknown): value is Record<string, unknown>;
+/**
+ * A page operand, checked before it reaches an engine. These arrive from page arithmetic and from
+ * REST query strings (`parseQueryParams` yields `NaN` for a non-numeric one), and each engine's own
+ * complaint names neither the clause nor the value - or, for `$limit: 0`, quietly means something
+ * else. Shared so every backend rejects the same input.
+ */
+export declare function assertNonNegativeInteger(value: number, clause: string): number;
+/**
+ * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
+ * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * SQL and MongoDB refuse the same query with the same words.
+ */
+export declare function throwUnknownAggregateColumn(key: string, clause: string): never;
+/** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
+export declare function assertAggregateColumns(clauseMap: object | undefined, emitted: ReadonlySet<string>, clause: string): void;

package/dist/util/dialect.util.js

@@ -301,3 +301,45 @@ export function parseGroupMap(group, agg) {
     }
     return entries;
 }
+/**
+ * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
+ * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
+ * reading their keys as operators drops the condition (a `Date` has none) or throws on an array's
+ * indices. Shared by the SQL and MongoDB builders, whose `$where` and `$having` all face this.
+ */
+export function isOperatorMap(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date) &&
+        !(value instanceof Uint8Array) &&
+        !(value instanceof QueryRaw));
+}
+/**
+ * A page operand, checked before it reaches an engine. These arrive from page arithmetic and from
+ * REST query strings (`parseQueryParams` yields `NaN` for a non-numeric one), and each engine's own
+ * complaint names neither the clause nor the value - or, for `$limit: 0`, quietly means something
+ * else. Shared so every backend rejects the same input.
+ */
+export function assertNonNegativeInteger(value, clause) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError(`${clause} must be a non-negative integer, got ${value}`);
+    }
+    return value;
+}
+/**
+ * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
+ * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * SQL and MongoDB refuse the same query with the same words.
+ */
+export function throwUnknownAggregateColumn(key, clause) {
+    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor an $agg alias`);
+}
+/** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
+export function assertAggregateColumns(clauseMap, emitted, clause) {
+    for (const key of getKeys(clauseMap ?? {})) {
+        if (!emitted.has(key)) {
+            throwUnknownAggregateColumn(key, clause);
+        }
+    }
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.28.2",
+  "version": "0.30.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -12,8 +12,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "browser": {
-    "./dist/context/context.js": "./dist/context/context.browser.js",
-    "./dist/querier/querierContext.js": "./dist/querier/querierContext.browser.js"
+    "./dist/context/context.js": "./dist/context/context.browser.js"
   },
   "bin": {
     "uql-migrate": "./dist/migrate/bin.js"
@@ -134,13 +133,13 @@
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
-    "@types/pg": "^8.21.0",
+    "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.3",
     "mongodb": "^7.5.0",
-    "mysql2": "^3.23.3",
+    "mysql2": "^3.23.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",

package/dist/querier/querierContext.browser.d.ts

@@ -1,12 +0,0 @@
-import type { Querier } from '../type/index.js';
-/**
- * Browser build of the transactional querier context: bundlers targeting the browser resolve
- * `querierContext.ts` to this file (see the `browser` map in package.json), keeping the root entrypoint
- * free of `node:async_hooks`.
- *
- * Nothing in a browser bundle opens a transaction. The browser querier serializes queries over HTTP and
- * the server owns the transaction, so there is no ambient querier to hand out and no flow to track.
- */
-export declare function withQuerierContext<T>(_querier: Querier, callback: () => T): T;
-export declare function currentQuerier(): Querier;
-export declare function currentQuerierIfAny(): Querier | undefined;

package/dist/querier/querierContext.browser.js

@@ -1,18 +0,0 @@
-/**
- * Browser build of the transactional querier context: bundlers targeting the browser resolve
- * `querierContext.ts` to this file (see the `browser` map in package.json), keeping the root entrypoint
- * free of `node:async_hooks`.
- *
- * Nothing in a browser bundle opens a transaction. The browser querier serializes queries over HTTP and
- * the server owns the transaction, so there is no ambient querier to hand out and no flow to track.
- */
-export function withQuerierContext(_querier, callback) {
-    return callback();
-}
-export function currentQuerier() {
-    throw new TypeError('currentQuerier() is server-only: transactions run on the server, and the browser querier sends each ' +
-        'request over HTTP. Call it from server code, or use the querier you already have.');
-}
-export function currentQuerierIfAny() {
-    return undefined;
-}

package/dist/querier/querierContext.d.ts

@@ -1,22 +0,0 @@
-import type { Querier } from '../type/index.js';
-/** Runs `callback` with `querier` as the ambient one, for the whole async flow beneath it. */
-export declare function withQuerierContext<T>(querier: Querier, callback: () => T): T;
-/**
- * The querier of the enclosing `@Transactional()` method.
- *
- * This is what replaced `@InjectQuerier()`: the standard decorator spec has no parameter decorators, so
- * the querier can no longer be injected into an argument and is read from the ambient flow instead.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export declare function currentQuerier(): Querier;
-/** The ambient querier, or `undefined` outside a transaction. For callers that can work without one. */
-export declare function currentQuerierIfAny(): Querier | undefined;

package/dist/querier/querierContext.js

@@ -1,42 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-/**
- * The querier `@Transactional()` opened for the current async flow.
- *
- * Separate from the `UqlContext` storage in `context/context.ts` on purpose: that one is remapped to a
- * synchronous browser shim which cannot propagate across `await`, and a querier handle must. Nothing in
- * a browser bundle opens a transaction, so this stays server-only and `verify-dist` keeps it out of the
- * browser-facing graph.
- */
-const querierStorage = new AsyncLocalStorage();
-/** Runs `callback` with `querier` as the ambient one, for the whole async flow beneath it. */
-export function withQuerierContext(querier, callback) {
-    return querierStorage.run(querier, callback);
-}
-/**
- * The querier of the enclosing `@Transactional()` method.
- *
- * This is what replaced `@InjectQuerier()`: the standard decorator spec has no parameter decorators, so
- * the querier can no longer be injected into an argument and is read from the ambient flow instead.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export function currentQuerier() {
-    const querier = querierStorage.getStore();
-    if (!querier) {
-        throw new TypeError('currentQuerier() found no active querier. Call it inside a @Transactional() method, or take a querier ' +
-            'from the pool yourself with `await using querier = await pool.getQuerier()`.');
-    }
-    return querier;
-}
-/** The ambient querier, or `undefined` outside a transaction. For callers that can work without one. */
-export function currentQuerierIfAny() {
-    return querierStorage.getStore();
-}

package/dist/querier/transactional.d.ts

@@ -1,26 +0,0 @@
-import type { IsolationLevel, QuerierPool } from '../type/index.js';
-export type TransactionalOptions = {
-    /** `required` opens a transaction when none is active; `supported` joins one but never starts one. */
-    readonly propagation?: 'supported' | 'required';
-    readonly pool?: QuerierPool;
-    readonly isolationLevel?: IsolationLevel;
-};
-/**
- * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
- *
- * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
- * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
- * so the querier travels through async-local storage instead. A nested call joins the transaction
- * already in flight rather than opening a second one.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export declare function Transactional({ propagation, pool, isolationLevel }?: TransactionalOptions): <This, Args extends unknown[], R>(original: (this: This, ...args: Args) => Promise<R>, context: ClassMethodDecoratorContext<This>) => (this: This, ...args: Args) => Promise<R>;

package/dist/querier/transactional.js

@@ -1,43 +0,0 @@
-import { getQuerierPool } from '../options.js';
-import { currentQuerierIfAny, withQuerierContext } from './querierContext.js';
-/**
- * Wraps the method in a transaction and publishes its querier for {@link currentQuerier} to pick up.
- *
- * @remarks Replaces the `@InjectQuerier()` parameter that used to receive the querier. The standard
- * decorator spec has no parameter decorators, and the separate TC39 proposal for them is still Stage 1,
- * so the querier travels through async-local storage instead. A nested call joins the transaction
- * already in flight rather than opening a second one.
- *
- * @example
- * ```ts
- * class UserService {
- *   @Transactional()
- *   async register(data: Partial<User>) {
- *     await currentQuerier().insertOne(User, data);
- *   }
- * }
- * ```
- */
-export function Transactional({ propagation = 'required', pool, isolationLevel } = {}) {
-    return (original, context) => {
-        // Checked at decoration time rather than on the first call: a synchronous method cannot be wrapped in
-        // a transaction, and finding that out at startup beats finding out mid-request.
-        if (original.constructor.name !== 'AsyncFunction') {
-            throw new TypeError(`@Transactional() needs an async method, but '${String(context.name)}' is not one.`);
-        }
-        return async function (...args) {
-            // Already inside a transactional flow: join it and let the outermost call own commit and release.
-            if (currentQuerierIfAny()) {
-                return original.apply(this, args);
-            }
-            // `withQuerier` releases; `transaction` commits or rolls back. `supported` joins a transaction but
-            // never starts one, so it takes only the first half.
-            return (pool ?? getQuerierPool()).withQuerier((querier) => {
-                const run = () => original.apply(this, args);
-                return withQuerierContext(querier, () => propagation === 'supported'
-                    ? run()
-                    : querier.transaction(run, isolationLevel ? { isolationLevel } : undefined));
-            });
-        };
-    };
-}