@equinor/fusion-framework-module-context 4.1.0 → 4.1.1

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "4.1.0";
+export declare const version = "4.1.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {

package/src/ContextConfigBuilder.ts

@@ -21,6 +21,8 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
     builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>,
 ) => void | Promise<void>;
 
+// TODO - this should extend the BaseConfigBuilder
+
 export class ContextConfigBuilder<
     TModules extends Array<AnyModule> = [],
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/ContextProvider.ts

@@ -26,35 +26,114 @@ import Query from '@equinor/fusion-query';
  * WARNING: this is an initial out cast.
  * api clients will most probably not be exposed in future!
  */
+/**
+ * Represents a context provider that manages the current context and provides methods for querying and manipulating context items.
+ */
 export interface IContextProvider {
     /** DANGER */
     readonly contextClient: ContextClient;
     /** DANGER */
     readonly queryClient: Query<ContextItem[], QueryContextParameters>;
 
+    // stream of current context
     readonly currentContext$: Observable<ContextItem | null | undefined>;
+
+    // current context of the current state
     currentContext: ContextItem | null | undefined;
+
+    /**
+     * Queries the context items based on the provided search string.
+     * @param search The search string.
+     * @returns An observable that emits an array of context items.
+     */
     queryContext(search: string): Observable<Array<ContextItem>>;
+
+    /**
+     * Queries the context items asynchronously based on the provided search string.
+     * @param search The search string.
+     * @returns A promise that resolves to an array of context items.
+     */
     queryContextAsync(search: string): Promise<Array<ContextItem>>;
+
+    /**
+     * Validates the given context item.
+     * @param item The context item to validate.
+     * @returns A boolean indicating whether the context item is valid or not.
+     */
     validateContext(item: ContextItem<Record<string, unknown>>): boolean;
+
+    /**
+     * Resolves the context item as a stream.
+     * @param current The current context item.
+     * @returns An observable that emits the resolved context item.
+     */
     resolveContext: (current: ContextItem) => Observable<ContextItem>;
+
+    /**
+     * Resolves the context item asynchronously.
+     * @param current The current context item.
+     * @returns A promise that resolves to the resolved context item.
+     */
     resolveContextAsync: (current: ContextItem) => Promise<ContextItem>;
+
+    /**
+     * Retrieves the related context items based on the provided parameters.
+     * @param args The parameters for retrieving related context items.
+     * @returns An observable that emits an array of related context items.
+     */
     relatedContexts: (
         args: RelatedContextParameters,
     ) => Observable<Array<ContextItem<Record<string, unknown>>>>;
+
+    /**
+     * Retrieves the related context items asynchronously based on the provided parameters.
+     * @param args The parameters for retrieving related context items.
+     * @returns A promise that resolves to an array of related context items.
+     */
     relatedContextsAsync: (
         args: RelatedContextParameters,
     ) => Promise<Array<ContextItem<Record<string, unknown>>>>;
+
+    /**
+     * Clears the current context.
+     */
     clearCurrentContext: VoidFunction;
 
+    /**
+     * Sets the current context item by its ID.
+     * @param id The ID of the context item.
+     * @returns An observable that emits the current context item.
+     */
     setCurrentContextById(id: string): Observable<ContextItem<Record<string, unknown>>>;
+
+    /**
+     * Sets the current context item by its ID asynchronously.
+     * @param id The ID of the context item.
+     * @returns A promise that resolves to the current context item.
+     */
     setCurrentContextByIdAsync(id: string): Promise<ContextItem<Record<string, unknown>>>;
 
+    /**
+     * Sets the current context item.
+     * @param context The context item to set as the current context.
+     * @param opt Optional settings for the operation.
+     * @param opt.validate Specifies whether to validate the context item. Default is `true`.
+     * @param opt.resolve Specifies whether to resolve the context item. Default is `true`.
+     * @returns An observable that emits the current context item or `null`.
+     */
     setCurrentContext(
         context: ContextItem<Record<string, unknown>> | null,
         opt?: { validate?: boolean; resolve?: boolean },
     ): Observable<ContextItem<Record<string, unknown>> | null>;
 
+    /**
+     * Sets the current context item asynchronously.
+     * @param context The context item to set as the current context.
+     * @param opt Optional settings for the operation.
+     * @param opt.validate Specifies whether to validate the context item. Default is `true`.
+     * @param opt.resolve Specifies whether to resolve the context item. Default is `true`.
+     * @returns A promise that resolves to the current context item or `null`.
+     */
     setCurrentContextAsync(
         context: ContextItem<Record<string, unknown>> | null,
         opt?: { validate?: boolean; resolve?: boolean },
@@ -72,7 +151,7 @@ export class ContextProvider implements IContextProvider {
 
     #contextType?: ContextModuleConfig['contextType'];
     #contextFilter: ContextModuleConfig['contextFilter'];
-    #contextParameterFn: Required<ContextModuleConfig['contextParameterFn']>;
+    #contextParameterFn: Required<ContextModuleConfig>['contextParameterFn'];
 
     #contextQueue = new Subject<Observable<ContextItem<Record<string, unknown>>>>();
 
@@ -122,12 +201,14 @@ export class ContextProvider implements IContextProvider {
 
         this.#event = event;
 
+        // set the resolve and validate context functions
         config.resolveContext && (this.resolveContext = config.resolveContext?.bind(this));
         config.validateContext && (this.validateContext = config.validateContext?.bind(this));
 
         this.#contextType = config.contextType;
         this.#contextFilter = config.contextFilter;
 
+        // create clients
         this.#contextClient = new ContextClient(config.client.get);
         this.#contextQuery = new Query(config.client.query);
 
@@ -135,27 +216,36 @@ export class ContextProvider implements IContextProvider {
             this.#contextRelated = new Query(config.client.related);
         }
 
+        // set the context parameter function
         this.#contextParameterFn =
             config.contextParameterFn ??
+            // fallback to default
             ((args: Parameters<Required<ContextModuleConfig>['contextParameterFn']>[0]) => ({
                 search: args.search,
                 filter: { type: args.type },
             }));
 
+        // if event module is available, setup event listeners
         if (this.#event) {
             this.#subscriptions.add(
-                this.currentContext$.pipe(pairwise()).subscribe(([previous, next]) => {
-                    this.#event?.dispatchEvent('onCurrentContextChanged', {
-                        source: this,
-                        canBubble: true,
-                        detail: { previous, next },
-                    });
-                }),
+                // observe current context changes
+                this.currentContext$
+                    .pipe(
+                        // emit previous and next context
+                        pairwise(),
+                    )
+                    .subscribe(([previous, next]) => {
+                        this.#event?.dispatchEvent('onCurrentContextChanged', {
+                            source: this,
+                            canBubble: true,
+                            detail: { previous, next },
+                        });
+                    }),
             );
             this.#subscriptions.add(
