@equinor/fusion-framework-module-context 8.0.0 → 8.0.2

package/src/ContextProvider.ts

@@ -24,6 +24,7 @@ import type {
   FrameworkEventInit,
 } from '@equinor/fusion-framework-module-event';
 import Query from '@equinor/fusion-query';
+import type { SemVer } from 'semver';
 
 /**
  * Interface representing a provider for managing and interacting with context items within an application.
@@ -296,6 +297,13 @@ export interface IContextProvider {
    * @returns path for the context item
    */
   generatePathFromContext?: (context: ContextItem, path: string) => string | undefined;
+  /**
+   * The version of the context provider.
+   *
+   * @remarks
+   * This property represents the version of the context provider, which can be a string or a SemVer object.
+   */
+  readonly version: string | SemVer;
 }
 
 /**
@@ -346,35 +354,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 +422,7 @@ export class ContextProvider
 
     super({ version, config });
 
+    // warn about deprecated parentContext constructor arg
     if (args.parentContext) {
       console.warn(
         '@deprecated',
@@ -398,16 +436,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 is to avoid breaking change, the signature will be updated in future major release
       this.extractContextIdFromPath = config.extractContextIdFromPath;
     }
+    // override generatePathFromContext if configured
     if (config.generatePathFromContext) {
-      // @ts-ignore
+      // @ts-expect-error - this is to avoid breaking change, the signature will be updated in future major release
       this.generatePathFromContext = config.generatePathFromContext;
     }
 
@@ -418,6 +459,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 +478,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 +534,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 +549,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 +565,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 +613,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 +655,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 +671,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 +691,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 +727,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 +761,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 +783,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 +846,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 +870,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 +881,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 +916,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 +942,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 +1005,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;
         }

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();
   }

package/src/configurator.ts

@@ -8,7 +8,11 @@ import type {
 } from '@equinor/fusion-framework-module';
 import type { ServicesModule, IApiProvider } from '@equinor/fusion-framework-module-services';
 import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
-import { getContextSelector, queryContextSelector, relatedContextSelector } from './selectors';
+import {
+  getContextSelector,
+  queryContextSelector,
+  relatedContextSelector,
+} from './get-context-selector';
 import type { QueryCtorOptions } from '@equinor/fusion-query';
 import type {
   ContextFilterFn,
@@ -149,9 +153,10 @@ export interface ContextModuleConfig {
    * @returns An observable input emitting the initial context item, or void.
    */
   resolveInitialContext?: (args: {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    // biome-ignore lint/suspicious/noExplicitAny: `AnyModuleInstance | any` intentionally widens to accept any module instance shape for `ref`
     ref?: AnyModuleInstance | any;
     modules: ModuleInstance;
+    // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior — `undefined` would break assignability of resolver functions that only conditionally emit a `ContextItem`
   }) => ObservableInput<ContextItem | void>;
 }
 
