@squide/firefly 9.3.2 → 9.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@squide/firefly",
   "author": "Workleap",
-  "version": "9.3.2",
+  "version": "9.3.4",
   "description": "Helpers to facilitate the creation of an application with the Squide firefly technology stack.",
   "license": "Apache-2.0",
   "repository": {
@@ -22,7 +22,8 @@
     }
   },
   "files": [
-    "/dist",
+    "src",
+    "dist",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -34,29 +35,30 @@
     "react-router-dom": "*"
   },
   "dependencies": {
-    "@types/react": "19.0.1",
-    "@types/react-dom": "19.0.2",
-    "@squide/core": "5.4.1",
-    "@squide/module-federation": "6.2.1",
-    "@squide/msw": "3.2.1",
-    "@squide/react-router": "6.4.2"
+    "@types/react": "19.0.7",
+    "@types/react-dom": "19.0.3",
+    "@squide/core": "5.4.2",
+    "@squide/module-federation": "6.2.2",
+    "@squide/msw": "3.2.2",
+    "@squide/react-router": "6.4.4"
   },
   "devDependencies": {
-    "@rsbuild/plugin-react": "1.1.0",
-    "@rslib/core": "0.1.4",
-    "@swc/core": "1.10.1",
+    "@rsbuild/core": "1.1.13",
+    "@rslib/core": "0.3.1",
+    "@swc/core": "1.10.7",
     "@swc/jest": "0.2.37",
     "@testing-library/jest-dom": "6.6.3",
-    "@testing-library/react": "16.1.0",
+    "@testing-library/react": "16.2.0",
     "@types/jest": "29.5.14",
-    "@typescript-eslint/parser": "8.18.0",
-    "@workleap/eslint-plugin": "3.2.5",
-    "@workleap/swc-configs": "2.2.3",
+    "@typescript-eslint/parser": "8.20.0",
+    "@workleap/eslint-plugin": "3.2.6",
+    "@workleap/rslib-configs": "1.0.2",
+    "@workleap/swc-configs": "2.2.4",
     "@workleap/typescript-configs": "3.0.2",
     "eslint": "8.57.0",
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",
-    "msw": "2.6.9",
+    "msw": "2.7.0",
     "react": "19.0.0",
     "react-dom": "19.0.0",
     "react-router-dom": "6.27.0",

package/src/AppRouter.tsx

@@ -0,0 +1,63 @@
+import { useLogger } from "@squide/core";
+import { useRoutes, type Route } from "@squide/react-router";
+import { useEffect, useMemo, type ReactElement } from "react";
+import type { RouterProviderProps } from "react-router-dom";
+import { AppRouterDispatcherContext, AppRouterStateContext } from "./AppRouterContext.ts";
+import { useAppRouterReducer } from "./AppRouterReducer.ts";
+import { RootRoute } from "./RootRoute.tsx";
+import { useStrictRegistrationMode } from "./useStrictRegistrationMode.ts";
+
+export interface AppRouterRenderFunctionArgs {
+    routes: Route[];
+}
+
+export interface RenderRouterProviderFunctionArgs {
+    rootRoute: ReactElement;
+    registeredRoutes: Route[];
+    routerProviderProps: Omit<RouterProviderProps, "router">;
+}
+
+export type RenderRouterProviderFunction = (args: RenderRouterProviderFunctionArgs) => ReactElement;
+
+export interface AppRouterProps {
+    waitForMsw: boolean;
+    waitForPublicData?: boolean;
+    waitForProtectedData?: boolean;
+    children: RenderRouterProviderFunction;
+}
+
+export function AppRouter(props: AppRouterProps) {
+    const {
+        waitForMsw,
+        waitForPublicData = false,
+        waitForProtectedData = false,
+        children: renderRouterProvider
+    } = props;
+
+    const [state, dispatch] = useAppRouterReducer(waitForMsw, waitForPublicData, waitForProtectedData);
+
+    const logger = useLogger();
+    const routes = useRoutes();
+
+    useStrictRegistrationMode();
+
+    useEffect(() => {
+        logger.debug("[squide] AppRouter state updated:", state);
+    }, [state, logger]);
+
+    const routerProvider = useMemo(() => {
+        return renderRouterProvider({
+            rootRoute: <RootRoute />,
+            registeredRoutes: routes,
+            routerProviderProps: {}
+        });
+    }, [routes, renderRouterProvider]);
+
+    return (
+        <AppRouterDispatcherContext.Provider value={dispatch}>
+            <AppRouterStateContext.Provider value={state}>
+                {routerProvider}
+            </AppRouterStateContext.Provider>
+        </AppRouterDispatcherContext.Provider>
+    );
+}

package/src/AppRouterContext.ts

@@ -0,0 +1,27 @@
+import { isNil } from "@squide/core";
+import { createContext, useContext } from "react";
+import type { AppRouterDispatch, AppRouterState } from "./AppRouterReducer.ts";
+
+export const AppRouterStateContext = createContext<AppRouterState | undefined>(undefined);
+
+export function useAppRouterState() {
+    const state = useContext(AppRouterStateContext);
+
+    if (isNil(state)) {
+        throw new Error("[squide] The useAppRouterState hook must be called by a children of the AppRouter component.");
+    }
+
+    return state;
+}
+
+export const AppRouterDispatcherContext = createContext<AppRouterDispatch | undefined>(undefined);
+
+export function useAppRouterDispatcher() {
+    const dispatch = useContext(AppRouterDispatcherContext);
+
+    if (isNil(dispatch)) {
+        throw new Error("[squide] The useAppRouterDispatcher hook must be called by a children of the AppRouter component.");
+    }
+
+    return dispatch;
+}

package/src/AppRouterReducer.ts

@@ -0,0 +1,363 @@
+import { addLocalModuleRegistrationStatusChangedListener, getLocalModuleRegistrationStatus, removeLocalModuleRegistrationStatusChangedListener, useEventBus, useLogger } from "@squide/core";
+import { addRemoteModuleRegistrationStatusChangedListener, areModulesReady, areModulesRegistered, getRemoteModuleRegistrationStatus, removeRemoteModuleRegistrationStatusChangedListener } from "@squide/module-federation";
+import { addMswStateChangedListener, isMswReady, removeMswStateChangedListener } from "@squide/msw";
+import { useCallback, useEffect, useMemo, useReducer, type Dispatch } from "react";
+import { useExecuteOnce } from "./useExecuteOnce.ts";
+import { isApplicationBootstrapping } from "./useIsBootstrapping.ts";
+
+export type ActiveRouteVisiblity = "unknown" | "public" | "protected";
+
+export interface AppRouterState {
+    waitForMsw: boolean;
+    waitForPublicData: boolean;
+    waitForProtectedData: boolean;
+    areModulesRegistered: boolean;
+    areModulesReady: boolean;
+    isMswReady: boolean;
+    isPublicDataReady: boolean;
+    isProtectedDataReady: boolean;
+    publicDataUpdatedAt?: number;
+    protectedDataUpdatedAt?: number;
+    deferredRegistrationsUpdatedAt?: number;
+    activeRouteVisibility: ActiveRouteVisiblity;
+    isUnauthorized: boolean;
+}
+
+export type AppRouterActionType =
+| "modules-registered"
+| "modules-ready"
+| "msw-ready"
+| "public-data-ready"
+| "protected-data-ready"
+| "public-data-updated"
+| "protected-data-updated"
+| "deferred-registrations-updated"
+| "active-route-is-public"
+| "active-route-is-protected"
+| "is-unauthorized";
+
+// The followings event const are a concatenation of "squide-" with AppRouterActionType.
+// They are dispatched by the useEnhancedReducerDispatch hook.
+export const ModulesRegisteredEvent = "squide-modules-registered";
+export const ModulesReadyEvent = "squide-modules-ready";
+export const MswReadyEvent = "squide-msw-ready";
+export const PublicDataReadyEvent = "squide-public-data-ready";
+export const ProtectedDataReadyEvent = "squide-protected-data-ready";
+export const PublicDataUpdatedEvent = "squide-public-data-updated";
+export const ProtectedDataUpdatedEvent = "squide-protected-data-updated";
+export const DeferredRegistrationsUpdatedEvent = "squide-deferred-registrations-updated";
+export const ApplicationBoostrappedEvent = "squide-app-boostrapped";
+
+export interface AppRouterAction {
+    type: AppRouterActionType;
+}
+
+export type AppRouterDispatch = Dispatch<AppRouterAction>;
+
+function reducer(state: AppRouterState, action: AppRouterAction) {
+    let newState = state;
+
+    switch (action.type) {
+        case "modules-registered": {
+            newState = {
+                ...newState,
+                areModulesRegistered: true
+            };
+
+            break;
+        }
+        case "modules-ready": {
+            newState = {
+                ...newState,
+                areModulesReady: true,
+                // Will be set even if the app is not using deferred registrations.
+                deferredRegistrationsUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "msw-ready": {
+            newState = {
+                ...newState,
+                isMswReady: true
+            };
+
+            break;
+        }
+        case "public-data-ready": {
+            newState = {
+                ...newState,
+                isPublicDataReady: true,
+                publicDataUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "protected-data-ready": {
+            newState = {
+                ...newState,
+                isProtectedDataReady: true,
+                protectedDataUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "public-data-updated": {
+            newState = {
+                ...newState,
+                publicDataUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "protected-data-updated": {
+            newState = {
+                ...newState,
+                protectedDataUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "deferred-registrations-updated": {
+            newState = {
+                ...newState,
+                deferredRegistrationsUpdatedAt: Date.now()
+            };
+
+            break;
+        }
+        case "active-route-is-public": {
+            newState = {
+                ...newState,
+                activeRouteVisibility: "public"
+            };
+
+            break;
+        }
+        case "active-route-is-protected": {
+            newState = {
+                ...newState,
+                activeRouteVisibility: "protected"
+            };
+
+            break;
+        }
+        case "is-unauthorized": {
+            newState = {
+                ...newState,
+                isUnauthorized: true
+            };
+
+            break;
+        }
+        default: {
+            throw new Error(`[squide] The AppRouter component state reducer doesn't support action type "${action.type}".`);
+        }
+    }
+
+    return newState;
+}
+
+export function getAreModulesRegistered() {
+    const localModuleStatus = getLocalModuleRegistrationStatus();
+    const remoteModuleStatus = getRemoteModuleRegistrationStatus();
+
+    return areModulesRegistered(localModuleStatus, remoteModuleStatus);
+}
+
+export function getAreModulesReady() {
+    const localModuleStatus = getLocalModuleRegistrationStatus();
+    const remoteModuleStatus = getRemoteModuleRegistrationStatus();
+
+    return areModulesReady(localModuleStatus, remoteModuleStatus);
+}
+
+export function useModuleRegistrationStatusDispatcher(areModulesRegisteredValue: boolean, areModulesReadyValue: boolean, dispatch: AppRouterDispatch) {
+    const logger = useLogger();
+
+    const dispatchModulesRegistered = useExecuteOnce(useCallback(() => {
+        if (getAreModulesRegistered()) {
+            dispatch({ type: "modules-registered" });
+
+            logger.debug("[squide] %cModules are registered%c.", "color: white; background-color: green;", "");
+
+            return true;
+        }
+
+        return false;
+    }, [dispatch, logger]));
+
+    const dispatchModulesReady = useExecuteOnce(useCallback(() => {
+        if (getAreModulesReady()) {
+            dispatch({ type: "modules-ready" });
+
+            logger.debug("[squide] %cModules are ready%c.", "color: white; background-color: green;", "");
+
+            return true;
+        }
+
+        return false;
+    }, [dispatch, logger]));
+
+    return useEffect(() => {
+        if (!areModulesRegisteredValue) {
+            addLocalModuleRegistrationStatusChangedListener(dispatchModulesRegistered);
+            addRemoteModuleRegistrationStatusChangedListener(dispatchModulesRegistered);
+        }
+
+        if (!areModulesReadyValue) {
+            addLocalModuleRegistrationStatusChangedListener(dispatchModulesReady);
+            addRemoteModuleRegistrationStatusChangedListener(dispatchModulesReady);
+        }
+
+        return () => {
+            removeLocalModuleRegistrationStatusChangedListener(dispatchModulesRegistered);
+            removeRemoteModuleRegistrationStatusChangedListener(dispatchModulesRegistered);
+
+            removeLocalModuleRegistrationStatusChangedListener(dispatchModulesReady);
+            removeRemoteModuleRegistrationStatusChangedListener(dispatchModulesReady);
+        };
+    }, [areModulesRegisteredValue, areModulesReadyValue, dispatchModulesRegistered, dispatchModulesReady]);
+}
+
+export function useMswStatusDispatcher(isMswReadyValue: boolean, dispatch: AppRouterDispatch) {
+    const logger = useLogger();
+
+    const dispatchMswReady = useExecuteOnce(useCallback(() => {
+        if (isMswReady()) {
+            dispatch({ type: "msw-ready" });
+
+            logger.debug("[squide] %cMSW is ready%c.", "color: white; background-color: green;", "");
+
+            return true;
+        }
+
+        return false;
+    }, [dispatch, logger]));
+
+    useEffect(() => {
+        if (!isMswReadyValue) {
+            addMswStateChangedListener(dispatchMswReady);
+        }
+
+        return () => {
+            removeMswStateChangedListener(dispatchMswReady);
+        };
+    }, [isMswReadyValue, dispatchMswReady]);
+}
+
+export function useBootstrappingCompletedDispatcher(state: AppRouterState) {
+    const eventBus = useEventBus();
+
+    const areModulesRegisteredValue = state.areModulesRegistered;
+    const isBoostrapping = isApplicationBootstrapping(state);
+
+    useExecuteOnce(useCallback(() => {
+        if (areModulesRegisteredValue && !isBoostrapping) {
+            eventBus.dispatch(ApplicationBoostrappedEvent);
+
+            return true;
+        }
+
+        return false;
+    }, [areModulesRegisteredValue, isBoostrapping, eventBus]), true);
+}
+
+let dispatchProxyFactory: ((reactDispatch: AppRouterDispatch) => AppRouterDispatch) | undefined;
+
+// This function should only be used by tests.
+export function __setAppReducerDispatchProxyFactory(factory: (reactDispatch: AppRouterDispatch) => AppRouterDispatch) {
+    dispatchProxyFactory = factory;
+}
+
+// This function should only be used by tests.
+export function __clearAppReducerDispatchProxy() {
+    dispatchProxyFactory = undefined;
+}
+
+function useReducerDispatchProxy(reactDispatch: AppRouterDispatch) {
+    return useMemo(() => {
+        return dispatchProxyFactory ? dispatchProxyFactory(reactDispatch) : reactDispatch;
+    }, [reactDispatch]);
+}
+
+function useEnhancedReducerDispatch(reducerDispatch: AppRouterDispatch) {
+    const logger = useLogger();
+    const eventBus = useEventBus();
+
+    return useCallback((action: AppRouterAction) => {
+        logger.debug("[squide] The following action has been dispatched to the AppRouter reducer:", action);
+        eventBus.dispatch(`squide-${action.type}`);
+
+        reducerDispatch(action);
+    }, [reducerDispatch, logger, eventBus]);
+}
+
+export function useAppRouterReducer(waitForMsw: boolean, waitForPublicData: boolean, waitForProtectedData: boolean): [AppRouterState, AppRouterDispatch] {
+    const areModulesInitiallyRegistered = getAreModulesRegistered();
+    const areModulesInitiallyReady = getAreModulesReady();
+    const isMswInitiallyReady = isMswReady();
+
+    const eventBus = useEventBus();
+
+    // When modules are initially registered, the reducer action will never be dispatched, therefore the event would not be dispatched as well.
+    // To ensure the bootstrapping events sequencing, the event is manually dispatched when the modules are initially registered.
+    useExecuteOnce(useCallback(() => {
+        if (areModulesInitiallyRegistered) {
+            eventBus.dispatch(ModulesRegisteredEvent);
+        }
+
+        return true;
+    }, [areModulesInitiallyRegistered, eventBus]), true);
+
+    // When modules are initially registered, the reducer action will never be dispatched, therefore the event would not be dispatched as well.
+    // To ensure the bootstrapping events sequencing, the event is manually dispatched when the modules are initially registered.
+    useExecuteOnce(useCallback(() => {
+        if (areModulesInitiallyReady) {
+            eventBus.dispatch(ModulesReadyEvent);
+        }
+
+        return true;
+    }, [areModulesInitiallyReady, eventBus]), true);
+
+    // When modules are initially registered, the reducer action will never be dispatched, therefore the event would not be dispatched as well.
+    // To ensure the bootstrapping events sequencing, the event is manually dispatched when the modules are initially registered.
+    useExecuteOnce(useCallback(() => {
+        if (isMswInitiallyReady) {
+            eventBus.dispatch(MswReadyEvent);
+        }
+
+        return true;
+    }, [isMswInitiallyReady, eventBus]), true);
+
+    const [state, reactDispatch] = useReducer(reducer, {
+        waitForMsw,
+        waitForPublicData,
+        waitForProtectedData,
+        // When the modules registration functions are awaited, the event listeners are registered after the modules are registered.
+        areModulesRegistered: areModulesInitiallyRegistered,
+        areModulesReady: areModulesInitiallyReady,
+        isMswReady: isMswInitiallyReady,
+        isPublicDataReady: false,
+        isProtectedDataReady: false,
+        activeRouteVisibility: "unknown",
+        isUnauthorized: false
+    });
+
+    const {
+        areModulesRegistered: areModulesRegisteredValue,
+        areModulesReady: areModulesReadyValue,
+        isMswReady: isMswReadyValue
+    } = state;
+
+    // The dispatch proxy is strictly an utility allowing tests to mock the useReducer dispatch function. It's easier
+    // than mocking the import from React.
+    const dispatchProxy = useReducerDispatchProxy(reactDispatch);
+    const dispatch = useEnhancedReducerDispatch(dispatchProxy);
+
+    useModuleRegistrationStatusDispatcher(areModulesRegisteredValue, areModulesReadyValue, dispatch);
+    useMswStatusDispatcher(isMswReadyValue, dispatch);
+    useBootstrappingCompletedDispatcher(state);
+
+    return [state, dispatch];
+}

package/src/FireflyRuntime.tsx

@@ -0,0 +1,71 @@
+import type { RegisterRouteOptions, RuntimeOptions } from "@squide/core";
+import { MswPlugin, MswPluginName } from "@squide/msw";
+import { ReactRouterRuntime, type Route } from "@squide/react-router";
+import type { RequestHandler } from "msw";
+import { getAreModulesRegistered } from "./AppRouterReducer.ts";
+
+export interface FireflyRuntimeOptions extends RuntimeOptions {
+    useMsw?: boolean;
+}
+
+export class FireflyRuntime extends ReactRouterRuntime {
+    readonly #useMsw: boolean;
+
+    constructor({ plugins, useMsw, ...options }: FireflyRuntimeOptions = {}) {
+        if (useMsw) {
+            super({
+                plugins: [
+                    ...(plugins ?? []),
+                    runtime => new MswPlugin(runtime)
+                ],
+                ...options
+            });
+
+            this.#useMsw = true;
+        } else {
+            super({
+                plugins,
+                ...options
+            });
+
+            this.#useMsw = false;
+        }
+    }
+
+    registerRequestHandlers(handlers: RequestHandler[]) {
+        const mswPlugin = this.getPlugin(MswPluginName) as MswPlugin;
+
+        if (!mswPlugin) {
+            throw new Error("[squide] Cannot register the provided MSW request handlers because the runtime hasn't been initialized with MSW. Did you instanciate the FireflyRuntime with the \"useMsw\" option?");
+        }
+
+        if (getAreModulesRegistered()) {
+            throw new Error("[squide] Cannot register an MSW request handlers once the modules are registered. Are you trying to register an MSW request handler in a deferred registration function? Only navigation items can be registered in a deferred registration function.");
+        }
+
+        mswPlugin.registerRequestHandlers(handlers);
+    }
+
+    // Must define a return type otherwise we get an "error TS2742: The inferred type of 'requestHandlers' cannot be named" error.
+    get requestHandlers(): RequestHandler[] {
+        const mswPlugin = this.getPlugin(MswPluginName) as MswPlugin;
+
+        if (!mswPlugin) {
+            throw new Error("[squide] Cannot retrieve MSW request handlers because the runtime hasn't been initialized with MSW. Did you instanciate the FireflyRuntime with the \"useMsw\" option?");
+        }
+
+        return mswPlugin.requestHandlers;
+    }
+
+    registerRoute(route: Route, options: RegisterRouteOptions = {}) {
+        if (getAreModulesRegistered()) {
+            throw new Error("[squide] Cannot register a route once the modules are registered. Are you trying to register a route in a deferred registration function? Only navigation items can be registered in a deferred registration function.");
+        }
+
+        super.registerRoute(route, options);
+    }
+
+    get isMswEnabled() {
+        return this.#useMsw;
+    }
+}

package/src/GlobalDataQueriesError.ts

@@ -0,0 +1,17 @@
+export class GlobalDataQueriesError extends Error {
+    readonly #errors: Error[];
+
+    constructor(message: string, errors: Error[]) {
+        super(message);
+
+        this.#errors = errors;
+    }
+
+    get errors() {
+        return this.#errors;
+    }
+}
+
+export function isGlobalDataQueriesError(error?: unknown): error is GlobalDataQueriesError {
+    return error !== undefined && error !== null && error instanceof GlobalDataQueriesError;
+}

package/src/RootRoute.tsx

@@ -0,0 +1,25 @@
+import { useEffect } from "react";
+import { Outlet } from "react-router-dom";
+import { useAppRouterDispatcher, useAppRouterState } from "./AppRouterContext.ts";
+import { useIsActiveRouteProtected } from "./useIsActiveRouteProtected.ts";
+
+export function RootRoute() {
+    const state = useAppRouterState();
+    const isActiveRouteProtected = useIsActiveRouteProtected(state.areModulesReady);
+
+    const dispatch = useAppRouterDispatcher();
+
+    useEffect(() => {
+        // Dispatching the active route visibility must be done in a route because React Router's useLocation
+        // hook throws if it's not called from a child of the router component.
+        if (isActiveRouteProtected) {
+            dispatch({ type: "active-route-is-protected" });
+        } else {
+            dispatch({ type: "active-route-is-public" });
+        }
+    }, [isActiveRouteProtected, dispatch]);
+
+    return (
+        <Outlet />
+    );
+}