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

package/dist/materialized-views/index.d.ts

@@ -0,0 +1,183 @@
+export { w as withMaterializedView } from '../with-materialized-view-DaKR-N6J.js';
+import { aH as Collection, at as TxContext, ba as MVQueryContext, bb as RegisteredMV, bc as MaterializedViewRegistry } from '../types-DW9RGSSs.js';
+export { bd as MaterializedFromMeta, be as MaterializedViewOutput, aE as MaterializedViewStrategy, aF as MaterializedViewStrategyHandle, bf as UnionSource } from '../types-DW9RGSSs.js';
+import { Q as Query } from '../index-CNwA-B6-.js';
+export { m as MaterializedViewConfigError, n as MaterializedViewCycleError, o as MaterializedViewSourceUnknownError, p as MaterializedViewTooLargeError } from '../index-CNwA-B6-.js';
+import '../lazy-builder-Rpd-V3jP.js';
+import '../predicate-Dnu81tsS.js';
+import '../strategy-DSTrsZ8t.js';
+import '../strategy-BSxFXGzb.js';
+
+/**
+ * Accessor shape passed in from the owning Vault. Mirrors v1's
+ * `DerivationStaleAccessor` — provides the per-collection resolver
+ * and the active TxContext so refresh writes/tombstones register on
+ * `_executed` for #133-style rollback symmetry.
+ */
+interface MVExecutorAccessor {
+    getCollection(name: string): Collection<any>;
+    getActiveTxContext(): TxContext | null;
+    /**
+     * Vault-shaped accessor passed to the MV's `query()` callback at
+     * each refresh. Same instance the registry used at registration
+     * time; threading through the executor lets the refresh path
+     * re-evaluate the closure against the live vault state.
+     */
+    getQueryContext(): MVQueryContext;
+}
+interface RefreshResult {
+    /** Rows newly written / overwritten. */
+    written: number;
+    /** Rows tombstoned via `_internalDelete` (only when `onEmpty: 'delete'`). */
+    deleted: number;
+    /** Failed row writes (non-strict mode). */
+    failed: number;
+}
+/**
+ * Run an MV's `query()` and write the result rows to the output
+ * collection. Same-DEK encryption: routes through the standard
+ * `Collection.put` pipeline, so the output collection's DEK is what
+ * gets used (matches the v2 spec's "same DEK as the left-most source"
+ * invariant — `Collection.put` looks up the DEK by collection name,
+ * and the output collection IS the MV's owned collection).
+ *
+ * Stamps `_materializedFrom` onto every emitted row.
+ *
+ * **Tombstoning** (#152): when `spec.onEmpty: 'delete'` (default), rows
+ * that existed in a prior refresh but no longer appear in the new
+ * materialized result are deleted via `Collection._internalDelete` —
+ * the housekeeping bypass primitive added in PR #148 prevents user
+ * `onDelete` guards on the output collection from firing on these
+ * system-internal deletes. `onEmpty: 'keep'` opts out (rows from
+ * prior refreshes linger even when the new result lacks them).
+ *
+ * **Cost ceiling** (#152): if the materialized row count exceeds
+ * `spec.maxRows` (default 100k), throws `MaterializedViewTooLargeError`
+ * before any writes hit the store — so strict-mode rollback is
+ * clean.
+ *
+ * **Strict mode** (#152): `spec.strict === true` re-throws on any
+ * row-write failure; the active TxContext registration means the
+ * source-write rolls back atomically via `revertExecuted` (#133).
+ *
+ * @internal
+ */
+declare const MaterializedViewExecutor: {
+    refresh(reg: RegisteredMV, accessor: MVExecutorAccessor): Promise<RefreshResult>;
+};
+
+/**
+ * Walks a `Query<T>` plan and returns the set of source collection
+ * names that any source-write should trigger a refresh on.
+ *
+ * Foundation sub-issue (#150) handles:
+ *   - root collection (the one the query was built from)
+ *   - FK join targets (`.join(field, { as })`)
+ *
+ * Deferred to later sub-issues:
+ *   - `.crossJoin()` — v3 cross-join spec (separate primitive)
+ *   - `.wherePredicate(name)` — v2 predicate primitive, sub-issue #153
+ *   - Overlay-name expansion to {base, overlay} — sub-issue #154
+ *
+ * The set is materialized at MV registration time. The MV registry
+ * uses it to (a) dispatch `onSourceWrite` only to MVs that actually
+ * care, and (b) contribute edges to the shared cycle-detection graph.
+ */
+declare function analyzeDependencies(query: Query<any>): Set<string>;
+/**
+ * Convenience: produce a stable string summary of the query plan
+ * suitable for `queryHash` derivation. Captures everything the
+ * dependency analyzer reads + the where/orderBy/limit/offset
+ * structure that affects materialized rows.
+ *
+ * `joinContext` is intentionally NOT included — the join-resolution
+ * function references would defeat hash determinism. The set of join
+ * TARGETS (collection names) IS included via the plan.joins legs.
+ */
+declare function summarizeQueryPlan(query: Query<any>): string;
+
+/**
+ * Deterministic hash of a materialized view strategy's "shape": MV
+ * name + canonical query-plan summary + sorted dependency-set.
+ *
+ * Used to detect strategy drift: a row whose `_materializedFrom.queryHash`
+ * doesn't match the current strategy is considered stale.
+ *
+ * Web Crypto SHA-256 — no extra deps. Mirrors the v1
+ * `computeStrategyHash` pattern.
+ */
+declare function computeQueryHash(mvName: string, 
+/**
+ * Source-collection set the query depends on. Sorted before
+ * canonicalization so set iteration order doesn't affect the hash.
+ */
+dependencies: ReadonlySet<string>, 
+/**
+ * Stringified query-plan summary. The caller produces this from the
+ * `Query<T>` builder — concretely: a JSON serialization of clauses +
+ * orderBy + limit + offset + joins. Function bodies inside
+ * `wherePredicate` are NOT included here (those carry their own
+ * `predicateHash` to be folded in by a later sub-issue).
+ */
+queryPlanSummary: string): Promise<string>;
+/**
+ * Canonicalize a query plan for hashing. Walks the plan structure
+ * with sorted keys so insertion order doesn't perturb the result.
+ * Lives here rather than in `query/builder.ts` to keep that module
+ * stable across MV-specific evolutions.
+ *
+ * @internal exported for testing
+ */
+declare function canonicalizeQueryPlan(plan: unknown): string;
+
+/**
+ * Accessor shape passed in from the owning Vault. Provides the
+ * registry (used as a stable WeakMap key + to look up MVs by output
+ * collection) and the runtime context the lazy refresh needs.
+ * Mirrors v1's `DerivationStaleAccessor`.
+ */
+interface MVStaleAccessor {
+    registry(): MaterializedViewRegistry;
+    getCollection(name: string): Collection<any>;
+    getActiveTxContext(): TxContext | null;
+    getQueryContext(): MVQueryContext;
+}
+/**
+ * Mark an MV as stale. Called from `Collection.dispatchMaterializedViews`
+ * when a source-write fires for a `refresh: 'lazy'` MV.
+ *
+ * @internal
+ */
+declare function markMVStale(registry: MaterializedViewRegistry, mvName: string): void;
+/**
+ * Test-only: check whether a given MV name is currently flagged stale
+ * against a registry. Exported so the regression suite can pin the
+ * stale-bit lifecycle without touching the internal `WeakMap`.
+ *
+ * @internal
+ */
+declare function isMVStale(registry: MaterializedViewRegistry, mvName: string): boolean;
+/**
+ * Called from `Collection.get` (and any reader that materializes the
+ * MV's output collection). If any MV producing `outputCollection` is
+ * flagged stale, runs the executor against the live source state
+ * before returning. No-op when there is no pending work — keeps the
+ * read fast path negligible.
+ *
+ * Dynamic-imports the executor only when a stale flag actually fires
+ * (the floor-bundle isolation pattern v1 derivations established in
+ * #130).
+ */
+declare function resolveStaleMVOnRead(accessor: MVStaleAccessor, outputCollection: string): Promise<void>;
+/**
+ * Drop every stale flag for a registry. Used after a manual
+ * `vault.refreshView(name)` runs the executor explicitly — the
+ * post-refresh state matches the registered strategies, so
+ * lingering stale bits would force a redundant refresh on the next
+ * read.
+ *
+ * @internal
+ */
+declare function clearMVStale(registry: MaterializedViewRegistry, mvName: string): void;
+
+export { type MVExecutorAccessor, type MVStaleAccessor, MaterializedViewExecutor, MaterializedViewRegistry, type RefreshResult, RegisteredMV, analyzeDependencies, canonicalizeQueryPlan, clearMVStale, computeQueryHash, isMVStale, markMVStale, resolveStaleMVOnRead, summarizeQueryPlan };

