@noy-db/hub 0.2.0-pre.30 → 0.2.0-pre.31

package/dist/derivations/index.cjs

@@ -1,469 +0,0 @@
-"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/derivations/index.ts
-var derivations_exports = {};
-__export(derivations_exports, {
-  DerivationCapExceededError: () => DerivationCapExceededError,
-  DerivationCycleError: () => DerivationCycleError,
-  DerivationDepthError: () => DerivationDepthError,
-  DerivationExecutor: () => DerivationExecutor,
-  DerivationOutputShapeError: () => DerivationOutputShapeError,
-  DerivationOutputUnknownError: () => DerivationOutputUnknownError,
-  DerivationRegistry: () => DerivationRegistry,
-  withDerivation: () => withDerivation,
-  withRollup: () => withRollup
-});
-module.exports = __toCommonJS(derivations_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 DerivationCycleError = class extends NoydbError {
-  path;
-  constructor(path) {
-    super(
-      "DERIVATION_CYCLE",
-      `Derivation graph contains a cycle: ${path.join(" \u2192 ")}. Refusing to open vault \u2014 break the cycle before retrying.`
-    );
-    this.name = "DerivationCycleError";
-    this.path = path;
-  }
-};
-var DerivationDepthError = class extends NoydbError {
-  limit;
-  attempted;
-  constructor(limit, attempted) {
-    super(
-      "DERIVATION_DEPTH",
-      `Derivation cascade exceeded max depth ${limit} (attempted ${attempted}). Pass lifecycle: { maxDepth: N } to raise the limit if intentional.`
-    );
-    this.name = "DerivationDepthError";
-    this.limit = limit;
-    this.attempted = attempted;
-  }
-};
-var DerivationOutputUnknownError = class extends NoydbError {
-  collection;
-  constructor(collection) {
-    super(
-      "DERIVATION_OUTPUT_UNKNOWN",
-      `Derivation output collection "${collection}" is not declared on the vault. Register the collection (e.g. via schema) before registering a derivation that writes to it.`
-    );
-    this.name = "DerivationOutputUnknownError";
-    this.collection = collection;
-  }
-};
-var DerivationOutputShapeError = class extends NoydbError {
-  outputKey;
-  constructor(outputKey, detail) {
-    super(
-      "DERIVATION_OUTPUT_SHAPE",
-      `Derivation output "${outputKey}" has invalid shape: ${detail}.`
-    );
-    this.name = "DerivationOutputShapeError";
-    this.outputKey = outputKey;
-  }
-};
-var DerivationCapExceededError = class extends NoydbError {
-  outputKey;
-  returned;
-  maxFanout;
-  constructor(outputKey, returned, maxFanout) {
-    super(
-      "DERIVATION_CAP_EXCEEDED",
-      `Derivation array output "${outputKey}" returned ${returned} rows, exceeding maxFanout=${maxFanout}. Raise \`maxFanout\` on the OutputSpec if this fanout is intended (the cap exists to keep dispatch cost bounded).`
-    );
-    this.name = "DerivationCapExceededError";
-    this.outputKey = outputKey;
-    this.returned = returned;
-    this.maxFanout = maxFanout;
-  }
-};
-
-// src/derivations/with-derivation.ts
-function withDerivation(spec) {
-  if (!spec.source || spec.source.length === 0) {
-    throw new ValidationError("withDerivation: source collection name is required");
-  }
-  if (!spec.outputs || Object.keys(spec.outputs).length === 0) {
-    throw new ValidationError("withDerivation: outputs map must declare at least one output");
-  }
-  if (spec.deterministic !== true) {
-    throw new ValidationError("withDerivation: v1 only supports deterministic derivations");
-  }
-  if (typeof spec.derive !== "function") {
-    throw new ValidationError("withDerivation: derive must be a function");
-  }
-  if (spec.sources !== void 0) {
-    for (const extra of spec.sources) {
-      if (typeof extra !== "string" || extra.length === 0) {
-        throw new ValidationError("withDerivation: each entry in sources[] must be a non-empty string");
-      }
-      if (extra === spec.source) {
-        throw new ValidationError(
-          `withDerivation: sources[] must not contain the primary source "${spec.source}"`
-        );
-      }
-    }
-  }
-  if (spec.triggerBy !== void 0) {
-    for (const t of spec.triggerBy) {
-      if (typeof t?.collection !== "string" || t.collection.length === 0) {
-        throw new ValidationError("withDerivation: each triggerBy entry needs a non-empty `collection`");
-      }
-      if (t.collection === spec.source) {
-        throw new ValidationError(
-          `withDerivation: triggerBy.collection must not equal the source "${spec.source}" (use sources[] for same-id triggers)`
-        );
-      }
-      if (typeof t.on !== "string" || t.on.length === 0) {
-        throw new ValidationError(
-          `withDerivation: triggerBy on "${t.collection}" needs a non-empty \`on\` (the FK field on the source)`
-        );
-      }
-      if (t.maxFanout !== void 0 && (!Number.isInteger(t.maxFanout) || t.maxFanout < 1)) {
-        throw new ValidationError(
-          `withDerivation: triggerBy maxFanout on "${t.collection}" must be a positive integer (got ${String(t.maxFanout)}).`
-        );
-      }
-    }
-  }
-  const lifecycleMode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
-  for (const [outputKey, outputSpec] of Object.entries(spec.outputs)) {
-    if (outputSpec.shape === "record" && outputSpec.collection === spec.source) {
-      if (!outputSpec.denorm || outputSpec.denorm.length === 0) {
-        throw new ValidationError(
-          `withDerivation: self-write output "${outputKey}" (collection === source "${spec.source}") must declare \`denorm: [...]\` naming the fields it maintains.`
-        );
-      }
-    }
-    if (outputSpec.shape === "array") {
-      if (lifecycleMode !== "eager") {
-        throw new ValidationError(
-          `withDerivation: shape 'array' supports lifecycle 'eager' only in this release Output "${outputKey}" declared lifecycle '${lifecycleMode}'. Switch to \`lifecycle: "eager"\` or use shape: "record".`
-        );
-      }
-      if (typeof outputSpec.key !== "function") {
-        throw new ValidationError(
-          `withDerivation: shape 'array' output "${outputKey}" requires \`key: (out) => string\`.`
-        );
-      }
-      if (outputSpec.maxFanout !== void 0) {
-        if (!Number.isInteger(outputSpec.maxFanout) || outputSpec.maxFanout < 1) {
-          throw new ValidationError(
-            `withDerivation: maxFanout for output "${outputKey}" must be a positive integer (got ${String(outputSpec.maxFanout)}).`
-          );
-        }
-      }
-    }
-  }
-  return {
-    __noydb_strategy: "derivation",
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    spec
-  };
-}
-
-// src/derivations/with-rollup.ts
-function withRollup(config) {
-  const { from, key, into, field, compute } = config;
-  if (!from || from.length === 0) {
-    throw new ValidationError("withRollup: `from` (child collection) is required");
-  }
-  if (!into || into.length === 0) {
-    throw new ValidationError("withRollup: `into` (parent collection) is required");
-  }
-  if (from === into) {
-    throw new ValidationError("withRollup: `from` and `into` must be different collections");
-  }
-  if (!key || key.length === 0) {
-    throw new ValidationError("withRollup: `key` (FK field on the child) is required");
-  }
-  if (!field || field.length === 0) {
-    throw new ValidationError("withRollup: `field` (target field on the parent) is required");
-  }
-  if (typeof compute !== "function") {
-    throw new ValidationError("withRollup: `compute` must be a function");
-  }
-  const spec = {
-    source: into,
-    // the parent record is what carries the rolled-up field
-    deterministic: true,
-    rollup: { from, key, field, compute },
-    // Synthetic self-write output for registry / cycle bookkeeping. Dispatch
-    // patches `field` directly (value-equality guarded); the executor is not run.
-    outputs: { value: { shape: "record", collection: into, denorm: [field] } },
-    derive: () => ({ value: {} }),
-    // never invoked for a rollup strategy
-    lifecycle: "eager"
-  };
-  return { __noydb_strategy: "derivation", spec };
-}
-
-// src/derivations/strategy-hash.ts
-async function computeStrategyHash(source, outputKeys, derive, sources) {
-  const canonical = JSON.stringify({
-    source,
-    outputs: [...outputKeys].sort(),
-    derive: derive.toString(),
-    // Declared sibling sources (#344) — adding/removing a trigger
-    // collection invalidates cached derived records. Omitted when empty
-    // so strategies without siblings keep their existing hash.
-    ...sources?.length ? { sources: [...sources].sort() } : {}
-  });
-  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("");
-}
-
-// src/derivations/registry.ts
-var DerivationRegistry = class {
-  _bySource = /* @__PURE__ */ new Map();
-  _byOutput = /* @__PURE__ */ new Map();
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async register(spec) {
-    const outputKeys = Object.keys(spec.outputs);
-    const strategyHash = await computeStrategyHash(spec.source, outputKeys, spec.derive, spec.sources);
-    const reg = { spec, strategyHash };
-    const fromSource = this._bySource.get(spec.source);
-    if (fromSource) fromSource.push(reg);
-    else this._bySource.set(spec.source, [reg]);
-    for (const extra of spec.sources ?? []) {
-      const fromExtra = this._bySource.get(extra);
-      if (fromExtra) fromExtra.push(reg);
-      else this._bySource.set(extra, [reg]);
-    }
-    for (const t of spec.triggerBy ?? []) {
-      const fromTrigger = this._bySource.get(t.collection);
-      if (fromTrigger) fromTrigger.push(reg);
-      else this._bySource.set(t.collection, [reg]);
-    }
-    if (spec.rollup) {
-      const fromRollup = this._bySource.get(spec.rollup.from);
-      if (fromRollup) fromRollup.push(reg);
-      else this._bySource.set(spec.rollup.from, [reg]);
-    }
-    for (const key of outputKeys) {
-      const output = spec.outputs[key];
-      if (!output) continue;
-      const outputCollection = output.collection;
-      const arr = this._byOutput.get(outputCollection);
-      if (arr) arr.push(reg);
-      else this._byOutput.set(outputCollection, [reg]);
-    }
-  }
-  strategiesForSource(source) {
-    return this._bySource.get(source) ?? [];
-  }
-  strategiesProducingOutput(collection) {
-    return this._byOutput.get(collection) ?? [];
-  }
-  /**
-   * All registered strategies as a flat, deduplicated array.
-   * Each strategy is indexed once per source (not once per output key),
-   * so iterating `_bySource.values()` naturally yields each strategy
-   * exactly once per source — deduplication is handled by flattening
-   * the per-source arrays and collecting into a Set by identity.
-   *
-   * Used by `dumpSchema()` / `describeDerivations()` in the introspection
-   * walker to populate the derivations map.
-   */
-  all() {
-    const seen = /* @__PURE__ */ new Set();
-    for (const strategies of this._bySource.values()) {
-      for (const s of strategies) seen.add(s);
-    }
-    return [...seen];
-  }
-  /**
-   * Cycle detection over the source → output → … graph. Call after all
-   * `register()` calls complete (i.e. at vault open). Throws
-   * `DerivationCycleError` on the first cycle found.
-   */
-  validate() {
-    const visited = /* @__PURE__ */ new Set();
-    const stack = [];
-    const visit = (node) => {
-      if (stack.includes(node)) {
-        const cycle = stack.slice(stack.indexOf(node)).concat(node);
-        throw new DerivationCycleError(cycle);
-      }
-      if (visited.has(node)) return;
-      stack.push(node);
-      const strategies = this._bySource.get(node);
-      if (strategies) {
-        for (const s of strategies) {
-          for (const key of Object.keys(s.spec.outputs)) {
-            const output = s.spec.outputs[key];
-            if (!output) continue;
-            if (output.shape === "record" && output.collection === s.spec.source && output.denorm !== void 0) {
-              continue;
-            }
-            visit(output.collection);
-          }
-        }
-      }
-      stack.pop();
-      visited.add(node);
-    };
-    for (const src of this._bySource.keys()) visit(src);
-  }
-};
-
-// src/derivations/executor.ts
-var DerivationExecutor = {
-  /**
-   * Run `derive` once, validate output shape against the spec, stamp
-   * `_derivedFrom` onto every output. Returns per-output success or
-   * failure; throws only for shape mismatches (a contract violation).
-   */
-  async run(strategy, source, sourceVersion, strategyHash, ctx) {
-    const outputs = {};
-    let derived;
-    try {
-      derived = await Promise.resolve(strategy.derive(source, ctx));
-    } catch (err) {
-      for (const key of Object.keys(strategy.outputs)) {
-        outputs[key] = {
-          kind: "failed",
-          value: {},
-          ok: false,
-          error: err instanceof Error ? err : new Error(String(err))
-        };
-      }
-      return { outputs, failed: true };
-    }
-    const meta = {
-      source: strategy.source,
-      sourceId: source.id,
-      sourceVersion,
-      derivedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      strategyHash
-    };
-    for (const key of Object.keys(strategy.outputs)) {
-      const outSpec = strategy.outputs[key];
-      if (!outSpec) continue;
-      const value = derived[key];
-      if (outSpec.shape === "array") {
-        if (value === void 0 || value === null) {
-          outputs[key] = { kind: "array", ok: true, entries: [] };
-          continue;
-        }
-        if (!Array.isArray(value)) {
-          throw new DerivationOutputShapeError(
-            key,
-            `shape 'array' expects an array, got ${typeof value}`
-          );
-        }
-        const maxFanout = outSpec.maxFanout ?? 64;
-        if (value.length > maxFanout) {
-          throw new DerivationCapExceededError(key, value.length, maxFanout);
-        }
-        const entries = [];
-        const seenKeys = /* @__PURE__ */ new Set();
-        for (let i = 0; i < value.length; i++) {
-          const row = value[i];
-          if (row === null || typeof row !== "object") {
-            throw new DerivationOutputShapeError(
-              key,
-              `array member at index ${i} must be a non-null object (got ${row === null ? "null" : typeof row})`
-            );
-          }
-          let derivedKey;
-          try {
-            derivedKey = outSpec.key(row);
-          } catch (err) {
-            throw new DerivationOutputShapeError(
-              key,
-              `key extractor threw on array member at index ${i}: ` + (err instanceof Error ? err.message : String(err))
-            );
-          }
-          if (typeof derivedKey !== "string" || derivedKey.length === 0) {
-            throw new DerivationOutputShapeError(
-              key,
-              `key extractor returned ${typeof derivedKey === "string" ? "empty string" : typeof derivedKey} at index ${i}; expected non-empty string`
-            );
-          }
-          if (seenKeys.has(derivedKey)) {
-            throw new DerivationOutputShapeError(
-              key,
-              `duplicate key "${derivedKey}" in array output (index ${i}); each derived row must have a unique key within a single derive() invocation`
-            );
-          }
-          seenKeys.add(derivedKey);
-          entries.push({
-            key: derivedKey,
-            value: { ...row, _derivedFrom: meta }
-          });
-        }
-        outputs[key] = { kind: "array", ok: true, entries };
-        continue;
-      }
-      if (value === void 0 || value === null) {
-        if (outSpec.optional === true) {
-          outputs[key] = { kind: "record", value: {}, ok: true, skipped: true };
-          continue;
-        }
-        throw new DerivationOutputShapeError(
-          key,
-          `expected object, got ${value === void 0 ? "undefined" : "null"}`
-        );
-      }
-      if (typeof value !== "object") {
-        throw new DerivationOutputShapeError(
-          key,
-          `expected object, got ${typeof value}`
-        );
-      }
-      outputs[key] = {
-        kind: "record",
-        value: { ...value, _derivedFrom: meta },
-        ok: true
-      };
-    }
-    return { outputs, failed: false };
-  }
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  DerivationCapExceededError,
-  DerivationCycleError,
-  DerivationDepthError,
-  DerivationExecutor,
-  DerivationOutputShapeError,
-  DerivationOutputUnknownError,
-  DerivationRegistry,
-  withDerivation,
-  withRollup
-});
-//# sourceMappingURL=index.cjs.map