@equinor/fusion-framework-module-app 5.2.13 → 5.3.0

package/dist/types/app/App.d.ts

@@ -39,12 +39,12 @@ export declare class App<TEnv = any, TModules extends Array<AnyModule> | unknown
     get config$(): Observable<AppConfig<TEnv>>;
     get modules$(): Observable<AppScriptModule>;
     get instance$(): Observable<AppModulesInstance<TModules>>;
-    get state(): AppBundleState;
+    get state(): Readonly<AppBundleState>;
     get appKey(): string;
-    get manifest(): AppManifest | undefined;
-    get manifestAsync(): Promise<AppManifest>;
-    get config(): AppConfig<TEnv> | undefined;
-    get configAsync(): Promise<AppConfig<TEnv>>;
+    get manifest(): Readonly<AppManifest> | undefined;
+    get manifestAsync(): Promise<Readonly<AppManifest>>;
+    get config(): Readonly<AppConfig<TEnv>> | undefined;
+    get configAsync(): Promise<Readonly<AppConfig<TEnv>>>;
     get instance(): AppModulesInstance<TModules> | undefined;
     constructor(value: AppBundleStateInitial, args: {
         provider: AppModuleProvider;

package/dist/types/helpers.d.ts

@@ -1,2 +1,2 @@
 import { AppManifest } from './types';
-export declare const compareAppManifest: <T extends AppManifest>(a?: T | undefined, b?: T | undefined) => boolean;
+export declare const compareAppManifest: <T extends AppManifest>(a?: T, b?: T) => boolean;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.2.13";
+export declare const version = "5.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-app",
-  "version": "5.2.13",
+  "version": "5.3.0",
   "description": "",
   "main": "dist/esm/index.js",
   "exports": {
@@ -48,16 +48,16 @@
   "dependencies": {
     "immer": "^9.0.16",
     "rxjs": "^7.8.1",
-    "@equinor/fusion-observable": "^8.1.5",
-    "@equinor/fusion-query": "^4.0.6"
+    "@equinor/fusion-observable": "^8.2.0",
+    "@equinor/fusion-query": "^4.1.0"
   },
   "devDependencies": {
-    "typescript": "^5.1.3",
-    "@equinor/fusion-framework-module": "^4.2.6",
-    "@equinor/fusion-framework-module-event": "^4.0.7",
-    "@equinor/fusion-framework-module-http": "^5.1.5",
-    "@equinor/fusion-framework-module-msal": "^3.0.9",
-    "@equinor/fusion-framework-module-service-discovery": "^7.0.19"
+    "typescript": "^5.4.2",
+    "@equinor/fusion-framework-module-event": "^4.1.0",
+    "@equinor/fusion-framework-module": "^4.3.0",
+    "@equinor/fusion-framework-module-http": "^5.2.0",
+    "@equinor/fusion-framework-module-msal": "^3.1.0",
+    "@equinor/fusion-framework-module-service-discovery": "^7.1.0"
   },
   "scripts": {
     "build": "tsc -b"

package/src/app/App.ts

@@ -8,7 +8,6 @@ import {
     firstValueFrom,
     lastValueFrom,
     map,
-    of,
     OperatorFunction,
     Subscription,
 } from 'rxjs';
@@ -25,39 +24,150 @@ export function filterEmpty<T>(): OperatorFunction<T | null | undefined, T> {
     return filter((value): value is T => value !== undefined && value !== null);
 }
 
-// TODO add comments!
+/**
+ * Represents an application in the framework.
+ * @template TEnv The type of the environment.
+ * @template TModules The type of the app modules.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface IApp<TEnv = any, TModules extends Array<AnyModule> | unknown = unknown> {
+    /**
+     * Returns an observable that emits the app manifest.
+     * @returns An observable of type AppManifest.
+     */
     get manifest$(): Observable<AppManifest>;
+
+    /**
+     * Observable that emits the configuration of the app.
+     * @returns An Observable that emits the app configuration.
+     */
     get config$(): Observable<AppConfig<TEnv>>;
+
+    /**
+     * Returns an observable stream of the loaded app script instance.
+     * @returns {Observable<AppScriptModule>} The observable stream of app script modules.
+     */
     get modules$(): Observable<AppScriptModule>;
+
+    /**
+     * Returns an observable that emits the instance of the app modules.
+     * @returns An observable that emits the instance of the app modules.
+     */
     get instance$(): Observable<AppModulesInstance<TModules>>;
+
+    /**
+     * Gets the current state of the Application.
+     * @returns The current state of the Application.
+     */
     get state(): AppBundleState;
+
+    /**
+     * Gets the app key.
+     * @returns The app key.
+     */
     get appKey(): string;
+
+    /**
+     * Gets the manifest of the app.
+     * @returns The manifest of the app, or undefined if it doesn't exist.
+     */
     get manifest(): AppManifest | undefined;
+
+    /**
+     * Retrieves the manifest asynchronously.
+     * @returns A promise that resolves to the AppManifest.
+     */
     get manifestAsync(): Promise<AppManifest>;
+
+    /**
+     * Gets the configuration of the app.
+     * @returns The configuration object or undefined if no configuration is set.
+     */
     get config(): AppConfig<TEnv> | undefined;
+
+    /**
+     * Retrieves the configuration asynchronously.
+     * @returns A promise that resolves to the AppConfig.
+     */
     get instance(): AppModulesInstance<TModules> | undefined;
 
+    /**
+     * Initializes the application container.
+     * @returns An observable that emits an object containing the manifest, script, and config.
+     * @example
+     * ```typescript
+     * app.initialize().subscribe({
+     *   next: ({ manifest, script, config }) => {
+     *     // Use the manifest, script, and config to initialize the application
+     *     script.render(el, ...);
+     *   },
+     *   error: (err) => console.error('Failed to load application', err),
+     *   complete: () => setInitializingApp(false)
+     * });
+     * ```
+     */
     initialize(): Observable<{
         manifest: AppManifest;
         script: AppScriptModule;
         config: AppConfig;
     }>;
 
+    /**
+     * Loads the app configuration.
+     */
     loadConfig(): void;
 
+    /**
+     * Loads the app manifest.
+     */
     loadManifest(): void;
 
+    /**
+     * Loads the app module.
+     * @param allow_cache Whether to allow loading from cache.
+     */
     loadAppModule(allow_cache?: boolean): void;
 
+    /**
+     * Gets the app configuration.
+     * @param force_refresh Whether to force refreshing the configuration.
+     * @returns An observable that emits the app configuration.
+     */
     getConfig(force_refresh?: boolean): Observable<AppConfig>;
+
+    /**
+     * Retrieves the app configuration asynchronously.
+     * @param allow_cache Whether to allow loading from cache.
+     * @returns A promise that resolves to the AppConfig.
+     */
     getConfigAsync(allow_cache?: boolean): Promise<AppConfig>;
 
+    /**
+     * Gets the app manifest.
+     * @param force_refresh Whether to force refreshing the manifest.
+     * @returns An observable that emits the app manifest.
+     */
     getManifest(force_refresh?: boolean): Observable<AppManifest>;
+
+    /**
+     * Retrieves the app manifest asynchronously.
+     * @param allow_cache Whether to allow loading from cache.
+     * @returns A promise that resolves to the AppManifest.
+     */
     getManifestAsync(allow_cache?: boolean): Promise<AppManifest>;
 
+    /**
+     * Gets the app module.
+     * @param force_refresh Whether to force refreshing the app module.
+     * @returns An observable that emits the app module.
+     */
     getAppModule(force_refresh?: boolean): Observable<AppScriptModule>;
+
+    /**
+     * Retrieves the app module asynchronously.
+     * @param allow_cache Whether to allow loading from cache.
+     * @returns A promise that resolves to the AppScriptModule.
+     */
     getAppModuleAsync(allow_cache?: boolean): Promise<AppScriptModule>;
 }
 
@@ -100,28 +210,28 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
 
     //#endregion
 
-    get state(): AppBundleState {
+    get state(): Readonly<AppBundleState> {
         // todo deep-freeze
-        return this.#state.value;
+        return Object.freeze(this.#state.value) as Readonly<AppBundleState>;
     }
 
     get appKey(): string {
         return this.#state.value.appKey;
     }
 
-    get manifest(): AppManifest | undefined {
+    get manifest(): Readonly<AppManifest> | undefined {
         return this.state.manifest;
     }
 
-    get manifestAsync(): Promise<AppManifest> {
+    get manifestAsync(): Promise<Readonly<AppManifest>> {
         return firstValueFrom(this.manifest$);
     }
 
-    get config(): AppConfig<TEnv> | undefined {
+    get config(): Readonly<AppConfig<TEnv>> | undefined {
         return this.state.config;
     }
 
-    get configAsync(): Promise<AppConfig<TEnv>> {
+    get configAsync(): Promise<Readonly<AppConfig<TEnv>>> {
         return firstValueFrom(this.config$);
     }
 
@@ -141,16 +251,24 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
         const { appKey } = value;
         const { event } = args;
 
+        // register events if event module is provided
         event && this.#registerEvents(event);
 
+        // create a tear down handler for the application
         const subscriptions = new Subscription();
+
         if (event) {
+            // when app is disposed, dispatch event to notify listeners
             subscriptions.add(() => {
                 event.dispatchEvent('onAppDispose', { detail: { appKey } });
             });
+
+            // when disposed, dispose of monitoring of app modules loaded
             subscriptions.add(
                 event.addEventListener('onAppModulesLoaded', (e) => {
+                    // validate that the event is for the current app
                     if (e.detail.appKey === appKey) {
+                        // set the instance of the app modules
                         this.#state.next(actions.setInstance(e.detail.modules));
                     }
                 }),
@@ -160,88 +278,122 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
         this.dispose = () => {
             subscriptions?.unsubscribe();
             if (this.#state.value.instance) {
-                /** tear down modules of application */
+                // tear down modules of application
                 this.#state.value.instance.dispose();
             }
             this.#state.complete();
         };
     }
 
+    /**
+     * Registers event listeners for various actions in the app.
+     * @param event - The event module used for dispatching events.
+     */
     #registerEvents(event: ModuleType<EventModule>): void {
         const { appKey } = this;
 
+        // monitor when application manifest is loading
         this.#state.addEffect(actions.fetchManifest.type, () => {
+            // dispatch event to notify listeners that the application manifest is being loaded
             event.dispatchEvent('onAppManifestLoad', {
                 detail: { appKey },
                 source: this,
             });
         });
+
+        // monitor when application manifest is loaded
         this.#state.addEffect(actions.fetchManifest.success.type, (action) => {
+            // dispatch event to notify listeners that the application manifest has been loaded
             event.dispatchEvent('onAppManifestLoaded', {
                 detail: { appKey, manifest: action.payload },
                 source: this,
             });
         });
+
+        // monitor when application manifest fails to load
         this.#state.addEffect(actions.fetchManifest.failure.type, (action) => {
+            // dispatch event to notify listeners that the application manifest failed to load
             event.dispatchEvent('onAppManifestFailure', {
                 detail: { appKey, error: action.payload },
                 source: this,
             });
         });
 
+        // monitor when application configuration is loading
         this.#state.addEffect(actions.fetchConfig.type, () => {
+            // dispatch event to notify listeners that the application configuration is being loaded
             event.dispatchEvent('onAppConfigLoad', {
                 detail: { appKey },
                 source: this,
             });
         });
+
+        // monitor when application configuration is loaded
         this.#state.addEffect(actions.fetchConfig.success.type, (action) => {
+            // dispatch event to notify listeners that the application configuration has been loaded
             event.dispatchEvent('onAppConfigLoaded', {
                 detail: { appKey, config: action.payload },
                 source: this,
             });
         });
