@nubbin/store-fs 0.1.1 → 0.3.0

package/README.md

@@ -20,15 +20,21 @@ await store.publish("/promotions/summer", artifact.hash);
 .nubbin/
   artifacts/<hash>.json
   routes/%2Fpromotions%2Fsummer.json
+  history/%2Fpromotions%2Fsummer.jsonl
 ```
 
 Writes are temp-then-rename, so a concurrent reader sees the old pointer or the new one and
 never half of either. `manifest()` reads the pointer directory rather than a stored file, so
 there is nothing to keep in step.
 
+Each publish also appends one line to the route's history log — after the pointer has moved,
+so a failed publish is never recorded as live. Appending writes only the new line, never
+reading the log back to rewrite it, so concurrent publishes of one route cannot lose each
+other's entry either. `history(route)` reads it back oldest first, and `unpublish` leaves it
+where it is.
+
 It passes a shared `ArtifactStore` contract suite, which is how a replacement adapter proves
 itself equivalent — by execution rather than by inspection.
 
-**Release candidate.**
-
-<https://effekt.github.io/nubbin/>. MIT.
+Read the [Nubbin documentation](https://nubbin.io) for the complete artifact store reference.
+MIT.

package/dist/index.d.ts

@@ -1,8 +1,85 @@
 import { ArtifactStore } from '@nubbin/core';
 
 /**
- * One pointer file per route, one file per artifact, and nothing else. No aggregate document
- * exists, so two publishes to different routes cannot lose each other's write.
+ * Builds the reference `ArtifactStore` over a directory — the store the studio, the example app
+ * and the documented `@nubbin/cli` setup all publish through, and the one a replacement adapter is
+ * measured against.
+ *
+ * Three kinds of file live under `root`, and nothing else does:
+ *
+ * ```text
+ * <root>/
+ *   artifacts/<hash>.json                 one per written artifact, never rewritten
+ *   routes/%2Fpromotions%2Fsummer.json    the pointer — the only file that moves
+ *   history/%2Fpromotions%2Fsummer.jsonl  one line per publish, oldest first
+ * ```
+ *
+ * A route key is percent-encoded, so a route with slashes is one flat filename rather than a
+ * directory tree, and `manifest()` can list `routes/` to find every published route. The logs sit
+ * in their own directory for that reason: a `.jsonl` filed among the pointers would be read as one
+ * and break the listing.
+ *
+ * Nothing is created until something is written — `root` need not exist, and each write makes the
+ * directory it needs. Reading before then is not a failure: an unknown hash and an unpublished
+ * route both read as `null`, and a store with no `routes/` yet manifests as no routes.
+ *
+ * Repeating a call is safe, which is what a publish retried after a timeout needs, but the two
+ * repeats differ. Writing a hash the store already holds leaves the file alone — a content address
+ * that already resolves holds the same bytes by construction. Publishing the same route and hash
+ * again does not: the pointer is rewritten with a fresh `updatedAt` and a second move is appended
+ * to the log. Content addressing dedupes artifacts, not moves.
+ *
+ * Every `ArtifactStore` method is implemented, `history` included, so a caller reading a route's
+ * moves needs no `?? []` fallback for this store. Within one publish the pointer moves first and
+ * the log is appended after: a crash between the two leaves the log one entry short, which
+ * under-reports. The opposite order would let the log claim a publish that never went live.
+ *
+ * @param root - The directory the store owns, absolute or resolved against `process.cwd()`. It
+ *   owns everything beneath it, so give it a directory nothing else writes into. Two stores over
+ *   one root are the same store, and so is a second process pointed at it — the state is the files.
+ * @returns An `ArtifactStore` bound to `root`. It holds no cache and no open handle: every call
+ *   reads the filesystem, so one built at module scope stays correct as other processes publish
+ *   underneath it.
+ *
+ * @throws {NubbinError} From `publish`, coded `artifact-not-stored` when nothing has been written
+ *   at that hash. A pointer at an unwritten hash would be a live 404, so the existence check comes
+ *   before the pointer is touched.
+ * @throws {NubbinError} From `publish`, coded `invalid-route` when the route addresses no page.
+ *   Core's `parseMatchKind` judges it, so an adapter that never called `compile` still cannot
+ *   publish an unaddressable route.
+ * @throws A Node filesystem error, unchanged, when the operation itself fails — no permission on
+ *   `root`, a full disk, or a path taken by something that is not the expected kind of file.
+ *   `ENOENT` alone is not one of these: it is how absence is read.
+ * @throws A `SyntaxError` from `read`, `pointer` or `manifest` when a file under `root` is not the
+ *   JSON this store wrote. Hand-editing the directory, or pointing two tools at one root, is what
+ *   produces that.
+ *
+ * @example Compile, store, publish
+ * ```ts
+ * import { compile } from "@nubbin/core";
+ * import { createFsArtifactStore } from "@nubbin/store-fs";
+ *
+ * const store = createFsArtifactStore("./.nubbin");
+ *
+ * const { artifact } = compile(version, catalog, registry, "/promotions/summer");
+ * await store.write(artifact);
+ * await store.publish(artifact.route, artifact.hash);
+ * ```
+ *
+ * @example Serve a request from the store
+ * ```ts
+ * const pointer = await store.pointer("/promotions/summer");
+ * const artifact = pointer === null ? null : await store.read(pointer.hash);
+ * ```
+ *
+ * @example Roll a route back to what it pointed at before
+ * ```ts
+ * const moves = await store.history?.("/promotions/summer") ?? [];
+ * const previous = moves.at(-2);
+ * if (previous !== undefined) {
+ *   await store.publish("/promotions/summer", previous.hash);
+ * }
+ * ```
  */
 declare function createFsArtifactStore(root: string): ArtifactStore;
 

package/dist/index.js

@@ -4,15 +4,25 @@ function artifactPath(root, hash) {
   return join(root, "artifacts", `${hash}.json`);
 }
 
-// src/fsManifest.ts
-import { readdir } from "fs/promises";
+// src/historyPath.ts
 import { join as join2 } from "path";
 
-// src/readJsonOrNull.ts
+// src/encodeRouteKey.ts
+function encodeRouteKey(route) {
+  return encodeURIComponent(route);
+}
+
+// src/historyPath.ts
+function historyPath(root, route) {
+  const key = encodeRouteKey(route);
+  return join2(root, "history", `${key}.jsonl`);
+}
+
+// src/readFileOrNull.ts
 import { readFile } from "fs/promises";
-async function readJsonOrNull(filePath) {
+async function readFileOrNull(filePath) {
   try {
-    return JSON.parse(await readFile(filePath, "utf8"));
+    return await readFile(filePath, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       return null;
@@ -21,9 +31,28 @@ async function readJsonOrNull(filePath) {
   }
 }
 
+// src/fsHistory.ts
+async function fsHistory(root, route) {
+  const log = await readFileOrNull(historyPath(root, route));
+  if (log === null) {
+    return [];
+  }
+  return log.split("\n").filter((line) => line !== "").map((line) => JSON.parse(line));
+}
+
+// src/fsManifest.ts
+import { readdir } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/readJsonOrNull.ts
+async function readJsonOrNull(filePath) {
+  const text = await readFileOrNull(filePath);
+  return text === null ? null : JSON.parse(text);
+}
+
 // src/fsManifest.ts
 async function fsManifest(root) {
-  const directory = join2(root, "routes");
+  const directory = join3(root, "routes");
   let entries;
   try {
     entries = await readdir(directory);
@@ -33,7 +62,7 @@ async function fsManifest(root) {
     }
     entries = [];
   }
-  const read = entries.map((entry) => readJsonOrNull(join2(directory, entry)));
+  const read = entries.map((entry) => readJsonOrNull(join3(directory, entry)));
   const routes = (await Promise.all(read)).filter((pointer) => pointer !== null);
   return { routes, generatedAt: (/* @__PURE__ */ new Date()).toISOString() };
 }
@@ -41,25 +70,28 @@ async function fsManifest(root) {
 // src/fsPublish.ts
 import { NubbinIssueCode, parseMatchKind, refuse } from "@nubbin/core";
 
-// src/pointerPath.ts
-import { join as join3 } from "path";
-
-// src/encodeRouteKey.ts
-function encodeRouteKey(route) {
-  return encodeURIComponent(route);
+// src/appendJsonLine.ts
+import { appendFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+async function appendJsonLine(filePath, value) {
+  const line = `${JSON.stringify(value)}
+`;
+  await mkdir(dirname(filePath), { recursive: true });
+  await appendFile(filePath, line);
 }
 
 // src/pointerPath.ts
+import { join as join4 } from "path";
 function pointerPath(root, route) {
-  return join3(root, "routes", `${encodeRouteKey(route)}.json`);
+  return join4(root, "routes", `${encodeRouteKey(route)}.json`);
 }
 
 // src/writeJsonAtomic.ts
-import { mkdir, rename, writeFile } from "fs/promises";
-import { dirname } from "path";
+import { mkdir as mkdir2, rename, writeFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
 var writes = 0;
 async function writeJsonAtomic(filePath, value) {
-  await mkdir(dirname(filePath), { recursive: true });
+  await mkdir2(dirname2(filePath), { recursive: true });
   writes += 1;
   const temp = `${filePath}.${process.pid}.${writes}.tmp`;
   await writeFile(temp, JSON.stringify(value, null, 2));
@@ -68,7 +100,8 @@ async function writeJsonAtomic(filePath, value) {
 
 // src/fsPublish.ts
 async function fsPublish(root, route, hash) {
-  if (!await readJsonOrNull(artifactPath(root, hash))) {
+  const artifact = await readJsonOrNull(artifactPath(root, hash));
+  if (artifact === null) {
     refuse(
       NubbinIssueCode.ArtifactNotStored,
       `cannot publish ${route}: artifact ${hash} is not in the store`,
@@ -82,6 +115,11 @@ async function fsPublish(root, route, hash) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   await writeJsonAtomic(pointerPath(root, route), pointer);
+  await appendJsonLine(historyPath(root, route), {
+    hash,
+    documentVersion: artifact.documentVersion,
+    movedAt: pointer.updatedAt
+  });
 }
 
 // src/fsUnpublish.ts
@@ -107,7 +145,8 @@ function createFsArtifactStore(root) {
     pointer: (route) => readJsonOrNull(pointerPath(root, route)),
     manifest: () => fsManifest(root),
     publish: (route, hash) => fsPublish(root, route, hash),
-    unpublish: (route) => fsUnpublish(root, route)
+    unpublish: (route) => fsUnpublish(root, route),
+    history: (route) => fsHistory(root, route)
   };
 }
 export {

package/dist/testing/index.d.ts

@@ -0,0 +1,15 @@
+import { Artifact, ArtifactStore } from '@nubbin/core';
+
+/** A minimal valid artifact; hash and route parameterized because the contract keys on both. */
+declare function artifactFixture(hash: string, route: string): Artifact;
+
+/** The reference implementation the contract suite defines equivalence against. Test-only. */
+declare function createMemoryArtifactStore(): ArtifactStore;
+
+/**
+ * One suite, every implementation. An adapter passing by eye instead of by execution is the
+ * failure this exists to prevent.
+ */
+declare function runArtifactStoreContract(name: string, makeStore: () => Promise<ArtifactStore>): void;
+
+export { artifactFixture, createMemoryArtifactStore, runArtifactStoreContract };

package/dist/testing/index.js

@@ -0,0 +1,181 @@
+// src/testing/artifactFixture.ts
+function artifactFixture(hash, route) {
+  return {
+    hash,
+    route,
+    documentId: "d1",
+    documentVersion: 1,
+    blockVersions: { Hero: 1 },
+    tree: [],
+    meta: { title: "t" },
+    compiledWith: "0.0.0"
+  };
+}
+
+// src/testing/createMemoryArtifactStore.ts
+import { NubbinIssueCode, parseMatchKind, refuse } from "@nubbin/core";
+function createMemoryArtifactStore() {
+  const artifacts = /* @__PURE__ */ new Map();
+  const pointers = /* @__PURE__ */ new Map();
+  const moves = /* @__PURE__ */ new Map();
+  return {
+    read: async (hash) => artifacts.get(hash) ?? null,
+    write: async (artifact) => {
+      if (!artifacts.has(artifact.hash)) {
+        artifacts.set(artifact.hash, artifact);
+      }
+    },
+    pointer: async (route) => pointers.get(route) ?? null,
+    publish: async (route, hash) => {
+      const artifact = artifacts.get(hash);
+      if (artifact === void 0) {
+        refuse(
+          NubbinIssueCode.ArtifactNotStored,
+          `cannot publish ${route}: artifact ${hash} is not in the store`,
+          route
+        );
+      }
+      const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      pointers.set(route, { route, matchKind: parseMatchKind(route), hash, updatedAt });
+      const trail = moves.get(route) ?? [];
+      trail.push({ hash, documentVersion: artifact.documentVersion, movedAt: updatedAt });
+      moves.set(route, trail);
+    },
+    unpublish: async (route) => {
+      pointers.delete(route);
+    },
+    manifest: async () => ({
+      routes: [...pointers.values()],
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }),
+    // Copied on the way out, so a caller mutating the answer cannot edit the record.
+    history: async (route) => [...moves.get(route) ?? []]
+  };
+}
+
+// src/testing/runArtifactStoreContract.ts
+import { describe, expect as expect3, test as test3 } from "vitest";
+
+// src/testing/runHistoryContract.ts
+import { expect, test } from "vitest";
+function runHistoryContract(makeStore) {
+  const storeWithHistory = async (ctx) => {
+    const store = await makeStore();
+    if (store.history === void 0) ctx.skip();
+    return store;
+  };
+  test("history records every publish in order, oldest first", async (ctx) => {
+    const store = await storeWithHistory(ctx);
+    await store.write(artifactFixture("a1", "/x"));
+    await store.write(artifactFixture("a2", "/x"));
+    await store.publish("/x", "a1");
+    await store.publish("/x", "a2");
+    const moves = await store.history?.("/x") ?? [];
+    expect(moves.map((move) => move.hash)).toEqual(["a1", "a2"]);
+    expect(moves.every((move) => move.documentVersion === 1)).toBe(true);
+  });
+  test("only published states appear \u2014 a written artifact is not a move", async (ctx) => {
+    const store = await storeWithHistory(ctx);
+    await store.write(artifactFixture("a1", "/x"));
+    expect(await store.history?.("/x")).toEqual([]);
+  });
+  test("unpublish leaves the trail \u2014 a route taken down and put back keeps it", async (ctx) => {
+    const store = await storeWithHistory(ctx);
+    await store.write(artifactFixture("a1", "/x"));
+    await store.publish("/x", "a1");
+    await store.unpublish("/x");
+    expect((await store.history?.("/x") ?? []).map((move) => move.hash)).toEqual(["a1"]);
+  });
+  test("republishing the same hash is a second move \u2014 dedupe is for artifacts", async (ctx) => {
+    const store = await storeWithHistory(ctx);
+    await store.write(artifactFixture("a1", "/x"));
+    await store.publish("/x", "a1");
+    await store.publish("/x", "a1");
+    expect((await store.history?.("/x") ?? []).map((move) => move.hash)).toEqual(["a1", "a1"]);
+  });
+}
+
+// src/testing/runPointerRaceContract.ts
+import { expect as expect2, test as test2 } from "vitest";
+var WRITERS = ["a1", "a2", "a3", "a4", "a5", "a6", "a7", "a8"];
+function runPointerRaceContract(makeStore) {
+  test2("publishes racing for one route leave a whole winner, never a torn pointer", async () => {
+    const store = await makeStore();
+    await store.write(artifactFixture("a1", "/x"));
+    await store.write(artifactFixture("a2", "/x"));
+    await Promise.all([store.publish("/x", "a1"), store.publish("/x", "a2")]);
+    const pointer = await store.pointer("/x");
+    expect2(pointer).not.toBeNull();
+    expect2(["a1", "a2"]).toContain(pointer?.hash);
+  });
+  test2("many concurrent publishes to one route all settle, leaving one pointer", async () => {
+    const store = await makeStore();
+    for (const hash of WRITERS) {
+      await store.write(artifactFixture(hash, "/x"));
+    }
+    await Promise.all(WRITERS.map((hash) => store.publish("/x", hash)));
+    expect2(WRITERS).toContain((await store.pointer("/x"))?.hash);
+    expect2((await store.manifest()).routes).toHaveLength(1);
+  });
+}
+
+// src/testing/runArtifactStoreContract.ts
+function runArtifactStoreContract(name, makeStore) {
+  describe(`ArtifactStore contract: ${name}`, () => {
+    test3("write then read round-trips; an unknown hash reads null", async () => {
+      const store = await makeStore();
+      const artifact = artifactFixture("a1", "/x");
+      await store.write(artifact);
+      expect3(await store.read("a1")).toEqual(artifact);
+      expect3(await store.read("ghost")).toBeNull();
+    });
+    test3("writing an already-stored hash again is a no-op, not an error", async () => {
+      const store = await makeStore();
+      await store.write(artifactFixture("a1", "/x"));
+      await expect3(store.write(artifactFixture("a1", "/x"))).resolves.toBeUndefined();
+    });
+    test3("publish writes a pointer with matchKind parsed from the route", async () => {
+      const store = await makeStore();
+      await store.write(artifactFixture("a1", "/x"));
+      await store.publish("/x", "a1");
+      const pointer = await store.pointer("/x");
+      expect3(pointer?.hash).toBe("a1");
+      expect3(pointer?.matchKind).toBe("exact");
+      expect3(await store.pointer("/never")).toBeNull();
+    });
+    test3("publish rejects a hash that was never written \u2014 no dead pointers", async () => {
+      const store = await makeStore();
+      await expect3(store.publish("/x", "ghost")).rejects.toThrow(/ghost/);
+    });
+    test3("publishing the same route and hash twice is a safe no-op", async () => {
+      const store = await makeStore();
+      await store.write(artifactFixture("a1", "/x"));
+      await store.publish("/x", "a1");
+      await expect3(store.publish("/x", "a1")).resolves.toBeUndefined();
+    });
+    test3("unpublish removes the pointer, keeps the artifact, and tolerates a missing pointer", async () => {
+      const store = await makeStore();
+      await store.write(artifactFixture("a1", "/x"));
+      await store.publish("/x", "a1");
+      await store.unpublish("/x");
+      expect3(await store.pointer("/x")).toBeNull();
+      expect3(await store.read("a1")).not.toBeNull();
+      await expect3(store.unpublish("/x")).resolves.toBeUndefined();
+    });
+    test3("publishes to different routes never contend, and manifest lists them all", async () => {
+      const store = await makeStore();
+      await store.write(artifactFixture("a1", "/x"));
+      await store.write(artifactFixture("a2", "/y"));
+      await Promise.all([store.publish("/x", "a1"), store.publish("/y", "a2")]);
+      const { routes } = await store.manifest();
+      expect3(routes.map((pointer) => pointer.route).sort()).toEqual(["/x", "/y"]);
+    });
+    runPointerRaceContract(makeStore);
+    runHistoryContract(makeStore);
+  });
+}
+export {
+  artifactFixture,
+  createMemoryArtifactStore,
+  runArtifactStoreContract
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/store-fs",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The reference artifact store for Nubbin: one file per artifact, one pointer file per route, and no aggregate to lose a write.",
   "keywords": [
     "nubbin",
@@ -23,6 +23,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -32,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nubbin/core": "0.1.1"
+    "@nubbin/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "25.9.2",
@@ -40,6 +44,14 @@
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
+  "peerDependencies": {
+    "vitest": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",