-                /** observe event from child modules */
+                // observe current context changes from child modules
                 this.#event.addEventListener('onCurrentContextChanged', (e) => {
-                    /** loop prevention */
+                    // prevent infinite loop, only set context if source is not this
                     if (e.source !== this && e.detail.next !== undefined) {
                         this.setCurrentContext(e.detail.next);
                     }
@@ -163,13 +253,18 @@ export class ContextProvider implements IContextProvider {
             );
         }
 
+        // wire up context queue
         this.#subscriptions.add(
             this.#contextQueue
                 .pipe(
+                    // resolve context item from queue
                     switchMap((next) => next),
                     tap((x) => console.debug('ContextProvider::#contextQueue', x)),
                 )
-                .subscribe((context) => this.#contextClient.setCurrentContext(context ?? null)),
+                .subscribe((context) => {
+                    // set context from resolved context item from queue
+                    this.#contextClient.setCurrentContext(context ?? null);
+                }),
         );
     }
 
@@ -181,6 +276,8 @@ export class ContextProvider implements IContextProvider {
             // do not set context if parent has not initialized
             filter((x): x is ContextItem | null => x !== undefined),
             filter((next, index) => {
+                // skip first item if opt.skipFirst is true
+                // TODO: this is a bit hacky, should be handled in a better way
                 if (opt?.skipFirst && index <= 1) {
                     console.debug(
                         'ContextProvider::connectParentContext',
@@ -189,24 +286,29 @@ export class ContextProvider implements IContextProvider {
                     );
                     return false;
                 }
+                // only set context if it has changed
                 return this.currentContext?.id !== next?.id;
             }),
             switchMap(async (next) => {
-                if (next) {
-                    const onParentContextChanged = await this.#event?.dispatchEvent(
-                        'onParentContextChanged',
-                        {
-                            source: this,
-                            detail: next,
-                            cancelable: true,
-                        },
-                    );
-                    return { next, canceled: onParentContextChanged?.canceled };
+                if (!next) {
+                    // if parent context is null, just return
+                    return { next };
                 }
-                return { next };
+                // notify event observers that parent context is about to change and await for cancelation
+                const onParentContextChanged = await this.#event?.dispatchEvent(
+                    'onParentContextChanged',
+                    {
+                        source: this,
+                        detail: next,
+                        cancelable: true,
+                    },
+                );
+                return { next, canceled: onParentContextChanged?.canceled };
             }),
+            // filter out canceled context changes
             filter((x) => !x.canceled),
             switchMap(({ next }) => {
+                // set current context with validation and resolution
                 return this.setCurrentContext(next, {
                     validate: true,
                     resolve: true,
@@ -217,17 +319,22 @@ export class ContextProvider implements IContextProvider {
                             'setCurrentContext',
                             err,
                         );
+                        // do not emit any value if an error occurs
                         return EMPTY;
                     }),
                 );
             }),
             catchError((err) => {
                 console.warn('ContextProvider::onParentContextChanged', 'unhandled exception', err);
+                // do not emit any value if an error occurs
                 return EMPTY;
             }),
         );
 
