@fedify/testing 2.4.0-dev.1909 → 2.4.0-dev.1919

package/README.md

@@ -95,6 +95,33 @@ The package also exports helper functions for creating various context types:
  -  `createRequestContext()`: Creates a request context
  -  `createInboxContext()`: Creates an inbox context
 
+### Store conformance tests
+
+The package provides reusable conformance suites for Fedify storage adapters.
+Use `testKvStore()` to check a `KvStore` implementation and
+`testMessageQueue()` to check a `MessageQueue` implementation:
+
+~~~~ typescript
+import { test } from "@fedify/fixture";
+import { testKvStore, testMessageQueue } from "@fedify/testing";
+
+test("MyKvStore", () =>
+  testKvStore(
+    () => new MyKvStore(),
+    async ({ store }) => await store.close(),
+  ));
+
+test("MyMessageQueue", () =>
+  testMessageQueue(
+    () => new MyMessageQueue(),
+    async ({ mq1, mq2, controller }) => {
+      controller.abort();
+      await mq1.close();
+      await mq2.close();
+    },
+  ));
+~~~~
+
 
 Features
 --------

package/dist/mod.cjs

@@ -4523,7 +4523,7 @@ const Now = /*@__PURE__*/ Object.defineProperties({}, {
 		}
 	})
 });
