@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
package/src/quasar.ts CHANGED
@@ -12,8 +12,17 @@
12
12
  */
13
13
 
14
14
  import type { RedisClient } from "./drivers/RedisDriver.js";
15
- import type { BusMessage, CacheBus } from "./drivers/TieredDriver.js";
16
- import { quasarConnection as loadQuasarConnection } from "./vendor/quasarConnection.js";
15
+ import {
16
+ type BusMessage,
17
+ type CacheBus,
18
+ isBusMessage,
19
+ } from "./drivers/TieredDriver.js";
20
+ import { EchoError } from "./errors.js";
21
+ import {
22
+ hasCommands,
23
+ hasEnded,
24
+ quasarConnection as loadQuasarConnection,
25
+ } from "./vendor/quasarConnection.js";
17
26
 
18
27
  /**
19
28
  * The commands this driver actually issues.
@@ -33,21 +42,44 @@ const REQUIRED = [
33
42
  "srem",
34
43
  "smembers",
35
44
  "expire",
45
+ "persist",
36
46
  "ttl",
37
47
  ] as const;
38
48
 
49
+ /**
50
+ * The connection is handed over only once it carries every command above.
51
+ * `keys` and `exists` are declared but never called, so not required either;
52
+ * `scan` stays optional, but when there it has to be a function too.
53
+ */
54
+ function isRedisClient(value: unknown): value is RedisClient {
55
+ return (
56
+ hasCommands(value, REQUIRED) &&
57
+ (!("scan" in value) ||
58
+ value.scan === undefined ||
59
+ typeof value.scan === "function")
60
+ );
61
+ }
62
+
39
63
  /**
40
64
  * A resolver for `drivers.redis({ connection })` — quasar is loaded on the
41
65
  * first cache command, not at config time.
42
66
  */
