@pixotope/event-bus 0.4.0 → 0.6.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @pixotope/event-bus@0.4.0 build /home/circleci/project/packages/event-bus
+> @pixotope/event-bus@0.6.0 build /home/circleci/project/packages/event-bus
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/index.js     1.40 KB
-ESM dist/index.js.map 3.67 KB
-ESM ⚡️ Build success in 198ms
-CJS dist/index.cjs     2.36 KB
-CJS dist/index.cjs.map 3.76 KB
-CJS ⚡️ Build success in 199ms
+ESM dist/index.js     1.59 KB
+ESM dist/index.js.map 4.81 KB
+ESM ⚡️ Build success in 533ms
+CJS dist/index.cjs     2.55 KB
+CJS dist/index.cjs.map 4.91 KB
+CJS ⚡️ Build success in 534ms
 DTS Build start
-DTS ⚡️ Build success in 2192ms
-DTS dist/index.d.cts 1.94 KB
-DTS dist/index.d.ts  1.94 KB
+DTS ⚡️ Build success in 1944ms
+DTS dist/index.d.cts 3.06 KB
+DTS dist/index.d.ts  3.06 KB

package/.turbo/turbo-check-types.log

@@ -1,4 +1,4 @@
 
-> @pixotope/event-bus@0.4.0 check-types /home/circleci/project/packages/event-bus
+> @pixotope/event-bus@0.6.0 check-types /home/circleci/project/packages/event-bus
 > tsc --noEmit
 

package/.turbo/turbo-test.log

@@ -1,14 +1,14 @@
 
-> @pixotope/event-bus@0.4.0 test /home/circleci/project/packages/event-bus
+> @pixotope/event-bus@0.6.0 test /home/circleci/project/packages/event-bus
 > vitest
 
 
  RUN  v3.2.4 /home/circleci/project/packages/event-bus
 
- ✓ src/EventBus.test.ts (8 tests) 99ms
+ ✓ src/EventBus.test.ts (8 tests) 157ms
 
  Test Files  1 passed (1)
       Tests  8 passed (8)
-   Start at  16:16:57
-   Duration  4.18s (transform 712ms, setup 0ms, collect 893ms, tests 99ms, environment 0ms, prepare 1.21s)
+   Start at  13:46:44
+   Duration  4.70s (transform 950ms, setup 0ms, collect 689ms, tests 157ms, environment 0ms, prepare 1.79s)
 

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pixotope/event-bus
 
+## 0.6.0
+
+### Minor Changes
+
+- 8a28444: Include detailed documentation for every package and setup `typedoc`
+
+## 0.5.0
+
+### Minor Changes
+
+- aeed4b1: stronger `on` event-bus types
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,52 @@
+# @pixotope/event-bus
+
+Typed in-memory event bus for Pixotope Foundation.
+
+## Install
+
+```sh
+pnpm add @pixotope/event-bus
+```
+
+## Quick start
+
+```ts
+import { EventBus } from "@pixotope/event-bus";
+
+// Define the events this bus can carry and their payload types.
+type Events = {
+  test: { payload: string };
+  test2: { payload: number };
+};
+
+const bus = new EventBus<Events>();
+
+// Subscribe. `on` returns an unsubscribe function.
+const off = bus.on("test", ({ payload }) => {
+  console.log("got test:", payload);
+});
+
+// Emit an event to all matching handlers.
+bus.emit("test", { payload: "hello" });
+
+// Unsubscribe either by calling the returned function...
+off();
+
+// ...or by calling `off` with the same type and handler reference.
+const handler = ({ payload }: { payload: number }) => console.log(payload);
+bus.on("test2", handler);
+bus.off("test2", handler);
+
+// Remove every handler on the bus.
+bus.dispose();
+```
+
+## API overview
+
+- `EventBus<Events>` - typed, mitt-like, in-memory pub/sub event bus.
+  - `on(type, handler)` - subscribe to an event type (or `"*"` for every event); returns a function that unsubscribes.
+  - `off(type, handler)` - unsubscribe a specific handler from an event type.
+  - `emit(type, event?)` - emit an event, invoking every matching handler and any wildcard handlers.
+  - `dispose()` - remove all registered handlers.
+
+See the generated API reference (`pnpm typedoc`) for full type signatures.

package/dist/index.cjs

