feat: Add static typing for eventbus (#586)

Author: patricklafrance

.changeset/eager-numbers-dress.md

@@ -0,0 +1,7 @@
+---
+"@squide/firefly-module-federation": major
+"@squide/firefly": major
+"@squide/core": major
+---
+
+Added typed EventBus through module augmentation of EventMap.

agent-docs/design/cross-module-communication.md

@@ -7,16 +7,25 @@ coordination happens through the FireflyRuntime API.
 
 ## Event Bus
 
-Pub/sub messaging for decoupled communication between modules:
+Pub/sub messaging for decoupled communication between modules. Events are type-safe via module augmentation of the `EventMap` interface (same pattern as `EnvironmentVariables` and `FeatureFlags`). All Squide native events are pre-augmented; consumer apps add their own events:
+
+```ts
+// types/event-map.d.ts — consumer augmentation
+declare module "@squide/firefly" {
+    interface EventMap {
+        "tenant-changed": { tenantId: string };
+    }
+}
+```
 
 ```tsx
-// Dispatch an event
+// Dispatch — payload type inferred from EventMap
 const dispatch = useEventBusDispatcher();
-dispatch("event-name", payload);
+dispatch("tenant-changed", { tenantId: "abc" });
 
-// Listen for an event
-const handler = useCallback((data, context) => { /* ... */ }, []);
-useEventBusListener("event-name", handler, { once: true });
+// Listen — handler payload type inferred from EventMap
+const handler = useCallback(data => { /* ... */ }, []);
+useEventBusListener("tenant-changed", handler, { once: true });
 ```
 
 ## Plugins

agent-skills/workleap-squide/SKILL.md

@@ -11,7 +11,7 @@ description: |
   (7) Squide hooks for event bus, environment variables, feature flags, logging, or bootstrapping state
   (8) Error boundaries or modular architecture in Squide applications
 metadata:
-  version: 1.9
+  version: 1.10
 ---
 
 # Squide Framework

agent-skills/workleap-squide/references/hooks-api.md

@@ -222,34 +222,51 @@ useDeferredRegistrations(undefined, {
 
 ## Messaging Hooks
 
+The event bus is type-safe via module augmentation of the `EventMap` interface (same pattern as `EnvironmentVariables` and `FeatureFlags`). Events must be declared in `EventMap` before they can be dispatched or listened to.
+
+### TypeScript Augmentation (EventMap Interface)
+
+```ts
+// types/event-map.d.ts
+import "@squide/firefly";
+
+declare module "@squide/firefly" {
+    interface EventMap {
+        "tenant-changed": { tenantId: string };
+        "theme-updated": { mode: "light" | "dark" };
+    }
+}
+```
+
+All Squide native events (bootstrapping lifecycle, data fetching, AppRouter state) are pre-augmented and already type-safe.
+
 ### useEventBusListener(eventName, handler, options?)
-Listen to events from the event bus.
+Listen to events from the event bus. The handler payload type is inferred from `EventMap`.
 
 ```ts
 import { useEventBusListener } from "@squide/firefly";
 import { useCallback } from "react";
 
-const handleEvent = useCallback((data, context) => {
-    console.log("Event received:", data);
+// Payload inferred as { tenantId: string }
+const handleTenantChanged = useCallback(data => {
+    console.log("Tenant:", data?.tenantId);
 }, []);
-
-// Listen to all events
-useEventBusListener("user-updated", handleEvent);
+useEventBusListener("tenant-changed", handleTenantChanged);
 
 // Listen once
-useEventBusListener("init-complete", handleEvent, { once: true });
+useEventBusListener("tenant-changed", handleTenantChanged, { once: true });
 ```
 
 ### useEventBusDispatcher()
-Get a function to dispatch events.
+Get a function to dispatch events. The payload type is enforced by `EventMap`.
 
 ```ts
 import { useEventBusDispatcher } from "@squide/firefly";
 
 const dispatch = useEventBusDispatcher();
 
-// Dispatch event with payload
-dispatch("user-updated", { id: 123, name: "John" });
+// Payload must match EventMap["tenant-changed"]
+dispatch("tenant-changed", { tenantId: "abc" });
 ```
 
 ## Environment & Configuration Hooks

docs/essentials/use-event-bus.md

@@ -17,12 +17,12 @@ Register a function that will be invoked each time the specified event is dispat
 import { useCallback } from "react";
 import { useEventBusListener } from "@squide/firefly";
 
-const handleFoo = useCallback((data, context) => {
+const handleShowToast = useCallback(data => {
     // Do something...
 }, []);
 
-// Listen to every "foo" events.
-useEventBusListener("foo", handleFoo);
+// Listen to every "show-toast" events.
+useEventBusListener("show-toast", handleShowToast);
 ```
 
 ## Add an event listener that will be invoked once
@@ -33,12 +33,12 @@ Register a function that will be invoked once, and then automatically unregister
 import { useCallback } from "react";
 import { useEventBusListener } from "@squide/firefly";
 
-const handleFoo = useCallback((data, context) => {
+const handleShowToast = useCallback(data => {
     // Do something...
 }, []);
 
-// Listen to the first "foo" event.
-useEventBusListener("foo", handleFoo, { once: true };
+// Listen to the first "show-toast" event.
+useEventBusListener("show-toast", handleShowToast, { once: true });
 ```
 
 ## Dispatch an event
@@ -48,8 +48,72 @@ import { useEventBusDispatcher } from "@squide/firefly";
 
 const dispatch = useEventBusDispatcher();
 
-// Dispatch a "foo" event with a "bar" payload.
-dispatch("foo", "bar");
+// Dispatch a "show-toast" event with a string payload.
+dispatch("show-toast", "Hello!");
 ```
 
+## Setup the typings
 
+Before dispatching or listening to events, modules should [augment](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) the [EventMap](../reference/messaging/EventMap.md) interface with the events they intend to use to ensure type safety and autocompletion.
+
+First, create a types folder in the project:
+
+``` !#7-8
+project
+├── src
+├────── register.tsx
+├────── Page.tsx
+├────── index.tsx
+├────── App.tsx
+├── types
+├────── event-map.d.ts
+```
+
+Then create an `event-map.d.ts` file:
+
+```ts !#6 project/types/event-map.d.ts
+import "@squide/firefly";
+
+declare module "@squide/firefly" {
+    interface EventMap {
+        // Each entry maps an event name to its payload type.
+        "show-toast": string;
+    }
+}
+```
+
+Finally, update the project `tsconfig.json` to include the `types` folder:
+
+```json !#5-7 project/tsconfig.json
+{
+    "compilerOptions": {
+        "incremental": true,
+        "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json",
+        "types": [
+            "./types/event-map.d.ts"
+        ]
+    },
+    "exclude": ["dist", "node_modules"]
+}
+```
+
+If any other project using those events must also reference the project's `event-map.d.ts` file:
+
+```json !#5-7 project/tsconfig.json
+{
+    "compilerOptions": {
+        "incremental": true,
+        "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json",
+        "types": [
+            "../another-project/types/event-map.d.ts"
+        ]
+    },
+    "exclude": ["dist", "node_modules"]
+}
+```
+
+Once configured, the event bus hooks are fully typed:
+
+:::align-image-left
+![Auto-completion example](../static/event-bus-typings.png){width=735}
+:::

docs/reference/messaging/EventMap.md

@@ -0,0 +1,71 @@
+---
+order: 90
+toc:
+    depth: 2-3
+---
+
+# EventMap
+
+The `EventMap` interface defines the shape and types of the event names and payload values that modules dispatch and listen to through the [FireflyRuntime](../runtime/FireflyRuntime.md) instance event bus.
+
+Consumer applications are expected to [augment](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) this interface to declare the events they intend to use, providing a fully type-safe experience when working with the event bus.
+
+All Squide native events (bootstrapping lifecycle, data fetching, AppRouter state transitions) are pre-augmented and already type-safe. You only need to augment `EventMap` for your own application events.
+
+## Augment the interface
+
+First, create a types folder in the project:
+
+``` !#7-8
+project
+├── src
+├────── register.tsx
+├────── Page.tsx
+├────── index.tsx
+├────── App.tsx
+├── types
+├────── event-map.d.ts
+```
+
+Then create an `event-map.d.ts` file:
+
+```ts !#6 project/types/event-map.d.ts
+import "@squide/firefly";
+
+declare module "@squide/firefly" {
+    interface EventMap {
+        // Each entry maps an event name to its payload type.
+        "show-toast": string;
+    }
+}
+```
+
+Finally, update the project `tsconfig.json` to include the `types` folder:
+
+```json !#5-7 project/tsconfig.json
+{
+    "compilerOptions": {
+        "incremental": true,
+        "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json",
+        "types": [
+            "./types/event-map.d.ts"
+        ]
+    },
+    "exclude": ["dist", "node_modules"]
+}
+```
+
+Any project that uses these events must also reference the project's `event-map.d.ts` file:
+
+```json !#5-7 project/tsconfig.json
+{
+    "compilerOptions": {
+        "incremental": true,
+        "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json",
+        "types": [
+            "../another-project/types/event-map.d.ts"
+        ]
+    },
+    "exclude": ["dist", "node_modules"]
+}
+```

docs/reference/messaging/useEventBusDispatcher.md

@@ -19,7 +19,7 @@ None
 
 ### Returns
 
-A dispatch function: `(eventName: string, payload?: {}) => void`.
+A dispatch function. The event name must be a key augmented in [EventMap](./EventMap.md). The payload type is inferred from the event name.
 
 ## Usage
 
@@ -28,5 +28,5 @@ import { useEventBusDispatcher } from "@squide/firefly";
 
 const dispatch = useEventBusDispatcher();
 
-dispatch("foo", "bar");
+dispatch("show-toast", "Hello!");
 ```

docs/reference/messaging/useEventBusListener.md

@@ -15,28 +15,37 @@ useEventBusListener(eventName, callback: () => {}, options?: { once? })
 
 ### Parameters
 
-- `eventName`: The name of the event to listen for.
-- `callback`: A function to be executed when a event matching the provided name is dispatched.
+- `eventName`: The name of the event to listen for. Must be a key augmented in [EventMap](./EventMap.md).
+- `callback`: A function to be executed when an event matching the provided name is dispatched.
 - `options`: An optional object literal of options:
-    - `once`: Whether or not the event listener should be automatically removed once an event as been handled.
+    - `once`: Whether or not the event listener should be automatically removed once an event has been handled.
 
 ### Returns
 
 Nothing
 
 ## Usage
 
-```ts !#9,12
+```ts !#8
 import { useCallback } from "react";
 import { useEventBusListener } from "@squide/firefly";
 
-const handleFoo = useCallback((data, context) => {
-    // Do something...
+const handleToast = useCallback(data => {
+    console.log("Toast:", data);
 }, []);
 
-// Listen to every "foo" events.
-useEventBusListener("foo", handleFoo);
+useEventBusListener("show-toast", handleToast);
+```
+
+### Listen once
+
+```ts !#8
+import { useCallback } from "react";
+import { useEventBusListener } from "@squide/firefly";
+
+const handleToast = useCallback(data => {
+    console.log("Toast:", data);
+}, []);
 
-// Listen to the first "foo" event, then automatically remove the listener.
-useEventBusListener("foo", handleFoo, { once: true };
+useEventBusListener("show-toast", handleToast, { once: true });
 ```

docs/static/event-bus-typings.png

@@ -15,5 +15,6 @@ order: 50
 - [Migrate from v8 to v15.0](./migrate-from-v8-to-v15.0.md)
 - [Migrate to firefly v16.0](./migrate-to-firefly-v16.0.md)
 - [Migrate to firefly v16.2](./migrate-to-firefly-v16.2.md)
+- [Migrate to firefly v17.0](./migrate-to-firefly-v17.0.md)
 - [Migrate to Rsbuild](./migrate-to-rsbuild.md) [!badge variant="danger" size="xs" text="experimental"]
 - [Migrate to Just-In-Time (JIT) packages](./migrate-to-jit-packages.md)