uql-orm 0.48.0 → 0.50.0

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

@@ -1,5 +1,5 @@
 import { type HttpMethod } from '../../http/contract.js';
-import type { EntityData, EntityId, FieldKey, IdValue, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, RelationKey, RequestCountedSuccessResponse, RequestSuccessResponse, Type, UpdatePayload } from '../../type/index.js';
+import type { EntityData, EntityId, FieldKey, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, RelationKey, RequestCountedSuccessResponse, RequestSuccessResponse, Type, UpdatePayload, WrittenId } from '../../type/index.js';
 import type { ClientQuerier, RequestFindOptions, RequestOptions } from '../type/index.js';
 export type HttpQuerierDefaults = {
     /**
@@ -34,12 +34,12 @@ export declare class HttpQuerier implements ClientQuerier {
         count?: number;
         data: boolean;
     }>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E> | undefined>>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): Promise<RequestSuccessResponse<(IdValue<E> | undefined)[]>>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<WrittenId<E> | undefined>>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): Promise<RequestSuccessResponse<(WrittenId<E> | undefined)[]>>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<EntityId<E> | undefined>>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): Promise<RequestSuccessResponse<(EntityId<E> | undefined)[]>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<WrittenId<E> | undefined>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): Promise<RequestSuccessResponse<(WrittenId<E> | undefined)[]>>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
     getBasePath<E>(entity: Type<E>): string;

package/dist/browser/type/clientQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, IdValue, QuerierResult, QueryOptions, SharedQuerier, Type } from '../../type/index.js';
+import type { EntityData, QuerierResult, QueryOptions, SharedQuerier, Type, WrittenId } from '../../type/index.js';
 import type { RequestOptions } from './request.js';
 /**
  * Client-side querier: {@link SharedQuerier} on the `'client'` transport, so every result arrives in
@@ -7,8 +7,8 @@ import type { RequestOptions } from './request.js';
  * @see UniversalQuerier for the same operations with direct return types.
  */
 export interface ClientQuerier extends SharedQuerier<'client', RequestOptions, QueryOptions & RequestOptions> {
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): QuerierResult<'client', IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): QuerierResult<'client', (IdValue<E> | undefined)[]>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): QuerierResult<'client', EntityId<E> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): QuerierResult<'client', (EntityId<E> | undefined)[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): QuerierResult<'client', WrittenId<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): QuerierResult<'client', (WrittenId<E> | undefined)[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>, opts?: RequestOptions): QuerierResult<'client', WrittenId<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions): QuerierResult<'client', (WrittenId<E> | undefined)[]>;
 }

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

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

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

