@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/README.md CHANGED
@@ -137,3 +137,120 @@ Features
137
137
  - Configure custom URI templates
138
138
  - Test queue-based activity processing
139
139
  - Mock document loaders and context loaders
140
+
141
+
142
+ Atomic key–value store conformance
143
+ ----------------------------------
144
+
145
+ *This API is available since Fedify 2.5.0.*
146
+
147
+ Use `testAtomicKvStore()` to check an `AtomicKvStore` implementation. It
148
+ covers ordered snapshot reads, all-or-nothing batches, conditional updates and
149
+ deletions, competing clients, logical expiry, and validation. Run
150
+ `testKvStore()` separately for ordinary key–value behavior and prefix listing.
151
+
152
+ Each case calls the factory for a fresh pair of clients sharing isolated
153
+ backing state. Persistent adapters need independent handles connected to the
154
+ same backend. `MemoryKvStore` may return the same instance for both clients:
155
+
156
+ ~~~~ typescript
157
+ import { MemoryKvStore } from "@fedify/fedify";
158
+ import { testAtomicKvStore } from "@fedify/testing";
159
+ import { test } from "node:test";
160
+
161
+ test("Memory atomic contract", () => testAtomicKvStore(() => {
162
+ const store = new MemoryKvStore();
163
+ return {
164
+ first: store,
165
+ second: store,
166
+ dispose() {},
167
+ };
168
+ }, { objectKeyOrder: "ignored" }));
169
+ ~~~~
170
+
171
+ For persistent adapters, `dispose()` must close both clients and remove the
172
+ isolated backing state. If factory construction fails before returning a
173
+ pair, the factory must clean up any resources it already acquired. The helper
174
+ waits for all started concurrent operations before disposal. If an assertion
175
+ and disposal both fail, it retains both errors in an `AggregateError`.
176
+
177
+ The checks that are expected to succeed use batches of up to three keys or
178
+ entries. Configure a supported atomic scope large enough for those calls. The
179
+ `key` option can place generated keys in that scope, for example a common Redis
180
+ Cluster hash tag. The mapping must preserve distinct keys and structural key
181
+ equality; it need not preserve prefixes. Keys receive a fresh random prefix
182
+ before mapping.
183
+
184
+ `objectKeyOrder: "ignored"` checks that reordered object members compare equal
185
+ in single-key and batch compare-and-swap (CAS) operations. Use `"significant"`
186
+ for a codec that compares encoded JSON bytes. Omit the option when the adapter
187
+ makes neither promise; nested JSON round trips and type/array distinctions are
188
+ still checked.
189
+
190
+ TTL defaults are 500 ms for the short lifetime and 1 s for the expiry wait.
191
+ Override both (`ttl.short` and `ttl.wait`) with positive durations when a
192
+ backend rounds expiry or needs more time for network operations. The wait must
193
+ exceed the TTL after the backend's rounding, plus the expected latency. Zero
194
+ and negative TTL policies are adapter-specific and need separate adapter tests.
195
+
196
+ ### Limit and scope rejection probes
197
+
198
+ Provide `rejections()` to test documented backend limits or unsupported atomic
199
+ key scopes. The `rejections()` callback receives a key factory that already
200
+ applies the configured mapper. Returned keys are used verbatim. Every key
201
+ must be valid for individual store calls. The helper seeds each mutation key,
202
+ then verifies that rejection leaves it unchanged through individual reads. It
203
+ seeds CAS keys with the supplied expectations, including absence for expected
204
+ `undefined`. Supply distinct mutation keys, supported values and TTLs, and
205
+ changes that would be observable if incorrectly committed. Do not supply no-op
206
+ deletion probes on absent keys or CAS entries whose new value equals their
207
+ expectation.
208
+
209
+ For example, build probes from the adapter's documented maximum batch count,
210
+ rather than assuming a universal limit. This configuration example imports
211
+ `Temporal` from `temporal-polyfill`; install that package as a direct
212
+ development dependency when using the example in a runtime without native
213
+ Temporal:
214
+
215
+ ~~~~ typescript
216
+ import type { TestAtomicKvStoreOptions } from "@fedify/testing";
217
+ import { Temporal } from "temporal-polyfill";
218
+
219
+ function optionsForBatchLimit(maxEntries: number): TestAtomicKvStoreOptions {
220
+ return {
221
+ ttl: {
222
+ short: Temporal.Duration.from({ seconds: 1 }),
223
+ wait: Temporal.Duration.from({ seconds: 2 }),
224
+ },
225
+ key: (key) => ["{fedify-atomic-test}", ...key],
226
+ rejections: (makeKey) => {
227
+ const keys = Array.from(
228
+ { length: maxEntries + 1 },
229
+ (_, index) => makeKey("over-limit", String(index)),
230
+ );
231
+ return {
232
+ getMany: keys,
233
+ setMany: keys.map((key, index) => ({ key, value: index })),
234
+ deleteMany: keys,
235
+ casMany: keys.map((key, index) => ({
236
+ key,
237
+ expectedValue: index,
238
+ newValue: index + 1,
239
+ })),
240
+ };
241
+ },
242
+ };
243
+ }
244
+ ~~~~
245
+
246
+ This example assumes the documented count applies to all four operations.
247
+ When the limits differ, provide only the relevant operation probes or build
248
+ each from its own limit. For a scope probe, the callback can deliberately
249
+ return individually valid keys outside the shared atomic scope.
250
+
251
+ The concurrency checks repeat several races in both snapshot invocation
252
+ orders; they are not an exhaustive proof of linearizability. Add
253
+ backend-specific tests for competing handles, absent and expired entries,
254
+ rollback when a later write in the same batch fails, injected failures,
255
+ supported isolation levels, and reopen persistence. Method presence and
256
+ passing these shared checks do not establish crash durability.