uql-orm 0.36.1 → 0.37.1

package/dist/type/query.js

@@ -1,3 +1,14 @@
+/**
+ * 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 const COUNT_RESULT_KEY = '_count';
 /**
  * `Query`'s clauses grouped by the shape of their value - what a parser reading one off the wire and
  * a validator checking a relation's own query both need, and what each used to enumerate for itself.
@@ -14,5 +25,11 @@ export const QUERY_OBJECT_CLAUSES = [
     '$where',
     '$sort',
 ];
+/**
+ * Object clauses only the statement itself takes, never a relation's own query - the mirror of
+ * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a
+ * populated relation's rows are assembled after that, so there is nothing for a nested one to count.
+ */
+export const QUERY_ROOT_OBJECT_CLAUSES = ['$count'];
 export const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'];
 export const QUERY_BOOLEAN_CLAUSES = ['$distinct'];

package/dist/type/universalQuerier.d.ts

@@ -1,11 +1,20 @@
 import type { EntityData, FieldKey, IdValue, RelationKey, UpdatePayload } from './entity.js';
-import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryProjected, QuerySearch, QueryUpdateResult } from './query.js';
+import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
+import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
 /**
- * A `querier` allows to interact with the datasource to perform persistence operations on any entity.
+ * The operations {@link UniversalQuerier} and `ClientQuerier` declare identically, written once and
+ * instantiated per transport: `SharedQuerier<'server', QueryOptions>` against
+ * `SharedQuerier<'client', RequestOptions, QueryOptions & RequestOptions>`. See {@link QuerierResult}
+ * for how the return type follows `W`.
+ *
+ * @typeParam W - which side of the wire, picking each method's return type.
+ * @typeParam O - the per-call options.
+ * @typeParam DO - the delete methods' options, which the client also lets carry {@link QueryOptions}
+ * (`hardDelete`, `filters`) since it has no other way to reach them.
  */
-export interface UniversalQuerier {
+export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
     /**
      * obtains the record with the given primary key.
      * @param entity the target entity
@@ -13,30 +22,21 @@ export interface UniversalQuerier {
      * @param q the additional criteria options
      * @return the record
      */
-    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
+    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: IdValue<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the first record matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the record
      */
-    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P> | undefined>;
+    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the records matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the records
      */
-    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<QueryFindResult<E, S, V, X, P>[]>;
-    /**
-     * streams the records matching the given search parameters as an async iterable.
-     * Does not fill relations or fire lifecycle hooks - designed for high-performance
-     * bulk reads (ETL, exports, migrations).
-     * @param entity the target entity
-     * @param q the criteria options
-     * @return an async iterable of records
-     */
-    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
+    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C>[]>;
     /**
      * obtains the records matching the given search parameters,
      * also counts the number of matches ignoring pagination.
@@ -44,14 +44,67 @@ export interface UniversalQuerier {
      * @param q the criteria options
      * @return the records and the count
      */
-    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P>, opts?: QueryOptions): Promise<[QueryFindResult<E, S, V, X, P>[], number]>;
+    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierCountedResult<W, QueryFindResult<E, S, V, X, P, C>>;
     /**
-     * counts the number of records matching the given filter.
+     * counts the number of records matching the given filter, optionally paged - a `$skip`/`$limit`
+     * settles the matching rows first and counts them, rather than scanning every match.
      * @param entity the target entity
      * @param q the filter
      * @return the count
      */