43
67
  export function quasarConnection(name?: string): () => Promise<RedisClient> {
44
68
  return async () =>
45
- loadQuasarConnection<RedisClient>({
69
+ loadQuasarConnection({
46
70
  pkg: "echo",
47
71
  name,
48
72
  required: REQUIRED,
73
+ isConnection: isRedisClient,
49
74
  what: "the cache store",
50
- raise: (_reason, message, cause) => new Error(message, { cause }),
75
+ raise: (reason, message, cause) =>
76
+ new EchoError(
77
+ reason === "quasar-missing"
78
+ ? "E_ECHO_QUASAR_MISSING"
79
+ : "E_ECHO_INCOMPLETE_CONNECTION",
80
+ message,
81
+ { cause },
82
+ ),
51
83
  });
52
84
  }
53
85
 
@@ -114,7 +146,8 @@ async function loadQuasar(context: string): Promise<unknown> {
114
146
  ? loaded
115
147
  : Reflect.get(Object(loaded), "default");
116
148
  } catch (cause) {
117
- throw new Error(
149
+ throw new EchoError(
150
+ "E_ECHO_QUASAR_MISSING",
118
151
  `Echo: ${context}, but @c9up/quasar is not installed.\n pnpm add @c9up/quasar`,
119
152
  { cause },
120
153
  );
@@ -145,20 +178,109 @@ export function quasarBus(options?: {
145
178
  Promise<(raw: string) => void>
146
179
  >();
147
180
 
181
+ /** What `ready` settled to, so its state can be read. */
182
+ let current: PubSubSource | undefined;
183
+ /**
184
+ * Subscriptions to carry over from a source that ended, taken when the end
185
+ * was noticed. A snapshot, not `opened` itself: a subscribe made after that
186
+ * moment waits on the new source, and waiting on it from here would be
187
+ * waiting on ourselves.
188
+ */
189
+ let moving:
190
+ | { from: PubSubSource; pending: Array<Promise<(raw: string) => void>> }
191
+ | undefined;
192
+
193
+ /**
194
+ * Listen on `source`, waited on through the callbacks, not on the call's
195
+ * return value: `subscribe` reports a failure rather than rejecting, and
196
+ * newer quasar declares it `void`. This shape is correct against both.
197
+ */
198
+ const listen = (
199
+ source: PubSubSource,
200
+ wrapper: (raw: string) => void,
201
+ ): Promise<void> =>
202
+ new Promise<void>((resolve, reject) => {
203
+ source.subscribe(channel, wrapper, {
204
+ onSubscription: () => resolve(),
205
+ onError: (error) =>
206
+ reject(error instanceof Error ? error : new Error(String(error))),
207
+ });
208
+ });
209
+
210
+ /**
211
+ * Carry every listener over to the connection that replaced an ended one.
212
+ * The subscriptions lived on the dead subscriber socket — quasar drops
213
+ * them on its `end` — so without this the instance kept publishing on the
214
+ * new connection and never heard its peers again: every one served its
215
+ * stale L1 until the TTL ran out.
216
+ */
217
+ const move = async (
218
+ from: PubSubSource,
219
+ to: PubSubSource,
220
+ pending: Array<Promise<(raw: string) => void>>,
221
+ ): Promise<void> => {
222
+ for (const opening of pending) {
223
+ let wrapper: (raw: string) => void;
224
+ try {
225
+ wrapper = await opening;
226
+ } catch {
227
+ // Never subscribed: its own caller already saw the rejection.
228
+ continue;
229
+ }
230
+ await listen(to, wrapper);
231
+ try {
232
+ // Named, as everywhere else: the old connection may be shared.
233
+ await from.unsubscribe?.(channel, wrapper);
234
+ } catch {
235
+ // The ended socket refuses; nothing listens on it any more anyway.
236
+ }
237
+ }
238
+ };
239
+
148
240
  const manager = (): Promise<PubSubSource> => {
241
+ // Re-resolved once the source has ended for good: quasar retires a
242
+ // connection whose retry strategy gave up and hands out a fresh one,
243
+ // and keeping the dead one failed every publish with "Connection is
244
+ // closed." until restart. NAMED DEVIATION, better than upstream, whose
245
+ // bus keeps the client it was built with.
246
+ if (current !== undefined && hasEnded(current)) {
247
+ moving ??= { from: current, pending: [...opened.values()] };
248
+ current = undefined;
249
+ ready = undefined;
250
+ }
149
251
  ready ??= loadQuasar(
150
252
  `the cache bus asks for the "${options?.connection ?? "default"}" quasar connection`,
151
- ).then((loaded) => {
152
- const source = isConnectionSource(loaded)
153
- ? loaded.connection(options?.connection)
154
- : loaded;
155
- if (!isPubSubSource(source)) {
156
- throw new Error(
157
- "Echo: the quasar connection does not expose publish()/subscribe()",
158
- );
159
- }
160
- return source;
161
- });
253
+ )
254
+ .then((loaded) => {
255
+ const source = isConnectionSource(loaded)
256
+ ? loaded.connection(options?.connection)
257
+ : loaded;
258
+ if (!isPubSubSource(source)) {
259
+ throw new EchoError(
260
+ "E_ECHO_INCOMPLETE_CONNECTION",
261
+ "Echo: the quasar connection does not expose publish()/subscribe()",
262
+ );
263
+ }
264
+ return source;
265
+ })
266
+ .then(async (source) => {
267
+ // A move that fails leaves `moving` set, so the next call — which
268
+ // resolves again, since this one rejects — tries it again.
269
+ if (moving !== undefined && moving.from !== source) {
270
+ await move(moving.from, source, moving.pending);
271
+ }
272
+ moving = undefined;
273
+ current = source;
274
+ return source;
275
+ })
276
+ // Forgotten on failure, as the Redis driver forgets its client:
277
+ // kept, one rejection (quasar's provider not booted yet when an
278
+ // earlier provider wrote to a tiered store) was replayed by every
279
+ // later publish and subscribe for the life of the process.
280
+ .catch((error: unknown) => {
281
+ ready = undefined;
282
+ throw error;
283
+ });
162
284
  return ready;
163
285
  };
164
286
 
@@ -169,11 +291,15 @@ export function quasarBus(options?: {
169
291
  },
170
292
  async subscribe(handler: (message: BusMessage) => void): Promise<void> {
171
293
  const wrapper = (raw: string): void => {
294
+ let frame: unknown;
172
295
  try {
173
- handler(JSON.parse(raw) as BusMessage);
296
+ frame = JSON.parse(raw);
174
297
  } catch {
175
- /* a malformed frame is not a reason to stop listening */
298
+ // A malformed frame is not a reason to stop listening.
299
+ return;
176
300
  }
301
+ // Anything on the channel reaches here, not only what echo sent.
302
+ if (isBusMessage(frame)) handler(frame);
177
303
  };
178
304
  // AWAITED, and a reported failure becomes a rejection.
179
305
  //
@@ -188,18 +314,7 @@ export function quasarBus(options?: {
188
314
  // quietly incoherent.
189
315
  const attempt = (async (): Promise<(raw: string) => void> => {
190
316
  const source = await manager();
191
- // Waited on through the callbacks, not on the call's return value:
192
- // `subscribe` reports a failure rather than rejecting, and newer
193
- // quasar declares it `void`. This shape is correct against both.
194
- await new Promise<void>((resolve, reject) => {
195
- source.subscribe(channel, wrapper, {
196
- onSubscription: () => resolve(),
197
- onError: (error) => {
198
- opened.delete(handler);
199
- reject(error instanceof Error ? error : new Error(String(error)));
200
- },
201
- });
202
- });
317
+ await listen(source, wrapper);
203
318
  return wrapper;
204
319
  })();
205
320
  opened.set(handler, attempt);
@@ -11,7 +11,8 @@
11
11
  * const cached = await cache.get<User>('user:42')
12
12
  */
13
13
 
14
- import type { CacheManager } from "../CacheManager.js";
14
+ import { CacheManager } from "../CacheManager.js";
15
+ import { EchoError } from "../errors.js";
15
16
 
16
17
  let instance: CacheManager | undefined;
17
18
 
@@ -33,7 +34,29 @@ export function clearCache(): void {
33
34
  instance = undefined;
34
35
  }
35
36
 
36
- const cache: CacheManager = new Proxy({} as CacheManager, {
37
+ /**
38
+ * What the proxy stands on. Never reached: every read goes through the trap
39
+ * below, to the bound manager or to the not-booted error. A real instance
40
+ * rather than an asserted `{}`, so the proxy is a `CacheManager` by type.
41
+ */
42
+ const unbooted = (): Promise<never> => Promise.reject(notBooted());
43
+ const placeholder = new CacheManager({
44
+ get: unbooted,
45
+ set: unbooted,
46
+ delete: unbooted,
47
+ flush: unbooted,
48
+ has: unbooted,
49
+ });
50
+
51
+ function notBooted(): EchoError {
52
+ return new EchoError(
53
+ "E_ECHO_NOT_BOOTED",
54
+ "[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
55
+ "or `setCache(myCache)` was called. Wire one of them first.",
56
+ );
57
+ }
58
+
59
+ const cache: CacheManager = new Proxy(placeholder, {
37
60
  get(_target, prop) {
38
61
  // A module loader inspects what it imports before anyone uses it: it reads
39
62
  // `then` to decide whether the namespace is thenable, and various symbols
@@ -44,12 +67,7 @@ const cache: CacheManager = new Proxy({} as CacheManager, {
44
67
  if (typeof prop === "symbol" || prop === "then") {
45
68
  return undefined;
46
69
  }
47
- if (!instance) {
48
- throw new Error(
49
- "[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
50
- "or `setCache(myCache)` was called. Wire one of them first.",
51
- );
52
- }
70
+ if (!instance) throw notBooted();
53
71
  const value = Reflect.get(instance, prop, instance);
54
72
  return typeof value === "function" ? value.bind(instance) : value;
55
73
  },
package/src/types.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  */
5
5
 
6
6
  import type { Duration } from "./duration.js";
7
- import type { FactoryError } from "./errors.js";
7
+ import type { FactoryError, LockTimeoutError } from "./errors.js";
8
8
 
9
9
  /**
10
10
  * A driver-level entry. `stale` is `true` when the value is past its logical
@@ -20,6 +20,13 @@ export interface CacheEntry<T = unknown> {
20
20
  * promotes an entry between tiers instead of resetting it to immortal.
21
21
  */
22
22
  expiresAt?: number;
23
+ /**
24
+ * The tags the entry was written with, when the driver keeps them. A
25
+ * composing driver needs them to promote an entry between tiers: a
26
+ * promoted copy written without its tags was invisible to `deleteByTag`
27
+ * on the very instance that promoted it.
28
+ */
29
+ tags?: string[];
23
30
  }
24
31
 
25
32
  /** Options for the grace-aware {@link CacheDriver.setEntry}. */
@@ -140,11 +147,21 @@ export interface GetOrSetOptions<T> {
140
147
  factory: Factory<T>;
141
148
  ttl?: Duration;
142
149
  grace?: Duration;
150
+ /**
151
+ * After the factory failed and the stale value was served, how long that
152
+ * value counts as fresh before the factory is tried again. Default
153
+ * `'10s'` (or the store's); `0` or `null` retries on the next call.
154
+ */
155
+ graceBackoff?: Duration;
143
156
  /** Soft timeout: on a stale hit, return the stale value if the factory is slower, then refresh in the background. */
144
157
  timeout?: Duration;
145
158
  /** Hard timeout: reject with {@link TimeoutError} if the factory exceeds it (even without a stale fallback). */
146
159
  hardTimeout?: Duration;
147
- /** Max time to wait on another caller's in-flight factory before falling back to stale (single-flight lock). */
160
+ /**
161
+ * Max time to wait on another caller's in-flight factory for the same key
162
+ * (single-flight lock). Past it the stale value is returned when there is
163
+ * one, and a {@link LockTimeoutError} is thrown when there is not.
164
+ */
148
165
  lockTimeout?: Duration;
149
166
  tags?: string[];
150
167
  /** Observe factory failures (foreground and background). */
@@ -169,18 +186,40 @@ export interface ExpireOptions {
169
186
  key: string;
170
187
  }
171
188
 
172
- /** Payloads for each emitted cache event (bento event-name parity). */
189
+ /**
190
+ * Payloads for each emitted cache event (bento event-name parity).
191
+ *
192
+ * Upstream's fields, plus two of our own that a profiler needs and upstream's
193
+ * payloads do not carry: `duration`, the milliseconds from the call to the
194
+ * event, and on a write its `ttl`, as Laravel's `KeyWritten` reports it.
195
+ * Additive: a listener written against upstream's shape reads what it read.
196
+ */
173
197
  export interface CacheEventMap {
174
198
  "cache:hit": {
175
199
  key: string;
176
200
  value: unknown;
177
201
  store: string;
178
202
  graced: boolean;
203
+ duration: number;
204
+ };
205
+ /**
206
+ * Reported once the call is served. For `getOrSet` that is after its
207
+ * factory ran, as upstream reports it, so `duration` includes the factory.
208
+ */
209
+ "cache:miss": { key: string; store: string; duration: number };
210
+ "cache:written": {
211
+ key: string;
212
+ value: unknown;
213
+ store: string;
214
+ /** Seconds the entry lives, `null` when it never expires. */
215
+ ttl: number | null;
216
+ /** The write alone: a `getOrSet`'s factory is counted in its miss. */
217
+ duration: number;
179
218
  };
180
- "cache:miss": { key: string; store: string };
181
- "cache:written": { key: string; value: unknown; store: string };
182
- "cache:deleted": { key: string; store: string };
183
- "cache:cleared": { store: string };
219
+ "cache:deleted": { key: string; store: string; duration: number };
220
+ "cache:cleared": { store: string; duration: number };
221
+ /** A key marked stale by `expire()`, kept for its grace window or dropped. */
222
+ "cache:expire": { key: string; store: string; duration: number };
184
223
  }
185
224
 
186
225
  /**
@@ -31,23 +31,83 @@ interface ConnectionSource {
31
31
  * `"connection" in manager` is FALSE while reading it returns the function —
32
32
  * gating on `in` rejected the real manager. And a module namespace under a
33
33
  * test double RAISES for an export it does not have, rather than answering
34
- * undefined, so a bare read fails on the mock. Reading through a catch is what
35
- * satisfies both.
34
+ * undefined, so a bare read fails on the mock.
35
+ *
36
+ * So the read is caught, but what it raised is kept: on quasar's accessor a
37
+ * throw is not an absence, it is the accessor saying its provider has not
38
+ * booted, and dropping that turned it into a wrong diagnosis.
36
39
  */
37
- function readMember(value: unknown, name: string): unknown {
38
- if (typeof value !== "object" || value === null) return undefined;
40
+ type MemberRead = { value: unknown } | { threw: unknown };
41
+
42
+ function readMember(value: unknown, name: string): MemberRead {
43
+ if (typeof value !== "object" || value === null) return { value: undefined };
39
44
  try {
40
- return Reflect.get(value, name);
41
- } catch {
42
- return undefined;
45
+ return { value: Reflect.get(value, name) };
46
+ } catch (threw) {
47
+ return { threw };
43
48
  }
44
49
  }
45
50
 
51
+ function memberValue(read: MemberRead): unknown {
52
+ return "value" in read ? read.value : undefined;
53
+ }
54
+
46
55
  function isConnectionSource(value: unknown): value is ConnectionSource {
47
- return typeof readMember(value, "connection") === "function";
56
+ return typeof memberValue(readMember(value, "connection")) === "function";
48
57
  }
49
58
 
50
- export interface QuasarConnectionRequest {
59
+ /**
60
+ * The commands among `commands` that `value` does not carry as functions.
61
+ *
62
+ * Reads go through the same catch as above, so a command whose read throws
63
+ * counts as missing.
64
+ */
65
+ export function missingCommands(
66
+ value: unknown,
67
+ commands: readonly string[],
68
+ ): string[] {
69
+ return commands.filter(
70
+ (command) => typeof memberValue(readMember(value, command)) !== "function",
71
+ );
72
+ }
73
+
74
+ /**
75
+ * Whether `value` carries every one of `commands` as a function.
76
+ *
77
+ * The building block of the guard a caller passes as `isConnection`, over the
78
+ * same list it passes as `required` — which is what names the gap when the
79
+ * guard says no.
80
+ */
81
+ export function hasCommands(
82
+ value: unknown,
83
+ commands: readonly string[],
84
+ ): value is object {
85
+ if (typeof value !== "object" || value === null) return false;
86
+ return missingCommands(value, commands).length === 0;
87
+ }
88
+
89
+ /**
90
+ * Whether a client resolved earlier has ended for good, and must be resolved
91
+ * again rather than used.
92
+ *
93
+ * ioredis reaches `end` once its retry strategy gives up (quasar's generated
94
+ * config gives up after ten attempts, about three seconds of outage), or after
95
+ * `quit()`/`disconnect()`. From there every command rejects with "Connection is
96
+ * closed." and the client never comes back. Quasar drops such a connection and
97
+ * hands out a fresh one on the next `connection(name)`, so a store that kept
98
+ * the first answer of its resolver stayed on the dead client until the process
99
+ * restarted, even once Redis was back.
100
+ *
101
+ * `close` is NOT terminal: ioredis reconnects from it by itself, and throwing
102
+ * that client away would leak its socket. A client with no `status` (a test
103
+ * double, another library) never counts as ended. Only meaningful for a
104
+ * resolver: a client handed in directly is the caller's to replace.
105
+ */
106
+ export function hasEnded(client: unknown): boolean {
107
+ return memberValue(readMember(client, "status")) === "end";
108
+ }
109
+
110
+ export interface QuasarConnectionRequest<T> {
51
111
  /** The package asking. It prefixes every message this can raise. */
52
112
  pkg: string;
53
113
  /**
@@ -65,8 +125,16 @@ export interface QuasarConnectionRequest {
65
125
  ) => Error;
66
126
  /** Connection name, or `undefined` for quasar's default. */
67
127
  name?: string;
68
- /** The commands the caller will actually issue. */
128
+ /** The commands the caller will actually issue, named in the message. */
69
129
  required: readonly string[];
130
+ /**
131
+ * The caller's check that the connection is the client it needs.
132
+ *
133
+ * Written by the caller over the commands it issues (`hasCommands` with
134
+ * `required` does it), because only the caller knows its client type. The
135
+ * connection is handed over only once this has said yes.
136
+ */
137
+ isConnection: (value: unknown) => value is T;
70
138
  /** What the caller does with them, for the message that names a gap. */
71
139
  what: string;
72
140
  /**
@@ -86,9 +154,10 @@ export interface QuasarConnectionRequest {
86
154
  * command, far from the line that asked for it.
87
155
  */
88
156
  export async function quasarConnection<T>(
89
- request: QuasarConnectionRequest,
157
+ request: QuasarConnectionRequest<T>,
90
158
  ): Promise<T> {
91
- const { pkg, name, required, what, raise, alternative } = request;
159
+ const { pkg, name, required, what, raise, alternative, isConnection } =
160
+ request;
92
161
  const specifier = "@c9up/quasar/services/main";
93
162
  let loaded: unknown;
94
163
  try {
@@ -102,9 +171,22 @@ export async function quasarConnection<T>(
102
171
  );
103
172
  }
104
173
 
105
- const manager = isConnectionSource(loaded)
106
- ? loaded
107
- : Reflect.get(Object(loaded), "default");
174
+ // The namespace itself may be the manager (a test double); a throw there is
175
+ // the mock refusing an export it lacks, not an answer.
176
+ const direct = memberValue(readMember(loaded, "connection"));
177
+ const manager =
178
+ typeof direct === "function"
179
+ ? loaded
180
+ : memberValue(readMember(Object(loaded), "default"));
181
+ const read = readMember(manager, "connection");
182
+ if ("threw" in read) {
183
+ throw raise(
184
+ "quasar-missing",
185
+ `[${pkg}] ${what} asks for the quasar connection "${name ?? "default"}", but @c9up/quasar's manager is not available yet: ` +
186
+ "its provider has not booted, or is not registered in this application's providers.",
187
+ read.threw,
188
+ );
189
+ }
108
190
  if (!isConnectionSource(manager)) {
109
191
  throw raise(
110
192
  "quasar-missing",
@@ -113,17 +195,18 @@ export async function quasarConnection<T>(
113
195
  }
114
196
 
115
197
  const connection = manager.connection(name);
116
- const missing = required.filter(
117
- (command) => typeof readMember(connection, command) !== "function",
118
- );
198
+ const missing = missingCommands(connection, required);
119
199
  if (missing.length > 0) {
120
200
  throw raise(
121
201
  "incomplete-connection",
122
202
  `[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is missing ${missing.join(", ")}, which ${what} issues`,
123
203
  );
124
204
  }
125
- // Load-bearing: every member of `required` has just been checked to be a
126
- // function on this object. The caller names the type it needs because only
127
- // the caller knows which commands it asked for.
128
- return connection as T;
205
+ if (!isConnection(connection)) {
206
+ throw raise(
207
+ "incomplete-connection",
208
+ `[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is not the client ${what} needs`,
209
+ );
210
+ }
211
+ return connection;
129
212
  }