@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 +117 -2
- 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/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.
|