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

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