@fedify/testing 2.5.0-dev.2761 → 2.5.0-dev.2766

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/mod.d.cts CHANGED
@@ -2,7 +2,7 @@
2
2
  import { Context, Federation, InboxContext, OutboxContext, PortableRequest, RequestContext } from "@fedify/fedify/federation";
3
3
  import { Activity } from "@fedify/vocab";
4
4
  import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
5
- import { KvStore, MessageQueue } from "@fedify/fedify";
5
+ import { AtomicKvStore, KvKey, KvStore, KvStoreCasEntry, KvStoreSetEntry, MessageQueue } from "@fedify/fedify";
6
6
 
7
7
  //#region src/context.d.ts
8
8
  declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -300,4 +300,108 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
300
300
  declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
301
301
  declare const getRandomKey: (prefix: string) => string;
302
302
  //#endregion
303
- export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };
303
+ //#region src/atomic-kv-tester.d.ts
304
+ /**
305
+ * Two clients sharing a fresh, isolated backing store for one conformance case.
306
+ * Persistent adapters must use independent clients. Memory implementations
307
+ * may return the same instance twice. The factory owns cleanup if construction
308
+ * fails before it returns this pair.
309
+ * @since 2.5.0
310
+ */
311
+ interface AtomicKvStoreTestPair {
312
+ /** The first client. */
313
+ readonly first: AtomicKvStore;
314
+ /** The second client, sharing the first client's backing store. */
315
+ readonly second: AtomicKvStore;
316
+ /** Releases both clients and their isolated backing state. */
317
+ dispose(): void | Promise<void>;
318
+ }
319
+ /**
320
+ * Calls that exceed a backend's documented batch limits or atomic key scope.
321
+ * Keys must be individually usable by ordinary store operations. Mutation
322
+ * probes must contain distinct keys and attempt observable changes. CAS
323
+ * expectations are seeded before testing the rejection. Supply supported
324
+ * values and TTLs so rejection tests the intended limit or scope.
325
+ * @since 2.5.0
326
+ */
327
+ interface TestAtomicKvStoreRejections {
328
+ /** An unsupported snapshot read. */
329
+ readonly getMany?: readonly KvKey[];
330
+ /** An unsupported unconditional write. */
331
+ readonly setMany?: readonly KvStoreSetEntry[];
332
+ /** An unsupported deletion. */
333
+ readonly deleteMany?: readonly KvKey[];
334
+ /** An unsupported conditional write. */
335
+ readonly casMany?: readonly KvStoreCasEntry[];
336
+ }
337
+ /**
338
+ * Configuration for {@link testAtomicKvStore}.
339
+ * @since 2.5.0
340
+ */
341
+ interface TestAtomicKvStoreOptions {
342
+ /**
343
+ * Positive expiry-test timing. Defaults to a 500 ms TTL and a 1 s wait.
344
+ * Choose a wait longer than the backend's rounded TTL and expected latency.
345
+ * Zero and negative TTL policies are adapter-specific and are not tested.
346
+ */
347
+ readonly ttl?: {
348
+ readonly short: Temporal.Duration;
349
+ readonly wait: Temporal.Duration;
350
+ };
351
+ /**
352
+ * Maps generated keys into the backend's atomic scope, for example a Redis
353
+ * Cluster hash tag. The mapping must be injective and preserve structural
354
+ * key equality; it need not preserve prefixes. Each case uses a fresh
355
+ * random key prefix before mapping.
356
+ */
357
+ readonly key?: (key: KvKey) => KvKey;
358
+ /**
359
+ * Whether reordered object members compare equally in CAS. Omit this to
360
+ * leave member-order behavior unspecified. Nested JSON round trips and
361
+ * single/batch CAS equivalence are always tested.
362
+ */
363
+ readonly objectKeyOrder?: "ignored" | "significant";
364
+ /**
365
+ * Supplies optional backend limit/scope probes. The key factory already
366
+ * applies {@link TestAtomicKvStoreOptions.key}; returned keys are used
367
+ * verbatim and may deliberately cross atomic scopes. Each probe runs on
368
+ * a fresh pair. Oversized operations must reject rather than return false
369
+ * or partially commit. No universal batch maximum is assumed.
370
+ */
371
+ readonly rejections?: (key: (...segments: string[]) => KvKey) => TestAtomicKvStoreRejections;
372
+ }
373
+ /**
374
+ * Tests an {@link AtomicKvStore} using fresh client pairs for independent cases.
375
+ *
376
+ * Covers ordered snapshot reads, all-or-nothing writes/deletes/CAS, absent-key
377
+ * races, single/batch CAS interaction, logical expiry, validation, and optional
378
+ * backend-limit probes. Baseline successful calls use at most three keys or
379
+ * entries; choose a backend scope that supports them. Concurrent checks use
380
+ * bounded repetition; they are
381
+ * not an exhaustive linearizability proof. Add adapter-specific transaction
382
+ * rollback, injected-failure, persistence, and supported-isolation tests.
383
+ * Run `testKvStore()` separately for ordinary KV and prefix-listing behavior.
384
+ *
385
+ * All started racing operations settle before pair disposal, even when an
386
+ * assertion fails. Assertion and disposal errors are retained together in
387
+ * an {@link AggregateError}. Configure TTL timing for the adapter's documented
388
+ * expiry precision and expected operation latency.
389
+ *
390
+ * @example
391
+ * ```typescript ignore
392
+ * import { test } from "node:test";
393
+ * import { MemoryKvStore } from "@fedify/fedify";
394
+ * import { testAtomicKvStore } from "@fedify/testing";
395
+ *
396
+ * test("Memory atomic contract", () => testAtomicKvStore(() => {
397
+ * const store = new MemoryKvStore();
398
+ * return { first: store, second: store, dispose() {} };
399
+ * }, { objectKeyOrder: "ignored" }));
400
+ * ```
401
+ * @param createPair Creates a fresh pair sharing isolated backing state.
402
+ * @param options Backend scope, comparison, expiry, and rejection probes.
403
+ * @since 2.5.0
404
+ */
405
+ declare function testAtomicKvStore(createPair: () => AtomicKvStoreTestPair | Promise<AtomicKvStoreTestPair>, options?: TestAtomicKvStoreOptions): Promise<void>;
406
+ //#endregion
407
+ export { type AtomicKvStoreTestPair, type TestAtomicKvStoreOptions, type TestAtomicKvStoreRejections, type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testAtomicKvStore, testKvStore, testMessageQueue, waitFor };
package/dist/mod.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  import { Activity } from "@fedify/vocab";
3
3
  import { DocumentLoader, PortableObjectVerifier } from "@fedify/vocab-runtime";
