turbine-orm 0.47.0 → 0.48.0

package/dist/cjs/powdb-introspect.js

@@ -128,7 +128,16 @@ async function introspectPowdbDatabase(exec, options = {}) {
         // `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) => ({
+        const describeRows = (await exec(`describe ${(0, powdb_js_1.quotePowqlIdent)(tableName)}`)).rows
+            // PowDB >= 0.19.1 appends entity-LINK rows after the 4 column rows in
+            // `describe <T>` (a `type` cell of literally `"link"`, an Empty nullable
+            // slot, and an arrow description in the index slot). They are NOT columns,
+            // so drop them before column parsing, unconditionally (no capability check):
+            // the rows simply never appear on a pre-0.19.1 engine, and a linked database
+            // introspected without this filter would produce garbage `link`-typed
+            // columns. Declared links are read separately via `schema links` below.
+            .filter((r) => asString(r.type) !== 'link')
+            .map((r) => ({
             column: asString(r.column),
             type: asString(r.type),
             nullable: asBool(r.nullable),
@@ -208,10 +217,120 @@ async function introspectPowdbDatabase(exec, options = {}) {
             allColumns,
             primaryKey,
             uniqueColumns,
-            // PowDB has no declared foreign keys → no relations from introspection.
+            // Populated below from `schema links` when the engine supports link
+            // introspection (>= 0.19.1); stays `{}` otherwise (PowDB has no declared
+            // foreign keys, so pre-link introspection reports no relations).
             relations: {},
             indexes,
         };
     }
+    // Link introspection (>= 0.19.1): populate relations from declared entity links.
+    // Behaves exactly as before (relations stay `{}`) when the capability is absent
+    // or not supplied.
+    if (options.capabilities?.linkIntrospection) {
+        await introspectPowdbLinks(exec, tables);
+    }
     return { tables, enums: {} };
 }
+/**
+ * Read `schema links` and populate {@link TableMetadata.relations}: the first
+ * time PowDB introspection can report relations. Each declared link becomes a
+ * relation on its OWNER, and its natural REVERSE is synthesized on the target
+ * (mirroring the SQL introspector, which always emits both sides of a FK):
+ *
+ *   - `"to-one"`  link `Order.user -> User`: owner gets a `belongsTo` (localKey =
+ *     the FK on the owner, targetKey = the referenced key on target); the target
+ *     gets a reverse `hasMany` named for the pluralized owner table.
+ *   - `"to-many"` link `User.orders -> Order`: owner gets a `hasMany` (localKey =
+ *     the referenced key on the owner, targetKey = the FK on the child); the
+ *     target gets a reverse `belongsTo` named for the singularized owner table.
+ *
+ * Reverse synthesis is best-effort and collision-guarded: a synthesized name that
+ * would shadow a column field or an already-present relation on the target is
+ * skipped (never a hard error), so introspection can only ADD relations, never
+ * clobber. m2m junctions cannot be inferred from links and stay undetected;
+ * `defineSchema` remains the relation-complete path. Column names arrive as
+ * PowDB's emitted (snake) names and stay snake in `foreignKey`/`referenceKey`
+ * (the SQL introspector's convention); the relation NAME is camelCased to match
+ * the query field surface. Naming edge: `schema links` is the contextual listing
+ * keyword: a table literally named `links` is still read via `describe links`.
+ */
+async function introspectPowdbLinks(exec, tables) {
+    const linkRows = (await exec('schema links')).rows.map((r) => ({
+        owner: asString(r.owner),
+        name: asString(r.name),
+        target: asString(r.target),
+        localKey: asString(r.local_key),
+        targetKey: asString(r.target_key),
+        cardinality: asString(r.cardinality),
+    }));
+    for (const link of linkRows) {
+        const owner = tables[link.owner];
+        const target = tables[link.target];
+        // A link referencing a filtered-out (include/exclude) table is skipped: we
+        // cannot describe the target, so the relation would be unusable.
+        if (!owner || !target)
+            continue;
+        const toOne = link.cardinality === 'to-one';
+        const relName = (0, schema_js_1.snakeToCamel)(link.name);
+        // Forward relation on the owner (the declared direction).
+        if (toOne) {
+            addRelation(owner, {
+                type: 'belongsTo',
+                name: relName,
+                from: link.owner,
+                to: link.target,
+                foreignKey: link.localKey,
+                referenceKey: link.targetKey,
+            });
+        }
+        else {
+            addRelation(owner, {
+                type: 'hasMany',
+                name: relName,
+                from: link.owner,
+                to: link.target,
+                foreignKey: link.targetKey, // FK on the child (target) side
+                referenceKey: link.localKey, // referenced key on the owner (parent) side
+            });
+        }
+        // Reverse relation on the target (synthesized, collision-guarded).
+        const reverseName = toOne ? pluralize((0, schema_js_1.snakeToCamel)(link.owner)) : (0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(link.owner));
+        if (!relationNameTaken(target, reverseName)) {
+            addRelation(target, {
+                type: toOne ? 'hasMany' : 'belongsTo',
+                name: reverseName,
+                from: link.target,
+                to: link.owner,
+                // Same two columns, roles swapped for the opposite direction.
+                foreignKey: toOne ? link.localKey : link.targetKey,
+                referenceKey: toOne ? link.targetKey : link.localKey,
+            });
+        }
+    }
+}
+/** True when `name` already names a relation OR a column field/name on `meta`. */
+function relationNameTaken(meta, name) {
+    if (meta.relations[name])
+        return true;
+    return meta.columns.some((c) => c.field === name || c.name === name);
+}
+/** Add a relation to a table's relations map (keyed by its camelCase name). */
+function addRelation(meta, rel) {
+    if (meta.relations[rel.name])
+        return; // never clobber an existing relation
+    meta.relations[rel.name] = rel;
+}
+/**
+ * Minimal English pluralizer for reverse-relation names (`user` → `users`,
+ * `company` → `companies`, `box` → `boxes`). Only ever produces a candidate name
+ * that {@link relationNameTaken} then vets, so an imperfect plural can at worst be
+ * skipped, never break a query.
+ */
+function pluralize(word) {
+    if (/[^aeiou]y$/i.test(word))
+        return `${word.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/i.test(word))
+        return `${word}es`;
+    return `${word}s`;
+}

package/dist/cjs/powdb.js

@@ -98,7 +98,10 @@ exports.requireCapability = requireCapability;
 exports.isJsonColumn = isJsonColumn;
 exports.powqlColumnType = powqlColumnType;
 exports.quotePowqlIdent = quotePowqlIdent;
+exports.deriveDesiredLinks = deriveDesiredLinks;
+exports.powdbLinkStatement = powdbLinkStatement;
 exports.powqlSchemaDDL = powqlSchemaDDL;
+exports.applyPowdbLinks = applyPowdbLinks;
 exports.coerceValue = coerceValue;
 exports.coerceNativeValue = coerceNativeValue;
 exports.rowToEntity = rowToEntity;
@@ -112,6 +115,8 @@ const client_js_1 = require("./client.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const optional_peer_import_cjs_1 = __importDefault(require("./optional-peer-import.cjs"));
+const warn_registry_js_1 = require("./query/warn-registry.js");
+const schema_js_1 = require("./schema.js");
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
  * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
@@ -247,7 +252,14 @@ function assertSupportedPowdbVersion(version) {
     throw new errors_js_1.ConnectionError(`[turbine] turbine-orm/powdb requires PowDB >= ${exports.MIN_POWDB_VERSION}; the server reports "${version}". ` +
         'Upgrade the PowDB server (0.7.0 added the `returning` keyword and the int->float coercion fix Turbine relies on).');
 }
-/** Minimum engine version each gated feature needs, for the E017 hint text. */
+/**
+ * Minimum engine version each gated feature needs, for the E017 hint text.
+ * Most gates carry a `major.minor` floor (patch-insensitive); the two link
+ * lanes carry a `major.minor.patch` floor (`0.19.1`) because the listing
+ * statement and the safe traversal semantics landed in the PATCH release, not
+ * in 0.19.0. {@link atLeastVersion} compares all three components, so a
+ * `major.minor` floor still matches every patch of that minor.
+ */
 const POWDB_FEATURE_MIN_VERSION = {
     introspection: '0.10',
     jsonDocs: '0.12',
@@ -255,6 +267,8 @@ const POWDB_FEATURE_MIN_VERSION = {
     serverJoins: '0.13',
     nestedProjections: '0.18',
     entityLinks: '0.19',
+    linkIntrospection: '0.19.1',
+    linkPaths: '0.19.1',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -268,6 +282,11 @@ const POWDB_FEATURE_MIN_VERSION = {
  * `entityLinks` stays OFF for a stronger reason still: declaring a link
  * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
  * so it must only ever light up behind a real version probe.
+ * `linkIntrospection` / `linkPaths` stay OFF for the same probe-only discipline:
+ * `linkPaths` flips real query generation (a to-one `with` compiling to link
+ * projections), and `linkIntrospection` is only meaningful once genuinely
+ * probed, so both must come from a real version resolution, never a bare
+ * construction.
  */
 exports.ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -277,6 +296,8 @@ exports.ALL_POWDB_CAPABILITIES = {
     serverJoins: true,
     nestedProjections: false,
     entityLinks: false,
+    linkIntrospection: false,
+    linkPaths: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -286,9 +307,20 @@ function parsePowdbSemver(version) {
         return null;
     return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0) };
 }
-/** Is `sem` at least `major.minor`? */
-function atLeastVersion(sem, major, minor) {
-    return sem.major > major || (sem.major === major && sem.minor >= minor);
+/**
+ * Is `sem` at least `major.minor.patch`? PATCH-AWARE: `patch` defaults to `0`,
+ * so a two-component floor (`atLeastVersion(sem, 0, 19)`) behaves exactly as the
+ * old major/minor comparison did (matches every patch of 0.19), while a
+ * three-component floor (`atLeastVersion(sem, 0, 19, 1)`) additionally requires
+ * the patch, the distinction the link lanes need (0.19.1, never 0.19.0). Every
+ * existing two-argument call keeps its prior semantics unchanged.
+ */
+function atLeastVersion(sem, major, minor, patch = 0) {
+    if (sem.major !== major)
+        return sem.major > major;
+    if (sem.minor !== minor)
+        return sem.minor > minor;
+    return sem.patch >= patch;
 }
 /**
  * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
@@ -307,6 +339,8 @@ function capabilitiesFromVersion(version, opts = {}) {
             serverJoins: false,
             nestedProjections: false,
             entityLinks: false,
+            linkIntrospection: false,
+            linkPaths: false,
             nativeRaw: false,
         };
     }
@@ -318,6 +352,11 @@ function capabilitiesFromVersion(version, opts = {}) {
         serverJoins: atLeastVersion(sem, 0, 13),
         nestedProjections: atLeastVersion(sem, 0, 18),
         entityLinks: atLeastVersion(sem, 0, 19),
+        // PATCH-floored at 0.19.1: the `schema links` listing + `describe` link rows
+        // and the safe (hard-erroring) scalar-path traversal both landed in 0.19.1,
+        // never 0.19.0.
+        linkIntrospection: atLeastVersion(sem, 0, 19, 1),
+        linkPaths: atLeastVersion(sem, 0, 19, 1),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -526,6 +565,48 @@ function quotePowqlIdent(name) {
     }
     return exports.POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
 }
+/**
+ * Derive the entity links Turbine would declare from a schema's relations. One
+ * link per single-column hasMany / hasOne / belongsTo relation, owned by the
+ * relation's `from` table:
+ *   - belongsTo Order->User: `Order.user -> User on user_id = id`
+ *     (localKey = the FK on the owner, targetKey = the referenced key on target).
+ *   - hasMany  User->Order: `User.orders -> Order on id = user_id`
+ *     (localKey = the referenced key on the owner, targetKey = the FK on the child).
+ * Composite-key relations and m2m junctions are skipped (links are single-column;
+ * a junction cannot be inferred from links). A relation whose name collides with
+ * a column on the owner is skipped and reported through `onCollision` (the caller
+ * decides whether to warn). Pure: no capability gate, no side effects.
+ */
+function deriveDesiredLinks(schema, onCollision) {
+    const links = [];
+    for (const meta of Object.values(schema.tables)) {
+        for (const rel of Object.values(meta.relations)) {
+            if (rel.type === 'manyToMany')
+                continue;
+            const fk = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+            const rk = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+            if (fk.length !== 1 || rk.length !== 1)
+                continue; // links are single-column
+            // A link name that collides with a column on the owner is a hard engine
+            // error at declare time, so skip it (and let the caller warn).
+            const collides = meta.columns.some((c) => c.name === rel.name || c.field === rel.name);
+            if (collides) {
+                onCollision?.(meta.name, rel.name);
+                continue;
+            }
+            const localKey = rel.type === 'belongsTo' ? fk[0] : rk[0];
+            const targetKey = rel.type === 'belongsTo' ? rk[0] : fk[0];
+            links.push({ owner: meta.name, name: rel.name, target: rel.to, localKey, targetKey });
+        }
+    }
+    return links;
+}
+/** Render one {@link PowdbDesiredLink} as its create-only `link ...` DDL statement. */
+function powdbLinkStatement(link) {
+    return (`link ${quotePowqlIdent(link.owner)}.${quotePowqlIdent(link.name)} -> ` +
+        `${quotePowqlIdent(link.target)} on ${quotePowqlIdent(link.localKey)} = ${quotePowqlIdent(link.targetKey)}`);
+}
 function powqlSchemaDDL(schema, opts = {}) {
     const caps = opts.capabilities;
     const stmts = [];
@@ -606,8 +687,94 @@ function powqlSchemaDDL(schema, opts = {}) {
             }
         }
     }
+    // Entity-link DDL (opt-in). Appended after every type so the referenced types
+    // already exist when the links declare. Gated behind the entityLinks capability
+    // when a caller supplied one (an old engine has no `link` statement).
+    if (opts.emitLinks) {
+        if (caps)
+            requireCapability(caps, 'entityLinks', 'entity link DDL (`emitLinks`)');
+        const links = deriveDesiredLinks(schema, (owner, name) => {
+            if ((0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
+                console.warn(`[turbine] powqlSchemaDDL(emitLinks): relation "${name}" on "${owner}" collides with a column of the ` +
+                    'same name; skipping its link declaration (PowDB hard-errors on a link that shadows a column).');
+            }
+        });
+        for (const link of links)
+            stmts.push(powdbLinkStatement(link));
+    }
     return stmts;
 }
+/**
+ * Existence-checked apply of entity-link DDL against a LIVE PowDB database.
+ * Because link DDL is create-only (no `if not exists`, redeclaring is an error,
+ * and there is no drop spelling), an apply layer must diff against the live
+ * catalog first: this reads the `schema links` listing, then executes only the
+ * links that are genuinely missing.
+ *
+ *   - a desired link already declared with the SAME endpoints  → skipped (idempotent);
+ *   - a link declared with the same owner + name but DIFFERENT endpoints → skipped
+ *     with a one-time warning (never dropped/replaced: there is no drop DDL, and a
+ *     silent replace would be a destructive schema change);
+ *   - a name/column collision on the owner → skipped (deriveDesiredLinks warns).
+ *
+ * Requires the `entityLinks` + `linkIntrospection` capabilities when `capabilities`
+ * is supplied (the listing statement is 0.19.1+). Returns the statements executed.
+ * `exec` runs one PowQL statement (embedded `db.raw` / a networked query shim); it
+ * must return rows keyed by column name for the `schema links` read.
+ */
+async function applyPowdbLinks(exec, schema, options = {}) {
+    const caps = options.capabilities;
+    if (caps) {
+        requireCapability(caps, 'entityLinks', 'entity link DDL (`applyPowdbLinks`)');
+        requireCapability(caps, 'linkIntrospection', 'PowDB `schema links` introspection');
+    }
+    const existing = await listPowdbLinks(exec);
+    const byOwnerName = new Map(existing.map((l) => [`${l.owner}${l.name}`, l]));
+    const desired = deriveDesiredLinks(schema, (owner, name) => {
+        if ((0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
+            console.warn(`[turbine] applyPowdbLinks: relation "${name}" on "${owner}" collides with a column of the same name; ` +
+                'skipping its link (PowDB hard-errors on a link that shadows a column).');
+        }
+    });
+    const executed = [];
+    for (const link of desired) {
+        const found = byOwnerName.get(`${link.owner}${link.name}`);
+        if (found) {
+            const same = found.target === link.target && found.localKey === link.localKey && found.targetKey === link.targetKey;
+            if (!same && (0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.powdbLinks, `drift:${link.owner}.${link.name}`)) {
+                console.warn(`[turbine] applyPowdbLinks: link "${link.name}" on "${link.owner}" is already declared with different ` +
+                    `endpoints (have ${found.target} on ${found.localKey} = ${found.targetKey}, want ${link.target} on ` +
+                    `${link.localKey} = ${link.targetKey}); leaving it untouched (PowDB has no drop-link DDL).`);
+            }
+            continue; // identical → idempotent skip; drift → warned skip
+        }
+        const stmt = powdbLinkStatement(link);
+        await exec(stmt);
+        executed.push(stmt);
+    }
+    return executed;
+}
+/**
+ * Read the live `schema links` listing into {@link PowdbDesiredLink} rows (owner,
+ * name, target, localKey, targetKey; cardinality is dropped — it is derived, not
+ * a DDL input). An empty catalog returns `[]`, never an error. Naming edge: a
+ * table literally named `links` is described with `describe links`, but the
+ * link LISTING is the contextual keyword form `schema links`.
+ */
+async function listPowdbLinks(exec) {
+    const { rows } = await exec('schema links');
+    return rows.map((r) => ({
+        owner: powdbCell(r.owner),
+        name: powdbCell(r.name),
+        target: powdbCell(r.target),
+        localKey: powdbCell(r.local_key),
+        targetKey: powdbCell(r.target_key),
+    }));
+}
+/** Coerce a wire cell (string on the legacy wire, typed on the native wire) to string. */
+function powdbCell(v) {
+    return v === null || v === undefined ? '' : String(v);
+}
 /** Coerce a JS value into a PowDB positional param (the write side). */
 function toPowdbParam(value, col) {
     if (value instanceof PowdbFloatParam)
@@ -847,6 +1014,18 @@ function wrapPowdbError(err) {
     if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
         return new errors_js_1.ValidationError(`[turbine] PowDB join rejected: ${msg}`);
     }
+    // Entity-link misuse hard errors (0.19.1 turned the two silent-wrong-results
+    // 0.19.0 behaviors into hard errors) → ValidationError (E003), a query defect
+    // to fix. Matched explicitly on the pinned message text so both transports
+    // classify identically regardless of how the wire wraps them (embedded tags
+    // every error `GenericFailure`; networked carries a wire class): a bare dotted
+    // projection path that was not alias-qualified, and an aggregate over a nested
+    // or link projection. Turbine's own generator never emits either shape (it
+    // always aliases and never aggregates over a link), so these fire only for a
+    // raw user PowQL string; mapping them keeps that path typed.
+    if (/is ambiguous in a projection|aggregates over a nested or link projection/i.test(msg)) {
+        return new errors_js_1.ValidationError(`[turbine] PowDB query rejected: ${msg}`);
+    }
     // Typed wire error class (networked, server >= 0.17): the client surfaces the
     // stable one-byte class from the error frame as `.wireErrorClass`. Classify by
     // it BEFORE the generic message regexes: the server sanitizes non-allowlisted
@@ -1518,7 +1697,11 @@ function encodePowqlLiteral(value) {
  * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
  * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
  * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
- * unmoved.
+ * unmoved. The 0.19.1 link-introspection / link-path round is likewise lexer-neutral:
+ * `git diff v0.19.0 v0.19.1 -- crates/query/src/lexer.rs` is empty (the bare-dotted-path
+ * hard error is parser-level, not tokenization), so this ceiling stays `'0.19'`. The
+ * guard in {@link PowdbEmbeddedPool.exec} compares major.minor only, so `'0.19'`
+ * already covers every 0.19.x patch — no bump is needed for 0.19.1.
  */
 exports.POWQL_LEXER_TESTED_CEILING = '0.19';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */