@jarenjs/db 0.49.2 → 0.56.0

package/src/query.js

@@ -39,7 +39,7 @@ import { chain } from './driver.js';
 import {
   planQuery, planEntityQuery, entityShape, planEntityPredicate, entityPathRef,
 } from './plan.js';
-import { emitPlan, emitEntityPlan, createEntityPredicateEmitters } from './emit.js';
+import { emitPlan, emitEntityPlan, createEntityPredicateEmitters, UnrepresentablePath } from './emit.js';
 import { selectPlan } from './algebra.js';
 import { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
 import { derivedSlotValue, probeBox, probeVector, columnScore } from './derive.js';
@@ -77,6 +77,33 @@ export function createQueryState(bound = undefined, operators = null,
   };
 }
 
+/**
+ * The answer for a native selection's items: the engine's result shape
+ * (`undefined | item | items`), or — when the document is a chain's
+ * element WINDOW, `[<phrase>]` (plan.js, `wrapped`) — the items as the
+ * ONE array that constructor yields, never singleton-unwrapped: an empty
+ * selection is `[]`, one row is `[row]`. Exactly the engine's answer for
+ * the same document, which is what lets a chain's `toArray()` push.
+ * @param {any} entry
+ * @param {any[]} items
+ * @returns {any}
+ */
+function answerOf(entry, items) {
+  return entry.planned.wrapped === true ? items : sequenceResult(items);
+}
+
+/**
+ * The same for one aggregate value: `[value]` under the window, and `[]`
+ * for an aggregate that answers nothing.
+ * @param {any} entry
+ * @param {any} value
+ * @returns {any}
+ */
+function wrapValue(entry, value) {
+  if (entry.planned.wrapped !== true) return value;
+  return value === undefined ? [] : [value];
+}
+
 /** @param {any} value - a bindable native parameter? */
 function bindable(value) {
   return typeof value === 'string'
@@ -299,8 +326,26 @@ export function createQueryEngine(context) {
       return out;
     };
 
-    const plan = shapePlan(planned.plan ?? selectPlan(collection.name));
-    const emitted = emitPlan(plan, dialect, physical);
+    let plan = shapePlan(planned.plan ?? selectPlan(collection.name));
+    let emitted;
+    try {
+      emitted = emitPlan(plan, dialect, physical);
+    }
+    catch (error) {
+      if (!(error instanceof UnrepresentablePath)) throw error;
+      // a member name the dialect cannot spell: the whole document runs
+      // in the set residual, named — and strict mode refuses it by name
+      if (strict) {
+        throw new DbCompileError('JD0010',
+          `strict mode refused a residual: 'path' — ${error.message}`, collection.docPath);
+      }
+      planned = {
+        ...planned, plan: null, mode: 'set', rowReturn: null, udfs: [], prefilters: [],
+        series: null, reasons: [{ construct: 'path', reason: error.message }, ...planned.reasons],
+      };
+      plan = shapePlan(selectPlan(collection.name));
+      emitted = emitPlan(plan, dialect, physical);
+    }
     const externalNames = planned.analysis.externals.map((e) => e.name);
     const limits = profile === null ? undefined : profile.limits;
     const entry = {
@@ -549,6 +594,12 @@ export function createQueryEngine(context) {
    */
   const candidatesOf = (entry, externals, diverted) => {
     if (diverted) {
+      // a diversion IS a full-table scan; the plan-shape check above
+      // only ever saw the native statement
+      if (entry.needsScanCheck) {
+        throw profileRefusal(`the profile refuses a full-table scan of '${collection.name}' `
+          + '(a bound external the database cannot take diverted the call to the whole collection)');
+      }
       if (entry.planned.mode === 'knn') knnStats.diverted++;
       return chain(fullScanOf(entry), (statement) =>
         chain(statement.all(fullScanParams(entry)), (rows) =>
@@ -612,26 +663,26 @@ export function createQueryEngine(context) {
             const items = [];
             for (const row of checkRowBound(entry, rows))
               items.push(...entry.rowResidual(JSON.parse(row.doc), externals));
-            return sequenceResult(items);
+            return answerOf(entry, items);
           }));
       }
       return chain(statementOf(entry), (statement) => {
         if (entry.plan.aggregate !== null) {
           return chain(statement.get(bindParams(entry, externals)),
-            (row) => aggregateResult(entry, row));
+            (row) => wrapValue(entry, aggregateResult(entry, row)));
         }
         if (entry.plan.bucket !== null) {
           return chain(statement.all(bindParams(entry, externals)), (rows) => {
             const items = bucketItems(entry, checkRowBound(entry, rows));
             if (items === null) return divertBucket(entry, document, externals);
             countSeries(entry, 1, rows.length, items.length);
-            return sequenceResult(items);
+            return answerOf(entry, items);
           });
         }
         return chain(statement.all(bindParams(entry, externals)), (rows) => {
           const docs = rowsToDocs(checkRowBound(entry, rows));
           countSeries(entry, 1, docs.length, docs.length);
-          return sequenceResult(docs);
+          return answerOf(entry, docs);
         });
       });
     });
@@ -664,6 +715,21 @@ export function createQueryEngine(context) {
       if (done) return Promise.resolve({ done: true, value: undefined });
       if (bufferedAt < buffered.length) return Promise.resolve(nextFromBuffer());
 
+      if (entry.planned.wrapped === true) {
+        // a chain's element window is ONE item — the array — whatever
+        // the plan mode; the cursor hands it over as `execute` answers it
+        if (materialized === null) {
+          materialized = Promise.resolve(chain(execute(document, options), (value) => {
+            buffered = [value];
+            bufferedAt = 0;
+          }));
+        }
+        return materialized.then(() => {
+          if (bufferedAt < buffered.length) return nextFromBuffer();
+          done = true;
+          return { done: true, value: undefined };
+        });
+      }
       if (entry.planned.mode === 'set' || entry.planned.mode === 'knn'
         || mustDivert(entry, externals)) {
         // the barrier: materialize candidates, pack the result items
@@ -827,11 +893,14 @@ export function createQueryEngine(context) {
     return chain(connection.prepare(dialect.explainQuery(entry.sql)), (statement) =>
       chain(statement.all(eqpParams), (rows) => ({
         mode: entry.planned.mode,
+        // a chain's element window (`[<phrase>]`): the phrase planned as
+        // if bare, its rows answered as the one array item
+        wrapped: entry.planned.wrapped === true,
         externals: [...entry.externalNames],
         operators: [...entry.dependencies.operators],
         functions: [...entry.dependencies.functions],
         collations: [...entry.dependencies.collations],
-        limits: entry.limits,
+        limits: entry.residualLimits ?? entry.limits,
         sql: entry.sql,
         params,
         indexes,
@@ -876,6 +945,7 @@ export function createQueryEngine(context) {
 // ————— The entity query surface (the second document kind) —————
 
 import { mergeEntityRow, parseGraphRow } from './graph.js';
+import { relationTables } from './model.js';
 
 /** The default include depth bound (D14: printed, never silent). */
 export const INCLUDE_DEPTH_DEFAULT = 3;
@@ -897,6 +967,10 @@ export function createEntityQueryEngine(context) {
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
   const physicalOf = (name) => ({ table: mapping.entities[name].table });
+  // the relation tables of every root this engine serves (§10.1): the
+  // engine is the scope every entity set of the store shares, so a
+  // producer holding one set can follow a hop into another root
+  const relations = relationTables(entities);
 
   const entryFor = (document, pushdown) => {
     const key = ['E', document, dialect.name, pushdown];
@@ -907,6 +981,14 @@ export function createEntityQueryEngine(context) {
     }
     state.counters.misses++;
     let planned = planEntityQuery(document, entities, mapping, operators);
+    if (planned.referenced.length === 0) {
+      // `$[*]` over the entity MAP answered the rows of every entity,
+      // mixed, and explain() named no table read; the root is the map
+      // of entity arrays, and a query ranges over one of them by name
+      throw new DbCompileError('JD0033',
+        'an entity query ranges over a declared entity array ($.<Entity>[*]); this '
+        + 'document names none, so it has no rows to answer', '/entities');
+    }
     if (!pushdown) {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: 'pushdown', reason: 'disabled by the harness switch' }] };
@@ -986,11 +1068,11 @@ export function createEntityQueryEngine(context) {
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql);
     return chain(entry.statement, (statement) => {
       if (entry.planned.plan.aggregate === 'count')
-        return chain(statement.get(params), (row) => row?.value ?? 0);
+        return chain(statement.get(params), (row) => wrapValue(entry, row?.value ?? 0));
       return chain(statement.all(params), (rows) => {
         const retEntity = entry.planned.plan.bindings
           .find((binding) => binding.name === entry.planned.plan.ret).entity;
-        return sequenceResult(rows.map((row) =>
+        return answerOf(entry, rows.map((row) =>
           mergeEntityRow(mapping.entities[retEntity], row, '__doc')));
       });
     });
@@ -1001,6 +1083,7 @@ export function createEntityQueryEngine(context) {
     const entry = entryFor(document, pushdown);
     const base = {
       mode: entry.planned.mode,
+      wrapped: entry.planned.wrapped === true,
       referenced: [...entry.planned.referenced],
       reasons: entry.planned.reasons,
       sql: entry.sql,
@@ -1018,7 +1101,7 @@ export function createEntityQueryEngine(context) {
       })));
   };
 
-  return { execute, explain };
+  return { execute, explain, relations };
 }
 
 /**
@@ -1048,6 +1131,11 @@ export function createLoadEngine(context, entityName) {
   const refuse = (reason, path) => new DbCompileError('JD0032',
     `${reason} (include path: ${path.join('.') || '<root>'})`,
     entities.get(entityName)?.docPath);
+  const isWindowBound = (value) => Number.isSafeInteger(value) && value >= 0;
+  /** An include's window inside its subquery: LIMIT, and OFFSET for a
+   * `skip` — per parent row, since the subquery is correlated (§10.4). */
+  const windowClause = (child) => (child.take !== undefined || (child.skip !== undefined && child.skip > 0)
+    ? ` ${dialect.limitClause(child.take ?? null, child.skip)}` : '');
 
   /** Compile a where EXPRESSION over `$it` against one entity. */
   const compileWhere = (expression, entity, path) => {
@@ -1118,6 +1206,7 @@ export function createLoadEngine(context, entityName) {
       where: spec?.where !== undefined ? compileWhere(spec.where, entity, path) : null,
       order: spec?.orderBy !== undefined ? compileOrder(spec.orderBy, entity, path) : null,
       take: spec?.take,
+      skip: spec?.skip,
       includes: [],
     };
     const includeSpec = spec?.include;
@@ -1133,6 +1222,26 @@ export function createLoadEngine(context, entityName) {
           [...path, relationName]);
       }
       const childSpec = includeSpec[relationName] === true ? {} : includeSpec[relationName];
+      if (childSpec.count === true) {
+        // a count counts EVERY related row; a where/take beside it was
+        // dropped without a word, and the number answered was the total
+        const dropped = ['where', 'orderBy', 'take', 'skip', 'include', 'after']
+          .filter((member) => childSpec[member] !== undefined);
+        if (dropped.length > 0) {
+          throw refuse(`count: true counts every related row and takes no ${dropped.join('/')} — `
+            + 'load the rows to count a subset', [...path, relationName]);
+        }
+      }
+      for (const member of ['take', 'skip']) {
+        if (childSpec[member] !== undefined && !isWindowBound(childSpec[member]))
+          throw refuse(`${member} must be a non-negative integer`, [...path, relationName]);
+      }
+      // a keyset cursor is one position in ONE ordered set; an include is
+      // a set per parent, so it windows with skip/take and never seeks
+      if (childSpec.after !== undefined) {
+        throw refuse("'after' (keyset pagination) paginates the root — an include windows with skip and take",
+          [...path, relationName]);
+      }
       const childName = relation.to;
       const include = {
         name: relationName,
@@ -1186,6 +1295,17 @@ export function createLoadEngine(context, entityName) {
     const parentKey = parentNode.entityMapping.keys[0];
     if (include.count === true) {
       const childTable = mapping.entities[relation.to].table;
+      if (relation.kind === 'manyToMany') {
+        const join = mapping.joinTables[relation.joinTable];
+        const own = join.left.entity === parentNode.entity.name ? join.left : join.right;
+        return `(SELECT COUNT(*) FROM ${q(relation.joinTable)} AS ${q(childAlias)} `
+          + `WHERE ${q(childAlias)}.${q(own.column)} = ${q(parentAlias)}.${q(parentKey)})`;
+      }
+      if (relation.kind === 'oneToOne') {
+        const childKey = mapping.entities[relation.to].keys[0];
+        return `(SELECT COUNT(*) FROM ${q(childTable)} AS ${q(childAlias)} `
+          + `WHERE ${q(childAlias)}.${q(childKey)} = ${q(parentAlias)}.${q(relation.via)})`;
+      }
       return `(SELECT COUNT(*) FROM ${q(childTable)} AS ${q(childAlias)} `
         + `WHERE ${q(childAlias)}.${q(relation.via)} = ${q(parentAlias)}.${q(parentKey)})`;
     }
@@ -1220,10 +1340,10 @@ export function createLoadEngine(context, entityName) {
         + (child.where !== null
           ? ` AND ${emitters.emitPred(rendered.aliasSql, rendered.docSql, child.where)}` : '')
         + ` ORDER BY ${orderSql.join(', ')}`
-        + (child.take !== undefined ? ` ${dialect.limitClause(child.take, undefined)}` : '')
+        + windowClause(child)
       : `SELECT ${rendered.aliasSql}.* FROM ${q(childTable)} AS ${q(childAlias)} `
         + `WHERE ${conditions.join(' AND ')} ORDER BY ${orderSql.join(', ')}`
-        + (child.take !== undefined ? ` ${dialect.limitClause(child.take, undefined)}` : '');
+        + windowClause(child);
     if (relation.kind === 'oneToOne') {
       return `(SELECT json_object(${rendered.projection()}) FROM `
         + `(${inner} ${dialect.limitClause(1, undefined)}) AS ${q(childAlias)})`;
@@ -1250,6 +1370,11 @@ export function createLoadEngine(context, entityName) {
     };
     const emitters = createEntityPredicateEmitters(dialect, param);
     const maxDepth = spec?.maxDepth ?? INCLUDE_DEPTH_DEFAULT;
+    for (const member of ['take', 'skip']) {
+      // interpolated into LIMIT/OFFSET as written: a string ran as SQL
+      if (spec?.[member] !== undefined && !isWindowBound(spec[member]))
+        throw refuse(`${member} must be a non-negative integer`, []);
+    }
     const tree = buildTree(entityName, spec ?? {}, 0, maxDepth, [], new Set());
     const rendered = render(tree, 'r', param, emitters);