@equinor/fusion-framework-module-app 6.0.3 → 6.1.1

package/src/app/App.ts

@@ -3,6 +3,7 @@ import type {
     AppScriptModule,
     AppManifest,
     AppConfig,
+    AppSettings,
     ConfigEnvironment,
 } from '../types';
 import { FlowSubject, Observable } from '@equinor/fusion-observable';
@@ -10,20 +11,22 @@ import { FlowSubject, Observable } from '@equinor/fusion-observable';
 import type { AppModuleProvider } from '../AppModuleProvider';
 import {
     combineLatest,
-    filter,
-    firstValueFrom,
-    lastValueFrom,
-    map,
     of,
-    OperatorFunction,
+    type OperatorFunction,
     Subscription,
+    firstValueFrom,
+    lastValueFrom,
 } from 'rxjs';
+import { defaultIfEmpty, filter, last, map, switchMap } from 'rxjs/operators';
+
 import { EventModule } from '@equinor/fusion-framework-module-event';
 import { AnyModule, ModuleType } from '@equinor/fusion-framework-module';
 import { createState } from './create-state';
 import { actions, Actions } from './actions';
 import { AppBundleState, AppBundleStateInitial } from './types';
 
+import isEqual from 'fast-deep-equal';
+
 import './events';
 
 // TODO - move globally
@@ -65,6 +68,18 @@ export interface IApp<
      */
     get instance$(): Observable<AppModulesInstance<TModules>>;
 
+    /**
+     * Observable that emits the settings of the app.
+     * @returns An Observable that emits the app settings.
+     */
+    get settings$(): Observable<AppSettings>;
+
+    /**
+     * Observable that emits the status of the app.
+     * @returns An Observable that emits the app status.
+     */
+    get status$(): Observable<AppBundleState['status']>;
+
     /**
      * Gets the current state of the Application.
      * @returns The current state of the Application.
@@ -152,6 +167,56 @@ export interface IApp<
      */
     getConfigAsync(allow_cache?: boolean): Promise<AppConfig>;
 