-    count<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: O): QuerierResult<W, number>;
+    /**
+     * whether any record matches the given filter - a count capped at one row, so the engine stops at
+     * the first match instead of scanning every other one.
+     * @param entity the target entity
+     * @param q the filter
+     * @return whether anything matched
+     */
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: O): QuerierResult<W, boolean>;
+    /**
+     * updates a record partially.
+     * @param entity the entity to persist on
+     * @param id the primary key of the record to be updated
+     * @param payload the data to be persisted
+     * @return the number of affected records
+     */
+    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    /**
+     * updates many records partially.
+     * @param entity the entity to persist on
+     * @param q the criteria to look for the records
+     * @param payload the data to be persisted
+     * @return the number of affected records
+     */
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    /**
+     * delete or SoftDelete a record.
+     * @param entity the entity to persist on
+     * @param id the primary key of the record
+     * @return the number of affected records
+     */
+    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: DO): QuerierResult<W, number>;
+    /**
+     * delete or SoftDelete records.
+     * @param entity the entity to persist on
+     * @param q the criteria to look for the records
+     * @return the number of affected records
+     */
+    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: DO): QuerierResult<W, number>;
+}
+/**
+ * A `querier` allows to interact with the datasource to perform persistence operations on any entity.
+ */
+export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions> {
+    /**
+     * streams the records matching the given search parameters as an async iterable.
+     * Does not fill relations or fire lifecycle hooks - designed for high-performance
+     * bulk reads (ETL, exports, migrations).
+     * @param entity the target entity
+     * @param q the criteria options
+     * @return an async iterable of records
+     */
+    findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never>(entity: Type<E>, q: QueryStreamProjected<E, S, V, X, P>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P>>;
     /**
      * Insert a single record and return its ID (provided, `onInsert`-generated, or
      * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
@@ -78,22 +131,6 @@ export interface UniversalQuerier {
      * @return the IDs
      */
     insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
-    /**
-     * updates a record partially.
-     * @param entity the entity to persist on
-     * @param id the primary key of the record to be updated
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
-    updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * updates many records partially.
-     * @param entity the entity to persist on
-     * @param q the criteria to look for the records
-     * @param payload the data to be persisted
-     * @return the number of affected records
-     */
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Insert or update a record based on the conflict paths.
      * @param entity the entity to persist on
@@ -124,20 +161,6 @@ export interface UniversalQuerier {
      * @return the IDs
      */
     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
-     * @param id the primary key of the record
-     * @return the number of affected records
-     */
-    deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
-    /**
-     * delete or SoftDelete records.
-     * @param entity the entity to persist on
-     * @param q the criteria to look for the records
-     * @return the number of affected records
-     */
-    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.
@@ -151,4 +174,18 @@ export interface UniversalQuerier {
      * @return the aggregate results
      */
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
+    /**
+     * How many rows the engine's own statistics say the table holds, without reading one: Postgres'
+     * `pg_class.reltuples`, CockroachDB's table statistics, MySQL/MariaDB's `information_schema`,
+     * MongoDB's `estimatedDocumentCount`. For a table too big to {@link count} cheaply.
+     *
+     * The whole table, and only ever approximately. It takes no filter because none of those sources
+     * can answer one, which also puts soft-deleted rows and every entity `filters` inside the number.
+     * It is as stale as the last `ANALYZE`/autovacuum (Postgres reports nothing at all until the
+     * first one, which reads here as `0`), and a table SQLite can answer for does not exist - it
+     * throws there rather than quietly running the scan this exists to avoid.
+     * @param entity the target entity
+     * @return the estimated number of rows
+     */
+    estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
 }

package/dist/type/wire.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The envelope a wire response wraps its result in.
+ */
+export type RequestSuccessResponse<E> = {
+    data: E;
+    count?: number;
+};
+/**
+ * A {@link RequestSuccessResponse} whose `count` is always present - what `findManyAndCount` sends.
+ */
+export type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {
+    count: number;
+};
+/**
+ * Which side of the wire a querier sits on. A server querier hands the result back directly, a
+ * client one hands back the envelope its transport wrapped it in.
+ */
+export type QuerierTransport = 'server' | 'client';
+/**
+ * A querier method's result on the given transport, so one signature serves both:
+ * `QuerierResult<'server', User[]>` is `Promise<User[]>` and `QuerierResult<'client', User[]>` is
+ * `Promise<RequestSuccessResponse<User[]>>`. Indexing a map by the transport is what stands in for
+ * the higher-kinded wrapper TypeScript cannot express, and it resolves away: errors and hovers show
+ * the `Promise<User[]>` it picked, never this indirection.
+ */
+export type QuerierResult<W extends QuerierTransport, T> = {
+    server: Promise<T>;
+    client: Promise<RequestSuccessResponse<T>>;
+}[W];
+/**
+ * `findManyAndCount`'s result: the one shape the transports disagree on past the envelope, a tuple
+ * on the server against a counted envelope on the client.
+ */
+export type QuerierCountedResult<W extends QuerierTransport, T> = {
+    server: Promise<[T[], number]>;
+    client: Promise<RequestCountedSuccessResponse<T[]>>;
+}[W];

package/dist/type/wire.js

@@ -0,0 +1 @@
+export {};

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

@@ -108,6 +108,12 @@ export type ParsedGroupEntry = {
  * through to field filtering and emit a condition on a `$size` *column*.
  */
 export declare function parseRelationSize(val: unknown): number | QuerySizeComparisonOps | undefined;
+/**
+ * The direction a `$sort` orders a to-many relation by its size, or `undefined` when the value is a
+ * map of the relation's own fields (which only a to-one can be ordered by). Mirrors
+ * {@link parseRelationSize}, the same clause spelled for a filter rather than an ordering.
+ */
+export declare function parseSortByCount(val: unknown): unknown;
 /**
  * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.

package/dist/util/dialect.util.js

@@ -290,6 +290,21 @@ export function parseRelationSize(val) {
     }
     return val.$size;
 }
+/**
+ * The direction a `$sort` orders a to-many relation by its size, or `undefined` when the value is a
+ * map of the relation's own fields (which only a to-one can be ordered by). Mirrors
+ * {@link parseRelationSize}, the same clause spelled for a filter rather than an ordering.
+ */
+export function parseSortByCount(val) {
+    if (!val || typeof val !== 'object' || !('$count' in val)) {
+        return undefined;
+    }
+    const siblings = getKeys(val).filter((key) => key !== '$count');
+    if (siblings.length) {
+        throw new TypeError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
+    }
+    return val.$count;
+}
 /**
  * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.

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

@@ -9,6 +9,15 @@ export type RelationRequestSummary<E> = {
  * the one field it reads, so it answers for a relation being declared as well as for a resolved one.
  */
 export declare function isToManyRelation(relation: Pick<RelationMeta, 'cardinality'>): boolean;
+/**
+ * The column holding the parent's id: a junction's own for a relation that goes through one, the
+ * child's foreign key otherwise. The two are spelled from opposite ends - `local` names a column of
+ * the table the relation is declared to write, `foreign` a column of the other one - and getting
+ * that backwards reads a real column of the wrong table, so it is answered once here.
+ */
+export declare function parentKeyColumn(relOpts: Pick<RelationMeta, 'references' | 'through'>): string;
+/** The column on a junction table holding the target's id, the other half of {@link parentKeyColumn}. */
+export declare function targetKeyColumn(relOpts: Pick<RelationMeta, 'references'>): string;
 /**
  * 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

package/dist/util/relationQuery.util.js

@@ -7,6 +7,19 @@ import { getKeys, someKey } from './object.util.js';
 export function isToManyRelation(relation) {
     return relation.cardinality === '1m' || relation.cardinality === 'mm';
 }
+/**
+ * The column holding the parent's id: a junction's own for a relation that goes through one, the
+ * child's foreign key otherwise. The two are spelled from opposite ends - `local` names a column of
+ * the table the relation is declared to write, `foreign` a column of the other one - and getting
+ * that backwards reads a real column of the wrong table, so it is answered once here.
+ */
+export function parentKeyColumn(relOpts) {
+    return relOpts.through ? relOpts.references[0].local : relOpts.references[0].foreign;
+}
+/** The column on a junction table holding the target's id, the other half of {@link parentKeyColumn}. */
+export function targetKeyColumn(relOpts) {
+    return relOpts.references[1].local;
+}
 /**
  * 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

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.36.1",
+  "version": "0.37.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -130,7 +130,7 @@
   "devDependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
-    "@libsql/client": "^0.17.4",
+    "@libsql/client": "^0.18.0",
     "@neondatabase/serverless": "^1.1.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/core": "^12.0.1",
@@ -143,9 +143,9 @@
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
-    "mariadb": "^3.5.3",
+    "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
-    "mysql2": "^3.24.2",
+    "mysql2": "^3.24.3",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",