@@ -9,10 +9,10 @@
     "import type { Type, UniversalQuerier } from '../type/index.js';\n// the specific util modules, not the barrel, so the browser bundle does not pull in entity metadata\nimport { getKeys } from '../util/object.util.js';\nimport { kebabCase } from '../util/string.util.js';\n\ntype RouteShape = {\n  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n  readonly path: '' | `/${string}`;\n};\n\n/**\n * Single source of truth for the CRUD-over-HTTP surface, shared by server adapters and the browser client.\n * Keys are constrained to {@link UniversalQuerier} method names, so renaming a querier method\n * (or routing a non-existent one) is a compile error.\n */\nexport const CRUD_ROUTES = {\n  findMany: { method: 'GET', path: '' },\n  findOne: { method: 'GET', path: '/one' },\n  count: { method: 'GET', path: '/count' },\n  findOneById: { method: 'GET', path: '/:id' },\n  insertOne: { method: 'POST', path: '' },\n  insertMany: { method: 'POST', path: '/many' },\n  saveOne: { method: 'PUT', path: '' },\n  saveMany: { method: 'PUT', path: '/many' },\n  updateMany: { method: 'PATCH', path: '' },\n  updateOneById: { method: 'PATCH', path: '/:id' },\n  deleteOneById: { method: 'DELETE', path: '/:id' },\n  deleteMany: { method: 'DELETE', path: '' },\n} as const satisfies Partial<Record<keyof UniversalQuerier, RouteShape>>;\n\nexport type CrudOperation = keyof typeof CRUD_ROUTES;\n\nexport type CrudRoute = (typeof CRUD_ROUTES)[CrudOperation];\n\n/**\n * `QUERY` (RFC 10008) is an alternate transport for the read operations: same semantics as the\n * GET routes, but the JSON query travels in the request body instead of the query string,\n * avoiding URL-length limits for large queries.\n */\nexport type HttpMethod = CrudRoute['method'] | 'QUERY';\n\nconst CRUD_OPS = getKeys(CRUD_ROUTES);\n\n// derived from CRUD_ROUTES (the literal-path GET routes) so the sub-paths live in exactly one place\nconst QUERY_READ_OPS: ReadonlyMap<string, CrudOperation> = new Map(\n  CRUD_OPS.filter((op) => CRUD_ROUTES[op].method === 'GET' && CRUD_ROUTES[op].path !== '/:id').map((op) => [\n    CRUD_ROUTES[op].path,\n    op,\n  ]),\n);\n\n/**\n * URL segment for an entity, e.g. `entityPath(UserProfile) === 'user-profile'`.\n */\nexport function entityPath<E>(entity: Type<E>): string {\n  return kebabCase(entity.name);\n}\n\nexport type RouteMatch = {\n  readonly op: CrudOperation;\n  /**\n   * the resolved transport method - differs from the op's canonical route method for QUERY.\n   */\n  readonly method: HttpMethod;\n  readonly id?: string;\n};\n\n/**\n * Resolve a (method, sub-path) pair to a CRUD operation. Literal sub-paths win over `:id`.\n */\nexport function matchRoute(method: string, subPath: string | undefined): RouteMatch | undefined {\n  const raw = method.toUpperCase();\n  const literal = subPath === undefined ? '' : `/${subPath}`;\n  if (raw === 'QUERY') {\n    const op = QUERY_READ_OPS.get(literal);\n    return op ? { op, method: 'QUERY' } : undefined;\n  }\n  // HEAD reads like GET per HTTP semantics; the server runtime omits the response body\n  const verb = raw === 'HEAD' ? 'GET' : raw;\n  let idOp: CrudOperation | undefined;\n  for (const op of CRUD_OPS) {\n    const route = CRUD_ROUTES[op];\n    if (route.method !== verb) {\n      continue;\n    }\n    if (route.path === literal) {\n      return { op, method: route.method };\n    }\n    if (route.path === '/:id') {\n      idOp = op;\n    }\n  }\n  return idOp && subPath !== undefined ? { op: idOp, method: CRUD_ROUTES[idOp].method, id: subPath } : undefined;\n}\n\nexport type RequestErrorResponse = {\n  readonly error: {\n    readonly message: string;\n    readonly code: number;\n  };\n};\n\n/**\n * Map a thrown error to the wire error envelope. Honors a numeric `status` on the error\n * (e.g. hooks throwing 403), defaults to 500; `code` mirrors the HTTP status.\n */\nexport function toErrorResponse(err: unknown): { status: number; body: RequestErrorResponse } {\n  const status = err instanceof Error && 'status' in err && typeof err.status === 'number' ? err.status : 500;\n  const message = err instanceof Error ? err.message : 'Internal Server Error';\n  return { status, body: { error: { message, code: status } } };\n}\n",
     "import type { FieldKey, IdKey, JsonFieldPaths, RelationKey, RelationTarget } 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 { 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   * prefix the query with this.\n   */\n  prefix?: string;\n  /**\n   * automatically infer the prefix for the query.\n   */\n  autoPrefix?: boolean;\n};\n\nexport type QuerySelectOptions = {\n  /**\n   * prefix the query with this.\n   */\n  prefix?: string;\n  /**\n   * automatically add the prefix for the alias.\n   */\n  autoPrefixAlias?: boolean;\n};\n\n/**\n * Query field selection - `{ name: true }` whitelists specific fields. Fields only: a relation is a\n * sub-query rather than a projection flag, and a whitelist naming one could not say whether the\n * scalars come with it. Relations go in `$populate`.\n */\nexport type QuerySelect<E> = {\n  [K in FieldKey<E>]?: BooleanLike;\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> = QuerySelect<E> | readonly QueryRaw[];\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> = {\n  [K in RelationKey<E>]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;\n};\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. One statement per relation named here, batched over every parent at once, so it\n * stays flat however many rows the read returned. Comes back under `_count`, which keeps it clear of\n * a relation of the same name that `$populate` filled with rows.\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\nexport type QueryCount<E> = {\n  [K in ToManyRelationKey<E>]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;\n};\n\n/**\n * query conflict paths - subset of field keys used to detect upsert conflicts.\n */\nexport type QueryConflictPaths<E> = {\n  [K in FieldKey<E>]?: true;\n};\n\n/**\n * Options to populate a relation declared as `V`, by its cardinality.\n */\nexport type QueryPopulateRelationOptions<V> = (IsMany<V> extends true\n  ? // `$lock` is statement-level, so it is excluded here rather than being silently ignored per\n    // relation. `QueryUnique` is a `Pick` and already leaves it out.\n    Except<Query<RelationTarget<V>>, '$lock'>\n  : QueryUnique<RelationTarget<V>>) & {\n  $required?: boolean;\n};\n\n/**\n * Ambient per-request context (e.g. `{ tenantId, userId, roles }`) resolved by parameterized\n * filters. Set with `withContext(ctx, cb)`. It's an `interface` (not a type alias) so you can type\n * your keys once via declaration merging and get them typed wherever context is read:\n *\n * ```ts\n * declare module 'uql-orm' {\n *   interface UqlContext { tenantId: number; userId: string }\n * }\n * ```\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 FilterCondition<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 condition: FilterCondition<E>;\n  /** Applied to every query unless bypassed via `QueryOptions.filters`. Defaults to `true`. */\n  readonly default?: boolean;\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.\n   */\n  readonly security?: boolean;\n  /** What to do when the condition returns `undefined`. Defaults to `skip`, or `throw` for `security`. */\n  readonly onMissing?: FilterOnMissing;\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 * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order\n * it by, and joining one in would duplicate the parent instead. Order those inside `$populate`.\n */\ntype ToOneRelationKey<E> = { [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K }[RelationKey<E>];\n\n/** The relation names a parent holds many rows of, which a populated query fills with a list. */\ntype ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;\n\n/**\n * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,\n * like `QueryWhereMap`), relation sort via nested objects, and vector similarity search on\n * `number[]` fields. `Vector` is what confines a vector search to the level the statement ranks:\n * the queried entity. A relation of it is joined in one row at a time, so there is nothing to rank\n * there - the SQL dialects throw, and MongoDB would quietly drop it, so this is its only guard.\n *\n * One mapped type over the three key sets rather than three intersected. The sets are disjoint - a\n * JSON path is dotted, and a field key cannot also be a relation key - and an assignability check\n * against an intersection is repeated per constituent, which made this the single most expensive\n * type in the package to check.\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\nexport type QuerySortMap<E, Vector extends boolean = true> = {\n  [K in FieldKey<E> | JsonFieldPaths<E> | RelationKey<E>]?: K extends RelationKey<E>\n    ? // A to-many has no single value to order by, so what it offers instead is its own size.\n      IsMany<E[K]> extends true\n      ? QuerySortByCount\n      : QuerySortMap<RelationTarget<E[K]>, false>\n    : K extends FieldKey<E>\n      ? Vector extends true\n        ? NonNullable<E[K]> extends readonly number[]\n          ? QuerySortValue\n          : QuerySortDirection\n        : QuerySortDirection\n      : QuerySortDirection;\n};\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> = {\n  /**\n   * filtering options.\n   */\n  $where?: QueryWhere<E>;\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> = QueryFilter<E> & 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> = QueryPage<E> & {\n  /**\n   * sorting options.\n   */\n  $sort?: QuerySortMap<E>;\n};\n\n/**\n * query options.\n */\nexport type Query<E> = {\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>;\n\n  /**\n   * relation population options.\n   */\n  $populate?: QueryPopulate<E>;\n\n  /**\n   * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.\n   */\n  $count?: QueryCount<E>;\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   * take a row-level lock on the rows this query returns (`SELECT ... FOR UPDATE`). Needs an open\n   * transaction: outside one the statement commits and drops the lock before the caller can act on\n   * the rows, so it is rejected rather than emitted. Locks only the queried entity, never anything\n   * reached through `$populate`. SQL only; MongoDB and the SQLite family reject it.\n   *\n   * Declared here rather than on {@link QuerySearch}, which `update`/`delete` take: that placement\n   * is what keeps the clause off those statements at the type level.\n   */\n  $lock?: QueryLock;\n\n  /**\n   * how many candidates an approximate-nearest-neighbour index explores before ranking, for a vector\n   * search. Higher trades speed for recall; the default is whatever the engine's own is, which is\n   * tuned for speed. Ignored where the search is exact (SQLite, libSQL and Turso scan every row) and\n   * where the field carries no ANN index, since there is nothing to widen.\n   *\n   * The units are the index's, not UQL's, so the number is not comparable across index types: it\n   * becomes `hnsw.ef_search` or `ivfflat.probes` on Postgres, `mhnsw_ef_search` on MariaDB, and\n   * `numCandidates` on MongoDB Atlas. On Postgres it needs an open transaction, since a `SET LOCAL`\n   * outside one applies to nothing.\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>;\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 * `Query`'s clauses grouped by the shape of their value - what a parser reading one off the wire and\n * a validator checking a relation's own query both need, and what each used to enumerate for itself.\n * Declared beside the type they describe so the two cannot drift, and `satisfies` fails the build\n * rather than the runtime if a clause is ever renamed.\n *\n * `$lock` belongs to no group on purpose: it is the one clause neither a wire query nor a relation's\n * query accepts, so leaving it out is what excludes it from both.\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, never a relation's own query - the mirror of\n * `$lock`, which neither takes. Counting a relation is batched over the rows a read returned, and a\n * populated relation's rows are assembled after that, so there is nothing for a nested one to count.\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/**\n * options to get a single record.\n */\nexport type QueryOne<E> = Except<Query<E>, '$limit'>;\n\n/**\n * options to get an unique record.\n */\nexport type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$populate' | '$where'>;\n\n/**\n * The clauses that decide a row's shape, captured from the query as written: the field names\n * `$select` and `$exclude` list, the value those maps carry (a falsy one subtracts instead of\n * selecting, as it does at runtime, and a widened map is how a projection that is not statically\n * known announces itself), and the relation names `$populate` lists.\n *\n * Each is captured as a *key set* rather than as the map itself, which is what keeps the checks\n * intact: TypeScript skips excess-property checking on a naked type parameter, so a captured map\n * would take a typo'd key without a word, while a captured key set makes that typo fail its own\n * `FieldKey<E>` / `RelationKey<E>` constraint. Every other clause - `$where`, `$sort`, and each\n * populated relation's own query - stays the concrete {@link Query} it is today.\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> = QueryStreamProjection<E, S, V, X, P> & {\n  // Intersecting the captured names with {@link QueryCount}'s own leaves a to-one relation no key\n  // here at all, so counting one is an excess property rather than a value to check. Narrowing the\n  // key rather than the value also instantiates `QueryCount<E>` once instead of once per counted\n  // relation, worth ~87k instantiations in a consuming project.\n  $count?: { [K in C & keyof QueryCount<E>]?: QueryCount<E>[K] };\n};\n\n/**\n * {@link QueryProjection} without `$count`, which a stream cannot honor. Split out rather than\n * subtracted afterwards: an optional key is a *known* key even when its value maps over `never`, so\n * a statement that must not take the clause has to be built without it in the first place.\n * @internal\n */\ntype QueryStreamProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = {\n  $select?: { [K in S]?: V } | readonly QueryRaw[];\n  $exclude?: { [K in X]?: V };\n  $populate?: { [K in P]?: QueryPopulate<E>[K] };\n};\n\n/**\n * A {@link QueryProjected} a stream can honor: no `$count`, which is batched over a result set a\n * stream never holds all of.\n */\nexport type QueryStreamProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>> = Except<\n  Query<E>,\n  '$count'\n> &\n  QueryStreamProjection<E, S, V, X, P>;\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> = Query<E> & QueryProjection<E, S, V, X, P, C>;\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> = QueryOne<E> & QueryProjection<E, S, V, X, P, C>;\n\n/**\n * The keys a query comes back with, mirroring what the runtime projects: the fields a positive\n * `$select` names, or every field minus what a falsy `$select` entry or a truthy `$exclude` entry\n * subtracts, plus the relations `$populate` asked for. A positive `$select` wins outright, which is\n * why `$exclude` is only read on the branch where there is none.\n * @internal\n */\ntype ProjectedKeys<E, S, V, X, P, C> =\n  | ([V] extends [false | 0] ? Exclude<FieldKey<E>, S> : [S] extends [never] ? Exclude<FieldKey<E>, X> : S)\n  | P\n  // Populating a relation keeps the id whatever the projection says, and so does counting one: both\n  // assemble their result by it (`selectFields` puts it back, as does MongoDB's `pipelineProjection`).\n  | ([P | C] extends [never] ? never : NamedIdKey<E>);\n\n/**\n * The id key when it can be named, and nothing when it cannot: {@link IdKey} widens to *every* field\n * for an entity whose id is neither branded nor called `id`/`_id`/`uuid`, and adding that back would\n * hand the caller a row claiming fields the query never fetched. Missing an id costs a `$select`\n * entry; promising absent fields is the bug this type exists to prevent.\n * @internal\n */\ntype NamedIdKey<E> = [FieldKey<E>] extends [IdKey<E>] ? never : IdKey<E>;\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 row of a find result: the entity narrowed to the fields the query projected, plus the relations\n * it populated - reading anything the query left out is a compile error rather than a silent\n * `undefined`. Modifiers are preserved, so an optional field stays optional. Name a projected row\n * with it where a helper has to take one: `QueryFindResult<User, 'id' | 'name'>`.\n *\n * The entity itself when the query projects nothing, when it uses a raw-projection array (columns,\n * not fields), and when the projection is not uniform - a `Query<E>` built elsewhere, or a map\n * mixing selected and subtracted entries, whose positive keys inference cannot recover. Relations\n * keep their declared type: narrowing them means capturing their queries as maps, which costs those\n * queries their own checks.\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, C> & 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, C>, 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/**\n * result of an update operation.\n */\nexport type QueryUpdateResult = {\n  /**\n   * number of affected records.\n   */\n  changes?: number;\n  /**\n   * the inserted IDs, in insertion order. Exact on `'returning'` dialects; inferred from the\n   * driver header on the others (see {@link InsertIdSource}), and empty when the header\n   * reports no generated ID.\n   */\n  ids?: PrimaryKey[];\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 { Query, QueryOptions } 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 specific util module, not the barrel, so the browser bundle does not pull in entity metadata\nimport { getKeys } 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 Query<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 Query<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> = {}): Query<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\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 Query<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 ? JSON.stringify(value) : String(value));\n  }\n  const qs = params.toString();\n  return qs ? `?${qs}` : '';\n}\n",