+    /**
+     * Gets the app settings.
+     * @param force_refresh Whether to force refreshing the settings.
+     * @returns An observable that emits the app settings.
+     */
+    getSettings(force_refresh?: boolean): Observable<AppSettings>;
+
+    /**
+     * Retrieves the app settings asynchronously.
+     * @param allow_cache Whether to allow loading from cache.
+     * @returns A promise that resolves to the AppSettings.
+     */
+    getSettingsAsync(allow_cache?: boolean): Promise<AppSettings>;
+
+    /**
+     * Sets the app settings.
+     * @param settings The settings object to save.
+     * @returns An observable that emits the app settings.
+     */
+    updateSettings<T extends AppSettings>(settings: T): Observable<T>;
+
+    /**
+     * Sets the app settings asyncronously.
+     * @param settings The settings object to save.
+     * @returns An Promise that resolves the app settings.
+     */
+    updateSettingsAsync<T extends AppSettings>(settings: T): Promise<T>;
+
+    /**
+     * Updates a specific setting of the app.
+     * @param property The property to update.
+     * @param value The value to set.
+     * @returns An observable that emits the app settings.
+     */
+    updateSetting<T extends AppSettings, P extends keyof T>(
+        property: P,
+        value: T[P],
+    ): Observable<T[P]>;
+
+    /**
+     * Updates a specific setting of the app asynchronously.
+     * @param property The property to update.
+     * @param value The value to set.
+     * @returns A promise that resolves to the AppSettings.
+     */
+    updateSettingAsync<T extends AppSettings, P extends keyof T>(
+        property: P,
+        value: T[P],
+    ): Promise<T[P]>;
+
     /**
      * Gets the app manifest.
      * @param force_refresh Whether to force refreshing the manifest.
@@ -181,6 +246,8 @@ export interface IApp<
     getAppModuleAsync(allow_cache?: boolean): Promise<AppScriptModule>;
 }
 
+const fallbackSettings: AppSettings = {};
+
 // TODO make streams distinct until changed from state
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class App<
@@ -193,31 +260,39 @@ export class App<
     //#region === streams ===
 
     get manifest$(): Observable<AppManifest> {
-        return this.#state.pipe(
-            map(({ manifest }) => manifest),
-            filterEmpty(),
-        );
+        return this.#state.select((state) => state.manifest).pipe(filterEmpty());
     }
 
     get config$(): Observable<AppConfig<TEnv>> {
-        return this.#state.pipe(
-            map(({ config }) => config as AppConfig<TEnv>),
-            filterEmpty(),
-        );
+        return this.#state
+            .select((state) => state.config as AppConfig<TEnv>, isEqual)
+            .pipe(filterEmpty());
     }
 
     get modules$(): Observable<AppScriptModule> {
-        return this.#state.pipe(
-            map(({ modules }) => modules),
-            filterEmpty(),
-        );
+        return this.#state.select((state) => state.modules).pipe(filterEmpty());
     }
 
     get instance$(): Observable<AppModulesInstance<TModules>> {
-        return this.#state.pipe(
-            map(({ instance }) => instance as AppModulesInstance<TModules>),
-            filterEmpty(),
-        );
+        return this.#state
+            .select((state) => state.instance as AppModulesInstance<TModules>)
+            .pipe(filterEmpty());
+    }
+
+    get settings$(): Observable<AppSettings> {
+        return new Observable<AppSettings>((subscriber) => {
+            this.#state.next(actions.fetchSettings(this.appKey));
+            subscriber.add(
+                this.#state
+                    .select((state) => state.settings, isEqual)
+                    .pipe(filterEmpty(), defaultIfEmpty(fallbackSettings))
+                    .subscribe(subscriber),
+            );
+        });
+    }
+
+    get status$(): Observable<AppBundleState['status']> {
+        return this.#state.select((state) => state.status);
     }
 
     //#endregion
@@ -358,6 +433,60 @@ export class App<
             });
         });
 
+        // monitor when application settings is loading
+        this.#state.addEffect(actions.fetchSettings.type, () => {
+            // dispatch event to notify listeners that the application settings is being loaded
+            event.dispatchEvent('onAppSettingsLoad', {
+                detail: { appKey },
+                source: this,
+            });
+        });
+
+        // monitor when application settings is loaded
+        this.#state.addEffect(actions.fetchSettings.success.type, (action) => {
+            // dispatch event to notify listeners that the application settings has been loaded
+            event.dispatchEvent('onAppSettingsLoaded', {
+                detail: { appKey, settings: action.payload },
+                source: this,
+            });
+        });
+
+        // monitor when application settings fails to load
+        this.#state.addEffect(actions.fetchSettings.failure.type, (action) => {
+            // dispatch event to notify listeners that the application settings failed to load
+            event.dispatchEvent('onAppSettingsFailure', {
+                detail: { appKey, error: action.payload },
+                source: this,
+            });
+        });
+
+        // monitor when application settings is updated
+        this.#state.addEffect(actions.updateSettings.type, (action) => {
+            // dispatch event to notify listeners that the application settings has been loaded
+            event.dispatchEvent('onAppSettingsUpdate', {
+                detail: { appKey, settings: action.payload.settings },
+                source: this,
+            });
+        });
+
+        // monitor when application settings is updated
+        this.#state.addEffect(actions.updateSettings.success.type, (action) => {
+            // dispatch event to notify listeners that the application settings has been loaded
+            event.dispatchEvent('onAppSettingsUpdated', {
+                detail: { appKey, settings: action.payload.settings },
+                source: this,
+            });
+        });
+
+        // monitor when application settings fails to updated
+        this.#state.addEffect(actions.updateSettings.failure.type, (action) => {
+            // dispatch event to notify listeners that the application settings has been loaded
+            event.dispatchEvent('onAppSettingsUpdateFailure', {
+                detail: { appKey, settings: 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
@@ -529,6 +658,123 @@ export class App<
         return operator(this.getConfig(!allow_cache));
     }
 
+    public getSettings<T extends AppSettings>(force_refresh = false): Observable<T> {
+        return new Observable<T>((subscriber) => {
+            if (this.#state.value.settings) {
+                // emit current settings to the subscriber
+                subscriber.next(this.#state.value.settings as T);
+                if (!force_refresh) {
+                    // since we have the settings and no force refresh, complete the stream
+                    return subscriber.complete();
+                }
+            }
+
+            // when stream closes, dispose of subscription to change of state settings
+            subscriber.add(
+                // monitor changes to state changes of settings and emit to subscriber
+                this.#state.addEffect('set_settings', ({ payload }) => {
+                    subscriber.next(payload as T);
+                }),
+            );
+
+            // when stream closes, dispose of subscription to fetch settings
+            subscriber.add(
+                // monitor success of fetching settings and emit to subscriber
+                this.#state.addEffect('fetch_settings::success', ({ payload }) => {
+                    // application settings loaded, emit to subscriber and complete the stream
+                    subscriber.next(payload as T);
+                    subscriber.complete();
+                }),
+            );
+
+            // when stream closes, dispose of subscription to fetch settings
+            subscriber.add(
+                // monitor failure of fetching settings and emit error to subscriber
+                this.#state.addEffect('fetch_settings::failure', ({ payload }) => {
+                    // application settings failed to load, emit error and complete the stream
+                    subscriber.error(
+                        Error('failed to load application settings', {
+                            cause: payload,
+                        }),
+                    );
+                }),
+            );
+
+            this.#state.next(actions.fetchSettings(this.appKey));
+        });
+    }
+
+    public getSettingsAsync<T extends AppSettings>(allow_cache = true): Promise<T> {
+        // when allow_cache is true, use first emitted value, otherwise use last emitted value
+        const operator = allow_cache ? firstValueFrom : lastValueFrom;
+        return operator(this.getSettings<T>(!allow_cache));
+    }
+
+    public updateSettings<T extends AppSettings>(settings: T): Observable<T> {
+        return new Observable((subscriber) => {
+            subscriber.add(
+                // monitor failure of updating settings and emit error to subscriber
+                this.#state.addEffect('update_settings::failure', ({ payload }) => {
+                    // request to reset settings to source state
+                    this.#state.next(actions.fetchSettings(this.appKey));
+
+                    // application settings failed to save, emit error and complete the stream
+                    subscriber.error(
+                        Error('failed to update application settings', {
+                            cause: payload,
+                        }),
+                    );
+                }),
+            );
+
+            subscriber.add(
+                // monitor success of updating settings and emit to subscriber
+                this.#state.addEffect('update_settings::success', ({ payload }) => {
+                    subscriber.next(payload as T);
+                    subscriber.complete();
+                }),
+            );
+
+            // optimistic update of settings
+            this.#state.next(actions.setSettings(settings));
+
+            // request to update settings
+            this.#state.next(actions.updateSettings(this.appKey, settings));
+        });
+    }
+
+    public updateSettingsAsync<T extends AppSettings>(settings: T): Promise<T> {
+        return lastValueFrom(this.updateSettings(settings));
+    }
+
+    public updateSetting<T extends AppSettings, P extends keyof T>(
+        property: P,
+        value: T[P],
+    ): Observable<T[P]> {
+        const currentSettings$ =
+            this.#state.value.settings === undefined
+                ? // if settings are not loaded, fetch settings
+                  this.getSettings().pipe(last())
+                : // if settings are loaded, use current settings
+                  of(this.#state.value.settings);
+
+        return currentSettings$.pipe(
+            // merge current settings with new value
+            map((settings) => ({ ...settings, [property]: value })),
+            // update settings
+            switchMap((settings) => this.updateSettings<T>(settings as T)),
+            // return the updated property
+            map((settings) => settings[property] as T[P]),
+        );
+    }
+
+    public updateSettingAsync<T extends AppSettings, P extends keyof T>(
+        property: P,
+        value: T[P],
+    ): Promise<T[P]> {
+        return lastValueFrom(this.updateSetting<T, P>(property, value));
+    }
+
     public getManifest(force_refresh = false): Observable<AppManifest> {
         return new Observable((subscriber) => {
             if (this.#state.value.manifest) {

package/src/app/actions.ts

@@ -4,7 +4,13 @@ import {
     createAction,
     createAsyncAction,
 } from '@equinor/fusion-observable';
-import type { AppConfig, AppManifest, AppModulesInstance, AppScriptModule } from '../types';
+import type {
+    AppConfig,
+    AppManifest,
+    AppModulesInstance,
+    AppScriptModule,
+    AppSettings,
+} from '../types';
 
 const createActions = () => ({
     /** Manifest loading */
