@objectstack/metadata-core 5.0.0

package/dist/index.js

@@ -0,0 +1,611 @@
+import {
+  BranchError,
+  ConflictError,
+  MetadataError,
+  NotFoundError,
+  SchemaValidationError,
+  canonicalize,
+  hashSpec
+} from "./chunk-G3VZZW54.js";
+
+// src/types.ts
+import { z } from "zod";
+var MetadataTypeSchema = z.enum([
+  "object",
+  "view",
+  "page",
+  "dashboard",
+  "app",
+  "flow",
+  "workflow",
+  "agent",
+  "tool",
+  "skill",
+  "report",
+  "translation",
+  "role",
+  "permission",
+  "policy",
+  "api",
+  "endpoint",
+  "datasource",
+  "cube",
+  "settings"
+]).describe("Canonical metadata type name");
+var MetaRefSchema = z.object({
+  org: z.string().min(1).describe('Tenant/org identifier; "system" for built-ins'),
+  type: MetadataTypeSchema,
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe("Snake_case machine name"),
+  version: z.string().optional().describe("Optional version pin (content hash); omit for HEAD")
+});
+function refKey(ref) {
+  return `${ref.org}/${ref.type}/${ref.name}`;
+}
+var MetadataItemSchema = z.object({
+  ref: MetaRefSchema,
+  body: z.record(z.string(), z.unknown()).describe("Canonical Zod-normalised spec"),
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/).describe("sha256(canonicalize(body))"),
+  parentHash: z.string().nullable().describe("Hash this version was derived from; null for first version"),
+  authoredBy: z.string().describe('Identity of the writer (user id, "cli", "ai:claude", \u2026)'),
+  authoredAt: z.string().describe("ISO-8601 timestamp"),
+  message: z.string().optional().describe("Optional commit message"),
+  seq: z.number().int().nonnegative().describe("Sequence number this write produced in the org log"),
+  schemaVersion: z.string().optional().describe("Zod schema version that wrote this spec (M3 codemod hook)")
+});
+var MetadataOpSchema = z.enum(["create", "update", "delete", "rename"]);
+var MetadataEventSchema = z.object({
+  seq: z.number().int().nonnegative(),
+  op: MetadataOpSchema,
+  ref: MetaRefSchema,
+  hash: z.string().nullable(),
+  parentHash: z.string().nullable(),
+  previousName: z.string().optional().describe('Set on op="rename"'),
+  actor: z.string(),
+  message: z.string().optional(),
+  ts: z.string(),
+  source: z.string().describe('Origin label: "fs", "studio", "rest", "ai", "git-import", \u2026')
+});
+
+// src/repository.ts
+var LAYER_SOURCE = /* @__PURE__ */ Symbol.for("objectstack.metadata.layer-source");
+
+// src/in-memory-repository.ts
+var orgKey = (ref) => ref.org;
+var matchesFilter = (ref, filter) => {
+  if (filter.org && filter.org !== ref.org) return false;
+  if (filter.type && filter.type !== ref.type) return false;
+  if (filter.name && filter.name !== ref.name) return false;
+  return true;
+};
+var InMemoryRepository = class {
+  constructor(opts = {}) {
+    this.items = /* @__PURE__ */ new Map();
+    /** Per-org event log. */
+    this.logs = /* @__PURE__ */ new Map();
+    /** Next seq per org. */
+    this.seqs = /* @__PURE__ */ new Map();
+    this.subscribers = /* @__PURE__ */ new Set();
+    this.now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  async get(ref) {
+    const item = this.items.get(refKey(ref));
+    if (!item) return null;
+    if (ref.version && item.hash !== ref.version) {
+      return null;
+    }
+    return clone(item);
+  }
+  async put(ref, spec, opts) {
+    const key = refKey(ref);
+    const current = this.items.get(key);
+    const currentHead = current?.hash ?? null;
+    if ((opts.parentVersion ?? null) !== currentHead) {
+      throw new ConflictError(ref, opts.parentVersion ?? null, currentHead);
+    }
+    const hash = hashSpec(spec);
+    if (current && current.hash === hash) {
+      return { version: hash, seq: current.seq, item: clone(current) };
+    }
+    const seq = this.bumpSeq(ref);
+    const ts = this.now().toISOString();
+    const item = {
+      ref: { ...ref, version: void 0 },
+      body: clonePlain(spec),
+      hash,
+      parentHash: currentHead,
+      authoredBy: opts.actor,
+      authoredAt: ts,
+      message: opts.message,
+      seq
+    };
+    this.items.set(key, item);
+    const evt = {
+      seq,
+      op: current ? "update" : "create",
+      ref: { ...ref, version: void 0 },
+      hash,
+      parentHash: currentHead,
+      actor: opts.actor,
+      message: opts.message,
+      ts,
+      source: opts.source ?? "in-memory"
+    };
+    this.appendEvent(ref, evt);
+    return { version: hash, seq, item: clone(item) };
+  }
+  async delete(ref, opts) {
+    const key = refKey(ref);
+    const current = this.items.get(key);
+    const currentHead = current?.hash ?? null;
+    if (currentHead !== opts.parentVersion) {
+      throw new ConflictError(ref, opts.parentVersion, currentHead);
+    }
+    this.items.delete(key);
+    const seq = this.bumpSeq(ref);
+    const ts = this.now().toISOString();
+    const evt = {
+      seq,
+      op: "delete",
+      ref: { ...ref, version: void 0 },
+      hash: null,
+      parentHash: currentHead,
+      actor: opts.actor,
+      message: opts.message,
+      ts,
+      source: opts.source ?? "in-memory"
+    };
+    this.appendEvent(ref, evt);
+    return { seq };
+  }
+  async *list(filter) {
+    const limit = filter.limit ?? Infinity;
+    let yielded = 0;
+    for (const item of this.items.values()) {
+      if (!matchesFilter(item.ref, filter)) continue;
+      if (filter.nameContains && !item.ref.name.includes(filter.nameContains)) continue;
+      const { body, ...header } = item;
+      void body;
+      yield clone(header);
+      if (++yielded >= limit) return;
+    }
+  }
+  async *history(ref, opts = {}) {
+    const log = this.logs.get(orgKey(ref)) ?? [];
+    const since = opts.sinceSeq ?? -1;
+    const limit = opts.limit ?? Infinity;
+    let yielded = 0;
+    for (const evt of log) {
+      if (evt.seq <= since) continue;
+      if (evt.ref.type !== ref.type || evt.ref.name !== ref.name) continue;
+      yield clone(evt);
+      if (++yielded >= limit) return;
+    }
+  }
+  watch(filter, since) {
+    const queue = [];
+    let waiter = null;
+    let closed = false;
+    const delivered = /* @__PURE__ */ new Set();
+    const evtKey = (e) => `${orgKey(e.ref)}#${e.seq}`;
+    const subscriber = {
+      filter,
+      closed: false,
+      push: (evt) => {
+        if (subscriber.closed) return;
+        if (waiter) {
+          const k = evtKey(evt);
+          if (delivered.has(k)) return;
+          delivered.add(k);
+          const w = waiter;
+          waiter = null;
+          w({ value: clone(evt), done: false });
+        } else {
+          queue.push(evt);
+        }
+      }
+    };
+    this.subscribers.add(subscriber);
+    const replay = [];
+    for (const ok of this.orgKeysMatching(filter)) {
+      const log = this.logs.get(ok) ?? [];
+      for (const evt of log) {
+        if (typeof since === "number" && evt.seq <= since) continue;
+        if (!matchesFilter(evt.ref, filter)) continue;
+        replay.push(evt);
+      }
+    }
+    replay.sort((a, b) => a.seq - b.seq);
+    let replayIdx = 0;
+    const drainQueueOrReplay = () => {
+      while (replayIdx < replay.length) {
+        const evt = replay[replayIdx++];
+        const k = evtKey(evt);
+        if (delivered.has(k)) continue;
+        delivered.add(k);
+        return { value: clone(evt), done: false };
+      }
+      while (queue.length > 0) {
+        const evt = queue.shift();
+        const k = evtKey(evt);
+        if (delivered.has(k)) continue;
+        delivered.add(k);
+        return { value: clone(evt), done: false };
+      }
+      return null;
+    };
+    const close = () => {
+      if (!closed) {
+        closed = true;
+        subscriber.closed = true;
+        this.subscribers.delete(subscriber);
+        if (waiter) {
+          const w = waiter;
+          waiter = null;
+          w({ value: void 0, done: true });
+        }
+      }
+      return { value: void 0, done: true };
+    };
+    const iterator = {
+      next: () => {
+        if (closed) return Promise.resolve({ value: void 0, done: true });
+        const immediate = drainQueueOrReplay();
+        if (immediate) return Promise.resolve(immediate);
+        return new Promise((resolve) => {
+          waiter = resolve;
+        });
+      },
+      return: () => Promise.resolve(close()),
+      throw: (err) => {
+        close();
+        return Promise.reject(err);
+      }
+    };
+    return {
+      [Symbol.asyncIterator]: () => iterator
+    };
+  }
+  // ── Internals ───────────────────────────────────────────────────────
+  bumpSeq(ref) {
+    const ok = orgKey(ref);
+    const next = (this.seqs.get(ok) ?? 0) + 1;
+    this.seqs.set(ok, next);
+    return next;
+  }
+  appendEvent(ref, evt) {
+    const ok = orgKey(ref);
+    const log = this.logs.get(ok) ?? [];
+    log.push(evt);
+    this.logs.set(ok, log);
+    for (const sub of this.subscribers) {
+      if (sub.closed) continue;
+      if (!matchesFilter(evt.ref, sub.filter)) continue;
+      sub.push(evt);
+    }
+  }
+  orgKeysMatching(filter) {
+    const keys = [];
+    for (const ok of this.logs.keys()) {
+      if (filter.org && filter.org !== ok) continue;
+      keys.push(ok);
+    }
+    return keys;
+  }
+};
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function clonePlain(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+// src/cache.ts
+var MetadataCache = class {
+  constructor(repo, opts = {}) {
+    /** LRU is implemented via insertion-order Map; touch on get/set. */
+    this.entries = /* @__PURE__ */ new Map();
+    this.bytes = 0;
+    /** De-duplicate concurrent fetches for the same key. */
+    this.inflight = /* @__PURE__ */ new Map();
+    /**
+     * Generation counter incremented on every invalidation. Each in-flight
+     * fetch captures the gen at start; if the gen changes before it
+     * resolves, the result is NOT cached.
+     */
+    this.fetchGen = /* @__PURE__ */ new Map();
+    this.watchIterator = null;
+    this.watchClosed = false;
+    this.watchLoop = null;
+    this.stats = {
+      entries: 0,
+      bytes: 0,
+      hits: 0,
+      misses: 0,
+      invalidations: 0,
+      coalesced: 0
+    };
+    this.repo = repo;
+    this.maxEntries = opts.maxEntries ?? 1024;
+    this.maxBytes = opts.maxBytes ?? 8 * 1024 * 1024;
+    this.watchFilter = opts.watchFilter ?? {};
+  }
+  /**
+   * Start the background watch subscription. Idempotent; safe to call
+   * multiple times. Caller is responsible for calling `close()` when
+   * the cache is no longer needed.
+   */
+  start() {
+    if (this.watchIterator || this.watchClosed) return;
+    const iter = this.repo.watch(this.watchFilter)[Symbol.asyncIterator]();
+    this.watchIterator = iter;
+    this.watchLoop = (async () => {
+      try {
+        while (!this.watchClosed) {
+          const { value, done } = await iter.next();
+          if (done) return;
+          this.applyEvent(value);
+        }
+      } catch {
+      }
+    })();
+  }
+  /** Tear down the watch subscription and clear in-flight tracking. */
+  async close() {
+    this.watchClosed = true;
+    if (this.watchIterator?.return) {
+      try {
+        await this.watchIterator.return(void 0);
+      } catch {
+      }
+    }
+    this.watchIterator = null;
+    if (this.watchLoop) {
+      try {
+        await this.watchLoop;
+      } catch {
+      }
+      this.watchLoop = null;
+    }
+    this.inflight.clear();
+  }
+  /** Read with cache. Coalesces concurrent reads for the same key. */
+  async get(ref) {
+    const key = refKey(ref);
+    const cached = this.entries.get(key);
+    if (cached) {
+      this.entries.delete(key);
+      this.entries.set(key, cached);
+      cached.hits += 1;
+      this.stats.hits += 1;
+      return cached.item ? clone2(cached.item) : null;
+    }
+    const existing = this.inflight.get(key);
+    if (existing) {
+      this.stats.coalesced += 1;
+      const item2 = await existing;
+      return item2 ? clone2(item2) : null;
+    }
+    this.stats.misses += 1;
+    const gen = this.fetchGen.get(key) ?? 0;
+    const promise = this.repo.get(ref).then((item2) => {
+      if ((this.fetchGen.get(key) ?? 0) === gen) {
+        this.cacheSet(key, item2);
+      }
+      return item2;
+    }).finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, promise);
+    const item = await promise;
+    return item ? clone2(item) : null;
+  }
+  /** Drop a single entry by ref. */
+  invalidate(ref) {
+    const key = refKey(ref);
+    this.bumpGen(key);
+    const removed = this.entries.get(key);
+    if (removed) {
+      this.bytes -= removed.size;
+      this.entries.delete(key);
+    }
+    this.stats.invalidations += 1;
+  }
+  /** Drop the entire cache (e.g. on a reset). */
+  clear() {
+    this.entries.clear();
+    this.bytes = 0;
+    for (const key of this.inflight.keys()) this.bumpGen(key);
+  }
+  getStats() {
+    return {
+      ...this.stats,
+      entries: this.entries.size,
+      bytes: this.bytes
+    };
+  }
+  // ── Internals ───────────────────────────────────────────────────────
+  applyEvent(evt) {
+    const ref = evt.ref;
+    this.invalidate(ref);
+    if (evt.op === "rename" && evt.previousName) {
+      this.invalidate({ ...ref, name: evt.previousName });
+    }
+  }
+  cacheSet(key, item) {
+    const size = item ? estimateSize(item) : 0;
+    const existing = this.entries.get(key);
+    if (existing) this.bytes -= existing.size;
+    this.entries.set(key, { item, size, hits: 0 });
+    this.bytes += size;
+    this.evictIfNeeded();
+  }
+  evictIfNeeded() {
+    while (this.entries.size > this.maxEntries || this.bytes > this.maxBytes) {
+      const first = this.entries.keys().next();
+      if (first.done) break;
+      const key = first.value;
+      const entry = this.entries.get(key);
+      this.bytes -= entry.size;
+      this.entries.delete(key);
+    }
+  }
+  bumpGen(key) {
+    this.fetchGen.set(key, (this.fetchGen.get(key) ?? 0) + 1);
+  }
+};
+function estimateSize(item) {
+  try {
+    return JSON.stringify(item.body).length * 2 + 256;
+  } catch {
+    return 1024;
+  }
+}
+function clone2(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+// src/layered-repository.ts
+var tagSource = (label, evt) => ({
+  ...evt,
+  source: `${label}:${evt.source}`
+});
+var LayeredRepository = class {
+  constructor(opts) {
+    if (!opts.layers.length) {
+      throw new Error("LayeredRepository requires at least one layer");
+    }
+    this.layers = opts.layers;
+    this.writableIdx = opts.layers.findIndex((l) => !l.readOnly);
+  }
+  async get(ref) {
+    for (const layer of this.layers) {
+      const item = await layer.repo.get(ref);
+      if (item) return item;
+    }
+    return null;
+  }
+  async put(ref, spec, opts) {
+    if (this.writableIdx < 0) {
+      throw new Error("LayeredRepository: no writable layer configured");
+    }
+    return this.layers[this.writableIdx].repo.put(ref, spec, opts);
+  }
+  async delete(ref, opts) {
+    if (this.writableIdx < 0) {
+      throw new Error("LayeredRepository: no writable layer configured");
+    }
+    return this.layers[this.writableIdx].repo.delete(ref, opts);
+  }
+  async *list(filter) {
+    const seen = /* @__PURE__ */ new Set();
+    const limit = filter.limit ?? Infinity;
+    let yielded = 0;
+    for (const layer of this.layers) {
+      for await (const header of layer.repo.list(filter)) {
+        const key = refKey(header.ref);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        yield header;
+        if (++yielded >= limit) return;
+      }
+    }
+  }
+  async *history(ref, opts = {}) {
+    const events = [];
+    for (const layer of this.layers) {
+      for await (const evt of layer.repo.history(ref, opts)) {
+        events.push(tagSource(layer.label, evt));
+      }
+    }
+    events.sort((a, b) => a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0);
+    const limit = opts.limit ?? Infinity;
+    let yielded = 0;
+    for (const evt of events) {
+      yield evt;
+      if (++yielded >= limit) return;
+    }
+  }
+  watch(filter, since) {
+    return multiplexWatch(this.layers, filter, since);
+  }
+};
+function multiplexWatch(layers, filter, since) {
+  return {
+    [Symbol.asyncIterator]() {
+      const children = layers.map((layer) => ({
+        label: layer.label,
+        iter: layer.repo.watch(filter, since)[Symbol.asyncIterator](),
+        pending: null,
+        done: false
+      }));
+      let closed = false;
+      const pumpAll = () => {
+        for (const c of children) {
+          if (c.done || c.pending) continue;
+          c.pending = c.iter.next().then((result) => ({ label: c.label, result }));
+        }
+      };
+      const closeAll = async () => {
+        if (closed) return;
+        closed = true;
+        await Promise.all(
+          children.map(async (c) => {
+            try {
+              await c.iter.return?.(void 0);
+            } catch {
+            }
+          })
+        );
+      };
+      return {
+        async next() {
+          while (!closed) {
+            pumpAll();
+            const inflight = children.filter((c) => c.pending);
+            if (!inflight.length) return { value: void 0, done: true };
+            const winner = await Promise.race(inflight.map((c) => c.pending));
+            const target = children.find((c) => c.label === winner.label);
+            target.pending = null;
+            if (winner.result.done) {
+              target.done = true;
+              continue;
+            }
+            return {
+              value: tagSource(winner.label, winner.result.value),
+              done: false
+            };
+          }
+          return { value: void 0, done: true };
+        },
+        async return() {
+          await closeAll();
+          return { value: void 0, done: true };
+        },
+        async throw(err) {
+          await closeAll();
+          throw err;
+        }
+      };
+    }
+  };
+}
+export {
+  BranchError,
+  ConflictError,
+  InMemoryRepository,
+  LAYER_SOURCE,
+  LayeredRepository,
+  MetaRefSchema,
+  MetadataCache,
+  MetadataError,
+  MetadataEventSchema,
+  MetadataItemSchema,
+  MetadataOpSchema,
+  MetadataTypeSchema,
+  NotFoundError,
+  SchemaValidationError,
+  canonicalize,
+  hashSpec,
+  refKey
+};
+//# sourceMappingURL=index.js.map