@dbsp/core 1.0.4 → 1.1.0

package/dist/index.js

@@ -2601,7 +2601,8 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
     return;
   }
   const includePath = `${sourceTable}.${relation.name}`;
-  if (state.visitedIncludes.has(includePath)) {
+  const isSelfReferentialRelation = relation.source === relation.target;
+  if (!isSelfReferentialRelation && state.visitedIncludes.has(includePath)) {
     state.warnings.push({
       code: "CIRCULAR_INCLUDE",
       message: `Circular include detected: ${includePath}`,
@@ -2609,12 +2610,12 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
     });
     return;
   }
-  state.visitedIncludes.add(includePath);
+  if (!isSelfReferentialRelation) state.visitedIncludes.add(includePath);
   const relationPath = `${sourceTable}.${relation.name}`;
   const paths = state.relationAccessCounts.get(relationPath) ?? [];
   paths.push(intentPath);
   state.relationAccessCounts.set(relationPath, paths);
-  const isRecursiveInclude = (!!include.recursive || !!relation.recursive) && relation.source === relation.target;
+  const isRecursiveInclude = (!!include.recursive || !!relation.recursive) && isSelfReferentialRelation;
   let includeStrategy;
   if (isRecursiveInclude) {
     if (opts.dialectCapabilities?.supportsRecursiveCTE === false) {
@@ -2749,7 +2750,7 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
       }
     }
   }