@@ -31,6 +37,33 @@ const createActions = () => ({
         (config: AppConfig) => ({ payload: config }),
         (error: unknown) => ({ payload: error }),
     ),
+    /** Settings loading */
+    setSettings: createAction('set_settings', (settings?: AppSettings) => ({
+        payload: settings,
+    })),
+    /** Fetching settings */
+    fetchSettings: createAsyncAction(
+        'fetch_settings',
+        (appKey: string) => ({ payload: { appKey } }),
+        (settings: AppSettings) => ({ payload: settings }),
+        (error: unknown) => ({ payload: error }),
+    ),
+    /** Updating settings */
+    updateSettings: createAsyncAction(
+        'update_settings',
+        (appKey: string, settings: AppSettings) => ({
+            payload: { appKey, settings },
+        }),
+        (settings: AppSettings) => ({
+            payload: settings,
+        }),
+        (error: unknown) => ({
+            payload: error,
+        }),
+    ),
+    updateSettingsAbort: createAction('update_settings::abort', (id: string) => ({
+        payload: id,
+    })),
     /** App loading */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     setModule: createAction('set_module', (module: any) => ({ payload: module })),

package/src/app/create-reducer.ts

@@ -30,6 +30,9 @@ export const createReducer = (value: AppBundleStateInitial) =>
                 .addCase(actions.setConfig, (state, action) => {
                     state.config = action.payload;
                 })
+                .addCase(actions.setSettings, (state, action) => {
+                    state.settings = action.payload;
+                })
                 .addCase(actions.setModule, (state, action) => {
                     state.modules = action.payload;
                 })

package/src/app/create-state.ts

@@ -2,7 +2,13 @@ import { FlowSubject } from '@equinor/fusion-observable';
 
 import { createReducer } from './create-reducer';
 
-import { handleFetchManifest, handleFetchConfig, handleImportApplication } from './flows';
+import {
+    handleFetchManifest,
+    handleFetchConfig,
+    handleFetchSettings,
+    handleUpdateSettings,
+    handleImportApplication,
+} from './flows';
 
 import type { Actions } from './actions';
 import type { AppBundleState, AppBundleStateInitial } from './types';
@@ -23,6 +29,11 @@ export const createState = (
     // add handler for fetching config
     state.addFlow(handleFetchConfig(provider));
 
+    // add handler for fetching settings
+    state.addFlow(handleFetchSettings(provider));
+
+    state.addFlow(handleUpdateSettings(provider));
+
     // add handler for loading application script
     state.addFlow(handleImportApplication(provider));
 

package/src/app/events.ts

@@ -2,7 +2,13 @@ import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framewo
 
 import type { App } from './App';
 
-import type { AppConfig, AppManifest, AppModulesInstance, AppScriptModule } from '../types';
+import type {
+    AppConfig,
+    AppManifest,
+    AppModulesInstance,
+    AppScriptModule,
+    AppSettings,
+} from '../types';
 
 /** base event type for applications */
 export type AppEventEventInit<TDetail extends Record<string, unknown> | unknown = unknown> =
@@ -45,6 +51,19 @@ declare module '@equinor/fusion-framework-module-event' {
         }>;
         onAppConfigFailure: AppEventFailure;
 
+        onAppSettingsLoad: AppEvent;
+        /** fired when the application has loaded corresponding settings */
+        onAppSettingsLoaded: AppEvent<{
+            settings: AppSettings;
+        }>;
+        onAppSettingsFailure: AppEventFailure;
+
+        onAppSettingsUpdate: AppEvent;
+        onAppSettingsUpdated: AppEvent<{
+            settings: AppSettings;
+        }>;
+        onAppSettingsUpdateFailure: AppEventFailure;
+
         /** fired when the application has loaded corresponding javascript module */
         onAppScriptLoad: AppEvent;
         onAppScriptLoaded: AppEvent<{

package/src/app/flows.ts

@@ -1,5 +1,5 @@
 import { from, of, concat } from 'rxjs';
-import { catchError, filter, last, map, share, switchMap } from 'rxjs/operators';
+import { catchError, concatMap, filter, last, map, share, switchMap } from 'rxjs/operators';
 
 import { actions } from './actions';
 
@@ -93,6 +93,76 @@ export const handleFetchConfig =
             }),
         );
 
