@equinor/fusion-framework-module-context 7.0.4-next.0 → 8.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "7.0.4-next.0",
+  "version": "8.0.1",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {
@@ -9,8 +9,8 @@
       "types": "./dist/types/index.d.ts"
     },
     "./errors.js": {
-      "import": "./dist/esm/errors.js",
-      "types": "./dist/types/errors.d.ts"
+      "import": "./dist/esm/errors/index.js",
+      "types": "./dist/types/errors/index.d.ts"
     },
     "./utils": {
       "import": "./dist/esm/utils/index.js",
@@ -25,7 +25,7 @@
         "dist/types/index.d.ts"
       ],
       "errors.js": [
-        "dist/types/errors.d.ts"
+        "dist/types/errors/index.d.ts"
       ],
       "utils": [
         "dist/types/utils/index.d.ts"
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@equinor/fusion-query": "^6.0.5-next.0"
+    "@equinor/fusion-query": "^7.0.2"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-framework-module-event": "^5.0.2-next.0",
-    "@equinor/fusion-framework-module-navigation": "^7.0.0-next.2",
-    "@equinor/fusion-framework-module-services": "^7.2.2-next.0"
+    "typescript": "^7.0.2",
+    "@equinor/fusion-framework-module-navigation": "^7.0.5",
+    "@equinor/fusion-framework-module": "^6.1.1",
+    "@equinor/fusion-framework-module-services": "^8.0.2",
+    "@equinor/fusion-framework-module-event": "^6.0.1"
   },
   "peerDependencies": {
-    "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0"
+    "rxjs": "^7.0.0",
+    "@equinor/fusion-framework-module": "^6.1.1"
   },
   "scripts": {
     "build": "tsc -b"

package/src/ContextConfigBuilder.ts

@@ -17,6 +17,14 @@ import type {
 
 import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
 
+/**
+ * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
+ *
+ * Receives a {@link ContextConfigBuilder} and may use its setter methods
+ * to populate the context module configuration. The callback may be async.
+ *
+ * @typeParam TDeps - Module dependency array inferred from the configurator.
+ */
 export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>(
   builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>,
 ) => void | Promise<void>;
@@ -44,19 +52,25 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
  * - The builder pattern allows chaining configuration methods for clarity and convenience.
  * - The `requireInstance` method enables asynchronous retrieval of module instances by name.
  *
- * @todo - this should extend the BaseConfigBuilder
+ * @todo(#5120) - this should extend the BaseConfigBuilder
  *
  * @see ContextModuleConfig
  * @see ModuleInitializerArgs
  */
 export class ContextConfigBuilder<
   TModules extends Array<AnyModule> = [],
+  // biome-ignore lint/suspicious/noExplicitAny: `ModuleInitializerArgs<any, any>` widens the constraint to accept initializer args for any configurator/module set \u2014 `unknown` breaks assignability of the concrete default type argument
   TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<
     ContextModuleConfigurator,
     TModules
   >,
 > {
   #init: TInit;
+  /**
+   * Creates a new `ContextConfigBuilder`.
+   * @param init - Module initializer arguments used to resolve module instances.
+   * @param config - The partial context module config to build upon.
+   */
   constructor(
     init: TInit,
     public config: Partial<ContextModuleConfig> = {},
@@ -64,13 +78,31 @@ export class ContextConfigBuilder<
     this.#init = init;
   }
 
+  /**
+   * Requires a module instance by its registered key.
+   * @param module - The key of the module to resolve.
+   * @returns A promise that resolves to the requested module instance.
+   */
   requireInstance<TKey extends string = Extract<keyof Modules, string>>(
     module: TKey,
   ): Promise<ModuleType<Modules[TKey]>>;
 
+  /**
+   * Requires a module instance by name.
+   * @param module - The name of the module to resolve.
+   * @returns A promise that resolves to the requested module instance.
+   */
   requireInstance<T>(module: string): Promise<T>;
 
-  requireInstance(module: string): Promise<any> {
+  /**
+   * Requires a module instance by key or name.
+   * @param module - The key or name of the module to resolve.
+   * @returns A promise that resolves to the requested module instance.
+   */
+  requireInstance(
+    module: string,
+    // biome-ignore lint/suspicious/noExplicitAny: implementation signature must satisfy both overloads above (`Promise<ModuleType<...>>` and `Promise<T>`); `unknown` is not assignable to the generic `Promise<T>` overload
+  ): Promise<any> {
     return this.#init.requireInstance(module);
   }
 
@@ -147,6 +179,13 @@ export class ContextConfigBuilder<
     this.config.generatePathFromContext = fn;
   }
 
+  /**
+   * Sets the function used to resolve the initial context during module post-initialization.
+   *
+   * @param fn - A function that returns an observable input emitting the initial context item.
+   *             The default resolver extracts a context ID from the navigation path, falling
+   *             back to the parent provider's current context.
+   */
   setResolveInitialContext(fn: ContextModuleConfig['resolveInitialContext']) {
     this.config.resolveInitialContext = fn;
   }
@@ -177,7 +216,7 @@ export class ContextConfigBuilder<
     },
     expire = 1 * 60 * 1000,
   ): void {
-    this.config.client = {
+    const clientConfig: ContextModuleConfig['client'] = {
       get:
         typeof client.get === 'function'
           ? {
@@ -191,7 +230,7 @@ export class ContextConfigBuilder<
       query:
         typeof client.query === 'function'
           ? {
-              // TODO - might cast to checksum
+              // TODO(#5118) - might cast to checksum
               key: (args) => JSON.stringify(args),
               client: {
                 fn: client.query,
@@ -200,12 +239,13 @@ export class ContextConfigBuilder<
             }
           : client.query,
     };
+    this.config.client = clientConfig;
+    // only override the related-context client config if one was provided
     if (client.related) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      this.config.client!.related =
+      clientConfig.related =
         typeof client.related === 'function'
           ? {
-              // TODO - might cast to checksum
+              // TODO(#5118) - might cast to checksum
               key: (args) => JSON.stringify(args),
               client: {
                 fn: client.related,

package/src/ContextProvider.ts

@@ -346,35 +346,64 @@ export class ContextProvider
 
   #contextQueue = new Subject<Observable<ContextItem<Record<string, unknown>>>>();
 
+  /**
+   * The underlying context client used to resolve and hold the current context item.
+   * @returns The internal {@link ContextClient} instance.
+   */
   public get contextClient() {
     return this.#contextClient;
   }
 
+  /**
+   * The query client used to search for context items.
+   * @returns The internal `Query` instance used by {@link queryContext}.
+   */
   public get queryClient() {
     return this.#contextQuery;
   }
 
+  /**
+   * Observable stream emitting the current context item.
+   * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
+   */
   get currentContext$(): Observable<ContextItem | null | undefined> {
     return this.#contextClient.currentContext$;
   }
 
+  /**
+   * Snapshot of the current context item.
+   * @returns The current `ContextItem`, or `null`/`undefined` if not set.
+   */
   get currentContext(): ContextItem | undefined | null {
     return this.#contextClient.currentContext;
   }
 
-  /** @deprecated do not use, will be removed */
+  /**
+   * Sets the current context item.
+   * @deprecated do not use, will be removed
+   * @param context - The context item to set as current. Must not be `undefined`.
+   * @throws Error if `context` is `undefined`.
+   */
   set currentContext(context: ContextItem | null | undefined) {
     console.warn(
       '@deprecated',
       'ContextProvider.currentContext',
       'use setCurrentContextById|setCurrentContext|clearCurrentContext',
     );
+    // undefined is reserved to mean "not yet initialized", so it cannot be set explicitly
     if (context === undefined) {
       throw Error('not allowed to set current context as undefined undefined!');
     }
     this.setCurrentContextAsync(context);
   }
 
+  /**
+   * Creates a new instance of `ContextProvider`.
+   * @param args - Constructor arguments.
+   * @param args.config - The context module configuration.
+   * @param args.event - Optional event module instance for dispatching context change events.
+   * @param args.parentContext - Optional parent context provider. Deprecated, use {@link connectParentContext}.
+   */
   constructor(args: {
     config: ContextModuleConfig;
     event?: ModuleType<EventModule>;
@@ -385,6 +414,7 @@ export class ContextProvider
 
     super({ version, config });
 
+    // warn about deprecated parentContext constructor arg
     if (args.parentContext) {
       console.warn(
         '@deprecated',
@@ -398,16 +428,19 @@ export class ContextProvider
     if (config.resolveContext) {
       this.resolveContext = config.resolveContext?.bind(this);
     }
+    // override validateContext if configured
     if (config.validateContext) {
       this.validateContext = config.validateContext?.bind(this);
     }
 
+    // override extractContextIdFromPath if configured
     if (config.extractContextIdFromPath) {
-      // @ts-ignore
+      // @ts-expect-error
       this.extractContextIdFromPath = config.extractContextIdFromPath;
     }
+    // override generatePathFromContext if configured
     if (config.generatePathFromContext) {
-      // @ts-ignore
+      // @ts-expect-error
       this.generatePathFromContext = config.generatePathFromContext;
     }
 
@@ -418,6 +451,7 @@ export class ContextProvider
     this.#contextClient = new ContextClient(config.client.get);
     this.#contextQuery = new Query(config.client.query);
 
+    // only create the related-context query when the config provides one
     if (config.client.related) {
       this.#contextRelated = new Query(config.client.related);
     }
@@ -436,10 +470,8 @@ export class ContextProvider
       this.#subscriptions.add(
         // observe current context changes
         this.currentContext$
-          .pipe(
-            // emit previous and next context
-            pairwise(),
-          )
+          // emit previous and next context together for change comparisons
+          .pipe(pairwise())
           .subscribe(([previous, next]) => {
             this.#event?.dispatchEvent('onCurrentContextChanged', {
               source: this,
@@ -494,12 +526,13 @@ export class ContextProvider
     provider: IContextProvider,
     opt?: { skipFirst: boolean },
   ): Subscription {
+    // build a stream of validated context changes from the parent provider
     const parentContext$ = provider.currentContext$.pipe(
       // 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
+        // TODO(#5121): this is a bit hacky, should be handled in a better way
         if (opt?.skipFirst && index <= 1) {
           console.debug('ContextProvider::connectParentContext', 'skipping first item', next);
           return false;
@@ -508,8 +541,8 @@ export class ContextProvider
         return this.currentContext?.id !== next?.id;
       }),
       switchMap(async (next) => {
+        // if parent context is null, just return
         if (!next) {
-          // if parent context is null, just return
           return { next };
         }
         // notify event observers that parent context is about to change and await for cancelation
@@ -524,15 +557,19 @@ export class ContextProvider
       filter((x) => !x.canceled),
       switchMap(({ next }) => {
         // set current context with validation and resolution
-        return this.setCurrentContext(next, {
-          validate: true,
-          resolve: true,
-        }).pipe(
-          catchError((err) => {
-            console.warn('ContextProvider::onParentContextChanged', 'setCurrentContext', err);
-            // do not emit any value if an error occurs
-            return EMPTY;
-          }),
+        return (
+          this.setCurrentContext(next, {
+            validate: true,
+            resolve: true,
+          })
+            // swallow errors so a failed context change doesn't break the parent subscription
+            .pipe(
+              catchError((err) => {
+                console.warn('ContextProvider::onParentContextChanged', 'setCurrentContext', err);
+                // do not emit any value if an error occurs
+                return EMPTY;
+              }),
+            )
         );
       }),
       catchError((err) => {
@@ -568,6 +605,7 @@ export class ContextProvider
         this.#contextClient
           // resolve context item by id
           .resolveContext(id)
+          // filter out invalid items and set as current context
           .pipe(
             // filter out invalid context items
             filter((item): item is ContextItem => !!item),
@@ -609,6 +647,11 @@ export class ContextProvider
    * If the observable is subscribe, unsubscribing __WILL__ abort the task and remove it from queue
    *
    * @param context context item which would be queue to set as current
+   * @param opt Optional settings.
+   * @param opt.validate Whether to validate the context item before setting it.
+   * @param opt.resolve Whether to attempt to resolve the context item if validation fails.
+   * @template T The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+   * @returns An observable that emits the context item once the queued task completes.
    */
   public setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(
     context: T,
@@ -620,6 +663,7 @@ export class ContextProvider
     // wrapper for returning an observable to the caller
     const subject$ = new Subject<T>();
 
+    // run the actual context-setting logic and relay results/errors to the caller's subject
     const task$ = this._setCurrentContext(context, opt).pipe(
       // send context item which was set to the caller
       tap((x) => subject$.next(x)),
@@ -639,6 +683,7 @@ export class ContextProvider
     // add task to internal queue
     this.#contextQueue.next(task$ as Observable<ContextItem<Record<string, unknown>>>);
 
+    // tear down the queued task if the caller unsubscribes
     return subject$.pipe(
       // if caller subscribes, unsubscribe should abort queue entry
       finalize(() => abort$.next(true)),
@@ -674,7 +719,7 @@ export class ContextProvider
    *    - Emit the context and complete the observable.
    *
    * @protected
-   * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+   * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
    * @param context - The new context to set.
    * @param opt - Optional settings:
    *   - `validate`: Whether to validate the context before setting.
@@ -708,7 +753,10 @@ export class ContextProvider
           // emit error and complete
           return subscriber.error(Error('failed to validate provided context'));
         }
+        // if resolve is enabled, attempt to resolve the invalid context before setting it
         if (opt.resolve) {
+          // the recursive `_setCurrentContext` call below is re-entered with the already
+          // validated/resolved context, so the generic `T` cast is safe here.
           return of(context)
             .pipe(
               // notify event observers that context is about to get resolved
@@ -727,6 +775,7 @@ export class ContextProvider
               }),
               // resolve context
               switchMap((context) =>
+                // Pair the resolved context alongside the original for downstream consumers.
                 this.resolveContext(context).pipe(
                   map((resolved) => ({
                     context,
@@ -789,7 +838,7 @@ export class ContextProvider
    *
    * @see {@link setCurrentContext} for more details.
    *
-   * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+   * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
    * @param context - The context item to set as the current context, or `null` to clear it.
    * @param opt - Optional settings for context handling.
    * @param opt.validate - If `true`, validates the context before setting it.
@@ -813,6 +862,7 @@ export class ContextProvider
    *
    * @param search - The search string to filter context items.
    * @returns An Observable that emits an array of `ContextItem` objects matching the search criteria.
+   * @throws Re-throws the underlying cause of a `QueryClientError`, otherwise re-throws the original error.
    */
   public queryContext(search: string): Observable<Array<ContextItem>> {
     const query$ = this.queryClient
@@ -823,6 +873,7 @@ export class ContextProvider
           type: this.#contextType,
         }) as QueryContextParameters,
       )
+      // unwrap query-client errors and expose the underlying cause to subscribers
       .pipe(
         catchError((err) => {
           // if query client throws a QueryClientError, extract the cause and throw it
@@ -857,7 +908,9 @@ export class ContextProvider
    * @returns `true` if the context type is not set or if the item's type ID matches one of the allowed types (case-insensitive); otherwise, `false`.
    */
   public validateContext(item: ContextItem<Record<string, unknown>>): boolean {
+    // no context type configured means every context item is considered valid
     if (!this.#contextType) return true;
+    // normalize allowed types for a case-insensitive comparison
     return this.#contextType.map((x) => x.toLowerCase()).includes(item.type.id.toLowerCase());
   }
 
@@ -881,7 +934,10 @@ export class ContextProvider
     // 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((x) =>
+        // keep only context items that validate against the provider's context type
+        x.filter((item) => this.validateContext(item)),
+      ),
       map((values) => {
         // related context should be resolved to a single context item
         const value = values.shift();
@@ -941,6 +997,7 @@ export class ContextProvider
     return this.#contextRelated.query(args).pipe(
       map(({ value }) => value),
       catchError((err) => {
+        // unwrap the underlying cause so callers see the original error
         if (err.cause) {
           throw err.cause;
         }
@@ -989,7 +1046,12 @@ export default ContextProvider;
 
 declare module '@equinor/fusion-framework-module-event' {
   interface FrameworkEventMap {
-    // event which is dispatched before the context changes
+    /**
+     * Dispatched **before** the current context is changed.
+     *
+     * The event is cancelable — calling `event.preventDefault()` in a
+     * listener will abort the context change.
+     */
     onCurrentContextChange: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -998,7 +1060,12 @@ declare module '@equinor/fusion-framework-module-event' {
         IContextProvider
       >
     >;
-    // event which is dispatched after the context changes
+    /**
+     * Dispatched **after** the current context has changed.
+     *
+     * Contains both the previous and next context items, enabling
+     * listeners to react to transitions.
+     */
     onCurrentContextChanged: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1009,7 +1076,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched before the parent context changes
+    /**
+     * Dispatched **before** a parent context change is applied locally.
+     *
+     * Cancelable — prevents the parent context from being mirrored into
+     * this provider.
+     */
     onParentContextChanged: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1019,7 +1091,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched before the context will be resolved
+    /**
+     * Dispatched **before** context resolution begins (when validation
+     * fails and the caller requested resolution).
+     *
+     * Cancelable — aborting prevents the resolution attempt.
+     */
     onSetContextResolve: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1029,7 +1106,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched after the context was resolved
+    /**
+     * Dispatched **after** the context has been resolved to a new item.
+     *
+     * Cancelable — aborting prevents the resolved item from being
+     * set as the current context.
+     */
     onSetContextResolved: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1040,7 +1122,10 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched if the context validation failed
+    /**
+     * Dispatched when context validation fails and resolution is not
+     * enabled.
+     */
     onSetContextValidationFailed: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1050,7 +1135,9 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched if the context resolve failed
+    /**
+     * Dispatched when context resolution fails with an error.
+     */
     onSetContextResolveFailed: FrameworkEvent<
       FrameworkEventInit<
         {

package/src/client/ContextClient.ts

@@ -25,7 +25,7 @@ export type GetContextParameters = { id: string };
  * @template ContextItem The type of the context item managed by the client.
  * @extends Observable<ContextItem | null | undefined>
  *
- * @todo - should this have `undefined` as a valid value?
+ * @todo(#5116) - should this have `undefined` as a valid value?
  *
  * @example
  * ```typescript
@@ -70,6 +70,10 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
     return this.#client;
   }
 
+  /**
+   * Creates a new `ContextClient`.
+   * @param options - Query constructor options used to fetch a `ContextItem` by its ID.
+   */
   constructor(options: QueryCtorOptions<ContextItem, GetContextParameters>) {
     super((observer) => this.#currentContext$.subscribe(observer));
     this.#client = new Query(options);
@@ -85,10 +89,11 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
    * @param idOrItem - The context identifier (string), a `ContextItem`, or `null`. If omitted, the current context may be cleared.
    */
   public setCurrentContext(idOrItem?: string | ContextItem | null): void {
+    // resolve string identifiers to a context item before setting
     if (typeof idOrItem === 'string') {
-      // TODO - compare context
+      // TODO(#5117) - compare context
+      // TODO(#5117) should this catch error?
       this.resolveContext(idOrItem)
-        // TODO should this catch error?
         .pipe(catchError(() => EMPTY))
         .subscribe((value) => this.setCurrentContext(value));
       /** only add context if not match */
@@ -105,10 +110,12 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
    * @throws Rethrows the underlying error cause if present, otherwise throws the original error.
    */
   public resolveContext(id: string): Observable<ContextItem> {
+    // unwrap the query result into the resolved context item
     return this.#client.query({ id }).pipe(
       map((x) => x.value),
       // unwrap error
       catchError((err) => {
+        // unwrap the underlying cause so callers see the original error
         if (err.cause) {
           throw err.cause;
         }
@@ -131,6 +138,9 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
     return fn(this.resolveContext(id));
   }
 
+  /**
+   * Disposes of the client, completing the internal current-context subject.
+   */
   public dispose(): void {
     this.#currentContext$.complete();
   }