@c9up/echo 0.2.3 → 0.2.5

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.
Files changed (109) hide show
  1. package/README.md +1 -1
  2. package/dist/CacheManager.d.ts +13 -2
  3. package/dist/CacheManager.d.ts.map +1 -1
  4. package/dist/CacheManager.js +309 -56
  5. package/dist/CacheManager.js.map +1 -1
  6. package/dist/EchoProvider.d.ts.map +1 -1
  7. package/dist/EchoProvider.js +32 -3
  8. package/dist/EchoProvider.js.map +1 -1
  9. package/dist/StoreManager.d.ts +38 -11
  10. package/dist/StoreManager.d.ts.map +1 -1
  11. package/dist/StoreManager.js +80 -22
  12. package/dist/StoreManager.js.map +1 -1
  13. package/dist/bytes.d.ts +13 -0
  14. package/dist/bytes.d.ts.map +1 -0
  15. package/dist/bytes.js +35 -0
  16. package/dist/bytes.js.map +1 -0
  17. package/dist/claim.d.ts +15 -0
  18. package/dist/claim.d.ts.map +1 -0
  19. package/dist/claim.js +10 -0
  20. package/dist/claim.js.map +1 -0
  21. package/dist/configure.d.ts +1 -0
  22. package/dist/configure.d.ts.map +1 -1
  23. package/dist/configure.js +3 -0
  24. package/dist/configure.js.map +1 -1
  25. package/dist/console/cacheClear.d.ts +13 -0
  26. package/dist/console/cacheClear.d.ts.map +1 -0
  27. package/dist/console/cacheClear.js +69 -0
  28. package/dist/console/cacheClear.js.map +1 -0
  29. package/dist/console/cacheDelete.d.ts +11 -0
  30. package/dist/console/cacheDelete.d.ts.map +1 -0
  31. package/dist/console/cacheDelete.js +42 -0
  32. package/dist/console/cacheDelete.js.map +1 -0
  33. package/dist/console/cachePrune.d.ts +9 -0
  34. package/dist/console/cachePrune.d.ts.map +1 -0
  35. package/dist/console/cachePrune.js +35 -0
  36. package/dist/console/cachePrune.js.map +1 -0
  37. package/dist/console/contract.d.ts +64 -0
  38. package/dist/console/contract.d.ts.map +1 -0
  39. package/dist/console/contract.js +32 -0
  40. package/dist/console/contract.js.map +1 -0
  41. package/dist/console/index.d.ts +25 -0
  42. package/dist/console/index.d.ts.map +1 -0
  43. package/dist/console/index.js +38 -0
  44. package/dist/console/index.js.map +1 -0
  45. package/dist/console/store.d.ts +14 -0
  46. package/dist/console/store.d.ts.map +1 -0
  47. package/dist/console/store.js +35 -0
  48. package/dist/console/store.js.map +1 -0
  49. package/dist/drivers/MemoryDriver.d.ts +37 -1
  50. package/dist/drivers/MemoryDriver.d.ts.map +1 -1
  51. package/dist/drivers/MemoryDriver.js +170 -72
  52. package/dist/drivers/MemoryDriver.js.map +1 -1
  53. package/dist/drivers/RedisDriver.d.ts +15 -8
  54. package/dist/drivers/RedisDriver.d.ts.map +1 -1
  55. package/dist/drivers/RedisDriver.js +198 -97
  56. package/dist/drivers/RedisDriver.js.map +1 -1
  57. package/dist/drivers/TieredDriver.d.ts +42 -0
  58. package/dist/drivers/TieredDriver.d.ts.map +1 -1
  59. package/dist/drivers/TieredDriver.js +114 -9
  60. package/dist/drivers/TieredDriver.js.map +1 -1
  61. package/dist/duration.d.ts +13 -3
  62. package/dist/duration.d.ts.map +1 -1
  63. package/dist/duration.js +22 -7
  64. package/dist/duration.js.map +1 -1
  65. package/dist/errors.d.ts +60 -2
  66. package/dist/errors.d.ts.map +1 -1
  67. package/dist/errors.js +81 -6
  68. package/dist/errors.js.map +1 -1
  69. package/dist/index.d.ts +4 -4
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +3 -3
  72. package/dist/index.js.map +1 -1
  73. package/dist/quasar.d.ts +1 -1
  74. package/dist/quasar.d.ts.map +1 -1
  75. package/dist/quasar.js +106 -19
  76. package/dist/quasar.js.map +1 -1
  77. package/dist/services/main.d.ts +1 -1
  78. package/dist/services/main.d.ts.map +1 -1
  79. package/dist/services/main.js +22 -5
  80. package/dist/services/main.js.map +1 -1
  81. package/dist/types.d.ts +44 -2
  82. package/dist/types.d.ts.map +1 -1
  83. package/dist/vendor/quasarConnection.d.ts +44 -3
  84. package/dist/vendor/quasarConnection.d.ts.map +1 -1
  85. package/dist/vendor/quasarConnection.js +64 -23
  86. package/dist/vendor/quasarConnection.js.map +1 -1
  87. package/package.json +5 -1
  88. package/src/CacheManager.ts +367 -69
  89. package/src/EchoProvider.ts +45 -4
  90. package/src/StoreManager.ts +131 -35
  91. package/src/bytes.ts +38 -0
  92. package/src/claim.ts +22 -0
  93. package/src/configure.ts +4 -0
  94. package/src/console/cacheClear.ts +96 -0
  95. package/src/console/cacheDelete.ts +65 -0
  96. package/src/console/cachePrune.ts +57 -0
  97. package/src/console/contract.ts +93 -0
  98. package/src/console/index.ts +61 -0
  99. package/src/console/store.ts +47 -0
  100. package/src/drivers/MemoryDriver.ts +221 -69
  101. package/src/drivers/RedisDriver.ts +234 -104
  102. package/src/drivers/TieredDriver.ts +169 -9
  103. package/src/duration.ts +28 -7
  104. package/src/errors.ts +103 -6
  105. package/src/index.ts +17 -3
  106. package/src/quasar.ts +145 -30
  107. package/src/services/main.ts +26 -8
  108. package/src/types.ts +46 -7
  109. package/src/vendor/quasarConnection.ts +105 -22