+        // subscribe to parent context changes
         const subscription = parentContext$.subscribe();
+
+        // add subscription to internal teardown
         this.#subscriptions.add(subscription);
         return subscription;
     }
@@ -236,19 +343,24 @@ export class ContextProvider implements IContextProvider {
         return new Observable((subscriber) => {
             try {
                 this.#contextClient
+                    // resolve context item by id
                     .resolveContext(id)
                     .pipe(
+                        // filter out invalid context items
                         filter((item): item is ContextItem => !!item),
+                        // set current context with validation and resolution
                         switchMap((item) => this.setCurrentContext(item)),
                     )
                     .subscribe(subscriber);
             } catch (err) {
+                // catch any unhandled exceptions and emit error
                 subscriber.error(err);
             }
         });
     }
 
     public setCurrentContextByIdAsync(id: string): Promise<ContextItem<Record<string, unknown>>> {
+        // return last value from observable
         return lastValueFrom(this.setCurrentContextById(id));
     }
 
@@ -267,33 +379,33 @@ export class ContextProvider implements IContextProvider {
         context: T,
         opt?: { validate?: boolean; resolve?: boolean },
     ): Observable<T> {
-        /** signal for aborting the queue entry */
+        // signal for aborting the queue entry
         const abort$ = new Subject();
 
-        /** wrapper for returning an observable to the caller */
+        // wrapper for returning an observable to the caller
         const subject$ = new Subject<T>();
 
         const task$ = this._setCurrentContext(context, opt).pipe(
-            /** send context item which was set to the caller */
+            // send context item which was set to the caller
             tap((x) => subject$.next(x)),
-            /** abort task on signal */
+            // abort task on signal
             takeUntil(abort$),
-            /** close observable sent to caller */
+            // close the observable sent to the caller
             finalize(() => subject$.complete()),
-            /** catch errors to not stall queue  */
+            // catch any unhandled exceptions to not stall the queue
             catchError((err) => {
-                /** send the error to the caller  */
+                // emit error to caller
                 subject$.error(err);
-                /** skip setting any context */
+                // skip setting any context
                 return EMPTY;
             }),
         );
 
-        /** add task to internal queue */
+        // add task to internal queue
         this.#contextQueue.next(task$ as Observable<ContextItem<Record<string, unknown>>>);
 
         return subject$.pipe(
-            /** if caller subscribes, unsubscribe should abort queue entry */
+            // if caller subscribes, unsubscribe should abort queue entry
             finalize(() => abort$.next(true)),
         );
     }