package/dist/materialized-views/index.js

@@ -0,0 +1,45 @@
+import {
+  withMaterializedView
+} from "../chunk-RD5LYKD6.js";
+import {
+  MaterializedViewExecutor
+} from "../chunk-SIZWEV2Y.js";
+import {
+  MaterializedViewRegistry,
+  analyzeDependencies,
+  canonicalizeQueryPlan,
+  computeQueryHash,
+  summarizeQueryPlan
+} from "../chunk-DPMFBCV6.js";
+import {
+  clearMVStale,
+  isMVStale,
+  markMVStale,
+  resolveStaleMVOnRead
+} from "../chunk-UZXLQCHP.js";
+import "../chunk-XGSOTWYX.js";
+import "../chunk-MRIBLZL3.js";
+import {
+  MaterializedViewConfigError,
+  MaterializedViewCycleError,
+  MaterializedViewSourceUnknownError,
+  MaterializedViewTooLargeError
+} from "../chunk-ADQ5MQ54.js";
+export {
+  MaterializedViewConfigError,
+  MaterializedViewCycleError,
+  MaterializedViewExecutor,
+  MaterializedViewRegistry,
+  MaterializedViewSourceUnknownError,
+  MaterializedViewTooLargeError,
+  analyzeDependencies,
+  canonicalizeQueryPlan,
+  clearMVStale,
+  computeQueryHash,
+  isMVStale,
+  markMVStale,
+  resolveStaleMVOnRead,
+  summarizeQueryPlan,
+  withMaterializedView
+};
+//# sourceMappingURL=index.js.map

