@equinor/fusion-framework-module-context 6.0.7-next.0 → 7.0.1

package/dist/types/errors.d.ts

@@ -1,5 +1,16 @@
 /**
- * Represents an error that occurs during a search in the Fusion Context.
+ * Represents an error that occurs during a Fusion context search operation.
+ *
+ * This error provides a title and an optional description to give more context
+ * about the failure. It extends the built-in `Error` class and sets the error
+ * name to `'FusionContextSearchError'`.
+ *
+ * @example
+ * ```typescript
+ * throw new FusionContextSearchError({ title: 'Search failed', description: 'No results found.' });
+ * ```
+ *
+ * @public
  */
 export declare class FusionContextSearchError extends Error {
     #private;

package/dist/types/module.d.ts

@@ -6,11 +6,42 @@ import { type IContextModuleConfigurator } from './configurator';
 import { type IContextProvider } from './ContextProvider';
 export type ContextModuleKey = 'context';
 export declare const moduleKey: ContextModuleKey;
+/**
+ * Represents a module for managing context within the framework.
+ *
+ * @typeParam ContextModuleKey - The unique key identifying the context module.
+ * @typeParam IContextProvider - The provider interface for context-related services.
+ * @typeParam IContextModuleConfigurator - The configurator interface for customizing the context module.
+ * @typeParam [ServicesModule, EventModule, NavigationModule] - The tuple of dependent modules required by the context module.
+ *
+ * @see Module
+ */
 export type ContextModule = Module<ContextModuleKey, IContextProvider, IContextModuleConfigurator, [
     ServicesModule,
     EventModule,
     NavigationModule
 ]>;
+/**
+ * The `module` object implements the `ContextModule` interface and provides the configuration,
+ * initialization, and lifecycle management for the context module within the Fusion Framework.
+ *
+ * @remarks
+ * - The `configure` method returns a new `ContextModuleConfigurator` for module configuration.
+ * - The `initialize` method asynchronously creates a `ContextProvider` using the provided configuration,
+ *   optional event module, and optional parent context provider. It also sets up resource disposal and
+ *   post-initialization logic.
+ * - The `postInitialize` function (attached during initialization) resolves the initial context if available,
+ *   sets it as the current context, and connects to the parent context provider if configured to do so.
+ * - The `dispose` function ensures proper cleanup by unsubscribing from the provider's subscription.
+ *
+ * @property {string} name - The unique key identifying the module.
+ * @method configure - Returns a new instance of `ContextModuleConfigurator` for configuring the module.
+ * @method initialize - Asynchronously initializes the context provider, sets up context resolution,
+ *   and manages lifecycle hooks.
+ * @see ContextModule
+ * @see ContextModuleConfigurator
+ * @see ContextProvider
+ */
 export declare const module: ContextModule;
 declare module '@equinor/fusion-framework-module' {
     interface Modules {

package/dist/types/types.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Represents a contextual item with associated metadata, value, and optional graphical or meta content.
+ *
+ * @typeParam TType - The type of the value property, defaults to a generic record.
+ * @property id - Unique identifier for the context item.
+ * @property externalId - Optional external identifier.
+ * @property source - Optional source of the context item.
+ * @property type - The type of the context item.
+ * @property value - The value associated with the context item.
+ * @property title - Optional title for display purposes.
+ * @property subTitle - Optional subtitle for display purposes.
+ * @property isActive - Optional flag indicating if the item is active.
+ * @property isDeleted - Optional flag indicating if the item is deleted.
+ * @property created - Optional creation date.
+ * @property updated - Optional last updated date.
+ * @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.
+ */
 export type ContextItem<TType extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
     externalId?: string;
@@ -31,10 +51,23 @@ export type QueryContextParameters = {
         externalId?: string;
     };
 };
+/**
+ * Parameters for retrieving related context items.
+ *
+ * @property item - The context item to find relations for.
+ * @property filter - Optional filter criteria.
+ * @property filter.type - Optional array of types to filter related items by.
+ */
 export type RelatedContextParameters = {
     item: ContextItem;
     filter?: {
         type?: string[];
     };
 };
+/**
+ * A function type that filters an array of `ContextItem` objects.
+ *
+ * @param items - The array of `ContextItem` objects to be filtered.
+ * @returns A new array of `ContextItem` objects after applying the filter.
+ */
 export type ContextFilterFn = (items: ContextItem[]) => ContextItem[];

package/dist/types/utils/enable-context.d.ts

@@ -2,7 +2,23 @@ import type { IModulesConfigurator, AnyModule, ModuleInitializerArgs } from '@eq
 import type { IContextModuleConfigurator } from '../configurator';
 import type { ContextConfigBuilder } from '../ContextConfigBuilder';
 /**
- * Method for enabling the Service module
- * @param configurator - configuration object
+ * Enables context configuration for a given modules configurator.
+ *
+ * @param configurator - The modules configurator instance to which the context module will be added.
+ * @param builder - An optional function that receives a context configuration builder. This function can be used to further configure the context module. It can be asynchronous.
+ *
+ * @remarks
+ * This utility function adds the context module to the provided configurator and optionally applies additional configuration using the provided builder function.
+ *
+ * @example
+ * ```ts
+ * import { enableContext } from '@equinor/fusion-framework-module-context';
+ *
+ * const configure = (configurator: IModulesConfigurator<any, any>) => {
+ *   enableContext(configurator, (builder) => {
+ *     // configure the context module here
+ *   });
+ * };
+ * ```
  */
 export declare const enableContext: (configurator: IModulesConfigurator<any, any>, builder?: <TDeps extends Array<AnyModule> = []>(builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>) => void | Promise<void>) => void;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "6.0.7-next.0";
+export declare const version = "7.0.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "6.0.7-next.0",
+  "version": "7.0.1",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@equinor/fusion-query": "^5.2.12-next.0"
+    "@equinor/fusion-query": "^6.0.0"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
     "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-event": "^4.3.7-next.2",
-    "@equinor/fusion-framework-module-services": "^6.0.4-next.0",
-    "@equinor/fusion-framework-module-navigation": "^5.0.4-next.0",
-    "@equinor/fusion-framework-module": "^4.4.3-next.2"
+    "@equinor/fusion-framework-module-event": "^4.3.7",
+    "@equinor/fusion-framework-module-navigation": "^6.0.0",
+    "@equinor/fusion-framework-module-services": "^7.1.2",
+    "@equinor/fusion-framework-module": "^5.0.3"
   },
   "peerDependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^4.4.3-next.2"
+    "@equinor/fusion-framework-module": "^5.0.3"
   },
   "scripts": {
     "build": "tsc -b"

package/src/ContextConfigBuilder.ts

@@ -21,11 +21,36 @@ export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>
   builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>,
 ) => void | Promise<void>;
 
