@noy-db/hub 0.2.0-pre.6 → 0.2.0-pre.7

package/dist/periods/index.d.cts

@@ -1,10 +1,10 @@
-import { a7 as PeriodsStrategy } from '../types-DVlvNn2c.cjs';
-export { a8 as CarryForwardContext, a9 as ClosePeriodOptions, aa as OpenPeriodOptions, ab as PERIODS_COLLECTION, ac as PeriodRecord, ad as ReadOnlyCollection, ae as appendPeriodLedgerEntry, af as assertTsWritable, ag as chainAnchor, ah as loadPeriods, ai as validatePeriodName } from '../types-DVlvNn2c.cjs';
-import '../lazy-builder-DXlSCNCJ.cjs';
-import '../predicate-B0IKeBXx.cjs';
+import { a7 as PeriodsStrategy } from '../types-r-y7TIqj.cjs';
+export { a8 as CarryForwardContext, a9 as ClosePeriodOptions, aa as OpenPeriodOptions, ab as PERIODS_COLLECTION, ac as PeriodRecord, ad as ReadOnlyCollection, ae as appendPeriodLedgerEntry, af as assertTsWritable, ag as chainAnchor, ah as loadPeriods, ai as validatePeriodName } from '../types-r-y7TIqj.cjs';
+import '../lazy-builder-wY4pMCEe.cjs';
+import '../predicate-BSAGEyu5.cjs';
 import '../strategy-DSTrsZ8t.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-5I0MZ0jQ.cjs';
+import '../index-vB43MAt4.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/periods/index.d.ts

@@ -1,10 +1,10 @@
-import { a7 as PeriodsStrategy } from '../types-DlnZh1_i.js';
-export { a8 as CarryForwardContext, a9 as ClosePeriodOptions, aa as OpenPeriodOptions, ab as PERIODS_COLLECTION, ac as PeriodRecord, ad as ReadOnlyCollection, ae as appendPeriodLedgerEntry, af as assertTsWritable, ag as chainAnchor, ah as loadPeriods, ai as validatePeriodName } from '../types-DlnZh1_i.js';
-import '../lazy-builder-D1MyR1qH.js';
-import '../predicate-B0IKeBXx.js';
+import { a7 as PeriodsStrategy } from '../types-DT7cXRHq.js';
+export { a8 as CarryForwardContext, a9 as ClosePeriodOptions, aa as OpenPeriodOptions, ab as PERIODS_COLLECTION, ac as PeriodRecord, ad as ReadOnlyCollection, ae as appendPeriodLedgerEntry, af as assertTsWritable, ag as chainAnchor, ah as loadPeriods, ai as validatePeriodName } from '../types-DT7cXRHq.js';
+import '../lazy-builder-7tIpFyWN.js';
+import '../predicate-BSAGEyu5.js';
 import '../strategy-DSTrsZ8t.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-fIPPh5dg.js';
