@noy-db/hub 0.6.0-pre.8 → 0.6.0

package/dist/{chunk-3737A6EA.js → chunk-EHW7NLGD.js}

@@ -1,23 +1,25 @@
 import {
-  applyJoins
-} from "./chunk-E6427JU2.js";
+  applyJoins,
+  splitAroundJoins
+} from "./chunk-EV2TDHQZ.js";
 import {
   NO_REDUCE
 } from "./chunk-YMUFFJCO.js";
 import {
   reducerBuilder
-} from "./chunk-CADUYBQD.js";
+} from "./chunk-ATL3ZVXT.js";
 import {
   evaluateClause,
   hasFnClause,
   readPath
-} from "./chunk-IGJCYUT5.js";
+} from "./chunk-NSITFOCJ.js";
 import {
   CrossJoinSourceUnknownError,
   CrossJoinTooLargeError,
   DanglingReferenceError,
-  FieldNotQueryableError
-} from "./chunk-HNGSV2YC.js";
+  FieldNotQueryableError,
+  RefNotDeclaredError
+} from "./chunk-Z3BZXPRO.js";
 
 // src/kernel/query/live.ts
 function buildLiveQuery(recompute, upstreams) {
@@ -99,6 +101,17 @@ var EMPTY_PLAN = {
   joins: []
 };
 var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
+function assertNoJoinAliasField(fields, joins, terminal) {
+  if (joins.length === 0) return;
+  const aliases = new Set(joins.map((leg) => leg.as));
+  for (const field of fields) {
+    const head = field.split(".")[0];
+    if (!aliases.has(head)) continue;
+    throw new Error(
+      `Query.${terminal}(): field "${field}" addresses the join alias "${head}", but ${terminal}() does not apply join legs \u2014 it would silently group every row under undefined. Joined aggregation is not supported. Either aggregate over the left collection's own fields, or use .crossJoin("${head}", { as: \u2026 }), whose expansion IS visible to ${terminal}().`
+    );
+  }
+}
 var Query = class _Query {
   source;
   plan;
@@ -415,9 +428,11 @@ var Query = class _Query {
     const descriptor = this.joinContext.resolveRef(field);
     const isDictJoinField = !descriptor && this.joinContext.resolveDictSource?.(field) != null;
     if (!descriptor && !isDictJoinField) {
-      throw new Error(
-        `Query.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry. See the ref() docs for the full list of modes.`
-      );
+      throw new RefNotDeclaredError({
+        collection: this.joinContext.leftCollection,
+        field,
+        message: `Query.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry. See the ref() docs for the full list of modes.`
+      });
     }
     const leg = descriptor ? {
       field,
@@ -453,6 +468,32 @@ var Query = class _Query {
    * carries the original `T` fields plus `result[as]` populated from every
    * right-side row (or the filtered subset when `on:` is supplied).
    *
+   * **⚠️ INNER-join semantics — an empty right subset DROPS the left row.**
+   * Each left row is emitted once per matching right row, so when `on:`
+   * yields nothing the row vanishes with no error, no warning and no count
+   * mismatch. This bites hardest on a reverse FK, where `.join()` (which is
+   * forward-only, and already a genuine LEFT outer join) does not apply and
+   * `.crossJoin()` is the only tool. To keep the row, return a one-element
+   * array holding `null`:
+   *
+   * ```ts
+   * .crossJoin('clients', { as: 'client', on: (b) => byEntity.get(b.entityId) ?? [null] })
+   * //                                                                          ^^^^^^^^
+   * //                                              the ONLY thing preserving the row
+   * ```
+   *
+   * **Prefer `outer: true`**, which does exactly this and types the alias as
+   * `TTarget | null`:
+   *
+   * ```ts
+   * .crossJoin('clients', { as: 'client', outer: true, on: (b) => byEntity.get(b.entityId) ?? [] })
+   * ```
+   *
+   * The `?? [null]` form remains valid and is what `outer` does internally, but
+   * it is invisible intent: it types the alias as non-null while the row can
+   * hold null, and a later "simplification" that drops it silently
+   * reintroduces the row loss.
+   *
    * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
    * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
    * where clause references the aliased fields).
@@ -510,7 +551,8 @@ var Query = class _Query {
       as: opts.as,
       ...onFn !== void 0 && { on: onFn },
       ...onPredicateName !== void 0 && { onPredicateName },
-      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
+      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows },
+      ...opts.outer === true && { outer: true }
     };
     return new _Query(
       this.source,
@@ -532,14 +574,37 @@ var Query = class _Query {
    * (Left/base i18n fields are resolved by `get`/`list`, not here.)
    */
   toArray(opts) {
-    const base = this.decodeVia(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
-    if (this.plan.joins.length === 0) return base;
+    const { preJoin, postJoin } = splitAroundJoins(this.plan.clauses, this.plan.joins);
+    if (postJoin.length === 0) {
+      const base = this.decodeVia(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
+      if (this.plan.joins.length === 0) return base;
+      return applyJoins(base, this.plan.joins, this.requireJoinContext("toArray"), opts?.locale);
+    }
+    const joinContext = this.requireJoinContext("toArray");
+    const narrowed = this.decodeVia(
+      executePlanWithSource(
+        this.source,
+        { ...this.plan, clauses: preJoin, orderBy: [], limit: void 0, offset: 0 },
+        joinContext,
+        opts?.locale
+      )
+    );
+    const joined = applyJoins(narrowed, this.plan.joins, joinContext, opts?.locale);
+    const filtered = filterRecords(joined, postJoin, fnViewDecoder(this.source));
+    return applyOrderAndPage(filtered, this.plan, this.source, joinContext, opts?.locale);
+  }
+  /**
+   * Joins need a `JoinContext`. Unreachable in practice — `.join()` throws
+   * when one is missing — but belt-and-braces for a plan built through the
+   * raw `Query` constructor with joins pre-populated.
+   */
+  requireJoinContext(terminal) {
     if (!this.joinContext) {
       throw new Error(
-        `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
+        `Query.${terminal}(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
       );
     }
-    return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
+    return this.joinContext;
   }
   /**
    * Decode this source's Via-covered fields on read (e.g. money: stored
@@ -567,12 +632,19 @@ var Query = class _Query {
   }
   /**
    * Return the number of matching records (after where/filter,
-   * before limit). **Joins are NOT applied** — count() reports the
-   * left-side cardinality, because joins in are projection-only
+   * before limit). **Joins are normally NOT applied** — count() reports the
+   * left-side cardinality, because joins are projection-only
    * (they attach an aliased field; they never filter). Running joins
    * here just to discard the aliases would be wasteful, and in strict
    * mode it could throw `DanglingReferenceError` for a call whose
    * intent is purely to count.
+   *
+   * The exception (#1030) is a `where` clause addressing a join alias. Then
+   * the legs must run, because the predicate is part of what is being
+   * counted — skipping them would report the unfiltered left cardinality.
+   * A strict-mode `DanglingReferenceError` becomes reachable from `count()`
+   * in exactly that case, which is acceptable: the caller asked to filter on
+   * the joined side, so they asked for the join.
    */
   count() {
     if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
@@ -583,12 +655,20 @@ var Query = class _Query {
       }
       return executeClausePipeline(this.source, this.plan.clauses, this.joinContext).length;
     }
-    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
-    if (remainingClauses.length === 0) return candidates.length;
-    return filterRecords(candidates, remainingClauses, fnViewDecoder(this.source)).length;
+    const { preJoin, postJoin } = splitAroundJoins(this.plan.clauses, this.plan.joins);
+    const { candidates, remainingClauses } = candidateRecords(this.source, preJoin);
+    const narrowed = remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(this.source));
+    if (postJoin.length === 0) return narrowed.length;
+    const joined = applyJoins(narrowed, this.plan.joins, this.requireJoinContext("count"));
+    return filterRecords(joined, postJoin, fnViewDecoder(this.source)).length;
   }
   aggregate(specOrBuild) {
     let spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    assertNoJoinAliasField(
+      Object.values(spec).map((r) => r.field).filter((f) => typeof f === "string"),
+      this.plan.joins,
+      "aggregate"
+    );
     spec = this.source.via?.wrapReducers(spec) ?? spec;
     const source = this.source;
     const clauses = this.plan.clauses;
@@ -613,6 +693,7 @@ var Query = class _Query {
     if (fields.length === 0) {
       throw new Error(".groupBy() requires at least one field");
     }
+    assertNoJoinAliasField(fields, this.plan.joins, "groupBy");
     const source = this.source;
     const clauses = this.plan.clauses;
     const joinCtx = this.joinContext;
@@ -777,6 +858,10 @@ function executePlanWithSource(source, plan, joinContext, locale) {
     const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
     result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
+  return applyOrderAndPage(result, plan, source, joinContext, locale);
+}
+function applyOrderAndPage(rows, plan, source, joinContext, locale) {
+  let result = rows;
   if (plan.orderBy.length > 0) {
     const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale, source.via);
     result = sortRecords(result, plan.orderBy, source.via, labelMaps);
@@ -896,15 +981,17 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   const rightRows = rightSource.snapshot();
   const maxRows = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
   const { as } = clause;
+  const outer = clause.outer === true;
   if (!clause.on) {
-    const product = leftRel.length * rightRows.length;
+    const rightSide = outer && rightRows.length === 0 ? [null] : rightRows;
+    const product = leftRel.length * rightSide.length;
     if (product > maxRows) {
       throw new CrossJoinTooLargeError({ target: clause.target, expected: product, limit: maxRows });
     }
     const expanded2 = [];
     for (const left of leftRel) {
       const leftObj = left;
-      for (const right of rightRows) {
+      for (const right of rightSide) {
         expanded2.push({ ...leftObj, [as]: right });
       }
     }
@@ -922,6 +1009,7 @@ function applyCrossJoin(leftRel, clause, rightSource) {
         callbackResult
       );
     }
+    if (outer && filteredRight.length === 0) filteredRight = [null];
     cumulative += filteredRight.length;
     if (cumulative > maxRows) {
       throw new CrossJoinTooLargeError({
@@ -1044,7 +1132,11 @@ function serializeClause(clause) {
       as: clause.as,
       on: clause.on ? "[function]" : void 0,
       onPredicateName: clause.onPredicateName,
-      maxRows: clause.maxRows
+      maxRows: clause.maxRows,
+      // Part of the identity, not decoration: `outer` changes which rows come
+      // back, so omitting it here would let an inner-mode plan be reused for an
+      // outer-mode query under the same hash (#1130).
+      outer: clause.outer
     };
   }
   return clause;
@@ -1300,9 +1392,11 @@ var ScanBuilder = class _ScanBuilder {
     }
     const descriptor = this.joinContext.resolveRef(field);
     if (!descriptor) {
-      throw new Error(
-        `ScanBuilder.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry.`
-      );
+      throw new RefNotDeclaredError({
+        collection: this.joinContext.leftCollection,
+        field,
+        message: `ScanBuilder.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry.`
+      });
     }
     const leg = {
       field,
@@ -1336,10 +1430,11 @@ var ScanBuilder = class _ScanBuilder {
    */
   async *[Symbol.asyncIterator]() {
     const joinResolvers = this.joins.length === 0 ? null : this.buildJoinResolvers();
+    const { preJoin, postJoin } = splitAroundJoins(this.clauses, this.joins);
     let page = await this.pageProvider.listPage({ limit: this.pageSize });
     while (true) {
       for (const record of page.items) {
-        if (!this.recordMatches(record)) continue;
+        if (!this.recordMatches(record, preJoin)) continue;
         const decoded = this.decodeVia(record);
         if (joinResolvers === null) {
           yield decoded;
@@ -1348,6 +1443,7 @@ var ScanBuilder = class _ScanBuilder {
           for (const resolver of joinResolvers) {
             attached = this.applyOneJoinStreaming(attached, resolver);
           }
+          if (postJoin.length > 0 && !this.recordMatches(attached, postJoin)) continue;
           yield attached;
         }
       }
@@ -1494,10 +1590,10 @@ var ScanBuilder = class _ScanBuilder {
    * path, because the stream sources records from the adapter
    * paginator, not from the in-memory cache where indexes live.
    */
-  recordMatches(record) {
-    if (this.clauses.length === 0) return true;
-    const fnView = this.via?.hasResultDecode && hasFnClause(this.clauses) ? this.decodeVia(record) : void 0;
-    for (const clause of this.clauses) {
+  recordMatches(record, clauses = this.clauses) {
+    if (clauses.length === 0) return true;
+    const fnView = this.via?.hasResultDecode && hasFnClause(clauses) ? this.decodeVia(record) : void 0;
+    for (const clause of clauses) {
       if (!evaluateClause(record, clause, fnView)) return false;
     }
     return true;
@@ -1517,4 +1613,4 @@ export {
   executePlan,
   ScanBuilder
 };
-//# sourceMappingURL=chunk-3737A6EA.js.map
+//# sourceMappingURL=chunk-EHW7NLGD.js.map