+/**
+ * Handles the fetch settings action by fetching the app settings from the provider,
+ * filtering out null values, and dispatching success or failure actions accordingly.
+ *
+ * @param provider The AppModuleProvider used to fetch the app settings.
+ * @returns A Flow function that takes an Observable of actions and returns an Observable of actions.
+ */
+export const handleFetchSettings =
+    (provider: AppModuleProvider): Flow<Actions, AppBundleState> =>
+    (action$) =>
+        action$.pipe(
+            // only handle fetch settings request actions
+            filter(actions.fetchSettings.match),
+            // when request is received, abort any ongoing request and start new
+            switchMap(({ payload }) => {
+                const { appKey } = payload;
+
+                // fetch settings from provider
+                const subject = from(provider.getAppSettings(appKey)).pipe(
+                    // filter out null values
+                    filter((x) => !!x),
+                    // allow multiple subscriptions
+                    share(),
+                );
+
+                // first load settings and then dispatch success action
+                return concat(
+                    subject.pipe(map((settings) => actions.setSettings(settings))),
+                    subject.pipe(
+                        last(),
+                        map((settings) => actions.fetchSettings.success(settings)),
+                    ),
+                ).pipe(
+                    // catch any error and dispatch failure action
+                    catchError((err) => {
+                        return of(actions.fetchSettings.failure(err));
+                    }),
+                );
+            }),
+        );
+
+/**
+ * Handles the set settings action by setting the app settings from the provider,
+ * filtering out null values, and dispatching success or failure actions accordingly.
+ *
+ * @param provider The AppModuleProvider used to fetch the app settings.
+ * @returns A Flow function that takes an Observable of actions and returns an Observable of actions.
+ */
+export const handleUpdateSettings =
+    (provider: AppModuleProvider): Flow<Actions, AppBundleState> =>
+    (action$) => {
+        return action$.pipe(filter(actions.updateSettings.match)).pipe(
+            switchMap(({ payload }) => {
+                const { appKey, settings } = payload;
+                return provider.updateAppSettings(appKey, settings).pipe(
+                    // take the last value
+                    last(),
+                    // request updating of settings and dispatch success action
+                    concatMap((updatedSettings) =>
+                        from([
+                            actions.setSettings(updatedSettings),
+                            actions.updateSettings.success(updatedSettings),
+                        ]),
+                    ),
+                    catchError((err) => of(actions.updateSettings.failure(err))),
+                );
+            }),
+        );
+    };
+
 /**
  * Handles the import application flow.
  * @returns A flow that takes in actions and returns an observable of AppBundleState.

package/src/app/types.ts

@@ -1,10 +1,13 @@
+import { ActionBaseType } from '@equinor/fusion-observable';
 import type {
     AppManifest,
     AppConfig,
     AppModulesInstance,
     AppScriptModule,
     ConfigEnvironment,
+    AppSettings,
 } from '../types';
+import { Actions } from './actions';
 
 /**
  * Represents the state of an application bundle.
@@ -16,6 +19,7 @@ import type {
  * @property {Set<string>} status - A set of strings representing the status of the application.
  * @property {AppManifest} [manifest] - An optional manifest describing the application.
  * @property {AppConfig<TConfig>} [config] - An optional configuration object for the application.
+ * @property {AppSettings} [settings] - An optional application settings object.
  * @property {AppScriptModule} [modules] - An optional script module for the application.
  * @property {AppModulesInstance<TModules>} [instance] - An optional instance of the application modules.
  */