-const Temporal$2 = /*@__PURE__*/ Object.defineProperties({}, {
+const Temporal$3 = /*@__PURE__*/ Object.defineProperties({}, {
 	...createStringTagDescriptors("Temporal"),
 	...createPropDescriptors({
 		PlainYearMonth,
@@ -4539,11 +4539,153 @@ const Temporal$2 = /*@__PURE__*/ Object.defineProperties({}, {
 });
 //#endregion
 //#region ../../node_modules/.pnpm/temporal-polyfill@1.0.1/node_modules/temporal-polyfill/index.js
-const Temporal$1 = NativeTemporal || Temporal$2;
+const Temporal$2 = NativeTemporal || Temporal$3;
 NativeTemporal && Date.prototype.toTemporalInstant;
 //#endregion
+//#region src/kv-tester.ts
+const Temporal$1 = Temporal$2;
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+async function testKvStore(getKvStore, onFinally, options = {}) {
+	const store = await getKvStore();
+	const prefix = [`fedify_test_${crypto.randomUUID()}`];
+	const key = (...segments) => [...prefix, ...segments];
+	try {
+		(0, node_assert_strict.strictEqual)(await store.get(key("missing")), void 0);
+		for (const [index, value] of [
+			"text",
+			42,
+			true,
+			null,
+			[
+				1,
+				"two",
+				false
+			],
+			{ nested: { value: "test" } }
+		].entries()) {
+			const valueKey = key("values", index.toString());
+			await store.set(valueKey, value);
+			(0, node_assert_strict.deepStrictEqual)(await store.get(valueKey), value);
+		}
+		const overwriteKey = key("overwrite");
+		await store.set(overwriteKey, "before");
+		await store.set(overwriteKey, "after");
+		(0, node_assert_strict.strictEqual)(await store.get(overwriteKey), "after");
+		const deleteKey = key("delete");
+		await store.set(deleteKey, "value");
+		await store.delete(deleteKey);
+		(0, node_assert_strict.strictEqual)(await store.get(deleteKey), void 0);
+		await store.delete(deleteKey);
+		const isolatedKeys = [
+			key("a", "b"),
+			key("a,b"),
+			key("a:b")
+		];
+		for (const [index, isolatedKey] of isolatedKeys.entries()) await store.set(isolatedKey, index);
+		for (const [index, isolatedKey] of isolatedKeys.entries()) (0, node_assert_strict.strictEqual)(await store.get(isolatedKey), index);
+		if (options.testTtl ?? true) {
+			const expiringKey = key("ttl", "expiring");
+			await store.set(expiringKey, "expired", { ttl: Temporal$1.Duration.from({ milliseconds: 50 }) });
+			await (0, es_toolkit.delay)(100);
+			(0, node_assert_strict.strictEqual)(await store.get(expiringKey), void 0);
+			(0, node_assert_strict.deepStrictEqual)(await collect(store.list(key("ttl"))), []);
+			const refreshedKey = key("ttl", "refreshed");
+			await store.set(refreshedKey, "temporary", { ttl: Temporal$1.Duration.from({ milliseconds: 50 }) });
+			await store.set(refreshedKey, "persistent");
+			await (0, es_toolkit.delay)(100);
+			(0, node_assert_strict.strictEqual)(await store.get(refreshedKey), "persistent");
+		}
+		const listPrefix = key("list");
+		const listEntries = [
+			{
+				key: listPrefix,
+				value: "exact"
+			},
+			{
+				key: key("list", "child"),
+				value: "child"
+			},
+			{
+				key: key("list", "child", "nested"),
+				value: "nested"
+			},
+			{
+				key: key("list-other"),
+				value: "other"
+			}
+		];
+		for (const entry of listEntries) await store.set(entry.key, entry.value);
+		(0, node_assert_strict.deepStrictEqual)(normalize(await collect(store.list(listPrefix))), normalize(listEntries.slice(0, 3)));
+		const prefixedEntries = await collect(store.list(prefix));
+		(0, node_assert_strict.deepStrictEqual)(normalize(filterByPrefix(await collect(store.list()), prefix)), normalize(prefixedEntries));
+		(0, node_assert_strict.deepStrictEqual)(normalize(filterByPrefix(await collect(store.list([])), prefix)), normalize(prefixedEntries));
+		if (options.testCas ?? store.cas != null) {
+			if (store.cas == null) throw new TypeError("KvStore.cas is not implemented");
+			const cas = store.cas.bind(store);
+			const casKey = key("cas", "value");
+			(0, node_assert_strict.strictEqual)(await cas(casKey, "wrong", "value"), false);
+			(0, node_assert_strict.strictEqual)(await cas(casKey, void 0, "created"), true);
+			(0, node_assert_strict.strictEqual)(await cas(casKey, "wrong", "updated"), false);
+			(0, node_assert_strict.strictEqual)(await cas(casKey, "created", "updated"), true);
+			(0, node_assert_strict.strictEqual)(await store.get(casKey), "updated");
+			(0, node_assert_strict.strictEqual)(await cas(casKey, "updated", void 0), true);
+			(0, node_assert_strict.strictEqual)(await store.get(casKey), void 0);
+			if (options.testTtl ?? true) {
+				const expiredCasKey = key("cas", "expired");
+				await store.set(expiredCasKey, "old", { ttl: Temporal$1.Duration.from({ milliseconds: 50 }) });
+				await (0, es_toolkit.delay)(100);
+				(0, node_assert_strict.strictEqual)(await cas(expiredCasKey, void 0, "replaced"), true);
+				const ttlCasKey = key("cas", "ttl");
+				(0, node_assert_strict.strictEqual)(await cas(ttlCasKey, void 0, "temporary", { ttl: Temporal$1.Duration.from({ milliseconds: 50 }) }), true);
+				await (0, es_toolkit.delay)(100);
+				(0, node_assert_strict.strictEqual)(await store.get(ttlCasKey), void 0);
+			}
+			const concurrentKey = key("cas", "concurrent");
+			(0, node_assert_strict.strictEqual)((await Promise.all(Array.from({ length: 8 }, (_, index) => cas(concurrentKey, void 0, index)))).filter(Boolean).length, 1);
+		}
+	} finally {
+		for await (const entry of store.list(prefix)) await store.delete(entry.key);
+		await onFinally({ store });
+	}
+}
+async function collect(entries) {
+	const results = [];
+	for await (const entry of entries) results.push(entry);
+	return results;
+}
+function normalize(entries) {
+	return entries.map((entry) => JSON.stringify(entry)).sort();
+}
+function filterByPrefix(entries, prefix) {
+	return entries.filter((entry) => prefix.every((segment, index) => entry.key[index] === segment));
+}
+//#endregion
 //#region src/mq-tester.ts
-const Temporal = Temporal$1;
+const Temporal = Temporal$2;
 /**
 * Tests a {@link MessageQueue} implementation with a standard set of tests.
 *
@@ -4729,5 +4871,6 @@ exports.createInboxContext = createInboxContext;
 exports.createOutboxContext = createOutboxContext;
 exports.createRequestContext = createRequestContext;
 exports.getRandomKey = getRandomKey;
+exports.testKvStore = testKvStore;
 exports.testMessageQueue = testMessageQueue;
 exports.waitFor = waitFor;

package/dist/mod.d.cts

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Context, Federation, InboxContext, OutboxContext, RequestContext } from "@fedify/fedify/federation";
 import { Activity } from "@fedify/vocab";
-import { MessageQueue } from "@fedify/fedify";
+import { KvStore, MessageQueue } from "@fedify/fedify";
 
 //#region src/context.d.ts
 declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -153,6 +153,53 @@ declare function createFederation<TContextData>(options?: {
   tracerProvider?: any;
 }): TestFederation<TContextData>;
 //#endregion
+//#region src/kv-tester.d.ts
+/**
+* Options for {@link testKvStore}.
+*/
+interface TestKvStoreOptions {
+  /**
+  * Whether to test compare-and-swap support.  By default, these tests run
+  * when the store implements {@link KvStore.cas}.
+  */
+  readonly testCas?: boolean;
+  /**
+  * Whether to test time-to-live support.  `true` by default.
+  * @default true
+  */
+  readonly testTtl?: boolean;
+}
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+declare function testKvStore<KV extends KvStore>(getKvStore: () => KV | Promise<KV>, onFinally: ({
+  store
+}: {
+  store: KV;
+}) => Promise<void> | void, options?: TestKvStoreOptions): Promise<void>;
+//#endregion
 //#region src/mq-tester.d.ts
 /**
 * Options for {@link testMessageQueue}.
@@ -223,4 +270,4 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
 declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
 declare const getRandomKey: (prefix: string) => string;
 //#endregion
-export { type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testMessageQueue, waitFor };
+export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };

package/dist/mod.d.ts

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { Activity } from "@fedify/vocab";
 import { Context, Federation, InboxContext, OutboxContext, RequestContext } from "@fedify/fedify/federation";
-import { MessageQueue } from "@fedify/fedify";
+import { KvStore, MessageQueue } from "@fedify/fedify";
 
 //#region src/context.d.ts
 declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -153,6 +153,53 @@ declare function createFederation<TContextData>(options?: {
   tracerProvider?: any;
 }): TestFederation<TContextData>;
 //#endregion
+//#region src/kv-tester.d.ts
+/**
+* Options for {@link testKvStore}.
+*/
+interface TestKvStoreOptions {
+  /**
+  * Whether to test compare-and-swap support.  By default, these tests run
+  * when the store implements {@link KvStore.cas}.
+  */
+  readonly testCas?: boolean;
+  /**
+  * Whether to test time-to-live support.  `true` by default.
+  * @default true
+  */
+  readonly testTtl?: boolean;
+}
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+declare function testKvStore<KV extends KvStore>(getKvStore: () => KV | Promise<KV>, onFinally: ({
+  store
+}: {
+  store: KV;
+}) => Promise<void> | void, options?: TestKvStoreOptions): Promise<void>;
+//#endregion
 //#region src/mq-tester.d.ts
 /**
 * Options for {@link testMessageQueue}.
@@ -223,4 +270,4 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
 declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
 declare const getRandomKey: (prefix: string) => string;
 //#endregion
-export { type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testMessageQueue, waitFor };
+export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };

package/dist/mod.js

@@ -977,6 +977,147 @@ var MockContext = class MockContext {
 	}
 };
 //#endregion
+//#region src/kv-tester.ts
+/**
+* Tests a {@link KvStore} implementation with a standard set of tests.
+*
+* The suite covers reads and writes, deletion, structured keys and values,
+* prefix listing, TTL expiration, and optional compare-and-swap behavior.
+* Every key is isolated below a random prefix and is deleted after the suite.
+*
+* @example
+* ```typescript ignore
+* import { test } from "@fedify/fixture";
+* import { testKvStore } from "@fedify/testing";
+* import { MyKvStore } from "./my-kv.ts";
+*
+* test("MyKvStore", () =>
+*   testKvStore(
+*     () => new MyKvStore(),
+*     async ({ store }) => await store.close(),
+*   )
+* );
+* ```
+*
+* @param getKvStore A factory that creates the store to test.
+* @param onFinally A cleanup function called after the suite completes.
+* @param options Optional configuration for the suite.
+*/
+async function testKvStore(getKvStore, onFinally, options = {}) {
+	const store = await getKvStore();
+	const prefix = [`fedify_test_${crypto.randomUUID()}`];
+	const key = (...segments) => [...prefix, ...segments];
+	try {
+		strictEqual(await store.get(key("missing")), void 0);
+		for (const [index, value] of [
+			"text",
+			42,
+			true,
+			null,
+			[
+				1,
+				"two",
+				false
+			],
+			{ nested: { value: "test" } }
+		].entries()) {
+			const valueKey = key("values", index.toString());
+			await store.set(valueKey, value);
+			deepStrictEqual(await store.get(valueKey), value);
+		}
+		const overwriteKey = key("overwrite");
+		await store.set(overwriteKey, "before");
+		await store.set(overwriteKey, "after");
+		strictEqual(await store.get(overwriteKey), "after");
+		const deleteKey = key("delete");
+		await store.set(deleteKey, "value");
+		await store.delete(deleteKey);
+		strictEqual(await store.get(deleteKey), void 0);
+		await store.delete(deleteKey);
+		const isolatedKeys = [
+			key("a", "b"),
+			key("a,b"),
+			key("a:b")
+		];
+		for (const [index, isolatedKey] of isolatedKeys.entries()) await store.set(isolatedKey, index);
+		for (const [index, isolatedKey] of isolatedKeys.entries()) strictEqual(await store.get(isolatedKey), index);
+		if (options.testTtl ?? true) {
+			const expiringKey = key("ttl", "expiring");
+			await store.set(expiringKey, "expired", { ttl: Temporal.Duration.from({ milliseconds: 50 }) });
+			await delay(100);
+			strictEqual(await store.get(expiringKey), void 0);
+			deepStrictEqual(await collect(store.list(key("ttl"))), []);
+			const refreshedKey = key("ttl", "refreshed");
+			await store.set(refreshedKey, "temporary", { ttl: Temporal.Duration.from({ milliseconds: 50 }) });
+			await store.set(refreshedKey, "persistent");
+			await delay(100);
+			strictEqual(await store.get(refreshedKey), "persistent");
+		}
+		const listPrefix = key("list");
+		const listEntries = [
+			{
+				key: listPrefix,
+				value: "exact"
+			},
+			{
+				key: key("list", "child"),
+				value: "child"
+			},
+			{
+				key: key("list", "child", "nested"),
+				value: "nested"
+			},
+			{
+				key: key("list-other"),
+				value: "other"
+			}
+		];
+		for (const entry of listEntries) await store.set(entry.key, entry.value);
+		deepStrictEqual(normalize(await collect(store.list(listPrefix))), normalize(listEntries.slice(0, 3)));
+		const prefixedEntries = await collect(store.list(prefix));
+		deepStrictEqual(normalize(filterByPrefix(await collect(store.list()), prefix)), normalize(prefixedEntries));
+		deepStrictEqual(normalize(filterByPrefix(await collect(store.list([])), prefix)), normalize(prefixedEntries));
+		if (options.testCas ?? store.cas != null) {
+			if (store.cas == null) throw new TypeError("KvStore.cas is not implemented");
+			const cas = store.cas.bind(store);
+			const casKey = key("cas", "value");
+			strictEqual(await cas(casKey, "wrong", "value"), false);
+			strictEqual(await cas(casKey, void 0, "created"), true);
+			strictEqual(await cas(casKey, "wrong", "updated"), false);
+			strictEqual(await cas(casKey, "created", "updated"), true);
+			strictEqual(await store.get(casKey), "updated");
+			strictEqual(await cas(casKey, "updated", void 0), true);
+			strictEqual(await store.get(casKey), void 0);
+			if (options.testTtl ?? true) {
+				const expiredCasKey = key("cas", "expired");
+				await store.set(expiredCasKey, "old", { ttl: Temporal.Duration.from({ milliseconds: 50 }) });
+				await delay(100);
+				strictEqual(await cas(expiredCasKey, void 0, "replaced"), true);
+				const ttlCasKey = key("cas", "ttl");
+				strictEqual(await cas(ttlCasKey, void 0, "temporary", { ttl: Temporal.Duration.from({ milliseconds: 50 }) }), true);
+				await delay(100);
+				strictEqual(await store.get(ttlCasKey), void 0);
+			}
+			const concurrentKey = key("cas", "concurrent");
+			strictEqual((await Promise.all(Array.from({ length: 8 }, (_, index) => cas(concurrentKey, void 0, index)))).filter(Boolean).length, 1);
+		}
+	} finally {
+		for await (const entry of store.list(prefix)) await store.delete(entry.key);
+		await onFinally({ store });
+	}
+}
+async function collect(entries) {
+	const results = [];
+	for await (const entry of entries) results.push(entry);
+	return results;
+}
+function normalize(entries) {
+	return entries.map((entry) => JSON.stringify(entry)).sort();
+}
+function filterByPrefix(entries, prefix) {
+	return entries.filter((entry) => prefix.every((segment, index) => entry.key[index] === segment));
+}
+//#endregion
 //#region src/mq-tester.ts
 /**
 * Tests a {@link MessageQueue} implementation with a standard set of tests.
@@ -1157,4 +1298,4 @@ async function waitFor(predicate, timeoutMs) {
 }
 const getRandomKey = (prefix) => `fedify_test_${prefix}_${crypto.randomUUID()}`;
 //#endregion
-export { createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testMessageQueue, waitFor };
+export { createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/testing",
-  "version": "2.4.0-dev.1909+065da803",
+  "version": "2.4.0-dev.1919+b6fdaec9",
   "description": "Testing utilities for Fedify applications",
   "keywords": [
     "fedify",
@@ -47,13 +47,13 @@
     "package.json"
   ],
   "peerDependencies": {
-    "@fedify/fedify": "^2.4.0-dev.1909+065da803"
+    "@fedify/fedify": "^2.4.0-dev.1919+b6fdaec9"
   },
   "dependencies": {
     "es-toolkit": "1.46.1",
     "temporal-polyfill": "^1.0.1",
-    "@fedify/vocab": "2.4.0-dev.1909+065da803",
-    "@fedify/vocab-runtime": "^2.4.0-dev.1909+065da803"
+    "@fedify/vocab-runtime": "^2.4.0-dev.1919+b6fdaec9",
+    "@fedify/vocab": "2.4.0-dev.1919+b6fdaec9"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",