uql-orm 0.74.1 → 0.76.0

package/dist/browser/uql-browser.min.js

@@ -1,4 +1,4 @@
-var p=[];function y(e){for(let r of p)r(e)}function _(e){p.push(e);let r=p.length-1;return()=>{p.splice(r,1)}}var S=["$select","$populate","$exclude","$where","$sort"],E=["$count"],T=["$skip","$limit"],f=["$candidates"],O=["$distinct"],v=["$lock",...E,...f];var b=Symbol("rawValue"),W=Symbol("rawAlias");function c(e){return e?Object.keys(e):[]}function C(e){if(typeof e!=="object"||e===null)return!0;if(Array.isArray(e))return!1;let r=Object.getPrototypeOf(e);return r!==Object.prototype&&r!==null}var Y=new Set([...S,...E,...T,...f,...O,"hardDelete","count"]);function i(e){if(!e)return"";let r=new URLSearchParams;for(let n of c(e)){let o=e[n];if(o===void 0)continue;r.append(n,typeof o==="object"&&o!==null?u(o):String(o))}let t=r.toString();return t?`?${t}`:""}function u(e){return JSON.stringify(e,(r,t)=>{if(typeof t!=="object"||t===null)return t;if(b in t)throw TypeError("raw SQL cannot travel over HTTP: what leaves the browser is JSON");if(t instanceof ArrayBuffer||ArrayBuffer.isView(t))throw TypeError("binary cannot travel over HTTP: what leaves the browser is JSON");return t})}class K extends Error{status;constructor(e,r){super(e);this.status=r;this.name="RequestError"}}function R(e,r){return a(e,{method:"get"},r)}function h(e,r,t){return a(e,{method:"post",body:u(r)},t)}function x(e,r,t){return a(e,{method:"patch",body:u(r)},t)}function Q(e,r,t){return a(e,{method:"put",body:u(r)},t)}function g(e,r){return a(e,{method:"delete"},r)}function k(e,r,t){return a(e,{method:"QUERY",body:u(r)},t)}function a(e,r,t){if(y({phase:"start",opts:t}),r.headers={accept:"application/json","content-type":"application/json",...t?.headers},t?.signal)r.signal=t.signal;return fetch(e,r).then((n)=>n.json().then((o)=>{if(n.status>=200&&n.status<300)return y({phase:"success",opts:t}),o;let P=o,l={message:P?.error?.message??n.statusText,code:P?.error?.code??n.status};throw y({phase:"error",error:l,opts:t}),new K(l.message,l.code)})).finally(()=>{y({phase:"complete",opts:t})})}function U(e){let r=e.charAt(0).toLowerCase();for(let t=1;t<e.length;++t)r+=e[t]===e[t].toUpperCase()?"-"+e[t].toLowerCase():e[t];return r}var s={findMany:{method:"GET",path:""},findOne:{method:"GET",path:"/one"},count:{method:"GET",path:"/count"},findOneById:{method:"GET",path:"/:id"},insertOne:{method:"POST",path:""},insertMany:{method:"POST",path:"/many"},saveOne:{method:"PUT",path:""},saveMany:{method:"PUT",path:"/many"},updateMany:{method:"PATCH",path:""},updateOneById:{method:"PATCH",path:"/:id"},deleteOneById:{method:"DELETE",path:"/:id"},deleteMany:{method:"DELETE",path:""}},V=c(s),re=new Map(V.filter((e)=>s[e].method==="GET"&&s[e].path!=="/:id").map((e)=>[s[e].path,e]));function j(e){return U(e.name)}function w(e,r){if(!C(r))throw TypeError(`'${e.name}' was addressed by an id object, which the HTTP route cannot carry.`);return String(r)}class m{basePath;defaults;constructor(e,r={}){this.basePath=e;this.defaults=r}async findOneById(e,r,t,n){let o=this.getBasePath(e),d=i(t);return R(`${o}/${w(e,r)}${d}`,this.buildOptions(n))}findOne(e,r,t){return this.read(`${this.getBasePath(e)}${s.findOne.path}`,r,t)}findMany(e,r,t){let n={...r};if(t?.count)n.count=!0;return this.read(this.getBasePath(e),n,t)}async findManyAndCount(e,r,t){let n=await this.findMany(e,r,{...t,count:!0});if(typeof n.count!=="number")throw TypeError("findManyAndCount response has an invalid count");return{...n,count:n.count}}count(e,r,t){return this.read(`${this.getBasePath(e)}${s.count.path}`,r,t)}async exists(e,r,t){let n=await this.count(e,{...r,$limit:1},t);return{...n,data:n.data>0}}insertOne(e,r,t){let n=this.getBasePath(e);return h(n,r,this.buildOptions(t))}insertMany(e,r,t){let n=this.getBasePath(e);return h(`${n}${s.insertMany.path}`,r,this.buildOptions(t))}async updateOneById(e,r,t,n){let o=this.getBasePath(e);return x(`${o}/${w(e,r)}`,t,this.buildOptions(n))}updateMany(e,r,t,n){let o=this.getBasePath(e),d=i(r);return x(`${o}${d}`,t,this.buildOptions(n))}saveOne(e,r,t){let n=this.getBasePath(e);return Q(n,r,this.buildOptions(t))}saveMany(e,r,t){let n=this.getBasePath(e);return Q(`${n}${s.saveMany.path}`,r,this.buildOptions(t))}async deleteOneById(e,r,t={}){let n=this.getBasePath(e),o=t.hardDelete?i({hardDelete:t.hardDelete}):"";return g(`${n}/${w(e,r)}${o}`,this.buildOptions(t))}deleteMany(e,r,t={}){let n=this.getBasePath(e),o=i(t.hardDelete?{...r,hardDelete:t.hardDelete}:r);return g(`${n}${o}`,this.buildOptions(t))}getBasePath(e){return`${this.basePath}/${(this.defaults.entityPath??j)(e)}`}read(e,r,t){if(this.defaults.readMethod==="QUERY")return k(e,r??{},this.buildOptions(t));return R(`${e}${i(r)}`,this.buildOptions(t))}buildOptions(e){if(!this.defaults.headers&&!e?.headers)return e;return{...e,headers:{...this.defaults.headers,...e?.headers}}}}var q={getQuerier:()=>new m("/api")};function de(e){q=e}function F(){return q}function pe(){return F().getQuerier()}export{m as HttpQuerier,K as RequestError,R as get,pe as getQuerier,F as getQuerierPool,y as notify,_ as on,x as patch,h as post,Q as put,k as query,g as remove,de as setQuerierPool};
+var p=[];function y(e){for(let r of p)r(e)}function _(e){p.push(e);let r=p.length-1;return()=>{p.splice(r,1)}}var P=["$select","$populate","$exclude","$where","$sort"],E=["$count"],T=["$skip","$limit"],f=["$candidates"],O=["$distinct"],v=["$lock",...E,...f];var b=Symbol("rawValue"),W=Symbol("rawAlias");function c(e){return e?Object.keys(e):[]}function C(e){if(typeof e!=="object"||e===null)return!0;if(Array.isArray(e))return!1;let r=Object.getPrototypeOf(e);return r!==Object.prototype&&r!==null}var Y=new Set([...P,...E,...T,...f,...O,"hardDelete","count"]);function i(e){if(!e)return"";let r=new URLSearchParams;for(let n of c(e)){let o=e[n];if(o===void 0)continue;r.append(n,typeof o==="object"&&o!==null?u(o):String(o))}let t=r.toString();return t?`?${t}`:""}function u(e){return JSON.stringify(e,(r,t)=>{if(typeof t!=="object"||t===null)return t;if(b in t)throw TypeError("raw SQL cannot travel over HTTP: what leaves the browser is JSON");if(t instanceof ArrayBuffer||ArrayBuffer.isView(t))throw TypeError("binary cannot travel over HTTP: what leaves the browser is JSON");return t})}class K extends Error{status;constructor(e,r){super(e);this.status=r;this.name="RequestError"}}function R(e,r){return a(e,{method:"get"},r)}function h(e,r,t){return a(e,{method:"post",body:u(r)},t)}function x(e,r,t){return a(e,{method:"patch",body:u(r)},t)}function Q(e,r,t){return a(e,{method:"put",body:u(r)},t)}function g(e,r){return a(e,{method:"delete"},r)}function k(e,r,t){return a(e,{method:"QUERY",body:u(r)},t)}function a(e,r,t){if(y({phase:"start",opts:t}),r.headers={accept:"application/json","content-type":"application/json",...t?.headers},t?.signal)r.signal=t.signal;return fetch(e,r).then((n)=>n.json().then((o)=>{if(n.status>=200&&n.status<300)return y({phase:"success",opts:t}),o;let S=o,l={message:S?.error?.message??n.statusText,code:S?.error?.code??n.status};throw y({phase:"error",error:l,opts:t}),new K(l.message,l.code)})).finally(()=>{y({phase:"complete",opts:t})})}function U(e){let r=e.charAt(0).toLowerCase();for(let t=1;t<e.length;++t)r+=e[t]===e[t].toUpperCase()?"-"+e[t].toLowerCase():e[t];return r}var s={findMany:{method:"GET",path:""},findOne:{method:"GET",path:"/one"},count:{method:"GET",path:"/count"},findOneById:{method:"GET",path:"/:id"},insertOne:{method:"POST",path:""},insertMany:{method:"POST",path:"/many"},saveOne:{method:"PUT",path:""},saveMany:{method:"PUT",path:"/many"},updateMany:{method:"PATCH",path:""},updateOneById:{method:"PATCH",path:"/:id"},deleteOneById:{method:"DELETE",path:"/:id"},deleteMany:{method:"DELETE",path:""}},F=c(s),re=new Map(F.filter((e)=>s[e].method==="GET"&&s[e].path!=="/:id").map((e)=>[s[e].path,e]));function j(e){return U(e.name)}function w(e,r){if(!C(r))throw TypeError(`'${e.name}' was addressed by an id object, which the HTTP route cannot carry.`);return String(r)}class m{basePath;defaults;constructor(e,r={}){this.basePath=e;this.defaults=r}async findOneById(e,r,t,n){let o=this.getBasePath(e),d=i(t);return R(`${o}/${w(e,r)}${d}`,this.buildOptions(n))}findOne(e,r,t){return this.read(`${this.getBasePath(e)}${s.findOne.path}`,r,t)}findMany(e,r,t){let n={...r};if(t?.count)n.count=!0;return this.read(this.getBasePath(e),n,t)}async findManyAndCount(e,r,t){let n=await this.findMany(e,r,{...t,count:!0});if(typeof n.count!=="number")throw TypeError("findManyAndCount response has an invalid count");return{...n,count:n.count}}count(e,r,t){return this.read(`${this.getBasePath(e)}${s.count.path}`,r,t)}async exists(e,r,t){let n=await this.count(e,{...r,$limit:1},t);return{...n,data:n.data>0}}insertOne(e,r,t){let n=this.getBasePath(e);return h(n,r,this.buildOptions(t))}insertMany(e,r,t){let n=this.getBasePath(e);return h(`${n}${s.insertMany.path}`,r,this.buildOptions(t))}async updateOneById(e,r,t,n){let o=this.getBasePath(e);return x(`${o}/${w(e,r)}`,t,this.buildOptions(n))}updateMany(e,r,t,n){let o=this.getBasePath(e),d=i(r);return x(`${o}${d}`,t,this.buildOptions(n))}saveOne(e,r,t){let n=this.getBasePath(e);return Q(n,r,this.buildOptions(t))}saveMany(e,r,t){let n=this.getBasePath(e);return Q(`${n}${s.saveMany.path}`,r,this.buildOptions(t))}async deleteOneById(e,r,t={}){let n=this.getBasePath(e),o=t.hardDelete?i({hardDelete:t.hardDelete}):"";return g(`${n}/${w(e,r)}${o}`,this.buildOptions(t))}deleteMany(e,r,t={}){let n=this.getBasePath(e),o=i(t.hardDelete?{...r,hardDelete:t.hardDelete}:r);return g(`${n}${o}`,this.buildOptions(t))}getBasePath(e){return`${this.basePath}/${(this.defaults.entityPath??j)(e)}`}read(e,r,t){if(this.defaults.readMethod==="QUERY")return k(e,r??{},this.buildOptions(t));return R(`${e}${i(r)}`,this.buildOptions(t))}buildOptions(e){if(!this.defaults.headers&&!e?.headers)return e;return{...e,headers:{...this.defaults.headers,...e?.headers}}}}var q={getQuerier:()=>new m("/api")};function de(e){q=e}function V(){return q}function pe(){return V().getQuerier()}export{m as HttpQuerier,K as RequestError,R as get,pe as getQuerier,V as getQuerierPool,y as notify,_ as on,x as patch,h as post,Q as put,k as query,g as remove,de as setQuerierPool};
 
-//# debugId=5397AE2C0FC782D564756E2164756E21
+//# debugId=3410F618088BC65664756E2164756E21
 //# sourceMappingURL=uql-browser.min.js.map

package/dist/browser/uql-browser.min.js.map