@@ -303,24 +415,29 @@ export class ContextProvider implements IContextProvider {
         opt?: { validate?: boolean; resolve?: boolean },
     ): Observable<T> {
         return new Observable((subscriber) => {
+            // if context is the same as current, just emit and complete
             if (context === this.currentContext) {
                 subscriber.next(context);
                 return subscriber.complete();
             }
+            // check if context is provided and should be validated
             if (context && opt?.validate && !this.validateContext(context)) {
+                // check if the resolve context is provided
                 if (!opt.resolve) {
-                    /** cannot resolve context, and provided is invalid  */
+                    // notify event observers that context validation failed since resolve is not provided
                     this.#event?.dispatchEvent('onSetContextValidationFailed', {
                         source: this,
                         detail: { context },
                     });
+                    // emit error and complete
                     return subscriber.error(Error('failed to validate provided context'));
                 }
                 if (opt.resolve) {
                     return of(context)
                         .pipe(
-                            /** notify event observers that context is about to get resolved */
+                            // notify event observers that context is about to get resolved
                             switchMap(async (context) => {
+                                // wait for event listeners to handle the event
                                 const event = await this.#event?.dispatchEvent(
                                     'onSetContextResolve',
                                     {
@@ -329,12 +446,13 @@ export class ContextProvider implements IContextProvider {
                                         detail: { context },
                                     },
                                 );
+                                // check if event was canceled and abort if so
                                 if (event?.canceled) {
                                     throw Error('resolving of context was canceled');
                                 }
                                 return context;
                             }),
-                            /** execute resolve */
+                            // resolve context
                             switchMap((context) =>
                                 this.resolveContext(context).pipe(
                                     map((resolved) => ({
@@ -343,8 +461,9 @@ export class ContextProvider implements IContextProvider {
                                     })),
                                 ),
                             ),
-                            /** notify event observers that context was resolved */
+                            // notify event listeners that context was resolved
                             switchMap(async ({ context, resolved }) => {
+                                // wait for event listeners to handle the event
                                 const event = await this.#event?.dispatchEvent(
                                     'onSetContextResolved',
                                     {
@@ -353,12 +472,13 @@ export class ContextProvider implements IContextProvider {
                                         detail: { context, resolved },
                                     },
                                 );
+                                // check if event was canceled and abort if so
                                 if (event?.canceled) {
                                     throw Error('resolving of context was canceled');
                                 }
                                 return resolved;
                             }),
-                            /** recursive set current context without validation and resolve */
+                            // recursive call to set current context without validation and resolution
                             switchMap((resolved) =>
                                 this._setCurrentContext(resolved as unknown as T),
                             ),
@@ -367,8 +487,10 @@ export class ContextProvider implements IContextProvider {
                 }
             }
 
+            // make the context an observable
             return of(context)
                 .pipe(
+                    // alert event listeners that context is about to change
                     switchMap(async (context) => {
                         const event = await this.#event?.dispatchEvent('onCurrentContextChange', {
                             source: this,
@@ -377,6 +499,7 @@ export class ContextProvider implements IContextProvider {
                             detail: { context: context },
                         });
 
+                        // check if event was canceled and abort if so
                         if (event?.canceled) {
                             throw Error('change of context was aborted');
                         }
@@ -385,7 +508,9 @@ export class ContextProvider implements IContextProvider {
                     }),
                 )
                 .subscribe((context) => {
+                    // emit context to the caller
                     subscriber.next(context);
+                    // only take the first value and complete
                     subscriber.complete();
                 });
         });
@@ -401,13 +526,15 @@ export class ContextProvider implements IContextProvider {
     public queryContext(search: string): Observable<Array<ContextItem>> {
         const query$ = this.queryClient
             .query(
-                // TODO
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                /* @ts-ignore */
-                this.#contextParameterFn({ search, type: this.#contextType }),
+                // generate query parameters
+                this.#contextParameterFn({
+                    search,
+                    type: this.#contextType,
+                }) as QueryContextParameters,
             )
             .pipe(
                 catchError((err) => {
+                    // if query client throws a QueryClientError, extract the cause and throw it
                     if (err.name === 'QueryClientError') {
                         throw err.cause;
                     }
@@ -416,6 +543,7 @@ export class ContextProvider implements IContextProvider {
                 map((x) => x.value),
             );
 
+        // apply context filter if available
         return this.#contextFilter ? query$.pipe(map(this.#contextFilter)) : query$;
     }
 
@@ -431,13 +559,20 @@ export class ContextProvider implements IContextProvider {
     public resolveContext(
         item: ContextItem<Record<string, unknown>>,
     ): Observable<ContextItem<Record<string, unknown>>> {
+        // request related context items for the given context item with the same context type which the provider is configured with
         return this.relatedContexts({ item, filter: { type: this.#contextType } }).pipe(
+            // filter out invalid context items
             map((x) => x.filter((item) => this.validateContext(item))),
             map((values) => {
+                // related context should be resolved to a single context item
                 const value = values.shift();
+
+                // if no value is found, throw an error
                 if (!value) {
                     throw Error('failed to resolve context');
                 }
+
+                // if multiple items are found, log a warning
                 if (values.length) {
                     console.warn(
                         'ContextProvider::relatedContext',
@@ -445,6 +580,8 @@ export class ContextProvider implements IContextProvider {
                         values,
                     );
                 }
+
+                // return the resolved context item
                 return value;
             }),
         );
@@ -459,6 +596,7 @@ export class ContextProvider implements IContextProvider {
     public relatedContexts(
         args: RelatedContextParameters,
     ): Observable<Array<ContextItem<Record<string, unknown>>>> {
+        // check if related context client is available
         if (!this.#contextRelated) {
             return throwError(() =>
                 Error(
@@ -466,6 +604,8 @@ export class ContextProvider implements IContextProvider {
                 ),
             );
         }
+
+        // request related context items
         return this.#contextRelated.query(args).pipe(
             map(({ value }) => value),
             catchError((err) => {
@@ -497,7 +637,7 @@ export default ContextProvider;
 
 declare module '@equinor/fusion-framework-module-event' {
     interface FrameworkEventMap {
-        /** dispatch before context changes */
+        // event which is dispatched before the context changes
         onCurrentContextChange: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -506,7 +646,7 @@ declare module '@equinor/fusion-framework-module-event' {
                 IContextProvider
             >
         >;
-        /** dispatch after context changed */
+        // event which is dispatched after the context changes
         onCurrentContextChanged: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -516,6 +656,8 @@ declare module '@equinor/fusion-framework-module-event' {
                 IContextProvider
             >
         >;
+
+        // event which is dispatched before the parent context changes
         onParentContextChanged: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -525,6 +667,7 @@ declare module '@equinor/fusion-framework-module-event' {
             >
         >;
 
+        // event which is dispatched before the context will be resolved
         onSetContextResolve: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -533,6 +676,8 @@ declare module '@equinor/fusion-framework-module-event' {
                 IContextProvider
             >
         >;
+
+        // event which is dispatched after the context was resolved
         onSetContextResolved: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -542,6 +687,8 @@ declare module '@equinor/fusion-framework-module-event' {
                 IContextProvider
             >
         >;
+
+        // event which is dispatched if the context validation failed
         onSetContextValidationFailed: FrameworkEvent<
             FrameworkEventInit<
                 {
@@ -550,6 +697,8 @@ declare module '@equinor/fusion-framework-module-event' {
                 IContextProvider
             >
         >;
+
+        // event which is dispatched if the context resolve failed
         onSetContextResolveFailed: FrameworkEvent<
             FrameworkEventInit<
                 {

package/src/errors.ts

@@ -1,17 +1,37 @@
+/**
+ * Represents an error that occurs during a search in the Fusion Context.
+ */
 export class FusionContextSearchError extends Error {
     #details;
 
+    /**
+     * The title of the error.
+     */
     get title(): string {
         return this.#details.title;
     }
 
+    /**
+     * The description of the error, if available.
+     */
     get description(): string | undefined {
         return this.#details.description;
     }
 
+    /**
+     * Creates a new instance of FusionContextSearchError.
+     * @param details - The details of the error.
+     * @param options - Optional parameters for the error.
+     */
     constructor(
         details: {
+            /**
+             * The title of the error.
+             */
             title: string;
+            /**
+             * The description of the error, if available.
+             */
             description?: string;
         },
         options?: ErrorOptions,