@fedify/testing 2.5.0-dev.2758 → 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/README.md +117 -0
- package/dist/mod.cjs +754 -10
- package/dist/mod.d.cts +106 -2
- package/dist/mod.d.ts +106 -2
- package/dist/mod.js +744 -2
- package/package.json +4 -4
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
|
-
|
|
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
|
-
|
|
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 };
|