turbine-orm 0.33.0 → 0.34.0

package/dist/cjs/query/builder.js

@@ -4527,7 +4527,18 @@ class QueryInterface {
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+        // Rows whose document lacks the path extract to NULL. Without a nulls
+        // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
+        // pick-row ordering (NULLS LAST both directions since 0.33) and from
+        // engines whose path ordering is nulls-last in both directions. Default to
+        // NULLS LAST in BOTH directions unless the caller set `nulls` explicitly;
+        // the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `${lhs} ${dir}${nullsSql}`;
     }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed

package/dist/cjs/schema-builder.js

@@ -25,6 +25,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
+exports.isDocFieldIndexDef = isDocFieldIndexDef;
 exports.defineSchema = defineSchema;
 exports.table = table;
 exports.applyManyToManyRelations = applyManyToManyRelations;
@@ -102,6 +103,10 @@ function resolveColumn(def) {
         check: def.check ?? null,
     };
 }
+/** Type guard: is this index declaration a doc-field expression index? */
+function isDocFieldIndexDef(idx) {
+    return 'docField' in idx && typeof idx.docField === 'string';
+}
 /** Check if a value is a TableDef (from legacy table() builder) */
 function isTableDef(v) {
     return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
@@ -145,7 +150,17 @@ function defineSchema(input, options) {
             let pk;
             let m2m;
             let checks;
+            let indexes;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'indexes') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                        }
+                        indexes = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
@@ -205,6 +220,7 @@ function defineSchema(input, options) {
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
                 ...(checks && checks.length > 0 ? { checks } : {}),
+                ...(indexes && indexes.length > 0 ? { indexes } : {}),
             };
         }
     }

package/dist/cjs/schema-metadata.js

@@ -25,10 +25,12 @@
  *     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.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -45,6 +47,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.schemaDefToMetadata = schemaDefToMetadata;
+const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
 const schema_js_1 = require("./schema.js");
 const schema_builder_js_1 = require("./schema-builder.js");
@@ -97,6 +100,67 @@ function resolveColumnName(raw, target) {
     return (0, schema_js_1.camelToSnake)(raw);
 }
 // ---------------------------------------------------------------------------