@@ -1 +1 @@
1
- {"version":3,"file":"quasar.d.ts","sourceRoot":"","sources":["../src/quasar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAwBtE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAS1E;AAwED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,QAAQ,CA0FX"}
1
+ {"version":3,"file":"quasar.d.ts","sourceRoot":"","sources":["../src/quasar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAEN,KAAK,QAAQ,EAEb,MAAM,2BAA2B,CAAC;AA4CnC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAiB1E;AAyED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,QAAQ,CA4KX"}
package/dist/quasar.js CHANGED
@@ -10,7 +10,9 @@
10
10
  * again: `src/vendor/quasarConnection.ts`, generated from one source. The bus
11
11
  * below is echo's alone and stays here.
12
12
  */
13
- import { quasarConnection as loadQuasarConnection } from "./vendor/quasarConnection.js";
13
+ import { isBusMessage, } from "./drivers/TieredDriver.js";
14
+ import { EchoError } from "./errors.js";
15
+ import { hasCommands, hasEnded, quasarConnection as loadQuasarConnection, } from "./vendor/quasarConnection.js";
14
16
  /**
15
17
  * The commands this driver actually issues.
16
18
  *
@@ -29,8 +31,20 @@ const REQUIRED = [
29
31
  "srem",
30
32
  "smembers",
31
33
  "expire",
34
+ "persist",
32
35
  "ttl",
33
36
  ];
37
+ /**
38
+ * The connection is handed over only once it carries every command above.
39
+ * `keys` and `exists` are declared but never called, so not required either;
40
+ * `scan` stays optional, but when there it has to be a function too.
41
+ */
42
+ function isRedisClient(value) {
43
+ return (hasCommands(value, REQUIRED) &&
44
+ (!("scan" in value) ||
45
+ value.scan === undefined ||
46
+ typeof value.scan === "function"));
47
+ }
34
48
  /**
35
49
  * A resolver for `drivers.redis({ connection })` — quasar is loaded on the
36
50
  * first cache command, not at config time.
@@ -40,8 +54,11 @@ export function quasarConnection(name) {
40
54
  pkg: "echo",
41
55
  name,
42
56
  required: REQUIRED,
57
+ isConnection: isRedisClient,
43
58
  what: "the cache store",
44
- raise: (_reason, message, cause) => new Error(message, { cause }),
59
+ raise: (reason, message, cause) => new EchoError(reason === "quasar-missing"
60
+ ? "E_ECHO_QUASAR_MISSING"
61
+ : "E_ECHO_INCOMPLETE_CONNECTION", message, { cause }),
45
62
  });
46
63
  }
47
64
  function isConnectionSource(value) {
@@ -72,7 +89,7 @@ async function loadQuasar(context) {
72
89
  : Reflect.get(Object(loaded), "default");
73
90
  }
74
91
  catch (cause) {
75
- throw new Error(`Echo: ${context}, but @c9up/quasar is not installed.\n pnpm add @c9up/quasar`, { cause });
92
+ throw new EchoError("E_ECHO_QUASAR_MISSING", `Echo: ${context}, but @c9up/quasar is not installed.\n pnpm add @c9up/quasar`, { cause });
76
93
  }
77
94
  }
78
95
  /**
@@ -92,15 +109,91 @@ export function quasarBus(options) {
92
109
  let ready;
93
110
  /** Per subscriber, the wrapper actually registered — once it has been. */
94
111
  const opened = new Map();
112
+ /** What `ready` settled to, so its state can be read. */
113
+ let current;
114
+ /**
115
+ * Subscriptions to carry over from a source that ended, taken when the end
116
+ * was noticed. A snapshot, not `opened` itself: a subscribe made after that
117
+ * moment waits on the new source, and waiting on it from here would be
118
+ * waiting on ourselves.
119
+ */
120
+ let moving;
121
+ /**
122
+ * Listen on `source`, waited on through the callbacks, not on the call's
123
+ * return value: `subscribe` reports a failure rather than rejecting, and
124
+ * newer quasar declares it `void`. This shape is correct against both.
125
+ */
126
+ const listen = (source, wrapper) => new Promise((resolve, reject) => {
127
+ source.subscribe(channel, wrapper, {
128
+ onSubscription: () => resolve(),
129
+ onError: (error) => reject(error instanceof Error ? error : new Error(String(error))),
130
+ });
131
+ });
132
+ /**
133
+ * Carry every listener over to the connection that replaced an ended one.
134
+ * The subscriptions lived on the dead subscriber socket — quasar drops
135
+ * them on its `end` — so without this the instance kept publishing on the
136
+ * new connection and never heard its peers again: every one served its
137
+ * stale L1 until the TTL ran out.
138
+ */
139
+ const move = async (from, to, pending) => {
140
+ for (const opening of pending) {
141
+ let wrapper;
142
+ try {
143
+ wrapper = await opening;
144
+ }
145
+ catch {
146
+ // Never subscribed: its own caller already saw the rejection.
147
+ continue;
148
+ }
149
+ await listen(to, wrapper);
150
+ try {
151
+ // Named, as everywhere else: the old connection may be shared.
152
+ await from.unsubscribe?.(channel, wrapper);
153
+ }
154
+ catch {
155
+ // The ended socket refuses; nothing listens on it any more anyway.
156
+ }
157
+ }
158
+ };
95
159
  const manager = () => {
96
- ready ??= loadQuasar(`the cache bus asks for the "${options?.connection ?? "default"}" quasar connection`).then((loaded) => {
160
+ // Re-resolved once the source has ended for good: quasar retires a
161
+ // connection whose retry strategy gave up and hands out a fresh one,
162
+ // and keeping the dead one failed every publish with "Connection is
163
+ // closed." until restart. NAMED DEVIATION, better than upstream, whose
164
+ // bus keeps the client it was built with.
165
+ if (current !== undefined && hasEnded(current)) {
166
+ moving ??= { from: current, pending: [...opened.values()] };
167
+ current = undefined;
168
+ ready = undefined;
169
+ }
170
+ ready ??= loadQuasar(`the cache bus asks for the "${options?.connection ?? "default"}" quasar connection`)
171
+ .then((loaded) => {
97
172
  const source = isConnectionSource(loaded)
98
173
  ? loaded.connection(options?.connection)
99
174
  : loaded;
100
175
  if (!isPubSubSource(source)) {
101
- throw new Error("Echo: the quasar connection does not expose publish()/subscribe()");
176
+ throw new EchoError("E_ECHO_INCOMPLETE_CONNECTION", "Echo: the quasar connection does not expose publish()/subscribe()");
177
+ }
178
+ return source;
179
+ })
180
+ .then(async (source) => {
181
+ // A move that fails leaves `moving` set, so the next call — which
182
+ // resolves again, since this one rejects — tries it again.
183
+ if (moving !== undefined && moving.from !== source) {
184
+ await move(moving.from, source, moving.pending);
102
185
  }
186
+ moving = undefined;
187
+ current = source;
103
188
  return source;
189
+ })
190
+ // Forgotten on failure, as the Redis driver forgets its client:
191
+ // kept, one rejection (quasar's provider not booted yet when an
192
+ // earlier provider wrote to a tiered store) was replayed by every
193
+ // later publish and subscribe for the life of the process.
194
+ .catch((error) => {
195
+ ready = undefined;
196
+ throw error;
104
197
  });
105
198
  return ready;
106
199
  };
@@ -111,12 +204,17 @@ export function quasarBus(options) {
111
204
  },
112
205
  async subscribe(handler) {
113
206
  const wrapper = (raw) => {
207
+ let frame;
114
208
  try {
115
- handler(JSON.parse(raw));
209
+ frame = JSON.parse(raw);
116
210
  }
117
211
  catch {
118
- /* a malformed frame is not a reason to stop listening */
212
+ // A malformed frame is not a reason to stop listening.
213
+ return;
119
214
  }
215
+ // Anything on the channel reaches here, not only what echo sent.
216
+ if (isBusMessage(frame))
217
+ handler(frame);
120
218
  };
121
219
  // AWAITED, and a reported failure becomes a rejection.
122
220
  //
@@ -131,18 +229,7 @@ export function quasarBus(options) {
131
229
  // quietly incoherent.
132
230
  const attempt = (async () => {
133
231
  const source = await manager();
134
- // Waited on through the callbacks, not on the call's return value:
135
- // `subscribe` reports a failure rather than rejecting, and newer
136
- // quasar declares it `void`. This shape is correct against both.
137
- await new Promise((resolve, reject) => {
138
- source.subscribe(channel, wrapper, {
139
- onSubscription: () => resolve(),
140
- onError: (error) => {
141
- opened.delete(handler);
142
- reject(error instanceof Error ? error : new Error(String(error)));
143
- },
144
- });
145
- });
232
+ await listen(source, wrapper);
146
233
  return wrapper;
147
234
  })();
148
235
  opened.set(handler, attempt);
@@ -1 +1 @@
1
- {"version":3,"file":"quasar.js","sourceRoot":"","sources":["../src/quasar.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"quasar.js","sourceRoot":"","sources":["../src/quasar.ts"],"names":[],"mappings":"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"}
@@ -10,7 +10,7 @@
10
10
  * await cache.set('user:42', user, 60)
11
11
  * const cached = await cache.get<User>('user:42')
12
12
  */
13
- import type { CacheManager } from "../CacheManager.js";
13
+ import { CacheManager } from "../CacheManager.js";
14
14
  /** @internal Bind the singleton (called by EchoProvider or by the app). */
15
15
  export declare function setCache(value: CacheManager): void;
16
16
  /** @internal Read the singleton (or `undefined` pre-boot). */
@@ -1 +1 @@
1
- {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,YAAY,GAAG,SAAS,CAEnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,QAAA,MAAM,KAAK,EAAE,YAoBX,CAAC;AAEH,eAAe,KAAK,CAAC"}
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKlD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,YAAY,GAAG,SAAS,CAEnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAwBD,QAAA,MAAM,KAAK,EAAE,YAeX,CAAC;AAEH,eAAe,KAAK,CAAC"}
@@ -10,6 +10,8 @@
10
10
  * await cache.set('user:42', user, 60)
11
11
  * const cached = await cache.get<User>('user:42')
12
12
  */
13
+ import { CacheManager } from "../CacheManager.js";
14
+ import { EchoError } from "../errors.js";
13
15
  let instance;
14
16
  /** @internal Bind the singleton (called by EchoProvider or by the app). */
15
17
  export function setCache(value) {
@@ -26,7 +28,24 @@ export function getCache() {
26
28
  export function clearCache() {
27
29
  instance = undefined;
28
30
  }
29
- const cache = new Proxy({}, {
31
+ /**
32
+ * What the proxy stands on. Never reached: every read goes through the trap
33
+ * below, to the bound manager or to the not-booted error. A real instance
34
+ * rather than an asserted `{}`, so the proxy is a `CacheManager` by type.
35
+ */
36
+ const unbooted = () => Promise.reject(notBooted());
37
+ const placeholder = new CacheManager({
38
+ get: unbooted,
39
+ set: unbooted,
40
+ delete: unbooted,
41
+ flush: unbooted,
42
+ has: unbooted,
43
+ });
44
+ function notBooted() {
45
+ return new EchoError("E_ECHO_NOT_BOOTED", "[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
46
+ "or `setCache(myCache)` was called. Wire one of them first.");
47
+ }
48
+ const cache = new Proxy(placeholder, {
30
49
  get(_target, prop) {
31
50
  // A module loader inspects what it imports before anyone uses it: it reads
32
51
  // `then` to decide whether the namespace is thenable, and various symbols
@@ -37,10 +56,8 @@ const cache = new Proxy({}, {
37
56
  if (typeof prop === "symbol" || prop === "then") {
38
57
  return undefined;
39
58
  }
40
- if (!instance) {
41
- throw new Error("[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
42
- "or `setCache(myCache)` was called. Wire one of them first.");
43
- }
59
+ if (!instance)
60
+ throw notBooted();
44
61
  const value = Reflect.get(instance, prop, instance);
45
62
  return typeof value === "function" ? value.bind(instance) : value;
46
63
  },
@@ -1 +1 @@
1
- {"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,IAAI,QAAkC,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC3C,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IACvB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACzB,QAAQ,GAAG,SAAS,CAAC;AACtB,CAAC;AAED,MAAM,KAAK,GAAiB,IAAI,KAAK,CAAC,EAAkB,EAAE;IACzD,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,2EAA2E;QAC3E,0EAA0E;QAC1E,8DAA8D;QAC9D,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,wEAAwE;gBACvE,4DAA4D,CAC7D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}
1
+ {"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,IAAI,QAAkC,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC3C,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IACvB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACzB,QAAQ,GAAG,SAAS,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,QAAQ,GAAG,GAAmB,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;AACnE,MAAM,WAAW,GAAG,IAAI,YAAY,CAAC;IACpC,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,QAAQ;IACf,GAAG,EAAE,QAAQ;CACb,CAAC,CAAC;AAEH,SAAS,SAAS;IACjB,OAAO,IAAI,SAAS,CACnB,mBAAmB,EACnB,wEAAwE;QACvE,4DAA4D,CAC7D,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAiB,IAAI,KAAK,CAAC,WAAW,EAAE;IAClD,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,2EAA2E;QAC3E,0EAA0E;QAC1E,8DAA8D;QAC9D,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,QAAQ;YAAE,MAAM,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}
package/dist/types.d.ts CHANGED
@@ -18,6 +18,13 @@ export interface CacheEntry<T = unknown> {
18
18
  * promotes an entry between tiers instead of resetting it to immortal.
19
19
  */
20
20
  expiresAt?: number;
21
+ /**
22
+ * The tags the entry was written with, when the driver keeps them. A
23
+ * composing driver needs them to promote an entry between tiers: a
24
+ * promoted copy written without its tags was invisible to `deleteByTag`
25
+ * on the very instance that promoted it.
26
+ */
27
+ tags?: string[];
21
28
  }
22
29
  /** Options for the grace-aware {@link CacheDriver.setEntry}. */
23
30
  export interface DriverSetOptions {
@@ -121,11 +128,21 @@ export interface GetOrSetOptions<T> {
121
128
  factory: Factory<T>;
122
129
  ttl?: Duration;
123
130
  grace?: Duration;
131
+ /**
132
+ * After the factory failed and the stale value was served, how long that
133
+ * value counts as fresh before the factory is tried again. Default
134
+ * `'10s'` (or the store's); `0` or `null` retries on the next call.
135
+ */
136
+ graceBackoff?: Duration;
124
137
  /** Soft timeout: on a stale hit, return the stale value if the factory is slower, then refresh in the background. */
125
138
  timeout?: Duration;
126
139
  /** Hard timeout: reject with {@link TimeoutError} if the factory exceeds it (even without a stale fallback). */
127
140
  hardTimeout?: Duration;
128
- /** Max time to wait on another caller's in-flight factory before falling back to stale (single-flight lock). */
141
+ /**
142
+ * Max time to wait on another caller's in-flight factory for the same key
143
+ * (single-flight lock). Past it the stale value is returned when there is
144
+ * one, and a {@link LockTimeoutError} is thrown when there is not.
145
+ */
129
146
  lockTimeout?: Duration;
130
147
  tags?: string[];
131
148
  /** Observe factory failures (foreground and background). */
@@ -147,29 +164,54 @@ export interface HasOptions {
147
164
  export interface ExpireOptions {
148
165
  key: string;
149
166
  }
150
- /** Payloads for each emitted cache event (bento event-name parity). */
167
+ /**
168
+ * Payloads for each emitted cache event (bento event-name parity).
169
+ *
170
+ * Upstream's fields, plus two of our own that a profiler needs and upstream's
171
+ * payloads do not carry: `duration`, the milliseconds from the call to the
172
+ * event, and on a write its `ttl`, as Laravel's `KeyWritten` reports it.
173
+ * Additive: a listener written against upstream's shape reads what it read.
174
+ */
151
175
  export interface CacheEventMap {
152
176
  "cache:hit": {
153
177
  key: string;
154
178
  value: unknown;
155
179
  store: string;
156
180
  graced: boolean;
181
+ duration: number;
157
182
  };
183
+ /**
184
+ * Reported once the call is served. For `getOrSet` that is after its
185
+ * factory ran, as upstream reports it, so `duration` includes the factory.
186
+ */
158
187
  "cache:miss": {
159
188
  key: string;
160
189
  store: string;
190
+ duration: number;
161
191
  };
162
192
  "cache:written": {
163
193
  key: string;
164
194
  value: unknown;
165
195
  store: string;
196
+ /** Seconds the entry lives, `null` when it never expires. */
197
+ ttl: number | null;
198
+ /** The write alone: a `getOrSet`'s factory is counted in its miss. */
199
+ duration: number;
166
200
  };
167
201
  "cache:deleted": {
168
202
  key: string;
169
203
  store: string;
204
+ duration: number;
170
205
  };
171
206
  "cache:cleared": {
172
207
  store: string;
208
+ duration: number;
209
+ };
210
+ /** A key marked stale by `expire()`, kept for its grace window or dropped. */
211
+ "cache:expire": {
212
+ key: string;
213
+ store: string;
214
+ duration: number;
173
215
  };
174
216
  }
175
217
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACtC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAChC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnE,yBAAyB;IACzB,QAAQ,CAAC,CACR,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,WAAW,CACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,mFAAmF;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,oEAAoE;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,4BAA4B;AAC5B,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE9C,iDAAiD;AACjD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAE5C,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,qHAAqH;IACrH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,gHAAgH;IAChH,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,gHAAgH;IAChH,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAExE,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;CACZ;AACD,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AACD,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AACD,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;CACZ;AACD,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,eAAe,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC/C"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,aAAa,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACtC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAChC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,uFAAuF;IACvF,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnE,yBAAyB;IACzB,QAAQ,CAAC,CACR,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,WAAW,CACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,mFAAmF;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,oEAAoE;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,4BAA4B;AAC5B,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE9C,iDAAiD;AACjD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAE5C,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,qHAAqH;IACrH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,gHAAgH;IAChH,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAExE,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;CACZ;AACD,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AACD,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AACD,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;CACZ;AACD,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KACjB,CAAC;IACF;;;OAGG;IACH,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,eAAe,EAAE;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,6DAA6D;QAC7D,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,sEAAsE;QACtE,QAAQ,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,eAAe,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,eAAe,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,8EAA8E;IAC9E,cAAc,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC/C"}
@@ -1,4 +1,37 @@
1
- export interface QuasarConnectionRequest {
1
+ /**
2
+ * The commands among `commands` that `value` does not carry as functions.
3
+ *
4
+ * Reads go through the same catch as above, so a command whose read throws
5
+ * counts as missing.
6
+ */
7
+ export declare function missingCommands(value: unknown, commands: readonly string[]): string[];
8
+ /**
9
+ * Whether `value` carries every one of `commands` as a function.
10
+ *
11
+ * The building block of the guard a caller passes as `isConnection`, over the
12
+ * same list it passes as `required` — which is what names the gap when the
13
+ * guard says no.
14
+ */
15
+ export declare function hasCommands(value: unknown, commands: readonly string[]): value is object;
16
+ /**
17
+ * Whether a client resolved earlier has ended for good, and must be resolved
18
+ * again rather than used.
19
+ *
20
+ * ioredis reaches `end` once its retry strategy gives up (quasar's generated
21
+ * config gives up after ten attempts, about three seconds of outage), or after
22
+ * `quit()`/`disconnect()`. From there every command rejects with "Connection is
23
+ * closed." and the client never comes back. Quasar drops such a connection and
24
+ * hands out a fresh one on the next `connection(name)`, so a store that kept
25
+ * the first answer of its resolver stayed on the dead client until the process
26
+ * restarted, even once Redis was back.
27
+ *
28
+ * `close` is NOT terminal: ioredis reconnects from it by itself, and throwing
29
+ * that client away would leak its socket. A client with no `status` (a test
30
+ * double, another library) never counts as ended. Only meaningful for a
31
+ * resolver: a client handed in directly is the caller's to replace.
32
+ */
33
+ export declare function hasEnded(client: unknown): boolean;
34
+ export interface QuasarConnectionRequest<T> {
2
35
  /** The package asking. It prefixes every message this can raise. */
3
36
  pkg: string;
4
37
  /**
@@ -12,8 +45,16 @@ export interface QuasarConnectionRequest {
12
45
  raise: (reason: "quasar-missing" | "incomplete-connection", message: string, cause?: unknown) => Error;
13
46
  /** Connection name, or `undefined` for quasar's default. */
14
47
  name?: string;
15
- /** The commands the caller will actually issue. */
48
+ /** The commands the caller will actually issue, named in the message. */
16
49
  required: readonly string[];
50
+ /**
51
+ * The caller's check that the connection is the client it needs.
52
+ *
53
+ * Written by the caller over the commands it issues (`hasCommands` with
54
+ * `required` does it), because only the caller knows its client type. The
55
+ * connection is handed over only once this has said yes.
56
+ */
57
+ isConnection: (value: unknown) => value is T;
17
58
  /** What the caller does with them, for the message that names a gap. */
18
59
  what: string;
19
60
  /**
@@ -31,5 +72,5 @@ export interface QuasarConnectionRequest {
31
72
  * handed over — a connection missing one would otherwise fail on the first
32
73
  * command, far from the line that asked for it.
33
74
  */
34
- export declare function quasarConnection<T>(request: QuasarConnectionRequest): Promise<T>;
75
+ export declare function quasarConnection<T>(request: QuasarConnectionRequest<T>): Promise<T>;
35
76
  //# sourceMappingURL=quasarConnection.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"quasarConnection.d.ts","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,uBAAuB;IACvC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,KAAK,EAAE,CACN,MAAM,EAAE,gBAAgB,GAAG,uBAAuB,EAClD,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,KACX,KAAK,CAAC;IACX,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAuCZ"}
1
+ {"version":3,"file":"quasarConnection.d.ts","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"AA0DA;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAIV;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,KAAK,IAAI,MAAM,CAGjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACzC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,KAAK,EAAE,CACN,MAAM,EAAE,gBAAgB,GAAG,uBAAuB,EAClD,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,KACX,KAAK,CAAC;IACX,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;IAC7C,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,CAAC,CAAC,CAsDZ"}
@@ -3,29 +3,62 @@
3
3
  // This package is published and built from its own repository, so the file
4
4
  // has to exist here rather than be imported. `pnpm vendor:sync` rewrites it,
5
5
  // and `pnpm vendor:check` fails if this copy has drifted from the original.
6
- /**
7
- * Read a member without assuming how the object answers.
8
- *
9
- * Two shapes have to work, and they disagree about `in`. Quasar's accessor is
10
- * a Proxy over an empty null-prototype object with only a `get` trap, so
11
- * `"connection" in manager` is FALSE while reading it returns the function —
12
- * gating on `in` rejected the real manager. And a module namespace under a
13
- * test double RAISES for an export it does not have, rather than answering
14
- * undefined, so a bare read fails on the mock. Reading through a catch is what
15
- * satisfies both.
16
- */
17
6
  function readMember(value, name) {
18
7
  if (typeof value !== "object" || value === null)
19
- return undefined;
8
+ return { value: undefined };
20
9
  try {
21
- return Reflect.get(value, name);
10
+ return { value: Reflect.get(value, name) };
22
11
  }
23
- catch {
24
- return undefined;
12
+ catch (threw) {
13
+ return { threw };
25
14
  }
26
15
  }
16
+ function memberValue(read) {
17
+ return "value" in read ? read.value : undefined;
18
+ }
27
19
  function isConnectionSource(value) {
28
- return typeof readMember(value, "connection") === "function";
20
+ return typeof memberValue(readMember(value, "connection")) === "function";
21
+ }
22
+ /**
23
+ * The commands among `commands` that `value` does not carry as functions.
24
+ *
25
+ * Reads go through the same catch as above, so a command whose read throws
26
+ * counts as missing.
27
+ */
28
+ export function missingCommands(value, commands) {
29
+ return commands.filter((command) => typeof memberValue(readMember(value, command)) !== "function");
30
+ }
31
+ /**
32
+ * Whether `value` carries every one of `commands` as a function.
33
+ *
34
+ * The building block of the guard a caller passes as `isConnection`, over the
35
+ * same list it passes as `required` — which is what names the gap when the
36
+ * guard says no.
37
+ */
38
+ export function hasCommands(value, commands) {
39
+ if (typeof value !== "object" || value === null)
40
+ return false;
41
+ return missingCommands(value, commands).length === 0;
42
+ }
43
+ /**
44
+ * Whether a client resolved earlier has ended for good, and must be resolved
45
+ * again rather than used.
46
+ *
47
+ * ioredis reaches `end` once its retry strategy gives up (quasar's generated
48
+ * config gives up after ten attempts, about three seconds of outage), or after
49
+ * `quit()`/`disconnect()`. From there every command rejects with "Connection is
50
+ * closed." and the client never comes back. Quasar drops such a connection and
51
+ * hands out a fresh one on the next `connection(name)`, so a store that kept
52
+ * the first answer of its resolver stayed on the dead client until the process
53
+ * restarted, even once Redis was back.
54
+ *
55
+ * `close` is NOT terminal: ioredis reconnects from it by itself, and throwing
56
+ * that client away would leak its socket. A client with no `status` (a test
57
+ * double, another library) never counts as ended. Only meaningful for a
58
+ * resolver: a client handed in directly is the caller's to replace.
59
+ */
60
+ export function hasEnded(client) {
61
+ return memberValue(readMember(client, "status")) === "end";
29
62
  }
30
63
  /**
31
64
  * The named connection, checked for the commands the caller needs BEFORE it is
@@ -33,7 +66,7 @@ function isConnectionSource(value) {
33
66
  * command, far from the line that asked for it.
34
67
  */
35
68
  export async function quasarConnection(request) {
36
- const { pkg, name, required, what, raise, alternative } = request;
69
+ const { pkg, name, required, what, raise, alternative, isConnection } = request;
37
70
  const specifier = "@c9up/quasar/services/main";
38
71
  let loaded;
39
72
  try {
@@ -43,20 +76,28 @@ export async function quasarConnection(request) {
43
76
  throw raise("quasar-missing", `[${pkg}] ${what} asks for the quasar connection "${name ?? "default"}", but @c9up/quasar is not installed.\n` +
44
77
  ` pnpm add @c9up/quasar${alternative ? `, ${alternative}` : ""}`, cause);
45
78
  }
46
- const manager = isConnectionSource(loaded)
79
+ // The namespace itself may be the manager (a test double); a throw there is
80
+ // the mock refusing an export it lacks, not an answer.
81
+ const direct = memberValue(readMember(loaded, "connection"));
82
+ const manager = typeof direct === "function"
47
83
  ? loaded
48
- : Reflect.get(Object(loaded), "default");
84
+ : memberValue(readMember(Object(loaded), "default"));
85
+ const read = readMember(manager, "connection");
86
+ if ("threw" in read) {
87
+ throw raise("quasar-missing", `[${pkg}] ${what} asks for the quasar connection "${name ?? "default"}", but @c9up/quasar's manager is not available yet: ` +
88
+ "its provider has not booted, or is not registered in this application's providers.", read.threw);
89
+ }
49
90
  if (!isConnectionSource(manager)) {
50
91
  throw raise("quasar-missing", `[${pkg}] @c9up/quasar/services/main did not expose a connection() manager`);
51
92
  }
52
93
  const connection = manager.connection(name);
53
- const missing = required.filter((command) => typeof readMember(connection, command) !== "function");
94
+ const missing = missingCommands(connection, required);
54
95
  if (missing.length > 0) {
55
96
  throw raise("incomplete-connection", `[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is missing ${missing.join(", ")}, which ${what} issues`);
56
97
  }
57
- // Load-bearing: every member of `required` has just been checked to be a
58
- // function on this object. The caller names the type it needs because only
59
- // the caller knows which commands it asked for.
98
+ if (!isConnection(connection)) {
99
+ throw raise("incomplete-connection", `[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is not the client ${what} needs`);
100
+ }
60
101
  return connection;
61
102
  }
62
103
  //# sourceMappingURL=quasarConnection.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"quasarConnection.js","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAqB5E;;;;;;;;;;GAUG;AACH,SAAS,UAAU,CAAC,KAAc,EAAE,IAAY;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,IAAI,CAAC;QACJ,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;AACF,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACzC,OAAO,OAAO,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,UAAU,CAAC;AAC9D,CAAC;AAmCD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,OAAgC;IAEhC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,SAAS,GAAG,4BAA4B,CAAC;IAC/C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,KAAK,CACV,gBAAgB,EAChB,IAAI,GAAG,KAAK,IAAI,oCAAoC,IAAI,IAAI,SAAS,yCAAyC;YAC7G,0BAA0B,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAClE,KAAK,CACL,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC;QACzC,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,CACV,gBAAgB,EAChB,IAAI,GAAG,oEAAoE,CAC3E,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAC9B,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,UAAU,CAClE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,CACV,uBAAuB,EACvB,IAAI,GAAG,0BAA0B,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,SAAS,CAClH,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,2EAA2E;IAC3E,gDAAgD;IAChD,OAAO,UAAe,CAAC;AACxB,CAAC"}
1
+ {"version":3,"file":"quasarConnection.js","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@c9up/echo",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "Cache — pluggable cache contract with memory + Redis drivers for the Ream framework",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -26,6 +26,10 @@
26
26
  "./testing": {
27
27
  "types": "./dist/testing/main.d.ts",
28
28
  "import": "./dist/testing/main.js"
29
+ },
30
+ "./commands": {
31
+ "types": "./dist/console/index.d.ts",
32
+ "import": "./dist/console/index.js"
29
33
  }
30
34
  },
31
35
  "peerDependencies": {