-    "import { CRUD_ROUTES, entityPath, type HttpMethod } from '../../http/contract.js';\nimport { stringifyQuery } from '../../http/query.js';\nimport type {\n  EntityData,\n  EntityId,\n  FieldKey,\n  IdValue,\n  Query,\n  QueryFilter,\n  QueryFindResult,\n  QueryOneProjected,\n  QueryOptions,\n  QueryPage,\n  QueryProjected,\n  QuerySearch,\n  RelationKey,\n  RequestCountedSuccessResponse,\n  RequestSuccessResponse,\n  Type,\n  UpdatePayload,\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/**\n * The id as one path segment.\n *\n * A composite key has no spelling here yet - the route is `/:id`, and how several columns share one\n * segment is a serialization to invent rather than copy. Refused rather than interpolated, which\n * would have sent `[object Object]` for the server to reject. Its callers are `async` so this\n * surfaces as a rejection, like every other failure they can hand back.\n */\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>,\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>,\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>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestSuccessResponse<QueryFindResult<E, S, V, X, P, C>[]>> {\n    const data: Query<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>,\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>, 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>, 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: EntityData<E>, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return post<IdValue<E> | undefined>(basePath, payload, this.buildOptions(opts));\n  }\n\n  insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return post<(IdValue<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: UpdatePayload<E>,\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>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: RequestOptions) {\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: EntityData<E>, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<EntityId<E> | undefined>(basePath, payload, this.buildOptions(opts));\n  }\n\n  saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<(EntityId<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>, 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 { CRUD_ROUTES, entityPath, type HttpMethod } from '../../http/contract.js';\nimport { stringifyQuery } from '../../http/query.js';\nimport type {\n  EntityData,\n  EntityId,\n  FieldKey,\n  Query,\n  QueryFilter,\n  QueryFindResult,\n  QueryOneProjected,\n  QueryOptions,\n  QueryPage,\n  QueryProjected,\n  QuerySearch,\n  RelationKey,\n  RequestCountedSuccessResponse,\n  RequestSuccessResponse,\n  Type,\n  UpdatePayload,\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/**\n * The id as one path segment.\n *\n * A composite key has no spelling here yet - the route is `/:id`, and how several columns share one\n * segment is a serialization to invent rather than copy. Refused rather than interpolated, which\n * would have sent `[object Object]` for the server to reject. Its callers are `async` so this\n * surfaces as a rejection, like every other failure they can hand back.\n */\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>,\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>,\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>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestSuccessResponse<QueryFindResult<E, S, V, X, P, C>[]>> {\n    const data: Query<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>,\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>, 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>, 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: EntityData<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: EntityData<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: UpdatePayload<E>,\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>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: RequestOptions) {\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: EntityData<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: EntityData<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>, 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": "AAEA,IAAM,EAAkC,CAAC,EAElC,SAAS,CAAM,CAAC,EAAyC,CAC9D,QAAW,KAAe,EACxB,EAAY,CAAY,EAIrB,SAAS,CAAE,CAAC,EAAiC,CAClD,EAAa,KAAK,CAAE,EACpB,IAAM,EAAQ,EAAa,OAAS,EACpC,MAAO,IAAY,CACjB,EAAa,OAAO,EAAO,CAAC,GCLzB,MAAM,UAAqB,KAAM,CAG3B,OAFX,WAAW,CACT,EACS,EACT,CACA,MAAM,CAAO,EAFJ,cAGT,KAAK,KAAO,eAEhB,CAEO,SAAS,CAAM,CAAC,EAAa,EAAuB,CACzD,OAAO,EAAW,EAAK,CAAE,OAAQ,KAAM,EAAG,CAAI,EAGzC,SAAS,CAAO,CAAC,EAAa,EAAkB,EAAuB,CAC5E,IAAM,EAAO,KAAK,UAAU,CAAO,EACnC,OAAO,EAAW,EAAK,CAAE,OAAQ,OAAQ,MAAK,EAAG,CAAI,EAGhD,SAAS,CAAQ,CAAC,EAAa,EAAkB,EAAuB,CAC7E,IAAM,EAAO,KAAK,UAAU,CAAO,EACnC,OAAO,EAAW,EAAK,CAAE,OAAQ,QAAS,MAAK,EAAG,CAAI,EAGjD,SAAS,CAAM,CAAC,EAAa,EAAkB,EAAuB,CAC3E,IAAM,EAAO,KAAK,UAAU,CAAO,EACnC,OAAO,EAAW,EAAK,CAAE,OAAQ,MAAO,MAAK,EAAG,CAAI,EAG/C,SAAS,CAAS,CAAC,EAAa,EAAuB,CAC5D,OAAO,EAAW,EAAK,CAAE,OAAQ,QAAS,EAAG,CAAI,EAQ5C,SAAS,CAAQ,CAAC,EAAa,EAAkB,EAAuB,CAC7E,IAAM,EAAO,KAAK,UAAU,CAAO,EACnC,OAAO,EAAW,EAAK,CAAE,OAAQ,QAAS,MAAK,EAAG,CAAI,EAGxD,SAAS,CAAU,CAAC,EAAa,EAAmB,EAAuB,CAQzE,GAPA,EAAO,CAAE,MAAO,QAAS,MAAK,CAAC,EAE/B,EAAK,QAAU,CACb,OAAQ,mBACR,eAAgB,sBACb,GAAM,OACX,EACI,GAAM,OACR,EAAK,OAAS,EAAK,OAGrB,OAAO,MAAM,EAAK,CAAI,EACnB,KAAK,CAAC,IACL,EAAQ,KAAK,EAAE,KAAK,CAAC,IAAkB,CAErC,GADkB,EAAQ,QAAU,KAAO,EAAQ,OAAS,IAG1D,OADA,EAAO,CAAE,MAAO,UAAW,MAAK,CAAC,EAC1B,EAET,IAAM,EAAY,EACZ,EAAQ,CACZ,QAAS,GAAW,OAAO,SAAW,EAAQ,WAC9C,KAAM,GAAW,OAAO,MAAQ,EAAQ,MAC1C,EAEA,MADA,EAAO,CAAE,MAAO,QAAS,QAAO,MAAK,CAAC,EAChC,IAAI,EAAa,EAAM,QAAS,EAAM,IAAI,EACjD,CACH,EACC,QAAQ,IAAM,CACb,EAAO,CAAE,MAAO,WAAY,MAAK,CAAC,EACnC,ECxBE,SAAS,CAAyB,CAAC,EAA8B,CACtE,OAAO,EAAO,OAAO,KAAK,CAAG,EAA6B,CAAC,EAuBtD,SAAS,CAAU,CAAC,EAAyB,CAClD,GAAI,OAAO,IAAU,UAAY,IAAU,KACzC,MAAO,GAET,GAAI,MAAM,QAAQ,CAAK,EACrB,MAAO,GAKT,IAAM,EAAQ,OAAO,eAAe,CAAK,EACzC,OAAO,IAAU,OAAO,WAAa,IAAU,KC9F1C,SAAS,CAAS,CAAC,EAAqB,CAC7C,IAAI,EAAO,EAAI,OAAO,CAAC,EAAE,YAAY,EACrC,QAAS,EAAI,EAAG,EAAI,EAAI,OAAQ,EAAE,EAChC,GAAQ,EAAI,KAAO,EAAI,GAAG,YAAY,EAAI,IAAM,EAAI,GAAG,YAAY,EAAI,EAAI,GAE7E,OAAO,ECUF,IAAM,EAAc,CACzB,SAAU,CAAE,OAAQ,MAAO,KAAM,EAAG,EACpC,QAAS,CAAE,OAAQ,MAAO,KAAM,MAAO,EACvC,MAAO,CAAE,OAAQ,MAAO,KAAM,QAAS,EACvC,YAAa,CAAE,OAAQ,MAAO,KAAM,MAAO,EAC3C,UAAW,CAAE,OAAQ,OAAQ,KAAM,EAAG,EACtC,WAAY,CAAE,OAAQ,OAAQ,KAAM,OAAQ,EAC5C,QAAS,CAAE,OAAQ,MAAO,KAAM,EAAG,EACnC,SAAU,CAAE,OAAQ,MAAO,KAAM,OAAQ,EACzC,WAAY,CAAE,OAAQ,QAAS,KAAM,EAAG,EACxC,cAAe,CAAE,OAAQ,QAAS,KAAM,MAAO,EAC/C,cAAe,CAAE,OAAQ,SAAU,KAAM,MAAO,EAChD,WAAY,CAAE,OAAQ,SAAU,KAAM,EAAG,CAC3C,EAaM,EAAW,EAAQ,CAAW,EAG9B,EAAqD,IAAI,IAC7D,EAAS,OAAO,CAAC,IAAO,EAAY,GAAI,SAAW,OAAS,EAAY,GAAI,OAAS,MAAM,EAAE,IAAI,CAAC,IAAO,CACvG,EAAY,GAAI,KAChB,CACF,CAAC,CACH,EAKO,SAAS,CAAa,CAAC,EAAyB,CACrD,OAAO,EAAU,EAAO,IAAI,ECyRvB,IAAM,EAAuB,CAClC,UACA,YACA,WACA,SACA,OACF,EAOa,EAA4B,CAAC,QAAQ,EAErC,EAAuB,CAAC,QAAS,QAAQ,EAOzC,EAA4B,CAAC,aAAa,EAE1C,EAAwB,CAAC,WAAW,ECtVjD,IAAM,EAAqB,IAAI,IAAY,CACzC,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,aACA,OACF,CAAuF,EA2DhF,SAAS,CAAc,CAAC,EAAyC,CACtE,GAAI,CAAC,EACH,MAAO,GAET,IAAM,EAAS,IAAI,gBACnB,QAAW,KAAO,EAAQ,CAAK,EAAG,CAChC,IAAM,EAAQ,EAAM,GACpB,GAAI,IAAU,OACZ,SAEF,EAAO,OAAO,EAAK,OAAO,IAAU,UAAY,IAAU,KAAO,KAAK,UAAU,CAAK,EAAI,OAAO,CAAK,CAAC,EAExG,IAAM,EAAK,EAAO,SAAS,EAC3B,OAAO,EAAK,IAAI,IAAO,GC7CzB,SAAS,CAAY,CAAC,EAAiB,EAAyB,CAC9D,GAAI,CAAC,EAAW,CAAE,EAChB,MAAU,UAAU,IAAI,EAAO,yEAAyE,EAE1G,OAAO,OAAO,CAAE,EAGX,MAAM,CAAqC,CAErC,SACA,SAFX,WAAW,CACA,EACA,EAAgC,CAAC,EAC1C,CAFS,gBACA,qBAGL,YAOL,CACC,EACA,EACA,EACA,EACgF,CAChF,IAAM,EAAW,KAAK,YAAY,CAAM,EAClC,EAAK,EAAe,CAAC,EAC3B,OAAO,EACL,GAAG,KAAY,EAAU,EAAQ,CAAE,IAAI,IACvC,KAAK,aAAa,CAAI,CACxB,EAGF,OAOC,CACC,EACA,EACA,EACgF,CAChF,OAAO,KAAK,KACV,GAAG,KAAK,YAAY,CAAM,IAAI,EAAY,QAAQ,OAClD,EACA,CACF,EAGF,QAOC,CACC,EACA,EACA,EACsE,CACtE,IAAM,EAAuC,IAAK,CAAE,EACpD,GAAI,GAAM,MACR,EAAK,MAAQ,GAEf,OAAO,KAAK,KAA0C,KAAK,YAAY,CAAM,EAAG,EAAM,CAAI,OAGtF,iBAOL,CACC,EACA,EACA,EAC6E,CAC7E,IAAM,EAAW,MAAM,KAAK,SAAS,EAAQ,EAAG,IAAK,EAAM,MAAO,EAAK,CAAC,EACxE,GAAI,OAAO,EAAS,QAAU,SAC5B,MAAU,UAAU,gDAAgD,EAEtE,MAAO,IAAK,EAAU,MAAO,EAAS,KAAM,EAG9C,KAAuB,CAAC,EAAiB,EAAkB,EAAuB,CAChF,OAAO,KAAK,KAAa,GAAG,KAAK,YAAY,CAAM,IAAI,EAAY,MAAM,OAAQ,EAAG,CAAI,OAIpF,OAAwB,CAAC,EAAiB,EAAoB,EAAuB,CACzF,IAAM,EAAM,MAAM,KAAK,MAAM,EAAQ,IAAK,EAAG,OAAQ,CAAE,EAAG,CAAI,EAC9D,MAAO,IAAK,EAAK,KAAM,EAAI,KAAO,CAAE,EAGtC,SAA2B,CAAC,EAAiB,EAAwB,EAAuB,CAC1F,IAAM,EAAW,KAAK,YAAY,CAAM,EACxC,OAAO,EAA6B,EAAU,EAAS,KAAK,aAAa,CAAI,CAAC,EAGhF,UAA4B,CAAC,EAAiB,EAA0B,EAAuB,CAC7F,IAAM,EAAW,KAAK,YAAY,CAAM,EACxC,OAAO,EACL,GAAG,IAAW,EAAY,WAAW,OACrC,EACA,KAAK,aAAa,CAAI,CACxB,OAGI,cAA+B,CACnC,EACA,EACA,EACA,EACA,CACA,IAAM,EAAW,KAAK,YAAY,CAAM,EACxC,OAAO,EAAc,GAAG,KAAY,EAAU,EAAQ,CAAE,IAAK,EAAS,KAAK,aAAa,CAAI,CAAC,EAG/F,UAA4B,CAAC,EAAiB,EAAmB,EAA2B,EAAuB,CACjH,IAAM,EAAW,KAAK,YAAY,CAAM,EAClC,EAAK,EAAe,CAAC,EAC3B,OAAO,EAAc,GAAG,IAAW,IAAM,EAAS,KAAK,aAAa,CAAI,CAAC,EAG3E,OAAyB,CAAC,EAAiB,EAAwB,EAAuB,CACxF,IAAM,EAAW,KAAK,YAAY,CAAM,EACxC,OAAO,EAA6B,EAAU,EAAS,KAAK,aAAa,CAAI,CAAC,EAGhF,QAA0B,CAAC,EAAiB,EAA0B,EAAuB,CAC3F,IAAM,EAAW,KAAK,YAAY,CAAM,EACxC,OAAO,EACL,GAAG,IAAW,EAAY,SAAS,OACnC,EACA,KAAK,aAAa,CAAI,CACxB,OAGI,cAA+B,CAAC,EAAiB,EAAiB,EAAsC,CAAC,EAAG,CAChH,IAAM,EAAW,KAAK,YAAY,CAAM,EAClC,EAAK,EAAK,WAAa,EAAe,CAAE,WAAY,EAAK,UAAW,CAAC,EAAI,GAC/E,OAAO,EAAe,GAAG,KAAY,EAAU,EAAQ,CAAE,IAAI,IAAM,KAAK,aAAa,CAAI,CAAC,EAG5F,UAA4B,CAAC,EAAiB,EAAmB,EAAsC,CAAC,EAAG,CACzG,IAAM,EAAW,KAAK,YAAY,CAAM,EAClC,EAAK,EAAe,EAAK,WAAa,IAAK,EAAG,WAAY,EAAK,UAAW,EAAI,CAAC,EACrF,OAAO,EAAe,GAAG,IAAW,IAAM,KAAK,aAAa,CAAI,CAAC,EAGnE,WAAc,CAAC,EAAiB,CAC9B,MAAO,GAAG,KAAK,aAAa,KAAK,SAAS,YAAc,GAAY,CAAM,IAGlE,IAAO,CAAC,EAAc,EAAwC,EAAuB,CAC7F,GAAI,KAAK,SAAS,aAAe,QAC/B,OAAO,EAAa,EAAM,GAAK,CAAC,EAAG,KAAK,aAAa,CAAI,CAAC,EAE5D,OAAO,EAAO,GAAG,IAAO,EAAe,CAAC,IAAK,KAAK,aAAa,CAAI,CAAC,EAG5D,YAAY,CAAC,EAAmD,CACxE,GAAI,CAAC,KAAK,SAAS,SAAW,CAAC,GAAM,QACnC,OAAO,EAET,MAAO,IAAK,EAAM,QAAS,IAAK,KAAK,SAAS,WAAY,GAAM,OAAQ,CAAE,EAE9E,CChOA,IAAI,EAAiC,CACnC,WAAY,IAAM,IAAI,EAAY,MAAM,CAC1C,EAEO,SAAS,EAA2C,CAAC,EAAS,CACnE,EAAc,EAGT,SAAS,CAAc,EAAsB,CAClD,OAAO,EAGF,SAAS,EAAU,EAAkB,CAC1C,OAAO,EAAe,EAAE,WAAW",
-  "debugId": "565BC245D18F9E8464756E2164756E21",
+  "mappings": "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",
+  "debugId": "0C3AE5E71CFBDD6864756E2164756E21",
   "names": []
 }