+import '../index-CmWQyC4e.js';
 import '@noy-db/attestation';
 
 /**

package/dist/periods/index.js

@@ -6,13 +6,13 @@ import {
   loadPeriods,
   validatePeriodName,
   withPeriods
-} from "../chunk-ZQMYB56Z.js";
+} from "../chunk-O3JCRQT3.js";
 import "../chunk-UF3BUNQZ.js";
-import "../chunk-6A4AMQ2H.js";
+import "../chunk-QYO6I7KK.js";
 import "../chunk-Z6FNBOTC.js";
-import "../chunk-5OVIFUQE.js";
-import "../chunk-EKTOYEZ3.js";
-import "../chunk-6HJ2ZALB.js";
+import "../chunk-WIRRPTFH.js";
+import "../chunk-YAMTXW77.js";
+import "../chunk-REQJJIPP.js";
 export {
   PERIODS_COLLECTION,
   appendPeriodLedgerEntry,

package/dist/{predicate-B0IKeBXx.d.cts → predicate-BSAGEyu5.d.cts}

@@ -163,7 +163,31 @@ interface GroupClause {
     readonly op: 'and' | 'or';
     readonly clauses: readonly Clause[];
 }
-type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause;
+/**
+ * Cartesian-product expansion clause. Appended to `QueryPlan.clauses`
+ * by `Query.crossJoin()`. Processed in declaration order by
+ * `executeClausePipeline` — NOT by `evaluateClause` (which is a
+ * per-record predicate and throws on this type).
+ */
+interface CrossJoinClause {
+    readonly type: 'crossJoin';
+    /** Target collection name to cross-join against. */
+    readonly target: string;
+    /** Alias under which the right-side record is exposed on each result row. */
+    readonly as: string;
+    /**
+     * Lateral filter callback. `undefined` → full cartesian product.
+     * Two call shapes:
+     *   - Subset:    `(left) => TTarget[]`            — returns the right rows for this left row
+     *   - Predicate: `(left) => (right) => boolean`   — executor materializes then filters
+     */
+    readonly on?: (left: unknown) => unknown[] | ((right: unknown) => boolean);
+    /** When `on:` was supplied as `{ predicate: name }`, the name is stored here for queryHash. */
+    readonly onPredicateName?: string;
+    /** Per-clause row ceiling override. `undefined` → `DEFAULT_CROSS_JOIN_MAX_ROWS`. */
+    readonly maxRows?: number;
+}
+type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause | CrossJoinClause;
 /**
  * Read a possibly nested field path like "address.city" from a record.
  * Returns undefined if any segment is missing.
@@ -182,4 +206,4 @@ declare function evaluateFieldClause(record: unknown, clause: FieldClause): bool
  */
 declare function evaluateClause(record: unknown, clause: Clause): boolean;
 
-export { CollectionIndexes as C, type FieldClause as F, type GroupClause as G, type HashIndex as H, type IndexDef as I, type Operator as O, type Clause as a, type FilterClause as b, evaluateFieldClause as c, evaluateClause as e, readPath as r };
+export { CollectionIndexes as C, type FieldClause as F, type GroupClause as G, type HashIndex as H, type IndexDef as I, type Operator as O, type Clause as a, type FilterClause as b, evaluateFieldClause as c, type CrossJoinClause as d, evaluateClause as e, readPath as r };

package/dist/{predicate-B0IKeBXx.d.ts → predicate-BSAGEyu5.d.ts}

@@ -163,7 +163,31 @@ interface GroupClause {
     readonly op: 'and' | 'or';
     readonly clauses: readonly Clause[];
 }
-type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause;
+/**
+ * Cartesian-product expansion clause. Appended to `QueryPlan.clauses`
+ * by `Query.crossJoin()`. Processed in declaration order by
+ * `executeClausePipeline` — NOT by `evaluateClause` (which is a
+ * per-record predicate and throws on this type).
+ */
+interface CrossJoinClause {
+    readonly type: 'crossJoin';
+    /** Target collection name to cross-join against. */
+    readonly target: string;
+    /** Alias under which the right-side record is exposed on each result row. */
+    readonly as: string;
+    /**
+     * Lateral filter callback. `undefined` → full cartesian product.
+     * Two call shapes:
+     *   - Subset:    `(left) => TTarget[]`            — returns the right rows for this left row
+     *   - Predicate: `(left) => (right) => boolean`   — executor materializes then filters
+     */
+    readonly on?: (left: unknown) => unknown[] | ((right: unknown) => boolean);
+    /** When `on:` was supplied as `{ predicate: name }`, the name is stored here for queryHash. */
+    readonly onPredicateName?: string;
+    /** Per-clause row ceiling override. `undefined` → `DEFAULT_CROSS_JOIN_MAX_ROWS`. */
+    readonly maxRows?: number;
+}
+type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause | CrossJoinClause;
 /**
  * Read a possibly nested field path like "address.city" from a record.
  * Returns undefined if any segment is missing.
@@ -182,4 +206,4 @@ declare function evaluateFieldClause(record: unknown, clause: FieldClause): bool
  */
 declare function evaluateClause(record: unknown, clause: Clause): boolean;
 