-  state.visitedIncludes.delete(includePath);
+  if (!isSelfReferentialRelation) state.visitedIncludes.delete(includePath);
 }
 function disambiguateRelation(relationName, sourceTable, model, state, opts, _intentPath, viaHint) {
   const directRelation = model.getRelation(`${sourceTable}.${relationName}`);
@@ -4105,6 +4106,12 @@ function coalesce(fields, as) {
   };
 }
 function raw(sqlFragment, as) {
+  if (typeof as !== "string" || as.trim().length === 0) {
+    throw new InvalidOperationError(
+      "raw",
+      "raw() requires an alias as second argument, e.g. raw('COUNT(*)', 'count')"
+    );
+  }
   validateIdentifier(as, "column");
   return {
     __expr: true,
@@ -6126,53 +6133,131 @@ function negotiateFeatures(model, capabilities, behavior = "warning", checkers =
 }
 
 // src/dx/nql.ts
-import { compile as nqlCompile } from "@dbsp/nql";
-function toNqlLiteral(value, index) {
-  if (value === null) {
-    return "null";
+import {
+  NqlLexer,
+  compile as nqlCompile
+} from "@dbsp/nql";
+import { NQL_INTERNAL_COMPILER_OPTIONS } from "@dbsp/types/internal";
+var NQL_RAW_FRAGMENT = /* @__PURE__ */ Symbol("NqlRawFragment");
+function nqlRaw(fragment) {
+  if (typeof fragment !== "string") {
+    throw new TypeError("nqlRaw() expects a string fragment");
+  }
+  const raw2 = { fragment };
+  Object.defineProperty(raw2, NQL_RAW_FRAGMENT, {
+    value: true,
+    enumerable: false
+  });
+  return Object.freeze(raw2);
+}
+function isNqlRawFragment(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
   }
-  switch (typeof value) {
-    case "boolean":
-      return value ? "true" : "false";
-    case "number": {
-      if (!Number.isFinite(value)) {
-        throw new Error(
-          `nql\`...\`: cannot interpolate non-finite number (${value}) at position ${index}. Only finite numbers are supported. For dynamic NQL structure use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      const s = value < 0 ? `-${Math.abs(value)}` : String(value);
-      if (/[eE]/.test(s)) {
-        throw new Error(
-          `nql\`...\`: number ${value} at position ${index} has no exact NQL numeric literal form (exponential notation). Convert it yourself or use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      return s;
+  if (!Object.hasOwn(value, NQL_RAW_FRAGMENT)) {
+    return false;
+  }
+  return value[NQL_RAW_FRAGMENT] === true;
+}
+function isInsideGeneratedRange(start, end, generatedRanges) {
+  return generatedRanges.some(
+    (range) => start >= range.start && end <= range.end
+  );
+}
+function findOverlappingGeneratedRange(start, end, generatedRanges) {
+  return generatedRanges.find(
+    (range) => start < range.end && end > range.start
+  );
+}
+function findExactGeneratedRange(name, start, end, generatedRanges) {
+  return generatedRanges.find(
+    (range) => range.name === name && range.start === start && range.end === end
+  );
+}
+function generatedParamLexError(name) {
+  return `Generated NQL parameter :${name} was not recognized as exactly one NamedParam token after raw-fragment assembly; check adjacent nqlRaw() fragments for quotes, comments, or identifier text that can swallow the placeholder.`;
+}
+function findInternalParamSourceError(query, generatedRanges) {
+  const lexResult = NqlLexer.tokenize(query);
+  const generatedTokenCounts = new Map(
+    generatedRanges.map((range) => [range.name, 0])
+  );
+  for (const token of lexResult.tokens) {
+    if (token.tokenType.name !== "NamedParam") {
+      continue;
     }
-    case "string": {
-      if (value.includes("\n") || value.includes("\r")) {
-        throw new Error(
-          `nql\`...\`: cannot interpolate a string containing a newline at position ${index}. NQL string literals do not support raw newline characters. For dynamic NQL structure use the builder API (orm.select()). See issue #134.`
-        );
-      }
-      const escaped = value.replaceAll("'", "''");
-      return `'${escaped}'`;
+    const name = token.image.slice(1);
+    if (!name.startsWith("__p")) {
+      continue;
     }
-    default: {
-      const typeName = value === void 0 ? "undefined" : typeof value;
-      throw new Error(
-        `nql\`...\`: cannot interpolate value of type "${typeName}" at position ${index}. Only string, number, boolean, and null are supported; for dynamic NQL fragments use the builder API (orm.select()). See issue #134.`
+    const start = token.startOffset;
+    const end = (token.endOffset ?? start + token.image.length - 1) + 1;
+    const exactGeneratedRange = findExactGeneratedRange(
+      name,
+      start,
+      end,
+      generatedRanges
+    );
+    if (exactGeneratedRange) {
+      generatedTokenCounts.set(
+        exactGeneratedRange.name,
+        (generatedTokenCounts.get(exactGeneratedRange.name) ?? 0) + 1
       );
+      continue;
+    }
+    const overlappingGeneratedRange = findOverlappingGeneratedRange(
+      start,
+      end,
+      generatedRanges
+    );
+    if (overlappingGeneratedRange) {
+      return generatedParamLexError(overlappingGeneratedRange.name);
     }
+    if (!isInsideGeneratedRange(start, end, generatedRanges)) {
+      return `Reserved NQL parameter namespace "__p" cannot be referenced by user source (${token.image}).`;
+    }
+  }
+  for (const range of generatedRanges) {
+    if (generatedTokenCounts.get(range.name) !== 1) {
+      return generatedParamLexError(range.name);
+    }
+  }
+  return void 0;
+}
+function assembleNqlTemplate(strings, values) {
+  const params = /* @__PURE__ */ Object.create(null);
+  const generatedRanges = [];
+  let query = strings[0] ?? "";
+  let boundIndex = 0;
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (isNqlRawFragment(value)) {
+      query += value.fragment;
+    } else {
+      const name = `__p${boundIndex++}`;
+      const placeholder = `:${name}`;
+      const start = query.length;
+      query += placeholder;
+      generatedRanges.push({ name, start, end: start + placeholder.length });
+      params[name] = value;
+    }
+    query += strings[i + 1] ?? "";
   }
+  return {
+    query,
+    params,
+    hasBoundParams: boundIndex > 0,
+    sourceError: findInternalParamSourceError(query, generatedRanges)
+  };
 }
 function createNqlTag(schemaDefinition, model, adapter, schemaName) {
   return function nql(strings, ...values) {
-    let query = strings[0] ?? "";
-    for (let i = 0; i < values.length; i++) {
-      query += toNqlLiteral(values[i], i) + (strings[i + 1] ?? "");
-    }
+    const assembled = assembleNqlTemplate(strings, values);
     return new NqlBuilderImpl(
-      query,
+      assembled.query,
+      assembled.params,
+      assembled.hasBoundParams,
+      assembled.sourceError,
       schemaDefinition,
       model,
       adapter,
@@ -6183,13 +6268,19 @@ function createNqlTag(schemaDefinition, model, adapter, schemaName) {
 var NqlBuilderImpl = class {
   _intent;
   query;
+  params;
+  hasBoundParams;
+  sourceError;
   schemaDefinition;
   model;
   // biome-ignore lint/correctness/noUnusedPrivateClassMembers: Reserved for future schema-scoping support
   _schemaName;
   adapter;
-  constructor(query, schemaDefinition, model, adapter, schemaName) {
+  constructor(query, params, hasBoundParams, sourceError, schemaDefinition, model, adapter, schemaName) {
     this.query = query;
+    this.params = params;
+    this.hasBoundParams = hasBoundParams;
+    this.sourceError = sourceError;
     this.schemaDefinition = schemaDefinition;
     this.model = model;
     this.adapter = adapter;
@@ -6199,7 +6290,14 @@ var NqlBuilderImpl = class {
     if (this._intent) {
       return this._intent;
     }
-    const compilerOptions = extractPseudoColumnKeywords(this.model);
+    if (this.sourceError !== void 0) {
+      throw new Error(`NQL compilation failed: ${this.sourceError}`);
+    }
+    const compilerOptions = {
+      ...extractPseudoColumnKeywords(this.model) ?? {},
+      params: this.params,
+      [NQL_INTERNAL_COMPILER_OPTIONS]: { allowInternalParams: true }
+    };
     const result = nqlCompile(
       this.query,
       this.schemaDefinition,
@@ -6208,7 +6306,8 @@ var NqlBuilderImpl = class {
     );
     if (!result.success) {
       const errors = result.errors?.map((e) => e.message).join(", ") ?? "Unknown error";
-      throw new Error(`NQL compilation failed: ${errors}`);
+      const rawHint = this.hasBoundParams ? " If an interpolation was intended as NQL structure, wrap a trusted fragment with nqlRaw()." : "";
+      throw new Error(`NQL compilation failed: ${errors}${rawHint}`);
     }
     if (result.ast?.mutation && !result.ast?.query) {
       throw new Error(
@@ -6224,12 +6323,15 @@ var NqlBuilderImpl = class {
   toIntentIR() {
     return this.compile();
   }
-  plan() {
+  planInternal() {
     const intent = this.compile();
     return plan(intent, this.model);
   }
+  plan() {
+    return this.planInternal();
+  }
   dump(meta) {
-    const planReport = this.plan();
+    const planReport = this.planInternal();
     if (!this.adapter) {
       return {
         plan: planReport,
@@ -6272,7 +6374,7 @@ var NqlBuilderImpl = class {
         "Cannot execute query: no adapter configured. Pass an adapter to createOrm() or use .toIntentIR() / .plan() for debugging."
       );
     }
-    const planReport = this.plan();
+    const planReport = this.planInternal();
     const compiled = this.adapter.compile(planReport);
     return this.adapter.execute(compiled);
   }
@@ -6661,8 +6763,152 @@ function hydrateJsonAggIncludes(results, planReport) {
   }
 }
 
+// src/dx/relation-paths.ts
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function includeNode(value) {
+  return value !== null && typeof value === "object" ? value : void 0;
+}
+function parseIntentPathIndexes(intentPath) {
+  const indexes = [];
+  const indexPattern = /include\[(\d+)\]/g;
+  let execResult = indexPattern.exec(intentPath);
+  while (execResult !== null) {
+    const rawIndex = execResult[1];
+    if (rawIndex === void 0) break;
+    indexes.push(parseInt(rawIndex, 10));
+    execResult = indexPattern.exec(intentPath);
+  }
+  return indexes;
+}
+function deriveRelationPathFromIntentPath(includes, intentPath, fallbackRelation) {
+  if (includes && intentPath) {
+    let current = includes;
+    const path = [];
+    for (const index of parseIntentPathIndexes(intentPath)) {
+      const item = includeNode(current[index]);
+      if (!item) break;
+      const segment = nonEmptyString(item.via) ?? nonEmptyString(item.relation);
+      if (!segment) break;
+      path.push(segment);
+      current = Array.isArray(item.include) ? item.include : [];
+    }
+    if (path.length > 0) return path.join(".");
+  }
+  return nonEmptyString(fallbackRelation);
+}
+function countDistinctRelationPathsByName(usages) {
+  const pathsByRelationName = /* @__PURE__ */ new Map();
+  for (const usage of usages) {
+    const relationName = nonEmptyString(usage.relationName);
+    if (!relationName) continue;
+    const relationPath = nonEmptyString(usage.relationPath) ?? relationName;
+    const paths = pathsByRelationName.get(relationName) ?? /* @__PURE__ */ new Set();
+    paths.add(relationPath);
+    pathsByRelationName.set(relationName, paths);
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const [relationName, paths] of pathsByRelationName) {
+    counts.set(relationName, paths.size);
+  }
+  return counts;
+}
+
 // src/dx/result-hydrator.ts
 var COMPOSITE_KEY_SEP = "\0";
+function stringProp(source, key) {
+  const value = source?.[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function resolveJoinIncludePath(planReport, decision) {
+  const context = decision.context;
+  const decisionRecord = decision;
+  const contextRecord = context;
+  const explicitRelationPath = stringProp(decisionRecord, "relationPath") ?? stringProp(contextRecord, "relationPath");
+  if (explicitRelationPath) return explicitRelationPath;
+  const fallbackRelation = stringProp(contextRecord, "relation") ?? stringProp(contextRecord, "includeAlias") ?? stringProp(decisionRecord, "relationName");
+  const intentPath = stringProp(contextRecord, "intentPath");
+  return deriveRelationPathFromIntentPath(
+    Array.isArray(planReport.intent?.include) ? planReport.intent.include : void 0,
+    intentPath,
+    fallbackRelation
+  );
+}
+function lastRelationSegment(path) {
+  const segments = path.split(".");
+  return segments[segments.length - 1] ?? path;
+}
+function resolveJoinRelationName(decision, relationPath) {
+  const context = decision.context;
+  const decisionRecord = decision;
+  return stringProp(context, "relation") ?? stringProp(context, "includeAlias") ?? stringProp(decisionRecord, "relationName") ?? lastRelationSegment(relationPath);
+}
+function collectJoinHydrationInfos(planReport) {
+  const candidates = [];
+  for (const decision of planReport.decisions) {
+    if (decision.type !== "include-strategy" || decision.choice !== "join") {
+      continue;
+    }
+    const relationPath = resolveJoinIncludePath(planReport, decision);
+    if (!relationPath) continue;
+    const relationName = resolveJoinRelationName(decision, relationPath);
+    const decisionRecord = decision;
+    const contextRecord = decision.context;
+    const hydrationPrefix = stringProp(decisionRecord, "hydrationPrefix") ?? stringProp(contextRecord, "hydrationPrefix");
+    candidates.push({
+      relationName,
+      relationPath,
+      ...hydrationPrefix && { hydrationPrefix }
+    });
+  }
+  const pathCountsByRelationName = countDistinctRelationPathsByName(candidates);
+  const infosByPath = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    if (infosByPath.has(candidate.relationPath)) continue;
+    const usesFullPath = (pathCountsByRelationName.get(candidate.relationName) ?? 0) > 1;
+    const keyPrefix = candidate.hydrationPrefix ?? (usesFullPath ? candidate.relationPath : candidate.relationName);
+    if (!keyPrefix) continue;
+    infosByPath.set(candidate.relationPath, {
+      relationPath: candidate.relationPath,
+      segments: candidate.relationPath.split("."),
+      keyPrefix,
+      keyPrefixWithDot: `${keyPrefix}.`
+    });
+  }
+  return [...infosByPath.values()];
+}
+function findLongestJoinInfo(key, infos) {
+  let best;
+  for (const info of infos) {
+    if (!key.startsWith(info.keyPrefixWithDot)) continue;
+    if (!best || info.keyPrefixWithDot.length > best.keyPrefixWithDot.length) {
+      best = info;
+    }
+  }
+  return best;
+}
+function assignNestedValue(target, path, value) {
+  let cursor = target;
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (!segment) return;
+    const existing = cursor[segment];
+    if (existing === null) {
+      return;
+    } else if (typeof existing !== "object" || Array.isArray(existing)) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment];
+  }
+  const leaf = path[path.length - 1];
+  if (leaf) cursor[leaf] = value;
+}
+function assignColumnValue(target, columnPath, value) {
+  const segments = columnPath.split(".").filter(Boolean);
+  if (segments.length === 0) return;
+  assignNestedValue(target, segments, value);
+}
 var ResultHydrator = class {
   model;
   from;
@@ -6739,51 +6985,42 @@ var ResultHydrator = class {
    * E2E-004: JOIN strategy for to-one relations returns columns like "author.id", "author.name".
    */
   hydrateJoinIncludes(results, planReport) {
-    const joinDecisions = planReport.decisions.filter(
-      (d) => d.type === "include-strategy" && d.choice === "join"
+    const joinInfos = collectJoinHydrationInfos(planReport);
+    if (joinInfos.length === 0) return;
+    const infosByDepth = [...joinInfos].sort(
+      (a, b) => a.segments.length - b.segments.length
     );
-    if (joinDecisions.length === 0) {
-      return;
-    }
-    const joinInfos = joinDecisions.map((d) => d.context?.relation).filter((r) => typeof r === "string").map((relation) => ({ relation, prefix: `${relation}.` }));
-    if (joinInfos.length === 0) {
-      return;
-    }
-    const joinInfosWithCache = joinInfos.map((info) => ({
-      ...info,
-      cachedKeys: null
-    }));
-    if (results.length > 0) {
-      const firstRow = results.find(
-        (r) => typeof r === "object" && r !== null
-      );
-      if (firstRow) {
-        const firstRecord = firstRow;
-        const allKeys = Object.keys(firstRecord);
-        for (const info of joinInfosWithCache) {
-          info.cachedKeys = allKeys.filter((k) => k.startsWith(info.prefix));
-        }
-      }
-    }
     for (const row of results) {
       if (typeof row !== "object" || row === null) {
         continue;
       }
       const record2 = row;
-      for (const info of joinInfosWithCache) {
-        const keys = info.cachedKeys && info.cachedKeys.length > 0 ? info.cachedKeys : Object.keys(record2).filter((k) => k.startsWith(info.prefix));
-        if (keys.length === 0) continue;
-        const nestedObj = {};
-        let allNull = true;
-        for (const key of keys) {
-          const val = record2[key];
-          if (val !== void 0) {
-            nestedObj[key.slice(info.prefix.length)] = val;
-            delete record2[key];
-            if (val !== null) allNull = false;
-          }
+      const valuesByPath = /* @__PURE__ */ new Map();
+      for (const key of Object.keys(record2)) {
+        const info = findLongestJoinInfo(key, joinInfos);
+        if (!info) continue;
+        const value = record2[key];
+        let entry = valuesByPath.get(info.relationPath);
+        if (!entry) {
+          entry = { values: {}, allNull: true };
+          valuesByPath.set(info.relationPath, entry);
         }
-        record2[info.relation] = allNull ? null : nestedObj;
+        assignColumnValue(
+          entry.values,
+          key.slice(info.keyPrefixWithDot.length),
+          value
+        );
+        if (value !== null && value !== void 0) entry.allNull = false;
+        delete record2[key];
+      }
+      for (const info of infosByDepth) {
+        const entry = valuesByPath.get(info.relationPath);
+        if (!entry) continue;
+        assignNestedValue(
+          record2,
+          info.segments,
+          entry.allNull ? null : entry.values
+        );
       }
     }
   }
@@ -11474,6 +11711,7 @@ export {
   composeBeforeMutationHooks,
   composeBeforeQueryHooks,
   composeOnErrorHooks,
+  countDistinctRelationPathsByName,
   createDialectCapabilities,
   createHookManager,
   createNqlTag,
@@ -11486,6 +11724,7 @@ export {
   defineModel,
   defineSchema,
   denseRank,
+  deriveRelationPathFromIntentPath,
   detectForeignKeys,
   detectManyToMany,
   distinct,
@@ -11588,6 +11827,7 @@ export {
   normalizeSchema,
   not,
   notExists,
+  nqlRaw,
   objectToWhereIntent,
   op,
   or,
@@ -11642,6 +11882,7 @@ export {
   validateAssertionBlocks,
   validateRecursiveInclude,
   validateRecursiveShape,
+  validateTypeName,
   wAvg,
   wCount,
   wMax,