-// TODO - this should extend the BaseConfigBuilder
-
+/**
+ * A builder class for configuring and customizing context module behavior within the Fusion Framework.
+ *
+ * `ContextConfigBuilder` provides a fluent API for setting up various aspects of context management,
+ * including context type, filtering, parent context connection, parameter resolution, validation,
+ * path extraction/generation, and client configuration for fetching context items.
+ *
+ * @typeParam TModules - An array of modules that extend `AnyModule`. Defaults to an empty array.
+ * @typeParam TInit - The initializer arguments for the module, extending `ModuleInitializerArgs`.
+ *
+ * @example
+ * ```typescript
+ * const builder = new ContextConfigBuilder(init);
+ * builder.setContextType(['ProjectMaster']);
+ * builder.setContextFilter(items => items.filter(ctx => ctx.isActive));
+ * builder.setContextClient({ get: fetchContextItem, query: fetchContextItems });
+ * ```
+ *
+ * @remarks
+ * - Use the provided setter methods to customize context behavior as needed.
+ * - 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
+ *
+ * @see ContextModuleConfig
+ * @see ModuleInitializerArgs
+ */
 export class ContextConfigBuilder<
   TModules extends Array<AnyModule> = [],
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<
     ContextModuleConfigurator,
     TModules
@@ -45,31 +70,60 @@ export class ContextConfigBuilder<
 
   requireInstance<T>(module: string): Promise<T>;
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   requireInstance(module: string): Promise<any> {
     return this.#init.requireInstance(module);
   }
 
+  /**
+   * Sets the context type for the current configuration.
+   *
+   * @param type - The context type to assign, as defined by `ContextModuleConfig['contextType']`.
+   */
   setContextType(type: ContextModuleConfig['contextType']) {
     this.config.contextType = type;
   }
 
+  /**
+   * Sets the context filter function for the configuration.
+   *
+   * @param filter - A function that determines whether a context should be included, as defined by `ContextModuleConfig['contextFilter']`.
+   */
   setContextFilter(filter: ContextModuleConfig['contextFilter']) {
     this.config.contextFilter = filter;
   }
 
+  /**
+   * Sets the function or configuration used to connect to a parent context.
+   *
+   * @param connect - The function or configuration that defines how to connect to the parent context.
+   */
   connectParentContext(connect: ContextModuleConfig['connectParentContext']) {
     this.config.connectParentContext = connect;
   }
 
+  /**
+   * Sets the function used to provide context parameters for the module configuration.
+   *
+   * @param fn - A function conforming to the `contextParameterFn` type defined in `ContextModuleConfig`.
+   */
   setContextParameterFn(fn: ContextModuleConfig['contextParameterFn']) {
     this.config.contextParameterFn = fn;
   }
 
+  /**
+   * Sets the function used to validate the context within the configuration.
+   *
+   * @param fn - A function that implements the `validateContext` signature from `ContextModuleConfig`.
+   */
   setValidateContext(fn: ContextModuleConfig['validateContext']) {
     this.config.validateContext = fn;
   }
 
+  /**
+   * Sets the function used to resolve the context for the module configuration.
+   *
+   * @param fn - A function that defines how the context should be resolved, conforming to the `resolveContext` type from `ContextModuleConfig`.
+   */
   setResolveContext(fn: ContextModuleConfig['resolveContext']) {
     this.config.resolveContext = fn;
   }
@@ -97,6 +151,18 @@ export class ContextConfigBuilder<
     this.config.resolveInitialContext = fn;
   }
 
+  /**
+   * Sets the context client configuration for fetching context items.
+   *
+   * This method allows you to provide custom query functions or query constructor options
+   * for retrieving single context items (`get`), querying multiple context items (`query`),
+   * and optionally fetching related context items (`related`). Each query can be provided
+   * as either a function or a configuration object. The expiration time for cached results
+   * can also be specified.
+   *
+   * @param client - An object containing the query functions or options for `get`, `query`, and optionally `related` context items.
+   * @param expire - Optional. The expiration time (in milliseconds) for cached query results. Defaults to 1 minute.
+   */
   setContextClient(
     client: {
       get: