@servicetitan/web-components 30.0.0 → 30.1.1

package/src/contexts/mfe-data-context.ts

@@ -1,9 +1,9 @@
-/**
- * Context used to pass data from the host to the MFEs
- */
-
 import { createContext, useContext } from 'react';
-import { JSON, JSONPrimitive } from '../types';
+
+type JSONPrimitive = string | number | boolean | null | undefined;
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type JSON = { [key: string]: JSONPrimitive | JSON[] | JSON };
 
 // Type complexity below is required to support Interfaces being used
 export type MFEContextData<T> = {
@@ -16,6 +16,9 @@ export type MFEContextData<T> = {
             : never;
 };
 
+/**
+ * Context used to pass data from the host to the MFEs
+ */
 export const MFEDataContext = createContext<JSON>({});
 
 export function useMFEDataContext<T extends MFEContextData<T>>() {

package/src/event-bus.ts

@@ -1,32 +1,85 @@
+import { symbolToken, SymbolToken } from '@servicetitan/react-ioc';
 import mitt from 'mitt';
 
-import { symbolToken, SymbolToken } from '@servicetitan/react-ioc';
-import { useRef } from 'react';
-import { JSON } from './types';
+import { JSON, Serializable } from './types';
+
+export const EVENT_BUS_TOKEN = symbolToken<EventBus>('EVENT_BUS_TOKEN');
+
+export function typedEventBusToken<EventTypes extends Serializable<EventTypes>>() {
+    return symbolToken<EventBus<EventTypes>>('EVENT_BUS_TOKEN');
+}
+
+export type EventHandler<EventTypes, Event, T = never> = (
+    data: [T] extends [never]
+        ? Event extends SymbolToken<infer DataType>
+            ? Serializable<DataType>
+            : Event extends keyof EventTypes
+              ? EventTypes[Event]
+              : T
+        : Serializable<T>
+) => void;
 
-export type EventHandler<T = unknown> = (data: T) => void;
 type JobPayload = JSON | void;
 
-export type JobEventHandler<Result extends JobPayload = void> = (defer: {
-    resolve(result: Result): void;
-    reject(reason?: string | Error): void;
-}) => void;
 export type EventType = string | number | symbol;
 export type SymbolTokenEventType<T, U extends EventType = EventType> =
     U extends SymbolToken<any> ? SymbolToken<T> : U;
 
-export const EVENT_BUS_TOKEN = symbolToken<EventBus>('EVENT_BUS_TOKEN');
-export class EventBus {
+export type JobEventHandler<Event> = (defer: {
+    /**
+     * Successfully complete a job.
+     * @param result The value to return from the successfully completed job.
+     */
+    resolve(
+        ...result: Event extends SymbolToken<infer ResultType>
+            ? undefined extends ResultType
+                ? [Serializable<ResultType>?]
+                : [Serializable<ResultType>]
+            : [JobPayload]
+    ): void;
+    /**
+     * Fail a job.
+     * @param reason The error to return from the failed job.
+     */
+    reject(reason?: string | Error): void;
+}) => void;
+
+export class EventBus<EventTypes extends Serializable<EventTypes> = never> {
     job = {
-        on: <Result extends JobPayload = void>(type: string, handler: JobEventHandler<Result>) => {
-            this.emitter.on(type, handler);
+        /**
+         * Register a job event handler. Jobs event handlers return a result or an error.
+         * @param event The job event to handle.
+         * @param handler The handler to call when the event occurs. This handler is passed a `resolve` callback to return a successful result, and a `reject` callback to return an error.
+         */
+        on: <Event extends SymbolToken<any> | keyof EventTypes>(
+            event: Event,
+            handler: JobEventHandler<Event>
+        ) => {
+            this.emitter.on(event, handler);
         },
-        off: <Result extends JobPayload = void>(type: string, handler: JobEventHandler<Result>) => {
-            this.emitter.off(type, handler);
+
+        /**
+         * Deregister a job event handler.
+         * @param event The previously registered event.
+         * @param handler The previously registered handler.
+         */
+        off: <Event extends SymbolToken<any> | keyof EventTypes>(
+            event: Event,
+            handler: JobEventHandler<Event>
+        ) => {
+            this.emitter.off(event, handler);
         },
-        emit: <Result extends JobPayload = void>(type: string) => {
-            return new Promise<Result>((resolve, reject) => {
-                this.emitter.emit(type, {
+
+        /**
+         * Send a job event.
+         * @param event The event to send.
+         * @returns a Promise that resolves or rejects depending on whether the job completes successfully.
+         */
+        emit: <Event extends SymbolToken<any> | keyof EventTypes>(event: Event) => {
+            return new Promise<
+                Event extends SymbolToken<infer ResultType> ? Serializable<ResultType> : JobPayload
+            >((resolve, reject) => {
+                this.emitter.emit(event, {
                     resolve,
                     reject: (reason?: string | Error) => {
                         if (typeof reason === 'string' || reason instanceof Error) {
@@ -42,25 +95,54 @@ export class EventBus {
 
     private emitter = mitt<any>();
 
-    on = <T, U extends EventType = EventType>(
-        type: SymbolTokenEventType<T, U>,
-        handler: EventHandler<T>
+    /**
+     * Register an event handler.
+     * @param event The event to handle.
+     * @param handler The handler to call when the event occurs.
+     */
+    on = <T extends Serializable<T> = never, Event extends SymbolToken<T> | keyof EventTypes = any>(
+        event: SymbolTokenEventType<T, Event>,
+        handler: EventHandler<EventTypes, Event, T>
     ) => {
-        this.emitter.on(type, handler);
+        this.emitter.on(event, handler);
     };
 
-    off = <T, U extends EventType = EventType>(
-        type: SymbolTokenEventType<T, U>,
-        handler: EventHandler<T>
+    /**
+     * Deregister an event handler.
+     * @param event The previously registered event.
+     * @param handler The previously registered handler.
+     */
+    off = <
+        T extends Serializable<T> = never,
+        Event extends SymbolToken<T> | keyof EventTypes = any,
+    >(
+        event: SymbolTokenEventType<T, Event>,
+        handler: EventHandler<EventTypes, Event, T>
     ) => {
-        this.emitter.off(type, handler);
+        this.emitter.off(event, handler);
     };
 
-    emit = <T, U extends EventType = EventType>(type: SymbolTokenEventType<T, U>, data?: T) => {
-        this.emitter.emit(type, data);
+    /**
+     * Send an event.
+     * @param event The event to send.
+     * @param data The data to pass to the event's handler.
+     */
+    emit = <T extends Serializable<T>, Event extends SymbolToken<T> | keyof EventTypes = any>(
+        event: SymbolTokenEventType<T, Event>,
+        ...data: Event extends SymbolToken<any>
+            ? undefined extends T
+                ? [T?]
+                : [T]
+            : [EventTypes] extends [never]
+              ? [T?]
+              : Event extends keyof EventTypes
+                ? undefined extends EventTypes[Event]
+                    ? [EventTypes[Event]?]
+                    : [EventTypes[Event]] extends [never]
+                      ? []
+                      : [EventTypes[Event]]
+                : never
+    ) => {
+        this.emitter.emit(event, data[0]);
     };
 }
-
-export function useEventBus() {
-    return useRef(new EventBus()).current;
-}

package/src/index.ts

@@ -5,3 +5,5 @@ export * from './get-value-for-environment';
 export * from './history-manager';
 export * from './loader';
 export * from './register';
+
+export type { JSON, JSONPrimitive, Serializable } from './types';

package/src/loader.tsx

@@ -7,6 +7,7 @@ import {
     useEffect,
     useImperativeHandle,
     useMemo,
+    useRef,
 } from 'react';
 import { ErrorBoundary } from '@servicetitan/error-boundary';
 import { type LDService } from '@servicetitan/launchdarkly-service';
@@ -23,7 +24,7 @@ import {
 } from './common';
 import { MFEContextData } from './contexts/mfe-data-context';
 import { Delayed } from './delayed';
-import { EventBus, EVENT_BUS_TOKEN, useEventBus } from './event-bus';
+import { EventBus, EVENT_BUS_TOKEN } from './event-bus';
 import { EXPOSED_DEPENDENCIES, EXPOSED_INSTANCE_DEPENDENCIES } from './globals';
 import {
     BundleInfo,
@@ -260,5 +261,9 @@ function ensureLDService(
     return exposedInstanceDependencies;
 }
 
+function useEventBus() {
+    return useRef(new EventBus()).current;
+}
+
 const MINUTE = 1000 * 60;
 const bundleCache = new TtlCache<BundleInfo>({ ttlMs: 15 * MINUTE });

package/src/types.ts

@@ -1,4 +1,13 @@
 export type JSONPrimitive = string | number | boolean | null | undefined;
 
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export type JSON = { [key: string]: JSONPrimitive | JSON[] | JSON };
+export type JSON = JSONPrimitive | { [key: string | number]: JSON } | JSON[];
+
+export type Serializable<T> = {
+    [P in keyof T]: T[P] extends JSONPrimitive
+        ? T[P]
+        : T[P] extends Function | Date | Map<any, any> | Set<any> | symbol
+          ? never
+          : T[P] extends (infer U)[]
+            ? Serializable<U>[]
+            : Serializable<T[P]>;
+};