package/dist/dialect/abstractSqlDialect.d.ts

@@ -104,7 +104,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * The alias names one column, and every column of a composite came from the caller, so there is no
      * id the statement could report that the payload does not already carry - the same "no id to give"
      * a `firstId` dialect already answers with. Empty rather than a refusal, so an insert and an upsert
-     * of a composite row both run; `idOf(meta, row)` names such a row.
+     * of a composite row both run, and the querier names those rows with `idOf`.
      */
     returningId<E>(meta: EntityMeta<E>): string;
     /** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */

package/dist/dialect/abstractSqlDialect.js

@@ -150,7 +150,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * The alias names one column, and every column of a composite came from the caller, so there is no
      * id the statement could report that the payload does not already carry - the same "no id to give"
      * a `firstId` dialect already answers with. Empty rather than a refusal, so an insert and an upsert
-     * of a composite row both run; `idOf(meta, row)` names such a row.
+     * of a composite row both run, and the querier names those rows with `idOf`.
      */
     returningId(meta) {
         const expression = this.returningIdExpression(meta);

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

@@ -1,4 +1,4 @@
-import type { EntityGetter, FieldOptions, FieldType, IdValue, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { EntityGetter, FieldOptions, FieldType, IdValue, NamedIdKey, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
@@ -54,16 +54,28 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
     references: EntityGetter;
 }) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
- * Declares the primary key, checked the same way as `@Field`.
+ * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
+ * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,
+ * `EntityId` and every by-id method are then typed against a column that is not the key.
+ */
+type KeyIsNamed<This> = [NamedIdKey<This>] extends [never] ? {
+    readonly __keyNeedsIdKeyBrand: true;
+} : 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;
+/**
+ * Declares the primary key, checked the same way as `@Field` and additionally against the class:
+ * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
  *
  * @example `@Id({ type: Number }) id?: number;`
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
 } & RejectUnknown<O, FieldOptions> & RejectIncompatible<O> & {
     readonly nullable?: false;
-}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}>(opts: O): IdDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/decorator/members.js

@@ -14,10 +14,12 @@ export function Field(opts) {
     };
 }
 /**
- * Declares the primary key, checked the same way as `@Field`.
+ * Declares the primary key, checked the same way as `@Field` and additionally against the class:
+ * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
  *
  * @example `@Id({ type: Number }) id?: number;`
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export function Id(opts) {
     return (_value, context) => {

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type } from '../../type/index.js';
+import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
@@ -40,13 +40,16 @@ export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>
  */
 export declare function namesKey<E>(meta: EntityMeta<E>, row: EntityData<E>): boolean;
 /**
- * A row's primary key in the shape a `$where` takes: the value itself for a single key, an object
- * carrying every key for a composite - which is exactly {@link EntityId}.
+ * A row's primary key: the value itself for a single key, an object carrying every key for a
+ * composite - which is {@link WrittenId}, and reads as the {@link EntityId} a `$where` takes.
  *
- * What a settled write names its rows by, and what an insert hands back. Naming a composite row by
- * one of its columns would address every row agreeing on that one.
+ * What a settled write names its rows by, and what a write hands back. Naming a composite row by one
+ * of its columns would address every row agreeing on that one.
+ *
+ * `WrittenId` does not reduce for an unresolved `E`, so which branch this entity is in cannot be
+ * proven here, only checked - which is what `ids.length` does.
  */
-export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): EntityId<E>;
+export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): WrittenId<E>;
 /**
  * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
  * deleted content type would otherwise keep its metadata for the life of the process. Nothing rewrites

package/dist/entity/metadata/definition.js

@@ -235,18 +235,19 @@ export function namesKey(meta, row) {
     return meta.ids.every((key) => row[key] != null);
 }
 /**
- * A row's primary key in the shape a `$where` takes: the value itself for a single key, an object
- * carrying every key for a composite - which is exactly {@link EntityId}.
+ * A row's primary key: the value itself for a single key, an object carrying every key for a
+ * composite - which is {@link WrittenId}, and reads as the {@link EntityId} a `$where` takes.
  *
- * What a settled write names its rows by, and what an insert hands back. Naming a composite row by
- * one of its columns would address every row agreeing on that one.
+ * What a settled write names its rows by, and what a write hands back. Naming a composite row by one
+ * of its columns would address every row agreeing on that one.
+ *
+ * `WrittenId` does not reduce for an unresolved `E`, so which branch this entity is in cannot be
+ * proven here, only checked - which is what `ids.length` does.
  */
 export function idOf(meta, row) {
     const { ids } = meta;
-    if (ids.length === 1) {
-        return row[ids[0]];
-    }
-    return Object.fromEntries(ids.map((key) => [key, row[key]]));
+    const id = ids.length === 1 ? row[ids[0]] : Object.fromEntries(ids.map((key) => [key, row[key]]));
+    return id;
 }
 /**
  * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 import { LoggerWrapper, type ParentJoin, type ParentPartition } from '../util/index.js';
 /**
  * Base class for all database queriers.
@@ -111,8 +111,12 @@ export declare abstract class AbstractQuerier implements Querier {
     protected abstract internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
     abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    /**
+     * A composite key is named here rather than by the statement: no column holds it, so no database
+     * reports one, but the caller wrote every column of it and the payload still carries them.
+     */
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
@@ -148,7 +152,7 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     private findDoomed;
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert or update, as the name has always promised - and now as one statement per kind rather
      * than a guess.