@@ -28,7 +28,12 @@ module.exports = __toCommonJS(index_exports);
 
 // src/EventBus.ts
 var EventBus = class {
+  /**
+   * Create a new event bus.
+   * @param all - An optional existing handler map to use instead of a new, empty one.
+   */
   constructor(all) {
+    /** The underlying map of event type to registered handlers. */
     __publicField(this, "all", /* @__PURE__ */ new Map());
     this.all = all || /* @__PURE__ */ new Map();
   }

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/EventBus.ts"],"sourcesContent":["export * from \"./EventBus\";\n","export type EventType = string | symbol;\n\nexport type EmitArgs<\n  Events extends Record<EventType, unknown>,\n  Key extends keyof Events,\n> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];\n\nexport type Handler<T = unknown> = (event: T) => void;\nexport type WildcardHandler<T = Record<string, unknown>> = (\n  type: keyof T,\n  event: T[keyof T]\n) => void;\n\nexport type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<\n  keyof Events | \"*\",\n  Set<GenericEventHandler<Events>>\n>;\n\nexport type GenericEventHandler<Events extends Record<EventType, unknown>> =\n  | Handler<Events[keyof Events]>\n  | WildcardHandler<Events>;\n\ntype IsLooseEvents<Events extends Record<EventType, unknown>> =\n  string extends keyof Events ? true : false;\n\nexport class EventBus<\n  Events extends Record<EventType, unknown> = Record<EventType, unknown>,\n> {\n  public readonly all: EventHandlerMap<Events> = new Map();\n\n  public constructor(all?: EventHandlerMap<Events>) {\n    this.all = all || new Map();\n  }\n\n  /**\n   * Add an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   * @returns A function to remove the event handler\n   */\n  public on(\n    type: keyof Events,\n    handler: Handler<Events[typeof type]>\n  ): () => void;\n  public on(type: \"*\", handler: WildcardHandler<Events>): () => void;\n  public on<T extends string>(\n    type: IsLooseEvents<Events> extends true ? T : never,\n    handler: IsLooseEvents<Events> extends true\n      ? (...args: any[]) => void\n      : never\n  ): () => void;\n  public on(type: keyof Events | \"*\", handler: GenericEventHandler<Events>) {\n    const handlers = this.all.get(type);\n    if (handlers) {\n      handlers.add(handler);\n    } else {\n      this.all.set(type, new Set([handler]));\n    }\n\n    return () => this.off(type, handler);\n  }\n\n  /**\n   * Remove an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   */\n  public off(\n    type: keyof Events | \"*\",\n    handler: (...args: any[]) => any\n  ): boolean {\n    return this.all.get(type)?.delete(handler) ?? false;\n  }\n\n  /**\n   * Emit an event\n   * @param type - The event type\n   * @param args - The event arguments\n   */\n  public emit<Key extends keyof Events>(\n    type: Key,\n    ...args: EmitArgs<Events, Key>\n  ) {\n    const evt = args[0] as Events[Key];\n    let handlers = this.all.get(type);\n    if (handlers) {\n      (handlers as Set<Handler<Events[Key]>>).forEach((h) => h(evt!));\n    }\n\n    handlers = this.all.get(\"*\");\n    if (handlers) {\n      (handlers as Set<WildcardHandler<Events>>).forEach((h) => h(type, evt!));\n    }\n  }\n\n  /**\n   * Clear all event handlers\n   */\n  public dispose() {\n    this.all.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyBO,IAAM,WAAN,MAEL;AAAA,EAGO,YAAY,KAA+B;AAFlD,wBAAgB,OAA+B,oBAAI,IAAI;AAGrD,SAAK,MAAM,OAAO,oBAAI,IAAI;AAAA,EAC5B;AAAA,EAmBO,GAAG,MAA0B,SAAsC;AACxE,UAAM,WAAW,KAAK,IAAI,IAAI,IAAI;AAClC,QAAI,UAAU;AACZ,eAAS,IAAI,OAAO;AAAA,IACtB,OAAO;AACL,WAAK,IAAI,IAAI,MAAM,oBAAI,IAAI,CAAC,OAAO,CAAC,CAAC;AAAA,IACvC;AAEA,WAAO,MAAM,KAAK,IAAI,MAAM,OAAO;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,IACL,MACA,SACS;AACT,WAAO,KAAK,IAAI,IAAI,IAAI,GAAG,OAAO,OAAO,KAAK;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,KACL,SACG,MACH;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,QAAI,WAAW,KAAK,IAAI,IAAI,IAAI;AAChC,QAAI,UAAU;AACZ,MAAC,SAAuC,QAAQ,CAAC,MAAM,EAAE,GAAI,CAAC;AAAA,IAChE;AAEA,eAAW,KAAK,IAAI,IAAI,GAAG;AAC3B,QAAI,UAAU;AACZ,MAAC,SAA0C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAI,CAAC;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,UAAU;AACf,SAAK,IAAI,MAAM;AAAA,EACjB;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/EventBus.ts"],"sourcesContent":["export * from \"./EventBus\";\n","/** The key used to identify an event: either a string or a symbol. */\nexport type EventType = string | symbol;\n\n/** The arguments accepted by {@link EventBus.emit} for a given event key: optional if the event's payload type allows `undefined`, required otherwise. */\nexport type EmitArgs<\n  Events extends Record<EventType, unknown>,\n  Key extends keyof Events,\n> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];\n\n/** A handler invoked with the payload of a single event type. */\nexport type Handler<T = unknown> = (event: T) => void;\n/** A handler invoked for every emitted event, receiving the event type and its payload. */\nexport type WildcardHandler<T = Record<string, unknown>> = (\n  type: keyof T,\n  event: T[keyof T]\n) => void;\n\n/** A map from event type (or `\"*\"` for wildcard handlers) to the set of handlers registered for it. */\nexport type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<\n  keyof Events | \"*\",\n  Set<GenericEventHandler<Events>>\n>;\n\n/** Either a typed event {@link Handler} or a {@link WildcardHandler} for the given event map. */\nexport type GenericEventHandler<Events extends Record<EventType, unknown>> =\n  | Handler<Events[keyof Events]>\n  | WildcardHandler<Events>;\n\n/** Resolves to `true` when `Events` is a loose (string-keyed, not literally typed) event map, enabling {@link EventBus.on}'s untyped overload. */\nexport type IsLooseEvents<Events extends Record<EventType, unknown>> =\n  string extends keyof Events ? true : false;\n\n/**\n * Typed, mitt-like, in-memory pub/sub event bus.\n *\n * @typeParam Events - A map of event type to its payload type. Defaults to\n * an untyped, loose event map when omitted.\n */\nexport class EventBus<\n  Events extends Record<EventType, unknown> = Record<EventType, unknown>,\n> {\n  /** The underlying map of event type to registered handlers. */\n  public readonly all: EventHandlerMap<Events> = new Map();\n\n  /**\n   * Create a new event bus.\n   * @param all - An optional existing handler map to use instead of a new, empty one.\n   */\n  public constructor(all?: EventHandlerMap<Events>) {\n    this.all = all || new Map();\n  }\n\n  /**\n   * Add an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   * @returns A function to remove the event handler\n   */\n  public on<Key extends keyof Events>(\n    type: Key,\n    handler: Handler<Events[Key]>\n  ): () => void;\n  public on(type: \"*\", handler: WildcardHandler<Events>): () => void;\n  public on<T extends string>(\n    type: IsLooseEvents<Events> extends true ? T : never,\n    handler: IsLooseEvents<Events> extends true\n      ? (...args: any[]) => void\n      : never\n  ): () => void;\n  public on(type: keyof Events | \"*\", handler: GenericEventHandler<Events>) {\n    const handlers = this.all.get(type);\n    if (handlers) {\n      handlers.add(handler);\n    } else {\n      this.all.set(type, new Set([handler]));\n    }\n\n    return () => this.off(type, handler);\n  }\n\n  /**\n   * Remove an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   */\n  public off(\n    type: keyof Events | \"*\",\n    handler: (...args: any[]) => any\n  ): boolean {\n    return this.all.get(type)?.delete(handler) ?? false;\n  }\n\n  /**\n   * Emit an event\n   * @param type - The event type\n   * @param args - The event arguments\n   */\n  public emit<Key extends keyof Events>(\n    type: Key,\n    ...args: EmitArgs<Events, Key>\n  ) {\n    const evt = args[0] as Events[Key];\n    let handlers = this.all.get(type);\n    if (handlers) {\n      (handlers as Set<Handler<Events[Key]>>).forEach((h) => h(evt!));\n    }\n\n    handlers = this.all.get(\"*\");\n    if (handlers) {\n      (handlers as Set<WildcardHandler<Events>>).forEach((h) => h(type, evt!));\n    }\n  }\n\n  /**\n   * Clear all event handlers\n   */\n  public dispose() {\n    this.all.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACsCO,IAAM,WAAN,MAEL;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,YAAY,KAA+B;AANlD;AAAA,wBAAgB,OAA+B,oBAAI,IAAI;AAOrD,SAAK,MAAM,OAAO,oBAAI,IAAI;AAAA,EAC5B;AAAA,EAmBO,GAAG,MAA0B,SAAsC;AACxE,UAAM,WAAW,KAAK,IAAI,IAAI,IAAI;AAClC,QAAI,UAAU;AACZ,eAAS,IAAI,OAAO;AAAA,IACtB,OAAO;AACL,WAAK,IAAI,IAAI,MAAM,oBAAI,IAAI,CAAC,OAAO,CAAC,CAAC;AAAA,IACvC;AAEA,WAAO,MAAM,KAAK,IAAI,MAAM,OAAO;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,IACL,MACA,SACS;AACT,WAAO,KAAK,IAAI,IAAI,IAAI,GAAG,OAAO,OAAO,KAAK;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,KACL,SACG,MACH;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,QAAI,WAAW,KAAK,IAAI,IAAI,IAAI;AAChC,QAAI,UAAU;AACZ,MAAC,SAAuC,QAAQ,CAAC,MAAM,EAAE,GAAI,CAAC;AAAA,IAChE;AAEA,eAAW,KAAK,IAAI,IAAI,GAAG;AAC3B,QAAI,UAAU;AACZ,MAAC,SAA0C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAI,CAAC;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,UAAU;AACf,SAAK,IAAI,MAAM;AAAA,EACjB;AACF;","names":[]}

