@objectstack/metadata-fs 5.0.0

package/dist/index.cjs

@@ -0,0 +1,622 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FileSystemRepository: () => FileSystemRepository,
+  JsonlLog: () => JsonlLog
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/repository.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_fs2 = require("fs");
+var import_node_path3 = __toESM(require("path"), 1);
+var import_chokidar = __toESM(require("chokidar"), 1);
+var import_metadata_core = require("@objectstack/metadata-core");
+
+// src/layout.ts
+var import_node_path = __toESM(require("path"), 1);
+function itemPath(layout, type, name) {
+  return import_node_path.default.join(layout.root, type, `${name}.json`);
+}
+function typeDir(layout, type) {
+  return import_node_path.default.join(layout.root, type);
+}
+function logDir(layout) {
+  return import_node_path.default.join(layout.root, ".objectstack", ".log");
+}
+function logFile(layout) {
+  return import_node_path.default.join(logDir(layout), `main.jsonl`);
+}
+function parseItemPath(layout, absPath) {
+  const rel = import_node_path.default.relative(layout.root, absPath);
+  if (rel.startsWith("..") || rel.startsWith(".objectstack")) return null;
+  const segments = rel.split(import_node_path.default.sep);
+  if (segments.length !== 2) return null;
+  const type = segments[0];
+  const file = segments[1];
+  if (!file.endsWith(".json")) return null;
+  const name = file.slice(0, -".json".length);
+  return { type, name };
+}
+
+// src/jsonl-log.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var import_node_readline = __toESM(require("readline"), 1);
+var import_node_fs = require("fs");
+var JsonlLog = class {
+  constructor(file) {
+    this.file = file;
+  }
+  async append(evt) {
+    await import_promises.default.mkdir(import_node_path2.default.dirname(this.file), { recursive: true });
+    await import_promises.default.appendFile(this.file, JSON.stringify(evt) + "\n", "utf8");
+  }
+  /** Read all events in seq order (i.e. file order). */
+  async *readAll() {
+    if (!(0, import_node_fs.existsSync)(this.file)) return;
+    const rl = import_node_readline.default.createInterface({
+      input: (0, import_node_fs.createReadStream)(this.file, { encoding: "utf8" }),
+      crlfDelay: Infinity
+    });
+    try {
+      for await (const line of rl) {
+        if (!line.trim()) continue;
+        try {
+          yield JSON.parse(line);
+        } catch {
+        }
+      }
+    } finally {
+      rl.close();
+    }
+  }
+  /** Return the highest seq number in the log, or 0 if empty. */
+  async highestSeq() {
+    let max = 0;
+    for await (const evt of this.readAll()) {
+      if (typeof evt.seq === "number" && evt.seq > max) max = evt.seq;
+    }
+    return max;
+  }
+};
+
+// src/sync.ts
+var KeyedMutex = class {
+  constructor() {
+    this.tails = /* @__PURE__ */ new Map();
+  }
+  async run(key, fn) {
+    const prev = this.tails.get(key) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    const swallowed = next.catch(() => void 0);
+    this.tails.set(key, swallowed);
+    try {
+      return await next;
+    } finally {
+      if (this.tails.get(key) === swallowed) {
+        this.tails.delete(key);
+      }
+    }
+  }
+};
+function createBroker(matches) {
+  const subs = /* @__PURE__ */ new Set();
+  return {
+    subscribe: (s) => {
+      subs.add(s);
+    },
+    unsubscribe: (s) => {
+      subs.delete(s);
+    },
+    publish: (evt) => {
+      for (const s of subs) {
+        if (s.closed) continue;
+        if (!matches(evt, s.filter)) continue;
+        s.push(evt);
+      }
+    }
+  };
+}
+
+// src/watch-iterable.ts
+function createWatchIterable(args) {
+  const queue = [];
+  let waiter = null;
+  let closed = false;
+  const delivered = /* @__PURE__ */ new Set();
+  const evtKey = (e) => `${args.branchKeyOf(e)}#${e.seq}`;
+  const subscriber = {
+    filter: args.filter,
+    closed: false,
+    push: (evt) => {
+      if (subscriber.closed) return;
+      const k = evtKey(evt);
+      if (delivered.has(k)) return;
+      if (waiter) {
+        delivered.add(k);
+        const w = waiter;
+        waiter = null;
+        w({ value: clone(evt), done: false });
+      } else {
+        queue.push(evt);
+      }
+    }
+  };
+  args.broker.subscribe(subscriber);
+  const replay = [...args.replay].sort((a, b) => a.seq - b.seq);
+  let replayIdx = 0;
+  const drain = () => {
+    while (replayIdx < replay.length) {
+      const evt = replay[replayIdx++];
+      if (typeof args.since === "number" && evt.seq <= args.since) continue;
+      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;
+      args.broker.unsubscribe(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 = drain();
+      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 };
+}
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+// src/repository.ts
+var matchRefFilter = (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 matchEvent = (evt, filter) => matchRefFilter(evt.ref, filter);
+var FileSystemRepository = class {
+  constructor(opts) {
+    this.mutex = new KeyedMutex();
+    this.broker = createBroker(matchEvent);
+    /** In-memory index: refKey → current hash (HEAD). */
+    this.heads = /* @__PURE__ */ new Map();
+    /** Next seq counter, hydrated from the log on `start()`. */
+    this.nextSeq = 1;
+    /** Paths we wrote ourselves; suppress the resulting chokidar event. */
+    this.selfWrites = /* @__PURE__ */ new Set();
+    this.watcher = null;
+    this.started = false;
+    this.org = opts.org;
+    this.fsActor = opts.fsActor ?? "fs";
+    this.disableWatch = opts.disableWatch ?? false;
+    this.now = opts.now ?? (() => /* @__PURE__ */ new Date());
+    this.layout = { root: import_node_path3.default.resolve(opts.root) };
+    this.log = new JsonlLog(logFile(this.layout));
+  }
+  // ── Lifecycle ───────────────────────────────────────────────────────
+  async start() {
+    if (this.started) return;
+    this.started = true;
+    await import_promises2.default.mkdir(this.layout.root, { recursive: true });
+    await import_promises2.default.mkdir(logDir(this.layout), { recursive: true });
+    await this.scanHeads();
+    const highest = await this.log.highestSeq();
+    this.nextSeq = highest + 1;
+    if (!this.disableWatch) this.startWatcher();
+  }
+  async close() {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+    this.started = false;
+  }
+  // ── Read API ────────────────────────────────────────────────────────
+  async get(ref) {
+    this.assertScope(ref);
+    const file = itemPath(this.layout, ref.type, ref.name);
+    if (!(0, import_node_fs2.existsSync)(file)) return null;
+    const body = await readJson(file);
+    if (!body) return null;
+    const hash = (0, import_metadata_core.hashSpec)(body);
+    if (ref.version && ref.version !== hash) return null;
+    const meta = await this.findMetaForHash(ref, hash);
+    return {
+      ref: { ...ref, version: void 0 },
+      body,
+      hash,
+      parentHash: meta?.parentHash ?? null,
+      authoredBy: meta?.actor ?? this.fsActor,
+      authoredAt: meta?.ts ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+      message: meta?.message,
+      seq: meta?.seq ?? 0
+    };
+  }
+  async *list(filter) {
+    const limit = filter.limit ?? Infinity;
+    let yielded = 0;
+    for (const [key, hash] of this.heads) {
+      const ref = parseRefKey(key);
+      if (!ref) continue;
+      if (!matchRefFilter(ref, filter)) continue;
+      if (filter.nameContains && !ref.name.includes(filter.nameContains)) continue;
+      const meta = await this.findMetaForHash(ref, hash);
+      const header = {
+        ref: { ...ref, version: void 0 },
+        hash,
+        parentHash: meta?.parentHash ?? null,
+        authoredBy: meta?.actor ?? this.fsActor,
+        authoredAt: meta?.ts ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+        message: meta?.message,
+        seq: meta?.seq ?? 0
+      };
+      yield header;
+      if (++yielded >= limit) return;
+    }
+  }
+  async *history(ref, opts = {}) {
+    this.assertScope(ref);
+    const since = opts.sinceSeq ?? -1;
+    const limit = opts.limit ?? Infinity;
+    let yielded = 0;
+    for await (const evt of this.log.readAll()) {
+      if (evt.seq <= since) continue;
+      if (evt.ref.type !== ref.type || evt.ref.name !== ref.name) continue;
+      if (evt.ref.org !== ref.org) continue;
+      yield evt;
+      if (++yielded >= limit) return;
+    }
+  }
+  watch(filter, since) {
+    const replay = [];
+    const promise = (async () => {
+      for await (const evt of this.log.readAll()) {
+        if (matchEvent(evt, filter)) replay.push(evt);
+      }
+    })();
+    return deferredIterable(promise.then(
+      () => createWatchIterable({
+        filter,
+        since,
+        replay,
+        broker: this.broker,
+        matches: matchEvent,
+        branchKeyOf: (e) => e.ref.org
+      })
+    ));
+  }
+  // ── Write API ───────────────────────────────────────────────────────
+  put(ref, spec, opts) {
+    this.assertScope(ref);
+    return this.mutex.run((0, import_metadata_core.refKey)(ref), async () => {
+      const key = (0, import_metadata_core.refKey)(ref);
+      const currentHead = this.heads.get(key) ?? null;
+      if ((opts.parentVersion ?? null) !== currentHead) {
+        throw new import_metadata_core.ConflictError(ref, opts.parentVersion ?? null, currentHead);
+      }
+      const hash = (0, import_metadata_core.hashSpec)(spec);
+      if (currentHead === hash) {
+        const meta = await this.findMetaForHash(ref, hash);
+        return {
+          version: hash,
+          seq: meta?.seq ?? 0,
+          item: {
+            ref: { ...ref, version: void 0 },
+            body: spec,
+            hash,
+            parentHash: meta?.parentHash ?? null,
+            authoredBy: meta?.actor ?? this.fsActor,
+            authoredAt: meta?.ts ?? this.now().toISOString(),
+            message: meta?.message,
+            seq: meta?.seq ?? 0
+          }
+        };
+      }
+      const seq = this.nextSeq++;
+      const ts = this.now().toISOString();
+      const file = itemPath(this.layout, ref.type, ref.name);
+      await import_promises2.default.mkdir(typeDir(this.layout, ref.type), { recursive: true });
+      this.selfWrites.add(file);
+      try {
+        await writeJsonAtomic(file, spec);
+      } finally {
+        setTimeout(() => this.selfWrites.delete(file), 200);
+      }
+      this.heads.set(key, hash);
+      const evt = {
+        seq,
+        op: currentHead ? "update" : "create",
+        ref: { ...ref, version: void 0 },
+        hash,
+        parentHash: currentHead,
+        actor: opts.actor,
+        message: opts.message,
+        ts,
+        source: opts.source ?? "fs"
+      };
+      await this.log.append(evt);
+      this.broker.publish(evt);
+      return {
+        version: hash,
+        seq,
+        item: {
+          ref: { ...ref, version: void 0 },
+          body: spec,
+          hash,
+          parentHash: currentHead,
+          authoredBy: opts.actor,
+          authoredAt: ts,
+          message: opts.message,
+          seq
+        }
+      };
+    });
+  }
+  delete(ref, opts) {
+    this.assertScope(ref);
+    return this.mutex.run((0, import_metadata_core.refKey)(ref), async () => {
+      const key = (0, import_metadata_core.refKey)(ref);
+      const currentHead = this.heads.get(key) ?? null;
+      if (currentHead !== opts.parentVersion) {
+        throw new import_metadata_core.ConflictError(ref, opts.parentVersion, currentHead);
+      }
+      const file = itemPath(this.layout, ref.type, ref.name);
+      this.selfWrites.add(file);
+      try {
+        if ((0, import_node_fs2.existsSync)(file)) await import_promises2.default.unlink(file);
+      } finally {
+        setTimeout(() => this.selfWrites.delete(file), 200);
+      }
+      this.heads.delete(key);
+      const seq = this.nextSeq++;
+      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 ?? "fs"
+      };
+      await this.log.append(evt);
+      this.broker.publish(evt);
+      return { seq };
+    });
+  }
+  // ── Internals ───────────────────────────────────────────────────────
+  assertScope(ref) {
+    if (ref.org !== this.org) {
+      throw new Error(
+        `FileSystemRepository scope mismatch: expected org=${this.org}, got org=${ref.org}`
+      );
+    }
+  }
+  async scanHeads() {
+    this.heads.clear();
+    let entries = [];
+    try {
+      entries = await import_promises2.default.readdir(this.layout.root, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      const type = entry.name;
+      const dir = import_node_path3.default.join(this.layout.root, type);
+      let files = [];
+      try {
+        files = await import_promises2.default.readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const name = file.slice(0, -".json".length);
+        const ref = {
+          org: this.org,
+          type,
+          name
+        };
+        const body = await readJson(import_node_path3.default.join(dir, file));
+        if (!body) continue;
+        this.heads.set((0, import_metadata_core.refKey)(ref), (0, import_metadata_core.hashSpec)(body));
+      }
+    }
+  }
+  async findMetaForHash(ref, hash) {
+    let last = null;
+    for await (const evt of this.log.readAll()) {
+      if (evt.ref.type !== ref.type || evt.ref.name !== ref.name) continue;
+      if (evt.ref.org !== ref.org) continue;
+      if (evt.hash === hash) last = evt;
+    }
+    return last;
+  }
+  startWatcher() {
+    const w = import_chokidar.default.watch(this.layout.root, {
+      ignored: [/(^|[\\/])\../],
+      // skip dotfiles incl. .objectstack
+      ignoreInitial: true,
+      depth: 2,
+      awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 20 },
+      // Use polling to avoid `fs.watch` EMFILE on macOS / busy dev hosts.
+      // The depth-2 recursion would otherwise wire native watches across
+      // the entire customization tree.
+      usePolling: true,
+      interval: 1e3,
+      binaryInterval: 2e3
+    });
+    w.on("add", (p) => void this.handleFsChange(p, "add"));
+    w.on("change", (p) => void this.handleFsChange(p, "change"));
+    w.on("unlink", (p) => void this.handleFsChange(p, "unlink"));
+    this.watcher = w;
+  }
+  async handleFsChange(absPath, kind) {
+    if (this.selfWrites.has(absPath)) return;
+    const parsed = parseItemPath(this.layout, absPath);
+    if (!parsed) return;
+    const ref = {
+      org: this.org,
+      type: parsed.type,
+      name: parsed.name
+    };
+    const key = (0, import_metadata_core.refKey)(ref);
+    await this.mutex.run(key, async () => {
+      if (kind === "unlink") {
+        const currentHead2 = this.heads.get(key) ?? null;
+        if (!currentHead2) return;
+        this.heads.delete(key);
+        const seq2 = this.nextSeq++;
+        const evt2 = {
+          seq: seq2,
+          op: "delete",
+          ref: { ...ref, version: void 0 },
+          hash: null,
+          parentHash: currentHead2,
+          actor: this.fsActor,
+          ts: this.now().toISOString(),
+          source: "fs"
+        };
+        await this.log.append(evt2);
+        this.broker.publish(evt2);
+        return;
+      }
+      const body = await readJson(absPath);
+      if (!body) return;
+      const hash = (0, import_metadata_core.hashSpec)(body);
+      const currentHead = this.heads.get(key) ?? null;
+      if (currentHead === hash) return;
+      this.heads.set(key, hash);
+      const seq = this.nextSeq++;
+      const evt = {
+        seq,
+        op: currentHead ? "update" : "create",
+        ref: { ...ref, version: void 0 },
+        hash,
+        parentHash: currentHead,
+        actor: this.fsActor,
+        ts: this.now().toISOString(),
+        source: "fs"
+      };
+      await this.log.append(evt);
+      this.broker.publish(evt);
+    });
+  }
+};
+async function readJson(file) {
+  try {
+    const text = await import_promises2.default.readFile(file, "utf8");
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+async function writeJsonAtomic(file, body) {
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await import_promises2.default.writeFile(tmp, JSON.stringify(body, null, 2) + "\n", "utf8");
+  await import_promises2.default.rename(tmp, file);
+}
+function parseRefKey(key) {
+  const parts = key.split("/");
+  if (parts.length !== 3) return null;
+  return {
+    org: parts[0],
+    type: parts[1],
+    name: parts[2]
+  };
+}
+function deferredIterable(promise) {
+  return {
+    [Symbol.asyncIterator]() {
+      let inner = null;
+      return {
+        async next() {
+          if (!inner) {
+            const iterable = await promise;
+            inner = iterable[Symbol.asyncIterator]();
+          }
+          return inner.next();
+        },
+        async return(value) {
+          if (!inner) {
+            const iterable = await promise;
+            inner = iterable[Symbol.asyncIterator]();
+          }
+          if (inner.return) return inner.return(value);
+          return { value: void 0, done: true };
+        }
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileSystemRepository,
+  JsonlLog
+});
+//# sourceMappingURL=index.cjs.map