@@ -3,7 +3,7 @@
   "sources": ["../../src/browser/http/bus.ts", "../../src/type/query.ts", "../../src/type/queryRaw.ts", "../../src/util/object.util.ts", "../../src/http/query.ts", "../../src/browser/http/http.ts", "../../src/util/string.util.ts", "../../src/http/contract.ts", "../../src/browser/querier/httpQuerier.ts", "../../src/browser/options.ts"],
   "sourcesContent": [
     "import type { RequestCallback, RequestNotification } from '../type/index.js';\n\nconst subscriptors: RequestCallback[] = [];\n\nexport function notify(notification: RequestNotification): void {\n  for (const subscriptor of subscriptors) {\n    subscriptor(notification);\n  }\n}\n\nexport function on(cb: RequestCallback): () => void {\n  subscriptors.push(cb);\n  const index = subscriptors.length - 1;\n  return (): void => {\n    subscriptors.splice(index, 1);\n  };\n}\n",
-    "import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';\nimport type { QueryLock } from './queryLock.js';\nimport type { QueryRaw } from './queryRaw.js';\nimport type { QueryWhere } from './queryWhere.js';\nimport type { BooleanLike, Except, IsMany, PrimaryKey } from './utility.js';\nimport type { QueryVectorQuery, QueryVectorSearch } from './vector.js';\n\nexport type QueryOptions = {\n  /**\n   * Toggle named entity filters for this query. `false` disables all filters;\n   * `{ softDelete: false }` disables one; `{ myFilter: true }` force-enables a `default: false` filter.\n   * Security filters cannot be disabled here.\n   */\n  filters?: false | Record<string, boolean>;\n  /**\n   * Delete only: physically remove rows instead of soft-deleting, ignoring the soft-delete filter so\n   * already-deleted rows are removed too. No effect on entities without a soft-delete field.\n   */\n  hardDelete?: boolean;\n  /**\n   * `updateMany`/`deleteMany` only: address every row of the table on purpose. Without it a bulk write\n   * that names none - no `$where` and no `$limit` - is refused, since a forgotten filter and the whole\n   * table look alike. The entity's own filters never count as naming one.\n   */\n  unfiltered?: boolean;\n  /**\n   * prefix the query with this.\n   */\n  prefix?: string;\n  /**\n   * automatically infer the prefix for the query.\n   */\n  autoPrefix?: boolean;\n};\n\n/**\n * Field selection - `{ name: true }` whitelists fields; relations go in `$populate`. Declared over\n * `F extends keyof E`, like every map keyed by an entity's members, so each key stays linked to its\n * property and an editor rename reaches it. `F` is also how a projection passes its captured key set.\n */\nexport type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {\n  [K in F]?: V;\n};\n\n/**\n * Accepted `$select` value: a field map, or raw SQL projections built with `raw()`\n * (e.g. ``[raw`*`, raw`LOG10(points)`.as('score')]``). The raw form is SQL-only.\n */\nexport type QuerySelectValue<E, Raw = QueryRaw> = QuerySelect<E> | readonly Raw[];\n\n/**\n * Fields to exclude from the query result - `{ name: true }` blacklists fields.\n * Mutually exclusive with positive field selections in `$select`.\n */\nexport type QueryExclude<E> = QuerySelect<E>;\n\n/**\n * relation population map.\n */\nexport type QueryPopulate<E, Raw = QueryRaw, R extends keyof E = RelationKey<E>> = {\n  [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K], Raw>;\n};\n\n/**\n * The key a read carries its relation tallies under. One spelling for the type and the runtime that\n * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.\n */\nexport const COUNT_RESULT_KEY = '_count';\n\n/**\n * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow\n * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes\n * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.\n */\nexport type QueryCount<E, Raw = QueryRaw, R extends keyof E = ToManyRelationKey<E>> = {\n  [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>, Raw>;\n};\n\n/**\n * query conflict paths - subset of field keys used to detect upsert conflicts.\n */\nexport type QueryConflictPaths<E> = QuerySelect<E, FieldKey<E>, true>;\n\n/**\n * Options to populate a relation declared as `V`, by its cardinality.\n */\nexport type QueryPopulateRelationOptions<V, Raw = QueryRaw> =\n  IsMany<V> extends true\n    ? RelationQuery<RelationTarget<V>, Raw>\n    : QueryUnique<RelationTarget<V>, Raw> & { $required?: boolean };\n\n/**\n * The per-request context parameterized filters read, set with `withContext(ctx, cb)`. An interface,\n * so its keys can be typed once: `declare module 'uql-orm' { interface UqlContext { tenantId: number } }`.\n */\nexport interface UqlContext {\n  [key: string]: unknown;\n}\n\n/**\n * A filter's `$where` fragment: a plain fragment, or a function of the ambient {@link UqlContext}.\n * Return `undefined` when the condition can't resolve (see {@link FilterOptions.onMissing}).\n */\nexport type FilterWhere<E> = QueryWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);\n\n/**\n * What to do when a filter's condition returns `undefined`. `skip` omits it (convenience filters);\n * `throw` fails closed (the default for `security` filters).\n */\nexport type FilterOnMissing = 'skip' | 'throw';\n\n/**\n * Authoring shape for `@Entity({ filters })` / `@Filter` / `defineFilter`.\n */\nexport type FilterOptions<E = unknown> = {\n  readonly where: FilterWhere<E>;\n  /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */\n  readonly default?: boolean;\n} & (\n  | {\n      readonly security?: false;\n      /** What to do when {@link FilterOptions.where} returns `undefined`. Defaults to `skip`. */\n      readonly onMissing?: FilterOnMissing;\n    }\n  | {\n      /**\n       * Row-level-security filter: always applied (ignores `QueryOptions.filters` bypass) and\n       * AND-merged so a client `$where` on the same field can't override it. It fails closed.\n       */\n      readonly security: true;\n      readonly onMissing?: 'throw';\n    }\n);\n\n/**\n * direction for the sort.\n */\nexport type QuerySortDirection = -1 | 1 | 'asc' | 'desc';\n\n/**\n * Accepted value for a field in `$sort` - either a direction or a vector similarity search.\n */\nexport type QuerySortValue = QuerySortDirection | QueryVectorSearch;\n\n/**\n * Ordering parents by how many rows a to-many relation holds - \"the ten users with the most posts\".\n * The tally is computed per parent as a correlated count, never by loading the rows.\n */\nexport type QuerySortByCount = {\n  $count: QuerySortDirection;\n};\n\n/** The fields of `E` a vector search can rank by. */\ntype VectorFieldKey<E> = { [P in FieldKey<E>]: NonNullable<E[P]> extends readonly number[] ? P : never }[FieldKey<E>];\n\n/**\n * Ordering parents by the row of a to-many nearest a vector, per vector field: its distance is the\n * smallest of theirs. Nothing to `$project`, since no one row of the parent's answers under it. Never\n * where the target has no vector, since an empty map would admit any value at all.\n */\nexport type QuerySortByNearest<E> = [VectorFieldKey<E>] extends [never]\n  ? never\n  : { [P in VectorFieldKey<E>]?: QueryVectorQuery };\n\n/**\n * Ordering by relevance to the `$text` at the root of `$where`, in either direction as any key sorts. The\n * object form also answers it under the name `$project` gives it, most relevant first unless `$order` says.\n */\nexport type QuerySortByText = {\n  $text?: QuerySortDirection | { readonly $project: string; readonly $order?: QuerySortDirection };\n};\n\n/**\n * A row with the value a `$sort` projects under the name its `$project` gives - a vector's distance, or a\n * `$text` relevance - which is not inferred: `(await querier.findMany(Post, q)) as WithProjection<Post, 'score'>[]`.\n */\nexport type WithProjection<E, K extends string> = E & Record<K, number>;\n\n/**\n * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count` or nearest row, a vector\n * distance, or - where `Root` says it sorts the queried entity itself, not a relation's rows - a `$text`\n * relevance or a distance it projects. One mapped type over the key sets: an intersection is checked once\n * per member, which made this the costliest.\n */\nexport type QuerySortMap<E, Root extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {\n  [P in K]?: P extends RelationKey<E>\n    ? // A to-many has no single value to order by, so what it offers instead is its size or nearest row.\n      IsMany<E[P]> extends true\n      ? QuerySortByCount | QuerySortByNearest<RelationTarget<E[P]>>\n      : QuerySortMap<RelationTarget<E[P]>, false>\n    : NonNullable<E[P]> extends readonly number[]\n      ? Root extends true\n        ? QuerySortValue\n        : QuerySortDirection | QueryVectorQuery\n      : QuerySortDirection;\n} & ([JsonFieldPaths<E>] extends [never] ? unknown : { [P in JsonFieldPaths<E>]?: QuerySortDirection }) &\n  (Root extends true ? QuerySortByText : unknown);\n\n/**\n * pager options.\n */\nexport type QueryPager = {\n  /**\n   * Index from where start the search\n   */\n  $skip?: number;\n\n  /**\n   * Max number of records to retrieve\n   */\n  $limit?: number;\n};\n\n/**\n * Which rows a statement addresses.\n */\nexport type QueryFilter<E, Raw = QueryRaw> = {\n  /**\n   * filtering options.\n   */\n  $where?: QueryWhere<E, Raw>;\n};\n\n/**\n * A filter plus the page `count` takes. No `$sort`: ordering picks *which* rows a page holds, never\n * how many, so a count that accepted one would promise an influence it cannot have.\n */\nexport type QueryPage<E, Raw = QueryRaw> = QueryFilter<E, Raw> & QueryPager;\n\n/**\n * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the\n * rows they address with a SELECT first, so the page is portable rather than MySQL-only, and a\n * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the\n * projection list to hold the distance. `$lock` stays off these, declared on {@link Query} instead.\n */\nexport type QuerySearch<E, Raw = QueryRaw> = QueryPage<E, Raw> & {\n  /**\n   * sorting options.\n   */\n  $sort?: QuerySortMap<E>;\n};\n\n/**\n * query options.\n */\nexport type Query<E, Raw = QueryRaw> = {\n  /**\n   * field selection - `{ name: true }` whitelists fields, or raw SQL projections\n   * (``[raw`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).\n   * Mutually exclusive with `$exclude`.\n   */\n  $select?: QuerySelectValue<E, Raw>;\n\n  /**\n   * relation population options.\n   */\n  $populate?: QueryPopulate<E, Raw>;\n\n  /**\n   * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.\n   */\n  $count?: QueryCount<E, Raw>;\n\n  /**\n   * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.\n   * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept\n   * regardless, since subtracting them would leave the relation unfilled.\n   */\n  $exclude?: QueryExclude<E>;\n\n  /**\n   * sorting options, vector similarity search included: a SELECT is the one statement with a\n   * projection list to hold the distance such a search computes.\n   */\n  $sort?: QuerySortMap<E>;\n\n  /**\n   * whether to return only distinct rows.\n   */\n  $distinct?: boolean;\n\n  /**\n   * Lock the rows this query returns, `SELECT ... FOR UPDATE`, inside an open transaction: outside one\n   * it is refused, since the lock would drop before the rows are used. SQL only, and not the SQLite family.\n   */\n  $lock?: QueryLock;\n\n  /**\n   * How many candidates an ANN index explores before ranking a vector search, in that index's own units\n   * (`hnsw.ef_search`, `numCandidates`...); ignored where the search is exact. Postgres needs a transaction.\n   */\n  $candidates?: number;\n\n  // `$where`, `$skip` and `$limit` are declared here rather than intersected in from\n  // {@link QueryFilter} and {@link QueryPager}: an assignability check against an intersection is\n  // repeated per constituent, and every query in a consuming codebase pays that. The two shapes are\n  // pinned together in `queryStatementClauses.test-d.ts` so the copies cannot drift.\n\n  /**\n   * filtering options.\n   */\n  $where?: QueryWhere<E, Raw>;\n\n  /**\n   * Index from where start the search\n   */\n  $skip?: number;\n\n  /**\n   * Max number of records to retrieve\n   */\n  $limit?: number;\n};\n\n/**\n * A {@link Query} as it travels as JSON, which a `raw` SQL fragment cannot: what the browser client takes,\n * and what an RPC contract (tRPC, oRPC, TanStack Start) declares as its input.\n */\nexport type WireQuery<E> = Query<E, never>;\n\n/**\n * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query\n * check alike; `satisfies` keeps them in step with `Query`.\n */\nexport const QUERY_OBJECT_CLAUSES = [\n  '$select',\n  '$populate',\n  '$exclude',\n  '$where',\n  '$sort',\n] as const satisfies readonly (keyof Query<unknown>)[];\n\n/**\n * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,\n * so a `$count` inside one would have no `_count` to land in.\n */\nexport const QUERY_ROOT_OBJECT_CLAUSES = ['$count'] as const satisfies readonly (keyof Query<unknown>)[];\n\nexport const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'] as const satisfies readonly (keyof Query<unknown>)[];\n\n/**\n * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.\n * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows\n * the statement returns, so a relation's own query has nothing to tune.\n */\nexport const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'] as const satisfies readonly (keyof Query<unknown>)[];\n\nexport const QUERY_BOOLEAN_CLAUSES = ['$distinct'] as const satisfies readonly (keyof Query<unknown>)[];\n\n/** The clauses that describe the statement, which a populated relation's own query refuses by name. */\nexport const QUERY_STATEMENT_CLAUSES = [\n  '$lock',\n  ...QUERY_ROOT_OBJECT_CLAUSES,\n  ...QUERY_ROOT_NUMBER_CLAUSES,\n] as const satisfies readonly (keyof Query<unknown>)[];\n\ntype RelationClause = (\n  | typeof QUERY_OBJECT_CLAUSES\n  | typeof QUERY_NUMBER_CLAUSES\n  | typeof QUERY_BOOLEAN_CLAUSES\n)[number];\n\n/**\n * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot\n * drift, and a clause added to {@link Query} stays off it until it joins one of them.\n */\nexport type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, RelationClause> & {\n  $required?: boolean;\n};\n\n/**\n * options to get a single record.\n */\nexport type QueryOne<E, Raw = QueryRaw> = Except<Query<E, Raw>, '$limit'>;\n\n/**\n * options to get an unique record.\n */\nexport type QueryUnique<E, Raw = QueryRaw> = Pick<QueryOne<E, Raw>, '$select' | '$exclude' | '$populate' | '$where'>;\n\n/**\n * The clauses that shape a row, captured as key sets rather than maps: a naked type parameter skips\n * excess-property checks, while a key set fails its own constraint on a typo.\n * @internal\n */\ntype QueryProjection<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E>,\n  Raw = QueryRaw,\n> = {\n  $select?: QuerySelect<E, S, V> | readonly Raw[];\n  $exclude?: QuerySelect<E, X, V>;\n  $populate?: QueryPopulate<E, Raw, P>;\n  // Narrowing the captured names to the to-many ones leaves a to-one relation no key here at all,\n  // so counting one is an excess property rather than a value to check.\n  $count?: QueryCount<E, Raw, C & ToManyRelationKey<E>>;\n};\n\n/**\n * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.\n */\nexport type QueryProjected<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E> = never,\n  Raw = QueryRaw,\n> = Query<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;\n\n/**\n * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.\n */\nexport type QueryOneProjected<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E> = never,\n  Raw = QueryRaw,\n> = QueryOne<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;\n\n/**\n * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every\n * field minus what `$select` or `$exclude` subtracts, plus the populated relations.\n * @internal\n */\ntype ProjectedKeys<E, S, V, X, P> =\n  | ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S)\n  | P;\n\n/**\n * Whether every entry of the captured map says the same thing: all selected, or all subtracted.\n * @internal\n */\ntype IsUniform<V> = [V] extends [true | 1] ? true : [V] extends [false | 0] ? true : false;\n\n/**\n * A find's row: the entity narrowed to what the query projected and populated, so reading anything\n * else does not compile. The entity itself where the projection is raw, absent or not uniform.\n * @example `QueryFindResult<User, 'id' | 'name'>`\n */\nexport type QueryFindResult<\n  E,\n  S extends FieldKey<E> = never,\n  // A whitelist by default, so the hand-written form reads `QueryFindResult<User, 'id' | 'name'>`.\n  V = true,\n  X extends FieldKey<E> = never,\n  P extends RelationKey<E> = never,\n  C extends RelationKey<E> = never,\n> = QueryProjectedRow<E, S, V, X, P, C> & CountedRelations<C>;\n\n/**\n * The `_count` a query asked for, or an inert intersection member when it asked for none - so a read\n * without `$count` keeps exactly the row type it had.\n */\ntype CountedRelations<C extends PropertyKey> = [C] extends [never]\n  ? unknown\n  : { [K in typeof COUNT_RESULT_KEY]: { [R in C]: number } };\n\n/** @internal */\ntype QueryProjectedRow<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E>,\n> = [S | X] extends [never]\n  ? E\n  : IsUniform<V> extends true\n    ? [PopulatedToMany<E, P>] extends [never]\n      ? // `Pick`, not a key remap: an entity keyed by an index signature - a content type defined at\n        // runtime - has `string` for its keys, and a remap keeps no literal one, so every projection\n        // over one came back as `{}`.\n        Pick<E, ProjectedKeys<E, S, V, X, P> & keyof E>\n      : // A populated to-many is always a list, empty where the parent has no children, so it maps\n        // and counts without a guard. Only that promotion needs a second member, and only a query\n        // that populates one pays for it; every other key keeps the modifier the entity declared,\n        // a to-one relation included, since a join that finds no row leaves it absent.\n        Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E> & {\n          [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;\n        }\n    : E;\n\n/** The to-many relations a query populated, which come back as lists rather than as optional ones. */\ntype PopulatedToMany<E, P> = Extract<P, ToManyRelationKey<E>>;\n\n/**\n * stringified query.\n */\nexport type QueryStringified = {\n  [K in keyof Query<unknown>]?: string;\n};\n\n/** What upserting one row reports. `created` is only knowable for a single statement, so a batch has none. */\nexport type QueryUpsertOneResult<E> = {\n  readonly id?: WrittenId<E>;\n  readonly changes?: number;\n  /** Whether the record was created (`true`) or updated (`false`), where the dialect can tell. */\n  readonly created?: boolean;\n};\n\n/**\n * What upserting many rows reports. `ids` is payload-aligned like an insert's, so it zips with the\n * rows that were passed, and carries a composite key as the map naming it.\n */\nexport type QueryUpsertManyResult<E> = {\n  readonly ids: (WrittenId<E> | undefined)[];\n  readonly changes?: number;\n};\n\n/**\n * result of an update operation, as the driver reports it - which is what `run` hands back, where\n * there is no entity to name the ids against. The `QueryUpsert*Result` pair is the entity-level shape.\n */\nexport type QueryUpdateResult = {\n  /**\n   * number of affected records.\n   */\n  changes?: number;\n  /**\n   * the IDs the statement reported, in payload order, `undefined` where it reported none for that\n   * row - a MongoDB upsert names only the documents it inserted. Exact on `'returning'` dialects;\n   * inferred from the driver header on the others (see {@link InsertIdSource}), and absent\n   * altogether when the header reports nothing.\n   */\n  ids?: (PrimaryKey | undefined)[];\n  /**\n   * first inserted ID.\n   */\n  firstId?: PrimaryKey;\n  /**\n   * whether the record was created (`true`) or updated (`false`).\n   * `undefined` when the dialect cannot determine this (e.g. SQLite).\n   */\n  created?: boolean;\n};\n",
+    "import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';\nimport type { QueryLock } from './queryLock.js';\nimport type { QueryRaw } from './queryRaw.js';\nimport type { QueryWhere } from './queryWhere.js';\nimport type { BooleanLike, Except, IsMany, PrimaryKey } from './utility.js';\nimport type { QueryVectorQuery, QueryVectorSearch } from './vector.js';\n\nexport type QueryOptions = {\n  /**\n   * Toggle named entity filters for this query. `false` disables all filters;\n   * `{ softDelete: false }` disables one; `{ myFilter: true }` force-enables a `default: false` filter.\n   * Security filters cannot be disabled here.\n   */\n  filters?: false | Record<string, boolean>;\n  /**\n   * Delete only: physically remove rows instead of soft-deleting, ignoring the soft-delete filter so\n   * already-deleted rows are removed too. No effect on entities without a soft-delete field.\n   */\n  hardDelete?: boolean;\n  /**\n   * `updateMany`/`deleteMany` only: address every row of the table on purpose. Without it a bulk write\n   * that names none - no `$where` and no `$limit` - is refused, since a forgotten filter and the whole\n   * table look alike. The entity's own filters never count as naming one.\n   */\n  unfiltered?: boolean;\n  /**\n   * prefix the query with this.\n   */\n  prefix?: string;\n  /**\n   * automatically infer the prefix for the query.\n   */\n  autoPrefix?: boolean;\n};\n\n/**\n * Field selection - `{ name: true }` whitelists fields; relations go in `$populate`. Declared over\n * `F extends keyof E`, like every map keyed by an entity's members, so each key stays linked to its\n * property and an editor rename reaches it. `F` is also how a projection passes its captured key set.\n */\nexport type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {\n  [K in F]?: V;\n};\n\n/**\n * Accepted `$select` value: a field map, or raw SQL projections built with `raw()`\n * (e.g. ``[raw`*`, raw`LOG10(points)`.as('score')]``). The raw form is SQL-only.\n */\nexport type QuerySelectValue<E, Raw = QueryRaw> = QuerySelect<E> | readonly Raw[];\n\n/**\n * Fields to exclude from the query result - `{ name: true }` blacklists fields.\n * Mutually exclusive with positive field selections in `$select`.\n */\nexport type QueryExclude<E> = QuerySelect<E>;\n\n/**\n * relation population map.\n */\nexport type QueryPopulate<E, Raw = QueryRaw, R extends keyof E = RelationKey<E>> = {\n  [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K], Raw>;\n};\n\n/**\n * The key a read carries its relation tallies under. One spelling for the type and the runtime that\n * fills it: they sit in different modules, so a drift would type-check and answer `undefined`.\n */\nexport const COUNT_RESULT_KEY = '_count';\n\n/**\n * How many rows each named relation holds per parent, `true` for all of them or a filter to narrow\n * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes\n * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.\n */\nexport type QueryCount<E, Raw = QueryRaw, R extends keyof E = ToManyRelationKey<E>> = {\n  [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>, Raw>;\n};\n\n/**\n * query conflict paths - subset of field keys used to detect upsert conflicts.\n */\nexport type QueryConflictPaths<E> = QuerySelect<E, FieldKey<E>, true>;\n\n/**\n * Options to populate a relation declared as `V`, by its cardinality.\n */\nexport type QueryPopulateRelationOptions<V, Raw = QueryRaw> =\n  IsMany<V> extends true\n    ? RelationQuery<RelationTarget<V>, Raw>\n    : QueryUnique<RelationTarget<V>, Raw> & { $required?: boolean };\n\n/**\n * The per-request context parameterized filters read, set with `withContext(ctx, cb)`. An interface,\n * so its keys can be typed once: `declare module 'uql-orm' { interface UqlContext { tenantId: number } }`.\n */\nexport interface UqlContext {\n  [key: string]: unknown;\n}\n\n/**\n * A filter's `$where` fragment: a plain fragment, or a function of the ambient {@link UqlContext}.\n * Return `undefined` when the condition can't resolve (see {@link FilterOptions.onMissing}).\n */\nexport type FilterWhere<E> = QueryWhere<E> | ((context: UqlContext | undefined) => QueryWhere<E> | undefined);\n\n/**\n * What to do when a filter's condition returns `undefined`. `skip` omits it (convenience filters);\n * `throw` fails closed (the default for `security` filters).\n */\nexport type FilterOnMissing = 'skip' | 'throw';\n\n/**\n * Authoring shape for `@Entity({ filters })` / `@Filter` / `defineFilter`.\n */\nexport type FilterOptions<E = unknown> = {\n  readonly where: FilterWhere<E>;\n  /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */\n  readonly default?: boolean;\n} & (\n  | {\n      readonly security?: false;\n      /** What to do when {@link FilterOptions.where} returns `undefined`. Defaults to `skip`. */\n      readonly onMissing?: FilterOnMissing;\n    }\n  | {\n      /**\n       * Row-level-security filter: always applied (ignores `QueryOptions.filters` bypass) and\n       * AND-merged so a client `$where` on the same field can't override it. It fails closed.\n       */\n      readonly security: true;\n      readonly onMissing?: 'throw';\n    }\n);\n\n/**\n * direction for the sort, and where nulls land in it.\n *\n * Unqualified, each engine has its own answer - Postgres and CockroachDB sort nulls last on `asc`, the\n * rest sort them first - so a placement is the only portable one. Engines with no `NULLS FIRST/LAST`\n * emulate it with a leading term, which no index can serve, which is why it is asked for and never\n * applied by default.\n */\nexport type QuerySortDirection = -1 | 1 | 'asc' | 'desc' | QuerySortNullsDirection;\n\n/** A {@link QuerySortDirection} stating where nulls land. */\nexport type QuerySortNullsDirection = 'ascNullsFirst' | 'ascNullsLast' | 'descNullsFirst' | 'descNullsLast';\n\n/**\n * Accepted value for a field in `$sort` - either a direction or a vector similarity search.\n */\nexport type QuerySortValue = QuerySortDirection | QueryVectorSearch;\n\n/**\n * Ordering parents by how many rows a to-many relation holds - \"the ten users with the most posts\".\n * The tally is computed per parent as a correlated count, never by loading the rows.\n */\nexport type QuerySortByCount = {\n  $count: QuerySortDirection;\n};\n\n/** The fields of `E` a vector search can rank by. */\ntype VectorFieldKey<E> = { [P in FieldKey<E>]: NonNullable<E[P]> extends readonly number[] ? P : never }[FieldKey<E>];\n\n/**\n * Ordering parents by the row of a to-many nearest a vector, per vector field: its distance is the\n * smallest of theirs. Nothing to `$project`, since no one row of the parent's answers under it. Never\n * where the target has no vector, since an empty map would admit any value at all.\n */\nexport type QuerySortByNearest<E> = [VectorFieldKey<E>] extends [never]\n  ? never\n  : { [P in VectorFieldKey<E>]?: QueryVectorQuery };\n\n/**\n * Ordering by relevance to the `$text` at the root of `$where`, in either direction as any key sorts. The\n * object form also answers it under the name `$project` gives it, most relevant first unless `$order` says.\n */\nexport type QuerySortByText = {\n  $text?: QuerySortDirection | { readonly $project: string; readonly $order?: QuerySortDirection };\n};\n\n/**\n * A row with the value a `$sort` projects under the name its `$project` gives - a vector's distance, or a\n * `$text` relevance - which is not inferred: `(await querier.findMany(Post, q)) as WithProjection<Post, 'score'>[]`.\n */\nexport type WithProjection<E, K extends string> = E & Record<K, number>;\n\n/**\n * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count` or nearest row, a vector\n * distance, or - where `Root` says it sorts the queried entity itself, not a relation's rows - a `$text`\n * relevance or a distance it projects. One mapped type over the key sets: an intersection is checked once\n * per member, which made this the costliest.\n */\nexport type QuerySortMap<E, Root extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {\n  [P in K]?: P extends RelationKey<E>\n    ? // A to-many has no single value to order by, so what it offers instead is its size or nearest row.\n      IsMany<E[P]> extends true\n      ? QuerySortByCount | QuerySortByNearest<RelationTarget<E[P]>>\n      : QuerySortMap<RelationTarget<E[P]>, false>\n    : NonNullable<E[P]> extends readonly number[]\n      ? Root extends true\n        ? QuerySortValue\n        : QuerySortDirection | QueryVectorQuery\n      : QuerySortDirection;\n} & ([JsonFieldPaths<E>] extends [never] ? unknown : { [P in JsonFieldPaths<E>]?: QuerySortDirection }) &\n  (Root extends true ? QuerySortByText : unknown);\n\n/**\n * pager options.\n */\nexport type QueryPager = {\n  /**\n   * Index from where start the search\n   */\n  $skip?: number;\n\n  /**\n   * Max number of records to retrieve\n   */\n  $limit?: number;\n};\n\n/**\n * Which rows a statement addresses.\n */\nexport type QueryFilter<E, Raw = QueryRaw> = {\n  /**\n   * filtering options.\n   */\n  $where?: QueryWhere<E, Raw>;\n};\n\n/**\n * A filter plus the page `count` takes. No `$sort`: ordering picks *which* rows a page holds, never\n * how many, so a count that accepted one would promise an influence it cannot have.\n */\nexport type QueryPage<E, Raw = QueryRaw> = QueryFilter<E, Raw> & QueryPager;\n\n/**\n * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the\n * rows they address with a SELECT first, so the page is portable rather than MySQL-only, and a\n * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the\n * projection list to hold the distance. `$lock` stays off these, declared on {@link Query} instead.\n */\nexport type QuerySearch<E, Raw = QueryRaw> = QueryPage<E, Raw> & {\n  /**\n   * sorting options.\n   */\n  $sort?: QuerySortMap<E>;\n};\n\n/**\n * query options.\n */\nexport type Query<E, Raw = QueryRaw> = {\n  /**\n   * field selection - `{ name: true }` whitelists fields, or raw SQL projections\n   * (``[raw`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).\n   * Mutually exclusive with `$exclude`.\n   */\n  $select?: QuerySelectValue<E, Raw>;\n\n  /**\n   * relation population options.\n   */\n  $populate?: QueryPopulate<E, Raw>;\n\n  /**\n   * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.\n   */\n  $count?: QueryCount<E, Raw>;\n\n  /**\n   * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.\n   * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept\n   * regardless, since subtracting them would leave the relation unfilled.\n   */\n  $exclude?: QueryExclude<E>;\n\n  /**\n   * sorting options, vector similarity search included: a SELECT is the one statement with a\n   * projection list to hold the distance such a search computes.\n   */\n  $sort?: QuerySortMap<E>;\n\n  /**\n   * whether to return only distinct rows.\n   */\n  $distinct?: boolean;\n\n  /**\n   * Lock the rows this query returns, `SELECT ... FOR UPDATE`, inside an open transaction: outside one\n   * it is refused, since the lock would drop before the rows are used. SQL only, and not the SQLite family.\n   */\n  $lock?: QueryLock;\n\n  /**\n   * How many candidates an ANN index explores before ranking a vector search, in that index's own units\n   * (`hnsw.ef_search`, `numCandidates`...); ignored where the search is exact. Postgres needs a transaction.\n   */\n  $candidates?: number;\n\n  // `$where`, `$skip` and `$limit` are declared here rather than intersected in from\n  // {@link QueryFilter} and {@link QueryPager}: an assignability check against an intersection is\n  // repeated per constituent, and every query in a consuming codebase pays that. The two shapes are\n  // pinned together in `queryStatementClauses.test-d.ts` so the copies cannot drift.\n\n  /**\n   * filtering options.\n   */\n  $where?: QueryWhere<E, Raw>;\n\n  /**\n   * Index from where start the search\n   */\n  $skip?: number;\n\n  /**\n   * Max number of records to retrieve\n   */\n  $limit?: number;\n};\n\n/**\n * A {@link Query} as it travels as JSON, which a `raw` SQL fragment cannot: what the browser client takes,\n * and what an RPC contract (tRPC, oRPC, TanStack Start) declares as its input.\n */\nexport type WireQuery<E> = Query<E, never>;\n\n/**\n * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query\n * check alike; `satisfies` keeps them in step with `Query`.\n */\nexport const QUERY_OBJECT_CLAUSES = [\n  '$select',\n  '$populate',\n  '$exclude',\n  '$where',\n  '$sort',\n] as const satisfies readonly (keyof Query<unknown>)[];\n\n/**\n * Object clauses only the statement itself takes: a populated relation's rows keep their declared type,\n * so a `$count` inside one would have no `_count` to land in.\n */\nexport const QUERY_ROOT_OBJECT_CLAUSES = ['$count'] as const satisfies readonly (keyof Query<unknown>)[];\n\nexport const QUERY_NUMBER_CLAUSES = ['$skip', '$limit'] as const satisfies readonly (keyof Query<unknown>)[];\n\n/**\n * Number clauses only the statement itself takes - the numeric mirror of {@link QUERY_ROOT_OBJECT_CLAUSES}.\n * `$candidates` tunes the index behind a vector search, and a vector search only ever ranks the rows\n * the statement returns, so a relation's own query has nothing to tune.\n */\nexport const QUERY_ROOT_NUMBER_CLAUSES = ['$candidates'] as const satisfies readonly (keyof Query<unknown>)[];\n\nexport const QUERY_BOOLEAN_CLAUSES = ['$distinct'] as const satisfies readonly (keyof Query<unknown>)[];\n\n/** The clauses that describe the statement, which a populated relation's own query refuses by name. */\nexport const QUERY_STATEMENT_CLAUSES = [\n  '$lock',\n  ...QUERY_ROOT_OBJECT_CLAUSES,\n  ...QUERY_ROOT_NUMBER_CLAUSES,\n] as const satisfies readonly (keyof Query<unknown>)[];\n\ntype RelationClause = (\n  | typeof QUERY_OBJECT_CLAUSES\n  | typeof QUERY_NUMBER_CLAUSES\n  | typeof QUERY_BOOLEAN_CLAUSES\n)[number];\n\n/**\n * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot\n * drift, and a clause added to {@link Query} stays off it until it joins one of them.\n */\nexport type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, RelationClause> & {\n  $required?: boolean;\n};\n\n/**\n * options to get a single record.\n */\nexport type QueryOne<E, Raw = QueryRaw> = Except<Query<E, Raw>, '$limit'>;\n\n/**\n * options to get an unique record.\n */\nexport type QueryUnique<E, Raw = QueryRaw> = Pick<QueryOne<E, Raw>, '$select' | '$exclude' | '$populate' | '$where'>;\n\n/**\n * The clauses that shape a row, captured as key sets rather than maps: a naked type parameter skips\n * excess-property checks, while a key set fails its own constraint on a typo.\n * @internal\n */\ntype QueryProjection<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E>,\n  Raw = QueryRaw,\n> = {\n  $select?: QuerySelect<E, S, V> | readonly Raw[];\n  $exclude?: QuerySelect<E, X, V>;\n  $populate?: QueryPopulate<E, Raw, P>;\n  // Narrowing the captured names to the to-many ones leaves a to-one relation no key here at all,\n  // so counting one is an excess property rather than a value to check.\n  $count?: QueryCount<E, Raw, C & ToManyRelationKey<E>>;\n};\n\n/**\n * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.\n */\nexport type QueryProjected<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E> = never,\n  Raw = QueryRaw,\n> = Query<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;\n\n/**\n * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.\n */\nexport type QueryOneProjected<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E> = never,\n  Raw = QueryRaw,\n> = QueryOne<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;\n\n/**\n * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every\n * field minus what `$select` or `$exclude` subtracts, plus the populated relations.\n * @internal\n */\ntype ProjectedKeys<E, S, V, X, P> =\n  | ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S)\n  | P;\n\n/**\n * Whether every entry of the captured map says the same thing: all selected, or all subtracted.\n * @internal\n */\ntype IsUniform<V> = [V] extends [true | 1] ? true : [V] extends [false | 0] ? true : false;\n\n/**\n * A find's row: the entity narrowed to what the query projected and populated, so reading anything\n * else does not compile. The entity itself where the projection is raw, absent or not uniform.\n * @example `QueryFindResult<User, 'id' | 'name'>`\n */\nexport type QueryFindResult<\n  E,\n  S extends FieldKey<E> = never,\n  // A whitelist by default, so the hand-written form reads `QueryFindResult<User, 'id' | 'name'>`.\n  V = true,\n  X extends FieldKey<E> = never,\n  P extends RelationKey<E> = never,\n  C extends RelationKey<E> = never,\n> = QueryProjectedRow<E, S, V, X, P, C> & CountedRelations<C>;\n\n/**\n * The `_count` a query asked for, or an inert intersection member when it asked for none - so a read\n * without `$count` keeps exactly the row type it had.\n */\ntype CountedRelations<C extends PropertyKey> = [C] extends [never]\n  ? unknown\n  : { [K in typeof COUNT_RESULT_KEY]: { [R in C]: number } };\n\n/** @internal */\ntype QueryProjectedRow<\n  E,\n  S extends FieldKey<E>,\n  V,\n  X extends FieldKey<E>,\n  P extends RelationKey<E>,\n  C extends RelationKey<E>,\n> = [S | X] extends [never]\n  ? E\n  : IsUniform<V> extends true\n    ? [PopulatedToMany<E, P>] extends [never]\n      ? // `Pick`, not a key remap: an entity keyed by an index signature - a content type defined at\n        // runtime - has `string` for its keys, and a remap keeps no literal one, so every projection\n        // over one came back as `{}`.\n        Pick<E, ProjectedKeys<E, S, V, X, P> & keyof E>\n      : // A populated to-many is always a list, empty where the parent has no children, so it maps\n        // and counts without a guard. Only that promotion needs a second member, and only a query\n        // that populates one pays for it; every other key keeps the modifier the entity declared,\n        // a to-one relation included, since a join that finds no row leaves it absent.\n        Pick<E, Exclude<ProjectedKeys<E, S, V, X, P>, PopulatedToMany<E, P>> & keyof E> & {\n          [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;\n        }\n    : E;\n\n/** The to-many relations a query populated, which come back as lists rather than as optional ones. */\ntype PopulatedToMany<E, P> = Extract<P, ToManyRelationKey<E>>;\n\n/**\n * stringified query.\n */\nexport type QueryStringified = {\n  [K in keyof Query<unknown>]?: string;\n};\n\n/** What upserting one row reports. `created` is only knowable for a single statement, so a batch has none. */\nexport type QueryUpsertOneResult<E> = {\n  readonly id?: WrittenId<E>;\n  readonly changes?: number;\n  /** Whether the record was created (`true`) or updated (`false`), where the dialect can tell. */\n  readonly created?: boolean;\n};\n\n/**\n * What upserting many rows reports. `ids` is payload-aligned like an insert's, so it zips with the\n * rows that were passed, and carries a composite key as the map naming it.\n */\nexport type QueryUpsertManyResult<E> = {\n  readonly ids: (WrittenId<E> | undefined)[];\n  readonly changes?: number;\n};\n\n/**\n * result of an update operation, as the driver reports it - which is what `run` hands back, where\n * there is no entity to name the ids against. The `QueryUpsert*Result` pair is the entity-level shape.\n */\nexport type QueryUpdateResult = {\n  /**\n   * number of affected records.\n   */\n  changes?: number;\n  /**\n   * the IDs the statement reported, in payload order, `undefined` where it reported none for that\n   * row - a MongoDB upsert names only the documents it inserted. Exact on `'returning'` dialects;\n   * inferred from the driver header on the others (see {@link InsertIdSource}), and absent\n   * altogether when the header reports nothing.\n   */\n  ids?: (PrimaryKey | undefined)[];\n  /**\n   * first inserted ID.\n   */\n  firstId?: PrimaryKey;\n  /**\n   * whether the record was created (`true`) or updated (`false`).\n   * `undefined` when the dialect cannot determine this (e.g. SQLite).\n   */\n  created?: boolean;\n};\n",
     "import type { QueryContext, RelationAggregateSpec, SqlQueryDialect } from './dialect.js';\nimport type { Type } from './utility.js';\n\n/** What a `raw` callback receives. See {@link QueryRawFn}. */\nexport type QueryRawRenderOptions = {\n  /** The dialect rendering the SQL. */\n  dialect: SqlQueryDialect;\n  /** The alias of the table in scope, unescaped; empty where there is none. */\n  prefix: string;\n  /** {@link prefix} escaped, with its trailing dot. */\n  escapedPrefix: string;\n  /** The query context the SQL is written into. */\n  ctx: QueryContext;\n  /**\n   * The entity being rendered, which a ref read off a definition's map resolves its column against: a\n   * computed field's own, or the one whose schema is built. Absent where a statement renders SQL.\n   */\n  entity?: Type<unknown>;\n};\n\n/** {@link QueryRawRenderOptions} as the callers along the way fill them in, every one still optional. */\nexport type QueryRawFnOptions = Partial<QueryRawRenderOptions>;\n\n/**\n * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else\n * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the\n * latter rejected `({ ctx }) => ctx.append(...)`, the form every computed field is written in, because\n * TypeScript's \"returning a value where void is expected\" allowance does not apply to a union.\n */\nexport type QueryRawFn = (opts: QueryRawRenderOptions) => unknown;\n\nexport const RAW_VALUE: unique symbol = Symbol('rawValue');\nexport const RAW_ALIAS: unique symbol = Symbol('rawAlias');\n\nexport class QueryRaw {\n  readonly [RAW_VALUE]: QueryRawFn;\n  readonly [RAW_ALIAS]?: string;\n\n  constructor(value: QueryRawFn, alias?: string) {\n    this[RAW_VALUE] = value;\n    this[RAW_ALIAS] = alias;\n  }\n\n  /** The same expression under an alias, for a `$select` projection. */\n  as(alias: string): QueryRaw {\n    return new QueryRaw(this[RAW_VALUE], alias);\n  }\n\n  /** Writes the expression into `opts.ctx`. The alias is the projection's to write, after the term. */\n  render(opts: QueryRawRenderOptions): void {\n    const emitted = this[RAW_VALUE](opts);\n    if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {\n      opts.ctx.append(String(emitted));\n    }\n  }\n}\n\n/**\n * A field of an entity as SQL, read off `refs(Entity)` or a definition's refs: interpolated into `raw`, it\n * renders as the field's column. Its `key` is how an index tells a column from an expression.\n */\nexport class ColumnRef<K extends string = string> extends QueryRaw {\n  constructor(\n    readonly key: K,\n    value: QueryRawFn,\n  ) {\n    super(value);\n  }\n}\n\n/**\n * A relation aggregate as SQL, read off a `computed` field's refs: `(user) => user.resources.count()`.\n * It renders as the correlated subquery a `$count` reads, so a field holding one is read, filtered and\n * sorted like any other.\n *\n * `V` is the value it reads and `Storable` whether a trigger could keep it, both carried in phantom\n * fields so the aggregate a field declares decides the property's type and refuses `stored: true` on\n * one no delta can maintain.\n */\nexport class RelationAggregate<V = unknown, Storable extends boolean = boolean> extends QueryRaw {\n  declare private readonly __value: V;\n  declare private readonly __storable: Storable;\n\n  constructor(\n    /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */\n    readonly spec: RelationAggregateSpec,\n    value: QueryRawFn,\n  ) {\n    super(value);\n  }\n}\n",
     "import type { EntityMeta } from '../type/index.js';\n\nexport function throwPendingTransaction(): never {\n  throw TypeError('pending transaction');\n}\n\nexport function throwNoPendingTransaction(): never {\n  throw TypeError('not a pending transaction');\n}\n\nexport function clone<T>(value: T): T {\n  if (typeof value !== 'object' || value === null) {\n    return value;\n  }\n  if (Array.isArray(value)) {\n    return value.map((it) => clone(it)) as T;\n  }\n  return { ...value };\n}\n\n/** Whether `obj` has at least one enumerable key. Narrows away `undefined`/`null` for callers. */\nexport function hasKeys<T>(obj: T): obj is NonNullable<T> {\n  if (typeof obj !== 'object' || obj === null) return false;\n  for (const _ in obj) return true;\n  return false;\n}\n\n/**\n * Whether any enumerable key of `obj` satisfies `pred`, short-circuiting on the first match\n * without materializing a key array (unlike `Object.keys(obj).some(pred)`).\n */\nexport function someKey<T extends object>(obj: T, pred: (key: keyof T & string) => boolean): boolean {\n  for (const key in obj) {\n    if (pred(key)) return true;\n  }\n  return false;\n}\n\n/** Whether `key` names an operator (`$eq`, `$push`...) rather than a field. */\nexport function isOperatorKey(key: string): boolean {\n  return key.startsWith('$');\n}\n\n/** Whether `value` is a non-empty object with an operator key (`$eq`, `$push`...): the one test every dialect classifies with. */\nexport function isOperatorObject(value: unknown): value is Record<string, unknown> {\n  return isRecord(value) && someKey(value, isOperatorKey);\n}\n\n/** Whether `value` is an object that is not an array, whose keys can be read. */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nexport function getKeys<T extends object>(obj: T | null | undefined): (keyof T & string)[] {\n  return obj ? (Object.keys(obj) as (keyof T & string)[]) : [];\n}\n\n/** The entries of `record` holding a value: a key declared but left `undefined` is no entry at all. */\nexport function definedEntries<K extends string, V>(record: Partial<Record<K, V>>): [K, V][] {\n  return (Object.entries(record) as [K, V | undefined][]).filter((entry): entry is [K, V] => entry[1] !== undefined);\n}\n\n/**\n * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so\n * the fallback is what an entity that named no table is called - which is why the sites spelling this\n * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.\n */\nexport function entityName<E>(meta: EntityMeta<E>): string {\n  return meta.name ?? meta.entity.name;\n}\n\n/**\n * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the\n * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which\n * is what a `$where` map and a composite key's id object both are; an array is a list of either.\n */\nexport function isScalarId(value: unknown): boolean {\n  if (typeof value !== 'object' || value === null) {\n    return true;\n  }\n  if (Array.isArray(value)) {\n    return false;\n  }\n  // `null` as well as `Object.prototype`: an object with no prototype is what a query-string parser\n  // hands back (`qs`, express's `req.params`), and reading one as a bare id would name one column\n  // with a map of several.\n  const proto = Object.getPrototypeOf(value);\n  return proto !== Object.prototype && proto !== null;\n}\n\n/** Whether `value` is a plain object naming columns, the one shape a `$where` takes. */\nexport function isWhereMap(value: unknown): value is Record<string, unknown> {\n  return !Array.isArray(value) && !isScalarId(value);\n}\n",
     "import type { QueryOptions, WireQuery } from '../type/index.js';\n// the clause lists themselves, not the barrel: this module is in the browser bundle's graph\nimport {\n  QUERY_BOOLEAN_CLAUSES,\n  QUERY_NUMBER_CLAUSES,\n  QUERY_OBJECT_CLAUSES,\n  QUERY_ROOT_NUMBER_CLAUSES,\n  QUERY_ROOT_OBJECT_CLAUSES,\n} from '../type/query.js';\n// the brand alone, not the class: importing `QueryRaw` for an `instanceof` kept it, and `ColumnRef`\n// with it, in the browser bundle, which is on a size budget\nimport { RAW_VALUE } from '../type/queryRaw.js';\n// the specific util module, not the barrel, so the browser bundle does not pull in entity metadata\nimport { getKeys, isWhereMap } from '../util/object.util.js';\n\n/**\n * Keys accepted from the wire - query structure ({@link Query}) plus the `hardDelete`/`count` scalar\n * flags. Anything else (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't\n * bypass a security filter or inject ambient context - those are server-only. The `satisfies` ties\n * every entry to a real query/option key, so a typo or a renamed option fails to compile.\n */\nconst ALLOWED_QUERY_KEYS = new Set<string>([\n  ...QUERY_OBJECT_CLAUSES,\n  ...QUERY_ROOT_OBJECT_CLAUSES,\n  ...QUERY_NUMBER_CLAUSES,\n  ...QUERY_ROOT_NUMBER_CLAUSES,\n  ...QUERY_BOOLEAN_CLAUSES,\n  'hardDelete',\n  'count',\n] satisfies (keyof WireQuery<unknown> | keyof Pick<QueryOptions, 'hardDelete'> | 'count')[]);\n\n/**\n * Keys that mean something locally but that this transport can never honor, so they are rejected\n * rather than dropped like the rest. Each request runs on its own auto-committing connection, so a\n * row lock taken here is released before the response is written: honoring `$lock` is impossible,\n * and ignoring it would hand the caller a read they believe is serialized and is not.\n */\nconst REJECTED_QUERY_KEYS = new Set<string>(['$lock'] satisfies (keyof WireQuery<unknown>)[]);\n\n/**\n * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.\n * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.\n */\nexport function parseQueryParams(params: Record<string, unknown> = {}): WireQuery<unknown> {\n  const query: Record<string, unknown> = {};\n  for (const key of getKeys(params)) {\n    if (REJECTED_QUERY_KEYS.has(key)) {\n      throw Object.assign(new TypeError(`'${key}' is not supported over HTTP`), { status: 400 });\n    }\n    if (ALLOWED_QUERY_KEYS.has(key)) {\n      query[key] = params[key];\n    }\n  }\n\n  for (const key of [...QUERY_OBJECT_CLAUSES, ...QUERY_ROOT_OBJECT_CLAUSES]) {\n    const value = query[key];\n    if (typeof value === 'string') {\n      try {\n        query[key] = JSON.parse(value);\n      } catch {\n        throw Object.assign(new SyntaxError(`invalid JSON in '${key}'`), { status: 400 });\n      }\n    }\n  }\n\n  query['$where'] ??= {};\n  if (!isWhereMap(query['$where'])) {\n    throw Object.assign(new TypeError(\"'$where' must be a JSON object\"), { status: 400 });\n  }\n\n  // A query string carries every value as text, so what decodes a clause is the shape its group\n  // declares. `'false'` is the reason the boolean pass exists rather than the raw value being taken:\n  // it is a non-empty string, so a `$distinct=false` would otherwise read as asking for one.\n  for (const key of [...QUERY_NUMBER_CLAUSES, ...QUERY_ROOT_NUMBER_CLAUSES]) {\n    if (query[key] !== undefined) {\n      query[key] = Number(query[key]);\n    }\n  }\n  for (const key of QUERY_BOOLEAN_CLAUSES) {\n    if (query[key] !== undefined) {\n      query[key] = query[key] === true || query[key] === 'true';\n    }\n  }\n\n  return query as WireQuery<unknown>;\n}\n\n/**\n * Serialize a UQL query object into a percent-encoded query string where object values\n * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.\n */\nexport function stringifyQuery(query?: Record<string, unknown>): string {\n  if (!query) {\n    return '';\n  }\n  const params = new URLSearchParams();\n  for (const key of getKeys(query)) {\n    const value = query[key];\n    if (value === undefined) {\n      continue;\n    }\n    params.append(key, typeof value === 'object' && value !== null ? wireJson(value) : String(value));\n  }\n  const qs = params.toString();\n  return qs ? `?${qs}` : '';\n}\n\n/**\n * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server\n * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not\n * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it\n * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,\n * hits where the client's types already refuse a fragment.\n */\nexport function wireJson(value: unknown): string {\n  return JSON.stringify(value, (_key: string, held: unknown) => {\n    if (typeof held !== 'object' || held === null) {\n      return held;\n    }\n    if (RAW_VALUE in held) {\n      throw new TypeError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');\n    }\n    // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.\n    if (held instanceof ArrayBuffer || ArrayBuffer.isView(held)) {\n      throw new TypeError('binary cannot travel over HTTP: what leaves the browser is JSON');\n    }\n    return held;\n  });\n}\n",
@@ -13,7 +13,7 @@
     "import { CRUD_ROUTES, entityPath, type HttpMethod } from '../../http/contract.js';\nimport { stringifyQuery } from '../../http/query.js';\nimport type {\n  EntityWrite,\n  EntityId,\n  FieldKey,\n  QueryFilter,\n  QueryFindResult,\n  QueryOneProjected,\n  QueryOptions,\n  QueryPage,\n  QueryProjected,\n  QuerySearch,\n  RelationKey,\n  RequestCountedSuccessResponse,\n  RequestSuccessResponse,\n  Type,\n  UpdateWrite,\n  WireQuery,\n  WrittenId,\n} from '../../type/index.js';\nimport { isScalarId } from '../../util/object.util.js';\nimport { get, query as httpQuery, patch, post, put, remove } from '../http/index.js';\nimport type { ClientQuerier, RequestFindOptions, RequestOptions } from '../type/index.js';\n\nexport type HttpQuerierDefaults = {\n  /**\n   * headers sent with every request from this instance, merged under per-call headers.\n   * Create one instance per request (e.g. during SSR) to scope auth headers safely.\n   */\n  readonly headers?: Record<string, string>;\n  /**\n   * transport for read queries (findOne, findMany, count). 'QUERY' (RFC 10008) sends the\n   * JSON query in the request body, avoiding URL-length limits for large queries; requires\n   * infrastructure (proxies, CDNs) that forwards the QUERY method. Defaults to 'GET'.\n   */\n  readonly readMethod?: Extract<HttpMethod, 'GET' | 'QUERY'>;\n  /**\n   * The URL segment an entity is addressed by, defaulting to its kebab-cased class name - the same\n   * option the server handler takes, so one map serves both. State it where the default cannot: a\n   * build that minifies class names renames every route.\n   */\n  readonly entityPath?: (entity: Type<unknown>) => string;\n};\n\n/** The id as one path segment, refusing a composite key, which has no spelling in `/:id` yet. Callers are `async`. */\nfunction idSegment<E>(entity: Type<E>, id: EntityId<E>): string {\n  if (!isScalarId(id)) {\n    throw new TypeError(`'${entity.name}' was addressed by an id object, which the HTTP route cannot carry.`);\n  }\n  return String(id);\n}\n\nexport class HttpQuerier implements ClientQuerier {\n  constructor(\n    readonly basePath: string,\n    readonly defaults: HttpQuerierDefaults = {},\n  ) {}\n\n  async findOneById<\n    E extends object,\n    const S extends FieldKey<E> = never,\n    const V = true,\n    const X extends FieldKey<E> = never,\n    const P extends RelationKey<E> = never,\n    const C extends RelationKey<E> = never,\n  >(\n    entity: Type<E>,\n    id: EntityId<E>,\n    q?: QueryOneProjected<E, S, V, X, P, C, never>,\n    opts?: RequestOptions,\n  ): Promise<RequestSuccessResponse<QueryFindResult<E, S, V, X, P, C> | undefined>> {\n    const basePath = this.getBasePath(entity);\n    const qs = stringifyQuery(q);\n    return get<QueryFindResult<E, S, V, X, P, C> | undefined>(\n      `${basePath}/${idSegment(entity, id)}${qs}`,\n      this.buildOptions(opts),\n    );\n  }\n\n  findOne<\n    E extends object,\n    const S extends FieldKey<E> = never,\n    const V = true,\n    const X extends FieldKey<E> = never,\n    const P extends RelationKey<E> = never,\n    const C extends RelationKey<E> = never,\n  >(\n    entity: Type<E>,\n    q: QueryOneProjected<E, S, V, X, P, C, never>,\n    opts?: RequestOptions,\n  ): Promise<RequestSuccessResponse<QueryFindResult<E, S, V, X, P, C> | undefined>> {\n    return this.read<QueryFindResult<E, S, V, X, P, C> | undefined>(\n      `${this.getBasePath(entity)}${CRUD_ROUTES.findOne.path}`,\n      q,\n      opts,\n    );\n  }\n\n  findMany<\n    E extends object,\n    const S extends FieldKey<E> = never,\n    const V = true,\n    const X extends FieldKey<E> = never,\n    const P extends RelationKey<E> = never,\n    const C extends RelationKey<E> = never,\n  >(\n    entity: Type<E>,\n    q: QueryProjected<E, S, V, X, P, C, never>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestSuccessResponse<QueryFindResult<E, S, V, X, P, C>[]>> {\n    const data: WireQuery<E> & { count?: boolean } = { ...q };\n    if (opts?.count) {\n      data.count = true;\n    }\n    return this.read<QueryFindResult<E, S, V, X, P, C>[]>(this.getBasePath(entity), data, opts);\n  }\n\n  async findManyAndCount<\n    E extends object,\n    const S extends FieldKey<E> = never,\n    const V = true,\n    const X extends FieldKey<E> = never,\n    const P extends RelationKey<E> = never,\n    const C extends RelationKey<E> = never,\n  >(\n    entity: Type<E>,\n    q: QueryProjected<E, S, V, X, P, C, never>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestCountedSuccessResponse<QueryFindResult<E, S, V, X, P, C>[]>> {\n    const response = await this.findMany(entity, q, { ...opts, count: true });\n    if (typeof response.count !== 'number') {\n      throw new TypeError('findManyAndCount response has an invalid count');\n    }\n    return { ...response, count: response.count };\n  }\n\n  count<E extends object>(entity: Type<E>, q?: QueryPage<E, never>, opts?: RequestOptions) {\n    return this.read<number>(`${this.getBasePath(entity)}${CRUD_ROUTES.count.path}`, q, opts);\n  }\n\n  /** The `count` route capped at one row, so existence needs no endpoint of its own. */\n  async exists<E extends object>(entity: Type<E>, q?: QueryFilter<E, never>, opts?: RequestOptions) {\n    const res = await this.count(entity, { ...q, $limit: 1 }, opts);\n    return { ...res, data: res.data > 0 };\n  }\n\n  insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return post<WrittenId<E> | undefined>(basePath, payload, this.buildOptions(opts));\n  }\n\n  insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return post<(WrittenId<E> | undefined)[]>(\n      `${basePath}${CRUD_ROUTES.insertMany.path}`,\n      payload,\n      this.buildOptions(opts),\n    );\n  }\n\n  async updateOneById<E extends object>(\n    entity: Type<E>,\n    id: EntityId<E>,\n    payload: UpdateWrite<E, never>,\n    opts?: RequestOptions,\n  ) {\n    const basePath = this.getBasePath(entity);\n    return patch<number>(`${basePath}/${idSegment(entity, id)}`, payload, this.buildOptions(opts));\n  }\n\n  updateMany<E extends object>(\n    entity: Type<E>,\n    q: QuerySearch<E, never>,\n    payload: UpdateWrite<E, never>,\n    opts?: RequestOptions,\n  ) {\n    const basePath = this.getBasePath(entity);\n    const qs = stringifyQuery(q);\n    return patch<number>(`${basePath}${qs}`, payload, this.buildOptions(opts));\n  }\n\n  saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<WrittenId<E> | undefined>(basePath, payload, this.buildOptions(opts));\n  }\n\n  saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<(WrittenId<E> | undefined)[]>(\n      `${basePath}${CRUD_ROUTES.saveMany.path}`,\n      payload,\n      this.buildOptions(opts),\n    );\n  }\n\n  async deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts: QueryOptions & RequestOptions = {}) {\n    const basePath = this.getBasePath(entity);\n    const qs = opts.hardDelete ? stringifyQuery({ hardDelete: opts.hardDelete }) : '';\n    return remove<number>(`${basePath}/${idSegment(entity, id)}${qs}`, this.buildOptions(opts));\n  }\n\n  deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E, never>, opts: QueryOptions & RequestOptions = {}) {\n    const basePath = this.getBasePath(entity);\n    const qs = stringifyQuery(opts.hardDelete ? { ...q, hardDelete: opts.hardDelete } : q);\n    return remove<number>(`${basePath}${qs}`, this.buildOptions(opts));\n  }\n\n  getBasePath<E>(entity: Type<E>) {\n    return `${this.basePath}/${(this.defaults.entityPath ?? entityPath)(entity)}`;\n  }\n\n  protected read<T>(path: string, q: Record<string, unknown> | undefined, opts?: RequestOptions) {\n    if (this.defaults.readMethod === 'QUERY') {\n      return httpQuery<T>(path, q ?? {}, this.buildOptions(opts));\n    }\n    return get<T>(`${path}${stringifyQuery(q)}`, this.buildOptions(opts));\n  }\n\n  protected buildOptions(opts?: RequestOptions): RequestOptions | undefined {\n    if (!this.defaults.headers && !opts?.headers) {\n      return opts;\n    }\n    return { ...opts, headers: { ...this.defaults.headers, ...opts?.headers } };\n  }\n}\n",
     "import { HttpQuerier } from './querier/httpQuerier.js';\nimport type { ClientQuerier, ClientQuerierPool } from './type/index.js';\n\nlet defaultPool: ClientQuerierPool = {\n  getQuerier: () => new HttpQuerier('/api'),\n};\n\nexport function setQuerierPool<T extends ClientQuerierPool>(pool: T) {\n  defaultPool = pool;\n}\n\nexport function getQuerierPool(): ClientQuerierPool {\n  return defaultPool;\n}\n\nexport function getQuerier(): ClientQuerier {\n  return getQuerierPool().getQuerier();\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "5397AE2C0FC782D564756E2164756E21",
+  "mappings": "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",
+  "debugId": "3410F618088BC65664756E2164756E21",
   "names": []
 }