package/dist/index.d.cts

@@ -1,12 +1,30 @@
+/** The key used to identify an event: either a string or a symbol. */
 type EventType = string | symbol;
+/** The arguments accepted by {@link EventBus.emit} for a given event key: optional if the event's payload type allows `undefined`, required otherwise. */
 type EmitArgs<Events extends Record<EventType, unknown>, Key extends keyof Events> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];
+/** A handler invoked with the payload of a single event type. */
 type Handler<T = unknown> = (event: T) => void;
+/** A handler invoked for every emitted event, receiving the event type and its payload. */
 type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
+/** A map from event type (or `"*"` for wildcard handlers) to the set of handlers registered for it. */
 type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | "*", Set<GenericEventHandler<Events>>>;
+/** Either a typed event {@link Handler} or a {@link WildcardHandler} for the given event map. */
 type GenericEventHandler<Events extends Record<EventType, unknown>> = Handler<Events[keyof Events]> | WildcardHandler<Events>;
+/** Resolves to `true` when `Events` is a loose (string-keyed, not literally typed) event map, enabling {@link EventBus.on}'s untyped overload. */
 type IsLooseEvents<Events extends Record<EventType, unknown>> = string extends keyof Events ? true : false;
+/**
+ * Typed, mitt-like, in-memory pub/sub event bus.
+ *
+ * @typeParam Events - A map of event type to its payload type. Defaults to
+ * an untyped, loose event map when omitted.
+ */
 declare class EventBus<Events extends Record<EventType, unknown> = Record<EventType, unknown>> {
+    /** The underlying map of event type to registered handlers. */
     readonly all: EventHandlerMap<Events>;
+    /**
+     * Create a new event bus.
+     * @param all - An optional existing handler map to use instead of a new, empty one.
+     */
     constructor(all?: EventHandlerMap<Events>);
     /**
      * Add an event handler
@@ -14,7 +32,7 @@ declare class EventBus<Events extends Record<EventType, unknown> = Record<EventT
      * @param handler - The event handler
      * @returns A function to remove the event handler
      */
-    on(type: keyof Events, handler: Handler<Events[typeof type]>): () => void;
+    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): () => void;
     on(type: "*", handler: WildcardHandler<Events>): () => void;
     on<T extends string>(type: IsLooseEvents<Events> extends true ? T : never, handler: IsLooseEvents<Events> extends true ? (...args: any[]) => void : never): () => void;
     /**
@@ -35,4 +53,4 @@ declare class EventBus<Events extends Record<EventType, unknown> = Record<EventT
     dispose(): void;
 }
 
-export { type EmitArgs, EventBus, type EventHandlerMap, type EventType, type GenericEventHandler, type Handler, type WildcardHandler };
+export { type EmitArgs, EventBus, type EventHandlerMap, type EventType, type GenericEventHandler, type Handler, type IsLooseEvents, type WildcardHandler };

package/dist/index.d.ts

@@ -1,12 +1,30 @@
+/** The key used to identify an event: either a string or a symbol. */
 type EventType = string | symbol;
