turbine-orm 0.29.0 → 0.31.0

package/dist/cjs/mssql.js

@@ -90,39 +90,9 @@
  * await db.disconnect();
  * ```
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mssqlDialect = exports.MssqlPool = void 0;
 exports.mssqlTypeToTs = mssqlTypeToTs;
@@ -132,6 +102,8 @@ exports.turbineMssql = turbineMssql;
 const client_js_1 = require("./client.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
+const introspect_js_1 = require("./introspect.js");
+const optional_peer_import_cjs_1 = __importDefault(require("./optional-peer-import.cjs"));
 const schema_js_1 = require("./schema.js");
 // ---------------------------------------------------------------------------
 // SQL Server / connection limits
@@ -784,11 +756,32 @@ function buildForJsonSubquery(dialect, ctx) {
         if (hasOrder) {
             const orderBy = orderEntries
                 .map(([k, dir]) => {
-                const col = (0, schema_js_1.camelToSnake)(k);
+                // FOR JSON nested ordering supports plain directions and { sort }
+                // specs only. Object shapes the core builder compiles with params
+                // (JSON-path / vector / relation ordering) must throw here: the
+                // shared param-collect mirror is gated on the native path, so a
+                // silently-ignored object would desync SQL text from params.
+                let rawDir = dir;
+                if (typeof dir === 'object' && dir !== null) {
+                    const sortValue = dir.sort;
+                    if (typeof sortValue !== 'string') {
+                        throw new errors_js_1.ValidationError(`[turbine] Nested orderBy on "${k}" (table "${targetTable}"): only plain directions and ` +
+                            `{ sort } specs are supported inside a relation orderBy on SQL Server.`);
+                    }
+                    if (dir.nulls !== undefined) {
+                        throw new errors_js_1.UnsupportedFeatureError('NULLS FIRST/LAST ordering', 'sqlserver', 'Explicit nulls placement in orderBy is only available on PostgreSQL and SQLite.');
+                    }
+                    rawDir = sortValue;
+                }
+                // columnMap-first resolution (camelToSnake fallback): matches the
+                // core builder's nested orderBy path so camelCase-named DB columns
+                // resolve on SQL Server too.
+                const col = targetMeta.columnMap[k] ?? (0, schema_js_1.camelToSnake)(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
+                    throw new errors_js_1.ValidationError(`[turbine] Unknown field "${k}" in orderBy on table "${targetTable}". ` +
+                        `Known fields: ${Object.keys(targetMeta.columnMap).join(', ') || '(none)'}.`);
                 }
-                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(rawDir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${a}.${q(col)} ${safeDir}`;
             })
                 .join(', ');