package/dist/dialect/abstractSqlDialect.d.ts

@@ -16,10 +16,14 @@ type InsertShape<E> = {
 };
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
 type HydratableField = readonly [string, HydrateKind];
+/** A direction as a statement writes it: the suffix, and where the caller asked nulls to land. */
+type SortOrder = {
+    readonly direction?: string;
+    readonly nulls?: 'first' | 'last';
+};
 /** A sort term of a relation's rows as their aggregate orders by it: the column carrying it out. */
-export type SortRef = {
+export type SortRef = SortOrder & {
     readonly ref: string;
-    readonly direction: string;
 };
 /**
  * One column of a read's projection: the key its row answers under, none for a raw expression written
@@ -443,6 +447,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected having(ctx: QueryContext, having: QueryHavingMap, emittedColumns: Record<string, string>): void;
     private static readonly SORT_DIRECTION_MAP;
     private resolveSortDirection;
+    /**
+     * One `ORDER BY` term. A placement the engine has no `NULLS FIRST/LAST` for becomes a term of its
+     * own in front of it, which is why one is only ever emitted where the caller asked for it: no index
+     * serves an expression. SQL Server needs a `CASE`, having no orderable boolean.
+     */
+    protected orderByTerm(expr: string, { direction, nulls }: SortOrder): string;
     /** Every operator of one `HAVING` condition, `AND`-joined. */
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     /**

package/dist/dialect/abstractSqlDialect.js

@@ -164,7 +164,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (!order.length || (q.$limit === undefined && q.$skip === undefined)) {
             return false;
         }
-        ctx.append(` ORDER BY ${order.map(({ ref, direction }) => ref + direction).join(', ')}`);
+        ctx.append(` ORDER BY ${order.map(({ ref, ...term }) => this.orderByTerm(ref, term)).join(', ')}`);
         return true;
     }
     /**
@@ -323,13 +323,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     carrySort(ctx, meta, q, opts) {
         const columns = [];
-        const order = this.sortTerms(ctx, meta, q, opts).map(({ key, expr, direction, output }) => {
+        const order = this.sortTerms(ctx, meta, q, opts).map(({ key, expr, output, ...term }) => {
             if (output) {
-                return { ref: expr, direction };
+                return { ref: expr, ...term };
             }
             const column = relationSortColumn(key);
             columns.push({ sql: expr, key: column });
-            return { ref: this.escapeId(column, true), direction };
+            return { ref: this.escapeId(column, true), ...term };
         });
         return { columns, order };
     }
@@ -800,7 +800,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     sort(ctx, entity, q, opts = {}) {
         const terms = this.sortTerms(ctx, getMeta(entity), q, opts);
         if (terms.length) {
-            ctx.append(` ORDER BY ${terms.map(({ expr, direction }) => expr + direction).join(', ')}`);
+            ctx.append(` ORDER BY ${terms.map(({ expr, ...term }) => this.orderByTerm(expr, term)).join(', ')}`);
         }
         return terms.length > 0;
     }
@@ -837,7 +837,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 // Where projected in the SELECT list, ordered by that alias rather than scored twice.
                 const { order, project } = textSortOf(sort);
                 const expr = project ? this.escapeId(project) : this.buildFragment(ctx, opts.rankText);
-                columns.push({ key, expr, direction: this.resolveSortDirection(order), output: project !== undefined });
+                columns.push({ key, expr, ...this.resolveSortDirection(order), output: project !== undefined });
                 continue;
             }
             if (relation) {
@@ -851,10 +851,10 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     }
                     const expr = this.buildFragment(ctx, (fragmentCtx) => this.appendRelationAggregate(fragmentCtx, meta.entity, spec, prefix ?? ''));
                     if (spec.search) {
-                        vectors.push({ key: name, expr, direction: '', output: false });
+                        vectors.push({ key: name, expr, output: false });
                     }
                     else {
-                        columns.push({ key: keyPath, expr, direction: this.resolveSortDirection(direction), output: false });
+                        columns.push({ key: keyPath, expr, ...this.resolveSortDirection(direction), output: false });
                     }
                 }
                 if (rest === undefined) {
@@ -872,19 +872,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             if (isVectorSearch(value)) {
                 // Already projected in the SELECT list: order by that alias rather than recomputing it.
                 vectors.push(value.$project
-                    ? { key: keyPath, expr: this.escapeId(value.$project), direction: '', output: true }
+                    ? { key: keyPath, expr: this.escapeId(value.$project), output: true }
                     : {
                         key: keyPath,
                         expr: this.buildFragment(ctx, (fragmentCtx) => this.appendVectorDistance(fragmentCtx, meta, key, value, prefix)),
-                        direction: '',
                         output: false,
                     });
                 continue;
             }
-            const direction = this.resolveSortDirection(value);
+            const order = this.resolveSortDirection(value);
             // A JSON path can sort by more than one reading, each carried under a name of its own.
             this.sortColumns(ctx, meta, key, prefix).forEach((column, index) => {
-                columns.push({ key: index ? `${keyPath}:${index}` : keyPath, ...column, direction });
+                columns.push({ key: index ? `${keyPath}:${index}` : keyPath, ...column, ...order });
             });
         }
     }
@@ -1097,7 +1096,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         Object.entries(sort).forEach(([key, dir], index) => {
             if (index > 0)
                 ctx.append(', ');
-            ctx.append(this.aggregateRef(emittedColumns, key, '$sort') + this.resolveSortDirection(dir));
+            ctx.append(this.orderByTerm(this.aggregateRef(emittedColumns, key, '$sort'), this.resolveSortDirection(dir)));
         });
         return true;
     }
@@ -1119,14 +1118,36 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         });
     }
     static SORT_DIRECTION_MAP = new Map([
-        [1, ''],
-        ['asc', ''],
-        ['desc', ' DESC'],
-        [-1, ' DESC'],
+        [1, {}],
+        ['asc', {}],
+        ['desc', { direction: ' DESC' }],
+        [-1, { direction: ' DESC' }],
+        ['ascNullsFirst', { nulls: 'first' }],
+        ['ascNullsLast', { nulls: 'last' }],
+        ['descNullsFirst', { direction: ' DESC', nulls: 'first' }],
+        ['descNullsLast', { direction: ' DESC', nulls: 'last' }],
     ]);
     resolveSortDirection(sort) {
-        const direction = AbstractSqlDialect.SORT_DIRECTION_MAP.get(sort);
-        return orRefuse(direction, `unknown sort direction: ${sort}`);
+        const order = AbstractSqlDialect.SORT_DIRECTION_MAP.get(sort);
+        return orRefuse(order, `unknown sort direction: ${sort}`);
+    }
+    /**
+     * One `ORDER BY` term. A placement the engine has no `NULLS FIRST/LAST` for becomes a term of its
+     * own in front of it, which is why one is only ever emitted where the caller asked for it: no index
+     * serves an expression. SQL Server needs a `CASE`, having no orderable boolean.
+     */
+    orderByTerm(expr, { direction = '', nulls }) {
+        if (!nulls) {
+            return expr + direction;
+        }
+        const first = nulls === 'first';
+        if (this.features.nullsOrdering === 'clause') {
+            return `${expr}${direction} NULLS ${first ? 'FIRST' : 'LAST'}`;
+        }
+        const lead = this.features.nullsOrdering === 'case'
+            ? `CASE WHEN ${expr} IS NULL THEN ${first ? 0 : 1} ELSE ${first ? 1 : 0} END`
+            : `${expr} IS ${first ? 'NOT NULL' : 'NULL'}`;
+        return `${lead}, ${expr}${direction}`;
     }
     /** Every operator of one `HAVING` condition, `AND`-joined. */
     havingCondition(ctx, expr, condition) {
@@ -1839,7 +1860,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 const key = relationTermKey(term);
                 return [key, `${alias}.${this.escapeId(key, true)}`];
             }),