+/** The arguments accepted by {@link EventBus.emit} for a given event key: optional if the event's payload type allows `undefined`, required otherwise. */
 type EmitArgs<Events extends Record<EventType, unknown>, Key extends keyof Events> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];
+/** A handler invoked with the payload of a single event type. */
 type Handler<T = unknown> = (event: T) => void;
+/** A handler invoked for every emitted event, receiving the event type and its payload. */
 type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
+/** A map from event type (or `"*"` for wildcard handlers) to the set of handlers registered for it. */
 type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | "*", Set<GenericEventHandler<Events>>>;
+/** Either a typed event {@link Handler} or a {@link WildcardHandler} for the given event map. */
 type GenericEventHandler<Events extends Record<EventType, unknown>> = Handler<Events[keyof Events]> | WildcardHandler<Events>;
+/** Resolves to `true` when `Events` is a loose (string-keyed, not literally typed) event map, enabling {@link EventBus.on}'s untyped overload. */
 type IsLooseEvents<Events extends Record<EventType, unknown>> = string extends keyof Events ? true : false;
+/**
+ * Typed, mitt-like, in-memory pub/sub event bus.
+ *
+ * @typeParam Events - A map of event type to its payload type. Defaults to
+ * an untyped, loose event map when omitted.
+ */
 declare class EventBus<Events extends Record<EventType, unknown> = Record<EventType, unknown>> {
+    /** The underlying map of event type to registered handlers. */
     readonly all: EventHandlerMap<Events>;
+    /**
+     * Create a new event bus.
+     * @param all - An optional existing handler map to use instead of a new, empty one.
+     */
     constructor(all?: EventHandlerMap<Events>);
     /**
      * Add an event handler
@@ -14,7 +32,7 @@ declare class EventBus<Events extends Record<EventType, unknown> = Record<EventT
      * @param handler - The event handler
      * @returns A function to remove the event handler
      */
-    on(type: keyof Events, handler: Handler<Events[typeof type]>): () => void;
+    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): () => void;
     on(type: "*", handler: WildcardHandler<Events>): () => void;
     on<T extends string>(type: IsLooseEvents<Events> extends true ? T : never, handler: IsLooseEvents<Events> extends true ? (...args: any[]) => void : never): () => void;
     /**
@@ -35,4 +53,4 @@ declare class EventBus<Events extends Record<EventType, unknown> = Record<EventT
     dispose(): void;
 }
 
-export { type EmitArgs, EventBus, type EventHandlerMap, type EventType, type GenericEventHandler, type Handler, type WildcardHandler };
+export { type EmitArgs, EventBus, type EventHandlerMap, type EventType, type GenericEventHandler, type Handler, type IsLooseEvents, type WildcardHandler };

package/dist/index.js

@@ -4,7 +4,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 
 // src/EventBus.ts
 var EventBus = class {
+  /**
+   * Create a new event bus.
+   * @param all - An optional existing handler map to use instead of a new, empty one.
+   */
   constructor(all) {
+    /** The underlying map of event type to registered handlers. */
     __publicField(this, "all", /* @__PURE__ */ new Map());
     this.all = all || /* @__PURE__ */ new Map();
   }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/EventBus.ts"],"sourcesContent":["export type EventType = string | symbol;\n\nexport type EmitArgs<\n  Events extends Record<EventType, unknown>,\n  Key extends keyof Events,\n> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];\n\nexport type Handler<T = unknown> = (event: T) => void;\nexport type WildcardHandler<T = Record<string, unknown>> = (\n  type: keyof T,\n  event: T[keyof T]\n) => void;\n\nexport type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<\n  keyof Events | \"*\",\n  Set<GenericEventHandler<Events>>\n>;\n\nexport type GenericEventHandler<Events extends Record<EventType, unknown>> =\n  | Handler<Events[keyof Events]>\n  | WildcardHandler<Events>;\n\ntype IsLooseEvents<Events extends Record<EventType, unknown>> =\n  string extends keyof Events ? true : false;\n\nexport class EventBus<\n  Events extends Record<EventType, unknown> = Record<EventType, unknown>,\n> {\n  public readonly all: EventHandlerMap<Events> = new Map();\n\n  public constructor(all?: EventHandlerMap<Events>) {\n    this.all = all || new Map();\n  }\n\n  /**\n   * Add an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   * @returns A function to remove the event handler\n   */\n  public on(\n    type: keyof Events,\n    handler: Handler<Events[typeof type]>\n  ): () => void;\n  public on(type: \"*\", handler: WildcardHandler<Events>): () => void;\n  public on<T extends string>(\n    type: IsLooseEvents<Events> extends true ? T : never,\n    handler: IsLooseEvents<Events> extends true\n      ? (...args: any[]) => void\n      : never\n  ): () => void;\n  public on(type: keyof Events | \"*\", handler: GenericEventHandler<Events>) {\n    const handlers = this.all.get(type);\n    if (handlers) {\n      handlers.add(handler);\n    } else {\n      this.all.set(type, new Set([handler]));\n    }\n\n    return () => this.off(type, handler);\n  }\n\n  /**\n   * Remove an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   */\n  public off(\n    type: keyof Events | \"*\",\n    handler: (...args: any[]) => any\n  ): boolean {\n    return this.all.get(type)?.delete(handler) ?? false;\n  }\n\n  /**\n   * Emit an event\n   * @param type - The event type\n   * @param args - The event arguments\n   */\n  public emit<Key extends keyof Events>(\n    type: Key,\n    ...args: EmitArgs<Events, Key>\n  ) {\n    const evt = args[0] as Events[Key];\n    let handlers = this.all.get(type);\n    if (handlers) {\n      (handlers as Set<Handler<Events[Key]>>).forEach((h) => h(evt!));\n    }\n\n    handlers = this.all.get(\"*\");\n    if (handlers) {\n      (handlers as Set<WildcardHandler<Events>>).forEach((h) => h(type, evt!));\n    }\n  }\n\n  /**\n   * Clear all event handlers\n   */\n  public dispose() {\n    this.all.clear();\n  }\n}\n"],"mappings":";;;;;AAyBO,IAAM,WAAN,MAEL;AAAA,EAGO,YAAY,KAA+B;AAFlD,wBAAgB,OAA+B,oBAAI,IAAI;AAGrD,SAAK,MAAM,OAAO,oBAAI,IAAI;AAAA,EAC5B;AAAA,EAmBO,GAAG,MAA0B,SAAsC;AACxE,UAAM,WAAW,KAAK,IAAI,IAAI,IAAI;AAClC,QAAI,UAAU;AACZ,eAAS,IAAI,OAAO;AAAA,IACtB,OAAO;AACL,WAAK,IAAI,IAAI,MAAM,oBAAI,IAAI,CAAC,OAAO,CAAC,CAAC;AAAA,IACvC;AAEA,WAAO,MAAM,KAAK,IAAI,MAAM,OAAO;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,IACL,MACA,SACS;AACT,WAAO,KAAK,IAAI,IAAI,IAAI,GAAG,OAAO,OAAO,KAAK;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,KACL,SACG,MACH;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,QAAI,WAAW,KAAK,IAAI,IAAI,IAAI;AAChC,QAAI,UAAU;AACZ,MAAC,SAAuC,QAAQ,CAAC,MAAM,EAAE,GAAI,CAAC;AAAA,IAChE;AAEA,eAAW,KAAK,IAAI,IAAI,GAAG;AAC3B,QAAI,UAAU;AACZ,MAAC,SAA0C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAI,CAAC;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,UAAU;AACf,SAAK,IAAI,MAAM;AAAA,EACjB;AACF;","names":[]}
