@c9up/echo 0.2.2 → 0.2.4
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/CacheManager.d.ts +2 -0
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +92 -32
- package/dist/CacheManager.js.map +1 -1
- package/dist/EchoProvider.d.ts.map +1 -1
- package/dist/EchoProvider.js +32 -3
- package/dist/EchoProvider.js.map +1 -1
- package/dist/StoreManager.d.ts +28 -9
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +42 -18
- package/dist/StoreManager.js.map +1 -1
- package/dist/bytes.d.ts +13 -0
- package/dist/bytes.d.ts.map +1 -0
- package/dist/bytes.js +35 -0
- package/dist/bytes.js.map +1 -0
- package/dist/claim.d.ts +15 -0
- package/dist/claim.d.ts.map +1 -0
- package/dist/claim.js +10 -0
- package/dist/claim.js.map +1 -0
- package/dist/configure.d.ts +7 -0
- package/dist/configure.d.ts.map +1 -1
- package/dist/configure.js +5 -18
- package/dist/configure.js.map +1 -1
- package/dist/console/cacheClear.d.ts +13 -0
- package/dist/console/cacheClear.d.ts.map +1 -0
- package/dist/console/cacheClear.js +69 -0
- package/dist/console/cacheClear.js.map +1 -0
- package/dist/console/cacheDelete.d.ts +11 -0
- package/dist/console/cacheDelete.d.ts.map +1 -0
- package/dist/console/cacheDelete.js +42 -0
- package/dist/console/cacheDelete.js.map +1 -0
- package/dist/console/cachePrune.d.ts +9 -0
- package/dist/console/cachePrune.d.ts.map +1 -0
- package/dist/console/cachePrune.js +35 -0
- package/dist/console/cachePrune.js.map +1 -0
- package/dist/console/contract.d.ts +64 -0
- package/dist/console/contract.d.ts.map +1 -0
- package/dist/console/contract.js +32 -0
- package/dist/console/contract.js.map +1 -0
- package/dist/console/index.d.ts +25 -0
- package/dist/console/index.d.ts.map +1 -0
- package/dist/console/index.js +38 -0
- package/dist/console/index.js.map +1 -0
- package/dist/console/store.d.ts +14 -0
- package/dist/console/store.d.ts.map +1 -0
- package/dist/console/store.js +35 -0
- package/dist/console/store.js.map +1 -0
- package/dist/drivers/MemoryDriver.d.ts +36 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +157 -62
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +13 -8
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +171 -94
- package/dist/drivers/RedisDriver.js.map +1 -1
- package/dist/drivers/TieredDriver.d.ts +42 -0
- package/dist/drivers/TieredDriver.d.ts.map +1 -1
- package/dist/drivers/TieredDriver.js +114 -9
- package/dist/drivers/TieredDriver.js.map +1 -1
- package/dist/duration.d.ts +13 -3
- package/dist/duration.d.ts.map +1 -1
- package/dist/duration.js +22 -7
- package/dist/duration.js.map +1 -1
- package/dist/errors.d.ts +60 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +81 -6
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/quasar.d.ts +1 -1
- package/dist/quasar.d.ts.map +1 -1
- package/dist/quasar.js +27 -6
- package/dist/quasar.js.map +1 -1
- package/dist/services/main.d.ts +1 -1
- package/dist/services/main.d.ts.map +1 -1
- package/dist/services/main.js +22 -5
- package/dist/services/main.js.map +1 -1
- package/dist/stubs.d.ts +14 -0
- package/dist/stubs.d.ts.map +1 -0
- package/dist/stubs.js +15 -0
- package/dist/stubs.js.map +1 -0
- package/dist/types.d.ts +12 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.d.ts +26 -3
- package/dist/vendor/quasarConnection.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.js +44 -23
- package/dist/vendor/quasarConnection.js.map +1 -1
- package/package.json +8 -3
- package/src/CacheManager.ts +117 -41
- package/src/EchoProvider.ts +45 -4
- package/src/StoreManager.ts +86 -31
- package/src/bytes.ts +38 -0
- package/src/claim.ts +22 -0
- package/src/configure.ts +13 -21
- package/src/console/cacheClear.ts +96 -0
- package/src/console/cacheDelete.ts +65 -0
- package/src/console/cachePrune.ts +57 -0
- package/src/console/contract.ts +93 -0
- package/src/console/index.ts +61 -0
- package/src/console/store.ts +47 -0
- package/src/drivers/MemoryDriver.ts +205 -60
- package/src/drivers/RedisDriver.ts +205 -101
- package/src/drivers/TieredDriver.ts +169 -9
- package/src/duration.ts +28 -7
- package/src/errors.ts +103 -6
- package/src/index.ts +17 -3
- package/src/quasar.ts +44 -8
- package/src/services/main.ts +26 -8
- package/src/stubs.ts +16 -0
- package/src/types.ts +13 -2
- package/src/vendor/quasarConnection.ts +84 -22
- package/stubs/config/cache.stub +21 -0
package/src/CacheManager.ts
CHANGED
|
@@ -9,8 +9,17 @@
|
|
|
9
9
|
* canonical one; the positional form is kept for back-compat.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import { claimed, hasUnref } from "./claim.js";
|
|
12
13
|
import { type Duration, parseDuration, resolveTtlSeconds } from "./duration.js";
|
|
13
|
-
import {
|
|
14
|
+
import {
|
|
15
|
+
EchoError,
|
|
16
|
+
FactoryError,
|
|
17
|
+
InvalidArgumentError,
|
|
18
|
+
InvalidDurationError,
|
|
19
|
+
LockTimeoutError,
|
|
20
|
+
TimeoutError,
|
|
21
|
+
UndefinedValueError,
|
|
22
|
+
} from "./errors.js";
|
|
14
23
|
import type {
|
|
15
24
|
CacheEmitter,
|
|
16
25
|
CacheEntry,
|
|
@@ -42,25 +51,40 @@ function isTaggableDriver(driver: CacheDriver): driver is TaggableDriver {
|
|
|
42
51
|
);
|
|
43
52
|
}
|
|
44
53
|
|
|
45
|
-
|
|
54
|
+
function notTaggable(): EchoError {
|
|
55
|
+
return new EchoError(
|
|
56
|
+
"E_ECHO_NOT_TAGGABLE",
|
|
57
|
+
"Echo: the configured driver does not support tag-based invalidation",
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The longest delay `setTimeout` honours; past it Node fires after 1 ms. */
|
|
62
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Resolve an optional timeout {@link Duration} to milliseconds; `undefined`
|
|
66
|
+
* when unset or `Infinity` (no timeout).
|
|
67
|
+
*
|
|
68
|
+
* Checked, because `setTimeout` reads NaN, Infinity and anything past
|
|
69
|
+
* 2^31-1 ms as 1 ms: "never time out" became "time out at once", and every
|
|
70
|
+
* getOrSet rejected. A longer one is clamped to the longest timer there is
|
|
71
|
+
* (24.8 days); NaN and negatives mean nothing and are refused.
|
|
72
|
+
*/
|
|
46
73
|
function resolveMs(duration: Duration | undefined): number | undefined {
|
|
47
74
|
if (duration === undefined || duration === null) return undefined;
|
|
48
75
|
const seconds =
|
|
49
76
|
typeof duration === "number" ? duration : parseDuration(duration);
|
|
50
|
-
|
|
77
|
+
if (seconds === Number.POSITIVE_INFINITY) return undefined;
|
|
78
|
+
if (Number.isNaN(seconds) || seconds < 0) {
|
|
79
|
+
throw new InvalidDurationError(
|
|
80
|
+
`Echo: a timeout must be a non-negative duration, or null for none — got ${String(duration)}`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
return Math.min(seconds * 1000, MAX_TIMER_MS);
|
|
51
84
|
}
|
|
52
85
|
|
|
53
86
|
const TIMEOUT: unique symbol = Symbol("echo.timeout");
|
|
54
87
|
|
|
55
|
-
/** A timer handle that can be unreferenced — Node's, not the browser's. */
|
|
56
|
-
function hasUnref(timer: unknown): timer is { unref(): void } {
|
|
57
|
-
return (
|
|
58
|
-
typeof timer === "object" &&
|
|
59
|
-
timer !== null &&
|
|
60
|
-
typeof Reflect.get(timer, "unref") === "function"
|
|
61
|
-
);
|
|
62
|
-
}
|
|
63
|
-
|
|
64
88
|
function withTimeout<T>(
|
|
65
89
|
promise: Promise<T>,
|
|
66
90
|
ms: number,
|
|
@@ -183,10 +207,25 @@ export class CacheManager {
|
|
|
183
207
|
this.#shared = shared ?? { inflight: new Map() };
|
|
184
208
|
}
|
|
185
209
|
|
|
210
|
+
/** The store's name, as events report it (upstream `cache.name`). */
|
|
211
|
+
get name(): string {
|
|
212
|
+
return this.#name;
|
|
213
|
+
}
|
|
214
|
+
|
|
186
215
|
#prefixKey(key: string): string {
|
|
187
216
|
return this.#prefix ? `${this.#prefix}:${key}` : key;
|
|
188
217
|
}
|
|
189
218
|
|
|
219
|
+
/**
|
|
220
|
+
* Tags live inside the namespace, exactly as keys do. They reached the
|
|
221
|
+
* driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
|
|
222
|
+
* also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
|
|
223
|
+
* same way: its tag invalidations are entries of the namespaced stack.
|
|
224
|
+
*/
|
|
225
|
+
#prefixTags(tags: string[]): string[] {
|
|
226
|
+
return tags.map((tag) => this.#prefixKey(tag));
|
|
227
|
+
}
|
|
228
|
+
|
|
190
229
|
#emit<E extends keyof CacheEventMap>(
|
|
191
230
|
event: E,
|
|
192
231
|
payload: CacheEventMap[E],
|
|
@@ -287,7 +326,8 @@ export class CacheManager {
|
|
|
287
326
|
use(name?: string): CacheManager {
|
|
288
327
|
if (this.#stores) return this.#stores.use(name);
|
|
289
328
|
if (name === undefined) return this;
|
|
290
|
-
throw new
|
|
329
|
+
throw new EchoError(
|
|
330
|
+
"E_ECHO_UNKNOWN_STORE",
|
|
291
331
|
`Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
|
|
292
332
|
"Declare `{ default, stores }` in config/cache.ts to name several.",
|
|
293
333
|
);
|
|
@@ -397,25 +437,43 @@ export class CacheManager {
|
|
|
397
437
|
if (value === null || value === undefined) {
|
|
398
438
|
// Named divergence (fail-loud): unlike bento (which no-ops), echo throws
|
|
399
439
|
// on caching null/undefined — a null cache write is almost always a bug.
|
|
400
|
-
throw new
|
|
401
|
-
|
|
402
|
-
|
|
440
|
+
throw new UndefinedValueError();
|
|
441
|
+
}
|
|
442
|
+
if (ttlSeconds < 0) {
|
|
443
|
+
// A TTL in the past: the value has already expired. Kept only as
|
|
444
|
+
// a stale copy for its grace window, otherwise dropped — and the
|
|
445
|
+
// key's previous value with it, which a skipped write would have
|
|
446
|
+
// left being served. Upstream deletes the same way when the TTL
|
|
447
|
+
// is not positive and grace is off.
|
|
448
|
+
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
449
|
+
await this.#driver.setEntry(prefixed, value, {
|
|
450
|
+
expiresAt: Date.now() - 1,
|
|
451
|
+
graceSeconds,
|
|
452
|
+
tags: this.#prefixTags(tags),
|
|
453
|
+
});
|
|
454
|
+
return;
|
|
455
|
+
}
|
|
456
|
+
await this.#driver.delete(prefixed);
|
|
457
|
+
return;
|
|
403
458
|
}
|
|
404
459
|
if (this.#driver.setEntry) {
|
|
405
460
|
await this.#driver.setEntry(prefixed, value, {
|
|
406
461
|
ttlSeconds,
|
|
407
462
|
graceSeconds,
|
|
408
|
-
tags,
|
|
463
|
+
tags: this.#prefixTags(tags),
|
|
409
464
|
});
|
|
410
465
|
return;
|
|
411
466
|
}
|
|
412
467
|
if (tags.length > 0) {
|
|
413
468
|
if (!isTaggableDriver(this.#driver)) {
|
|
414
|
-
throw
|
|
415
|
-
"Echo: the configured driver does not support tag-based invalidation",
|
|
416
|
-
);
|
|
469
|
+
throw notTaggable();
|
|
417
470
|
}
|
|
418
|
-
await this.#driver.setWithTags(
|
|
471
|
+
await this.#driver.setWithTags(
|
|
472
|
+
prefixed,
|
|
473
|
+
value,
|
|
474
|
+
this.#prefixTags(tags),
|
|
475
|
+
ttlSeconds,
|
|
476
|
+
);
|
|
419
477
|
return;
|
|
420
478
|
}
|
|
421
479
|
await this.#driver.set(prefixed, value, ttlSeconds);
|
|
@@ -488,7 +546,7 @@ export class CacheManager {
|
|
|
488
546
|
if (typeof keyOrOptions === "string") {
|
|
489
547
|
key = keyOrOptions;
|
|
490
548
|
val = value;
|
|
491
|
-
ttl = ttlSeconds
|
|
549
|
+
ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
|
|
492
550
|
graceSeconds = 0;
|
|
493
551
|
tags = [];
|
|
494
552
|
} else {
|
|
@@ -619,7 +677,7 @@ export class CacheManager {
|
|
|
619
677
|
await this.#writeValue(
|
|
620
678
|
this.#prefixKey(key),
|
|
621
679
|
value,
|
|
622
|
-
ttlSeconds
|
|
680
|
+
resolveTtlSeconds(ttlSeconds, this.#defaultTtl),
|
|
623
681
|
0,
|
|
624
682
|
tags,
|
|
625
683
|
);
|
|
@@ -637,14 +695,13 @@ export class CacheManager {
|
|
|
637
695
|
? tagsOrOptions
|
|
638
696
|
: tagsOrOptions.tags;
|
|
639
697
|
if (!isTaggableDriver(this.#driver)) {
|
|
640
|
-
throw
|
|
641
|
-
"Echo: the configured driver does not support tag-based invalidation",
|
|
642
|
-
);
|
|
698
|
+
throw notTaggable();
|
|
643
699
|
}
|
|
700
|
+
const scoped = this.#prefixTags(tags);
|
|
644
701
|
if (typeof this.#driver.deleteByTag === "function") {
|
|
645
|
-
return this.#driver.deleteByTag(
|
|
702
|
+
return this.#driver.deleteByTag(scoped);
|
|
646
703
|
}
|
|
647
|
-
return this.#driver.flushTags(
|
|
704
|
+
return this.#driver.flushTags(scoped);
|
|
648
705
|
}
|
|
649
706
|
|
|
650
707
|
/** @deprecated alias of {@link deleteByTag}. */
|
|
@@ -685,7 +742,7 @@ export class CacheManager {
|
|
|
685
742
|
): NormalizedGetOrSet<T> {
|
|
686
743
|
if (typeof a === "string") {
|
|
687
744
|
if (typeof c !== "function") {
|
|
688
|
-
throw new
|
|
745
|
+
throw new InvalidArgumentError(
|
|
689
746
|
"Echo: getOrSet(key, ttl, factory) requires a factory function",
|
|
690
747
|
);
|
|
691
748
|
}
|
|
@@ -776,16 +833,23 @@ export class CacheManager {
|
|
|
776
833
|
const hasStale = entry?.stale === true && o.graceSeconds > 0;
|
|
777
834
|
const staleValue = hasStale ? entry.value : undefined;
|
|
778
835
|
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
this.#
|
|
836
|
+
const record = this.#shared.inflight.get(prefixed);
|
|
837
|
+
// Joining another caller's factory, rather than running our own.
|
|
838
|
+
const joined = record !== undefined;
|
|
839
|
+
let factoryPromise: Promise<T>;
|
|
840
|
+
if (record === undefined) {
|
|
841
|
+
factoryPromise = this.#invokeFactory<T>(
|
|
842
|
+
prefixed,
|
|
843
|
+
o,
|
|
844
|
+
hasStale,
|
|
845
|
+
staleValue,
|
|
846
|
+
);
|
|
847
|
+
this.#shared.inflight.set(prefixed, { promise: factoryPromise });
|
|
848
|
+
} else {
|
|
849
|
+
// The map holds every key's factory, whatever its type; what the
|
|
850
|
+
// leader computes for this key is what this caller reads.
|
|
851
|
+
factoryPromise = record.promise.then((value) => claimed<T>(value));
|
|
785
852
|
}
|
|
786
|
-
// Single-flight join point: the shared map is heterogeneous (many T), so
|
|
787
|
-
// this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
|
|
788
|
-
const factoryPromise = record.promise as Promise<T>;
|
|
789
853
|
|
|
790
854
|
if (hasStale && staleValue !== undefined) {
|
|
791
855
|
// Stale-while-revalidate: serve stale up to the soft timeout (default 0
|
|
@@ -808,10 +872,22 @@ export class CacheManager {
|
|
|
808
872
|
return result;
|
|
809
873
|
}
|
|
810
874
|
|
|
811
|
-
|
|
812
|
-
|
|
875
|
+
// A joiner waits at most `lockTimeout` for the leader, stale value or
|
|
876
|
+
// not, as upstream bounds its lock acquisition either way. It was read
|
|
877
|
+
// on the stale path only, so behind a factory that hung every caller
|
|
878
|
+
// for the key waited forever. The leader is not bound by it: it holds
|
|
879
|
+
// the lock, and `hardTimeout` is what bounds its factory.
|
|
880
|
+
const lockMs = joined ? o.lockTimeoutMs : undefined;
|
|
881
|
+
const hardMs = o.hardTimeoutMs;
|
|
882
|
+
if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
|
|
883
|
+
const result = await withTimeout(factoryPromise, lockMs);
|
|
884
|
+
if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
|
|
885
|
+
return result;
|
|
886
|
+
}
|
|
887
|
+
if (hardMs !== undefined) {
|
|
888
|
+
const result = await withTimeout(factoryPromise, hardMs);
|
|
813
889
|
if (result === TIMEOUT) {
|
|
814
|
-
throw new TimeoutError(o.key,
|
|
890
|
+
throw new TimeoutError(o.key, hardMs);
|
|
815
891
|
}
|
|
816
892
|
return result;
|
|
817
893
|
}
|
package/src/EchoProvider.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import "./augmentations.js";
|
|
2
2
|
import { type CacheConfig, CacheManager } from "./CacheManager.js";
|
|
3
3
|
import { MemoryDriver } from "./drivers/MemoryDriver.js";
|
|
4
|
+
import { EchoError } from "./errors.js";
|
|
4
5
|
import { CacheStoreManager, type MultiStoreConfig } from "./StoreManager.js";
|
|
5
6
|
import { clearCache, getCache, setCache } from "./services/main.js";
|
|
6
7
|
import type { CacheEmitter } from "./types.js";
|
|
@@ -43,6 +44,34 @@ function isEmitter(value: unknown): value is CacheEmitter {
|
|
|
43
44
|
);
|
|
44
45
|
}
|
|
45
46
|
|
|
47
|
+
function isDuration(value: unknown): boolean {
|
|
48
|
+
return (
|
|
49
|
+
value === undefined ||
|
|
50
|
+
value === null ||
|
|
51
|
+
typeof value === "number" ||
|
|
52
|
+
typeof value === "string"
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** A single-store config, field by field. */
|
|
57
|
+
function isSingleStoreConfig(value: unknown): value is EchoProviderConfig {
|
|
58
|
+
if (typeof value !== "object" || value === null) return false;
|
|
59
|
+
const read = (name: string): unknown => Reflect.get(value, name);
|
|
60
|
+
const driver = read("driver");
|
|
61
|
+
const prefix = read("prefix");
|
|
62
|
+
const name = read("name");
|
|
63
|
+
const emitter = read("emitter");
|
|
64
|
+
return (
|
|
65
|
+
(driver === undefined || driver === "memory") &&
|
|
66
|
+
(prefix === undefined || typeof prefix === "string") &&
|
|
67
|
+
(name === undefined || typeof name === "string") &&
|
|
68
|
+
(emitter === undefined || isEmitter(emitter)) &&
|
|
69
|
+
["ttl", "grace", "timeout", "hardTimeout", "lockTimeout"].every((field) =>
|
|
70
|
+
isDuration(read(field)),
|
|
71
|
+
)
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
46
75
|
function isMultiStoreConfig(value: unknown): value is MultiStoreConfig {
|
|
47
76
|
return (
|
|
48
77
|
typeof value === "object" &&
|
|
@@ -94,15 +123,27 @@ export default class EchoProvider {
|
|
|
94
123
|
return manager.use();
|
|
95
124
|
}
|
|
96
125
|
|
|
97
|
-
const config =
|
|
98
|
-
const driver =
|
|
126
|
+
const config: unknown = raw ?? {};
|
|
127
|
+
const driver =
|
|
128
|
+
typeof config === "object" && config !== null
|
|
129
|
+
? (Reflect.get(config, "driver") ?? "memory")
|
|
130
|
+
: "memory";
|
|
99
131
|
if (driver !== "memory") {
|
|
100
|
-
throw new
|
|
101
|
-
|
|
132
|
+
throw new EchoError(
|
|
133
|
+
"E_ECHO_UNSUPPORTED_DRIVER",
|
|
134
|
+
`[echo] Unsupported driver '${String(driver)}' for default provider — ` +
|
|
102
135
|
"wire CacheManager yourself for non-memory drivers, or use the " +
|
|
103
136
|
"multi-store `{ default, stores }` config.",
|
|
104
137
|
);
|
|
105
138
|
}
|
|
139
|
+
// Checked, not asserted: a config file is the application's, and
|
|
140
|
+
// a prefix that is not a string would otherwise reach every key.
|
|
141
|
+
if (!isSingleStoreConfig(config)) {
|
|
142
|
+
throw new EchoError(
|
|
143
|
+
"E_ECHO_INVALID_CONFIG",
|
|
144
|
+
"[echo] config/cache.ts must export an object — `{ prefix, ttl, … }` for one store, or `{ default, stores }` for several.",
|
|
145
|
+
);
|
|
146
|
+
}
|
|
106
147
|
return new CacheManager(new MemoryDriver(), { ...config, emitter });
|
|
107
148
|
});
|
|
108
149
|
// Namespaced by the package that owns it, the way upstream namespaces
|
package/src/StoreManager.ts
CHANGED
|
@@ -16,15 +16,33 @@
|
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
18
|
import { CacheManager } from "./CacheManager.js";
|
|
19
|
-
import {
|
|
19
|
+
import {
|
|
20
|
+
MemoryDriver,
|
|
21
|
+
type MemoryDriverOptions,
|
|
22
|
+
} from "./drivers/MemoryDriver.js";
|
|
20
23
|
import { type RedisClient, RedisDriver } from "./drivers/RedisDriver.js";
|
|
21
|
-
import {
|
|
24
|
+
import {
|
|
25
|
+
type CacheBus,
|
|
26
|
+
TieredDriver,
|
|
27
|
+
type TieredDriverOptions,
|
|
28
|
+
} from "./drivers/TieredDriver.js";
|
|
22
29
|
import type { Duration } from "./duration.js";
|
|
30
|
+
import { EchoError } from "./errors.js";
|
|
23
31
|
import { quasarBus, quasarConnection } from "./quasar.js";
|
|
24
32
|
import type { CacheDriver, CacheEmitter, CacheEventMap } from "./types.js";
|
|
25
33
|
|
|
26
|
-
/**
|
|
27
|
-
|
|
34
|
+
/**
|
|
35
|
+
* A lazily-instantiated driver (built once per store, on first `use`). The
|
|
36
|
+
* store manager passes the store's name, which a tiered driver stamps on its
|
|
37
|
+
* bus messages so stores sharing a channel leave each other alone.
|
|
38
|
+
*/
|
|
39
|
+
export type DriverFactory = (context?: DriverContext) => CacheDriver;
|
|
40
|
+
|
|
41
|
+
/** What the store manager tells a driver factory about the store it builds. */
|
|
42
|
+
export interface DriverContext {
|
|
43
|
+
/** The store's key in the config. */
|
|
44
|
+
store: string;
|
|
45
|
+
}
|
|
28
46
|
|
|
29
47
|
export interface StoreConfig {
|
|
30
48
|
driver: DriverFactory;
|
|
@@ -42,6 +60,14 @@ export interface StoreConfig {
|
|
|
42
60
|
timeout?: Duration;
|
|
43
61
|
hardTimeout?: Duration;
|
|
44
62
|
lockTimeout?: Duration;
|
|
63
|
+
/**
|
|
64
|
+
* For a two-layer store: serve from L1 and the factory when the L2 fails,
|
|
65
|
+
* rather than failing the call. Default `true` (see
|
|
66
|
+
* {@link TieredDriverOptions.suppressL2Errors}).
|
|
67
|
+
*/
|
|
68
|
+
suppressL2Errors?: boolean;
|
|
69
|
+
/** For a two-layer store: how long to skip a failing L2. Off by default. */
|
|
70
|
+
l2CircuitBreakerDuration?: Duration;
|
|
45
71
|
}
|
|
46
72
|
|
|
47
73
|
export interface MultiStoreConfig {
|
|
@@ -109,20 +135,28 @@ export class Store {
|
|
|
109
135
|
entry(): StoreConfig {
|
|
110
136
|
const l1 = this.#l1;
|
|
111
137
|
const l2 = this.#l2;
|
|
112
|
-
if (!l1 && !l2) {
|
|
113
|
-
throw new Error(
|
|
114
|
-
"Echo: a store needs a layer — call useL1Layer() or useL2Layer() on it.",
|
|
115
|
-
);
|
|
116
|
-
}
|
|
117
138
|
if (l1 && l2) {
|
|
118
139
|
return {
|
|
119
140
|
...this.#options,
|
|
120
|
-
driver: drivers.tiered({
|
|
141
|
+
driver: drivers.tiered({
|
|
142
|
+
l1,
|
|
143
|
+
l2,
|
|
144
|
+
bus: this.#bus,
|
|
145
|
+
suppressL2Errors: this.#options.suppressL2Errors,
|
|
146
|
+
l2CircuitBreakerDuration: this.#options.l2CircuitBreakerDuration,
|
|
147
|
+
}),
|
|
121
148
|
};
|
|
122
149
|
}
|
|
123
|
-
const only =
|
|
150
|
+
const only = l1 ?? l2;
|
|
151
|
+
if (only === undefined) {
|
|
152
|
+
throw new EchoError(
|
|
153
|
+
"E_ECHO_INVALID_CONFIG",
|
|
154
|
+
"Echo: a store needs a layer — call useL1Layer() or useL2Layer() on it.",
|
|
155
|
+
);
|
|
156
|
+
}
|
|
124
157
|
if (this.#bus) {
|
|
125
|
-
throw new
|
|
158
|
+
throw new EchoError(
|
|
159
|
+
"E_ECHO_INVALID_CONFIG",
|
|
126
160
|
"Echo: a bus only means something with two layers — it keeps each instance's L1 in step. Add useL2Layer(), or drop useBus().",
|
|
127
161
|
);
|
|
128
162
|
}
|
|
@@ -146,12 +180,12 @@ export const drivers = {
|
|
|
146
180
|
* `maxItems` bounds the store by COUNT, which a TTL cannot: a cache keyed by
|
|
147
181
|
* a user id or a search term grows until the process runs out of memory,
|
|
148
182
|
* however short each entry's life. Omit it for no ceiling.
|
|
183
|
+
*
|
|
184
|
+
* Values are stored as JSON and read back as copies; `serialize: false`
|
|
185
|
+
* keeps references instead (see {@link MemoryDriverOptions.serialize}).
|
|
149
186
|
*/
|
|
150
|
-
memory(options?: {
|
|
151
|
-
|
|
152
|
-
maxItems?: number;
|
|
153
|
-
}): DriverFactory {
|
|
154
|
-
return () => new MemoryDriver(options?.sweepIntervalMs, options?.maxItems);
|
|
187
|
+
memory(options?: MemoryDriverOptions): DriverFactory {
|
|
188
|
+
return () => new MemoryDriver({ ...options });
|
|
155
189
|
},
|
|
156
190
|
/**
|
|
157
191
|
* Either hand it a client, or name a quasar connection — the AdonisJS shape,
|
|
@@ -181,16 +215,18 @@ export const drivers = {
|
|
|
181
215
|
redisBus(options?: { connection?: string; channel?: string }): CacheBus {
|
|
182
216
|
return quasarBus(options);
|
|
183
217
|
},
|
|
184
|
-
tiered(
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
218
|
+
tiered(
|
|
219
|
+
options: {
|
|
220
|
+
l1: DriverFactory;
|
|
221
|
+
l2: DriverFactory;
|
|
222
|
+
} & Omit<TieredDriverOptions, "l1" | "l2">,
|
|
223
|
+
): DriverFactory {
|
|
224
|
+
return (context) =>
|
|
190
225
|
new TieredDriver({
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
226
|
+
...options,
|
|
227
|
+
l1: options.l1(context),
|
|
228
|
+
l2: options.l2(context),
|
|
229
|
+
store: options.store ?? context?.store,
|
|
194
230
|
});
|
|
195
231
|
},
|
|
196
232
|
};
|
|
@@ -219,25 +255,44 @@ export class CacheStoreManager {
|
|
|
219
255
|
|
|
220
256
|
constructor(config: MultiStoreConfig) {
|
|
221
257
|
this.#config = config;
|
|
222
|
-
if (!config.
|
|
223
|
-
throw new
|
|
258
|
+
if (!this.#declared(config.default)) {
|
|
259
|
+
throw new EchoError(
|
|
260
|
+
"E_ECHO_UNKNOWN_STORE",
|
|
224
261
|
`Echo: default store "${config.default}" is not defined in stores`,
|
|
225
262
|
);
|
|
226
263
|
}
|
|
227
264
|
}
|
|
228
265
|
|
|
266
|
+
/**
|
|
267
|
+
* A store declared under `name` in the config's OWN keys: a plain lookup
|
|
268
|
+
* would answer `toString` or `constructor` with an Object.prototype member.
|
|
269
|
+
*/
|
|
270
|
+
#declared(name: string): MultiStoreConfig["stores"][string] | undefined {
|
|
271
|
+
return Object.hasOwn(this.#config.stores, name)
|
|
272
|
+
? this.#config.stores[name]
|
|
273
|
+
: undefined;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** The store `use()` answers with no name (upstream `defaultStoreName`). */
|
|
277
|
+
get defaultStoreName(): string {
|
|
278
|
+
return this.#config.default;
|
|
279
|
+
}
|
|
280
|
+
|
|
229
281
|
/** Resolve a store by name (or the default). Instances are built once and cached. */
|
|
230
282
|
use(name?: string): CacheManager {
|
|
231
283
|
const store = name ?? this.#config.default;
|
|
232
284
|
const existing = this.#built.get(store);
|
|
233
285
|
if (existing) return existing;
|
|
234
286
|
|
|
235
|
-
const declared = this.#
|
|
287
|
+
const declared = this.#declared(store);
|
|
236
288
|
if (!declared) {
|
|
237
|
-
throw new
|
|
289
|
+
throw new EchoError(
|
|
290
|
+
"E_ECHO_UNKNOWN_STORE",
|
|
291
|
+
`Echo: unknown cache store "${store}"`,
|
|
292
|
+
);
|
|
238
293
|
}
|
|
239
294
|
const cfg = entryOf(declared);
|
|
240
|
-
const manager = new CacheManager(cfg.driver(), {
|
|
295
|
+
const manager = new CacheManager(cfg.driver({ store }), {
|
|
241
296
|
prefix: cfg.prefix,
|
|
242
297
|
// The store's own, or the one every store inherits.
|
|
243
298
|
ttl: cfg.ttl ?? this.#config.ttl,
|
package/src/bytes.ts
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Byte sizes for the memory driver's bounds — upstream takes a number of bytes
|
|
3
|
+
* or a human string (`'10mb'`), in powers of 1024.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { EchoError } from "./errors.js";
|
|
7
|
+
|
|
8
|
+
const UNIT_BYTES: Record<string, number> = {
|
|
9
|
+
b: 1,
|
|
10
|
+
kb: 1024,
|
|
11
|
+
mb: 1024 ** 2,
|
|
12
|
+
gb: 1024 ** 3,
|
|
13
|
+
tb: 1024 ** 4,
|
|
14
|
+
pb: 1024 ** 5,
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
const BYTES_RE = /^\s*(\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* A size in bytes, from a number of bytes or a string like `'512kb'`.
|
|
21
|
+
*
|
|
22
|
+
* @throws {EchoError} `E_ECHO_INVALID_CONFIG` for anything that is not a
|
|
23
|
+
* finite, non-negative size: a bound that cannot be read would otherwise
|
|
24
|
+
* leave the store silently unbounded.
|
|
25
|
+
*/
|
|
26
|
+
export function parseBytes(value: number | string, option: string): number {
|
|
27
|
+
if (typeof value === "number") {
|
|
28
|
+
if (Number.isFinite(value) && value >= 0) return value;
|
|
29
|
+
} else {
|
|
30
|
+
const match = BYTES_RE.exec(value);
|
|
31
|
+
const factor = UNIT_BYTES[(match?.[2] ?? "b").toLowerCase()];
|
|
32
|
+
if (match && factor !== undefined) return Number(match[1]) * factor;
|
|
33
|
+
}
|
|
34
|
+
throw new EchoError(
|
|
35
|
+
"E_ECHO_INVALID_CONFIG",
|
|
36
|
+
`Echo: ${option} must be a number of bytes or a size like '10mb' — got ${String(value)}`,
|
|
37
|
+
);
|
|
38
|
+
}
|
package/src/claim.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one place a cached value becomes the caller's `T`.
|
|
3
|
+
*
|
|
4
|
+
* A cache hands back what was written under a key. The type parameter of
|
|
5
|
+
* `get<T>()` is the caller's statement of what that was — nothing the cache
|
|
6
|
+
* can check, and upstream's `get<T>()` makes the same claim. It lives in this
|
|
7
|
+
* one named function rather than as an assertion at every read site, so the
|
|
8
|
+
* boundary is visible and there is exactly one of it.
|
|
9
|
+
*/
|
|
10
|
+
export function claimed<T>(value: unknown): T;
|
|
11
|
+
export function claimed(value: unknown): unknown {
|
|
12
|
+
return value;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** A timer handle that can be unreferenced — Node's, not the browser's. */
|
|
16
|
+
export function hasUnref(timer: unknown): timer is { unref(): void } {
|
|
17
|
+
return (
|
|
18
|
+
typeof timer === "object" &&
|
|
19
|
+
timer !== null &&
|
|
20
|
+
typeof Reflect.get(timer, "unref") === "function"
|
|
21
|
+
);
|
|
22
|
+
}
|
package/src/configure.ts
CHANGED
|
@@ -7,14 +7,23 @@
|
|
|
7
7
|
* installed AND working.
|
|
8
8
|
*/
|
|
9
9
|
|
|
10
|
+
import { stubsRoot } from "./stubs.js";
|
|
11
|
+
|
|
10
12
|
interface Codemods {
|
|
11
13
|
addProvider(importPath: string): Promise<void>;
|
|
14
|
+
registerCommand(importPath: string): Promise<void>;
|
|
12
15
|
addEnvVars(vars: Record<string, string>): Promise<void>;
|
|
13
16
|
writeFile(
|
|
14
17
|
filePath: string,
|
|
15
18
|
content: string,
|
|
16
19
|
options?: { force?: boolean },
|
|
17
20
|
): Promise<void>;
|
|
21
|
+
makeUsingStub(
|
|
22
|
+
stubsRoot: string,
|
|
23
|
+
stubPath: string,
|
|
24
|
+
state?: Record<string, string | number | boolean>,
|
|
25
|
+
options?: { force?: boolean },
|
|
26
|
+
): Promise<{ path: string; contents: string }>;
|
|
18
27
|
}
|
|
19
28
|
|
|
20
29
|
export async function configure(codemods: Codemods): Promise<void> {
|
|
@@ -26,25 +35,8 @@ export async function configure(codemods: Codemods): Promise<void> {
|
|
|
26
35
|
});
|
|
27
36
|
|
|
28
37
|
await codemods.addProvider("@c9up/echo/provider");
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
export default defineConfig({
|
|
35
|
-
default: env.get('CACHE_STORE', 'memory'),
|
|
36
|
-
|
|
37
|
-
stores: {
|
|
38
|
-
// One layer, in this process.
|
|
39
|
-
memory: store().useL1Layer(drivers.memory({ maxItems: 1000 })),
|
|
40
|
-
|
|
41
|
-
// Two layers: memory in front of Redis, with a bus so every instance
|
|
42
|
-
// drops its own L1 entry when another writes.
|
|
43
|
-
tiered: store()
|
|
44
|
-
.useL1Layer(drivers.memory({ maxItems: 1000 }))
|
|
45
|
-
.useL2Layer(drivers.redis({ connection: 'main' }))
|
|
46
|
-
.useBus(drivers.redisBus({ connection: 'main' })),
|
|
47
|
-
},
|
|
48
|
-
})`,
|
|
49
|
-
);
|
|
38
|
+
// `cache:clear`, `cache:delete` and `cache:prune` are the package's, not the
|
|
39
|
+
// binary's: a project reaches them by listing the module.
|
|
40
|
+
await codemods.registerCommand("@c9up/echo/commands");
|
|
41
|
+
await codemods.makeUsingStub(stubsRoot, "config/cache.stub");
|
|
50
42
|
}
|