-            order: order.map(({ ref, direction }) => `${alias}.${ref}${direction}`).join(', '),
+            order: order.map(({ ref, ...term }) => this.orderByTerm(`${alias}.${ref}`, term)).join(', '),
         };
     }
     /**

package/dist/dialect/aliases.d.ts

@@ -24,6 +24,11 @@ export declare const JSON_ELEM_ALIAS = "_uql_elem";
 export declare const JSON_PULL_ALIAS = "_uql_pull";
 /** The field a MongoDB `$sort` by `$text` reads `textScore` from where it projects none, taken back out after. */
 export declare const TEXT_SCORE_ALIAS = "_uql_text_score";
+/**
+ * The field a MongoDB `$sort` placing nulls orders by first: 1 where the value is null or missing, 0
+ * where it is not. MongoDB takes no `NULLS FIRST`, so the placement is this flag plus the sort on it.
+ */
+export declare function nullsSortField(path: string): string;
 /** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
 export declare const REL_TEMP_PREFIX = "_uql_rel_";
 /** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */

package/dist/dialect/aliases.js

@@ -25,6 +25,13 @@ export const JSON_ELEM_ALIAS = '_uql_elem';
 export const JSON_PULL_ALIAS = '_uql_pull';
 /** The field a MongoDB `$sort` by `$text` reads `textScore` from where it projects none, taken back out after. */
 export const TEXT_SCORE_ALIAS = '_uql_text_score';