+
+        // monitor when application configuration fails to load
         this.#state.addEffect(actions.fetchConfig.failure.type, (action) => {
+            // dispatch event to notify listeners that the application configuration failed to load
             event.dispatchEvent('onAppConfigFailure', {
                 detail: { appKey, error: action.payload },
                 source: this,
             });
         });
 
+        // monitor when application script is loading
         this.#state.addEffect(actions.importApp.type, () => {
+            // dispatch event to notify listeners that the application script is being loaded
             event.dispatchEvent('onAppScriptLoad', {
                 detail: { appKey },
                 source: this,
             });
         });
+
+        // monitor when application script is loaded
         this.#state.addEffect(actions.importApp.success.type, (action) => {
+            // dispatch event to notify listeners that the application script has been loaded
             event.dispatchEvent('onAppScriptLoaded', {
                 detail: { appKey, script: action.payload },
                 source: this,
             });
         });
+
+        // monitor when application script fails to load
         this.#state.addEffect(actions.importApp.failure.type, (action) => {
+            // dispatch event to notify listeners that the application script failed to load
             event.dispatchEvent('onAppScriptFailure', {
                 detail: { appKey, error: action.payload },
                 source: this,
             });
         });
 
+        // monitor when application is initializing
         this.#state.addEffect(actions.initialize.type, () => {
