uql-orm 0.29.0 → 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.29.0",
+  "version": "0.30.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -133,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",