uql-orm 0.31.2 → 0.31.3

package/dist/nestjs/uqlModule.d.ts

@@ -30,6 +30,11 @@ export type UqlModuleAsyncOptions<Req = unknown> = UqlModuleCommon<Req> & {
     /** Providers to inject into `useFactory`. */
     readonly inject?: FactoryProvider['inject'];
 };
+/**
+ * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
+ * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
+ * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
+ */
 export declare class UqlModule {
     /** Configure with an already-built pool. */
     static forRoot<Req = unknown>({ pool, global, getContext }: UqlModuleOptions<Req>): DynamicModule;

package/dist/nestjs/uqlModule.js

@@ -43,11 +43,6 @@ import { UqlContextInterceptor } from './uqlContextInterceptor.js';
  * does not redirect UQL internals.
  */
 export const UQL_QUERIER_POOL = Symbol('UQL_QUERIER_POOL');
-/**
- * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
- * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
- * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
- */
 /**
  * Ends the pool when Nest shuts down.
  *
@@ -66,6 +61,11 @@ class UqlPoolLifecycle {
         return this.pool.end();
     }
 }
+/**
+ * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
+ * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
+ * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
+ */
 let UqlModule = (() => {
     let _classDecorators = [Module({})];
     let _classDescriptor;

package/dist/querier/abstractQuerier.d.ts

@@ -23,11 +23,13 @@ export declare abstract class AbstractQuerier implements Querier {
     private validateProjectionQueryRecursive;
     /**
      * Resolves `[entity, query, opts]` for the dual call pattern: `(entity, q, opts)` (entity argument)
-     * vs `(query, opts)` (entity via the query's `$entity` field).
+     * vs `(query, opts)` (entity via the query's `$entity` field). Generic in the query `Q` because it
+     * only ever reads `$entity`: pinning it to one statement's shape made every caller launder its own
+     * through a cast, which is how a read query's `$sort` used to reach a write's.
      */
-    protected resolveEntityQuery<E extends object>(entityOrQuery: Type<E> | (QuerySearch<E> & {
+    protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
         $entity: Type<E>;
-    }), maybeQueryOrOpts?: QuerySearch<E> | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, QuerySearch<E>, QueryOptions | undefined];
+    }), maybeQueryOrOpts?: Q | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, Q, QueryOptions | undefined];
     findOneById<E extends object>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     /**
      * Find a single record matching the query.

package/dist/querier/abstractQuerier.js

@@ -65,7 +65,9 @@ export class AbstractQuerier {
     }
     /**
      * Resolves `[entity, query, opts]` for the dual call pattern: `(entity, q, opts)` (entity argument)
-     * vs `(query, opts)` (entity via the query's `$entity` field).
+     * vs `(query, opts)` (entity via the query's `$entity` field). Generic in the query `Q` because it
+     * only ever reads `$entity`: pinning it to one statement's shape made every caller launder its own
+     * through a cast, which is how a read query's `$sort` used to reach a write's.
      */
     resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         if (typeof entityOrQuery === 'function' && entityOrQuery.prototype) {

package/dist/type/query.d.ts

@@ -36,7 +36,9 @@ export type QuerySelectOptions = {
     autoPrefixAlias?: boolean;
 };
 /**
- * Query field selection - `{ name: true }` whitelists specific fields.
+ * Query field selection - `{ name: true }` whitelists specific fields. Fields only: a relation is a
+ * sub-query rather than a projection flag, and a whitelist naming one could not say whether the
+ * scalars come with it. Relations go in `$populate`.
  */
 export type QuerySelect<E> = {
     [K in FieldKey<E>]?: BooleanLike;
@@ -116,17 +118,27 @@ export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
  * Accepted value for a field in `$sort` - either a direction or a vector similarity search.
  */
 export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
+/**
+ * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order
+ * it by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
+ */
+type ToOneRelationKey<E> = {
+    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
+}[RelationKey<E>];
 /**
  * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
  * like `QueryWhereMap`), relation sort via nested objects, and vector similarity search on
- * `number[]` fields.
+ * `number[]` fields. `Vector` is what confines a vector search to the level the statement ranks:
+ * the queried entity. A relation of it is joined in one row at a time, so there is nothing to rank
+ * there - the SQL dialects throw, and MongoDB would quietly drop it, so this is its only guard.
+ *
+ * One mapped type over the three key sets rather than three intersected. The sets are disjoint - a
+ * JSON path is dotted, and a field key cannot also be a relation key - and an assignability check
+ * against an intersection is repeated per constituent, which made this the single most expensive
+ * type in the package to check.
  */
 export type QuerySortMap<E, Vector extends boolean = true> = {
-    [K in FieldKey<E>]?: Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
-} & {
-    [P in JsonFieldPaths<E>]?: QuerySortDirection;
-} & {
-    [K in RelationKey<E> as IsMany<E[K]> extends true ? never : K]?: QuerySortMap<RelationTarget<E[K]>, false>;
+    [K in FieldKey<E> | JsonFieldPaths<E> | ToOneRelationKey<E>]?: K extends RelationKey<E> ? QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };
 /**
  * pager options.
@@ -153,17 +165,16 @@ export type QueryFilter<E> = {
 };
 /**
  * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the rows they
- * picked before writing, so the page is portable rather than MySQL-only.
- *
- * `$sort` excludes vector search here for the reason `$lock` is declared on {@link Query} instead:
- * a vector search ranks rows into a projected distance column, and only a SELECT has a projection
- * list to hold one. Passing `QuerySortMap` its `Vector = false` is what keeps it off these.
+ * picked with a SELECT before writing, so the page is portable rather than MySQL-only - and so a
+ * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the
+ * projection list to hold the distance. `$lock` is the clause that stays off these, declared on
+ * {@link Query} instead.
  */
 export type QuerySearch<E> = QueryFilter<E> & {
     /**
      * sorting options.
      */
-    $sort?: QuerySortMap<E, false>;
+    $sort?: QuerySortMap<E>;
 } & QueryPager;
 /**
  * query options.
@@ -243,3 +254,4 @@ export type QueryUpdateResult = {
      */
     created?: boolean;
 };
+export {};

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, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.31.2",
+  "version": "0.31.3",
   "type": "module",
   "engines": {
     "node": ">=24"