@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/chunk-CF5UU4S7.js

@@ -0,0 +1,757 @@
+import {
+  canonicalGroupKey
+} from "./chunk-XZHEOSQ2.js";
+import {
+  bindDistinctReducers,
+  reducerBuilder
+} from "./chunk-F2TDU7MQ.js";
+import {
+  LiveMaintainer
+} from "./chunk-VHM7HCKB.js";
+import {
+  gateTerminal
+} from "./chunk-5O7D6ZTW.js";
+import {
+  readPath
+} from "./chunk-HLEK5VAN.js";
+import {
+  applyI18nLocale
+} from "./chunk-GHLTDZRS.js";
+import {
+  viaBinder
+} from "./chunk-Z5HTYMMQ.js";
+import {
+  GroupCardinalityError
+} from "./chunk-244VXYPG.js";
+
+// src/with-lookup/reduce/reduction.ts
+function reduceRecords(records, spec) {
+  const state = {};
+  for (const key of Object.keys(spec)) {
+    state[key] = spec[key].init();
+  }
+  for (const record of records) {
+    for (const key of Object.keys(spec)) {
+      state[key] = spec[key].step(state[key], record);
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(spec)) {
+    result[key] = spec[key].finalize(state[key]);
+  }
+  return result;
+}
+var LiveAggregationImpl = class {
+  constructor(recompute, upstreams) {
+    this.recompute = recompute;
+    try {
+      this.value = recompute();
+      this.error = void 0;
+    } catch (err) {
+      this.value = void 0;
+      this.error = err;
+    }
+    for (const upstream of upstreams) {
+      const unsub = upstream.subscribe(() => this.refresh());
+      this.unsubscribes.push(unsub);
+    }
+  }
+  recompute;
+  value;
+  error;
+  listeners = /* @__PURE__ */ new Set();
+  unsubscribes = [];
+  stopped = false;
+  refresh() {
+    if (this.stopped) return;
+    try {
+      this.value = this.recompute();
+      this.error = void 0;
+    } catch (err) {
+      this.error = err;
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.warn("[noy-db] LiveReduction listener threw:", 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.unsubscribes) {
+      try {
+        unsub();
+      } catch (err) {
+        console.warn("[noy-db] LiveReduction upstream unsubscribe threw:", err);
+      }
+    }
+    this.unsubscribes.length = 0;
+    this.listeners.clear();
+  }
+};
+var Reduction = class {
+  constructor(executeRecords, spec, upstreams, gate) {
+    this.executeRecords = executeRecords;
+    this.spec = spec;
+    this.upstreams = upstreams;
+    this.gate = gate;
+  }
+  executeRecords;
+  spec;
+  upstreams;
+  gate;
+  /**
+   * Execute the query and reduce the results synchronously.
+   * Returns the reduced shape matching the spec — e.g. a spec of
+   * `{ total: sum('amount'), n: count() }` returns
+   * `{ total: number, n: number }`.
+   */
+  run() {
+    return gateTerminal(this.gate, "aggregate().run", () => reduceRecords(this.executeRecords(), this.spec));
+  }
+  /**
+   * Build a reactive `LiveReduction<R>` that re-runs the reduction
+   * whenever any upstream source notifies of a change. The initial
+   * value is computed eagerly in the constructor, so consumers can
+   * read `live.value` immediately after calling `.live()`.
+   *
+   * Always call `live.stop()` when finished — it tears down the
+   * upstream subscriptions. Vue's `onUnmounted` is the canonical
+   * place.
+   *
+   * **Implementation note:** every upstream change triggers a full
+   * re-reduction over the matching records — but since #1341 that record
+   * set is itself maintained per delta rather than re-scanned, so the cost
+   * is O(matches) rather than O(collection). Reducer-level `remove()`
+   * (O(1) per delta for sum/count/avg) remains unwired; see the file
+   * docstring for why folding beats inverting here.
+   */
+  live() {
+    const recompute = () => reduceRecords(this.executeRecords(), this.spec);
+    return gateTerminal(this.gate, "aggregate().live", () => new LiveAggregationImpl(recompute, this.upstreams));
+  }
+};
+function buildLiveReduction(recompute, upstreams) {
+  return new LiveAggregationImpl(recompute, upstreams);
+}
+
+// src/with-lookup/reduce/group-core.ts
+var GROUPBY_WARN_CARDINALITY = 1e4;
+var GROUPBY_MAX_CARDINALITY = 1e5;
+var warnedCardinalityFields = /* @__PURE__ */ new Set();
+function warnCardinalityApproaching(fields, observed) {
+  const key = JSON.stringify([...fields].sort());
+  if (warnedCardinalityFields.has(key)) return;
+  warnedCardinalityFields.add(key);
+  const label = `[${fields.join(", ")}]`;
+  console.warn(
+    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
+  );
+}
+function resetGroupByWarnings() {
+  warnedCardinalityFields.clear();
+}
+function groupFieldLabel(fields) {
+  return fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
+}
+function reduceGroupRow(fields, keyValues, records, spec, reducerKeys) {
+  const state = {};
+  for (const rk of reducerKeys) {
+    state[rk] = spec[rk].init();
+  }
+  for (const record of records) {
+    for (const rk of reducerKeys) {
+      state[rk] = spec[rk].step(state[rk], record);
+    }
+  }
+  const row = {};
+  for (const f of fields) {
+    row[f] = keyValues[f];
+  }
+  for (const rk of reducerKeys) {
+    row[rk] = spec[rk].finalize(state[rk]);
+  }
+  return row;
+}
+
+// src/with-lookup/reduce/incremental-group.ts
+var GroupedMaintainer = class {
+  inner;
+  fields;
+  spec;
+  reducerKeys;
+  fieldLabel;
+  project;
+  buckets = /* @__PURE__ */ new Map();
+  /** Dedup keys in emission (first-seen) order. Recomputed when `orderDirty`. */
+  order = [];
+  orderDirty = true;
+  stale = true;
+  attached = false;
+  patches = 0;
+  rebuilds = 0;
+  bucketsReduced = 0;
+  recordsFolded = 0;
+  constructor(cfg) {
+    this.fields = cfg.fields;
+    this.spec = cfg.spec;
+    this.reducerKeys = Object.keys(cfg.spec);
+    this.fieldLabel = groupFieldLabel(cfg.fields);
+    const project = cfg.source.project;
+    this.project = project ? (record) => project(record) : (record) => record;
+    this.inner = new LiveMaintainer({
+      snapshotEntries: cfg.source.snapshotEntries,
+      lookupById: cfg.source.lookupById,
+      matches: cfg.source.matches,
+      // Grouping reduces the whole match set in candidate order — it never
+      // sorts, offsets, limits or decodes. Same switches the ungrouped
+      // `.aggregate()` maintainer runs with.
+      offset: 0,
+      limit: void 0
+    });
+  }
+  /**
+   * Start accepting deltas. Call in the SAME synchronous turn as the initial
+   * read — `LiveReduction` computes its first value in its constructor and
+   * subscribes immediately after, so attaching there is that turn.
+   */
+  attach() {
+    this.attached = true;
+    this.inner.attach();
+  }
+  /** Stop accepting deltas; every later read rebuilds. */
+  detach() {
+    this.attached = false;
+    this.inner.detach();
+  }
+  /** Force the next read to rebuild. */
+  invalidate() {
+    this.stale = true;
+    this.inner.invalidate();
+  }
+  /** Patch/rebuild counters — the observable difference between the two paths. */
+  stats() {
+    return {
+      patches: this.patches,
+      rebuilds: this.rebuilds,
+      bucketsReduced: this.bucketsReduced,
+      recordsFolded: this.recordsFolded
+    };
+  }
+  /**
+   * Fold one upstream change into the maintained buckets.
+   *
+   * The match-set layer runs first and unconditionally — even when THIS layer
+   * is stale, keeping the inner maintainer current is what makes the rebuild
+   * below cost O(matches) instead of O(collection).
+   */
+  apply(change) {
+    let outcome;
+    try {
+      outcome = this.inner.apply(change);
+    } catch (err) {
+      this.stale = true;
+      throw err;
+    }
+    if (!this.attached || this.stale) return;
+    if (outcome.kind === "rebuilt") {
+      this.stale = true;
+      return;
+    }
+    try {
+      if (outcome.removed) this.leave(outcome.removed);
+      if (outcome.inserted) this.join(outcome.inserted);
+      this.patches++;
+    } catch (err) {
+      this.stale = true;
+      throw err;
+    }
+  }
+  /** The current grouped rows — a fresh array on every call. */
+  rows() {
+    if (!this.attached || this.stale) this.rebuild();
+    if (this.buckets.size >= GROUPBY_WARN_CARDINALITY) {
+      warnCardinalityApproaching(this.fields, this.buckets.size);
+    }
+    if (this.orderDirty) {
+      this.order = [...this.buckets.keys()].sort(
+        (a, b) => this.buckets.get(a).members[0].seq - this.buckets.get(b).members[0].seq
+      );
+      this.orderDirty = false;
+    }
+    const out = [];
+    for (const key of this.order) {
+      const bucket = this.buckets.get(key);
+      if (bucket.dirty) {
+        bucket.row = this.reduce(bucket);
+        bucket.dirty = false;
+      }
+      out.push(bucket.row);
+    }
+    return out;
+  }
+  /**
+   * Rebuild every bucket from the maintained match set. Equivalent to the
+   * eager path by construction: the inner maintainer hands back exactly the
+   * records `executeRecords()` would produce, in exactly that order, and
+   * `join()` below is the same bucketing loop `groupAndReduce` runs.
+   */
+  rebuild() {
+    this.rebuilds++;
+    this.buckets = /* @__PURE__ */ new Map();
+    const entries = this.inner.maintainedEntries();
+    for (const entry of entries) this.join({ seq: entry.seq, record: entry.record });
+    this.orderDirty = true;
+    this.stale = false;
+  }
+  /** A record left the match set, or left one group on its way to another. */
+  leave(delta) {
+    const record = this.project(delta.record);
+    const key = this.dedupKey(record);
+    const bucket = this.buckets.get(key);
+    if (!bucket) {
+      this.stale = true;
+      return;
+    }
+    const at = lowerBoundBySeq(bucket.members, delta.seq);
+    if (bucket.members[at]?.seq !== delta.seq) {
+      this.stale = true;
+      return;
+    }
+    bucket.members.splice(at, 1);
+    if (bucket.members.length === 0) {
+      this.buckets.delete(key);
+      this.orderDirty = true;
+      return;
+    }
+    if (at === 0) this.orderDirty = true;
+    bucket.dirty = true;
+  }
+  /** A record joined the match set, or joined a new group. */
+  join(delta) {
+    const record = this.project(delta.record);
+    const key = this.dedupKey(record);
+    let bucket = this.buckets.get(key);
+    if (bucket === void 0) {
+      if (this.buckets.size >= GROUPBY_MAX_CARDINALITY) {
+        throw new GroupCardinalityError(
+          this.fieldLabel,
+          this.buckets.size + 1,
+          GROUPBY_MAX_CARDINALITY
+        );
+      }
+      bucket = { members: [], row: void 0, dirty: true };
+      this.buckets.set(key, bucket);
+      this.orderDirty = true;
+    }
+    const at = lowerBoundBySeq(bucket.members, delta.seq);
+    bucket.members.splice(at, 0, { seq: delta.seq, record });
+    if (at === 0) this.orderDirty = true;
+    bucket.dirty = true;
+  }
+  reduce(bucket) {
+    const first = bucket.members[0].record;
+    const keyValues = {};
+    for (const f of this.fields) keyValues[f] = readPath(first, f);
+    this.bucketsReduced++;
+    this.recordsFolded += bucket.members.length;
+    return reduceGroupRow(
+      this.fields,
+      keyValues,
+      bucket.members.map((m) => m.record),
+      this.spec,
+      this.reducerKeys
+    );
+  }
+  dedupKey(record) {
+    const keyValues = {};
+    for (const f of this.fields) keyValues[f] = readPath(record, f);
+    return canonicalGroupKey(this.fields, keyValues);
+  }
+};
+function lowerBoundBySeq(members, seq) {
+  let lo = 0;
+  let hi = members.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (members[mid].seq < seq) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+// src/with-lookup/reduce/groupby.ts
+var GroupedQueryBase = class {
+  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver, via, maintenance) {
+    this.executeRecords = executeRecords;
+    this.upstreams = upstreams;
+    this.dictLabelResolver = dictLabelResolver;
+    this.via = via;
+    this.maintenance = maintenance;
+    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
+  }
+  executeRecords;
+  upstreams;
+  dictLabelResolver;
+  via;
+  maintenance;
+  /**
+   * Field set this grouped query buckets on. Stored in declaration
+   * order — the same order is preserved on every result row by
+   * `groupAndReduce`. For the single-field constructor, this is
+   * `[field]`.
+   */
+  fields;
+  /** Apply Via-aware reducer rewriting (e.g. money) when the source declares one. */
+  wrapSpec(spec) {
+    return bindDistinctReducers(this.via ? this.via.wrapReducers(spec) : spec, this.via);
+  }
+};
+var GroupedQuery = class extends GroupedQueryBase {
+  aggregate(specOrBuild) {
+    const spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    return new GroupedReduction(
+      this.executeRecords,
+      this.fields,
+      this.wrapSpec(spec),
+      this.upstreams,
+      this.dictLabelResolver,
+      NO_POST_GROUP,
+      this.maintenance
+    );
+  }
+};
+var GroupedQueryN = class extends GroupedQueryBase {
+  aggregate(specOrBuild) {
+    const spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    return new GroupedReduction(
+      this.executeRecords,
+      this.fields,
+      this.wrapSpec(spec),
+      this.upstreams,
+      this.dictLabelResolver,
+      NO_POST_GROUP,
+      this.maintenance
+    );
+  }
+};
+function groupAndReduce(records, fieldOrFields, spec, moneyFields) {
+  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
+  if (fields.length === 0) {
+    throw new Error(".groupBy() requires at least one field");
+  }
+  if (moneyFields) {
+    const binding = viaBinder("money")({ moneyFields });
+    spec = binding.wrapReducers(spec);
+    spec = bindDistinctReducers(spec, {
+      canonicalizeIndexKey: (f, v) => binding.canonicalizeIndexKey?.(f, v)
+    });
+  }
+  const buckets = /* @__PURE__ */ new Map();
+  const fieldLabel = groupFieldLabel(fields);
+  for (const record of records) {
+    const keyValues = {};
+    for (const f of fields) {
+      keyValues[f] = readPath(record, f);
+    }
+    const dedupKey = canonicalGroupKey(fields, keyValues);
+    let bucket = buckets.get(dedupKey);
+    if (bucket === void 0) {
+      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
+        throw new GroupCardinalityError(
+          fieldLabel,
+          buckets.size + 1,
+          GROUPBY_MAX_CARDINALITY
+        );
+      }
+      bucket = { keyValues, records: [] };
+      buckets.set(dedupKey, bucket);
+    }
+    bucket.records.push(record);
+  }
+  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
+    warnCardinalityApproaching(fields, buckets.size);
+  }
+  const reducerKeys = Object.keys(spec);
+  const out = [];
+  for (const bucket of buckets.values()) {
+    out.push(reduceGroupRow(fields, bucket.keyValues, bucket.records, spec, reducerKeys));
+  }
+  return out;
+}
+var NO_POST_GROUP = { having: [], orderBy: [], limit: void 0 };
+var DECIMAL_NUMERAL = /^[+-]?\d+(\.\d+)?$/;
+function compareReduced(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 === "bigint" && typeof b === "bigint") return a < b ? -1 : a > b ? 1 : 0;
+  if (typeof a === "string" && typeof b === "string") {
+    if (DECIMAL_NUMERAL.test(a) && DECIMAL_NUMERAL.test(b)) {
+      const an = Number(a);
+      const bn = Number(b);
+      if (an !== bn) return an < bn ? -1 : 1;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function applyPostGroup(rows, post) {
+  let out = rows;
+  for (const pred of post.having) {
+    out = out.filter((row) => pred(row));
+  }
+  if (post.orderBy.length > 0) {
+    out = [...out].sort((x, y) => {
+      for (const { key, direction } of post.orderBy) {
+        const cmp = compareReduced(
+          x[key],
+          y[key]
+        );
+        if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+      }
+      return 0;
+    });
+  }
+  if (post.limit !== void 0 && post.limit < out.length) out = out.slice(0, post.limit);
+  return out;
+}
+var GroupedReduction = class _GroupedReduction {
+  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver, post = NO_POST_GROUP, maintenance) {
+    this.executeRecords = executeRecords;
+    this.spec = spec;
+    this.upstreams = upstreams;
+    this.dictLabelResolver = dictLabelResolver;
+    this.post = post;
+    this.maintenance = maintenance;
+    this.fields = typeof fields === "string" ? [fields] : [...fields];
+  }
+  executeRecords;
+  spec;
+  upstreams;
+  dictLabelResolver;
+  post;
+  maintenance;
+  fields;
+  /** Clone with a replaced post-group stage. */
+  withPost(post) {
+    return new _GroupedReduction(
+      this.executeRecords,
+      this.fields,
+      this.spec,
+      this.upstreams,
+      this.dictLabelResolver,
+      post,
+      this.maintenance
+    );
+  }
+  /**
+   * Keep only the reduced rows a predicate accepts — SQL's `HAVING` (#1336).
+   *
+   * ```ts
+   * invoices.query()
+   *   .groupBy('clientId')
+   *   .aggregate({ total: sum('amount') })
+   *   .having(r => (r.total as number) > 10_000)
+   *   .orderBy('total', 'desc')
+   *   .limit(20)
+   *   .run()
+   * ```
+   *
+   * The predicate sees the WHOLE reduced row — group keys (including a
+   * `dateTrunc()`-derived one) and reducer outputs alike — with each value in
+   * its exact reduced form: a money `sum` arrives as its canonical decimal
+   * string (`'10004.00'`), never as a locale-formatted label, so comparing on
+   * it is exact. Successive calls AND.
+   *
+   * ⚠️ Not a memory optimization. See the class docs — the buckets exist
+   * already; `having` only decides what is returned.
+   */
+  having(predicate) {
+    return this.withPost({
+      ...this.post,
+      having: [...this.post.having, predicate]
+    });
+  }
+  /**
+   * Order the REDUCED rows by one of their keys (#1336). Successive calls are
+   * tie-breakers; the sort is stable, so bucket first-seen order breaks a
+   * final tie.
+   *
+   * ⭐ Distinguished from `Query.orderBy()` by POSITION, not by name: this one
+   * exists only after `.aggregate()` and sorts result rows by a reduced key or
+   * a group key; `Query.orderBy()` exists only before `.groupBy()` and sorts
+   * SOURCE RECORDS, which (via `.limit()`) changes which records are grouped
+   * at all. Both may appear in one chain and they do not interfere.
+   */
+  orderBy(key, direction = "asc") {
+    return this.withPost({
+      ...this.post,
+      orderBy: [...this.post.orderBy, { key, direction }]
+    });
+  }
+  /**
+   * Cap the number of reduced rows returned (#1336) — applied AFTER `having`
+   * and `orderBy`, so `.orderBy('total', 'desc').limit(20)` is a top-20.
+   *
+   * A later call replaces an earlier one.
+   */
+  limit(n) {
+    if (!Number.isInteger(n) || n < 0) {
+      throw new Error(`.limit(${n}): a post-group limit must be a non-negative integer.`);
+    }
+    return this.withPost({ ...this.post, limit: n });
+  }
+  /**
+   * Execute the query, group, reduce, and return an array of rows.
+   *
+   * `opts` (query-form MV grouping): when a `locale` + `i18nFields` are
+   * given, the declared group-key `i18nText` fields are resolved to that locale
+   * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+   * instead of a raw `{locale}` map. The MV executor passes the MV's
+   * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+   * unaffected.
+   */
+  run(opts) {
+    let records = this.executeRecords();
+    if (opts?.locale !== void 0 && opts.i18nFields !== void 0) {
+      const groupI18n = {};
+      for (const f of this.fields) {
+        const d = opts.i18nFields[f];
+        if (d !== void 0) groupI18n[f] = d;
+      }
+      if (Object.keys(groupI18n).length > 0) {
+        records = records.map((r) => applyI18nLocale(r, groupI18n, opts.locale, void 0, "mv"));
+      }
+    }
+    return applyPostGroup(groupAndReduce(records, this.fields, this.spec), this.post);
+  }
+  /**
+   * Execute the query, group, reduce, and resolve `<field>Label` for
+   * each result row when the grouping field is a `dictKey` and a
+   * `locale` is provided. Returns `R[]` synchronously when
+   * no locale is specified (identical to `.run()`).
+   *
+   * The `<field>Label` field is appended to each row. Rows whose group
+   * key has no dictionary entry get `<field>Label: undefined`.
+   *
+   * Dict-label resolution is single-field only — multi-key groupings
+   * do not produce a `<field>Label`. The resolver is only attached
+   * by the builder when `fields.length === 1`.
+   */
+  async runAsync(opts) {
+    const rows = applyPostGroup(
+      groupAndReduce(this.executeRecords(), this.fields, this.spec),
+      this.post
+    );
+    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
+    const resolve = this.dictLabelResolver;
+    const locale = opts.locale;
+    const fallback = opts.fallback;
+    const field = this.fields[0];
+    const labelKey = `${field}Label`;
+    return Promise.all(
+      rows.map(async (row) => {
+        const key = row[field];
+        if (typeof key !== "string") return row;
+        const label = await resolve(key, locale, fallback);
+        return { ...row, [labelKey]: label };
+      })
+    );
+  }
+  /**
+   * Build a reactive `LiveReduction<R[]>` that updates whenever any upstream
+   * source notifies of a change. Same error-isolation and idempotent-stop
+   * contract as `Reduction.live()` — the implementation delegates to the same
+   * `LiveAggregationImpl` class by threading a fresh recompute closure through
+   * the existing constructor.
+   *
+   * **Incremental per-group maintenance (#1341, grouped half).** When
+   * `Query.groupBy()` supplied a maintenance seam — a plan
+   * `canMaintainIncrementally()` admits, over a source that can hand back a
+   * snapshot and an id lookup — a change no longer re-runs the pipeline. The
+   * delta patches the match set, then patches the ONE OR TWO buckets it
+   * touches; every other bucket serves the row it already computed. See
+   * `incremental-group.ts` for the correctness argument, including the three
+   * membership transitions (a record changing group, a group emptying, a group
+   * appearing) that a naive per-group patch gets wrong.
+   *
+   * Every other plan, and every notification that arrives without a delta,
+   * re-runs the whole grouping exactly as before. Either way the emitted rows
+   * are identical to `.run()`'s.
+   *
+   * ⚠️ `.run()` is deliberately NOT served from the maintained state: it is a
+   * one-shot terminal that may be called long after a `.live()` was stopped,
+   * and reading the snapshot is the only answer that cannot be stale.
+   *
+   * Always call `live.stop()` when finished.
+   */
+  live() {
+    const maintainer = this.maintenance ? new GroupedMaintainer({
+      source: this.maintenance,
+      fields: this.fields,
+      spec: this.spec
+    }) : void 0;
+    if (!maintainer) {
+      const recompute2 = () => applyPostGroup(
+        groupAndReduce(this.executeRecords(), this.fields, this.spec),
+        this.post
+      );
+      return withStats(buildLiveReduction(recompute2, this.upstreams), void 0);
+    }
+    const recompute = () => applyPostGroup(maintainer.rows(), this.post);
+    const upstreams = this.upstreams.map((upstream) => ({
+      subscribe: (cb) => {
+        maintainer.attach();
+        const unsubscribe = upstream.subscribe((change) => {
+          try {
+            maintainer.apply(change);
+          } catch {
+            maintainer.invalidate();
+          }
+          cb();
+        });
+        return () => {
+          maintainer.detach();
+          unsubscribe();
+        };
+      }
+    }));
+    return withStats(buildLiveReduction(recompute, upstreams), maintainer);
+  }
+};
+function withStats(live, maintainer) {
+  return Object.assign(live, {
+    maintenanceStats: () => maintainer?.stats()
+  });
+}
+
+export {
+  reduceRecords,
+  Reduction,
+  buildLiveReduction,
+  GROUPBY_WARN_CARDINALITY,
+  GROUPBY_MAX_CARDINALITY,
+  resetGroupByWarnings,
+  GroupedMaintainer,
+  GroupedQuery,
+  GroupedQueryN,
+  groupAndReduce,
+  compareReduced,
+  GroupedReduction
+};
+//# sourceMappingURL=chunk-CF5UU4S7.js.map