@noy-db/hub 0.1.0-pre.3

package/dist/chunk-GOUT6DND.js

@@ -0,0 +1,1285 @@
+import {
+  evaluateClause,
+  readPath
+} from "./chunk-M5INGEFC.js";
+import {
+  DanglingReferenceError,
+  JoinTooLargeError
+} from "./chunk-ACLDOTNQ.js";
+
+// src/query/join.ts
+var DEFAULT_JOIN_MAX_ROWS = 5e4;
+var JOIN_WARN_FRACTION = 0.8;
+function coerceRefKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+var warnedDanglingKeys = /* @__PURE__ */ new Set();
+function warnOnceDangling(field, target, refId) {
+  const key = `${field}\u2192${target}:${refId}`;
+  if (warnedDanglingKeys.has(key)) return;
+  warnedDanglingKeys.add(key);
+  console.warn(
+    `[noy-db] .join() encountered dangling ref in 'warn' mode: field "${field}" \u2192 "${target}:${refId}" not found. Attaching null.`
+  );
+}
+var warnedCeilingKeys = /* @__PURE__ */ new Set();
+function warnCeilingApproaching(target, side, rows, maxRows) {
+  const key = `${target}:${side}`;
+  if (warnedCeilingKeys.has(key)) return;
+  warnedCeilingKeys.add(key);
+  const pct = Math.round(rows / maxRows * 100);
+  console.warn(
+    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
+  );
+}
+function applyJoins(rows, joins, context) {
+  if (joins.length === 0) return [...rows];
+  let result = [...rows];
+  for (const leg of joins) {
+    result = applyOneJoin(result, leg, context);
+  }
+  return result;
+}
+function applyOneJoin(leftRows, leg, context) {
+  if (leg.isDictJoin) {
+    const dictSource = context.resolveDictSource?.(leg.field);
+    if (!dictSource) {
+      throw new Error(
+        `.join() field "${leg.field}" on "${context.leftCollection}" is declared as a dictKey join but the dict source could not be resolved. Ensure the dictionary has at least one entry.`
+      );
+    }
+    const out = [];
+    const snapshot = dictSource.snapshot();
+    const dictMap = /* @__PURE__ */ new Map();
+    for (const entry of snapshot) {
+      const k = readPath(entry, "key");
+      if (typeof k === "string") dictMap.set(k, entry);
+    }
+    for (const left of leftRows) {
+      const rawId = readPath(left, leg.field);
+      const key = coerceRefKey(rawId);
+      const dictEntry = key === null ? void 0 : dictMap.get(key);
+      out.push({ ...left, [leg.as]: dictEntry ?? null });
+    }
+    return out;
+  }
+  const source = context.resolveSource(leg.target);
+  if (!source) {
+    throw new Error(
+      `.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${context.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before running the query.`
+    );
+  }
+  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS;
+  if (leftRows.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: -1,
+      maxRows,
+      side: "left",
+      message: `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ceiling for target "${leg.target}". Filter the left side further with where()/limit() before joining, or raise the ceiling via { maxRows }. Streaming joins over scan() are not yet supported.`
+    });
+  }
+  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "left", leftRows.length, maxRows);
+  }
+  const rightSnapshot = source.snapshot();
+  if (rightSnapshot.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: rightSnapshot.length,
+      maxRows,
+      side: "right",
+      message: `.join() right side "${leg.target}" has ${rightSnapshot.length} rows, exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } if the data genuinely fits in memory, or track  for streaming joins.`
+    });
+  }
+  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
+  }
+  const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
+  if (strategy === "nested" && source.lookupById) {
+    const lookup = (id) => source.lookupById?.(id);
+    return nestedLoopJoin(leftRows, leg, lookup);
+  }
+  return hashJoin(leftRows, leg, rightSnapshot);
+}
+function nestedLoopJoin(leftRows, leg, lookupById) {
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    const right = key === null ? void 0 : lookupById(key);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function hashJoin(leftRows, leg, rightSnapshot) {
+  const rightMap = /* @__PURE__ */ new Map();
+  for (const record of rightSnapshot) {
+    const rawId = readPath(record, "id");
+    const key = coerceRefKey(rawId);
+    if (key !== null) {
+      rightMap.set(key, record);
+    }
+  }
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    const right = key === null ? void 0 : rightMap.get(key);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function attachJoin(left, leg, right, rawId) {
+  if (left === null || typeof left !== "object") {
+    return left;
+  }
+  const merged = { ...left };
+  const refKey = coerceRefKey(rawId);
+  if (right === void 0) {
+    if (refKey !== null && leg.mode === "strict") {
+      throw new DanglingReferenceError({
+        field: leg.field,
+        target: leg.target,
+        refId: refKey,
+        message: `.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+      });
+    }
+    if (refKey !== null && leg.mode === "warn") {
+      warnOnceDangling(leg.field, leg.target, refKey);
+    }
+    merged[leg.as] = null;
+  } else {
+    merged[leg.as] = right;
+  }
+  return merged;
+}
+function resetJoinWarnings() {
+  warnedDanglingKeys.clear();
+  warnedCeilingKeys.clear();
+}
+
+// src/query/live.ts
+function buildLiveQuery(recompute, upstreams) {
+  return new LiveQueryImpl(recompute, upstreams);
+}
+var LiveQueryImpl = class {
+  constructor(recompute, upstreams) {
+    this.recompute = recompute;
+    this.refresh();
+    for (const upstream of upstreams) {
+      try {
+        this.unsubs.push(upstream.subscribe(this.onUpstreamChange));
+      } catch (err) {
+        this._error = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+  }
+  recompute;
+  _value = [];
+  _error = null;
+  listeners = /* @__PURE__ */ new Set();
+  unsubs = [];
+  stopped = false;
+  get value() {
+    return this._value;
+  }
+  get error() {
+    return this._error;
+  }
+  /**
+   * Bound change handler — used as the callback passed to every
+   * upstream's subscribe. Bound via class field so the `this`
+   * context survives the indirect call from arbitrary upstreams.
+   */
+  onUpstreamChange = () => {
+    this.refresh();
+    for (const cb of this.listeners) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  };
+  refresh() {
+    if (this.stopped) return;
+    try {
+      this._value = this.recompute();
+      this._error = null;
+    } catch (err) {
+      this._error = err instanceof Error ? err : new Error(String(err));
+    }
+  }
+  subscribe(cb) {
+    if (this.stopped) return () => {
+    };
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    for (const unsub of this.unsubs) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.unsubs.length = 0;
+    this.listeners.clear();
+  }
+};
+
+// src/aggregate/strategy.ts
+var NOT_ENABLED = new Error(
+  'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withAggregate }` from "@noy-db/hub/aggregate" and pass it to `createNoydb({ aggregateStrategy: withAggregate() })`.'
+);
+var NO_AGGREGATE = {
+  aggregate() {
+    throw NOT_ENABLED;
+  },
+  groupBy() {
+    throw NOT_ENABLED;
+  },
+  scanAggregate() {
+    throw NOT_ENABLED;
+  }
+};
+
+// src/query/builder.ts
+var EMPTY_PLAN = {
+  clauses: [],
+  orderBy: [],
+  limit: void 0,
+  offset: 0,
+  joins: []
+};
+var Query = class _Query {
+  source;
+  plan;
+  joinContext;
+  aggregateStrategy;
+  constructor(source, plan = EMPTY_PLAN, joinContext, aggregateStrategy = NO_AGGREGATE) {
+    this.source = source;
+    this.plan = plan;
+    this.joinContext = joinContext;
+    this.aggregateStrategy = aggregateStrategy;
+  }
+  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Logical OR group. Pass a callback that builds a sub-query.
+   * Each clause inside the callback is OR-combined; the group itself
+   * joins the parent plan with AND.
+   */
+  or(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+    );
+    const group = {
+      type: "group",
+      op: "or",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Logical AND group. Same shape as `or()` but every clause inside the group
+   * must match. Useful for explicit grouping inside a larger OR.
+   */
+  and(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+    );
+    const group = {
+      type: "group",
+      op: "and",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Sort by a field. Subsequent calls are tie-breakers. */
+  orderBy(field, direction = "asc") {
+    return new _Query(
+      this.source,
+      { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Cap the result size. */
+  limit(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, limit: n },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Skip the first N matching records (after ordering). */
+  offset(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, offset: n },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Resolve a `ref()`-declared foreign key and attach the right-side
+   * record under `opts.as`. — eager, single-FK, intra-
+   * vault joins.
+   *
+   * ```ts
+   * const rows = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .join('clientId', { as: 'client' })
+   *   .toArray()
+   * // → [{ id, amount, client: { id, name, ... } }, ...]
+   * ```
+   *
+   * Preconditions:
+   *   - The Query must have a `joinContext` (constructed via
+   *     `Collection.query()`, not `new Query`).
+   *   - `field` must have a matching `refs: { [field]: ref('<target>') }`
+   *     declaration on the left collection.
+   *   - The target collection must be reachable via the vault
+   *     (either currently open or openable on demand).
+   *
+   * Strategy:
+   *   - Nested-loop against `lookupById` when the target source
+   *     provides it (the common path for Collection targets).
+   *   - Hash join otherwise, or when `{ strategy: 'hash' }` is
+   *     explicitly passed for test purposes.
+   *
+   * Ref-mode semantics on dangling refs (left record has a non-null
+   * FK value pointing at a right-side id that doesn't exist):
+   *   - `strict`  → throws `DanglingReferenceError` with the full
+   *     field / target / refId context.
+   *   - `warn`    → attaches `null` and emits a one-shot warning per
+   *     unique dangling pair.
+   *   - `cascade` → attaches `null` silently. Cascade is a
+   *     delete-time mode; dangling refs visible at read time are
+   *     either mid-flight cascades or pre-existing orphans, not a
+   *     DSL-level error.
+   *
+   * A left-side record whose FK field is `null` / `undefined` is NOT
+   * a dangling ref — it's "no reference at all", always allowed
+   * regardless of mode.
+   *
+   * The return type widens `T` with `Record<As, R | null>`. The `R`
+   * parameter is optional — supply it explicitly for type-checked
+   * access to the joined fields:
+   *
+   * ```ts
+   * invoices.query().join<'client', Client>('clientId', { as: 'client' })
+   * //                 ^^^^^^^^^^^^^^^^^^^ alias literal + right-side type
+   * ```
+   *
+   * Without the generic, the joined field is typed as `unknown`, which
+   * still works but requires a cast to access its properties.
+   *
+   * Joins stay intra-vault by construction — cross-vault
+   * correlation goes through `Noydb.queryAcross`, not
+   * `.join()`.
+   */
+  join(field, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.join() requires a join context. Use collection.query() to construct a join-capable Query instead of the Query constructor directly (the direct constructor is only used for tests with plain-object sources).`
+      );
+    }
+    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.`
+      );
+    }
+    const leg = descriptor ? {
+      field,
+      as: opts.as,
+      target: descriptor.target,
+      mode: descriptor.mode,
+      strategy: opts.strategy,
+      maxRows: opts.maxRows,
+      //  constraint #1 — always 'all' in. Do not remove.
+      partitionScope: "all"
+    } : {
+      // Dict join leg
+      field,
+      as: opts.as,
+      target: field,
+      // dict name = field name for dictKey
+      mode: "strict",
+      strategy: opts.strategy,
+      maxRows: opts.maxRows,
+      partitionScope: "all",
+      isDictJoin: true
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, joins: [...this.plan.joins, leg] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Execute the plan and return the matching records. When the plan
+   * carries any join legs, they are applied after `where` / `orderBy`
+   * / `limit` / `offset` narrow the left set. See the `.join()` doc
+   * for the ordering rationale.
+   */
+  toArray() {
+    const base = executePlanWithSource(this.source, this.plan);
+    if (this.plan.joins.length === 0) return base;
+    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.`
+      );
+    }
+    return applyJoins(base, this.plan.joins, this.joinContext);
+  }
+  /** Return the first matching record, or null. Joins are applied. */
+  first() {
+    const arr = this.limit(1).toArray();
+    return arr[0] ?? null;
+  }
+  /**
+   * 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
+   * (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.
+   */
+  count() {
+    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
+    if (remainingClauses.length === 0) return candidates.length;
+    return filterRecords(candidates, remainingClauses).length;
+  }
+  /**
+   * Reduce the matching records through a named set of reducers.
+   * the aggregation terminal.
+   *
+   * ```ts
+   * const { total, n, avgAmount } = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .aggregate({
+   *     total:     sum('amount'),
+   *     n:         count(),
+   *     avgAmount: avg('amount'),
+   *   })
+   *   .run()
+   * ```
+   *
+   * Returns an `Aggregation<R>` wrapper with two terminals:
+   *   - `.run(): R` — synchronous one-shot reduction
+   *   - `.live(): LiveAggregation<R>` — reactive primitive that
+   *     re-runs the reduction whenever the source notifies of a
+   *     change. Always call `live.stop()` when finished.
+   *
+   * The reducer spec is bound here once and reused by both
+   * terminals — this is why `.aggregate()` returns a wrapper instead
+   * of being a direct terminal. Consumers who only need the static
+   * value read `.run()`; consumers wiring a reactive UI read
+   * `.live()`.
+   *
+   * Joins are intentionally NOT applied to aggregations in —
+   * the same logic as `.count()`. Joins in are projection-only
+   * (they attach an aliased field and never filter), so running
+   * them just to throw the aliases away would be wasteful. If you
+   * need a reducer that reads a joined field, open an issue —
+   * aggregations-across-joins is explicitly out of scope for v1.
+   *
+   * Every reducer factory accepts an optional `{ seed }` parameter
+   * that is plumbed through the protocol but unused by the
+   * executor — that's  constraint #2. When partition-aware
+   * aggregation lands, the seed will carry running state across
+   * partition boundaries without an API break.
+   */
+  aggregate(spec) {
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const executeRecords = () => {
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+    };
+    const upstreams = [];
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
+  }
+  /**
+   * Partition matching records into buckets keyed by a field, then
+   * terminate with `.aggregate(spec)` to compute per-bucket
+   * reducers..
+   *
+   * ```ts
+   * const byClient = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .groupBy('clientId')
+   *   .aggregate({ total: sum('amount'), n: count() })
+   *   .run()
+   * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
+   * ```
+   *
+   * Result rows carry the group key value under the grouping field
+   * name plus every reducer output from the spec. Buckets are
+   * emitted in first-seen order — consumers who want a specific
+   * ordering should `.sort()` downstream.
+   *
+   * **Cardinality caps:** a one-shot warning fires at 10_000
+   * distinct groups; `GroupCardinalityError` throws at 100_000.
+   * Grouping on a high-uniqueness field like `id` or `createdAt` is
+   * almost always a query mistake — the error message names the
+   * field and observed cardinality and suggests narrowing with
+   * `.where()` first.
+   *
+   * **Null / undefined keys:** records with a missing or explicitly
+   * `null` group field get their own buckets. `Map`-based
+   * partitioning distinguishes `undefined` from `null`, so the two
+   * cases do NOT merge. Consumers who want them merged should
+   * coalesce upstream with `.filter()`.
+   *
+   * **Joins are not applied** — same rationale as `.count()` and
+   * `.aggregate()`. Joined fields in are projection-only, so
+   * running a join inside a grouping pipeline would be wasteful and
+   * could trigger `DanglingReferenceError` in strict mode for a
+   * call whose intent is purely to bucket-and-reduce. Grouping by
+   * a joined field is explicitly out of scope for — file an
+   * issue if a real consumer needs it.
+   *
+   * **Filter clauses (`.filter(fn)`):** grouped queries still
+   * support filter clauses in the underlying plan — they run in
+   * the same candidate/filter pipeline that `.aggregate()` uses.
+   * The performance caveat is the same: filter clauses cost O(N)
+   * per record and can't be index-accelerated.
+   */
+  groupBy(field) {
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const executeRecords = () => {
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+    };
+    const upstreams = [];
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    const joinCtx = this.joinContext;
+    const dictLabelResolver = joinCtx?.resolveDictSource ? (() => {
+      const dictSource = joinCtx.resolveDictSource(field);
+      if (!dictSource) return void 0;
+      const snapshot = dictSource.snapshot();
+      const dictMap = /* @__PURE__ */ new Map();
+      for (const entry of snapshot) {
+        const k = entry["key"];
+        const labels = entry["labels"];
+        if (typeof k === "string" && labels && typeof labels === "object") {
+          dictMap.set(k, labels);
+        }
+      }
+      return async (key, locale, fallback) => {
+        const labels = dictMap.get(key);
+        if (!labels) return void 0;
+        if (labels[locale] !== void 0) return labels[locale];
+        const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+        for (const fb of chain) {
+          if (fb === "any") {
+            const any = Object.values(labels)[0];
+            if (any !== void 0) return any;
+          } else if (labels[fb] !== void 0) {
+            return labels[fb];
+          }
+        }
+        return void 0;
+      };
+    })() : void 0;
+    return this.aggregateStrategy.groupBy(executeRecords, field, upstreams, dictLabelResolver);
+  }
+  /**
+   * Re-run the query whenever the source notifies of changes.
+   * Returns an unsubscribe function. The callback receives the latest result.
+   * Throws if the source does not support subscriptions.
+   *
+   * **For joined queries, prefer `.live()`** — `subscribe()`
+   * only re-fires on LEFT-side changes, so joined data can be
+   * stale if the right side mutates between emissions. `.live()`
+   * merges change streams from every join target.
+   */
+  subscribe(cb) {
+    if (!this.source.subscribe) {
+      throw new Error("Query source does not support subscriptions. Pass a source with a subscribe() method.");
+    }
+    cb(this.toArray());
+    return this.source.subscribe(() => cb(this.toArray()));
+  }
+  /**
+   * Reactive terminal — returns a `LiveQuery<T>` that re-runs the
+   * query and updates its `value` whenever any source feeding it
+   * mutates..
+   *
+   * For non-joined queries, `.live()` is a convenience over the
+   * existing `.subscribe()` callback shape: a hand-rolled reactive
+   * primitive with `value` / `error` fields and a `subscribe(cb)`
+   * notification channel. Frame-agnostic — Vue / React / Solid
+   * adapters wrap it in their own primitive.
+   *
+   * For joined queries, `.live()` additionally subscribes to every
+   * join target's change stream. Mutations on a right-side
+   * collection (insert / update / delete of a client referenced by
+   * an invoice) re-fire the live query and re-evaluate every
+   * dependent left row. Right-side targets are deduped by
+   * collection name, so a chain that joins the same target twice
+   * (e.g. billing client + shipping client → both 'clients') only
+   * subscribes once.
+   *
+   * **Ref-mode behavior on right-side disappearance** — matches the
+   * eager `.toArray()` contract from :
+   *   - `strict`  → re-run throws `DanglingReferenceError`. The
+   *     LiveQuery catches the throw, stores it in `live.error`, and
+   *     notifies listeners (the throw does NOT propagate out of
+   *     the source's change handler — that would tear down the
+   *     emitter). Consumers check `live.error` after each
+   *     notification and render an error state in the UI.
+   *   - `warn`    → joined value flips to `null`; the existing
+   *     warn-channel deduplication keeps repeated re-runs from
+   *     spamming the console.
+   *   - `cascade` → no special handling needed; the cascade-
+   *     delete mechanism propagates the right-side delete into the
+   *     left collection on the next tick, and the live query
+   *     naturally re-fires with the orphaned left rows gone.
+   *
+   * Always call `live.stop()` when finished — it tears down every
+   * upstream subscription. The Vue layer's `onUnmounted` hook
+   * should call `stop()` automatically; raw consumers must do it
+   * themselves.
+   *
+   * **Limitations:**
+   *   - No granular delta updates — the whole query re-runs on
+   *     every change.
+   *   - No microtask batching — bursty changes produce one re-run
+   *     per change.
+   *   - No re-planning under live mutations — the planner picks
+   *     once at subscription time and reuses the same plan.
+   *   - Streaming live joins are deferred.
+   */
+  live() {
+    const upstreams = [];
+    if (this.source.subscribe) {
+      const leftSubscribe = this.source.subscribe.bind(this.source);
+      upstreams.push({
+        subscribe: (cb) => leftSubscribe(cb)
+      });
+    }
+    if (this.plan.joins.length > 0 && this.joinContext) {
+      const subscribed = /* @__PURE__ */ new Set();
+      for (const leg of this.plan.joins) {
+        if (subscribed.has(leg.target)) continue;
+        subscribed.add(leg.target);
+        const rightSource = this.joinContext.resolveSource(leg.target);
+        if (rightSource?.subscribe) {
+          const rightSubscribe = rightSource.subscribe.bind(rightSource);
+          upstreams.push({
+            subscribe: (cb) => rightSubscribe(cb)
+          });
+        }
+      }
+    }
+    return buildLiveQuery(() => this.toArray(), upstreams);
+  }
+  /**
+   * Return the plan as a JSON-friendly object. FilterClause entries are
+   * stripped (their `fn` cannot be serialized) and replaced with
+   * { type: 'filter', fn: '[function]' } so devtools can still see them.
+   */
+  toPlan() {
+    return serializePlan(this.plan);
+  }
+};
+function executePlanWithSource(source, plan) {
+  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function candidateRecords(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) {
+    return { candidates: source.snapshot(), remainingClauses: clauses };
+  }
+  const lookupById = (id) => source.lookupById?.(id);
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field") continue;
+    if (!indexes.has(clause.field)) continue;
+    let ids = null;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, clause.value);
+    } else if (clause.op === "in" && Array.isArray(clause.value)) {
+      ids = indexes.lookupIn(clause.field, clause.value);
+    }
+    if (ids !== null) {
+      const remaining = [];
+      for (let j = 0; j < clauses.length; j++) {
+        if (j !== i) remaining.push(clauses[j]);
+      }
+      return {
+        candidates: materializeIds(ids, lookupById),
+        remainingClauses: remaining
+      };
+    }
+  }
+  return { candidates: source.snapshot(), remainingClauses: clauses };
+}
+function materializeIds(ids, lookupById) {
+  const out = [];
+  for (const id of ids) {
+    const record = lookupById(id);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function executePlan(records, plan) {
+  let result = filterRecords(records, plan.clauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function filterRecords(records, clauses) {
+  if (clauses.length === 0) return [...records];
+  const out = [];
+  for (const r of records) {
+    let matches = true;
+    for (const clause of clauses) {
+      if (!evaluateClause(r, clause)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) out.push(r);
+  }
+  return out;
+}
+function sortRecords(records, orderBy) {
+  return [...records].sort((a, b) => {
+    for (const { field, direction } of orderBy) {
+      const av = readField(a, field);
+      const bv = readField(b, field);
+      const cmp = compareValues(av, bv);
+      if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+function readField(record, field) {
+  if (record === null || record === void 0) return void 0;
+  if (!field.includes(".")) {
+    return record[field];
+  }
+  const segments = field.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function compareValues(a, b) {
+  if (a === void 0 || a === null) return b === void 0 || b === null ? 0 : 1;
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function serializePlan(plan) {
+  return {
+    clauses: plan.clauses.map(serializeClause),
+    orderBy: plan.orderBy,
+    limit: plan.limit,
+    offset: plan.offset,
+    joins: plan.joins
+  };
+}
+function serializeClause(clause) {
+  if (clause.type === "filter") {
+    return { type: "filter", fn: "[function]" };
+  }
+  if (clause.type === "group") {
+    return {
+      type: "group",
+      op: clause.op,
+      clauses: clause.clauses.map(serializeClause)
+    };
+  }
+  return clause;
+}
+
+// src/query/scan-builder.ts
+var DEFAULT_SCAN_PAGE_SIZE = 100;
+var ScanBuilder = class _ScanBuilder {
+  pageProvider;
+  pageSize;
+  clauses;
+  /**
+   * Zero-or-more join legs to apply per record as the stream flows.
+   * Each leg attaches the resolved right-side record (or null) under
+   * its alias. — streaming joins.
+   *
+   * Joins are evaluated AFTER clauses, so a `where()` filtered-out
+   * record never triggers a right-side lookup. This is the same
+   * ordering as `Query.toArray()` (clauses first, joins after) and
+   * keeps the streaming path from doing wasted work.
+   */
+  joins;
+  /**
+   * Join resolution context. Required for `.join()` to translate a
+   * field name into a target collection + ref mode and to resolve
+   * the right-side `JoinableSource`. Optional because tests
+   * construct ScanBuilder directly with synthetic page providers
+   * that don't know about ref() — calling `.join()` without a
+   * context throws with an actionable error.
+   */
+  joinContext;
+  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext) {
+    this.pageProvider = pageProvider;
+    this.pageSize = pageSize;
+    this.clauses = clauses;
+    this.joins = joins;
+    this.joinContext = joinContext;
+  }
+  /**
+   * Add a field comparison. Runs per record as the scan stream
+   * flows through, so non-matching records are dropped before they
+   * reach `.aggregate()` or the iteration consumer. Multiple
+   * `.where()` calls are AND-combined — same semantics as
+   * `Query.where()`.
+   *
+   * Clauses cannot use the secondary-index fast path here because
+   * the scan sources records from the adapter's paginator, not from
+   * the in-memory cache where indexes live. Index-accelerated scans
+   * are a future optimization — the current implementation
+   * evaluates clauses per record in O(1) per clause.
+   */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      [...this.clauses, clause],
+      this.joins,
+      this.joinContext
+    );
+  }
+  /**
+   * Escape hatch: add an arbitrary predicate function. Same
+   * non-serializable caveat as `Query.filter()` — filter clauses
+   * don't round-trip through `toPlan()`. Prefer `.where()` when
+   * possible.
+   */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      [...this.clauses, clause],
+      this.joins,
+      this.joinContext
+    );
+  }
+  /**
+   * Resolve a `ref()`-declared foreign key per record as the scan
+   * stream flows, attaching the right-side record (or null) under
+   * `opts.as`. — streaming joins over `scan()`.
+   *
+   * ```ts
+   * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
+   *   await processInvoice(inv) // inv.client is attached
+   * }
+   *
+   * // Or terminate with .aggregate() for streaming joined aggregation
+   * const { total } = await invoices.scan()
+   *   .where('status', '==', 'open')
+   *   .join('clientId', { as: 'client' })
+   *   .aggregate({ total: sum('amount') })
+   * ```
+   *
+   * **The key difference from eager `.join()`:** the LEFT
+   * side streams page-by-page from the adapter and is never
+   * materialized. Memory ceiling on the left is O(pageSize), not
+   * O(rowCount). This is what makes streaming joins suitable for
+   * collections that exceed the eager join's 50_000-row ceiling.
+   *
+   * **Right-side strategy** is auto-selected per leg:
+   *   - **Indexed** — right source exposes `lookupById`, so each
+   *     left row costs O(1). This is the common path for
+   *     Collection right sides, which back `lookupById` with a Map
+   *     lookup over the in-memory cache. The right collection must
+   *     be in eager mode (the same constraint as eager join's
+   *     `querySourceForJoin` from ).
+   *   - **Hash** — right source has only `snapshot()`. Build a
+   *     `Map<id, record>` once at iteration start, probe per left
+   *     row. Same correctness, same per-row cost as the indexed
+   *     path; the difference is the upfront cost of materializing
+   *     the right side once.
+   *
+   * Both strategies hold the right side in memory for the duration
+   * of the iteration. The "streaming" property applies to the LEFT
+   * side only — true left-and-right streaming joins (where neither
+   * side fits in memory) require a sort-merge join planner that's
+   * out of scope for.
+   *
+   * **Ref-mode semantics** match eager `.join()` exactly:
+   *   - `strict`  → throws `DanglingReferenceError` mid-stream
+   *     when a left record points at a non-existent right id.
+   *     The throw aborts the async iterator — consumers should
+   *     wrap the `for await` in try/catch if they want to recover.
+   *   - `warn`    → attaches `null` and emits a one-shot warning
+   *     per unique dangling pair (deduped via the same warn
+   *     channel as eager join).
+   *   - `cascade` → attaches `null` silently. A delete-time mode;
+   *     dangling refs at read time are mid-flight or pre-existing
+   *     orphans, not a DSL error.
+   *
+   * Left records with null/undefined FK values attach `null`
+   * regardless of mode — same "no reference at all" policy as
+   * eager join and write-time `enforceRefsOnPut`.
+   *
+   * **Multi-FK chaining** is supported via repeated `.join()`
+   * calls: each leg resolves an independent ref. Each leg
+   * independently picks its right-side strategy and applies its
+   * own ref mode.
+   *
+   * **Joins are NOT applied** to a `.aggregate()` terminal that
+   * doesn't reference joined fields — wait, that's not quite
+   * right. The streaming path actually DOES apply joins before
+   * `.aggregate()` because the join attaches a field that the
+   * spec might reference. Unlike `Query.aggregate()` (which skips
+   * joins entirely as a projection-only short-circuit), the
+   * streaming aggregation can't know whether the spec touches a
+   * joined field, so it always applies joins. Consumers who want
+   * unjoined streaming aggregation should leave `.join()` off the
+   * chain — the chain is composable for a reason.
+   *
+   *  constraint #1 — every JoinLeg carries `partitionScope:
+   * 'all'` plumbed through but never read by. Same seam as
+   * eager join.
+   */
+  join(field, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `ScanBuilder.join() requires a join context. Use collection.scan() to construct a join-capable scan instead of the ScanBuilder constructor directly (the direct constructor is only used for tests with synthetic page providers).`
+      );
+    }
+    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.`
+      );
+    }
+    const leg = {
+      field,
+      as: opts.as,
+      target: descriptor.target,
+      mode: descriptor.mode,
+      strategy: void 0,
+      maxRows: void 0,
+      //  constraint #1 — always 'all' in, never read by
+      // the streaming executor. partition-aware scan joins
+      // will populate this from where() predicates without
+      // changing the planner shape.
+      partitionScope: "all"
+    };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      this.clauses,
+      [...this.joins, leg],
+      this.joinContext
+    );
+  }
+  /**
+   * Iterate the scan as an async iterable. Walks the page
+   * provider's cursors forward until exhaustion, applying every
+   * clause per record — only matching records are yielded.
+   *
+   * Backward-compatible with the previous async-generator `scan()`
+   * return type for `for await … of` consumers.
+   */
+  async *[Symbol.asyncIterator]() {
+    const joinResolvers = this.joins.length === 0 ? null : this.buildJoinResolvers();
+    let page = await this.pageProvider.listPage({ limit: this.pageSize });
+    while (true) {
+      for (const record of page.items) {
+        if (!this.recordMatches(record)) continue;
+        if (joinResolvers === null) {
+          yield record;
+        } else {
+          let attached = record;
+          for (const resolver of joinResolvers) {
+            attached = this.applyOneJoinStreaming(attached, resolver);
+          }
+          yield attached;
+        }
+      }
+      if (page.nextCursor === null) return;
+      page = await this.pageProvider.listPage({
+        cursor: page.nextCursor,
+        limit: this.pageSize
+      });
+    }
+  }
+  /**
+   * Per-leg right-side resolution state. Built once at iteration
+   * start and reused for every left record. Two strategies:
+   *
+   *   - `lookupById`: present when the right source exposes the
+   *     hook directly (typical Collection right side). Per-row
+   *     cost is O(1).
+   *   - `hashByPrimaryKey`: built from `snapshot()` when no
+   *     lookupById. Per-row cost is O(1) after the upfront O(N)
+   *     materialization. Same as eager join's hash strategy.
+   *
+   * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
+   * key on `field→target:refId` so the same dangling pair only
+   * warns once per iteration. The dedup is per-iteration, not
+   * per-process — a long-running scan that re-iterates would warn
+   * again, which is the desired behavior (the data may have
+   * changed between iterations).
+   */
+  buildJoinResolvers() {
+    if (!this.joinContext) {
+      throw new Error(
+        `ScanBuilder iterator: ${this.joins.length} join leg(s) present but no JoinContext attached. Use collection.scan() to construct a join-capable scan.`
+      );
+    }
+    const resolvers = [];
+    for (const leg of this.joins) {
+      const source = this.joinContext.resolveSource(leg.target);
+      if (!source) {
+        throw new Error(
+          `ScanBuilder.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${this.joinContext.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before iterating the scan.`
+        );
+      }
+      let lookupById = null;
+      let hashByPrimaryKey = null;
+      if (source.lookupById) {
+        const fn = source.lookupById.bind(source);
+        lookupById = (id) => fn(id);
+      } else {
+        const map = /* @__PURE__ */ new Map();
+        for (const record of source.snapshot()) {
+          const rawId = readPath(record, "id");
+          const key = coerceRefKey2(rawId);
+          if (key !== null) map.set(key, record);
+        }
+        hashByPrimaryKey = map;
+      }
+      resolvers.push({
+        leg,
+        source,
+        lookupById,
+        hashByPrimaryKey,
+        warnedKeys: /* @__PURE__ */ new Set()
+      });
+    }
+    return resolvers;
+  }
+  /**
+   * Resolve a single join leg for one left record and return the
+   * left record with the joined field attached under
+   * `leg.as`. Pure function over `(left, resolver)`; never
+   * mutates the input.
+   *
+   * Ref-mode dispatch matches eager `applyJoins` from :
+   *   - null/undefined FK → attach null silently (always allowed)
+   *   - dangling FK + strict → throw `DanglingReferenceError`
+   *   - dangling FK + warn → attach null, warn-once per pair
+   *   - dangling FK + cascade → attach null silently
+   */
+  applyOneJoinStreaming(left, resolver) {
+    if (left === null || typeof left !== "object") {
+      return left;
+    }
+    const { leg } = resolver;
+    const rawId = readPath(left, leg.field);
+    const refKey = coerceRefKey2(rawId);
+    let right = void 0;
+    if (refKey !== null) {
+      if (resolver.lookupById !== null) {
+        right = resolver.lookupById(refKey);
+      } else if (resolver.hashByPrimaryKey !== null) {
+        right = resolver.hashByPrimaryKey.get(refKey);
+      }
+    }
+    const merged = {
+      ...left
+    };
+    if (right === void 0) {
+      if (refKey !== null && leg.mode === "strict") {
+        throw new DanglingReferenceError({
+          field: leg.field,
+          target: leg.target,
+          refId: refKey,
+          message: `ScanBuilder.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+        });
+      }
+      if (refKey !== null && leg.mode === "warn") {
+        const dedupKey = `${leg.field}\u2192${leg.target}:${refKey}`;
+        if (!resolver.warnedKeys.has(dedupKey)) {
+          resolver.warnedKeys.add(dedupKey);
+          console.warn(
+            `[noy-db] ScanBuilder.join() encountered dangling ref in 'warn' mode: field "${leg.field}" \u2192 "${leg.target}:${refKey}" not found. Attaching null.`
+          );
+        }
+      }
+      merged[leg.as] = null;
+    } else {
+      merged[leg.as] = right;
+    }
+    return merged;
+  }
+  /**
+   * Reduce the scan stream through a named set of reducers and
+   * return the final aggregated shape.
+   *
+   * Memory is O(reducers): one mutable state slot per spec key.
+   * Records flow through the pipeline one at a time via
+   * `for await` and are discarded after their `step()` is applied
+   * — never collected into an array. This is the distinguishing
+   * property from `Query.aggregate()`, which materializes the full
+   * match set first.
+   *
+   * Reuses the same reducer protocol as `Query.aggregate()`,
+   * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
+   * `max(field)` all work unchanged. The `{ seed }` parameter
+   * plumbing from  constraint #2 is honored transparently — the
+   * factories ignore it in and the scan executor never
+   * touches the per-reducer state construction.
+   *
+   * **Returns a Promise**, unlike `Query.aggregate().run()` which
+   * is synchronous. The scan is inherently async because it walks
+   * adapter pages, so the terminal has to be too. Consumers
+   * destructure with await:
+   *
+   * ```ts
+   * const { total, n } = await invoices.scan()
+   *   .where('year', '==', 2025)
+   *   .aggregate({ total: sum('amount'), n: count() })
+   * ```
+   *
+   * **No `.live()` in.** `scan().aggregate().live()` would
+   * require reconciling an unbounded streaming iteration with a
+   * change-stream subscription — a design problem, not just a code
+   * one. Consumers with huge collections and live needs should
+   * narrow with `.where()` enough to fit in the 50k `query()`
+   * limit and use `query().aggregate().live()` instead.
+   */
+  async aggregate(spec) {
+    const keys = Object.keys(spec);
+    const state = {};
+    for (const key of keys) {
+      state[key] = spec[key].init();
+    }
+    for await (const record of this) {
+      for (const key of keys) {
+        state[key] = spec[key].step(state[key], record);
+      }
+    }
+    const result = {};
+    for (const key of keys) {
+      result[key] = spec[key].finalize(state[key]);
+    }
+    return result;
+  }
+  /**
+   * Evaluate the clause list against a single record. Linear in
+   * the clause count; short-circuits on first false. Clauses on a
+   * scan are always re-evaluated per record — no index-accelerated
+   * 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;
+    for (const clause of this.clauses) {
+      if (!evaluateClause(record, clause)) return false;
+    }
+    return true;
+  }
+};
+function coerceRefKey2(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+
+export {
+  DEFAULT_JOIN_MAX_ROWS,
+  applyJoins,
+  resetJoinWarnings,
+  buildLiveQuery,
+  NO_AGGREGATE,
+  Query,
+  executePlan,
+  ScanBuilder
+};
+//# sourceMappingURL=chunk-GOUT6DND.js.map