@nubbin/store-fs 0.2.0 → 0.3.0

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.2.0",
+  "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.2.0"
+    "@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",