@@ -25,9 +29,10 @@ export type AppBundleState<
     TModules = any,
 > = {
     appKey: string;
-    status: Set<string>;
+    status: Set<ActionBaseType<Actions>>;
     manifest?: AppManifest;
     config?: AppConfig<TConfig>;
+    settings?: AppSettings;
     modules?: AppScriptModule;
     instance?: AppModulesInstance<TModules>;
 };

package/src/errors.ts

@@ -86,6 +86,49 @@ export class AppConfigError extends Error {
     }
 }
 
+/**
+ * Represents an error that occurs while fetching application settings.
+ */
+export class AppSettingsError extends Error {
+    /**
+     * Creates an instance of `AppSettingsError` based on the HTTP response status.
+     * @param response The HTTP response.
+     * @param options Additional error options.
+     * @returns An instance of `AppSettingsError` based on the HTTP response status.
+     */
+    static fromHttpResponse(response: Response, options?: ErrorOptions): AppSettingsError {
+        switch (response.status) {
+            case 401:
+                return new AppSettingsError(
+                    'unauthorized',
+                    'failed to load application settings, request not authorized',
+                    options,
+                );
+            case 404:
+                return new AppSettingsError('not_found', 'application not found', options);
+        }
+        return new AppSettingsError(
+            'unknown',
+            `failed to load application settings, status code ${response.status}`,
+            options,
+        );
+    }
+
+    /**
+     * Creates an instance of `AppSettingsError`.
+     * @param type The type of the application error.
+     * @param message The error message.
+     * @param options Additional error options.
+     */
+    constructor(
+        public readonly type: AppErrorType,
+        message?: string,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
 /**
  * Represents an error that occurs when loading the application script.
  */

package/src/types.ts

@@ -23,6 +23,10 @@ export type AppEnv<TEnv extends ConfigEnvironment = ConfigEnvironment, TProps =
 // TODO: change to module-services when new app service is created
 export type ModuleDeps = [HttpModule, ServiceDiscoveryModule, EventModule];
 
+export interface AppSettings {
+    [key: string]: unknown;
+}
+
 // TODO: remove `report` and `launcher` when legacy apps are removed
 export type AppType = 'standalone' | 'report' | 'launcher' | 'template';
 

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '6.0.3';
+export const version = '6.1.1';