@@ -165,7 +169,7 @@ export declare abstract class AbstractQuerier implements Querier {
      * The hooks follow the statement: a named row fires `beforeUpsert`/`afterUpsert`, never the
      * update pair, because the database picks the branch as the statement runs.
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;

package/dist/querier/abstractQuerier.js

@@ -167,8 +167,17 @@ export class AbstractQuerier {
         const [id] = await this.insertMany(entity, [payload]);
         return id;
     }
+    /**
+     * A composite key is named here rather than by the statement: no column holds it, so no database
+     * reports one, but the caller wrote every column of it and the payload still carries them.
+     */
     async insertMany(entity, payload) {
-        return this.hooked(entity, 'Insert', payload, () => this.internalInsertMany(entity, payload));
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Insert', payload, async () => {
+            const reported = await this.internalInsertMany(entity, payload);
+            // Neither branch can be shown to be `WrittenId` for an unresolved `E`; `idOf` narrows likewise.
+            return meta.ids.length === 1 ? reported : payload.map((it) => idOf(meta, it));
+        });
     }
     async updateOneById(entity, id, payload, opts) {
         assertIdValue(entity, id);

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -37,14 +37,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.js

@@ -365,9 +365,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         payload = clone(payload);
         const meta = getMeta(entity);
-        // A composite key is supplied whole by the caller, so nothing is generated and nothing comes
-        // back: the rows insert, and their ids are `undefined` for the reason MySQL's are below - there
-        // is no id to report. `idOf` names such a row for the caller that wants one.
+        // What comes back is one column's value, so a composite reports nothing here and `insertMany`
+        // names those rows from the payload instead. `sole` is what keeps every id path off a key that
+        // is several columns.
         const [idKey] = meta.ids;
         const sole = meta.ids.length === 1;
         const idField = sole ? meta.fields[idKey] : undefined;

package/dist/type/entity.d.ts

@@ -182,9 +182,10 @@ export type UpdatePayload<E> = {
  */
 export type FieldValue<E> = E[FieldKey<E>];
 /**
- * Infers the name of the key identifier on an entity
+ * The key's name where the entity states it: the `idKey` brand first, then the conventional names.
+ * `never` when nothing does, which is the case {@link IdKey} falls back on and `@Id` refuses.
  */
-export type IdKey<E> = (E extends {
+export type NamedIdKey<E> = E extends {
     [idKey]?: infer K;
 } ? K & FieldKey<E> : E extends {
     _id?: unknown;
@@ -192,7 +193,11 @@ export type IdKey<E> = (E extends {
     id?: unknown;
 } ? 'id' & FieldKey<E> : E extends {
     uuid?: unknown;
-} ? 'uuid' & FieldKey<E> : FieldKey<E>) & string;
+} ? 'uuid' & FieldKey<E> : never;
+/**
+ * Infers the name of the key identifier on an entity
+ */
+export type IdKey<E> = ([NamedIdKey<E>] extends [never] ? FieldKey<E> : NamedIdKey<E>) & string;
 /**
  * Infers the value of the key identifier on an entity.
  *
@@ -206,25 +211,35 @@ export type IdKey<E> = (E extends {
  * filter"; `assertIdValue` is what rejects it.
  */
 export type IdValue<E> = E[IdKey<E>];
+/** Every column of a key, which is how a composite row is named and what a `$where` reduces to. */
+type IdMap<E> = {
+    [K in IdKey<E>]?: E[K];
+};
 /**
  * How a row is addressed by its primary key: the value for a single key, an object carrying every
  * key for a composite - which is also the `$where` map it reduces to, so both spellings are one type.
  *
- * Distinct from {@link IdValue}, the *column's* value, which stays a scalar: an id column holds a
- * number, never an object. The two read alike on a single-key entity and are not the same thing -
- * `findOneById` takes an `EntityId`, while the inserts return `IdValue | undefined`, which is why a
- * composite insert reports no id rather than the map.
+ * A union rather than a choice between the two, because a caller holding one column's value has to
+ * reach the same parameter as one holding a map. {@link WrittenId} is where a shape is committed to.
  *
- * The keys stay optional, and completeness is checked at run time by `assertIdValue`. Requiring them
- * needs `IdKey` to be precise, which it is not: with no `id`/`_id`/`uuid` and no `idKey` brand it
- * falls back to every field, so `IdKey<Membership>` accepts `'role'` and requiring the map would
- * demand fields that are not keys. Making it conditional on the brand was tried and reverted - a
- * conditional type does not reduce for an unresolved `E`, which left `QueryWhere<E>` opaque and broke
- * assignability across the dialects.
+ * The keys stay optional, and completeness is checked at run time by `assertIdValue`: requiring them
+ * would refuse a `$where` map that names one row while it is still being built up.
  */
-export type EntityId<E> = IdValue<E> | {
-    [K in IdKey<E>]?: E[K];
-};
+export type EntityId<E> = IdValue<E> | IdMap<E>;
+/** Whether `T` is a union of more than one member, which for a key means the entity's is composite. */
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+/**
+ * The id a write reports: the column's value for a single key, the key map for a composite.
+ *
+ * Exact where {@link EntityId} is a union, and that is the difference between them - a by-id method
+ * *accepts* either spelling, a write *commits* to one.
+ *
+ * Falls back to `EntityId` where {@link NamedIdKey} names nothing, because there `IdKey` is every
+ * field and a composite cannot be told from a single key: reporting a map for a scalar would be a
+ * lie. `@Id` refuses an unnamed key, so a decorated entity is always exact, and `defineEntity` is
+ * the path where this fallback is still reachable.
+ */
+export type WrittenId<E> = [NamedIdKey<E>] extends [never] ? EntityId<E> : IsUnion<IdKey<E>> extends true ? IdMap<E> : IdValue<E>;
 /**
  * Infers the values of the relations on an entity
  */

package/dist/type/universalQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, FieldKey, IdValue, RelationKey, UpdatePayload } from './entity.js';
+import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
 import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
@@ -116,7 +116,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the ID
      */
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
      * dialect's bind-parameter limit) and return their IDs in payload order.
@@ -125,12 +125,13 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * Database-generated IDs are exact on `'returning'` dialects (Postgres, MariaDB, MongoDB);
      * on MySQL/SQLite they are inferred from the driver header, which is only reliable for
      * auto-increment keys in batches without explicit IDs - otherwise those entries are
-     * `undefined` rather than potentially wrong values.
+     * `undefined` rather than potentially wrong values. A composite key is never one the statement
+     * reports, so those rows are named from the payload instead.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /**
      * Insert or update a record based on the conflict paths.
      * @param entity the entity to persist on
@@ -153,14 +154,14 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

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