@@ -206,10 +211,12 @@ export class ContextModuleConfigurator implements IContextModuleConfigurator {
   protected async _getServiceProvider(
     init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule]>,
   ): Promise<IApiProvider> {
+    // prefer the local services module instance if available
     if (init.hasModule('services')) {
       return init.requireInstance('services');
     }
     const parentServiceModule = (init.ref as ModulesInstanceType<[ServicesModule]>)?.services;
+    // fall back to the parent module's services instance
     if (!parentServiceModule) {
       throw Error('no service services provider configures [ServicesModule]');
     }
@@ -230,24 +237,21 @@ export class ContextModuleConfigurator implements IContextModuleConfigurator {
   public async createConfig(
     init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
   ): Promise<ContextModuleConfig> {
+    // run each registered config builder in sequence, merging results into the accumulated config
     const config = await this.#configBuilders.reduce(
       async (cur, cb) => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        // biome-ignore lint/suspicious/noExplicitAny: builder generics are erased here — `unknown` breaks assignability of the concrete `ContextConfigBuilder` instance passed to consumer callbacks
         const builder = new ContextConfigBuilder<any, any>(init, await cur);
         await Promise.resolve(cb(builder));
+        // Merge this builder's config into the accumulator for the next iteration.
         return Object.assign(cur, builder.config);
       },
       Promise.resolve({} as Partial<ContextModuleConfig>),
     );
 
-    config.resolveInitialContext ??= resolveInitialContext({
-      path: {
-        extract: config.extractContextIdFromPath,
-        validate: config.extractContextIdFromPath ? () => true : undefined,
-      },
-    });
+    config.resolveInitialContext ??= resolveInitialContext();
 
-    // TODO - make less lazy
+    // TODO(#5119) - make less lazy
     config.client ??= await (async (): Promise<ContextModuleConfig['client']> => {
       const apiProvider = await this._getServiceProvider(init);
       const contextClient = await apiProvider.createContextClient('json$');
@@ -263,7 +267,7 @@ export class ContextModuleConfigurator implements IContextModuleConfigurator {
           client: {
             fn: (query) => contextClient.query('v1', { query }, { selector: queryContextSelector }),
           },
-          // TODO - might cast to checksum
+          // TODO(#5118) - might cast to checksum
           key: (args) => JSON.stringify(args),
           expire: this.defaultExpireTime,
         },
@@ -277,7 +281,7 @@ export class ContextModuleConfigurator implements IContextModuleConfigurator {
               );
             },
           },
-          // TODO - might cast to checksum
+          // TODO(#5118) - might cast to checksum
           key: (args) => JSON.stringify(args),
           expire: this.defaultExpireTime,
         },

package/src/{errors.ts → errors/FusionContextSearchError.ts}

