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

package/dist/types/ContextConfigBuilder.d.ts

@@ -35,7 +35,7 @@ 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
@@ -43,8 +43,23 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
 export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = [], TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<ContextModuleConfigurator, TModules>> {
     #private;
     config: Partial<ContextModuleConfig>;
+    /**
+     * 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, config?: Partial<ContextModuleConfig>);
+    /**
+     * 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>;
     /**
      * Sets the context type for the current configuration.

package/dist/types/ContextProvider.d.ts

@@ -6,6 +6,7 @@ import type { ContextItem, QueryContextParameters, RelatedContextParameters } fr
 import type { ModuleType } from '@equinor/fusion-framework-module';
 import type { EventModule, FrameworkEvent, 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.
  *
@@ -257,6 +258,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;
 }
 /**
  * Provides context management functionality, including querying, setting, validating, and resolving context items.
@@ -290,12 +298,40 @@ export interface IContextProvider {
  */
 export declare class ContextProvider extends BaseModuleProvider<ContextModuleConfig> implements IContextProvider {
     #private;
+    /**
+     * The underlying context client used to resolve and hold the current context item.
+     * @returns The internal {@link ContextClient} instance.
+     */
     get contextClient(): ContextClient;
+    /**
+     * The query client used to search for context items.
+     * @returns The internal `Query` instance used by {@link queryContext}.
+     */
     get queryClient(): Query<ContextItem[], QueryContextParameters>;
+    /**
+     * Observable stream emitting the current context item.
+     * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
+     */
     get currentContext$(): Observable<ContextItem | null | undefined>;
+    /**
+     * Snapshot of the current context item.
+     * @returns The current `ContextItem`, or `null`/`undefined` if not set.
+     */
     get currentContext(): ContextItem | undefined | null;
-    /** @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);
+    /**
+     * 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>;
@@ -357,6 +393,11 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
      * 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.
      */
     setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(context: T, opt?: {
         validate?: boolean;
@@ -391,7 +432,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
      *    - 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.
@@ -412,7 +453,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
      *
      * @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.
@@ -433,6 +474,7 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
      *
      * @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.
      */
     queryContext(search: string): Observable<Array<ContextItem>>;
     /**

package/dist/types/client/ContextClient.d.ts

@@ -20,7 +20,7 @@ export type GetContextParameters = {
  * @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
@@ -55,6 +55,10 @@ export declare class ContextClient extends Observable<ContextItem | null | undef
     get client(): Query<ContextItem, {
         id: string;
     }>;
+    /**
+     * Creates a new `ContextClient`.
+     * @param options - Query constructor options used to fetch a `ContextItem` by its ID.
+     */
     constructor(options: QueryCtorOptions<ContextItem, GetContextParameters>);
     /**
      * Sets the current context based on the provided identifier or context item.
@@ -85,6 +89,9 @@ export declare class ContextClient extends Observable<ContextItem | null | undef
     resolveContextAsync(id: string, opt?: {
         awaitResolve: boolean;
     }): Promise<ContextItem>;
+    /**
+     * Disposes of the client, completing the internal current-context subject.
+     */
     dispose(): void;
 }
 export default ContextClient;

package/dist/types/{errors.d.ts → errors/FusionContextSearchError.d.ts}

@@ -16,10 +16,12 @@ export declare class FusionContextSearchError extends Error {
     #private;
     /**
      * The title of the error.
+     * @returns The error title.
      */
     get title(): string;
     /**
      * The description of the error, if available.
+     * @returns The error description, or `undefined` if none was provided.
      */
     get description(): string | undefined;
     /**

package/dist/types/errors/index.d.ts

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

package/dist/types/get-context-selector.d.ts

@@ -0,0 +1,9 @@
+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 declare const getContextSelector: (response: Response) => Promise<ContextItem>;
+export { queryContextSelector } from './query-context-selector';
+export { relatedContextSelector } from './related-context-selector';

package/dist/types/parse-context-item.d.ts

@@ -0,0 +1,8 @@
+import type { ApiVersion, ApiContextEntity } from '@equinor/fusion-framework-module-services/context';
+import type { ContextItem } from './types';
+/**
+ * Parses an ApiContextEntity object into a ContextItem object.
+ * @param item The ApiContextEntity object to parse.
+ * @returns The parsed ContextItem object.
+ */
+export declare const parseContextItem: (item: ApiContextEntity<ApiVersion.v1>) => ContextItem;

package/dist/types/query-context-selector.d.ts

@@ -0,0 +1,7 @@
+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 declare const queryContextSelector: (response: Response) => Promise<ContextItem[]>;

package/dist/types/related-context-selector.d.ts

@@ -0,0 +1,7 @@
+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 declare const relatedContextSelector: (response: Response) => Promise<ContextItem[]>;

package/dist/types/types.d.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/dist/types/utils/extract-context-id-from-path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const extractContextIdFromPath: (path: string, matcher?: RegExp) => string | undefined;

package/dist/types/utils/resolve-context-from-path.d.ts

@@ -2,6 +2,7 @@ import { type Observable } from 'rxjs';
 import type { ModuleType } from '@equinor/fusion-framework-module';
 import type { ContextModule } from '../module';
 import type { ContextItem } from '../types';
+export { extractContextIdFromPath } from './extract-context-id-from-path';
 /**
  * Arguments for resolving a context from a path.
  */
@@ -19,22 +20,6 @@ export type ContextPathResolveArgs = {
      */
     validate?: (contextId: string) => boolean;
 };
-/**
- * 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'
- * ```
- *
- * @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 declare const extractContextIdFromPath: (path: string, matcher?: RegExp) => string | undefined;
 /**
  * Method will try to resolve a context from a path.
  * The method will return a function that takes a path and returns an observable of the resolved context.
@@ -54,6 +39,10 @@ export declare const extractContextIdFromPath: (path: string, matcher?: RegExp)
  *
  * @param context The context module.
  * @returns A function that takes a path and returns an Observable of the resolved context item.
+ * @deprecated Replaced by the context-navigation plugin which resolves
+ * initial context from the URL via adapter `decode()` during module initialization.
+ * Portal-level code should use `enableContextNavigation` which handles
+ * URL-to-context resolution automatically. Will be removed in a future major version.
  */
 export declare function resolveContextFromPath(context: ModuleType<ContextModule>): (path: string) => Observable<ContextItem>;
 /**
@@ -74,6 +63,10 @@ export declare function resolveContextFromPath(context: ModuleType<ContextModule
  * @param context The context module.
  * @param args The arguments for resolving the path.
  * @returns A function that takes a path and returns an Observable of the resolved context item.
+ * @deprecated Replaced by the context-navigation plugin which resolves
+ * initial context from the URL via adapter `decode()` during module initialization.
+ * Portal-level code should use `enableContextNavigation` which handles
+ * URL-to-context resolution automatically. Will be removed in a future major version.
  */
 export declare function resolveContextFromPath(context: ModuleType<ContextModule>, args?: ContextPathResolveArgs): (path: string) => Observable<ContextItem>;
 export default resolveContextFromPath;

package/dist/types/utils/resolve-initial-context.d.ts

@@ -1,5 +1,4 @@
 import type { ContextModuleConfig } from '../configurator';
-import { type ContextPathResolveArgs } from './resolve-context-from-path';
 /**
  * Resolves the initial context from the parent module.
  *
@@ -10,12 +9,10 @@ export declare const resolveContextFromParent: ContextModuleConfig['resolveIniti
 /**
  * Resolves the initial context for a Fusion Framework context module.
  *
- * will try to resolve the initial context from the path, and if that fails, it will try to resolve the context from the parent.
+ * Attempts to resolve the initial context from the parent context provider.
+ * URL-based resolution is handled by the context-navigation plugin.
  *
- * @param options - Optional configuration for resolving the context path.
  * @returns A function that accepts the module's reference and modules, and returns an Observable of the resolved initial context.
  */
-export declare const resolveInitialContext: (options?: {
-    path?: ContextPathResolveArgs;
-}) => Required<ContextModuleConfig>["resolveInitialContext"];
+export declare const resolveInitialContext: () => Required<ContextModuleConfig>['resolveInitialContext'];
 export default resolveInitialContext;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "8.0.0";
+export declare const version = "8.0.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "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,23 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@equinor/fusion-query": "^7.0.0"
+    "@equinor/fusion-query": "^7.0.3"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
-    "typescript": "^5.9.3",
-    "@equinor/fusion-framework-module-event": "^6.0.0",
-    "@equinor/fusion-framework-module": "^6.0.0",
-    "@equinor/fusion-framework-module-services": "^8.0.0",
-    "@equinor/fusion-framework-module-navigation": "^7.0.0"
+    "typescript": "^7.0.2",
+    "@types/semver": "^7.0.0",
+    "semver": "^7.0.0",
+    "@equinor/fusion-framework-module-event": "^6.0.1",
+    "@equinor/fusion-framework-module-navigation": "^7.0.7",
+    "@equinor/fusion-framework-module": "^6.1.2",
+    "@equinor/fusion-framework-module-services": "^8.0.3"
   },
   "peerDependencies": {
+    "@types/semver": "^7.0.0",
+    "semver": "^7.0.0",
     "rxjs": "^7.0.0",
-    "@equinor/fusion-framework-module": "^6.0.0"
+    "@equinor/fusion-framework-module": "^6.1.2"
   },
   "scripts": {
     "build": "tsc -b"

package/src/ContextConfigBuilder.ts

@@ -52,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> = {},
@@ -72,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);
   }
 
@@ -192,7 +216,7 @@ export class ContextConfigBuilder<
     },
     expire = 1 * 60 * 1000,
   ): void {
-    this.config.client = {
+    const clientConfig: ContextModuleConfig['client'] = {
       get:
         typeof client.get === 'function'
           ? {
@@ -206,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,
@@ -215,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,