+/**
+ * The field a MongoDB `$sort` placing nulls orders by first: 1 where the value is null or missing, 0
+ * where it is not. MongoDB takes no `NULLS FIRST`, so the placement is this flag plus the sort on it.
+ */
+export function nullsSortField(path) {
+    return `_uql_nulls_${path.replace(/\./g, '_')}`;
+}
 /** Prefix for the field a MongoDB relation lookup parks its result on, one per condition. */
 export const REL_TEMP_PREFIX = '_uql_rel_';
 /** The field a ManyToMany lookup nests its target match under, inside the junction's own pipeline. */

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -31,6 +31,7 @@ export const MYSQL_FEATURES = {
     correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: true,
+    nullsOrdering: 'expression',
     rowLockOf: true,
     textScoreIndexes: true,
     orderedUpsertReturning: true,

package/dist/dialect/pgLikeSqlDialect.js

@@ -35,6 +35,7 @@ export const PG_FEATURES = {
     correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: false,
+    nullsOrdering: 'clause',
     rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: true,

package/dist/entity/decorator/members.d.ts

@@ -1,4 +1,4 @@
-import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
+import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, VersionKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to, on a class `O`. */
 type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
@@ -31,12 +31,14 @@ type DeclaredValue<O> = O extends {
 /**
  * The `null` a column reads back: every one holds it unless `nullable: false` says otherwise, so the
  * property admits it too. A key holds none, whether `@Id` or `@Field({ isId: true })` declares it, since
- * it is NOT NULL on every engine.
+ * it is NOT NULL on every engine, and neither does a version, which is NOT NULL DEFAULT 0.
  */
 type NullOf<O> = O extends {
     readonly nullable: false;
 } | {
     readonly isId: true;
+} | {
+    readonly version: true;
 } ? never : null;
 /** The enum's members, or a named complaint where they widened for lack of `as const`, which would check nothing. */
 type EnumValue<Members, Declared> = Declared extends Members ? {
@@ -51,7 +53,7 @@ export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, Thi
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
+}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O & VersionIsBranded<O, This>): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
 /**
  * Declares a field a relation aggregate computes, `@Field({ computed: (user) => user.resources.count() })`.
  * The aggregate says what the field holds, so it takes no `type`, and only `count` and `sum` - the two a
@@ -80,6 +82,16 @@ type AggregateOptions<E> = (Except<FieldOptions<never, E>, 'computed' | 'stored'
 type KeyIsNamed<This> = [NamedIdKey<This>] extends [never] ? {
     readonly __keyNeedsIdKeyBrand: true;
 } : unknown;
+/**
+ * An optimistic lock the type level cannot see. `version: true` is what makes the column a lock at run
+ * time; the `versionKey` brand is what makes an update payload require it, and a lock only half
+ * declared would be a guarantee nothing enforces, so the decorator asks for both.
+ */
+type VersionIsBranded<O, This> = O extends {
+    readonly version: true;
+} ? [VersionKey<This>] extends [never] ? {
+    readonly __versionNeedsVersionKeyBrand: true;
+} : unknown : unknown;
 /** {@link MemberDecorator} that also constrains the class, which is where a key is named. */
 type IdDecorator<V> = <This>(value: undefined, context: ClassFieldDecoratorContext<This, V> & KeyIsNamed<This>) => void;
 /**

package/dist/entity/metadata/definition.js

@@ -213,6 +213,18 @@ export function defineEntity(entity, opts = {}) {
         meta.softDelete = softDeleteKeys[0];
         (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
     }
+    // The optimistic lock, derived the same way and just as singular: one row has one version.
+    const versionKeys = getKeys(meta.fields).filter((key) => meta.fields[key]?.version);
+    if (versionKeys.length > 1) {
+        throw TypeError(`'${entity.name}' must have at most one field with 'version'`);
+    }
+    if (versionKeys.length) {
+        meta.version = versionKeys[0];
+        // Implied rather than stated: the DDL default covers a row written around the ORM, and `onInsert`
+        // covers MongoDB, which has no DDL to default. Both, so every backend starts a row at the same 0.
+        const field = meta.fields[meta.version];
+        meta.fields[meta.version] = { ...field, nullable: false, defaultValue: 0, onInsert: 0 };
+    }
     const ids = getIdKeys(meta);
     if (!ids.length) {
         throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);

package/dist/mongo/mongoDialect.d.ts

@@ -2,10 +2,20 @@ import { type Document, type Filter, type Sort, type UpdateFilter } from 'mongod
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
 import { type CallbackKey } from '../util/index.js';
+/**
+ * An ordering as the pipeline runs it: the `$sort`, the fields it needs on the document first - a
+ * placement's null flags - and the ones to take back off after it. One object, so a caller cannot
+ * order by a field it forgot to add, or leave one behind in the rows it answers with.
+ */
+export type MongoSortPlan = {
+    readonly sort: Sort;
+    readonly stages: MongoAggregationPipelineEntry<Document>[];
+    readonly fields: string[];
+};
 /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
 type MongoReadStages = {
     /** Ordering, which runs after the lookups when it reads one of their fields. */
-    readonly sort?: Sort;
+    readonly sort?: MongoSortPlan;
     readonly pager?: MongoAggregationPipelineEntry<Document>[];
     /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
     readonly score?: {
@@ -126,7 +136,13 @@ export declare class MongoDialect extends AbstractDialect {
      * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
      * added for the sort alone would change what the caller gets back.
      */
-    sort<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): Sort;
+    sort<E extends Document>(entity: Type<E>, q: Query<E>): Sort;
+    /**
+     * The ordering, and the paths whose nulls it places. MongoDB sorts null and missing lowest and takes
+     * no placement, so one is emulated: {@link nullsSortStages} flags each path and the flag is ordered
+     * by ahead of the value itself.
+     */
+    sortPlan<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): MongoSortPlan;
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
     private collectSort;
     /**

package/dist/mongo/mongoDialect.js

@@ -1,6 +1,6 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
 import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
@@ -9,6 +9,7 @@ import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInte
 import { decodeBigIntsExcept } from '../util/wideNumber.js';
 import { textLanguage } from './textLanguage.js';
 import { vectorDistanceExpr } from './vectorDistance.js';
+const EMPTY_SORT_PLAN = { sort: {}, stages: [], fields: [] };
 /** A scalar field's operator as the aggregation operator computing it. */
 const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
 /** Default {@link DialectFeatures} for MongoDB. */
@@ -460,10 +461,19 @@ export class MongoDialect extends AbstractDialect {
      * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
      * added for the sort alone would change what the caller gets back.
      */
-    sort(entity, { $sort: sort, $populate: populate, $where: where }) {
+    sort(entity, q) {
+        return this.sortPlan(entity, q).sort;
+    }
+    /**
+     * The ordering, and the paths whose nulls it places. MongoDB sorts null and missing lowest and takes
+     * no placement, so one is emulated: {@link nullsSortStages} flags each path and the flag is ordered
+     * by ahead of the value itself.
+     */
+    sortPlan(entity, { $sort: sort, $populate: populate, $where: where }) {
         const meta = getMeta(entity);
         const nearest = {};
         const columns = {};
+        const placed = [];
         // Refused as the SQL dialects refuse it, before MongoDB answers a missing score with its own error.
         if (sort?.$text) {
             rankedTextSearch(where);
@@ -472,12 +482,17 @@ export class MongoDialect extends AbstractDialect {
         // pipeline actually produces cannot drift apart - `$sort` contributes its own to-one joins here
         // exactly as it does on the SQL dialects.
         const joins = resolveQueryJoins(meta, { $populate: populate, $sort: sort });
-        this.collectSort(meta, sort, joins, '', nearest, columns);
-        // A vector distance is the primary ordering wherever it appears, as on the SQL dialects.
-        return { ...nearest, ...columns };
+        this.collectSort(meta, sort, joins, '', nearest, columns, placed);
+        const flags = Object.fromEntries(placed.map((path) => [nullsSortField(path), { $cond: [{ $eq: [{ $ifNull: [`$${path}`, null] }, null] }, 1, 0] }]));
+        return {
+            // A vector distance is the primary ordering wherever it appears, as on the SQL dialects.
+            sort: { ...nearest, ...columns },
+            stages: placed.length ? [{ $addFields: flags }] : [],
+            fields: placed.map(nullsSortField),
+        };
     }
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
-    collectSort(meta, sort, joins, path, nearest, out) {
+    collectSort(meta, sort, joins, path, nearest, out, placed) {
         for (const [key, value] of Object.entries(sort ?? {})) {
             const relation = meta.relations[key];
             if (key === '$text') {
@@ -495,7 +510,14 @@ export class MongoDialect extends AbstractDialect {
                 if (isVectorSearch(value)) {
                     throw new TypeError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
                 }
-                out[path + this.pathOf(meta, key)] = sortDirection(value);
+                const docPath = path + this.pathOf(meta, key);
+                const nulls = sortNulls(value);
+                if (nulls) {
+                    placed.push(docPath);
+                    // The flag holds 1 for a null, so ordering by it descending brings the null block to the front.
+                    out[nullsSortField(docPath)] = nulls === 'first' ? -1 : 1;
+                }
+                out[docPath] = sortDirection(value);
                 continue;
             }
             // A `$lookup` is what puts the relation's fields on the document, and only `$populate` asks for
@@ -521,7 +543,7 @@ export class MongoDialect extends AbstractDialect {
                 continue;
             }
             const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, rest, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
-            this.collectSort(join.meta, relationSort, joins, `${relPath}.`, nearest, out);
+            this.collectSort(join.meta, relationSort, joins, `${relPath}.`, nearest, out, placed);
         }
     }
     /**
@@ -699,7 +721,7 @@ export class MongoDialect extends AbstractDialect {
         return [
             ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
             ...this.readStages(entity, q, {
-                sort: this.sort(entity, q),
+                sort: this.sortPlan(entity, q),
                 pager: this.pagerStages(q),
                 score: text && { field: text.project ?? TEXT_SCORE_ALIAS, meta: 'textScore', temporary: !text.project },
             }),
@@ -722,10 +744,12 @@ export class MongoDialect extends AbstractDialect {
         // The value an ordering by a relation's aggregate reads, and the field it parks it on: both belong
         // with the lookups, since the `$sort` right after them is what they exist for.
         const aggregated = this.sortAggregateStages(entity, q.$sort);
+        const ordering = extra.sort ?? EMPTY_SORT_PLAN;
         const lookups = [...this.lookupStages(meta, joins), ...aggregated.stages];
         // Each to-many and each `$count`, which neither drop nor reorder a row, so they read the page alone.
         const related = this.relationReadStages(entity, q);
-        const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
+        // The flags a placement orders by travel with their `$sort`, wherever the pipeline puts it.
+        const sort = hasKeys(ordering.sort) ? [...ordering.stages, { $sort: ordering.sort }] : [];
         const pager = extra.pager ?? [];
         // The score becomes a real field before anything reads it, so the lookups, the sort and the projection
         // that follow treat it like any other; merged into the query's own projection rather than standing in
@@ -743,7 +767,7 @@ export class MongoDialect extends AbstractDialect {
         // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
         // it has run, so ordering by an unpopulated relation costs the same nothing it does there.
         const sortOnly = [...joins.values()].filter((join) => !join.projected).map((join) => join.path);
-        const dropped = [...sortOnly, ...aggregated.fields];
+        const dropped = [...sortOnly, ...aggregated.fields, ...ordering.fields];
         const unset = dropped.length ? [{ $unset: dropped }] : [];
         // The grouping collapses rows onto the columns it projects, which leaves nothing for an ordering
         // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
@@ -1328,9 +1352,16 @@ export class MongoDialect extends AbstractDialect {
         return { $vectorSearch: stage };
     }
 }
-/** `-1` for the two descending spellings, `1` for everything else - MongoDB knows no other value. */
+/** `-1` for every descending spelling, `1` for everything else - MongoDB knows no other value. */
 function sortDirection(value) {
-    return value === 'desc' || value === -1 ? -1 : 1;
+    return value === -1 || (typeof value === 'string' && value.startsWith('desc')) ? -1 : 1;
+}
+/** Where a direction asks nulls to land, where it asks at all. */
+function sortNulls(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    return value.endsWith('NullsFirst') ? 'first' : value.endsWith('NullsLast') ? 'last' : undefined;
 }
 /**
  * A `computed` field writing SQL is refused wherever a query names it, since no document engine

package/dist/mongo/mongodbQuerier.js

@@ -78,6 +78,8 @@ export class MongodbQuerier extends AbstractQuerier {
             this.dialect.constrainsRelations(entity, q.$where) ||
             this.dialect.sortsRelations(entity, q.$sort) ||
             this.dialect.readsAggregates(entity, q) ||
+            // A placement is a field the pipeline adds and orders by; a `find` cursor can add none.
+            hasKeys(this.dialect.sortPlan(entity, q).fields) ||
             textSortOf(q.$sort) !== undefined);
     }
     buildScalarProjection(entity, q) {
@@ -117,7 +119,7 @@ export class MongodbQuerier extends AbstractQuerier {
             this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
             // `$vectorSearch` has already applied `$limit`, so the pager is its own.
             ...this.dialect.readStages(entity, q, {
-                sort: this.dialect.sort(entity, { ...q, $sort: vectorSort.regularSort }),
+                sort: this.dialect.sortPlan(entity, { ...q, $sort: vectorSort.regularSort }),
                 score: scoreAlias ? { field: scoreAlias, meta: 'vectorSearchScore' } : undefined,
             }),
         ];

package/dist/mssql/mssqlDialect.js

@@ -33,6 +33,7 @@ const MSSQL_FEATURES = {
     correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: true,
+    nullsOrdering: 'case',
     rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: false,

package/dist/querier/abstractQuerier.d.ts

@@ -86,6 +86,12 @@ export declare abstract class AbstractQuerier implements Querier {
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
+     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * still costs one statement. Best effort by nature - the row can change again while we ask.
+     */
+    private throwStaleVersion;
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     private updateColumns;
     /**

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,6 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
 import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, hasKeys, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
-import { enrichError } from './queryError.js';
+import { enrichError, UqlOptimisticLockError } from './queryError.js';
 /**
  * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
  * which would address every row agreeing on the rest. Callers are `async`, so it always rejects.
@@ -38,6 +38,29 @@ function assertNamesRows(entity, method, q, opts) {
     }
     throw new TypeError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
 }
+/**
+ * An optimistic lock as one update applies it: the value the payload carried, out of the payload and
+ * into the filter, and the next one back in its place. The bump is a plain value rather than SQL
+ * arithmetic, since the filter pins what the column holds, which spares every engine a read-back.
+ */
+function lockVersion(meta, key, q, row) {
+    const expected = row[key];
+    if (expected === undefined || expected === null) {
+        throw new TypeError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
+    }
+    row[key] = (typeof expected === 'bigint' ? expected + 1n : Number(expected) + 1);
+    return { expected, q: { ...q, $where: { $and: [q.$where ?? {}, { [key]: expected }] } } };
+}
+/**
+ * Refuses a write that cannot carry the lock, rather than writing over whatever the row holds now.
+ * An upsert has no portable way to match a version - MySQL's `ON DUPLICATE KEY UPDATE` takes no
+ * `WHERE` - and a write the library itself composes has no version to carry.
+ */
+function assertUnversioned(meta, method) {
+    if (meta.version) {
+        throw new TypeError(`cannot '${method}' the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
+    }
+}
 /**
  * The id each written row is named by, in payload order. Read off the rows as written, so a key the
  * database generated or the ORM filled is there, and a composite is named by every column of it.
@@ -198,9 +221,18 @@ export class AbstractQuerier {
         const meta = getMeta(entity);
         return this.hooked(entity, 'Update', [payload], async ([row]) => {
             fillOnFields(meta, [row], 'onUpdate');
+            const { version } = meta;
+            const lock = version && lockVersion(meta, version, q, row);
             const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
             if (!relKeys.length && !this.settlesWrite(entity, q)) {
-                return this.updateColumns(entity, q, row, opts, 0);
+                const changes = await this.updateColumns(entity, lock ? lock.q : q, row, opts, 0);
+                return lock && !changes ? this.throwStaleVersion(entity, version, q, lock.expected, opts) : changes;
+            }
+            if (lock) {
+                // Everything below reads the ids first and writes them in a second statement, which puts the
+                // race back in the gap between the two - the very thing the version is here to close.
+                // `settlesWrite` covers the paged forms, so `$sort`, `$limit` and `$skip` land here as well.
+                throw new TypeError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
             }
             const ids = await this.settleIds(entity, q, opts);
             if (!ids.length) {
@@ -213,6 +245,19 @@ export class AbstractQuerier {
             return changes;
         });
     }
+    /**
+     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
+     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * still costs one statement. Best effort by nature - the row can change again while we ask.
+     */
+    async throwStaleVersion(entity, key, q, expected, opts) {
+        const meta = getMeta(entity);
+        const row = await this.findOne(entity, { $select: { [key]: true }, $where: q.$where }, opts);
+        const actual = row?.[key];
+        throw new UqlOptimisticLockError(actual === undefined
+            ? `no row of '${entityName(meta)}' matched the update: it is gone, or the filter names none`
+            : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`, expected, actual);
+    }
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     async updateColumns(entity, q, row, opts, unwritten) {
         const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
@@ -241,6 +286,7 @@ export class AbstractQuerier {
         if (!meta.softDelete) {
             throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
         }
+        assertUnversioned(meta, 'restoreMany');
         const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
         return this.updateMany(entity, { ...q, $where }, { [meta.softDelete]: null }, {
             filters: { softDelete: false },
@@ -249,6 +295,7 @@ export class AbstractQuerier {
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     async upsertOne(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
+        assertUnversioned(meta, 'upsertOne');
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
             const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
             adoptReportedIds(meta, rows, ids);
@@ -258,6 +305,7 @@ export class AbstractQuerier {
     }
     async upsertMany(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
+        assertUnversioned(meta, 'upsertMany');
         return this.hooked(entity, 'Upsert', payload, async (rows) => {
             const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
             adoptReportedIds(meta, rows, ids);
@@ -295,6 +343,8 @@ export class AbstractQuerier {
         return changes;
     }
     async saveOne(entity, payload) {
+        // Named here as well as in `saveMany`, so the refusal names the method the caller reached for.
+        assertUnversioned(getMeta(entity), 'saveOne');
         const [id] = await this.saveMany(entity, [payload]);
         return id;
     }
@@ -305,6 +355,7 @@ export class AbstractQuerier {
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
+        assertUnversioned(meta, 'saveMany');
         // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
         // passed, which concatenating the branches did not do.
         const toInsert = [];
@@ -409,6 +460,9 @@ export class AbstractQuerier {
     }
     /** Each parent gets its own referenced row, and its own column pointing at it. */
     async saveManyToOne(entity, relEntity, localColumn, writes) {
+        // Before anything is written: the follow-up that points each row at its new relation carries no
+        // version, and half an insert is worse than a refusal.
+        assertUnversioned(getMeta(entity), 'save a to-one relation of');
         const pointing = writes.filter(({ value }) => value);
         const referenceIds = await this.insertMany(relEntity, pointing.map(({ value }) => value));
         for (const [index, { id }] of pointing.entries()) {

package/dist/querier/queryError.d.ts

@@ -11,7 +11,19 @@ export interface QueryError extends Error {
  * What a failed query ran into, named the same on every engine. `retryable` is a deadlock, a
  * serialization failure, a lock timeout or a busy database: the transaction can simply run again.
  */
-export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'retryable';
+export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable';
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left. `status` is what an HTTP transport answers with.
+ */
+export declare class UqlOptimisticLockError extends Error {
+    readonly expected: unknown;
+    readonly actual: unknown;
+    name: string;
+    readonly status = 409;
+    constructor(message: string, expected: unknown, actual: unknown);
+}
 /**
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
  * read, so it works on any driver error, whether or not a querier saw it first.

package/dist/querier/queryError.js

@@ -1,3 +1,19 @@
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left. `status` is what an HTTP transport answers with.
+ */
+export class UqlOptimisticLockError extends Error {
+    expected;
+    actual;
+    name = 'UqlOptimisticLockError';
+    status = 409;
+    constructor(message, expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -52,6 +68,9 @@ export function queryErrorKind(err) {
     if (typeof err !== 'object' || err === null) {
         return undefined;
     }
+    if (err instanceof UqlOptimisticLockError) {
+        return 'optimisticLock';
+    }
     const { code, errno, number, errorLabels, message } = err;
     const text = typeof message === 'string' ? message : '';
     return (SQLSTATE_KINDS.get(code) ??

package/dist/sqlite/sqliteDialect.js

@@ -35,6 +35,7 @@ export const SQLITE_FEATURES = {
     correlatedWrites: true,
     rowLocks: false,
     rowLockWithWindow: true,
+    nullsOrdering: 'clause',
     rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: true,

package/dist/type/dialect.d.ts

@@ -144,6 +144,11 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly rowLockWithWindow: boolean;
     /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
     readonly rowLockOf: boolean;
+    /**
+     * How a `$sort` states where nulls land: the `NULLS FIRST/LAST` clause, a leading `IS NULL` term
+     * (MySQL, MariaDB), or a leading `CASE` (SQL Server, which has no orderable boolean).
+     */
+    readonly nullsOrdering: 'clause' | 'expression' | 'case';
     /**
      * Whether a fulltext index's heavier column needs a fulltext index of its own to be scored by, as
      * MySQL's `MATCH` does, which reads only an index over exactly its columns.

package/dist/type/entity.d.ts

@@ -6,6 +6,12 @@ import type { Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked,
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
+/**
+ * Brands the property holding an entity's optimistic-lock version, which is what makes an update
+ * payload require it. No conventional name, unlike {@link idKey}: a field merely called `version`
+ * must not start demanding one.
+ */
+export declare const versionKey: unique symbol;
 /** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
 export declare const SOFT_DELETE_FILTER = "softDelete";
 /** A filter name an entity may declare: any but {@link SOFT_DELETE_FILTER}, which a refusal names. */
@@ -30,8 +36,20 @@ export type WritableKey<E> = {
 }[FieldKey<E>];
 /** A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write. */
 export type EntityWrite<E> = EntityData<E, WritableKey<E>>;
-/** A partial write as a caller supplies one: {@link UpdatePayload} without them. */
-export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>>;
+/**
+ * The property an entity brands with {@link versionKey} as its optimistic lock, `never` where it
+ * brands none. The brand is what carries `@Field({ version: true })` to the type level, since a
+ * decorator's options never reach `E`.
+ */
+export type VersionKey<E> = E extends {
+    [versionKey]?: infer K;
+} ? K & FieldKey<E> : never;
+/**
+ * A partial write as a caller supplies one: {@link UpdatePayload} without the fields it cannot write,
+ * and with the version where the entity keeps one - a write that cannot say which row state it read
+ * is refused here rather than silently overwriting whatever is there now.
+ */
+export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>> & Required<Pick<E, VersionKey<E>>>;
 /** The relation names of an entity: every key but its fields and its methods, so the two sets cannot drift. */
 export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
 /**
@@ -247,6 +265,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
      * stamps `new Date()`, anything else is the value or callback stamped, `softDelete: () => Date.now()`.
      */
     readonly softDelete?: true | OnFieldCallback<V>;
+    /**
+     * Makes the column an optimistic lock: an update matches the version its payload carries and writes
+     * the next one, so a write against a row someone else moved on throws instead of overwriting it. The
+     * column is `NOT NULL DEFAULT 0`, and the entity brands the property with {@link versionKey}.
+     */
+    readonly version?: true;
     /** The SQL type, where it differs from the one `type` implies: `type: String, columnType: 'decimal'`. */
     readonly columnType?: ColumnType;
     /** A string column's length. */
@@ -643,6 +667,8 @@ export type EntityMeta<E> = {
     /** Every column of the primary key, in declaration order. */
     ids: readonly IdKey<E>[];
     softDelete?: FieldKey<E>;
+    /** The optimistic lock's column, from `@Field({ version: true })`. */
+    version?: FieldKey<E>;
     /** Named, default-on `$where` filters applied to every query unless bypassed. */
     filters?: Record<string, FilterOptions<E>>;
     fields: {
@@ -729,7 +755,10 @@ export type IndexOptions = Except<EntityIndexMeta, 'columns' | 'where'> & {
  */
 export type EntityIndexOptions<E> = Except<IndexOptions, 'include' | 'where'> & {
     readonly include?: (refs: RefMap<E>) => readonly ColumnRef<FieldKey<E>>[];
-    /** Partial-index predicate. See {@link EntityWhere}. */
+    /**
+     * Partial-index predicate, written as the predicate the query passes: a planner matches the two by
+     * shape, so a hand-written `raw` that means the same thing leaves the index unused. See {@link EntityWhere}.
+     */
     readonly where?: EntityWhere<E>;
 };
 /**

package/dist/type/entity.js

@@ -1,5 +1,11 @@
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export const idKey = Symbol('idKey');
+/**
+ * Brands the property holding an entity's optimistic-lock version, which is what makes an update
+ * payload require it. No conventional name, unlike {@link idKey}: a field merely called `version`
+ * must not start demanding one.
+ */
+export const versionKey = Symbol('versionKey');
 /** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
 export const SOFT_DELETE_FILTER = 'softDelete';
 /** Every SQL column type a field may declare, by family: the unions below and `columnFamily` both read it. */

package/dist/type/query.d.ts

@@ -115,9 +115,16 @@ export type FilterOptions<E = unknown> = {
     readonly onMissing?: 'throw';
 });
 /**
- * direction for the sort.
- */
-export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
+ * direction for the sort, and where nulls land in it.
+ *
+ * Unqualified, each engine has its own answer - Postgres and CockroachDB sort nulls last on `asc`, the
+ * rest sort them first - so a placement is the only portable one. Engines with no `NULLS FIRST/LAST`
+ * emulate it with a leading term, which no index can serve, which is why it is asked for and never
+ * applied by default.
+ */
+export type QuerySortDirection = -1 | 1 | 'asc' | 'desc' | QuerySortNullsDirection;
+/** A {@link QuerySortDirection} stating where nulls land. */
+export type QuerySortNullsDirection = 'ascNullsFirst' | 'ascNullsLast' | 'descNullsFirst' | 'descNullsLast';
 /**
  * Accepted value for a field in `$sort` - either a direction or a vector similarity search.
  */

package/dist/util/dialect.util.js

@@ -69,7 +69,9 @@ export function getSoftDeleteValue(field) {
 /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
 export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
-    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey]);
+    // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
+    // are values a caller meant, and a falsy one was silently never filled.
+    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey] !== undefined);
     if (keys.length === 0) {
         return payloads;
     }

package/dist/util/fieldOption.util.d.ts

@@ -20,6 +20,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly onInsert: '*';
     readonly onUpdate: '*';
     readonly softDelete: '*';
+    readonly version: 'numeric';
     readonly columnType: '*';
     readonly length: 'string';
     readonly precision: 'numeric';
@@ -44,8 +45,15 @@ type InlineRead = (typeof INLINE_READS)[number];
  * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
  * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
  */
-declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement"];
+declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "version"];
 type GeneratedWrite = (typeof GENERATED_WRITES)[number];
+/**
+ * What an optimistic lock cannot use: the querier writes the column on every update and matches the
+ * value the payload carried, so anything else deciding it would be fighting that, and the three that
+ * would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
+ */
+declare const VERSION_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "computed", "stored", "isId"];
+type VersionWrite = (typeof VERSION_WRITES)[number];
 /**
  * The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
  * where every option applies. The runtime half of the decorators' check, so the imperative API and
@@ -68,7 +76,12 @@ type DeadOptions<O> = (O extends {
     readonly nullable: true;
 } ? 'nullable' : never) | (O extends {
     readonly updatable: false;
-} ? 'onUpdate' : never);
+} ? 'onUpdate' : never) | (O extends {
+    readonly version: true;
+} ? VersionWrite : never) | (O extends {
+    readonly version: true;
+    readonly nullable: true;
+} ? 'nullable' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
 type Offending<O> = {
     [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;

package/dist/util/fieldOption.util.js

@@ -21,6 +21,7 @@ const FIELD_OPTION_FAMILY = {
     onInsert: '*',
     onUpdate: '*',
     softDelete: '*',
+    version: 'numeric',
     columnType: '*',
     length: 'string',
     precision: 'numeric',
@@ -46,12 +47,8 @@ const INLINE_READS = [
     'eager',
     'distance',
 ];
-/**
- * What a column the *database* writes cannot use. A stored computed column is a real column - it has
- * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
- * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
- */
-const GENERATED_WRITES = [
+/** Every option that decides what a column holds, or whether it is written at all. */
+const VALUE_DECIDERS = [
     'updatable',
     'onInsert',
     'onUpdate',
@@ -60,19 +57,37 @@ const GENERATED_WRITES = [
     'autoIncrement',
 ];
 /**
- * Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. Only
- * `nullable: true` contradicts a key: `nullable: false` says what the key already is, and rejecting
- * an accurate statement teaches an author to distrust the check.
+ * What a column the *database* writes cannot use. A stored computed column is a real column - it has
+ * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
+ * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
+ */
+const GENERATED_WRITES = [...VALUE_DECIDERS, 'version'];
+/**
+ * What an optimistic lock cannot use: the querier writes the column on every update and matches the
+ * value the payload carried, so anything else deciding it would be fighting that, and the three that
+ * would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
  */
+const VERSION_WRITES = [...VALUE_DECIDERS, 'computed', 'stored', 'isId'];
+/**
+ * Whether `key` is the `nullable: true` a NOT NULL column contradicts. `nullable: false` says what
+ * such a column already is, and rejecting an accurate statement teaches an author to distrust the check.
+ */
+function contradictsNotNull(opts, key) {
+    return key === 'nullable' && opts.nullable === true;
+}
+/** Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. */
 function deadOn(opts, key) {
     if (isInlinedExpression(opts) && !INLINE_READS.some((read) => read === key))
         return 'an inlined computed field';
     if (opts.stored === true && GENERATED_WRITES.some((write) => write === key))
         return 'a stored computed column';
-    if (opts.isId === true && key === 'nullable' && opts.nullable === true)
+    if (opts.isId === true && contradictsNotNull(opts, key))
         return 'a primary key';
     if (opts.updatable === false && key === 'onUpdate')
         return "a field declared 'updatable: false'";
+    if (opts.version === true && (VERSION_WRITES.some((write) => write === key) || contradictsNotNull(opts, key))) {
+        return 'a version field';
+    }
     return undefined;
 }
 /**

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.74.1",
+  "version": "0.76.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -74,12 +74,17 @@ export class Post {
 }
 ```
 
-- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as
-  `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
-- A column is nullable unless it says `nullable: false`, and its property must admit `null` to match:
-  `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
+- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
+- A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
 - `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
+- `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })` states a partial index's filter as the predicate the query passes, never as `raw`: a planner matches the two by shape, so `raw` that means the same thing leaves the index unused.
+- `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, makes the column an
+  optimistic lock: every update payload must carry the version it read (a compile error otherwise), the update
+  matches on it and writes the next one, and a write against a row someone else moved on throws
+  `UqlOptimisticLockError` (`status` 409) instead of overwriting it. Save, upsert and `restoreMany` are refused on such
+  an entity (restore with `updateOneById`, `{ filters: { softDelete: false } }`); `updateMany` writes only the rows
+  still at the version it carries, and delete needs none.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -100,6 +105,10 @@ const users = await pool.findMany(User, {
 
 - The keys are `$select`, `$exclude`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`;
   `$count: { posts: true }` tallies a to-many under `_count` without loading it.
+- `$sort` takes `'asc'`/`1` or `'desc'`/`-1`, and `'ascNullsLast'`, `'ascNullsFirst'`, `'descNullsFirst'` or
+  `'descNullsLast'` to say where nulls land, which reads the same on every engine (emulated where there is no
+  `NULLS FIRST`). Unqualified, each engine keeps its own answer: Postgres and CockroachDB sort nulls last on `asc`,
+  the rest sort them first.
 - `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`,
   `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`,
   `$isNotNull`. `$and`, `$or`, `$not` and `$nor` combine clauses.