@@ -894,103 +887,15 @@ function buildForJsonManyToMany(dialect, ctx, h) {
 }
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
 /**
- * Derive belongsTo + hasMany relations (and conservatively-detected manyToMany
- * junctions) from a flat foreign-key list. Mirrors the PostgreSQL / MySQL / SQLite
- * introspectors so the produced {@link SchemaMetadata} has an identical relation
- * shape across engines.
+ * Derive relations from the FK list via the SHARED introspection pipeline
+ * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
+ * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
+ * IDENTICAL relation names to `turbine generate` against Postgres for the
+ * same logical schema — legacy-first naming, per-column disambiguation, and
+ * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
-    const tableSet = new Set(tableNames);
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        if (!tableSet.has(fk.targetTable))
-            continue;
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(fk.sourceColumns[0].replace(/_id$/, ''))
-            : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : (0, schema_js_1.snakeToCamel)(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // Conservative many-to-many auto-detection (additive): a table J is a pure
-    // junction iff PK is exactly two columns, exactly two single-column FKs whose
-    // source columns ARE the PK, two distinct target tables, and no payload columns.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = (0, schema_js_1.snakeToCamel)(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
-    return relationsByTable;
+    return (0, introspect_js_1.deriveEngineRelations)(tableNames, foreignKeys, pkByTable, columnsByTable);
 }
 /**
  * Introspect a SQL Server database into the same {@link SchemaMetadata} shape the
@@ -1237,11 +1142,12 @@ async function loadMssql() {
     let mod;
     try {
         // `mssql` ships no bundled type declarations (it needs @types/mssql, which
-        // Turbine deliberately does not depend on) — the structural MssqlModule above
-        // is our typed surface. Import through a widened specifier so tsc treats the
-        // typeless module as `any` instead of erroring (TS7016).
-        const specifier = 'mssql';
-        mod = (await Promise.resolve(`${specifier}`).then(s => __importStar(require(s))));
+        // Turbine deliberately does not depend on) — the structural MssqlModule
+        // above is our typed surface; the helper returns `unknown` so no TS7016.
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() even if a future mssql major goes ESM-only (the CommonJS pass
+        // transpiles a plain `import()` here into `require()`).
+        mod = (await (0, optional_peer_import_cjs_1.default)('mssql'));
     }
     catch (err) {
         throw new errors_js_1.ConnectionError("[turbine] turbine-orm/mssql requires the optional peer dependency 'mssql'. Install it: npm i mssql. " +

package/dist/cjs/mysql.js

@@ -63,39 +63,9 @@
  * await db.disconnect();
  * ```
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mysqlDialect = exports.MysqlPool = void 0;
 exports.mysqlTypeToTs = mysqlTypeToTs;
@@ -105,6 +75,8 @@ exports.turbineMysql = turbineMysql;
 const client_js_1 = require("./client.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
+const introspect_js_1 = require("./introspect.js");
+const optional_peer_import_cjs_1 = __importDefault(require("./optional-peer-import.cjs"));
 const schema_js_1 = require("./schema.js");
 // ---------------------------------------------------------------------------
 // Value coercion (params in)
@@ -596,103 +568,15 @@ exports.mysqlDialect = {
 };
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
 /**
- * Derive belongsTo + hasMany relations (and conservatively-detected manyToMany
- * junctions) from a flat foreign-key list. Mirrors the PostgreSQL / SQLite
- * introspectors so the produced {@link SchemaMetadata} has an identical relation
- * shape across engines.
+ * Derive relations from the FK list via the SHARED introspection pipeline
+ * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
+ * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
+ * IDENTICAL relation names to `turbine generate` against Postgres for the
+ * same logical schema — legacy-first naming, per-column disambiguation, and
+ * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
-    const tableSet = new Set(tableNames);
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        if (!tableSet.has(fk.targetTable))
-            continue;
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(fk.sourceColumns[0].replace(/_id$/, ''))
-            : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : (0, schema_js_1.snakeToCamel)(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // Conservative many-to-many auto-detection (additive): a table J is a pure
-    // junction iff PK is exactly two columns, exactly two single-column FKs whose
-    // source columns ARE the PK, two distinct target tables, and no payload columns.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = (0, schema_js_1.snakeToCamel)(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
-    return relationsByTable;
+    return (0, introspect_js_1.deriveEngineRelations)(tableNames, foreignKeys, pkByTable, columnsByTable);
 }
 /**
  * Introspect a MySQL database into the same {@link SchemaMetadata} shape the
@@ -939,7 +823,10 @@ function parseMysqlConfig(connectionString) {
 async function loadCreatePool() {
     let mod;
     try {
-        mod = (await Promise.resolve().then(() => __importStar(require('mysql2/promise'))));
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() even if a future mysql2 major goes ESM-only (the CommonJS pass
+        // transpiles a plain `import()` here into `require()`).
+        mod = (await (0, optional_peer_import_cjs_1.default)('mysql2/promise'));
     }
     catch (err) {
         throw new errors_js_1.ConnectionError("[turbine] turbine-orm/mysql requires the optional peer dependency 'mysql2'. Install it: npm i mysql2. " +

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

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * True dynamic `import()` for the optional peer dependencies (`mysql2`,
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * build outputs, including for peers that are ESM-only.
+ *
+ * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
+ * the engine subpaths load their optional peers with dynamic `import()` so the
+ * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
+ * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
+ * module CommonJS) however TRANSPILES `import()` into
+ * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
+ * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
+ *
+ * TypeScript offers no way to preserve `import()` under `module: CommonJS`,
+ * and the CJS pass cannot switch to `module: NodeNext` (the root package.json
+ * says `"type": "module"`, so NodeNext would classify every `.ts` source as
+ * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
+ * CommonJS-format by extension regardless of package `type`, so under the ESM
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
+ * import in CJS files precisely because it is the only way CJS can load ESM).
+ *
+ * That gives the published package two copies of this module:
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *
+ * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
+ * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
+ * recognizable code and this function falls back to delegating the load to the
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * which is a plain CommonJS file (loadable by `require()` on every supported
+ * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
+ * no such sibling; its lazy `require` throws and the original error surfaces,
+ * so the fallback can never recurse.
+ *
+ * Keep this module dependency-free and side-effect-free: it must be loadable
+ * from both module systems on every supported Node (≥ 20) without pulling in
+ * anything else.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+/**
+ * Does this error mean "the module exists but cannot be loaded via
+ * `require()` because it is ESM-only"? These are the only failures worth
+ * retrying through a real `import()`; anything else (not installed, throw on
+ * init, …) is rethrown untouched so callers keep the original diagnostics.
+ */
+function isEsmOnlyLoadError(err) {
+    const code = err?.code;
+    return (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' || // exports map has no `require` condition
+        code === 'ERR_REQUIRE_ESM' || // require() of an ES module (pre-require(esm) Node)
+        code === 'ERR_REQUIRE_ASYNC_MODULE' // require(esm) of a module with top-level await
+    );
+}
+/**
+ * Dynamically import an optional peer dependency. In the ESM build this is a
+ * plain `import()`. In the CJS build the first attempt is a transpiled
+ * `require()`; if the peer turns out to be ESM-only, the load is retried
+ * through the ESM-build sibling copy of this file, whose `import()` survived
+ * transpilation (see the module doc comment).
+ *
+ * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
+ * @param allowEsmFallback internal recursion guard — the delegated call passes
+ *   `false` so a failure in the sibling copy can never bounce back.
+ */
+async function importOptionalPeer(specifier, allowEsmFallback = true) {
+    try {
+        return await Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+    }
+    catch (err) {
+        if (!allowEsmFallback || !isEsmOnlyLoadError(err))
+            throw err;
+        let esmCapableCopy;
+        try {
+            // Only resolvable from dist/cjs/, where it lands on the NodeNext-built
+            // dist/optional-peer-import.cjs. From anywhere else (the ESM copy
+            // itself, or running the TypeScript source directly) the file does not
+            // exist and the original error is rethrown below.
+            esmCapableCopy = require('../optional-peer-import.cjs');
+        }
+        catch {
+            esmCapableCopy = undefined;
+        }
+        if (typeof esmCapableCopy !== 'function')
+            throw err;
+        return esmCapableCopy(specifier, false);
+    }
+}
+module.exports = importOptionalPeer;