turbine-orm 0.29.0 → 0.31.0

package/dist/query/deferred.d.ts

@@ -66,9 +66,14 @@ export interface QueryInterfaceOptions {
      * without a `limit`. Defaults to `true` so that accidental unbounded
      * queries are surfaced loudly during development. Pass `false` to silence
      * the warning entirely (e.g. for CLI tooling that intentionally streams
-     * full tables).
+     * full tables), or a per-table map (`{ userProfiles: false }`) to silence
+     * only the tables that intentionally read full sets — unlisted tables keep
+     * the default. Map keys accept BOTH the camelCase accessor name
+     * (`userProfiles`) and the snake_case table name (`user_profiles`); the
+     * snake_case entry wins if both are present. Individual calls can also
+     * override via `findMany({ warnOnUnlimited: false })`.
      */
-    warnOnUnlimited?: boolean;
+    warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
      * Enable prepared statements. When true, queries are submitted with a
      * `{ name, text, values }` object to the pg driver, which caches the

package/dist/query/filters.d.ts

@@ -5,7 +5,7 @@
  * compiler. Kept out of builder.ts so the class file stays about SQL assembly
  * and execution rather than filter-shape bookkeeping.
  */
-import type { ArrayFilter, JsonFilter, OrderBySpec, OrderDirection, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
+import type { ArrayFilter, ColumnRef, JsonFilter, JsonPathOrderBy, OrderBySpec, OrderDirection, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
 /** Check if a value is a where operator object (has at least one known operator key) */
 export declare function isWhereOperator(value: unknown): value is WhereOperator;
 /**
@@ -15,11 +15,30 @@ export declare function isWhereOperator(value: unknown): value is WhereOperator;
  * bind values and return false, as do arrays and Dates.
  */
 export declare function isUnmatchedPlainObject(value: unknown): boolean;
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+export declare const COLUMN_REF_OPERATORS: Set<string>;
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+export declare function isColumnRef(value: unknown): value is ColumnRef;
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 export declare function fingerprintOperatorShape(value: WhereOperator): string;
 /**
@@ -48,6 +67,24 @@ export declare function sortedEntries<V>(obj: Record<string, V>): [string, V][];
 export declare const UPDATE_OPERATOR_KEYS: Set<string>;
 /** Known JSONB operator keys */
 export declare const JSONB_OPERATOR_KEYS: Set<string>;
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+export declare const JSON_RANGE_OPERATORS: Record<'gt' | 'gte' | 'lt' | 'lte', string>;
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+export declare function fingerprintJsonFilterShape(filter: JsonFilter): string;
 /**
  * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
  * appear in any other where-filter shape, so the presence of one of these is
@@ -109,6 +146,14 @@ export declare function isVectorFilter(value: unknown): value is VectorFilter;
 export declare function isVectorOrderBy(value: unknown): value is VectorOrderBy;
 /** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
 export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/query/filters.js

@@ -36,17 +36,48 @@ export function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+export const COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+export function isColumnRef(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 export function fingerprintOperatorShape(value) {
     const obj = value;
     const opKeys = Object.keys(obj)
         .filter((k) => k !== 'mode')
-        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .map((k) => {
+        const v = obj[k];
+        if ((k === 'equals' || k === 'not') && v === null)
+            return `${k}:null`;
+        if (COLUMN_REF_OPERATORS.has(k) && isColumnRef(v))
+            return `${k}:col(${JSON.stringify(v.col)})`;
+        return k;
+    })
         .sort();
     const modeStr = value.mode === 'insensitive' ? ':i' : '';
     return `op(${opKeys.join(',')}${modeStr})`;
@@ -90,6 +121,36 @@ export function sortedEntries(obj) {
 export const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 export const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSON range comparison operators → SQL comparison tokens, in the FIXED order
+ * the build and collect paths iterate them. These keys are deliberately NOT in
+ * {@link JSONB_OPERATOR_KEYS}: `gt`/`gte`/`lt`/`lte` overlap with
+ * `WhereOperator`, so a bare `{ gt: 5 }` must keep its column-comparison
+ * meaning. They only compile as JSON range ops when the object is already a
+ * {@link JsonFilter} (detected via `path` / `equals` / `contains` / `hasKey`),
+ * and they always require `path`.
+ */
+export const JSON_RANGE_OPERATORS = {
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+/**
+ * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
+ * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
+ * because a numeric comparison compiles to a `::numeric` cast — a different
+ * SQL text than the text comparison — so the two must never share a cached
+ * SQL entry.
+ */
+export function fingerprintJsonFilterShape(filter) {
+    const obj = filter;
+    const parts = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort()
+        .map((k) => (k in JSON_RANGE_OPERATORS ? `${k}#${typeof obj[k] === 'number' ? 'n' : 's'}` : k));
+    return `json(${parts.join(',')})`;
+}
 /**
  * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
  * appear in any other where-filter shape, so the presence of one of these is
@@ -219,6 +280,20 @@ export function isVectorOrderBy(value) {
 export function isOrderBySpec(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
 }
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+export function isJsonPathOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value)
+        return false;
+    return Array.isArray(value.path);
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByArgs, HavingClause, JsonFilter, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/types.d.ts

@@ -18,20 +18,48 @@ export type OrderDirection = 'asc' | 'desc';
  * Precedence: per-query arg > client `relationLoadStrategy` config > `'join'`.
  */
 export type RelationLoadStrategy = 'join' | 'batched';
+/**
+ * Reference to ANOTHER COLUMN of the same table inside a where operator,
+ * enabling column-to-column comparison:
+ *
+ * ```ts
+ * where: { currentVersionId: { equals: { col: 'publishedVersionId' } } }
+ * // → WHERE "current_version_id" = "published_version_id"
+ * ```
+ *
+ * Accepted by `equals`, `not`, `gt`, `gte`, `lt`, and `lte`. The referenced
+ * field resolves through the table's columnMap (camelCase accepted, same as a
+ * where key) and compiles to a quoted identifier: NO parameter is bound.
+ * An unknown referenced field throws {@link ValidationError} (E003).
+ *
+ * Notes:
+ *  - `mode: 'insensitive'` cannot be combined with a column reference: it
+ *    throws E003 (use `client.sql` for `lower(a) = lower(b)`).
+ *  - On json/jsonb columns `equals` routes to the JSONB containment filter
+ *    first, so `{ equals: { col } }` there is treated as a JSON value, not a
+ *    column reference.
+ *
+ * `F` narrows the referenced name to the table's field names when the
+ * surrounding {@link WhereClause} knows the entity type.
+ */
+export interface ColumnRef<F extends string = string> {
+    col: F;
+}
 /** Operator object for advanced where filtering */
-export interface WhereOperator<V = unknown> {
+export interface WhereOperator<V = unknown, F extends string = string> {
     /**
      * Explicit equality: `{ equals: value }` → `column = $n`.
      * `{ equals: null }` → `column IS NULL`.
+     * `{ equals: { col: 'otherField' } }` → `column = "other_field"` ({@link ColumnRef}).
      * On json/jsonb columns `equals` routes to the JSONB containment filter
      * ({@link JsonFilter}) instead.
      */
-    equals?: V | null;
-    gt?: V;
-    gte?: V;
-    lt?: V;
-    lte?: V;
-    not?: V | null;
+    equals?: V | ColumnRef<F> | null;
+    gt?: V | ColumnRef<F>;
+    gte?: V | ColumnRef<F>;
+    lt?: V | ColumnRef<F>;
+    lte?: V | ColumnRef<F>;
+    not?: V | ColumnRef<F> | null;
     in?: V[];
     notIn?: V[];
     contains?: string;
@@ -50,7 +78,7 @@ export interface WhereOperator<V = unknown> {
  * - A text search filter object ({ search, config? })
  * - A vector distance filter object ({ distance: { to, metric, lt } }) for pgvector columns
  */
-export type WhereValue<V = unknown> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
+export type WhereValue<V = unknown, F extends string = string> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V, F> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
 /** Relation filter on a to-many relation property. */
 export interface TypedRelationFilter<U> {
     some?: WhereClause<U>;
@@ -71,7 +99,7 @@ export interface TypedToOneFilter<V> {
  * Relation names can be used with some/every/none sub-filters.
  */
 export type WhereClause<T> = {
-    [K in keyof T]?: WhereValue<T[K]>;
+    [K in keyof T]?: WhereValue<T[K], Extract<keyof T, string>>;
 } & {
     OR?: WhereClause<T>[];
     AND?: WhereClause<T>[];
@@ -148,7 +176,7 @@ export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ?
 export interface WithOptions<NestedR extends object = {}> {
     with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
-    orderBy?: Record<string, OrderDirection | OrderBySpec>;
+    orderBy?: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | RelationOrderBy>;
     limit?: number;
     /** Only include these fields from the relation */
     select?: Record<string, boolean>;
@@ -310,6 +338,13 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     relationLoadStrategy?: RelationLoadStrategy;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
+    /**
+     * Per-call override of the unbounded-findMany warning. Pass `false` when
+     * this call intentionally reads the full table (the config-level
+     * `warnOnUnlimited` stays in effect for every other call); pass `true` to
+     * force the warning even when it is disabled in config.
+     */
+    warnOnUnlimited?: boolean;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
@@ -628,6 +663,18 @@ export interface JsonFilter {
     contains?: unknown;
     /** Key existence check: column ? key */
     hasKey?: string;
+    /**
+     * Greater-than comparison of the value at `path` (required). Numbers cast
+     * the extracted text to numeric — `(col #>> path)::numeric > $n` — while
+     * strings compare as text.
+     */
+    gt?: number | string;
+    /** Greater-than-or-equal comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    gte?: number | string;
+    /** Less-than comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    lt?: number | string;
+    /** Less-than-or-equal comparison of the value at `path` (required). See {@link JsonFilter.gt}. */
+    lte?: number | string;
 }
 /** Array query operators for where clauses */
 export interface ArrayFilter {
@@ -722,6 +769,32 @@ export interface OrderBySpec {
     sort: OrderDirection;
     nulls?: 'first' | 'last';
 }
+/**
+ * Ordering by a JSON path on a json/jsonb column of the SAME table:
+ *
+ * ```ts
+ * orderBy: { data: { path: ['weight'], direction: 'asc', type: 'numeric' } }
+ * // → ORDER BY ("data" #>> $n::text[])::numeric ASC
+ * ```
+ *
+ * The path is bound as a single text[] parameter (never interpolated).
+ * Comparison rule: values extracted from the path compare as TEXT by default;
+ * pass `type: 'numeric'` to cast for numeric comparison (`::numeric` on
+ * PostgreSQL). The column must be json/jsonb: anything else throws
+ * {@link ValidationError} (E003). Non-Postgres engines route through the same
+ * dialect JSON-extract hook the JSON where-filters use. Cross-relation
+ * (lateral) JSON ordering is NOT supported: same-table columns only.
+ */
+export interface JsonPathOrderBy {
+    /** JSON path into the column (each element a key or array index). Bound as one text[] param. */
+    path: (string | number)[];
+    /** Sort direction. Defaults to `'asc'`. */
+    direction?: OrderDirection;
+    /** Comparison kind for the extracted value. Defaults to `'text'`; `'numeric'` adds a numeric cast. */
+    type?: 'numeric' | 'text';
+    /** NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}). */
+    nulls?: 'first' | 'last';
+}
 /**
  * Ordering by a relation, keyed by the relation name in an {@link OrderByClause}:
  *
@@ -738,9 +811,10 @@ export type RelationOrderBy = {
  * An orderBy clause maps each key to one of:
  *  - a plain direction (`'asc'` / `'desc'`),
  *  - an {@link OrderBySpec} (`{ sort, nulls }`) for NULLS placement,
+ *  - for json/jsonb columns, a JSON-path ordering ({@link JsonPathOrderBy}),
  *  - for pgvector columns, a KNN distance ordering ({@link VectorOrderBy}),
  *  - for a relation name, a {@link RelationOrderBy} (`_count` for to-many, a
  *    target column for to-one).
  */
-export type OrderByClause = Record<string, OrderDirection | OrderBySpec | VectorOrderBy | RelationOrderBy>;
+export type OrderByClause = Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | VectorOrderBy | RelationOrderBy>;
 export {};

package/dist/schema-metadata.d.ts

@@ -0,0 +1,77 @@
+/**
+ * turbine-orm — defineSchema() → SchemaMetadata bridge
+ *
+ * Converts a code-first {@link SchemaDef} (the output of `defineSchema()`)
+ * into the runtime {@link SchemaMetadata} shape that the query builder,
+ * `TurbineClient`, and the non-SQL engines consume — without touching a
+ * live database.
+ *
+ * Why this exists: the historical converter path (`introspect()` +
+ * `generate()`) requires a running SQL database, but code-first engines
+ * (PowDB, in-memory SQLite bootstraps, tests) only have the `SchemaDef`.
+ * `schemaDefToMetadata()` is the pure-function equivalent: its output
+ * matches what `turbine generate` would emit into `metadata.ts` for the
+ * same schema, minus the pieces only a live catalog can know (real index
+ * names, constraint names, view flags).
+ *
+ * Parity notes (ground truth = introspect.ts + generate.ts):
+ *   - Relations are derived from `references:` exactly like introspection
+ *     derives them from foreign keys: a `belongsTo` on the child table and
+ *     a `hasMany` on the parent, with the same disambiguation rules when
+ *     multiple FKs point at the same target.
+ *   - Pure junction tables (2-column composite PK that IS the two
+ *     single-column FKs to two distinct tables, no payload columns) get
+ *     the same conservative auto-`manyToMany` treatment as introspection.
+ *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
+ *     {@link applyManyToManyRelations} (additive, never clobbering).
+ *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
+ *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
+ *     and the dev-mode missing-index warning stay silent instead of
+ *     producing blanket false positives.
+ *
+ * @example
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata } from 'turbine-orm';
+ *
+ * const def = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, name: { type: 'text', notNull: true } },
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            userId: { type: 'integer', notNull: true, references: 'users.id' } },
+ * });
+ * const metadata = schemaDefToMetadata(def);
+ * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
+ * ```
+ */
+import { type SchemaMetadata } from './schema.js';
+import { type SchemaDef } from './schema-builder.js';
+/**
+ * Convert a code-first {@link SchemaDef} into runtime {@link SchemaMetadata}.
+ *
+ * Pure function — no database connection, no side effects, input untouched.
+ * The output is shaped identically to the `SCHEMA` constant `turbine generate`
+ * emits from introspection, so it can be handed to any consumer that expects
+ * introspected metadata: `new TurbineClient(config, metadata)`,
+ * `turbinePowDB(..., metadata)`, `QueryInterface`, the index advisor, etc.
+ *
+ * What maps:
+ *   - Columns → full {@link ColumnMetadata} (snake_case name, camelCase field,
+ *     pg type names, TS types, nullability, defaults, `isGenerated` for
+ *     serial/bigserial, array + varchar length info, date-column tracking).
+ *   - Column-level `primaryKey` and table-level composite `primaryKey`.
+ *   - `unique: true` columns → single-column `uniqueColumns` entries.
+ *   - `references:` FKs → `belongsTo` (child) + `hasMany` (parent) relations,
+ *     including `onDelete`/`onUpdate` actions (the `'no action'` default is
+ *     omitted, matching introspection).
+ *   - Pure junction tables → auto-detected `manyToMany` relations (same
+ *     conservative rules as introspection).
+ *   - Explicit `manyToMany` declarations → merged additively.
+ *   - Schema-level `enums`.
+ *
+ * What SchemaDef cannot express (and how it degrades):
+ *   - Indexes → every table gets `indexes: []`, which keeps
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
+ *     false positives on code-first metadata.
+ *   - Views → never marked (`isView` is introspection-only).
+ *   - Composite foreign keys → `references:` is single-column by design.
+ */
+export declare function schemaDefToMetadata(def: SchemaDef): SchemaMetadata;