uql-orm 0.25.1 → 0.26.0

package/README.md

@@ -9,7 +9,7 @@
 
 <h3>The smartest TypeScript ORM</h3>
 
-<p>Type-safe to the leaf, serializable queries, no codegen, <a href="https://uql-orm.dev/benchmark">extremely fast</a>, and one API across every SQL database, MongoDB, and every runtime.</p>
+<p>Type-safe to the leaf, serializable queries, no codegen, and one API across every SQL database, MongoDB, and every runtime. And the <a href="https://uql-orm.dev/benchmark">fastest</a>.</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·
@@ -50,14 +50,15 @@ from the browser to the server. The same object runs on every supported database
 
 ## Why UQL?
 
-- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.4× faster than the runner-up on average, reaching over 4.6M ops/s on simple SELECTs.
+- **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. Entities are plain classes: no `.prisma` file, no generated client, no build step.
+- **Queries are data (JSON), not method chains.** Plain JSON in, typed rows out. No DSL to learn.
+- **One API, everywhere it runs.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
+- **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) loads a to-many with one query for all parents, not one per parent. Nothing is lazy, so nothing fires behind your back in a serializer.
+- **Migrations you read before they run.** Edit an entity, run `uql-migrate generate:entities`, review the SQL in the PR like any other file. [`drift:check`](https://uql-orm.dev/migrations) catches a database that no longer matches.
+- **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [virtual fields](https://uql-orm.dev/entities/virtual-fields) are sub-queries you can filter on, and a migration can be plain SQL.
 - **Light.** Zero runtime dependencies, 305 kB on the wire, every dialect included. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
-- **Queries are data (JSON), not method chains.** Plain JSON in, typed rows out. There's no DSL to learn and nothing to compile.
-- **Type-safe to the leaf.** Every key is autocompleted and checked against your entity, down to the fields of a populated relation. Operators are gated per field type, and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths resolve each path's value type, so `$like` on a numeric column, or a typo'd path, is a compile error instead of a runtime surprise.
-- **No codegen, no build step.** Entities are TypeScript classes, so your code *is* the schema. There's no `.prisma` file to regenerate and no generated client to keep in sync.
-- **One API everywhere.** PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB!
-- **Runs on every runtime.** Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser). ESM-only with no native binaries on the `fetch`-based drivers, so an edge bundle needs no special build.
-- **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).
+- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [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).
+- **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark): 278µs, against 621µs for the next closest and 1,889µs for the slowest.
 
 ## Get started
 

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

@@ -5,7 +5,7 @@
     "import type { RequestCallback, RequestNotification } from '../type/index.js';\n\nconst subscriptors: RequestCallback[] = [];\n\nexport function notify(notification: RequestNotification): void {\n  for (const subscriptor of subscriptors) {\n    subscriptor(notification);\n  }\n}\n\nexport function on(cb: RequestCallback): () => void {\n  subscriptors.push(cb);\n  const index = subscriptors.length - 1;\n  return (): void => {\n    subscriptors.splice(index, 1);\n  };\n}\n",
     "import type { 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",
+    "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) => {\n      // Lower-casing the rest is only right for a word that carries no case of its own: it turns\n      // `USER_ID` into `UserId`, but it also turns `tenantId` into `Tenantid`.\n      const rest = word === word.toUpperCase() ? word.slice(1).toLowerCase() : word.slice(1);\n      return word.charAt(0).toUpperCase() + rest;\n    })\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// 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",

package/dist/cockroachdb/cockroachDialect.js

@@ -26,7 +26,7 @@ export class CockroachDialect extends PgLikeSqlDialect {
      * `NULLS FIRST/LAST` answers "unimplemented: this syntax" and `jsonb_path_ops` "operator class is
      * not supported" (both verified on v26.2), so neither is offered here.
      */
-    indexFeatures = new Set(['expression', 'include']);
+    indexFeatures = new Set(['expression', 'partial', 'include']);
     /**
      * CockroachDB's vector index is native and has its own syntax: `CREATE VECTOR INDEX ... ("col"
      * vector_cosine_ops)`, with no access-method keyword, and tuning knobs of its own names that UQL

package/dist/dialect/indexSqlDialect.d.ts

@@ -50,8 +50,9 @@ export declare abstract class IndexSqlDialect extends VectorSqlDialect {
     /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
     protected indexTuning(_index: IndexSchema): string;
     /**
-     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
-     * silently widening a partial unique index changes which rows the database accepts.
+     * The partial-index predicate. Engines without one reject the index in {@link assertIndexFeatures}
+     * rather than reaching here: silently widening a partial unique index changes which rows the
+     * database accepts.
      */
     protected indexPredicate(index: IndexSchema): string;
 }