4
4
  import { Context, Federation, InboxContext, OutboxContext, PortableRequest, RequestContext } from "@fedify/fedify/federation";
5
- import { KvStore, MessageQueue } from "@fedify/fedify";
5
+ import { AtomicKvStore, KvKey, KvStore, KvStoreCasEntry, KvStoreSetEntry, MessageQueue } from "@fedify/fedify";
6
6
 
7
7
  //#region src/context.d.ts
8
8
  declare function createContext<TContextData>(values: Partial<Context<TContextData>> & {
@@ -300,4 +300,108 @@ declare function testMessageQueue<MQ extends MessageQueue>(getMessageQueue: () =
300
300
  declare function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void>;
301
301
  declare const getRandomKey: (prefix: string) => string;
302
302
  //#endregion
303
- export { type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testKvStore, testMessageQueue, waitFor };
303
+ //#region src/atomic-kv-tester.d.ts
304
+ /**
305
+ * Two clients sharing a fresh, isolated backing store for one conformance case.
306
+ * Persistent adapters must use independent clients. Memory implementations
307
+ * may return the same instance twice. The factory owns cleanup if construction
308
+ * fails before it returns this pair.
309
+ * @since 2.5.0
310
+ */
311
+ interface AtomicKvStoreTestPair {
312
+ /** The first client. */
313
+ readonly first: AtomicKvStore;
314
+ /** The second client, sharing the first client's backing store. */
315
+ readonly second: AtomicKvStore;
316
+ /** Releases both clients and their isolated backing state. */
317
+ dispose(): void | Promise<void>;
318
+ }
319
+ /**
320
+ * Calls that exceed a backend's documented batch limits or atomic key scope.
321
+ * Keys must be individually usable by ordinary store operations. Mutation
322
+ * probes must contain distinct keys and attempt observable changes. CAS
323
+ * expectations are seeded before testing the rejection. Supply supported
324
+ * values and TTLs so rejection tests the intended limit or scope.
325
+ * @since 2.5.0
326
+ */
327
+ interface TestAtomicKvStoreRejections {
328
+ /** An unsupported snapshot read. */
329
+ readonly getMany?: readonly KvKey[];
330
+ /** An unsupported unconditional write. */
331
+ readonly setMany?: readonly KvStoreSetEntry[];
332
+ /** An unsupported deletion. */
333
+ readonly deleteMany?: readonly KvKey[];
334
+ /** An unsupported conditional write. */
335
+ readonly casMany?: readonly KvStoreCasEntry[];
336
+ }
337
+ /**
338
+ * Configuration for {@link testAtomicKvStore}.
339
+ * @since 2.5.0
340
+ */
341
+ interface TestAtomicKvStoreOptions {
342
+ /**
343
+ * Positive expiry-test timing. Defaults to a 500 ms TTL and a 1 s wait.
344
+ * Choose a wait longer than the backend's rounded TTL and expected latency.
345
+ * Zero and negative TTL policies are adapter-specific and are not tested.
346
+ */
347
+ readonly ttl?: {
348
+ readonly short: Temporal.Duration;
349
+ readonly wait: Temporal.Duration;
350
+ };
351
+ /**
352
+ * Maps generated keys into the backend's atomic scope, for example a Redis
353
+ * Cluster hash tag. The mapping must be injective and preserve structural
354
+ * key equality; it need not preserve prefixes. Each case uses a fresh
355
+ * random key prefix before mapping.
356
+ */
357
+ readonly key?: (key: KvKey) => KvKey;
358
+ /**
359
+ * Whether reordered object members compare equally in CAS. Omit this to
360
+ * leave member-order behavior unspecified. Nested JSON round trips and
361
+ * single/batch CAS equivalence are always tested.
362
+ */
363
+ readonly objectKeyOrder?: "ignored" | "significant";
364
+ /**
365
+ * Supplies optional backend limit/scope probes. The key factory already
366
+ * applies {@link TestAtomicKvStoreOptions.key}; returned keys are used
367
+ * verbatim and may deliberately cross atomic scopes. Each probe runs on
368
+ * a fresh pair. Oversized operations must reject rather than return false
369
+ * or partially commit. No universal batch maximum is assumed.
370
+ */
371
+ readonly rejections?: (key: (...segments: string[]) => KvKey) => TestAtomicKvStoreRejections;
372
+ }
373
+ /**
374
+ * Tests an {@link AtomicKvStore} using fresh client pairs for independent cases.
375
+ *
376
+ * Covers ordered snapshot reads, all-or-nothing writes/deletes/CAS, absent-key
377
+ * races, single/batch CAS interaction, logical expiry, validation, and optional
378
+ * backend-limit probes. Baseline successful calls use at most three keys or
379
+ * entries; choose a backend scope that supports them. Concurrent checks use
380
+ * bounded repetition; they are
381
+ * not an exhaustive linearizability proof. Add adapter-specific transaction
382
+ * rollback, injected-failure, persistence, and supported-isolation tests.
383
+ * Run `testKvStore()` separately for ordinary KV and prefix-listing behavior.
384
+ *
385
+ * All started racing operations settle before pair disposal, even when an
386
+ * assertion fails. Assertion and disposal errors are retained together in
387
+ * an {@link AggregateError}. Configure TTL timing for the adapter's documented
388
+ * expiry precision and expected operation latency.
389
+ *
390
+ * @example
391
+ * ```typescript ignore
392
+ * import { test } from "node:test";
393
+ * import { MemoryKvStore } from "@fedify/fedify";
394
+ * import { testAtomicKvStore } from "@fedify/testing";
395
+ *
396
+ * test("Memory atomic contract", () => testAtomicKvStore(() => {
397
+ * const store = new MemoryKvStore();
398
+ * return { first: store, second: store, dispose() {} };
399
+ * }, { objectKeyOrder: "ignored" }));
400
+ * ```
401
+ * @param createPair Creates a fresh pair sharing isolated backing state.
402
+ * @param options Backend scope, comparison, expiry, and rejection probes.
403
+ * @since 2.5.0
404
+ */
405
+ declare function testAtomicKvStore(createPair: () => AtomicKvStoreTestPair | Promise<AtomicKvStoreTestPair>, options?: TestAtomicKvStoreOptions): Promise<void>;
406
+ //#endregion
407
+ export { type AtomicKvStoreTestPair, type TestAtomicKvStoreOptions, type TestAtomicKvStoreRejections, type TestKvStoreOptions, type TestMessageQueueOptions, createContext, createFederation, createInboxContext, createOutboxContext, createRequestContext, getRandomKey, testAtomicKvStore, testKvStore, testMessageQueue, waitFor };