+            // dispatch event to notify listeners that the application is initializing
             event.dispatchEvent('onAppInitialize', {
                 detail: { appKey },
                 source: this,
             });
         });
 
+        // monitor when application has been initialized
         this.#state.addEffect(actions.initialize.success.type, () => {
+            // dispatch event to notify listeners that the application has been initialized
             event.dispatchEvent('onAppInitialized', {
                 detail: { appKey },
                 source: this,
             });
         });
 
+        // monitor when application fails to initialize
         this.#state.addEffect(actions.initialize.failure.type, ({ payload }) => {
+            // dispatch event to notify listeners that the application failed to initialize
             event.dispatchEvent('onAppInitializeFailure', {
                 detail: { appKey, error: payload },
                 source: this,
@@ -249,45 +401,36 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
         });
     }
 
-    /**
-     * The initializing request won`t trigger until subscribing to the returned observable
-     *
-     * @example
-     * ```ts
-     * app.initialize().subscribe({
-     *  next: (value) => {
-     *      value.script.render(el, ...);
-     *  },
-     *  error: (err) => console.error('failed to load application', err),
-     *  complete: () => setInitializingApp(false)
-     * })
-     * ```
-     */
     public initialize(): Observable<{
         manifest: AppManifest;
         script: AppScriptModule;
         config: AppConfig;
     }> {
-        return new Observable((observer) => {
+        return new Observable((subscriber) => {
+            // dispatch initialize action to indicate that the application is initializing
             this.#state.next(actions.initialize());
-            observer.add(
+            subscriber.add(
+                // request latest manifest, application script, and configuration
                 combineLatest([
                     this.getManifest(),
                     this.getAppModule(),
                     this.getConfig(),
                 ]).subscribe({
                     next: ([manifest, script, config]) =>
-                        observer.next({
+                        // emit the manifest, script, and config to the subscriber
+                        subscriber.next({
                             manifest,
                             script,
                             config,
                         }),
                     error: (err) => {
-                        observer.error(err), this.#state.next(actions.initialize.failure(err));
+                        // emit error and complete the stream
+                        subscriber.error(err), this.#state.next(actions.initialize.failure(err));
                     },
                     complete: () => {
+                        // dispatch initialize success action to indicate that the application has been initialized
                         this.#state.next(actions.initialize.success());
-                        observer.complete();
+                        subscriber.complete();
                     },
                 }),
             );
@@ -314,24 +457,37 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
     public getConfig(force_refresh = false): Observable<AppConfig> {
         return new Observable((subscriber) => {
             if (this.#state.value.config) {
+                // emit current config to the subscriber
                 subscriber.next(this.#state.value.config);
                 if (!force_refresh) {
+                    // since we have the config and no force refresh, complete the stream
                     return subscriber.complete();
                 }
             }
+
+            // when stream closes, dispose of subscription to change of state config
             subscriber.add(
+                // monitor changes to state changes of config and emit to subscriber
                 this.#state.addEffect('set_config', ({ payload }) => {
                     subscriber.next(payload);
                 }),
             );
+
+            // when stream closes, dispose of subscription to fetch config
             subscriber.add(
+                // monitor success of fetching config and emit to subscriber
                 this.#state.addEffect('fetch_config::success', ({ payload }) => {
+                    // application config loaded, emit to subscriber and complete the stream
                     subscriber.next(payload);
                     subscriber.complete();
                 }),
             );
+
+            // when stream closes, dispose of subscription to fetch config
             subscriber.add(
+                // monitor failure of fetching config and emit error to subscriber
                 this.#state.addEffect('fetch_config::failure', ({ payload }) => {
+                    // application config failed to load, emit error and complete the stream
                     subscriber.error(
                         Error('failed to load application config', {
                             cause: payload,
@@ -345,6 +501,7 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
     }
 
     public getConfigAsync(allow_cache = true): Promise<AppConfig> {
+        // when allow_cache is true, use first emitted value, otherwise use last emitted value
         const operator = allow_cache ? firstValueFrom : lastValueFrom;
         return operator(this.getConfig(!allow_cache));
     }
@@ -352,24 +509,34 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
     public getManifest(force_refresh = false): Observable<AppManifest> {
         return new Observable((subscriber) => {
             if (this.#state.value.manifest) {
+                // emit current manifest to the subscriber
                 subscriber.next(this.#state.value.manifest);
                 if (!force_refresh) {
+                    // since we have the manifest and no force refresh, complete the stream
                     return subscriber.complete();
                 }
             }
+            // when stream closes, dispose of subscription to change of state manifest
             subscriber.add(
+                // monitor changes to state changes of manifest and emit to subscriber
                 this.#state.addEffect('set_manifest', ({ payload }) => {
                     subscriber.next(payload);
                 }),
             );
+
+            // when stream closes, dispose of subscription to fetch manifest
             subscriber.add(
+                // monitor success of fetching manifest and emit to subscriber
                 this.#state.addEffect('fetch_manifest::success', ({ payload }) => {
                     subscriber.next(payload);
+                    // application manifest loaded, complete the stream
                     subscriber.complete();
                 }),
             );
             subscriber.add(
+                // monitor failure of fetching manifest and emit error to subscriber
                 this.#state.addEffect('fetch_manifest::failure', ({ payload }) => {
+                    // application manifest failed to load, emit error and complete the stream
                     subscriber.error(
                         Error('failed to load application manifest', {
                             cause: payload,
@@ -378,11 +545,13 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
                 }),
             );
 
+            // fetch the application manifest
             this.loadManifest();
         });
     }
 
     public getManifestAsync(allow_cache = true): Promise<AppManifest> {
+        // when allow_cache is true, use first emitted value, otherwise use last emitted value
         const operator = allow_cache ? firstValueFrom : lastValueFrom;
         return operator(this.getManifest(!allow_cache));
     }
@@ -390,24 +559,37 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
     public getAppModule(force_refresh = false): Observable<AppScriptModule> {
         return new Observable((subscriber) => {
             if (this.#state.value.modules) {
+                // emit current value to the subscriber
                 subscriber.next(this.#state.value.modules);
                 if (!force_refresh) {
+                    // complete if no force refresh
                     return subscriber.complete();
                 }
             }
+
+            // when stream closes, dispose of subscription to change of state modules
             subscriber.add(
+                // monitor changes to state changes of modules and emit to subscriber
                 this.#state.addEffect('set_module', ({ payload }) => {
                     subscriber.next(payload);
                 }),
             );
+
+            // when stream closes, dispose of subscription script load success
             subscriber.add(
+                // monitor success of loading application script and emit to subscriber
                 this.#state.addEffect('import_app::success', ({ payload }) => {
                     subscriber.next(payload);
+                    // application module loaded, complete the stream
                     subscriber.complete();
                 }),
             );
+
+            // when stream closes, dispose of subscription to script load failure
             subscriber.add(
+                // monitor failure of loading application script and emit error to subscriber
                 this.#state.addEffect('import_app::failure', ({ payload }) => {
+                    // application module failed to load, emit error and complete the stream
                     subscriber.error(
                         Error('failed to load application modules from script', {
                             cause: payload,
@@ -416,15 +598,19 @@ export class App<TEnv = any, TModules extends Array<AnyModule> | unknown = unkno
                 }),
             );
 
+            // when stream closes, dispose of subscription to fetch manifest
             subscriber.add(
-                this.getManifest().subscribe((manifest) =>
-                    of(this.#state.next(actions.importApp(manifest.entry))),
-                ),
+                // fetch application latest manifest and request loading of the application script
+                this.getManifest().subscribe((manifest) => {
+                    // dispatch import_app action to load the application script
+                    this.#state.next(actions.importApp(manifest.entry));
+                }),
             );
         });
     }
 
     public getAppModuleAsync(allow_cache = true): Promise<AppScriptModule> {
+        // when allow_cache is true, use first emitted value, otherwise use last emitted value
         const operator = allow_cache ? firstValueFrom : lastValueFrom;
         return operator(this.getAppModule(!allow_cache));
     }

package/src/app/create-reducer.ts

@@ -16,6 +16,7 @@ import { AppBundleState, AppBundleStateInitial } from './types';
 export const createReducer = (value: AppBundleStateInitial) =>
     makeReducer({ ...value, status: new Set() } as AppBundleState, (builder) =>
         builder
+            // update or set manifest
             .addCase(actions.setManifest, (state, action) => {
                 if (action.meta.update) {
                     state.manifest = { ...state.manifest, ...action.payload };
@@ -32,11 +33,11 @@ export const createReducer = (value: AppBundleStateInitial) =>
             .addCase(actions.setInstance, (state, action) => {
                 state.instance = action.payload;
             })
-            /** mark status as loading {{type}} */
+            // add status which indicates that a request is in progress
             .addMatcher(isRequestAction, (state, action) => {
                 state.status.add(actionBaseType(action));
             })
-            /** clear status {{type}} */
+            // remove status when a request is complete
             .addMatcher(isCompleteAction, (state, action) => {
                 state.status.delete(actionBaseType(action));
             }),

package/src/app/create-state.ts

@@ -13,9 +13,18 @@ export const createState = (
     provider: AppModuleProvider,
 ): FlowSubject<AppBundleState, Actions> => {
     const reducer = createReducer(value);
+
+    // create state
     const state = new FlowSubject<AppBundleState, Actions>(reducer);
+
+    // add handler for fetching manifest
     state.addFlow(handleFetchManifest(provider));
+
+    // add handler for fetching config
     state.addFlow(handleFetchConfig(provider));
+
+    // add handler for loading application script
     state.addFlow(handleImportApplication());
+
     return state;
 };