+// Index declarations → IndexMetadata
+// ---------------------------------------------------------------------------
+/**
+ * Render a doc-field JSON path into an illustrative PowQL fragment for the
+ * `IndexMetadata.definition` field (debuggability only; the authoritative,
+ * lexer-exact emission lives in `powqlSchemaDDL`). String segments are shown
+ * double-quoted, integer array indexes bare.
+ */
+function docPathFragment(column, path) {
+    const segs = path.map((s) => (typeof s === 'number' ? `->${s}` : `->"${s}"`)).join('');
+    return `(.${column}${segs})`;
+}
+/**
+ * Convert a table's {@link SchemaIndexDef} list into {@link IndexMetadata}.
+ * A doc-field index carries `docPath` and `columns: [<json column>]`; a plain
+ * column index carries its snake_case column list and no `docPath`. Names are
+ * auto-derived (`<table>_<cols>_idx`) when not supplied.
+ */
+function mapIndexes(tableDef, declared) {
+    if (!declared || declared.length === 0)
+        return [];
+    const out = [];
+    for (const idx of declared) {
+        if ((0, schema_builder_js_1.isDocFieldIndexDef)(idx)) {
+            const column = (0, schema_js_1.camelToSnake)(idx.docField);
+            const segPart = idx.path.map((s) => (typeof s === 'number' ? String(s) : s)).join('_');
+            const name = idx.name ?? `${tableDef.name}_${column}_${segPart}_idx`;
+            // Validate numeric (array-index) segments up front: PowDB rejects a
+            // negative / fractional / NaN JSON-path index at migration time with an
+            // opaque parse error, so fail here with a typed ValidationError naming the
+            // index instead of emitting malformed PowQL later.
+            for (const seg of idx.path) {
+                if (typeof seg === 'number' && (!Number.isInteger(seg) || seg < 0)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Doc-field index "${name}" on "${tableDef.name}": array-index path segment ${seg} must be a ` +
+                        'non-negative integer (a JSON array index). Use a string for an object key.');
+                }
+            }
+            out.push({
+                name,
+                columns: [column],
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}${docPathFragment(column, idx.path)}`,
+                docPath: [...idx.path],
+                declared: true,
+            });
+        }
+        else {
+            const columns = idx.columns.map(schema_js_1.camelToSnake);
+            const name = idx.name ?? `${tableDef.name}_${columns.join('_')}_idx`;
+            out.push({
+                name,
+                columns,
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}(${columns.join(', ')})`,
+                declared: true,
+            });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // The converter
 // ---------------------------------------------------------------------------
 /**
@@ -122,10 +186,14 @@ function resolveColumnName(raw, target) {
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * 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.
  */
@@ -302,9 +370,12 @@ function schemaDefToMetadata(def) {
             primaryKey: pk,
             uniqueColumns,
             relations: relationsByTable.get(tableDef.name) ?? {},
-            // SchemaDef cannot express indexes. An empty list keeps
-            // schemaHasIndexInfo() false → no index-advisor false positives.
-            indexes: [],
+            // Declared `indexes` (plain column + doc-field expression) carry through;
+            // an undeclared table gets `[]`, which keeps schemaHasIndexInfo() false so
+            // the index advisor stays silent. Doc-field (docPath) indexes are ignored
+            // by the advisor entirely (see index-advisor.ts), so a doc-only index set
+            // never flips schemaHasIndexInfo() and never produces FK false positives.
+            indexes: mapIndexes(tableDef, tableDef.indexes),
         };
     }
     const enums = {};

package/dist/index-advisor.d.ts

@@ -58,7 +58,21 @@ export declare function isProbeIndexed(meta: TableMetadata, columns: string[]):
  * should gate on {@link schemaHasIndexInfo} to avoid blanket false positives.
  */
 export declare function findMissingRelationIndexes(schema: SchemaMetadata): MissingRelationIndex[];
-/** True when at least one table in the schema carries index metadata. */
+/**
+ * True when at least one table in the schema carries real, DB-backed index
+ * metadata (i.e. from introspection).
+ *
+ * Excluded (so they never flip the flag, keeping the schema "index-info
+ * unknown"):
+ *   - doc-field expression indexes (`docPath`): they carry no FK-coverage info;
+ *   - code-first DECLARED indexes (`declared`): the SQL DDL generators do NOT
+ *     emit `TableDef.indexes` yet, so a declared index does not reflect a real
+ *     index on the SQL engines. Counting one would arm blanket FK false
+ *     positives (the FK auto-index the push path DID create is then reported
+ *     "missing") and, inversely, suppress warnings for indexes never created.
+ *     A pure code-first schema therefore stays silent exactly as it did before
+ *     `TableDef.indexes` existed.
+ */
 export declare function schemaHasIndexInfo(schema: SchemaMetadata): boolean;
 /**
  * Single-relation check for the dev-mode runtime warning: the (table, columns)

package/dist/index.d.ts

@@ -47,7 +47,7 @@ export { type AggregateArgs, type AggregateResult, type ArrayFilter, type Column
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
-export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';
 export { schemaDefToMetadata } from './schema-metadata.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';

package/dist/index.js

@@ -53,7 +53,7 @@ export { validateChannel } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
-export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
+export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, isDocFieldIndexDef, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB

package/dist/optional-peer-import.cjs

@@ -86,4 +86,32 @@ async function importOptionalPeer(specifier, allowEsmFallback = true) {
         return esmCapableCopy(specifier, false);
     }
 }
+/**
+ * Merged namespace so callers can reach {@link peerPackageVersion} off the same
+ * default import (`importOptionalPeer.peerPackageVersion(...)`). Lives in this
+ * `.cts` file for the same reason the dynamic import does: a `.cts` compiles to
+ * CommonJS in BOTH build passes, so `require` / `require.resolve` are natively
+ * available and `import.meta` is never emitted (which would break the CJS build
+ * and crash CJS consumers, see `resolveEmbeddedVersion` in powdb.ts).
+ */
+(function (importOptionalPeer) {
+    /**
+     * Resolve an optional peer's declared `package.json` version WITHOUT loading
+     * the package itself (so an ESM-only peer never trips `require`). `require` is
+     * anchored on THIS module's location (inside the published `dist/`), so bare
+     * resolution walks up `node_modules` and finds the peer exactly where
+     * `import.meta.url` used to point, but it compiles under `module: CommonJS`
+     * too. Returns `null` when the peer / its package.json cannot be resolved.
+     */
+    function peerPackageVersion(specifier) {
+        try {
+            const pkg = require(`${specifier}/package.json`);
+            return typeof pkg.version === 'string' ? pkg.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    importOptionalPeer.peerPackageVersion = peerPackageVersion;
+})(importOptionalPeer || (importOptionalPeer = {}));
 module.exports = importOptionalPeer;

package/dist/optional-peer-import.d.cts

@@ -50,4 +50,23 @@
  *   `false` so a failure in the sibling copy can never bounce back.
  */
 declare function importOptionalPeer(specifier: string, allowEsmFallback?: boolean): Promise<unknown>;
+/**
+ * Merged namespace so callers can reach {@link peerPackageVersion} off the same
+ * default import (`importOptionalPeer.peerPackageVersion(...)`). Lives in this
+ * `.cts` file for the same reason the dynamic import does: a `.cts` compiles to
+ * CommonJS in BOTH build passes, so `require` / `require.resolve` are natively
+ * available and `import.meta` is never emitted (which would break the CJS build
+ * and crash CJS consumers, see `resolveEmbeddedVersion` in powdb.ts).
+ */
+declare namespace importOptionalPeer {
+    /**
+     * Resolve an optional peer's declared `package.json` version WITHOUT loading
+     * the package itself (so an ESM-only peer never trips `require`). `require` is
+     * anchored on THIS module's location (inside the published `dist/`), so bare
+     * resolution walks up `node_modules` and finds the peer exactly where
+     * `import.meta.url` used to point, but it compiles under `module: CommonJS`
+     * too. Returns `null` when the peer / its package.json cannot be resolved.
+     */
+    function peerPackageVersion(specifier: string): string | null;
+}
 export = importOptionalPeer;

package/dist/powdb-introspect.d.ts

@@ -0,0 +1,84 @@
+/**
+ * turbine-orm/powdb — `describe`-based introspection.
+ *
+ * PowDB exposes its catalog through two ordinary rows-returning statements
+ * (keywords since engine 0.10):
+ *   - `schema` → one row per type: `{ name, columns }` (columns = a count).
+ *   - `describe <T>` / `schema <T>` → one row per column:
+ *     `{ column, type, nullable, index }` where `type` is a PowQL type name
+ *     (`str`/`int`/`float`/`bool`/`json`/`datetime`/`uuid`/`bytes`), `nullable`
+ *     is `"true"`/`"false"`, and `index` is `"unique"` / `"index"` / `""`.
+ *
+ * {@link introspectPowdbDatabase} turns those into the same {@link SchemaMetadata}
+ * shape the SQL introspectors produce, so a code-first PowDB database can be
+ * introspected for bootstrap/verification. It is transport-agnostic: the caller
+ * supplies an `exec(powql)` that returns row objects **keyed by column name**.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.raw([q]) })`
+ *     using a live `turbinePowDB` client's `raw` tagged template.
+ *   - Networked: the raw `@zvndev/powdb-client` returns POSITIONAL rows
+ *     (`{ columns: string[], rows: string[][] }`), so zip them into records.
+ *     A bare `(await client.query(q)).rows` would hand this function `string[][]`
+ *     whose `.name` cell is `undefined` and every table would silently drop out:
+ *     ```ts
+ *     const exec = async (q) => {
+ *       const r = await client.query(q);
+ *       return { rows: r.rows.map((row) => Object.fromEntries(r.columns.map((c, i) => [c, row[i]]))) };
+ *     };
+ *     ```
+ *     (A mis-shaped exec is now caught: if `schema` returns rows but none carry
+ *     a `name`, {@link introspectPowdbDatabase} throws instead of returning an
+ *     empty schema.)
+ *
+ * IMPORTANT LIMITATIONS (all documented, none silent):
+ *   - Relations are ALWAYS `{}`: PowDB has no declared foreign keys, so
+ *     `describe` cannot report them. The recommended flow for relation-aware
+ *     metadata is code-first `defineSchema` + `schemaDefToMetadata`; use
+ *     introspection to bootstrap or verify column shape.
+ *   - Primary key is a HEURISTIC (`describe` has no PK concept): PowDB marks a
+ *     PK column as `required unique`, so the first non-nullable `unique` column
+ *     is chosen (a column named `id` wins ties). A table with no such column
+ *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
+ *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
+ *     modifier, so an introspected int PK is treated as client-supplied unless
+ *     the caller hand-edits the metadata.
+ *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
+ *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
+ *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types
+ *     (`Date` / `string` / `Uint8Array`). Turbine never emits those PowQL types
+ *     on write, so writing to such a column may not round-trip.
+ *
+ * v1 is a PROGRAMMATIC API (exported from `turbine-orm/powdb`); the CLI's
+ * `turbine generate` still defaults to Postgres. Routing a `powdb://` URL
+ * through the CLI would additionally need: a `powdbDialect.introspector`
+ * wired to a networked `exec`, and `cli/config.ts` teaching the generate
+ * funnel to construct a PowDB client instead of a `pg` client for `powdb://`.
+ */
+import { type PowdbCapabilities } from './powdb.js';
+import type { SchemaMetadata } from './schema.js';
+/** A minimal rows-returning executor over a PowDB connection (embedded or networked). */
+export type PowdbExec = (powql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>;
+/** Options controlling which tables {@link introspectPowdbDatabase} reads. */
+export interface PowdbIntrospectOptions {
+    /** Only introspect these table names (snake_case, as PowDB reports them). */
+    include?: string[];
+    /** Skip these table names. */
+    exclude?: string[];
+    /**
+     * Bound connection capabilities. When supplied AND `introspection` (engine
+     * >= 0.10) is false, this throws a version-hinting {@link UnsupportedFeatureError}
+     * (E017) up front instead of letting a pre-0.10 engine reject the `schema` /
+     * `describe` keywords with an opaque parse error. Omit it (the bare-exec path)
+     * to run ungated; the pool paths that know the version pass it through.
+     */
+    capabilities?: PowdbCapabilities;
+}
+/**
+ * Read a live PowDB database into {@link SchemaMetadata} via `schema` +
+ * `describe <T>` statements run through the supplied {@link PowdbExec}.
+ *
+ * @param exec Rows-returning executor (embedded `db.raw` or networked `client.query`).
+ * @param options `include`/`exclude` table filters.
+ */
+export declare function introspectPowdbDatabase(exec: PowdbExec, options?: PowdbIntrospectOptions): Promise<SchemaMetadata>;

package/dist/powdb-introspect.js

@@ -0,0 +1,219 @@
+/**
+ * turbine-orm/powdb — `describe`-based introspection.
+ *
+ * PowDB exposes its catalog through two ordinary rows-returning statements
+ * (keywords since engine 0.10):
+ *   - `schema` → one row per type: `{ name, columns }` (columns = a count).
+ *   - `describe <T>` / `schema <T>` → one row per column:
+ *     `{ column, type, nullable, index }` where `type` is a PowQL type name
+ *     (`str`/`int`/`float`/`bool`/`json`/`datetime`/`uuid`/`bytes`), `nullable`
+ *     is `"true"`/`"false"`, and `index` is `"unique"` / `"index"` / `""`.
+ *
+ * {@link introspectPowdbDatabase} turns those into the same {@link SchemaMetadata}
+ * shape the SQL introspectors produce, so a code-first PowDB database can be
+ * introspected for bootstrap/verification. It is transport-agnostic: the caller
+ * supplies an `exec(powql)` that returns row objects **keyed by column name**.
+ *   - Embedded / owned pool: `exec = async (q) => ({ rows: await db.raw([q]) })`
+ *     using a live `turbinePowDB` client's `raw` tagged template.
+ *   - Networked: the raw `@zvndev/powdb-client` returns POSITIONAL rows
+ *     (`{ columns: string[], rows: string[][] }`), so zip them into records.
+ *     A bare `(await client.query(q)).rows` would hand this function `string[][]`
+ *     whose `.name` cell is `undefined` and every table would silently drop out:
+ *     ```ts
+ *     const exec = async (q) => {
+ *       const r = await client.query(q);
+ *       return { rows: r.rows.map((row) => Object.fromEntries(r.columns.map((c, i) => [c, row[i]]))) };
+ *     };
+ *     ```
+ *     (A mis-shaped exec is now caught: if `schema` returns rows but none carry
+ *     a `name`, {@link introspectPowdbDatabase} throws instead of returning an
+ *     empty schema.)
+ *
+ * IMPORTANT LIMITATIONS (all documented, none silent):
+ *   - Relations are ALWAYS `{}`: PowDB has no declared foreign keys, so
+ *     `describe` cannot report them. The recommended flow for relation-aware
+ *     metadata is code-first `defineSchema` + `schemaDefToMetadata`; use
+ *     introspection to bootstrap or verify column shape.
+ *   - Primary key is a HEURISTIC (`describe` has no PK concept): PowDB marks a
+ *     PK column as `required unique`, so the first non-nullable `unique` column
+ *     is chosen (a column named `id` wins ties). A table with no such column
+ *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
+ *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
+ *     modifier, so an introspected int PK is treated as client-supplied unless
+ *     the caller hand-edits the metadata.
+ *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
+ *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
+ *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types
+ *     (`Date` / `string` / `Uint8Array`). Turbine never emits those PowQL types
+ *     on write, so writing to such a column may not round-trip.
+ *
+ * v1 is a PROGRAMMATIC API (exported from `turbine-orm/powdb`); the CLI's
+ * `turbine generate` still defaults to Postgres. Routing a `powdb://` URL
+ * through the CLI would additionally need: a `powdbDialect.introspector`
+ * wired to a networked `exec`, and `cli/config.ts` teaching the generate
+ * funnel to construct a PowDB client instead of a `pg` client for `powdb://`.
+ */
+import { ValidationError } from './errors.js';
+import { quotePowqlIdent, requireCapability } from './powdb.js';
+import { snakeToCamel } from './schema.js';
+/** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
+function asString(v) {
+    return v === null || v === undefined ? '' : String(v);
+}
+/** Coerce a `describe` `nullable` cell (`"true"`/`"false"` or a native boolean) to a JS boolean. */
+function asBool(v) {
+    return v === true || asString(v).toLowerCase() === 'true';
+}
+/**
+ * Map a PowQL type name to the {@link ColumnMetadata} TS/dialect types. The
+ * `tsType` drives read coercion (`coerceValue`) and write typing
+ * (`powqlColumnType`); `dialectType`/`pgType` carry the PowQL type name so
+ * `isFloatColumn` / `isJsonColumn` classify correctly.
+ */
+function mapPowqlType(powqlType) {
+    switch (powqlType) {
+        case 'int':
+            return { tsType: 'number', dialectType: 'int' };
+        case 'float':
+            return { tsType: 'number', dialectType: 'float' };
+        case 'bool':
+            return { tsType: 'boolean', dialectType: 'bool' };
+        case 'json':
+            return { tsType: 'unknown', dialectType: 'json' };
+        case 'datetime':
+            return { tsType: 'Date', dialectType: 'datetime' };
+        case 'uuid':
+            return { tsType: 'string', dialectType: 'uuid' };
+        case 'bytes':
+            return { tsType: 'Uint8Array', dialectType: 'bytes' };
+        default:
+            // `str` and any unknown future scalar fall back to string.
+            return { tsType: 'string', dialectType: 'str' };
+    }
+}
+/**
+ * Read a live PowDB database into {@link SchemaMetadata} via `schema` +
+ * `describe <T>` statements run through the supplied {@link PowdbExec}.
+ *
+ * @param exec Rows-returning executor (embedded `db.raw` or networked `client.query`).
+ * @param options `include`/`exclude` table filters.
+ */
+export async function introspectPowdbDatabase(exec, options = {}) {
+    // Gate on the engine's introspection capability (>= 0.10) when the caller
+    // knows the version, so a pre-0.10 engine gets a typed E017 hint instead of
+    // an opaque `unexpected token schema` parse error.
+    if (options.capabilities) {
+        requireCapability(options.capabilities, 'introspection', 'PowDB `describe` introspection');
+    }
+    // ----- Types (one row per table, columns `name`, `columns`) -----
+    const schemaRows = (await exec('schema')).rows;
+    let tableNames = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
+    // A mis-shaped `exec` (e.g. the raw client's positional `string[][]` rows
+    // passed straight through) yields rows whose `name` cell is `undefined`, so
+    // every table filters out and the schema comes back silently empty. Refuse
+    // that instead of losing data: real rows must carry a `name`.
+    if (schemaRows.length > 0 && tableNames.length === 0) {
+        throw new ValidationError(`[turbine] PowDB introspection: the \`schema\` statement returned ${schemaRows.length} row(s) but none carried a ` +
+            '`name` cell. The `exec` you supplied likely returns POSITIONAL rows (string[][]) rather than records keyed by ' +
+            'column name; zip `columns` with each row (see introspectPowdbDatabase docs).');
+    }
+    if (options.include?.length) {
+        const inc = new Set(options.include);
+        tableNames = tableNames.filter((t) => inc.has(t));
+    }
+    if (options.exclude?.length) {
+        const exc = new Set(options.exclude);
+        tableNames = tableNames.filter((t) => !exc.has(t));
+    }
+    const tables = {};
+    for (const tableName of tableNames) {
+        // `describe` needs the table name in bare-identifier position → quote it so
+        // a reserved-word / non-bare table name (`order`) does not become a parse
+        // error.
+        const describeRows = (await exec(`describe ${quotePowqlIdent(tableName)}`)).rows.map((r) => ({
+            column: asString(r.column),
+            type: asString(r.type),
+            nullable: asBool(r.nullable),
+            index: asString(r.index),
+        }));
+        const columns = [];
+        const columnMap = {};
+        const reverseColumnMap = {};
+        const dateColumns = new Set();
+        const dialectTypes = {};
+        const pgTypes = {};
+        const allColumns = [];
+        const uniqueColumns = [];
+        const indexes = [];
+        // PK heuristic candidates: non-nullable `unique` columns.
+        const pkCandidates = [];
+        for (const row of describeRows) {
+            const name = row.column;
+            const field = snakeToCamel(name);
+            const { tsType, dialectType } = mapPowqlType(row.type);
+            const nullable = row.nullable;
+            const finalTs = nullable ? `${tsType} | null` : tsType;
+            const col = {
+                name,
+                field,
+                dialectType,
+                pgType: dialectType,
+                tsType: finalTs,
+                nullable,
+                // `describe` reports neither defaults nor the `auto` modifier.
+                hasDefault: false,
+                isGenerated: false,
+                isArray: false,
+                arrayType: undefined,
+                pgArrayType: 'text[]',
+            };
+            columns.push(col);
+            columnMap[field] = name;
+            reverseColumnMap[name] = field;
+            allColumns.push(name);
+            dialectTypes[name] = dialectType;
+            pgTypes[name] = dialectType;
+            if (dialectType === 'datetime')
+                dateColumns.add(name);
+            if (row.index === 'unique') {
+                uniqueColumns.push([name]);
+                if (!nullable)
+                    pkCandidates.push(name);
+            }
+            if (row.index === 'unique' || row.index === 'index') {
+                indexes.push({
+                    name: `${tableName}_${name}_idx`,
+                    columns: [name],
+                    unique: row.index === 'unique',
+                    definition: `${row.index === 'unique' ? 'unique ' : ''}index on ${tableName}(${name})`,
+                });
+            }
+        }
+        // Primary key: first non-nullable unique column, preferring one named `id`.
+        let primaryKey = [];
+        if (pkCandidates.length > 0) {
+            primaryKey = [pkCandidates.includes('id') ? 'id' : pkCandidates[0]];
+        }
+        else {
+            console.warn(`[turbine] PowDB introspection: table "${tableName}" has no non-nullable unique column; ` +
+                'primaryKey is [] (single-row operations will fail). Supply a primary key via code-first ' +
+                '`defineSchema` metadata if this table needs findUnique/update/delete by id.');
+        }
+        tables[tableName] = {
+            name: tableName,
+            columns,
+            columnMap,
+            reverseColumnMap,
+            dateColumns,
+            dialectTypes,
+            pgTypes,
+            allColumns,
+            primaryKey,
+            uniqueColumns,
+            // PowDB has no declared foreign keys → no relations from introspection.
+            relations: {},
+            indexes,
+        };
+    }
+    return { tables, enums: {} };
+}