@@ -17,6 +17,7 @@ export class FusionContextSearchError extends Error {
 
   /**
    * The title of the error.
+   * @returns The error title.
    */
   get title(): string {
     return this.#details.title;
@@ -24,6 +25,7 @@ export class FusionContextSearchError extends Error {
 
   /**
    * The description of the error, if available.
+   * @returns The error description, or `undefined` if none was provided.
    */
   get description(): string | undefined {
     return this.#details.description;

package/src/errors/index.ts

@@ -0,0 +1 @@
+export * from './FusionContextSearchError';

package/src/get-context-selector.ts

@@ -0,0 +1,18 @@
+import type { GetContextResponse } from '@equinor/fusion-framework-module-services/context/get';
+
+import { parseContextItem } from './parse-context-item';
+import type { ContextItem } from './types';
+
+/**
+ * Parse the response from the GetContext API into a context item.
+ * @param response The response object containing the context item.
+ * @returns A promise that resolves to the context item.
+ */
+export const getContextSelector = async (response: Response): Promise<ContextItem> => {
+  const result = (await response.json()) as GetContextResponse<'v1'>;
+  return parseContextItem(result);
+};
+
+// Deliberately re-exported from here to preserve the package's existing selectors entry point
+export { queryContextSelector } from './query-context-selector';
+export { relatedContextSelector } from './related-context-selector';

package/src/parse-context-item.ts

@@ -0,0 +1,39 @@
+import type {
+  ApiVersion,
+  ApiContextEntity,
+} from '@equinor/fusion-framework-module-services/context';
+import type { GetContextResponse } from '@equinor/fusion-framework-module-services/context/get';
+
+import type { ContextItem, ContextItemType } from './types';
+
+/**
+ * Parses the context type from the response of the GetContext API.
+ *
+ * @param type The type property from the GetContext response.
+ * @returns The parsed context item type.
+ */
+const parseContextType = (type: GetContextResponse<'v1'>['type']): ContextItemType => ({
+  id: type.id,
+  isChildType: type.isChildType,
+  parentTypeIds: type.parentTypeIds ?? [],
+});
+
+/**
+ * Parses an ApiContextEntity object into a ContextItem object.
+ * @param item The ApiContextEntity object to parse.
+ * @returns The parsed ContextItem object.
+ */
+export const parseContextItem = (item: ApiContextEntity<ApiVersion.v1>): ContextItem => {
+  return {
+    id: item.id,
+    externalId: item.externalId ?? undefined,
+    isActive: item.isActive,
+    isDeleted: item.isDeleted,
+    created: new Date(item.created),
+    source: item.source ?? undefined,
+    title: item.title ?? undefined,
+    type: parseContextType(item.type),
+    // TODO(#5115): parse and map the raw `value` payload into a typed context item value
+    value: item.value ?? {},
+  };
+};

package/src/query-context-selector.ts

@@ -0,0 +1,15 @@
+import type { QueryContextResponse } from '@equinor/fusion-framework-module-services/context/query';
+
+import { parseContextItem } from './parse-context-item';
+import type { ContextItem } from './types';
+
+/**
+ * Parse the response from the QueryContext API into an array of context items.
+ * @param response The response object.
+ * @returns A promise that resolves to an array of context items.
+ */
+export const queryContextSelector = async (response: Response): Promise<ContextItem[]> => {
+  const result = (await response.json()) as QueryContextResponse<'v1'>;
+  // parse each raw API entry into a ContextItem
+  return result.map(parseContextItem);
+};

package/src/related-context-selector.ts

@@ -0,0 +1,15 @@
+import type { RelatedContextResponse } from '@equinor/fusion-framework-module-services/context/related';
+
+import { parseContextItem } from './parse-context-item';
+import type { ContextItem } from './types';
+
+/**
+ * Parse the response from the RelatedContext API into an array of context items.
+ * @param response The response object containing the related context items.
+ * @returns A promise that resolves to an array of ContextItem objects.
+ */
+export const relatedContextSelector = async (response: Response): Promise<ContextItem[]> => {
+  const result = (await response.json()) as RelatedContextResponse<'v1'>;
+  // parse each raw API entry into a ContextItem
+  return result.map(parseContextItem);
+};

package/src/types.ts

@@ -16,7 +16,7 @@
  * @property graphic - Optional graphical representation, either as a string or an object containing type and content.
  * @property meta - Optional meta information, either as a string or an object containing type and content.
  *
- * @todo - convert to Zod schema for validation and type safety.
+ * @todo(#5122) - convert to Zod schema for validation and type safety.
  */
 export type ContextItem<TType extends Record<string, unknown> = Record<string, unknown>> = {
   id: string;

package/src/utils/extract-context-id-from-path.ts

@@ -0,0 +1,39 @@
+// GUID pattern
+const matchGUID =
+  /^(?:(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12})$/;
+
+/**
+ * Method will try to extract a context id from a path.
+ * The default matcher is a GUID pattern.
+ * Will iterate over the path and return the first match.
+ *
+ * @example
+ * ```ts
+ * const path = '/apps/context/7fd97952-7fe6-409b-a6dc-292dbf0e50d7?dsadasdas#example';
+ * const contextId = extractContextIdFromPath(path); // '7fd97952-7fe6-409b-a6dc-292dbf0e50d7'
+ *
+ * // Custom matcher for numeric IDs
+ * extractContextIdFromPath('/projects/42/details', /^\d+$/);  // '42'
+ *
+ * // No match
+ * extractContextIdFromPath('/apps/my-app/settings'); // undefined
+ * ```
+ *
+ * @param path string - the path to extract the context id from
+ * @param matcher RegExp - the pattern to match against
+ * @returns string | undefined - the context id or undefined
+ */
+export const extractContextIdFromPath = (
+  path: string,
+  matcher: RegExp = matchGUID,
+): string | undefined =>
+  //
+  path
+    // remove query-string and hash fragments before segment matching
+    .split(/[?#]/)[0]
+    // remove leading slashes
+    .replace(/^\/+/, '')
+    // split path by slashes
+    .split('/')
+    // find the first path fragment that matches the matcher
+    .find((x) => x.match(matcher));