@tooee/overlays 0.2.4 → 0.3.1

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.
@@ -4,46 +4,98 @@
4
4
  * `tsc -b` (which only checks `src/`) fails if the store's typing is ever
5
5
  * loosened.
6
6
  *
7
- * The store's event/emitted payload maps (`OverlayStoreEvents`, the emitted
8
- * map inside `overlay-store.ts`) are deliberately CLOSED — no index
9
- * signatures. That makes unknown `store.trigger.*`, `store.send`,
10
- * `store.on(...)`, and `enqueue.emit.*` event names compile errors. If one of
11
- * the `@ts-expect-error` lines below starts compiling, the maps have been
12
- * widened (e.g. an index signature was added); fix the maps, not this file.
7
+ * The store's event/emitted payload maps (`OverlayStoreEvents`, the emitted map
8
+ * inside `overlay-store.ts`) are deliberately CLOSED — no index signatures. That
9
+ * makes unknown `store.trigger.*`, `store.send`, `store.on(...)`, and
10
+ * `enqueue.emit.*` event names compile errors.
11
+ *
12
+ * Unknown names are pinned as TYPE-LEVEL assertions rather than
13
+ * `@ts-expect-error`-ed calls: writing `store.trigger.bogusEvent({})` is an
14
+ * unsafe call on an error-typed value, which is exactly what the lint gate
15
+ * should reject. Asserting on the key sets proves the same property without
16
+ * invalid executable syntax. If one of the `Assert<...>` lines below stops
17
+ * compiling, the maps have been widened (e.g. an index signature was added);
18
+ * fix the maps, not this file.
13
19
  */
14
- import type { OverlayCloseReason } from "./overlay-context.js"
15
- import { createOverlayStore, type OverlayRecord } from "./overlay-store.js"
20
+ import type { OverlayCloseReason } from "./overlay-context.js";
21
+ import { overlayValue } from "./overlay-context.js";
22
+ import { createOverlayStore } from "./overlay-store.js";
23
+ import type { OverlayRecord, OverlayStore } from "./overlay-store.js";
24
+
25
+ declare const record: OverlayRecord;
26
+ declare const reason: OverlayCloseReason;
27
+
28
+ // --- Type-level assertion helpers -------------------------------------------
29
+
30
+ type Assert<T extends true> = T;
31
+ type IsNever<T> = [T] extends [never] ? true : false;
32
+ type Has<TKeys, TName> = [Extract<TKeys, TName>] extends [never] ? false : true;
33
+
34
+ type TriggerNames = keyof OverlayStore["trigger"];
35
+ type SendNames = Parameters<OverlayStore["send"]>[0]["type"];
36
+ type EmittedNames = Parameters<OverlayStore["on"]>[0];
37
+
38
+ // --- Known event names must be present --------------------------------------
39
+
40
+ type KnownTriggers = Assert<Has<TriggerNames, "opened" | "updated" | "closed" | "closedTop">>;
41
+ type KnownSends = Assert<Has<SendNames, "opened" | "updated" | "closed" | "closedTop">>;
42
+ type KnownEmits = Assert<Has<EmittedNames, "closed">>;
43
+
44
+ // --- Unknown event names must NOT exist in the maps --------------------------
45
+
46
+ type UnknownTriggerRejected = Assert<IsNever<Extract<TriggerNames, "bogusEvent">>>;
47
+ type UnknownSendRejected = Assert<IsNever<Extract<SendNames, "bogusEvent">>>;
48
+ type UnknownEmitRejected = Assert<IsNever<Extract<EmittedNames, "bogusEmit">>>;
16
49
 
17
- declare const record: OverlayRecord
18
- declare const reason: OverlayCloseReason
50
+ export type OverlayStoreEventNameChecks = [
51
+ KnownTriggers,
52
+ KnownSends,
53
+ KnownEmits,
54
+ UnknownTriggerRejected,
55
+ UnknownSendRejected,
56
+ UnknownEmitRejected,
57
+ ];
19
58
 
20
59
  // Never called; exists only to be typechecked.
21
- export function overlayStoreTypeChecks(): void {
22
- const store = createOverlayStore()
60
+ export const overlayStoreTypeChecks = function overlayStoreTypeChecks(): void {
61
+ const store = createOverlayStore();
23
62
 
24
63
  // --- Valid usage must compile -------------------------------------------
25
- store.trigger.opened({ record })
26
- store.trigger.updated({ id: "x", next: null })
27
- store.trigger.closed({ id: "x", reason })
28
- store.trigger.closedTop({ reason })
29
- store.send({ type: "closedTop", reason })
64
+ store.trigger.opened({ record });
65
+ // The store's payloads are erased to `unknown`, and `OverlayUpdate<T>` is
66
+ // invariant in T (the updater arm consumes T), so direct store callers erase
67
+ // explicitly. Typed callers go through the shell adapter.
68
+ store.trigger.updated({ id: "x", next: overlayValue<unknown>(null) });
69
+ store.trigger.closed({ id: "x", reason });
70
+ store.trigger.closedTop({ reason });
71
+ store.send({ reason, type: "closedTop" });
30
72
  store.on("closed", (emitted) => {
31
- const _reason: OverlayCloseReason = emitted.reason
32
- const _restoreModeTo: string | null = emitted.restoreModeTo
33
- const _record: OverlayRecord = emitted.record
34
- })
73
+ const {
74
+ reason: closeReason,
75
+ restoreModeTo,
76
+ record: closedRecord,
77
+ }: {
78
+ reason: OverlayCloseReason;
79
+ restoreModeTo: string | null;
80
+ record: OverlayRecord;
81
+ } = emitted;
82
+ void closeReason;
83
+ void restoreModeTo;
84
+ void closedRecord;
85
+ });
35
86
 
36
87
  // --- Unknown event names must NOT compile --------------------------------
37
- // @ts-expect-error unknown trigger event name
38
- store.trigger.bogusEvent({})
88
+ // (trigger names are covered by the type-level assertions above)
39
89
  // @ts-expect-error unknown send event type
40
- store.send({ type: "bogusEvent" })
90
+ store.send({ type: "bogusEvent" });
41
91
  // @ts-expect-error unknown emitted event name
42
- store.on("bogusEmit", () => {})
92
+ store.on("bogusEmit", () => void 0);
43
93
 
44
94
  // --- Wrong payloads must NOT compile --------------------------------------
45
95
  // @ts-expect-error reason must be an OverlayCloseReason
46
- store.trigger.closedTop({ reason: 42 })
96
+ store.trigger.closedTop({ reason: 42 });
47
97
  // @ts-expect-error record is required
48
- store.trigger.opened({})
49
- }
98
+ store.trigger.opened({});
99
+ // @ts-expect-error a bare value is not an OverlayUpdate (value/updater must be explicit)
100
+ store.trigger.updated({ id: "x", next: "raw-payload" });
101
+ };