package/dist/dialect/indexSqlDialect.js

@@ -18,7 +18,7 @@ export class IndexSqlDialect extends VectorSqlDialect {
         this.assertIndexFeatures(index);
         const unique = index.unique ? 'UNIQUE ' : '';
         const ifNotExists = (opts.ifNotExists ?? this.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
-        const columns = index.columns.map((entry) => this.indexColumn(entry, index)).join(', ');
+        const columns = index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
         return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.escapeId(index.name)} ` +
             `ON ${this.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
             `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
@@ -28,13 +28,14 @@ export class IndexSqlDialect extends VectorSqlDialect {
      * refused by at least one other, so an index asking for a missing one is rejected rather than
      * emitted: each of them is a hard error at the server, not a slower plan.
      */
-    indexFeatures = new Set(['expression']);
+    indexFeatures = new Set(['expression', 'partial']);
     assertIndexFeatures(index) {
         const requested = [
-            ['expression', index.columns.some((entry) => entry.expression)],
-            ['prefixLength', index.columns.some((entry) => entry.length !== undefined)],
-            ['nullsOrder', index.columns.some((entry) => entry.nulls !== undefined)],
-            ['opsClass', index.columns.some((entry) => entry.opsClass !== undefined)],
+            ['expression', index.entries.some((entry) => entry.expression)],
+            ['partial', index.where !== undefined],
+            ['prefixLength', index.entries.some((entry) => entry.length !== undefined)],
+            ['nullsOrder', index.entries.some((entry) => entry.nulls !== undefined)],
+            ['opsClass', index.entries.some((entry) => entry.opsClass !== undefined)],
             ['include', Boolean(index.include?.length)],
         ];
         for (const [feature, needed] of requested) {
@@ -92,8 +93,9 @@ export class IndexSqlDialect extends VectorSqlDialect {
         return '';
     }
     /**
-     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
-     * silently widening a partial unique index changes which rows the database accepts.
+     * The partial-index predicate. Engines without one reject the index in {@link assertIndexFeatures}
+     * rather than reaching here: silently widening a partial unique index changes which rows the
+     * database accepts.
      */
     indexPredicate(index) {
         return index.where ? ` WHERE ${index.where}` : '';

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -56,8 +56,6 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     protected indexKeyword(index: IndexSchema): string;
     protected readonly indexFeatures: Set<IndexFeature>;
     protected indexAccessMethod(index: IndexSchema): string;
-    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
-    protected indexPredicate(index: IndexSchema): string;
     protected numericCast(expr: string): string;
     protected ilikeExpr(f: string, ph: string): string;
     protected neExpr(field: string, ph: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -105,13 +105,6 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     indexAccessMethod(index) {
         return index.type && index.type !== 'fulltext' ? ` USING ${index.type}` : '';
     }
-    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
-    indexPredicate(index) {
-        if (index.where) {
-            throw new TypeError(`${this.dialectName} does not support partial indexes (index "${index.name}" declares a "where" condition)`);
-        }
-        return '';
-    }
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
     }

package/dist/dialect/pgLikeSqlDialect.js

@@ -70,6 +70,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     }
     indexFeatures = new Set([
         'expression',
+        'partial',
         'nullsOrder',
         'opsClass',
         'include',

package/dist/maria/mariaDialect.js

@@ -72,7 +72,7 @@ export class MariaDialect extends MysqlLikeSqlDialect {
      * being dropped, which would silently build the index on cosine instead.
      */
     getInlineVectorIndexDeclaration(index) {
-        const columns = index.columns.map((entry) => this.indexColumnTarget(entry)).join(', ');
+        const columns = index.entries.map((entry) => this.indexColumnTarget(entry)).join(', ');
         let clause = `VECTOR INDEX (${columns})`;
         if (index.m !== undefined) {
             clause += ` M=${index.m}`;

package/dist/migrate/builder/migrationBuilder.js

@@ -27,7 +27,7 @@ function createIndexOperation(tableName, columns, options = {}) {
         index: {
             ...index,
             name: name ?? `idx_${tableName}_${entries.map((entry) => entry.column).join('_')}`,
-            columns: entries,
+            entries,
             unique: unique ?? false,
         },
     };

package/dist/migrate/builder/tableBuilder.js

@@ -167,7 +167,7 @@ export class TableBuilder {
         this._indexes.push({
             ...rest,
             name: name ?? `${prefix}_${this._name}_${entries.map((entry) => entry.column).join('_')}`,
-            columns: entries,
+            entries,
             unique,
         });
         return this;
@@ -195,7 +195,7 @@ export class TableBuilder {
                 if (!this._indexes.some((idx) => idx.name === indexName)) {
                     this._indexes.push({
                         name: indexName,
-                        columns: [{ column: col.name }],
+                        entries: [{ column: col.name }],
                         unique: col.unique,
                     });
                 }

package/dist/migrate/cli.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { SchemaASTBuilder } from '../schema/index.js';
 import { assertCliConfig } from './assertCliConfig.js';
 import { loadConfig } from './cli-config.js';
 import { createEntityCodeGenerator } from './codegen/entityCodeGenerator.js';
 import { detectDrift } from './drift/driftDetector.js';
 import { Migrator } from './migrator.js';
-import { createSchemaGenerator } from './schemaGenerator.js';
+import { buildEntityAST, createSchemaGenerator } from './schemaGenerator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 import { DEFAULT_MIGRATIONS_TABLE } from './storage/databaseStorage.js';
 /** Sync helper for SQL dialects only; returns `undefined` for MongoDB - use {@link createSchemaGeneratorAsync}. */
@@ -253,21 +252,20 @@ export async function runDriftCheck(migrator, config) {
         console.error('No entities configured. Add entities to your uql config.');
         process.exit(1);
     }
-    else if (!migrator.schemaIntrospector) {
+    else if (!migrator.schemaIntrospector || !migrator.schemaGenerator) {
         console.error('No introspector available. Check your pool configuration.');
         process.exit(1);
     }
     else {
         console.log('\nChecking for schema drift...');
-        // Build expected schema from entities
-        const builder = new SchemaASTBuilder();
-        const expectedAST = builder.fromEntities(config.entities);
+        const expectedAST = buildEntityAST(migrator.schemaGenerator, config.entities);
         // Build actual schema from database
         const actualAST = await migrator.schemaIntrospector.introspect();
         // Detect drift. The dialect renders canonical types as SQL - without it every type formats as
         // `unknown` and type drift compares equal, silently reporting a mismatched column as in sync.
         const report = detectDrift(expectedAST, actualAST, {
             dialect: config.pool?.dialect,
+            indexFacets: migrator.schemaIntrospector.indexFacets,
             excludeTables: [config.tableName ?? DEFAULT_MIGRATIONS_TABLE],
         });
         printDriftReport(report);

package/dist/migrate/codegen/entityCodeGenerator.d.ts

@@ -85,6 +85,11 @@ export declare class EntityCodeGenerator {
      * Build Field decorator options.
      */
     private buildFieldOptions;
+    /**
+     * The indexes this table needs an `@Index` for, which is every one a `@Field({ index })` cannot
+     * carry on its own.
+     */
+    private declaredIndexes;
     /**
      * Build relation definitions.
      */

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -13,6 +13,7 @@ import { canonicalToTypeScript } from '../../schema/canonicalType.js';
 import { DEFAULT_FOREIGN_KEY_ACTION, } from '../../schema/types.js';
 import { camelCase, pascalCase, singularize } from '../../util/string.util.js';
 import { buildFieldOptionsSource } from './fieldOptionsSource.js';
+import { buildIndexDecoratorSource, indexNeedsRaw, isPlainFieldIndex } from './indexDecoratorSource.js';
 /**
  * Generates TypeScript entity code from SchemaAST.
  */
@@ -91,12 +92,14 @@ export class EntityCodeGenerator {
                 }
             }
         }
-        // Check for composite index decorators
         if (this.options.includeIndexes) {
-            const compositeIndexes = this.ast.getTableIndexes(table.name).filter((idx) => idx.columns.length > 1);
-            if (compositeIndexes.length > 0) {
+            const declared = this.declaredIndexes(table);
+            if (declared.length > 0) {
                 uqlImports.add('Index');
             }
+            if (declared.some(indexNeedsRaw)) {
+                uqlImports.add('raw');
+            }
         }
         let code = `import { ${Array.from(uqlImports).sort().join(', ')} } from '${this.options.uqlImportPath}';\n`;
         // Add related entity imports
@@ -110,18 +113,9 @@ export class EntityCodeGenerator {
      */
     buildEntityDecorators(table) {
         const lines = [];
-        // Add composite index decorators
         if (this.options.includeIndexes) {
-            const compositeIndexes = this.ast.getTableIndexes(table.name).filter((idx) => idx.columns.length > 1);
-            for (const idx of compositeIndexes) {
-                const propNames = idx.columns.map((c) => `'${this.options.propertyNameTransformer(c.name)}'`).join(', ');
-                const options = [];
-                if (idx.name)
-                    options.push(`name: '${idx.name}'`);
-                if (idx.unique)
-                    options.push('unique: true');
-                const optStr = options.length > 0 ? `, { ${options.join(', ')} }` : '';
-                lines.push(`@Index([${propNames}]${optStr})`);
+            for (const index of this.declaredIndexes(table)) {
+                lines.push(buildIndexDecoratorSource(index, this.options.propertyNameTransformer));
             }
         }
         // Entity decorator
@@ -158,11 +152,11 @@ export class EntityCodeGenerator {
         }
         // Decorator
         if (col.isPrimaryKey) {
-            const idOptions = this.buildIdOptions(col);
+            const idOptions = this.buildIdOptions(col, propertyName);
             lines.push(`  @Id(${idOptions})`);
         }
         else {
-            const fieldOptions = this.buildFieldOptions(col);
+            const fieldOptions = this.buildFieldOptions(col, propertyName);
             lines.push(`  @Field(${fieldOptions})`);
         }
         // Property
@@ -173,20 +167,23 @@ export class EntityCodeGenerator {
     /**
      * Build Id decorator options.
      */
-    buildIdOptions(col) {
-        const options = [];
-        if (col.name !== 'id') {
-            options.push(`name: '${col.name}'`);
-        }
-        return options.length > 0 ? `{ ${options.join(', ')} }` : '';
+    buildIdOptions(col, propertyName) {
+        return propertyName === col.name ? '' : `{ name: '${col.name}' }`;
     }
     /**
      * Build Field decorator options.
      */
-    buildFieldOptions(col) {
+    buildFieldOptions(col, propertyName) {
         const indexes = this.options.includeIndexes ? this.ast.getTableIndexes(col.table.name) : [];
-        const singleColIndex = indexes.find((idx) => idx.columns.length === 1 && idx.columns[0].name === col.name);
-        return buildFieldOptionsSource(col, singleColIndex?.name);
+        const fieldIndex = indexes.find((idx) => isPlainFieldIndex(idx) && idx.entries[0]?.column === col.name);
+        return buildFieldOptionsSource(col, propertyName, fieldIndex?.name);
+    }
+    /**
+     * The indexes this table needs an `@Index` for, which is every one a `@Field({ index })` cannot
+     * carry on its own.
+     */
+    declaredIndexes(table) {
+        return this.ast.getTableIndexes(table.name).filter((index) => !isPlainFieldIndex(index));
     }
     /**
      * Build relation definitions.

package/dist/migrate/codegen/fieldOptionsSource.d.ts

@@ -7,4 +7,4 @@ import type { ColumnNode } from '../../schema/types.js';
  * merging a column into an existing entity file quietly produced a weaker field than generating the
  * file from scratch.
  */
-export declare function buildFieldOptionsSource(col: ColumnNode, indexName?: string): string;
+export declare function buildFieldOptionsSource(col: ColumnNode, propertyName: string, indexName?: string): string;

package/dist/migrate/codegen/fieldOptionsSource.js

@@ -7,8 +7,13 @@ import { canonicalToColumnType } from '../../schema/canonicalType.js';
  * merging a column into an existing entity file quietly produced a weaker field than generating the
  * file from scratch.
  */
-export function buildFieldOptionsSource(col, indexName) {
+export function buildFieldOptionsSource(col, propertyName, indexName) {
     const options = [];
+    // Without this the entity maps to a column named after the property, which for anything the
+    // transformer rewrote - every `user_id` - is a column the database does not have.
+    if (propertyName !== col.name) {
+        options.push(`name: '${col.name}'`);
+    }
     const columnType = canonicalToColumnType(col.type);
     if (columnType) {
         options.push(`columnType: '${columnType}'`);

package/dist/migrate/codegen/indexDecoratorSource.d.ts

@@ -0,0 +1,14 @@
+import type { IndexNode } from '../../schema/types.js';
+/**
+ * Whether `@Field({ index })` can carry the whole index. It says only "this column is indexed under
+ * this name", so anything else the index declares - an expression, a predicate, uniqueness, an access
+ * method, stored columns, a stored order - has to be written out as `@Index([...])` instead.
+ */
+export declare function isPlainFieldIndex(index: IndexNode): boolean;
+/**
+ * One `@Index([...])` as source, for an index no `@Field` can express. Emits `raw(...)` for an
+ * expression entry, so callers import `raw` when {@link indexNeedsRaw} holds.
+ */
+export declare function buildIndexDecoratorSource(index: IndexNode, propertyName: (column: string) => string): string;
+/** Whether emitting this index needs `raw` imported alongside `Index`. */
+export declare function indexNeedsRaw(index: IndexNode): boolean;

package/dist/migrate/codegen/indexDecoratorSource.js

@@ -0,0 +1,105 @@
+/**
+ * A vector index carries its metric in the operator class pgvector names after it
+ * (`vector_cosine_ops`), which is the only place introspection can recover it from. `@Index` requires
+ * a `distance` beside a vector `type`, so emitting the type without one would not compile.
+ */
+const DISTANCE_BY_OPS_SUFFIX = new Map([
+    ['cosine', 'cosine'],
+    ['l2', 'l2'],
+    ['ip', 'inner'],
+    ['l1', 'l1'],
+]);
+function vectorDistance(index) {
+    if (index.distance) {
+        return index.distance;
+    }
+    const opsClass = index.entries.map((entry) => entry.opsClass).find(Boolean);
+    const suffix = opsClass?.match(/_(\w+)_ops$/)?.[1];
+    return suffix === undefined ? undefined : DISTANCE_BY_OPS_SUFFIX.get(suffix);
+}
+/**
+ * The per-entry modifiers worth writing into an entity, which is not everything introspection reports.
+ * Postgres states an entry in full - a plain column comes back `order: 'asc', nulls: 'last'` - and
+ * emitting that would bake one engine's defaults into source that is meant to run on any of them.
+ * `nulls` never survives for the same reason: it is Postgres-only and always reported.
+ */
+function significantModifiers(entry) {
+    const parts = [];
+    if (entry.order === 'desc')
+        parts.push(`order: 'desc'`);
+    if (entry.opsClass)
+        parts.push(`opsClass: '${entry.opsClass}'`);
+    if (entry.length !== undefined)
+        parts.push(`length: ${entry.length}`);
+    return parts;
+}
+/**
+ * Whether `@Field({ index })` can carry the whole index. It says only "this column is indexed under
+ * this name", so anything else the index declares - an expression, a predicate, uniqueness, an access
+ * method, stored columns, a stored order - has to be written out as `@Index([...])` instead.
+ */
+export function isPlainFieldIndex(index) {
+    const entries = index.entries;
+    const [entry] = entries;
+    return (entries.length === 1 &&
+        entry !== undefined &&
+        !entry.expression &&
+        !index.unique &&
+        index.where === undefined &&
+        // Postgres names an access method on every index, so the default one still counts as plain.
+        (index.type === undefined || index.type === 'btree') &&
+        !index.include?.length &&
+        significantModifiers(entry).length === 0);
+}
+/**
+ * One `@Index([...])` as source, for an index no `@Field` can express. Emits `raw(...)` for an
+ * expression entry, so callers import `raw` when {@link indexNeedsRaw} holds.
+ */
+export function buildIndexDecoratorSource(index, propertyName) {
+    const entries = index.entries.map((entry) => indexEntrySource(entry, propertyName)).join(', ');
+    const isVector = index.type === 'hnsw' || index.type === 'ivfflat';
+    const distance = isVector ? vectorDistance(index) : undefined;
+    const options = [];
+    if (index.name)
+        options.push(`name: '${index.name}'`);
+    if (index.unique)
+        options.push('unique: true');
+    // `btree` is every engine's default and is reported on every index, so writing it out would put it
+    // in every generated entity. A vector type whose metric could not be recovered is left off too,
+    // rather than written out in a form that does not compile.
+    const writesType = index.type !== undefined && index.type !== 'btree' && (distance !== undefined || !isVector);
+    if (writesType) {
+        options.push(`type: '${index.type}'`);
+    }
+    if (distance)
+        options.push(`distance: '${distance}'`);
+    if (index.where)
+        options.push(`where: ${quote(index.where)}`);
+    if (index.include?.length) {
+        options.push(`include: [${index.include.map((column) => `'${propertyName(column)}'`).join(', ')}]`);
+    }
+    return `@Index([${entries}]${options.length > 0 ? `, { ${options.join(', ')} }` : ''})`;
+}
+/** Whether emitting this index needs `raw` imported alongside `Index`. */
+export function indexNeedsRaw(index) {
+    return index.entries.some((entry) => entry.expression);
+}
+function indexEntrySource(entry, propertyName) {
+    if (entry.expression) {
+        return `raw(${quote(entry.column)})`;
+    }
+    const modifiers = significantModifiers(entry);
+    if (modifiers.length === 0) {
+        return `'${propertyName(entry.column)}'`;
+    }
+    return `{ column: '${propertyName(entry.column)}', ${modifiers.join(', ')} }`;
+}
+/**
+ * SQL as a TypeScript string literal. `JSON.stringify` rather than hand-rolled quoting: a reprinted
+ * expression is arbitrary text, and it arrives multi-line, carrying quotes of both kinds and
+ * backslashes (`name ~ '\\d+'`), each of which a naive wrapper turns into source that does not
+ * compile or, worse, compiles to a different index.
+ */
+function quote(sql) {
+    return JSON.stringify(sql);
+}

package/dist/migrate/drift/driftDetector.d.ts

@@ -5,6 +5,7 @@
  * actual database schema.
  */
 import type { AbstractDialect } from '../../dialect/abstractDialect.js';
+import type { IndexFacet } from '../../schema/indexDifferences.js';
 import type { SchemaAST } from '../../schema/schemaAST.js';
 import type { DriftReport } from '../../schema/types.js';
 /**
@@ -17,6 +18,8 @@ export interface DriftDetectorOptions {
     checkNullable?: boolean;
     /** Include index differences */
     checkIndexes?: boolean;
+    /** `indexFacets` of the introspector that produced the actual schema; anything else goes uncompared. */
+    indexFacets?: ReadonlySet<IndexFacet>;
     /** Include foreign key differences */
     checkForeignKeys?: boolean;
     /**
@@ -34,55 +37,7 @@ export interface DriftDetectorOptions {
     dialect?: AbstractDialect;
 }
 /**
- * Detects drift between expected and actual database schemas.
- */
-export declare class DriftDetector {
-    private readonly expectedAST;
-    private readonly actualAST;
-    private readonly options;
-    constructor(expectedAST: SchemaAST, actualAST: SchemaAST, options?: DriftDetectorOptions);
-    /**
-     * Detect all schema drift.
-     */
-    detect(): DriftReport;
-    /**
-     * Detect table-level drifts (missing/unexpected tables).
-     */
-    private detectTableDrifts;
-    /**
-     * Detect column-level drifts.
-     */
-    private detectColumnDrifts;
-    /**
-     * Add drifts for column alterations (type/nullable mismatches).
-     */
-    private addAlterColumnDrifts;
-    /**
-     * Detect index drifts.
-     */
-    private detectIndexDrifts;
-    /**
-     * Detect relationship/FK drifts.
-     */
-    private detectRelationshipDrifts;
-    /**
-     * Calculate overall status based on drifts.
-     */
-    private calculateStatus;
-    /**
-     * Create a summary of drifts by severity.
-     */
-    private createSummary;
-    /**
-     * Format type for display.
-     */
-    private formatType;
-}
-/**
- * Create a DriftDetector for comparing expected vs actual schemas.
- */
-export declare function createDriftDetector(expectedAST: SchemaAST, actualAST: SchemaAST, options?: DriftDetectorOptions): DriftDetector;
-/**
- * Quick check for schema drift.
+ * Compare an expected schema (from entities) with an actual one (from the database) and report every
+ * way they have drifted apart.
  */
 export declare function detectDrift(expectedAST: SchemaAST, actualAST: SchemaAST, options?: DriftDetectorOptions): DriftReport;