-export { CollectionIndexes as C, type FieldClause as F, type GroupClause as G, type HashIndex as H, type IndexDef as I, type Operator as O, type Clause as a, type FilterClause as b, evaluateFieldClause as c, evaluateClause as e, readPath as r };
+export { CollectionIndexes as C, type FieldClause as F, type GroupClause as G, type HashIndex as H, type IndexDef as I, type Operator as O, type Clause as a, type FilterClause as b, evaluateFieldClause as c, type CrossJoinClause as d, evaluateClause as e, readPath as r };

package/dist/{public-envelope-YKHKP74C.js → public-envelope-BXPXMN3U.js}

@@ -12,9 +12,9 @@ import {
   resolveLocale,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-WEA4TDTJ.js";
-import "./chunk-5OVIFUQE.js";
-import "./chunk-6HJ2ZALB.js";
+} from "./chunk-BNUCCUES.js";
+import "./chunk-WIRRPTFH.js";
+import "./chunk-REQJJIPP.js";
 export {
   DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
   PUBLIC_ENVELOPE_FIELDS,
@@ -28,4 +28,4 @@ export {
   savePublicEnvelope,
   validatePublicEnvelopeInput
 };
-//# sourceMappingURL=public-envelope-YKHKP74C.js.map
+//# sourceMappingURL=public-envelope-BXPXMN3U.js.map

package/dist/query/index.cjs

@@ -22,6 +22,9 @@ var query_exports = {};
 __export(query_exports, {
   Aggregation: () => Aggregation,
   CollectionIndexes: () => CollectionIndexes,
+  CrossJoinSourceUnknownError: () => CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError: () => CrossJoinTooLargeError,
+  DEFAULT_CROSS_JOIN_MAX_ROWS: () => DEFAULT_CROSS_JOIN_MAX_ROWS,
   DEFAULT_JOIN_MAX_ROWS: () => DEFAULT_JOIN_MAX_ROWS,
   DanglingReferenceError: () => DanglingReferenceError,
   GROUPBY_MAX_CARDINALITY: () => GROUPBY_MAX_CARDINALITY,
@@ -119,6 +122,10 @@ function evaluateClause(record, clause) {
       return clause.fn(record);
     case "wherePredicate":
       return clause.fn(record, clause.ctx);
+    case "crossJoin":
+      throw new Error(
+        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
+      );
     case "group":
       if (clause.op === "and") {
         for (const child of clause.clauses) {
@@ -208,6 +215,34 @@ var JoinTooLargeError = class extends NoydbError {
     this.side = opts.side;
   }
 };
+var CrossJoinTooLargeError = class extends NoydbError {
+  target;
+  expected;
+  limit;
+  constructor(opts) {
+    super(
+      "CROSS_JOIN_TOO_LARGE",
+      `crossJoin("${opts.target}"): would produce ${opts.expected} rows, exceeding the limit of ${opts.limit}. Narrow the left side with .where() first, or raise the ceiling with crossJoin("${opts.target}", { ..., maxRows: ${opts.expected} }).`
+    );
+    this.name = "CrossJoinTooLargeError";
+    this.target = opts.target;
+    this.expected = opts.expected;
+    this.limit = opts.limit;
+  }
+};
+var CrossJoinSourceUnknownError = class extends NoydbError {
+  target;
+  leftCollection;
+  constructor(target, leftCollection) {
+    super(
+      "CROSS_JOIN_SOURCE_UNKNOWN",
+      `crossJoin("${target}"): collection "${target}" is not known in the vault (cross-joining from "${leftCollection}"). Make sure "${target}" is open in the same vault before executing this query.`
+    );
+    this.name = "CrossJoinSourceUnknownError";
+    this.target = target;
+    this.leftCollection = leftCollection;
+  }
+};
 var DanglingReferenceError = class extends NoydbError {
   field;
   target;
@@ -474,6 +509,7 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
@@ -755,6 +791,78 @@ var Query = class _Query {
       this.predicates
     );
   }
+  /**
+   * Cartesian-product cross-join against `target` collection. Each result row
+   * carries the original `T` fields plus `result[as]` populated from every
+   * right-side row (or the filtered subset when `on:` is supplied).
+   *
+   * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
+   * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
+   * where clause references the aliased fields).
+   *
+   * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
+   * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
+   * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
+   *
+   * **`on:` shapes:**
+   *   - `on: (left) => TTarget[]`              — subset form (most efficient)
+   *   - `on: (left) => (right) => boolean`     — predicate form
+   *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
+   *     (requires the Query to have been augmented via `_withPredicates`)
+   *
+   * Requires a JoinContext (constructed via `collection.query()`).
+   */
+  crossJoin(target, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.crossJoin("${target}"): requires a join context. Use collection.query() to construct a cross-join-capable Query instead of the Query constructor directly.`
+      );
+    }
+    let onFn;
+    let onPredicateName;
+    if (opts.on !== void 0) {
+      if (typeof opts.on === "function") {
+        onFn = opts.on;
+        if (this.predicates) {
+          console.warn(
+            `Query.crossJoin("${target}", { on: callback }): inline on: callback inside a withMaterializedView query() disables queryHash drift detection for this cross-join. Use on: { predicate: '<name>' } to enable it.`
+          );
+        }
+      } else {
+        const predName = opts.on.predicate;
+        if (!this.predicates) {
+          throw new Error(
+            `Query.crossJoin("${target}", { on: { predicate: "${predName}" } }): the { predicate } form requires a predicates map. Use this form inside a withMaterializedView query() callback that declares predicates: { ${predName}: { hash, fn } }.`
+          );
+        }
+        const decl = this.predicates.get(predName);
+        if (!decl) {
+          throw new Error(
+            `Query.crossJoin("${target}"): predicate "${predName}" not registered. Available: ${[...this.predicates.keys()].join(", ") || "(none)"}.`
+          );
+        }
+        const as = opts.as;
+        const predicateFn = decl.fn;
+        onFn = (_left) => (right) => predicateFn({ ..._left, [as]: right });
+        onPredicateName = predName;
+      }
+    }
+    const clause = {
+      type: "crossJoin",
+      target,
+      as: opts.as,
+      ...onFn !== void 0 && { on: onFn },
+      ...onPredicateName !== void 0 && { onPredicateName },
+      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy,
+      this.predicates
+    );
+  }
   /**
    * Execute the plan and return the matching records. When the plan
    * carries any join legs, they are applied after `where` / `orderBy`
@@ -762,7 +870,7 @@ var Query = class _Query {
    * for the ordering rationale.
    */
   toArray() {
-    const base = executePlanWithSource(this.source, this.plan);
+    const base = executePlanWithSource(this.source, this.plan, this.joinContext);
     if (this.plan.joins.length === 0) return base;
     if (!this.joinContext) {
       throw new Error(
@@ -786,6 +894,14 @@ var Query = class _Query {
    * intent is purely to count.
    */
   count() {
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      if (!this.joinContext) {
+        throw new Error(
+          `Query.count(): plan contains crossJoin clauses but no JoinContext is attached.`
+        );
+      }
+      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).length;
@@ -833,7 +949,13 @@ var Query = class _Query {
   aggregate(spec) {
     const source = this.source;
     const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
     const executeRecords = () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.aggregate(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
       return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
     };
@@ -850,7 +972,13 @@ var Query = class _Query {
     }
     const source = this.source;
     const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
     const executeRecords = () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.groupBy(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
       return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
     };
@@ -964,6 +1092,21 @@ var Query = class _Query {
         }
       }
     }
+    if (this.joinContext) {
+      const subscribedCross = /* @__PURE__ */ new Set();
+      for (const clause of this.plan.clauses) {
+        if (clause.type !== "crossJoin") continue;
+        if (subscribedCross.has(clause.target)) continue;
+        subscribedCross.add(clause.target);
+        const rightSource = this.joinContext.resolveSource(clause.target);
+        if (rightSource?.subscribe) {
+          const rightSubscribe = rightSource.subscribe.bind(rightSource);
+          upstreams.push({
+            subscribe: (cb) => rightSubscribe(cb)
+          });
+        }
+      }
+    }
     return buildLiveQuery(() => this.toArray(), upstreams);
   }
   /**
@@ -975,9 +1118,20 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan) {
-  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+function executePlanWithSource(source, plan, joinContext) {
+  const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
+  let result;
+  if (hasCrossJoins) {
+    if (!joinContext) {
+      throw new Error(
+        `Query.toArray(): plan contains crossJoin clauses but no JoinContext is attached. Use collection.query() instead of new Query() for cross-join support.`
+      );
+    }
+    result = executeClausePipeline(source, plan.clauses, joinContext);
+  } else {
+    const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  }
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
   }
@@ -1027,6 +1181,11 @@ function materializeIds(ids, lookupById) {
   return out;
 }
 function executePlan(records, plan) {
+  if (plan.clauses.some((c) => c.type === "crossJoin")) {
+    throw new Error(
+      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
+    );
+  }
   let result = filterRecords(records, plan.clauses);
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
@@ -1054,6 +1213,74 @@ function filterRecords(records, clauses) {
   }
   return out;
 }
+function executeClausePipeline(source, clauses, joinContext) {
+  let rel = [...source.snapshot()];
+  let filterBatch = [];
+  for (const clause of clauses) {
+    if (clause.type === "crossJoin") {
+      if (filterBatch.length > 0) {
+        rel = filterRecords(rel, filterBatch);
+        filterBatch = [];
+      }
+      const rightSource = joinContext.resolveSource(clause.target);
+      if (!rightSource) {
+        throw new CrossJoinSourceUnknownError(clause.target, joinContext.leftCollection);
+      }
+      rel = applyCrossJoin(rel, clause, rightSource);
+    } else {
+      filterBatch.push(clause);
+    }
+  }
+  if (filterBatch.length > 0) {
+    rel = filterRecords(rel, filterBatch);
+  }
+  return rel;
+}
+function applyCrossJoin(leftRel, clause, rightSource) {
+  const rightRows = rightSource.snapshot();
+  const maxRows = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
+  const { as } = clause;
+  if (!clause.on) {
+    const product = leftRel.length * rightRows.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) {
+        expanded2.push({ ...leftObj, [as]: right });
+      }
+    }
+    return expanded2;
+  }
+  const expanded = [];
+  let cumulative = 0;
+  for (const left of leftRel) {
+    const callbackResult = clause.on(left);
+    let filteredRight;
+    if (Array.isArray(callbackResult)) {
+      filteredRight = callbackResult;
+    } else {
+      filteredRight = rightRows.filter(
+        callbackResult
+      );
+    }
+    cumulative += filteredRight.length;
+    if (cumulative > maxRows) {
+      throw new CrossJoinTooLargeError({
+        target: clause.target,
+        expected: cumulative,
+        limit: maxRows
+      });
+    }
+    const leftObj = left;
+    for (const right of filteredRight) {
+      expanded.push({ ...leftObj, [as]: right });
+    }
+  }
+  return expanded;
+}
 function sortRecords(records, orderBy) {
   return [...records].sort((a, b) => {
     for (const { field, direction } of orderBy) {
@@ -1116,6 +1343,16 @@ function serializeClause(clause) {
       clauses: clause.clauses.map(serializeClause)
     };
   }
+  if (clause.type === "crossJoin") {
+    return {
+      type: "crossJoin",
+      target: clause.target,
+      as: clause.as,
+      on: clause.on ? "[function]" : void 0,
+      onPredicateName: clause.onPredicateName,
+      maxRows: clause.maxRows
+    };
+  }
   return clause;
 }
 function canonicalCtxHash(ctx) {
@@ -2102,6 +2339,9 @@ function coerceRefKey2(value) {
 0 && (module.exports = {
   Aggregation,
   CollectionIndexes,
+  CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
   DEFAULT_JOIN_MAX_ROWS,
   DanglingReferenceError,
   GROUPBY_MAX_CARDINALITY,