@equinor/fusion-framework-module-context 5.0.7 → 5.0.8

package/dist/types/ContextProvider.d.ts

@@ -5,25 +5,98 @@ import { ContextItem, QueryContextParameters, RelatedContextParameters } from '.
 import { ModuleType } from '@equinor/fusion-framework-module';
 import { EventModule, FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
 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>;
     readonly currentContext$: Observable<ContextItem | null | undefined>;
     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;
@@ -35,10 +108,12 @@ export declare class ContextProvider implements IContextProvider {
     get queryClient(): Query<ContextItem[], QueryContextParameters>;
     get currentContext$(): Observable<ContextItem | null | undefined>;
     get currentContext(): ContextItem | undefined | null;
+    /** @deprecated do not use, will be removed */
     set currentContext(context: ContextItem | null | undefined);
     constructor(args: {
         config: ContextModuleConfig;
         event?: ModuleType<EventModule>;
+        /** @deprecated use  ContextProvider.connectParentContext */
         parentContext?: IContextProvider;
     });
     connectParentContext(provider: IContextProvider, opt?: {
@@ -46,6 +121,17 @@ export declare class ContextProvider implements IContextProvider {
     }): Subscription;
     setCurrentContextById(id: string): Observable<ContextItem<Record<string, unknown>>>;
     setCurrentContextByIdAsync(id: string): Promise<ContextItem<Record<string, unknown>>>;
+    /**
+     * Setting context is a complex operation, and might not happen immediately.
+     * When setting the context, a task is created and added to the queue.
+     * Once the task is completed, the returned observable will emit the value which will be the next state.
+     *
+     * Even tho this function returns a `Observable`, the task will be queued even tho nobody subscribes.
+     *
+     * 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
+     */
     setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(context: T, opt?: {
         validate?: boolean;
         resolve?: boolean;

package/dist/types/configurator.d.ts

@@ -15,8 +15,17 @@ export interface ContextModuleConfig {
     };
     contextType?: string[];
     contextFilter?: ContextFilterFn;
+    /**
+     * connect context module to paren context module.
+     *
+     * _default: `true`_
+     */
     connectParentContext?: boolean;
+    /** set initial context from parent, will await resolve */
     skipInitialContext?: boolean;
+    /**
+     * Method for generating context query parameters.
+     */
     contextParameterFn?: (args: {
         search: string;
         type: ContextModuleConfig['contextType'];

package/dist/types/errors.d.ts

@@ -1,9 +1,29 @@
+/**
+ * Represents an error that occurs during a search in the Fusion Context.
+ */
 export declare class FusionContextSearchError extends Error {
     #private;
+    /**
+     * The title of the error.
+     */
     get title(): string;
+    /**
+     * The description of the error, if available.
+     */
     get description(): string | undefined;
+    /**
+     * 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);
 }

package/dist/types/selectors.d.ts

@@ -1,4 +1,19 @@
 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>;
+/**
+ * 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[]>;
+/**
+ * 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/utils/enable-context.d.ts

@@ -1,4 +1,8 @@
 import type { IModulesConfigurator, AnyModule, ModuleInitializerArgs } from '@equinor/fusion-framework-module';
 import type { IContextModuleConfigurator } from '../configurator';
 import type { ContextConfigBuilder } from '../ContextConfigBuilder';
-export declare const enableContext: (configurator: IModulesConfigurator<any, any>, builder?: (<TDeps extends AnyModule[] = []>(builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>) => void | Promise<void>) | undefined) => void;
+/**
+ * Method for enabling the Service module
+ * @param configurator - configuration object
+ */
+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/utils/resolve-context-from-path.d.ts

@@ -2,14 +2,81 @@ import { Observable } from 'rxjs';
 import { type ModuleType } from '@equinor/fusion-framework-module';
 import { type ContextModule } from '../module';
 import { type ContextItem } from '../types';
+/**
+ * Arguments for resolving a context from a path.
+ */
 export type ContextPathResolveArgs = {
+    /**
+     * Callback to extract a context id from a path.
+     * @param path string - the path to extract the context id from
+     * @returns string | undefined - the context id or undefined
+     */
     extract?: (path: string) => string | undefined;
+    /**
+     * Callback to validate a context id.
+     * @param contextId string - the context id to validate
+     * @returns boolean - true if the context id is valid
+     */
     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.
+ * The method will use the context module to resolve the context.
+ * The method will use the extract and validate methods from the args to extract and validate the context id.
+ * If the context id is not valid, the method will throw an error.
+ * If the context id is valid, the method will return an observable of the resolved context.
+ * If the context id is not found, the method will return an empty observable.
+ *
+ * @example
+ * ```ts
+ * const resolve = resolveContextFromPath(modules.context);
+ * resolve(
+ *  '/apps/context/7fd97952-7fe6-409b-a6dc-292dbf0e50d7?foobar#example'
+ * ).subscribe(console.log);
+ * ```
+ *
+ * @param context The context module.
+ * @returns A function that takes a path and returns an Observable of the resolved context item.
+ */
 export interface resolveContextFromPath {
     (context: ModuleType<ContextModule>): (path: string) => Observable<ContextItem>;
 }
+/**
+ *
+ * @example
+ * ```ts
+ * const resolve = resolveContextFromPath(
+ *      modules.context,
+ *       {
+ *          extract: (path) => path.find(extractingContextFromPath),
+ *          validate: (id) => isValidContextId(id)
+ * });
+ * resolve(
+ *      '/apps/context/7fd97952-7fe6-409b-a6dc-292dbf0e50d7?foobar#example'
+ * ).subscribe(console.log);
+ * ```
+ *
+ * @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.
+ */
 export interface resolveContextFromPath {
     (context: ModuleType<ContextModule>, args: ContextPathResolveArgs): (path: string) => Observable<ContextItem>;
 }

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

@@ -1,7 +1,21 @@
 import { type ContextModuleConfig } from '../configurator';
 import { type ContextPathResolveArgs } from './resolve-context-from-path';
+/**
+ * Resolves the initial context from the parent module.
+ *
+ * @param ref - parent modules.
+ * @returns An Observable of the resolved initial context.
+ */
 export declare const resolveContextFromParent: ContextModuleConfig['resolveInitialContext'];
+/**
+ * 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.
+ *
+ * @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'];
+}) => Required<ContextModuleConfig>["resolveInitialContext"];
 export default resolveInitialContext;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.0.7";
+export declare const version = "5.0.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "5.0.7",
+  "version": "5.0.8",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@equinor/fusion-query": "^5.0.5"
+    "@equinor/fusion-query": "^5.1.0"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
-    "typescript": "^5.4.2",
-    "@equinor/fusion-framework-module-navigation": "^4.0.2",
-    "@equinor/fusion-framework-module": "^4.3.1",
-    "@equinor/fusion-framework-module-event": "^4.1.2",
-    "@equinor/fusion-framework-module-services": "^4.1.0"
+    "typescript": "^5.5.3",
+    "@equinor/fusion-framework-module": "^4.3.2",
+    "@equinor/fusion-framework-module-navigation": "^4.0.3",
+    "@equinor/fusion-framework-module-event": "^4.2.0",
+    "@equinor/fusion-framework-module-services": "^4.1.1"
   },
   "peerDependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^4.3.1"
+    "@equinor/fusion-framework-module": "^4.3.2"
   },
   "scripts": {
     "build": "tsc -b"

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '5.0.7';
+export const version = '5.0.8';