uql-orm 0.22.0 → 0.24.0

package/README.md

@@ -32,8 +32,9 @@
 npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @tursodatabase/serverless, @libsql/client
 ```
 
-Decorators also need `reflect-metadata` ([setup](https://uql-orm.dev/getting-started)); the
-[imperative API](https://uql-orm.dev/entities/imperative) needs nothing extra.
+That is the whole install. Decorators are the standard TC39 ones, so there is no `reflect-metadata`
+and no compiler flag to turn on ([setup](https://uql-orm.dev/getting-started)), and the
+[imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
 
 ```ts
 await querier.findMany(User, {
@@ -55,8 +56,7 @@ from the browser to the server. The same object runs on every supported database
 - **Type-safe to the leaf.** Operators are gated per field type, and JSON/JSONB dot-paths resolve each path's value type, so `{ age: { $like: 'x' } }` or a typo'd path is a compile error instead of a runtime surprise.
 - **No codegen.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` file to regenerate, no generated client to keep in sync.
 - **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, LibSQL, Neon, Cloudflare D1, Bun SQL, and MongoDB.
-- **First ORM with a native Turso driver.** Turso Cloud over pure `fetch()` with zero native dependencies, so it runs on Cloudflare Workers and Vercel Edge, plus the embedded Rust engine for local-first apps.
-- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/extensions-http).
+- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [non-bypassable multi-tenant filters](https://uql-orm.dev/multi-tenancy), [entity-first migrations](https://uql-orm.dev/migrations), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [a REST API from your entities](https://uql-orm.dev/http).
 
 ## Get started
 

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

@@ -6,12 +6,12 @@
     "import type { RequestErrorResponse, RequestSuccessResponse } from '../../http/contract.js';\nimport type { RequestOptions } from '../type/index.js';\nimport { notify } from './bus.js';\n\n/**\n * Error thrown for non-2xx responses. Carries the HTTP status so callers can key\n * behavior on it (401 redirects, 402 payment flows, error-boundary routing).\n */\nexport class RequestError extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n  ) {\n    super(message);\n    this.name = 'RequestError';\n  }\n}\n\nexport function get<T>(url: string, opts?: RequestOptions) {\n  return request<T>(url, { method: 'get' }, opts);\n}\n\nexport function post<T>(url: string, payload: unknown, opts?: RequestOptions) {\n  const body = JSON.stringify(payload);\n  return request<T>(url, { method: 'post', body }, opts);\n}\n\nexport function patch<T>(url: string, payload: unknown, opts?: RequestOptions) {\n  const body = JSON.stringify(payload);\n  return request<T>(url, { method: 'patch', body }, opts);\n}\n\nexport function put<T>(url: string, payload: unknown, opts?: RequestOptions) {\n  const body = JSON.stringify(payload);\n  return request<T>(url, { method: 'put', body }, opts);\n}\n\nexport function remove<T>(url: string, opts?: RequestOptions) {\n  return request<T>(url, { method: 'delete' }, opts);\n}\n\n/**\n * HTTP QUERY (RFC 10008): a safe, idempotent read whose JSON query travels in the\n * request body, avoiding URL-length limits. Method name must stay uppercase\n * (fetch only normalizes the classic verbs).\n */\nexport function query<T>(url: string, payload: unknown, opts?: RequestOptions) {\n  const body = JSON.stringify(payload);\n  return request<T>(url, { method: 'QUERY', body }, opts);\n}\n\nfunction request<T>(url: string, init: RequestInit, opts?: RequestOptions) {\n  notify({ phase: 'start', opts });\n\n  init.headers = {\n    accept: 'application/json',\n    'content-type': 'application/json',\n    ...opts?.headers,\n  };\n  if (opts?.signal) {\n    init.signal = opts.signal;\n  }\n\n  return fetch(url, init)\n    .then((rawResp) =>\n      rawResp.json().then((resp: unknown) => {\n        const isSuccess = rawResp.status >= 200 && rawResp.status < 300;\n        if (isSuccess) {\n          notify({ phase: 'success', opts });\n          return resp as RequestSuccessResponse<T>;\n        }\n        const errorResp = resp as Partial<RequestErrorResponse> | undefined;\n        const error = {\n          message: errorResp?.error?.message ?? rawResp.statusText,\n          code: errorResp?.error?.code ?? rawResp.status,\n        };\n        notify({ phase: 'error', error, opts });\n        throw new RequestError(error.message, error.code);\n      }),\n    )\n    .finally(() => {\n      notify({ phase: 'complete', opts });\n    });\n}\n",
     "import type { FieldKey, FieldOptions } from '../type/index.js';\n\nexport function throwPendingTransaction(): never {\n  throw TypeError('pending transaction');\n}\n\nexport function throwNoPendingTransaction(): never {\n  throw TypeError('not a pending transaction');\n}\n\nexport function clone<T>(value: T): T {\n  if (typeof value !== 'object' || value === null) {\n    return value;\n  }\n  if (Array.isArray(value)) {\n    return value.map((it) => clone(it)) as T;\n  }\n  return { ...value };\n}\n\n/** Whether `obj` has at least one enumerable key. Narrows away `undefined`/`null` for callers. */\nexport function hasKeys<T>(obj: T): obj is NonNullable<T> {\n  if (typeof obj !== 'object' || obj === null) return false;\n  for (const _ in obj) return true;\n  return false;\n}\n\n/** Whether `obj` has at least two enumerable keys. */\nexport function hasMultipleKeys(obj: object): boolean {\n  let count = 0;\n  for (const _ in obj) {\n    if (++count > 1) return true;\n  }\n  return false;\n}\n\n/**\n * Whether any enumerable key of `obj` satisfies `pred`, short-circuiting on the first match\n * without materializing a key array (unlike `Object.keys(obj).some(pred)`).\n */\nexport function someKey(obj: object, pred: (key: string) => boolean): boolean {\n  for (const key in obj) {\n    if (pred(key)) return true;\n  }\n  return false;\n}\n\n/** Whether any enumerable value of `obj` satisfies `pred`, short-circuiting like {@link someKey}. */\nexport function someValue(obj: object, pred: (value: unknown) => boolean): boolean {\n  return someKey(obj, (key) => pred((obj as Record<string, unknown>)[key]));\n}\n\nconst isOperatorKey = (key: string) => key.startsWith('$');\n\n/**\n * Whether `value` is a non-empty object whose keys are query/update operators (`$eq`, `$push`, ...).\n * The single source of this test: the SQL dialects, the MongoDB dialect and the `$elemMatch` walker\n * all classify operator objects with it, and they used to disagree about `{}`.\n */\nexport function isOperatorObject(value: unknown): value is Record<string, unknown> {\n  return hasKeys(value) && !Array.isArray(value) && someKey(value, isOperatorKey);\n}\n\n/** Whether every key of the non-empty object `value` is an operator (no plain field names mixed in). */\nexport function isOperatorOnlyObject(value: unknown): value is Record<string, unknown> {\n  return hasKeys(value) && !Array.isArray(value) && !someKey(value, (key) => !isOperatorKey(key));\n}\n\nexport function getKeys<T extends object>(obj: T): (keyof T & string)[] {\n  return obj ? (Object.keys(obj) as (keyof T & string)[]) : [];\n}\n\nexport function getFieldKeys<E>(\n  fields: {\n    [K in FieldKey<E>]?: FieldOptions;\n  },\n): FieldKey<E>[] {\n  return getKeys(fields).filter((field) => fields[field]!.eager ?? true);\n}\n",
     "export function kebabCase(val: string): string {\n  let resp = val.charAt(0).toLowerCase();\n  for (let i = 1; i < val.length; ++i) {\n    resp += val[i] === val[i].toUpperCase() ? '-' + val[i].toLowerCase() : val[i];\n  }\n  return resp;\n}\n\nexport function upperFirst(text: string): string {\n  if (!text) return text;\n  return text[0].toUpperCase() + text.slice(1);\n}\n\nexport function lowerFirst(text: string): string {\n  if (!text) return text;\n  return text[0].toLowerCase() + text.slice(1);\n}\n\nexport function snakeCase(val: string): string {\n  if (val === null || val === undefined) return val as string;\n  if (!val) return '';\n  let resp = val.charAt(0).toLowerCase();\n  for (let i = 1; i < val.length; ++i) {\n    const char = val[i];\n    const charLower = char.toLowerCase();\n    if (char !== charLower && char === char.toUpperCase()) {\n      resp += '_' + charLower;\n    } else {\n      resp += char;\n    }\n  }\n  return resp;\n}\n\n/**\n * Convert a string to PascalCase (UpperCamelCase).\n * @example 'user_profile' -> 'UserProfile'\n * @example 'some-text' -> 'SomeText'\n */\nexport function pascalCase(str: string): string {\n  if (!str) return '';\n  return str\n    .split(/[_\\s-]+/)\n    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())\n    .join('');\n}\n\n/**\n * Convert a string to camelCase.\n * @example 'user_profile' -> 'userProfile'\n * @example 'SomeText' -> 'someText'\n */\nexport function camelCase(str: string): string {\n  const pascal = pascalCase(str);\n  return pascal.charAt(0).toLowerCase() + pascal.slice(1);\n}\n\n/**\n * Simple singularize function for English words.\n * @example 'users' -> 'user'\n * @example 'categories' -> 'category'\n */\nexport function singularize(name: string): string {\n  if (!name) return '';\n  if (name.endsWith('ies')) {\n    return name.slice(0, -3) + 'y';\n  }\n  if (name.endsWith('ses') || name.endsWith('xes') || name.endsWith('zes')) {\n    return name.slice(0, -2);\n  }\n  if (name.endsWith('s') && !name.endsWith('ss')) {\n    return name.slice(0, -1);\n  }\n  return name;\n}\n\n/**\n * Simple pluralize function for English words.\n * @example 'user' -> 'users'\n * @example 'category' -> 'categories'\n */\nexport function pluralize(name: string): string {\n  if (!name) return '';\n  if (name.endsWith('y') && name.length > 1 && !/[aeiou]/.test(name[name.length - 2])) {\n    return name.slice(0, -1) + 'ies';\n  }\n  if (name.endsWith('s') || name.endsWith('x') || name.endsWith('z') || name.endsWith('ch') || name.endsWith('sh')) {\n    return name + 'es';\n  }\n  return name + 's';\n}\n",
-    "import type { Type, UniversalQuerier } from '../type/index.js';\n// import from the specific util modules (not the barrel) to keep entity\n// metadata and reflect-metadata out of the browser bundle\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 RequestSuccessResponse<E> = {\n  data: E;\n  count?: number;\n};\n\nexport type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {\n  count: number;\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 { Query, QueryOptions } from '../type/index.js';\n// specific util module (not the barrel) to keep reflect-metadata out of the browser bundle\nimport { getKeys } from '../util/object.util.js';\n\nconst JSON_QUERY_KEYS = [\n  '$select',\n  '$populate',\n  '$exclude',\n  '$where',\n  '$sort',\n] as const satisfies readonly (keyof Query<unknown>)[];\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>([...JSON_QUERY_KEYS, '$skip', '$limit', 'hardDelete', 'count'] satisfies (\n  | keyof Query<unknown>\n  | keyof Pick<QueryOptions, 'hardDelete'>\n  | 'count'\n)[]);\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 (ALLOWED_QUERY_KEYS.has(key)) {\n      query[key] = params[key];\n    }\n  }\n\n  for (const key of JSON_QUERY_KEYS) {\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  if (query['$skip']) {\n    query['$skip'] = Number(query['$skip']);\n  }\n  if (query['$limit']) {\n    query['$limit'] = Number(query['$limit']);\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 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 RequestSuccessResponse<E> = {\n  data: E;\n  count?: number;\n};\n\nexport type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {\n  count: number;\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 { Query, QueryOptions } from '../type/index.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\nconst JSON_QUERY_KEYS = [\n  '$select',\n  '$populate',\n  '$exclude',\n  '$where',\n  '$sort',\n] as const satisfies readonly (keyof Query<unknown>)[];\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>([...JSON_QUERY_KEYS, '$skip', '$limit', 'hardDelete', 'count'] satisfies (\n  | keyof Query<unknown>\n  | keyof Pick<QueryOptions, 'hardDelete'>\n  | 'count'\n)[]);\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 (ALLOWED_QUERY_KEYS.has(key)) {\n      query[key] = params[key];\n    }\n  }\n\n  for (const key of JSON_QUERY_KEYS) {\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  if (query['$skip']) {\n    query['$skip'] = Number(query['$skip']);\n  }\n  if (query['$limit']) {\n    query['$limit'] = Number(query['$limit']);\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 {\n  CRUD_ROUTES,\n  entityPath,\n  type HttpMethod,\n  type RequestCountedSuccessResponse,\n  type RequestSuccessResponse,\n} from '../../http/contract.js';\nimport { stringifyQuery } from '../../http/query.js';\nimport type { IdValue, Query, QueryOne, QueryOptions, QuerySearch, Type, UpdatePayload } from '../../type/index.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\nexport class HttpQuerier implements ClientQuerier {\n  constructor(\n    readonly basePath: string,\n    readonly defaults: HttpQuerierDefaults = {},\n  ) {}\n\n  findOneById<E extends object>(\n    entity: Type<E>,\n    id: IdValue<E>,\n    q?: QueryOne<E>,\n    opts?: RequestOptions,\n  ): Promise<RequestSuccessResponse<E | undefined>> {\n    const basePath = this.getBasePath(entity);\n    const qs = stringifyQuery(q);\n    return get<E | undefined>(`${basePath}/${id}${qs}`, this.buildOptions(opts));\n  }\n\n  findOne<E extends object>(\n    entity: Type<E>,\n    q: QueryOne<E>,\n    opts?: RequestOptions,\n  ): Promise<RequestSuccessResponse<E | undefined>> {\n    return this.read<E | undefined>(`${this.getBasePath(entity)}${CRUD_ROUTES.findOne.path}`, q, opts);\n  }\n\n  findMany<E extends object>(\n    entity: Type<E>,\n    q: Query<E>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestSuccessResponse<E[]>> {\n    const data: Query<E> & { count?: boolean } = { ...q };\n    if (opts?.count) {\n      data.count = true;\n    }\n    return this.read<E[]>(this.getBasePath(entity), data, opts);\n  }\n\n  async findManyAndCount<E extends object>(\n    entity: Type<E>,\n    q: Query<E>,\n    opts?: RequestFindOptions,\n  ): Promise<RequestCountedSuccessResponse<E[]>> {\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?: QuerySearch<E>, opts?: RequestOptions) {\n    return this.read<number>(`${this.getBasePath(entity)}${CRUD_ROUTES.count.path}`, q, opts);\n  }\n\n  insertOne<E extends object>(entity: Type<E>, payload: 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: E[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return post<IdValue<E>[]>(`${basePath}${CRUD_ROUTES.insertMany.path}`, payload, this.buildOptions(opts));\n  }\n\n  updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return patch<number>(`${basePath}/${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: E, opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<IdValue<E>>(basePath, payload, this.buildOptions(opts));\n  }\n\n  saveMany<E extends object>(entity: Type<E>, payload: E[], opts?: RequestOptions) {\n    const basePath = this.getBasePath(entity);\n    return put<IdValue<E>[]>(`${basePath}${CRUD_ROUTES.saveMany.path}`, payload, this.buildOptions(opts));\n  }\n\n  deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts: QueryOptions & RequestOptions = {}) {\n    const basePath = this.getBasePath(entity);\n    const qs = opts.hardDelete ? stringifyQuery({ hardDelete: opts.hardDelete }) : '';\n    return remove<number>(`${basePath}/${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}/${entityPath(entity)}`;\n  }\n\n  protected read<T>(path: string, q: Record<string, unknown> | undefined, opts?: RequestOptions) {\n    if (this.defaults.readMethod === 'QUERY') {\n      return httpQuery<T>(path, q ?? {}, this.buildOptions(opts));\n    }\n    return get<T>(`${path}${stringifyQuery(q)}`, this.buildOptions(opts));\n  }\n\n  protected buildOptions(opts?: RequestOptions): RequestOptions | undefined {\n    if (!this.defaults.headers && !opts?.headers) {\n      return opts;\n    }\n    return { ...opts, headers: { ...this.defaults.headers, ...opts?.headers } };\n  }\n}\n",
     "import { HttpQuerier } from './querier/httpQuerier.js';\nimport type { ClientQuerier, ClientQuerierPool } from './type/index.js';\n\nlet defaultPool: ClientQuerierPool = {\n  getQuerier: () => new HttpQuerier('/api'),\n};\n\nexport function setQuerierPool<T extends ClientQuerierPool>(pool: T) {\n  defaultPool = pool;\n}\n\nexport function getQuerierPool(): ClientQuerierPool {\n  return defaultPool;\n}\n\nexport function getQuerier(): ClientQuerier {\n  return getQuerierPool().getQuerier();\n}\n"
   ],