+{"version":3,"sources":["../src/EventBus.ts"],"sourcesContent":["/** The key used to identify an event: either a string or a symbol. */\nexport type EventType = string | symbol;\n\n/** The arguments accepted by {@link EventBus.emit} for a given event key: optional if the event's payload type allows `undefined`, required otherwise. */\nexport type EmitArgs<\n  Events extends Record<EventType, unknown>,\n  Key extends keyof Events,\n> = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];\n\n/** A handler invoked with the payload of a single event type. */\nexport type Handler<T = unknown> = (event: T) => void;\n/** A handler invoked for every emitted event, receiving the event type and its payload. */\nexport type WildcardHandler<T = Record<string, unknown>> = (\n  type: keyof T,\n  event: T[keyof T]\n) => void;\n\n/** A map from event type (or `\"*\"` for wildcard handlers) to the set of handlers registered for it. */\nexport type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<\n  keyof Events | \"*\",\n  Set<GenericEventHandler<Events>>\n>;\n\n/** Either a typed event {@link Handler} or a {@link WildcardHandler} for the given event map. */\nexport type GenericEventHandler<Events extends Record<EventType, unknown>> =\n  | Handler<Events[keyof Events]>\n  | WildcardHandler<Events>;\n\n/** Resolves to `true` when `Events` is a loose (string-keyed, not literally typed) event map, enabling {@link EventBus.on}'s untyped overload. */\nexport type IsLooseEvents<Events extends Record<EventType, unknown>> =\n  string extends keyof Events ? true : false;\n\n/**\n * Typed, mitt-like, in-memory pub/sub event bus.\n *\n * @typeParam Events - A map of event type to its payload type. Defaults to\n * an untyped, loose event map when omitted.\n */\nexport class EventBus<\n  Events extends Record<EventType, unknown> = Record<EventType, unknown>,\n> {\n  /** The underlying map of event type to registered handlers. */\n  public readonly all: EventHandlerMap<Events> = new Map();\n\n  /**\n   * Create a new event bus.\n   * @param all - An optional existing handler map to use instead of a new, empty one.\n   */\n  public constructor(all?: EventHandlerMap<Events>) {\n    this.all = all || new Map();\n  }\n\n  /**\n   * Add an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   * @returns A function to remove the event handler\n   */\n  public on<Key extends keyof Events>(\n    type: Key,\n    handler: Handler<Events[Key]>\n  ): () => void;\n  public on(type: \"*\", handler: WildcardHandler<Events>): () => void;\n  public on<T extends string>(\n    type: IsLooseEvents<Events> extends true ? T : never,\n    handler: IsLooseEvents<Events> extends true\n      ? (...args: any[]) => void\n      : never\n  ): () => void;\n  public on(type: keyof Events | \"*\", handler: GenericEventHandler<Events>) {\n    const handlers = this.all.get(type);\n    if (handlers) {\n      handlers.add(handler);\n    } else {\n      this.all.set(type, new Set([handler]));\n    }\n\n    return () => this.off(type, handler);\n  }\n\n  /**\n   * Remove an event handler\n   * @param type - The event type\n   * @param handler - The event handler\n   */\n  public off(\n    type: keyof Events | \"*\",\n    handler: (...args: any[]) => any\n  ): boolean {\n    return this.all.get(type)?.delete(handler) ?? false;\n  }\n\n  /**\n   * Emit an event\n   * @param type - The event type\n   * @param args - The event arguments\n   */\n  public emit<Key extends keyof Events>(\n    type: Key,\n    ...args: EmitArgs<Events, Key>\n  ) {\n    const evt = args[0] as Events[Key];\n    let handlers = this.all.get(type);\n    if (handlers) {\n      (handlers as Set<Handler<Events[Key]>>).forEach((h) => h(evt!));\n    }\n\n    handlers = this.all.get(\"*\");\n    if (handlers) {\n      (handlers as Set<WildcardHandler<Events>>).forEach((h) => h(type, evt!));\n    }\n  }\n\n  /**\n   * Clear all event handlers\n   */\n  public dispose() {\n    this.all.clear();\n  }\n}\n"],"mappings":";;;;;AAsCO,IAAM,WAAN,MAEL;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,YAAY,KAA+B;AANlD;AAAA,wBAAgB,OAA+B,oBAAI,IAAI;AAOrD,SAAK,MAAM,OAAO,oBAAI,IAAI;AAAA,EAC5B;AAAA,EAmBO,GAAG,MAA0B,SAAsC;AACxE,UAAM,WAAW,KAAK,IAAI,IAAI,IAAI;AAClC,QAAI,UAAU;AACZ,eAAS,IAAI,OAAO;AAAA,IACtB,OAAO;AACL,WAAK,IAAI,IAAI,MAAM,oBAAI,IAAI,CAAC,OAAO,CAAC,CAAC;AAAA,IACvC;AAEA,WAAO,MAAM,KAAK,IAAI,MAAM,OAAO;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,IACL,MACA,SACS;AACT,WAAO,KAAK,IAAI,IAAI,IAAI,GAAG,OAAO,OAAO,KAAK;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,KACL,SACG,MACH;AACA,UAAM,MAAM,KAAK,CAAC;AAClB,QAAI,WAAW,KAAK,IAAI,IAAI,IAAI;AAChC,QAAI,UAAU;AACZ,MAAC,SAAuC,QAAQ,CAAC,MAAM,EAAE,GAAI,CAAC;AAAA,IAChE;AAEA,eAAW,KAAK,IAAI,IAAI,GAAG;AAC3B,QAAI,UAAU;AACZ,MAAC,SAA0C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAI,CAAC;AAAA,IACzE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,UAAU;AACf,SAAK,IAAI,MAAM;AAAA,EACjB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixotope/event-bus",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Typed in-memory event bus for Pixotope Foundation",
   "private": false,
   "type": "module",

package/src/EventBus.ts

@@ -1,33 +1,51 @@
+/** The key used to identify an event: either a string or a symbol. */
 export type EventType = string | symbol;
 
+/** The arguments accepted by {@link EventBus.emit} for a given event key: optional if the event's payload type allows `undefined`, required otherwise. */
 export type EmitArgs<
   Events extends Record<EventType, unknown>,
   Key extends keyof Events,
 > = undefined extends Events[Key] ? [evt?: Events[Key]] : [evt: Events[Key]];
 
+/** A handler invoked with the payload of a single event type. */
 export type Handler<T = unknown> = (event: T) => void;
+/** A handler invoked for every emitted event, receiving the event type and its payload. */
 export type WildcardHandler<T = Record<string, unknown>> = (
   type: keyof T,
   event: T[keyof T]
 ) => void;
 
+/** A map from event type (or `"*"` for wildcard handlers) to the set of handlers registered for it. */
 export type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<
   keyof Events | "*",
   Set<GenericEventHandler<Events>>
 >;
 
+/** Either a typed event {@link Handler} or a {@link WildcardHandler} for the given event map. */
 export type GenericEventHandler<Events extends Record<EventType, unknown>> =
   | Handler<Events[keyof Events]>
   | WildcardHandler<Events>;
 
-type IsLooseEvents<Events extends Record<EventType, unknown>> =
+/** Resolves to `true` when `Events` is a loose (string-keyed, not literally typed) event map, enabling {@link EventBus.on}'s untyped overload. */
+export type IsLooseEvents<Events extends Record<EventType, unknown>> =
   string extends keyof Events ? true : false;
 
+/**
+ * Typed, mitt-like, in-memory pub/sub event bus.
+ *
+ * @typeParam Events - A map of event type to its payload type. Defaults to
+ * an untyped, loose event map when omitted.
+ */
 export class EventBus<
   Events extends Record<EventType, unknown> = Record<EventType, unknown>,
 > {
+  /** The underlying map of event type to registered handlers. */
   public readonly all: EventHandlerMap<Events> = new Map();
 
+  /**
+   * Create a new event bus.
+   * @param all - An optional existing handler map to use instead of a new, empty one.
+   */
   public constructor(all?: EventHandlerMap<Events>) {
     this.all = all || new Map();
   }
@@ -38,9 +56,9 @@ export class EventBus<
    * @param handler - The event handler
    * @returns A function to remove the event handler
    */
-  public on(
-    type: keyof Events,
-    handler: Handler<Events[typeof type]>
+  public on<Key extends keyof Events>(
+    type: Key,
+    handler: Handler<Events[Key]>
   ): () => void;
   public on(type: "*", handler: WildcardHandler<Events>): () => void;
   public on<T extends string>(

package/typedoc.json

@@ -0,0 +1,3 @@
+{
+  "entryPoints": ["src/index.ts"]
+}