@noy-db/hub 0.1.0-pre.9 → 0.2.0-pre.2

package/dist/materialized-views/index.cjs

@@ -0,0 +1,837 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/errors.ts
+var NoydbError, ValidationError, GroupCardinalityError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    NoydbError = class extends Error {
+      /** Machine-readable error code. Stable across library versions. */
+      code;
+      constructor(code, message) {
+        super(message);
+        this.name = "NoydbError";
+        this.code = code;
+      }
+    };
+    ValidationError = class extends NoydbError {
+      constructor(message = "Validation error") {
+        super("VALIDATION_ERROR", message);
+        this.name = "ValidationError";
+      }
+    };
+    GroupCardinalityError = class extends NoydbError {
+      /** The field being grouped on. */
+      field;
+      /** Observed number of distinct groups at the moment the cap tripped. */
+      cardinality;
+      /** The cap that was exceeded. */
+      maxGroups;
+      constructor(field, cardinality, maxGroups) {
+        super(
+          "GROUP_CARDINALITY",
+          `.groupBy("${field}") produced ${cardinality} distinct groups, exceeding the ${maxGroups}-group ceiling. This is almost always a query mistake \u2014 grouping on a high-uniqueness field like "id" or "createdAt" produces one bucket per record. Narrow the query with .where() before grouping, or group on a lower-cardinality field (status, category, clientId). If you genuinely need high-cardinality grouping, file an issue with your use case.`
+        );
+        this.name = "GroupCardinalityError";
+        this.field = field;
+        this.cardinality = cardinality;
+        this.maxGroups = maxGroups;
+      }
+    };
+    MaterializedViewCycleError = class extends NoydbError {
+      path;
+      constructor(path) {
+        super(
+          "MATERIALIZED_VIEW_CYCLE",
+          `Materialized-view graph contains a cycle: ${path.join(" \u2192 ")}. Refusing to open vault \u2014 break the cycle before retrying.`
+        );
+        this.name = "MaterializedViewCycleError";
+        this.path = path;
+      }
+    };
+    MaterializedViewSourceUnknownError = class extends NoydbError {
+      mvName;
+      collection;
+      constructor(mvName, collection) {
+        super(
+          "MATERIALIZED_VIEW_SOURCE_UNKNOWN",
+          `Materialized view "${mvName}" references unknown source collection "${collection}". Declare the collection (e.g. via schema or by writing to it once) before registering the MV.`
+        );
+        this.name = "MaterializedViewSourceUnknownError";
+        this.mvName = mvName;
+        this.collection = collection;
+      }
+    };
+    MaterializedViewTooLargeError = class extends NoydbError {
+      mvName;
+      expected;
+      limit;
+      constructor(mvName, expected, limit) {
+        super(
+          "MATERIALIZED_VIEW_TOO_LARGE",
+          `Materialized view "${mvName}" would emit ${expected} rows, exceeding the configured limit of ${limit}. Override via { maxRows: N } on the MV strategy if intentional, or tighten the query's filter/groupBy.`
+        );
+        this.name = "MaterializedViewTooLargeError";
+        this.mvName = mvName;
+        this.expected = expected;
+        this.limit = limit;
+      }
+    };
+    MaterializedViewConfigError = class extends NoydbError {
+      constructor(message) {
+        super(
+          "MATERIALIZED_VIEW_CONFIG",
+          `[noy-db] withMaterializedView: ${message}`
+        );
+        this.name = "MaterializedViewConfigError";
+      }
+    };
+  }
+});
+
+// src/materialized-views/dependency-analyzer.ts
+function analyzeDependencies(query) {
+  const deps = /* @__PURE__ */ new Set();
+  const plan = query._plan();
+  const ctx = query._joinContext();
+  if (ctx?.leftCollection) {
+    deps.add(ctx.leftCollection);
+  }
+  for (const leg of plan.joins) {
+    deps.add(leg.target);
+  }
+  walkClausesForJoins(plan, deps, ctx);
+  return deps;
+}
+function walkClausesForJoins(plan, deps, ctx) {
+  void ctx;
+  for (const clause of plan.clauses) {
+    if (clause.type === "group") {
+    }
+  }
+}
+function summarizeQueryPlan(query) {
+  const plan = query._plan();
+  const ctx = query._joinContext();
+  return JSON.stringify({
+    root: ctx?.leftCollection ?? null,
+    clauses: plan.clauses,
+    orderBy: plan.orderBy,
+    limit: plan.limit ?? null,
+    offset: plan.offset,
+    joins: plan.joins.map((j) => ({ field: j.field, as: j.as, target: j.target, mode: j.mode }))
+  });
+}
+function summarizeUnionPlan(spec) {
+  const arms = (spec.unionSources ?? []).map((s) => s.collection).join(",");
+  const groupBy = Array.isArray(spec.groupBy) ? [...spec.groupBy].sort().join(",") : typeof spec.groupBy === "string" ? spec.groupBy : "";
+  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(",") : "";
+  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})`;
+}
+var init_dependency_analyzer = __esm({
+  "src/materialized-views/dependency-analyzer.ts"() {
+    "use strict";
+  }
+});
+
+// src/materialized-views/query-hash.ts
+async function computeQueryHash(mvName, dependencies, queryPlanSummary) {
+  const canonical = JSON.stringify({
+    mvName,
+    dependencies: [...dependencies].sort(),
+    queryPlanSummary
+  });
+  const bytes = new TextEncoder().encode(canonical);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function canonicalizeQueryPlan(plan) {
+  return JSON.stringify(plan, (_key, value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const sorted = {};
+      for (const k of Object.keys(value).sort()) {
+        sorted[k] = value[k];
+      }
+      return sorted;
+    }
+    return value;
+  });
+}
+var init_query_hash = __esm({
+  "src/materialized-views/query-hash.ts"() {
+    "use strict";
+  }
+});
+
+// src/materialized-views/registry.ts
+function isFieldClauseOnField(clause, field) {
+  return clause.type === "field" && clause.field === field;
+}
+function wrapDbWithPredicates(db, predicates) {
+  const map = /* @__PURE__ */ new Map();
+  for (const [name, decl] of Object.entries(predicates)) {
+    map.set(name, {
+      hash: decl.hash,
+      fn: decl.fn
+    });
+  }
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    collection(name) {
+      const c = db.collection(name);
+      return new Proxy(c, {
+        get(target, prop, receiver) {
+          if (prop === "query") {
+            return (...args) => {
+              const q = target.query(...args);
+              if (q && typeof q._withPredicates === "function") {
+                return q._withPredicates(map);
+              }
+              return q;
+            };
+          }
+          return Reflect.get(target, prop, receiver);
+        }
+      });
+    }
+  };
+}
+function extractPredicateRefs(plan) {
+  const refs = [];
+  const walk = (clauses) => {
+    for (const c of clauses) {
+      if (c.type === "wherePredicate") {
+        refs.push({ name: c.name, predicateHash: c.predicateHash, ctxHash: c.ctxHash });
+      } else if (c.type === "group") {
+        walk(c.clauses);
+      }
+    }
+  };
+  walk(plan.clauses);
+  refs.sort((a, b) => {
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+    if (a.predicateHash !== b.predicateHash) return a.predicateHash < b.predicateHash ? -1 : 1;
+    return a.ctxHash < b.ctxHash ? -1 : a.ctxHash > b.ctxHash ? 1 : 0;
+  });
+  return refs;
+}
+function partitionDisjoint(reg) {
+  const partition = reg.spec.output?.partition;
+  if (partition === void 0) return false;
+  const value = partition.value;
+  for (const c of reg.partitionClauses) {
+    if (c.op === "==" && c.value !== value) return true;
+    if (c.op === "!=" && c.value === value) return true;
+    if (c.op === "in" && Array.isArray(c.value)) {
+      const list = c.value;
+      if (!list.includes(value)) return true;
+    }
+  }
+  return false;
+}
+var MaterializedViewRegistry;
+var init_registry = __esm({
+  "src/materialized-views/registry.ts"() {
+    "use strict";
+    init_errors();
+    init_dependency_analyzer();
+    init_query_hash();
+    MaterializedViewRegistry = class {
+      /** Keyed by `spec.name`. */
+      _byName = /* @__PURE__ */ new Map();
+      /** Keyed by dependency source-collection → MVs that depend on it. */
+      _bySource = /* @__PURE__ */ new Map();
+      /**
+       * Register an MV. Invokes `spec.query()` once at registration time to
+       * read the plan + join context; the resulting `Query<T>` is discarded
+       * after dependency extraction. `vault.collection(...)` must therefore
+       * be functional by the time this runs — typically wired from
+       * `Vault._initMaterializedViews` after collection bootstrap.
+       *
+       * Throws `MaterializedViewSourceUnknownError` if the analyzer
+       * surfaces a dependency the vault doesn't know about (when a
+       * `knownCollections` checker is supplied).
+       */
+      async register(spec, db, options) {
+        const dbForQuery = spec.predicates ? wrapDbWithPredicates(db, spec.predicates) : db;
+        let dependencies;
+        let queryPlanSummary;
+        let qAny = null;
+        let isQuery = false;
+        if (spec.unionSources) {
+          dependencies = new Set(spec.unionSources.map((s) => s.collection));
+          queryPlanSummary = summarizeUnionPlan(spec);
+        } else {
+          const q = spec.query(dbForQuery);
+          qAny = q;
+          isQuery = typeof qAny._plan === "function";
+          if (isQuery) {
+            dependencies = analyzeDependencies(q);
+            queryPlanSummary = summarizeQueryPlan(q);
+            const predicateRefs = extractPredicateRefs(qAny._plan());
+            if (predicateRefs.length > 0) {
+              queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs });
+            }
+            if (spec.sources) for (const s of spec.sources) dependencies.add(s);
+          } else {
+            if (!spec.sources || spec.sources.length === 0) {
+              throw new Error(
+                `withMaterializedView "${spec.name}": query() returned an aggregate (Aggregation or GroupedAggregation) but no \`sources\` field is declared. The dependency analyzer cannot walk through groupBy().aggregate() back to the source \u2014 declare sources: [...] explicitly.`
+              );
+            }
+            dependencies = new Set(spec.sources);
+            queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() });
+          }
+        }
+        if (options?.knownCollections) {
+          for (const dep of dependencies) {
+            if (!options.knownCollections(dep)) {
+              throw new MaterializedViewSourceUnknownError(spec.name, dep);
+            }
+          }
+        }
+        const outputCollection = spec.output?.collection ?? spec.name;
+        const queryHash = await computeQueryHash(spec.name, dependencies, queryPlanSummary);
+        const partitionClauses = [];
+        const partitionField = spec.output?.partition?.field;
+        if (partitionField !== void 0 && isQuery) {
+          const plan = qAny._plan();
+          for (const clause of plan.clauses) {
+            if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause);
+          }
+        }
+        const reg = { spec, outputCollection, dependencies, queryHash, partitionClauses };
+        this._byName.set(spec.name, reg);
+        for (const dep of dependencies) {
+          const arr = this._bySource.get(dep);
+          if (arr) arr.push(reg);
+          else this._bySource.set(dep, [reg]);
+        }
+      }
+      /** All MVs that depend on `source`, in registration order. */
+      mvsForSource(source) {
+        return this._bySource.get(source) ?? [];
+      }
+      /** Single MV by name, or `undefined`. */
+      byName(name) {
+        return this._byName.get(name);
+      }
+      /** Iterate over every registered MV. */
+      all() {
+        return [...this._byName.values()];
+      }
+      /**
+       * Cycle detection over the combined derivation + MV graph. Edges:
+       *   - Derivation: derivation.source → output.collection (each output)
+       *   - MV: every dep in MV.dependencies → MV.outputCollection
+       *
+       * Throws `MaterializedViewCycleError` if the cycle's terminal node
+       * is an MV output collection; otherwise (a pure-derivation cycle)
+       * the caller's `DerivationRegistry.validate()` will surface
+       * `DerivationCycleError` separately at vault open.
+       *
+       * Call AFTER all `register()` calls complete.
+       */
+      validate(derivationRegistry) {
+        const visited = /* @__PURE__ */ new Set();
+        const stack = [];
+        const mvOutputs = /* @__PURE__ */ new Set();
+        for (const reg of this._byName.values()) mvOutputs.add(reg.outputCollection);
+        const edges = /* @__PURE__ */ new Map();
+        for (const reg of this._byName.values()) {
+          for (const dep of reg.dependencies) {
+            if (dep === reg.outputCollection && partitionDisjoint(reg)) continue;
+            const arr = edges.get(dep);
+            if (arr) arr.push(reg.outputCollection);
+            else edges.set(dep, [reg.outputCollection]);
+          }
+        }
+        if (derivationRegistry) {
+          for (const reg of this._byName.values()) {
+            void reg;
+          }
+          const sourcesToScan = /* @__PURE__ */ new Set();
+          for (const reg of this._byName.values()) {
+            for (const dep of reg.dependencies) sourcesToScan.add(dep);
+            sourcesToScan.add(reg.outputCollection);
+          }
+          for (const src of sourcesToScan) {
+            const strategies = derivationRegistry.strategiesForSource(src);
+            if (strategies.length === 0) continue;
+            for (const s of strategies) {
+              for (const key of Object.keys(s.spec.outputs)) {
+                const o = s.spec.outputs[key];
+                if (!o) continue;
+                const arr = edges.get(src);
+                if (arr) arr.push(o.collection);
+                else edges.set(src, [o.collection]);
+              }
+            }
+          }
+        }
+        const visit = (node) => {
+          if (stack.includes(node)) {
+            const cycle = stack.slice(stack.indexOf(node)).concat(node);
+            if (cycle.some((n) => mvOutputs.has(n))) {
+              throw new MaterializedViewCycleError(cycle);
+            }
+            return;
+          }
+          if (visited.has(node)) return;
+          stack.push(node);
+          const outs = edges.get(node);
+          if (outs) for (const o of outs) visit(o);
+          stack.pop();
+          visited.add(node);
+        };
+        for (const node of edges.keys()) visit(node);
+      }
+    };
+  }
+});
+
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+var init_predicate = __esm({
+  "src/query/predicate.ts"() {
+    "use strict";
+  }
+});
+
+// src/aggregate/canonical-key.ts
+function canonicalGroupKey(fields, row) {
+  const sorted = [...fields].sort();
+  const parts = [];
+  for (const name of sorted) {
+    const v = row[name];
+    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
+    parts.push(`${name}=${serialised}`);
+  }
+  return parts.join("|");
+}
+var init_canonical_key = __esm({
+  "src/aggregate/canonical-key.ts"() {
+    "use strict";
+  }
+});
+
+// src/aggregate/groupby.ts
+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 groupAndReduce(records, fieldOrFields, spec) {
+  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
+  if (fields.length === 0) {
+    throw new Error(".groupBy() requires at least one field");
+  }
+  const buckets = /* @__PURE__ */ new Map();
+  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
+  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()) {
+    const state = {};
+    for (const rk of reducerKeys) {
+      state[rk] = spec[rk].init();
+    }
+    for (const record of bucket.records) {
+      for (const rk of reducerKeys) {
+        state[rk] = spec[rk].step(state[rk], record);
+      }
+    }
+    const row = {};
+    for (const f of fields) {
+      row[f] = bucket.keyValues[f];
+    }
+    for (const rk of reducerKeys) {
+      row[rk] = spec[rk].finalize(state[rk]);
+    }
+    out.push(row);
+  }
+  return out;
+}
+var GROUPBY_WARN_CARDINALITY, GROUPBY_MAX_CARDINALITY, warnedCardinalityFields;
+var init_groupby = __esm({
+  "src/aggregate/groupby.ts"() {
+    "use strict";
+    init_predicate();
+    init_canonical_key();
+    init_errors();
+    GROUPBY_WARN_CARDINALITY = 1e4;
+    GROUPBY_MAX_CARDINALITY = 1e5;
+    warnedCardinalityFields = /* @__PURE__ */ new Set();
+  }
+});
+
+// src/materialized-views/executor.ts
+var executor_exports = {};
+__export(executor_exports, {
+  MaterializedViewExecutor: () => MaterializedViewExecutor
+});
+async function materializeQueryResult(q, mvName) {
+  if (typeof q?.toArray === "function") {
+    return await q.toArray();
+  }
+  if (typeof q?.run === "function") {
+    const result = await Promise.resolve(q.run());
+    if (Array.isArray(result)) {
+      return result;
+    }
+    return [result];
+  }
+  throw new Error(
+    `MV "${mvName}": query() must return a Query<T>, Aggregation, or GroupedAggregation. Got something without a .toArray() or .run() terminal.`
+  );
+}
+async function materializeUnionResult(spec, db) {
+  const unified = [];
+  for (const arm of spec.unionSources) {
+    const coll = db.collection(arm.collection);
+    const sourceRows = coll.query().toArray();
+    for (const r of sourceRows) {
+      unified.push(arm.map(r));
+    }
+  }
+  if (!spec.groupBy) return unified;
+  const groupFields = typeof spec.groupBy === "string" ? [spec.groupBy] : spec.groupBy;
+  if (!spec.aggregate) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const row of unified) {
+      const k = canonicalGroupKey(groupFields, row);
+      if (!seen.has(k)) seen.set(k, row);
+    }
+    return [...seen.values()];
+  }
+  return groupAndReduce(unified, groupFields, spec.aggregate);
+}
+async function listOutputIds(outputColl) {
+  const cAny = outputColl;
+  const adapter = cAny.adapter;
+  const vault = cAny.vault;
+  const name = cAny.name;
+  if (typeof adapter?.list !== "function") return [];
+  try {
+    const ids = await adapter.list(vault, name);
+    return [...ids];
+  } catch {
+    return [];
+  }
+}
+var DEFAULT_MAX_ROWS, MaterializedViewExecutor;
+var init_executor = __esm({
+  "src/materialized-views/executor.ts"() {
+    "use strict";
+    init_errors();
+    init_registry();
+    init_groupby();
+    init_canonical_key();
+    DEFAULT_MAX_ROWS = 1e5;
+    MaterializedViewExecutor = {
+      async refresh(reg, accessor) {
+        const spec = reg.spec;
+        const outputColl = accessor.getCollection(reg.outputCollection);
+        const maxRows = spec.maxRows ?? DEFAULT_MAX_ROWS;
+        const onEmpty = spec.onEmpty ?? "delete";
+        const strict = spec.strict ?? false;
+        const baseCtx = accessor.getQueryContext();
+        const ctxForQuery = spec.predicates ? wrapDbWithPredicates(baseCtx, spec.predicates) : baseCtx;
+        let rows;
+        if (spec.unionSources) {
+          rows = await materializeUnionResult(spec, ctxForQuery);
+        } else {
+          const q = spec.query(ctxForQuery);
+          rows = await materializeQueryResult(q, spec.name);
+        }
+        if (rows.length > maxRows) {
+          throw new MaterializedViewTooLargeError(spec.name, rows.length, maxRows);
+        }
+        const txCtx = accessor.getActiveTxContext();
+        const adapter = outputColl.adapter;
+        const vaultName = outputColl.vault;
+        const newIds = /* @__PURE__ */ new Set();
+        const enrichedRows = [];
+        for (const row of rows) {
+          const id = spec.rowKey(row);
+          newIds.add(id);
+          const meta = {
+            mvName: spec.name,
+            queryHash: reg.queryHash,
+            sourceVersions: {},
+            materializedAt: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          enrichedRows.push({ id, record: { ...row, _materializedFrom: meta } });
+        }
+        let written = 0;
+        let failed = 0;
+        for (const { id, record } of enrichedRows) {
+          try {
+            if (txCtx !== null) {
+              const prior = await adapter.get(vaultName, reg.outputCollection, id);
+              txCtx._executed.push({
+                op: { type: "put", vaultName, collectionName: reg.outputCollection, id },
+                priorEnvelope: prior
+              });
+            }
+            await outputColl.put(id, record);
+            written++;
+          } catch (err) {
+            failed++;
+            if (strict) throw err;
+            console.warn(`[mv] "${spec.name}" row write failed:`, err);
+          }
+        }
+        let deleted = 0;
+        if (onEmpty === "delete") {
+          const priorIds = await listOutputIds(outputColl);
+          for (const priorId of priorIds) {
+            if (newIds.has(priorId)) continue;
+            try {
+              const outAny = outputColl;
+              if (typeof outAny._internalDelete === "function") {
+                await outAny._internalDelete(priorId, txCtx);
+                deleted++;
+              } else {
+                await outputColl.delete(priorId);
+                deleted++;
+              }
+            } catch (err) {
+              failed++;
+              if (strict) throw err;
+              console.warn(`[mv] "${spec.name}" tombstone failed for id="${priorId}":`, err);
+            }
+          }
+        }
+        return { written, deleted, failed };
+      }
+    };
+  }
+});
+
+// src/materialized-views/index.ts
+var materialized_views_exports = {};
+__export(materialized_views_exports, {
+  MaterializedViewConfigError: () => MaterializedViewConfigError,
+  MaterializedViewCycleError: () => MaterializedViewCycleError,
+  MaterializedViewExecutor: () => MaterializedViewExecutor,
+  MaterializedViewRegistry: () => MaterializedViewRegistry,
+  MaterializedViewSourceUnknownError: () => MaterializedViewSourceUnknownError,
+  MaterializedViewTooLargeError: () => MaterializedViewTooLargeError,
+  analyzeDependencies: () => analyzeDependencies,
+  canonicalizeQueryPlan: () => canonicalizeQueryPlan,
+  clearMVStale: () => clearMVStale,
+  computeQueryHash: () => computeQueryHash,
+  isMVStale: () => isMVStale,
+  markMVStale: () => markMVStale,
+  resolveStaleMVOnRead: () => resolveStaleMVOnRead,
+  summarizeQueryPlan: () => summarizeQueryPlan,
+  withMaterializedView: () => withMaterializedView
+});
+module.exports = __toCommonJS(materialized_views_exports);
+
+// src/materialized-views/with-materialized-view.ts
+init_errors();
+function withMaterializedView(spec) {
+  if (!spec.name || spec.name.length === 0) {
+    throw new ValidationError("withMaterializedView: name is required");
+  }
+  if (spec.query && spec.unionSources) {
+    throw new MaterializedViewConfigError(
+      "query and unionSources are mutually exclusive \u2014 pick one"
+    );
+  }
+  if (!spec.query && !spec.unionSources) {
+    throw new MaterializedViewConfigError(
+      "strategy must declare either query or unionSources"
+    );
+  }
+  if (spec.query !== void 0 && typeof spec.query !== "function") {
+    throw new ValidationError("withMaterializedView: query must be a function returning a Query<T>");
+  }
+  if (spec.unionSources) {
+    if (spec.unionSources.length < 2) {
+      throw new MaterializedViewConfigError(
+        "unionSources requires at least 2 source collections"
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const s of spec.unionSources) {
+      if (typeof s?.collection !== "string" || s.collection.length === 0) {
+        throw new MaterializedViewConfigError(
+          "each unionSources entry must declare a non-empty `collection` string"
+        );
+      }
+      if (typeof s.map !== "function") {
+        throw new MaterializedViewConfigError(
+          `unionSources entry for "${s.collection}" is missing a \`map\` function`
+        );
+      }
+      if (seen.has(s.collection)) {
+        throw new MaterializedViewConfigError(
+          `unionSources must reference distinct collections (duplicate: "${s.collection}")`
+        );
+      }
+      seen.add(s.collection);
+    }
+    if (Array.isArray(spec.groupBy) && spec.groupBy.length === 0) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": groupBy must not be an empty array \u2014 omit it or provide at least one field name`
+      );
+    }
+    if (spec.aggregate && !spec.groupBy) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": UNION strategy with aggregate requires groupBy \u2014 use groupBy to declare the bucketing keys, or remove aggregate for a pure dedup MV`
+      );
+    }
+    if (spec.predicates) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": predicates are not supported on UNION strategies \u2014 UNION mode does not use a Query<T> chain, so .wherePredicate() cannot fire. Use the query() form, or open an issue if per-arm predicates are needed`
+      );
+    }
+  }
+  if (typeof spec.rowKey !== "function") {
+    throw new ValidationError("withMaterializedView: rowKey is required (no default; see spec \xA7 Type surface)");
+  }
+  if (spec.refresh !== "eager" && spec.refresh !== "lazy" && spec.refresh !== "manual") {
+    throw new ValidationError(
+      `withMaterializedView: refresh must be 'eager' | 'lazy' | 'manual', got "${String(spec.refresh)}"`
+    );
+  }
+  return {
+    __noydb_strategy: "materialized-view",
+    spec
+  };
+}
+
+// src/materialized-views/index.ts
+init_registry();
+init_executor();
+init_dependency_analyzer();
+init_query_hash();
+
+// src/materialized-views/stale.ts
+var _staleByRegistry = /* @__PURE__ */ new WeakMap();
+function markMVStale(registry, mvName) {
+  let set = _staleByRegistry.get(registry);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    _staleByRegistry.set(registry, set);
+  }
+  set.add(mvName);
+}
+function isMVStale(registry, mvName) {
+  return _staleByRegistry.get(registry)?.has(mvName) ?? false;
+}
+async function resolveStaleMVOnRead(accessor, outputCollection) {
+  const registry = accessor.registry();
+  const pending = _staleByRegistry.get(registry);
+  if (!pending || pending.size === 0) return;
+  const candidates = [];
+  for (const mv of registry.all()) {
+    if (mv.outputCollection !== outputCollection) continue;
+    if (!pending.has(mv.spec.name)) continue;
+    candidates.push(mv.spec.name);
+  }
+  if (candidates.length === 0) return;
+  let executor = null;
+  for (const name of candidates) {
+    const reg = registry.byName(name);
+    if (!reg) {
+      pending.delete(name);
+      continue;
+    }
+    if (executor === null) {
+      ({ MaterializedViewExecutor: executor } = await Promise.resolve().then(() => (init_executor(), executor_exports)));
+    }
+    await executor.refresh(reg, {
+      getCollection: (n) => accessor.getCollection(n),
+      getActiveTxContext: () => accessor.getActiveTxContext(),
+      getQueryContext: () => accessor.getQueryContext()
+    });
+    pending.delete(name);
+  }
+}
+function clearMVStale(registry, mvName) {
+  _staleByRegistry.get(registry)?.delete(mvName);
+}
+
+// src/materialized-views/index.ts
+init_errors();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MaterializedViewConfigError,
+  MaterializedViewCycleError,
+  MaterializedViewExecutor,
+  MaterializedViewRegistry,
+  MaterializedViewSourceUnknownError,
+  MaterializedViewTooLargeError,
+  analyzeDependencies,
+  canonicalizeQueryPlan,
+  clearMVStale,
+  computeQueryHash,
+  isMVStale,
+  markMVStale,
+  resolveStaleMVOnRead,
+  summarizeQueryPlan,
+  withMaterializedView
+});
+//# sourceMappingURL=index.cjs.map