-  "mappings": "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",
+  "mappings": "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",
   "debugId": "89C8E712B5A364FC64756E2164756E21",
   "names": []
 }

package/dist/dialect/abstractSqlDialect.d.ts

@@ -221,7 +221,20 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      */
     protected appendDefaultInsertValue(ctx: QueryContext, _field: FieldOptions | undefined): void;
     update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
-    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
+    /**
+     * `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...`, which SQLite adopted from Postgres
+     * and which every dialect here speaks except the MySQL family (see {@link MysqlLikeSqlDialect}).
+     *
+     * Two orderings matter, and they pull in opposite directions. The assignments are computed *before*
+     * the insert, because `appendInsertValues` fills `onInsert` fields into the payload and a column that
+     * exists only there - `createdAt` - must not join the update set. Their bound values are pushed
+     * *after* it, because a `?` placeholder is positional and the clause comes last in the statement.
+     * {@link PgLikeSqlDialect} overrides this: `$N` placeholders make array order irrelevant, so it can
+     * bind into the main context and skip the second one.
+     */
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
+    protected readonly upsertExcluded: (columnName: string) => string;
     protected getUpsertUpdateAssignments<E>(ctx: QueryContext, meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], callback?: (columnName: string) => string): string;
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;

package/dist/dialect/abstractSqlDialect.js

