turbine-orm 0.32.2 → 0.34.0

package/README.md

@@ -863,7 +863,7 @@ const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA)
 ```
 
 ```ts
-// PowDB — async; embedded (in-process) or networked. Schema is code-defined (no introspection).
+// PowDB — async; embedded (in-process) or networked. Schema is code-defined.
 import { turbinePowDB } from 'turbine-orm/powdb';
 import { schema } from './schema.js'; // defineSchema({...})
 
@@ -891,7 +891,7 @@ Everything is honest about what ports and what doesn't. Features marked **PG-onl
 
 **Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
 
-**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` (no wire introspection) — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
+**PowDB** speaks its own non-SQL query language (PowQL), so it sits outside the SQL matrix above. Writes use a trailing **`returning`** keyword (upsert reselects by PK). PKs are server-assigned `auto` ints **or** client UUIDs. Nested relations load client-side (N+1, including many-to-many via the junction — no `json_agg`). Nested writes cover hasMany/hasOne/belongsTo; many-to-many nested writes are not supported. Transactions are single-writer: concurrent `$transaction` calls queue FIFO (bounded by `transactionQueueTimeoutMs`); nested/re-entrant transactions throw typed errors (no savepoints). Schema is code-first via `defineSchema` — `schemaDefToMetadata()` bridges it to any engine that needs runtime metadata, and a programmatic `describe`-based introspector exists since 0.34 (relations excluded). JSON documents are first-class on engine 0.12+: `JsonFilter` where-filters, JSON-path `orderBy`/`groupBy`, doc-field expression indexes, and a lossless native wire (0.13+) that keeps JSON `null`, missing fields, and the string `"null"` distinct. Embedded `syncMode: 'normal'` moves fsync off the commit path; the networked transport runs the same data over a socket. Cursor streaming and the Postgres-only trio (pgvector / LISTEN/NOTIFY / RLS session GUCs) throw `UnsupportedFeatureError`. Full details: **[turbineorm.dev/engines#powdb](https://turbineorm.dev/engines#powdb)**.
 
 Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
 

package/dist/cjs/dialect.js

@@ -58,6 +58,7 @@ exports.postgresDialect = {
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,
+    supportsLateralJoin: true,
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/cjs/index.js

@@ -35,7 +35,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.defineSchema = exports.column = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -110,6 +110,7 @@ Object.defineProperty(exports, "applyManyToManyRelations", { enumerable: true, g
 Object.defineProperty(exports, "ColumnBuilder", { enumerable: true, get: function () { return schema_builder_js_1.ColumnBuilder; } });
 Object.defineProperty(exports, "column", { enumerable: true, get: function () { return schema_builder_js_1.column; } });
 Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
+Object.defineProperty(exports, "isDocFieldIndexDef", { enumerable: true, get: function () { return schema_builder_js_1.isDocFieldIndexDef; } });
 // Legacy compat (deprecated — use object format with defineSchema)
 Object.defineProperty(exports, "table", { enumerable: true, get: function () { return schema_builder_js_1.table; } });
 // Schema metadata bridge — defineSchema() → SchemaMetadata without a live DB

package/dist/cjs/mssql.js

@@ -478,6 +478,9 @@ exports.mssqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // SQL Server has OUTER APPLY, not FROM-clause LATERAL: the lateral pick plan
+    // is Postgres-only (out of scope here).
+    supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.

package/dist/cjs/mysql.js

@@ -379,6 +379,9 @@ exports.mysqlDialect = {
     supportsVector: false,
     supportsListenNotify: false,
     supportsRLS: false,
+    // MySQL 8.0.14+ supports LATERAL, but the opt-in lateral pick plan stays
+    // Postgres-only in this release (flipping it on is a one-line change + tests).
+    supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery

package/dist/cjs/optional-peer-import.cjs

@@ -119,4 +119,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/cjs/powdb-introspect.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * 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://`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectPowdbDatabase = introspectPowdbDatabase;
+const errors_js_1 = require("./errors.js");
+const powdb_js_1 = require("./powdb.js");
+const schema_js_1 = require("./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.
+ */
+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) {
+        (0, powdb_js_1.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 errors_js_1.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 ${(0, powdb_js_1.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 = (0, schema_js_1.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: {} };
+}