package/dist/materialized-views/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/overlay-views/index.cjs

@@ -0,0 +1,359 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/overlay-views/index.ts
+var overlay_views_exports = {};
+__export(overlay_views_exports, {
+  OverlayBaseIsVirtualError: () => OverlayBaseIsVirtualError,
+  OverlayCollectionUnavailableError: () => OverlayCollectionUnavailableError,
+  OverlayIdMismatchError: () => OverlayIdMismatchError,
+  OverlayNameCollisionError: () => OverlayNameCollisionError,
+  OverlayedCollection: () => OverlayedCollection,
+  OverlayedViewRegistry: () => OverlayedViewRegistry,
+  withOverlayedView: () => withOverlayedView
+});
+module.exports = __toCommonJS(overlay_views_exports);
+
+// src/errors.ts
+var NoydbError = class extends Error {
+  /** Machine-readable error code. Stable across library versions. */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NoydbError";
+    this.code = code;
+  }
+};
+var ValidationError = class extends NoydbError {
+  constructor(message = "Validation error") {
+    super("VALIDATION_ERROR", message);
+    this.name = "ValidationError";
+  }
+};
+var OverlayBaseIsVirtualError = class extends NoydbError {
+  overlayName;
+  base;
+  constructor(overlayName, base) {
+    super(
+      "OVERLAY_BASE_IS_VIRTUAL",
+      `withOverlayedView "${overlayName}": base "${base}" is another overlay's virtual name. Multi-overlay stacking is a v3 feature; base must reference a concrete collection (a real source or an MV output).`
+    );
+    this.name = "OverlayBaseIsVirtualError";
+    this.overlayName = overlayName;
+    this.base = base;
+  }
+};
+var OverlayCollectionUnavailableError = class extends NoydbError {
+  overlayName;
+  overlay;
+  constructor(overlayName, overlay) {
+    super(
+      "OVERLAY_COLLECTION_UNAVAILABLE",
+      `withOverlayedView "${overlayName}": overlay collection "${overlay}" is unavailable. It must be a real vault-known collection that is NOT itself an MV output collection.`
+    );
+    this.name = "OverlayCollectionUnavailableError";
+    this.overlayName = overlayName;
+    this.overlay = overlay;
+  }
+};
+var OverlayNameCollisionError = class extends NoydbError {
+  overlayName;
+  constructor(overlayName) {
+    super(
+      "OVERLAY_NAME_COLLISION",
+      `withOverlayedView "${overlayName}": virtual name collides with an MV output or a concrete source collection. Pick a unique name for the virtual collection.`
+    );
+    this.name = "OverlayNameCollisionError";
+    this.overlayName = overlayName;
+  }
+};
+var OverlayIdMismatchError = class extends NoydbError {
+  actual;
+  expected;
+  constructor(actual, expected) {
+    super(
+      "OVERLAY_ID_MISMATCH",
+      `Overlay put(id, record): id "${actual}" does not match the base MV's rowKey(record) \u2192 "${expected}". Pass the row directly via .put(record) to derive the id, or fix the id to match the base MV's rowKey output.`
+    );
+    this.name = "OverlayIdMismatchError";
+    this.actual = actual;
+    this.expected = expected;
+  }
+};
+
+// src/overlay-views/with-overlayed-view.ts
+function withOverlayedView(spec) {
+  if (!spec.name || spec.name.length === 0) {
+    throw new ValidationError("withOverlayedView: name is required");
+  }
+  if (!spec.base || spec.base.length === 0) {
+    throw new ValidationError("withOverlayedView: base is required");
+  }
+  if (!spec.overlay || spec.overlay.length === 0) {
+    throw new ValidationError("withOverlayedView: overlay is required");
+  }
+  if (spec.base === spec.overlay) {
+    throw new ValidationError("withOverlayedView: base and overlay must be different collections");
+  }
+  if (spec.base === spec.name || spec.overlay === spec.name) {
+    throw new ValidationError(
+      "withOverlayedView: virtual name must differ from both base and overlay collection names"
+    );
+  }
+  if (!spec.shadowField || spec.shadowField.length === 0) {
+    throw new ValidationError("withOverlayedView: shadowField is required");
+  }
+  return {
+    __noydb_strategy: "overlayed-view",
+    spec
+  };
+}
+
+// src/overlay-views/registry.ts
+var OverlayedViewRegistry = class {
+  _byName = /* @__PURE__ */ new Map();
+  /**
+   * Register an overlay. Validates name uniqueness, base concreteness,
+   * and overlay availability AGAINST the MV registry — overlays
+   * declared without the MV registry context skip cross-registry
+   * checks but still validate self-consistency.
+   */
+  register(spec, options) {
+    const { isOverlayName, isMVOutput, isKnownCollection } = options;
+    if (isMVOutput?.(spec.name) || isOverlayName?.(spec.name)) {
+      throw new OverlayNameCollisionError(spec.name);
+    }
+    if (isOverlayName?.(spec.base)) {
+      throw new OverlayBaseIsVirtualError(spec.name, spec.base);
+    }
+    if (isMVOutput?.(spec.overlay)) {
+      throw new OverlayCollectionUnavailableError(spec.name, spec.overlay);
+    }
+    void isKnownCollection;
+    this._byName.set(spec.name, spec);
+  }
+  byName(name) {
+    return this._byName.get(name);
+  }
+  /** All overlay virtual names. */
+  names() {
+    return new Set(this._byName.keys());
+  }
+  isOverlay(name) {
+    return this._byName.has(name);
+  }
+  /**
+   * Resolve the `rowKey` function for an overlay's base MV. Returns
+   * `undefined` if the base isn't an MV (raw source collection) or
+   * if the MV registry isn't supplied. Used by the virtual-collection
+   * proxy to derive ids from `put(record)` calls.
+   */
+  resolveBaseRowKey(name, mvRegistry) {
+    const spec = this._byName.get(name);
+    if (!spec || !mvRegistry) return void 0;
+    for (const reg of mvRegistry.all()) {
+      if (reg.outputCollection === spec.base || reg.spec.name === spec.base) {
+        return (row) => reg.spec.rowKey(row);
+      }
+    }
+    return void 0;
+  }
+};
+
+// src/overlay-views/virtual-collection.ts
+var OverlayedCollection = class {
+  constructor(spec, baseCollection, overlayCollection, baseRowKey) {
+    this.spec = spec;
+    this.baseCollection = baseCollection;
+    this.overlayCollection = overlayCollection;
+    this.baseRowKey = baseRowKey;
+  }
+  spec;
+  baseCollection;
+  overlayCollection;
+  baseRowKey;
+  /**
+   * Convenience accessors for advanced callers that need to bypass the
+   * virtual layer (bulk imports, direct overlay queries). Mirrors the
+   * spec's "direct writes to the underlying overlay collection skip
+   * the validation" escape hatch.
+   */
+  overlay = {
+    rowKey: (row) => {
+      if (!this.baseRowKey) {
+        throw new Error(
+          `Overlay "${this.spec.name}": base "${this.spec.base}" is not an MV \u2014 cannot auto-derive id from the row. Use \`put(id, record)\` instead.`
+        );
+      }
+      return this.baseRowKey(row);
+    }
+  };
+  /** Get the merged row by id. */
+  async get(id) {
+    const overlayRow = await this.overlayCollection.get(id);
+    if (overlayRow !== null && this.shadowPredicateApplies(overlayRow)) {
+      return overlayRow;
+    }
+    const baseRow = await this.baseCollection.get(id);
+    if (baseRow !== null) return baseRow;
+    return null;
+  }
+  /** List union of base + overlay ids, applying the merge per row. */
+  async list() {
+    const baseRows = await this.baseCollection.list();
+    const overlayRows = await this.overlayCollection.list();
+    const merged = /* @__PURE__ */ new Map();
+    const idOf = (row) => {
+      if (this.baseRowKey) return this.baseRowKey(row);
+      const idField = row.id;
+      return typeof idField === "string" ? idField : "";
+    };
+    for (const row of baseRows) {
+      const id = idOf(row);
+      if (id) merged.set(id, row);
+    }
+    for (const row of overlayRows) {
+      const id = idOf(row);
+      if (!id) continue;
+      if (this.shadowPredicateApplies(row)) {
+        merged.set(id, row);
+      } else if (!merged.has(id)) {
+        continue;
+      }
+    }
+    return [...merged.values()];
+  }
+  /**
+   * Write to the overlay. Two forms:
+   * - `put(record)`: id is derived via the base MV's `rowKey(record)`.
+   *   Throws if the base isn't an MV.
+   * - `put(id, record)`: validates `id === rowKey(record)`; throws
+   *   `OverlayIdMismatchError` on mismatch.
+   */
+  async put(idOrRecord, maybeRecord) {
+    let id;
+    let record;
+    if (maybeRecord === void 0) {
+      record = idOrRecord;
+      if (!this.baseRowKey) {
+        throw new Error(
+          `Overlay "${this.spec.name}".put(record): base "${this.spec.base}" is not an MV. Use put(id, record) explicitly.`
+        );
+      }
+      id = this.baseRowKey(record);
+    } else {
+      id = idOrRecord;
+      record = maybeRecord;
+      if (this.baseRowKey) {
+        const expected = this.baseRowKey(record);
+        if (id !== expected) {
+          throw new OverlayIdMismatchError(id, expected);
+        }
+      }
+    }
+    await this.overlayCollection.put(id, record);
+  }
+  /**
+   * Remove the overlay row only. Idempotent (no-op on absent).
+   * The base row is untouched — if a base row exists for `id`,
+   * subsequent reads return it.
+   */
+  async delete(id) {
+    await this.overlayCollection.delete(id);
+  }
+  /** True when `overlay[shadowField] === shadowValue`. */
+  shadowPredicateApplies(row) {
+    return row[this.spec.shadowField] === this.spec.shadowValue;
+  }
+  // ─── Throw-stubs for the unimplemented Collection<T> surface ───────
+  //
+  // `Vault.collection(name)` widens the return type to `Collection<T>`
+  // for the overlay intercept, but `OverlayedCollection` doesn't
+  // implement the full surface. These stubs catch the common
+  // reactive / chainable APIs with a clear "not yet implemented"
+  // error pointing at the relevant issue — so consumers don't hit a
+  // cryptic `undefined is not a function` runtime crash.
+  //
+  // Closes niwat-review of PR #160.
+  /** @throws — chainable Query<T> over a virtual collection is deferred. */
+  query() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".query() is not yet implemented for overlay views (#154). Use \`list()\` + filter for now, or read from the underlying \`${this.spec.base}\` / \`${this.spec.overlay}\` collections directly. Reactive APIs land in a future MV sub-issue.`
+    );
+  }
+  /** @throws — change-stream subscription over a virtual collection is deferred. */
+  subscribe() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".subscribe() is not yet implemented for overlay views (#154). Subscribe to the underlying \`${this.spec.base}\` / \`${this.spec.overlay}\` collections individually for now. Merged change-stream lands in a future MV sub-issue.`
+    );
+  }
+  /** @throws — live query over a virtual collection is deferred. */
+  live() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".live() is not yet implemented for overlay views (#154). Reactive APIs land in a future MV sub-issue.`
+    );
+  }
+  /** @throws — async iteration over a virtual collection is deferred. */
+  scan() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".scan() is not yet implemented for overlay views (#154). Use \`list()\` for now (no row-count ceiling at niwat scale), or scan the underlying collections directly.`
+    );
+  }
+  /** @throws — lazy-mode query is not applicable to virtual collections. */
+  lazyQuery() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".lazyQuery() is not supported. Virtual collections always materialize through base + overlay reads \u2014 lazy-mode indexed lookups don't apply.`
+    );
+  }
+  /** @throws — bulk-atomic put is deferred to a future MV sub-issue. */
+  putManyAtomic() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".putManyAtomic() is not yet implemented for overlay views (#154). Use sequential \`.put(record)\` calls for now, or write to \`${this.spec.overlay}\` directly.`
+    );
+  }
+  /** @throws — bulk delete is deferred to a future MV sub-issue. */
+  deleteMany() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".deleteMany() is not yet implemented for overlay views (#154). Use sequential \`.delete(id)\` calls for now, or operate on \`${this.spec.overlay}\` directly.`
+    );
+  }
+  /** @throws — `.first()` over a virtual collection is deferred. */
+  first() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".first() is not yet implemented for overlay views (#154). Use \`(await list())[0]\` for now.`
+    );
+  }
+  /** @throws — `.count()` over a virtual collection is deferred. */
+  count() {
+    throw new Error(
+      `OverlayedCollection "${this.spec.name}".count() is not yet implemented for overlay views (#154). Use \`(await list()).length\` for now.`
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OverlayBaseIsVirtualError,
+  OverlayCollectionUnavailableError,
+  OverlayIdMismatchError,
+  OverlayNameCollisionError,
+  OverlayedCollection,
+  OverlayedViewRegistry,
+  withOverlayedView
+});
+//# sourceMappingURL=index.cjs.map