@@ -1006,22 +1006,29 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
         this.search(ctx, entity, q, opts);
     }
-    upsert(ctx, entity, conflictPaths, payload) {
+    /**
+     * `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...`, which SQLite adopted from Postgres
+     * and which every dialect here speaks except the MySQL family (see {@link MysqlLikeSqlDialect}).
+     *
+     * Two orderings matter, and they pull in opposite directions. The assignments are computed *before*
+     * the insert, because `appendInsertValues` fills `onInsert` fields into the payload and a column that
+     * exists only there - `createdAt` - must not join the update set. Their bound values are pushed
+     * *after* it, because a `?` placeholder is positional and the clause comes last in the statement.
+     * {@link PgLikeSqlDialect} overrides this: `$N` placeholders make array order irrelevant, so it can
+     * bind into the main context and skip the second one.
+     */
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);
         const updateCtx = this.createContext();
-        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
-        if (update) {
-            this.appendInsertValues(ctx, entity, payload);
-            ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
-            ctx.pushValue(...updateCtx.values);
-        }
-        else {
-            const insertCtx = this.createContext();
-            this.appendInsertValues(insertCtx, entity, payload);
-            ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
-            ctx.pushValue(...insertCtx.values);
-        }
-    }
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, this.upsertExcluded);
+        const keys = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
+        this.appendInsertValues(ctx, entity, payload);
+        ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
+        ctx.pushValue(...updateCtx.values);
+    }
+    /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
+    upsertExcluded = (columnName) => `EXCLUDED.${columnName}`;
     getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, callback) {
         const sample = Array.isArray(payload) ? payload[0] : payload;
         const cloned = { ...sample };

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, EntityMeta, FieldOptions, IndexFeature, IndexSchema, InsertIdSource, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, IndexFeature, IndexSchema, InsertIdSource, QueryConflictPaths, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
@@ -26,6 +26,16 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     readonly alterColumnSyntax = "MODIFY COLUMN";
     readonly booleanLiteral = "integer";
     readonly insertIdSource: InsertIdSource;
+    /**
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
+     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
+     * unique index for you.
+     *
+     * The update assignments are built into their own context and pushed afterwards, since they read
+     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
+     * payload) has to land after the insert's for a `?`-placeholder driver.
+     */
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     readonly maxBindValues: number;
     escape(value: unknown): string;
     /**

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,3 +1,4 @@
+import { getMeta } from '../entity/index.js';
 import { getFieldKeys } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
@@ -44,6 +45,30 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     // No `RETURNING` support, so multi-row insert IDs are inferred from the header - see the
     // `innodb_autoinc_lock_mode` caveat on `buildUpdateResult` in `util/sql.util.ts`.
     insertIdSource = 'firstId';
+    /**
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
+     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
+     * unique index for you.
+     *
+     * The update assignments are built into their own context and pushed afterwards, since they read
+     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
+     * payload) has to land after the insert's for a `?`-placeholder driver.
+     */
+    upsert(ctx, entity, conflictPaths, payload) {
+        const meta = getMeta(entity);
+        const updateCtx = this.createContext();
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
+        if (update) {
+            this.appendInsertValues(ctx, entity, payload);
+            ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
+            ctx.pushValue(...updateCtx.values);
+            return;
+        }
+        const insertCtx = this.createContext();
+        this.appendInsertValues(insertCtx, entity, payload);
+        ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
+        ctx.pushValue(...insertCtx.values);
+    }
     maxBindValues = 65535;
     escape(value) {
         return escapeMysqlSqlLiteral(value);

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -46,15 +46,12 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected indexInclude(index: IndexSchema): string;
     protected indexTuning(index: IndexSchema): string;
     placeholder(index: number): string;
-    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
-     * Shared `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...` builder, assembling
-     * everything upfront rather than handing back fragments, for the `$N`-placeholder Postgres-wire
-     * dialects. `extraReturning` lets {@link PostgresDialect} append `(xmax = 0) AS "_created"` to
-     * detect insert-vs-update; CockroachDB has no `xmax`/`ctid` system columns, so it uses the default
-     * (empty) and `created` stays `undefined` in the result.
+     * The same statement as the base, binding the assignments into the main context instead of a second
+     * one: `$N` placeholders carry their own index, so the values need not be in statement order, and
+     * computing them first is what keeps `appendInsertValues`' `onInsert` fields out of the update set.
      */
-    protected buildUpsertOnConflict<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
     /**
      * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
      * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which

package/dist/dialect/pgLikeSqlDialect.js

@@ -115,23 +115,18 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     placeholder(index) {
         return `$${index}`;
     }
-    upsert(ctx, entity, conflictPaths, payload) {
-        this.buildUpsertOnConflict(ctx, entity, conflictPaths, payload);
-    }
     /**
-     * Shared `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...` builder, assembling
-     * everything upfront rather than handing back fragments, for the `$N`-placeholder Postgres-wire
-     * dialects. `extraReturning` lets {@link PostgresDialect} append `(xmax = 0) AS "_created"` to
-     * detect insert-vs-update; CockroachDB has no `xmax`/`ctid` system columns, so it uses the default
-     * (empty) and `created` stays `undefined` in the result.
+     * The same statement as the base, binding the assignments into the main context instead of a second
+     * one: `$N` placeholders carry their own index, so the values need not be in statement order, and
+     * computing them first is what keeps `appendInsertValues`' `onInsert` fields out of the update set.
      */
-    buildUpsertOnConflict(ctx, entity, conflictPaths, payload, extraReturning = '') {
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);
-        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
-        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, this.upsertExcluded);
+        const keys = this.getUpsertConflictPathsStr(meta, conflictPaths);
         const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
         this.appendInsertValues(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
+        ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
     }
     /**
      * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input

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

@@ -0,0 +1,35 @@
+import type { FieldOptions, HookEvent, RelationOptions, Type } from '../../type/index.js';
+/**
+ * What the member decorators record for one class, waiting for `@Entity()` or `defineEntity` to drain
+ * it into the metadata registry. Member decorators receive no class reference under the standard
+ * decorator spec, so this object is the only channel between them and the class decorator that does.
+ */
+export type MemberRegistrations = {
+    readonly fields: Record<string, FieldOptions>;
+    readonly relations: Record<string, RelationOptions>;
+    readonly hooks: Partial<Record<HookEvent, string[]>>;
+};
+/**
+ * The calling class's own registrations, created on first use.
+ *
+ * Deliberately holds **only** this class's members: inheritance is resolved later by walking the class
+ * prototype chain, not by reading through the metadata object's. tsc chains a subclass's metadata to its
+ * parent's and SWC does not, so anything built on that chain would work under one compiler and quietly
+ * lose inherited fields under the other. Keeping each bag to its own members also means a parent's map
+ * is never shared with its subclasses, and hooks cannot be registered twice.
+ */
+export declare function memberRegistrations(metadata: DecoratorMetadata): MemberRegistrations;
+/**
+ * Takes the registrations belonging to `metadata`, leaving none behind, so finalizing an entity twice
+ * cannot register its hooks twice.
+ */
+export declare function drainRegistrations(metadata: DecoratorMetadata | undefined): MemberRegistrations | undefined;
+/**
+ * The registrations a class made for itself.
+ *
+ * @remarks Only usable once the class is fully defined, which is why `@Entity()` reads
+ * `context.metadata` instead: TypeScript attaches `Symbol.metadata` to the class *after* its class
+ * decorators return. Ancestors are always fully defined by then, so this is how inherited members are
+ * collected.
+ */
+export declare function ownRegistrations(entity: Type<unknown>): MemberRegistrations | undefined;

package/dist/entity/decorator/bag.js

@@ -0,0 +1,54 @@
+/**
+ * Polyfill `Symbol.metadata`, which no runtime we support defines yet (checked on Node 24 and Bun
+ * 1.3): TypeScript's decorator emit reads it to decide whether to build the metadata object at all, so
+ * without this every `context.metadata` is `undefined` and field registration is silently dropped
+ * rather than failing.
+ *
+ * `Symbol.for`, not `Symbol()`, so a duplicated copy of this module (HMR, federated bundles, ESM+CJS
+ * dual-loading) lands on the same symbol, and so it agrees with the key esbuild and SWC fall back to
+ * (`Symbol.metadata ?? Symbol.for('Symbol.metadata')`). Assigned through a widened alias because the
+ * lib declares the property `readonly`; when a runtime does define it, `??=` leaves it alone.
+ */
+const symbolCtor = Symbol;
+symbolCtor.metadata ??= Symbol.for('Symbol.metadata');
+/** Where member registrations live on the per-class metadata object. */
+const registrations = Symbol.for('uql-orm/entity/decoratorMembers');
+/**
+ * The calling class's own registrations, created on first use.
+ *
+ * Deliberately holds **only** this class's members: inheritance is resolved later by walking the class
+ * prototype chain, not by reading through the metadata object's. tsc chains a subclass's metadata to its
+ * parent's and SWC does not, so anything built on that chain would work under one compiler and quietly
+ * lose inherited fields under the other. Keeping each bag to its own members also means a parent's map
+ * is never shared with its subclasses, and hooks cannot be registered twice.
+ */
+export function memberRegistrations(metadata) {
+    if (!Object.hasOwn(metadata, registrations)) {
+        metadata[registrations] = { fields: {}, relations: {}, hooks: {} };
+    }
+    return metadata[registrations];
+}
+/**
+ * Takes the registrations belonging to `metadata`, leaving none behind, so finalizing an entity twice
+ * cannot register its hooks twice.
+ */
+export function drainRegistrations(metadata) {
+    if (!metadata || !Object.hasOwn(metadata, registrations)) {
+        return undefined;
+    }
+    const own = metadata[registrations];
+    delete metadata[registrations];
+    return own;
+}
+/**
+ * The registrations a class made for itself.
+ *
+ * @remarks Only usable once the class is fully defined, which is why `@Entity()` reads
+ * `context.metadata` instead: TypeScript attaches `Symbol.metadata` to the class *after* its class
+ * decorators return. Ancestors are always fully defined by then, so this is how inherited members are
+ * collected.
+ */
+export function ownRegistrations(entity) {
+    const metadata = Object.getOwnPropertyDescriptor(entity, Symbol.metadata)?.value;
+    return drainRegistrations(metadata);
+}

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

@@ -1,2 +1,28 @@
-import type { EntityOptions, Type } from '../../type/index.js';
-export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>) => void;
+import type { EntityOptions, FieldKey, FilterOptions, IndexColumnInput, IndexOptions, Type } from '../../type/index.js';
+/**
+ * Marks a class as an entity and finalizes its metadata.
+ *
+ * @remarks Takes the registrations from `context.metadata` rather than from the class. Member
+ * decorators have already run by the time a class decorator does, but TypeScript defines
+ * `Symbol.metadata` on the class *after* the class decorators return, so reading `entity[Symbol.metadata]`
+ * here would find only what the base class left behind. `defineEntity` reads it off the class instead,
+ * which is correct for the imperative path because it runs later still.
+ */
+export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>, context?: ClassDecoratorContext) => void;
+/**
+ * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
+ *
+ * @example `@Filter('active', { condition: { status: 'active' }, default: false })`
+ */
+export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity: Type<E>) => void;
+/**
+ * Declares a composite index. Stacks, so several may sit above one class.
+ *
+ * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
+ * names be checked against it: `@Index(['nope'])` does not compile.
+ *
+ * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['email'], { unique: true })`
+ * @example `@Index(['status'], { where: "status = 'active'" })`
+ */
+export declare function Index<E>(columns: readonly IndexColumnInput<FieldKey<E>>[], options?: IndexOptions): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -1,6 +1,44 @@
-import { defineEntity } from '../metadata/definition.js';
+import { applyMembers, defineEntity, defineFilter, defineIndex } from '../metadata/definition.js';
+import { drainRegistrations } from './bag.js';
+// The class-level decorators. Unlike the member ones they receive the class, so each is a direct call
+// into the registry with no bag in between.
+/**
+ * Marks a class as an entity and finalizes its metadata.
+ *
+ * @remarks Takes the registrations from `context.metadata` rather than from the class. Member
+ * decorators have already run by the time a class decorator does, but TypeScript defines
+ * `Symbol.metadata` on the class *after* the class decorators return, so reading `entity[Symbol.metadata]`
+ * here would find only what the base class left behind. `defineEntity` reads it off the class instead,
+ * which is correct for the imperative path because it runs later still.
+ */
 export function Entity(opts) {
-    return (entity) => {
+    return (entity, context) => {
+        applyMembers(entity, drainRegistrations(context?.metadata));
         defineEntity(entity, opts);
     };
 }
+/**
+ * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
+ *
+ * @example `@Filter('active', { condition: { status: 'active' }, default: false })`
+ */
+export function Filter(name, opts) {
+    return (entity) => {
+        defineFilter(entity, name, opts);
+    };
+}
+/**
+ * Declares a composite index. Stacks, so several may sit above one class.
+ *
+ * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
+ * names be checked against it: `@Index(['nope'])` does not compile.
+ *
+ * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['email'], { unique: true })`
+ * @example `@Index(['status'], { where: "status = 'active'" })`
+ */
+export function Index(columns, options = {}) {
+    return (entity) => {
+        defineIndex(entity, { ...options, columns });
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { EntityGetter, FieldOptions, FieldType, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/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;
+/**
+ * Declares a persisted field.
+ *
+ * `@Field({ type: String })` on a `number` property is a compile error rather than a silent TEXT column,
+ * which is what makes the now-mandatory `type` worth stating.
+ *
+ * @example `@Field({ type: String }) name?: string;`
+ * @example `@Field({ references: () => Company }) companyId?: string;`
+ */
+export declare function Field<T extends FieldType>(opts: FieldOptions & {
+    readonly type: T;
+}): MemberDecorator<TsTypeOf<T> | undefined>;
+/**
+ * A foreign key may omit `type`: schema generation resolves it from the referenced primary key, so the
+ * column picks up that key's `columnType`, length and chained references rather than a guess.
+ */
+export declare function Field(opts: FieldOptions & {
+    readonly references: EntityGetter;
+}): MemberDecorator<unknown>;
+/**
+ * Declares the primary key, checked the same way as `@Field`.
+ *
+ * @example `@Id({ type: Number }) id?: number;`
+ * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ */
+export declare function Id<T extends FieldType>(opts: FieldOptions & {
+    readonly type: T;
+}): MemberDecorator<TsTypeOf<T> | 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
+ * cardinality on a non-array property does too. `entity` is required because nothing reflects it now.
+ */
+type WithEntity<E, O> = O & {
+    readonly entity: EntityGetter<E>;
+};
+export declare function OneToOne<E>(opts: WithEntity<E, RelationOneToOneOptions<E>>): MemberDecorator<E | undefined>;
+export declare function ManyToOne<E>(opts: WithEntity<E, RelationManyToOneOptions<E>>): MemberDecorator<E | undefined>;
+export declare function OneToMany<E>(opts: WithEntity<E, RelationOneToManyOptions<E>>): MemberDecorator<readonly E[] | undefined>;
+export declare function ManyToMany<E>(opts: WithEntity<E, RelationManyToManyOptions<E>>): MemberDecorator<readonly E[] | undefined>;
+export declare const BeforeInsert: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterInsert: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const BeforeUpdate: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterUpdate: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const BeforeDelete: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterDelete: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterLoad: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export {};

package/dist/entity/decorator/members.js

@@ -0,0 +1,51 @@
+import { memberRegistrations } from './bag.js';
+export function Field(opts) {
+    return (_value, context) => {
+        memberRegistrations(context.metadata).fields[String(context.name)] = opts;
+    };
+}
+/**
+ * Declares the primary key, checked the same way as `@Field`.
+ *
+ * @example `@Id({ type: Number }) id?: number;`
+ * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
+ */
+export function Id(opts) {
+    return (_value, context) => {
+        memberRegistrations(context.metadata).fields[String(context.name)] = { ...opts, isId: true };
+    };
+}
+function relation(opts) {
+    return (_value, context) => {
+        memberRegistrations(context.metadata).relations[String(context.name)] = opts;
+    };
+}
+export function OneToOne(opts) {
+    return relation({ cardinality: '11', ...opts });
+}
+export function ManyToOne(opts) {
+    return relation({ cardinality: 'm1', ...opts });
+}
+export function OneToMany(opts) {
+    return relation({ cardinality: '1m', ...opts });
+}
+export function ManyToMany(opts) {
+    return relation({ cardinality: 'mm', ...opts });
+}
+function hook(event) {
+    return () => 
+    // Generic in `This` so a hook declared with an explicit `this` parameter still matches; the default
+    // on `ClassMethodDecoratorContext` pins `this` to `unknown` and would reject it.
+    (_value, context) => {
+        const { hooks } = memberRegistrations(context.metadata);
+        hooks[event] ??= [];
+        hooks[event].push(String(context.name));
+    };
+}
+export const BeforeInsert = hook('beforeInsert');
+export const AfterInsert = hook('afterInsert');
+export const BeforeUpdate = hook('beforeUpdate');
+export const AfterUpdate = hook('afterUpdate');
+export const BeforeDelete = hook('beforeDelete');
+export const AfterDelete = hook('afterDelete');
+export const AfterLoad = hook('afterLoad');

package/dist/entity/index.d.ts

@@ -1 +1,3 @@
-export * from './decorator/index.js';
+export * from './decorator/entity.js';
+export * from './decorator/members.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1 +1,3 @@
-export * from './decorator/index.js';
+export * from './decorator/entity.js';
+export * from './decorator/members.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, } from './metadata/definition.js';