@equinor/fusion-framework-module-context 4.1.0 → 4.2.0

package/src/errors.ts

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

@@ -25,27 +25,41 @@ export const module: ContextModule = {
     name: moduleKey,
     configure: () => new ContextModuleConfigurator(),
     initialize: async function (args) {
+        // create config from configurator
         const config = await (args.config as ContextModuleConfigurator).createConfig(args);
+
+        // get event module if available
         const event = args.hasModule('event') ? await args.requireInstance('event') : undefined;
+
+        // get parent context provider if available
         const parentProvider = (args.ref as ModulesInstance<[ContextModule]>)?.context;
+
+        // create context provider
         const provider = new ContextProvider({ config, event, parentContext: parentProvider });
 
+        // create subscription for disposing the provider
         const subscription = new Subscription(() => provider.dispose());
 
+        // setup post initialize to module
         this.postInitialize = (args) =>
+            // create observable for resolving initial context
             new Observable((subscriber) => {
+                // resolve initial context if available from config if available
                 const resolveInitialContext$ = config.resolveInitialContext
                     ? from(config.resolveInitialContext(args)).pipe(
+                          // filter out invalid context items
                           filter((item): item is ContextItem => !!item),
                           switchMap((item) =>
+                              // set current context with validation and resolution
                               args.modules.context.setCurrentContext(item, {
                                   validate: true,
                                   resolve: true,
                               }),
                           ),
                       )
-                    : EMPTY;
+                    : EMPTY; // if no initial context is available, complete immediately
 
+                // add teardown to resolve initial context
                 subscriber.add(
                     resolveInitialContext$
                         .pipe(
@@ -55,6 +69,7 @@ export const module: ContextModule = {
                                     'failed to resolve initial context',
                                     err,
                                 );
+                                // failed to resolve initial context, complete immediately
                                 return EMPTY;
                             }),
                         )
@@ -67,6 +82,7 @@ export const module: ContextModule = {
                                 );
                             },
                             complete: () => {
+                                // connect parent context if available when stream completes
                                 if (config.connectParentContext !== false && parentProvider) {
                                     provider.connectParentContext(parentProvider);
                                 }
@@ -76,6 +92,7 @@ export const module: ContextModule = {
                 );
             });
 
+        // add teardown to module
         this.dispose = () => subscription.unsubscribe();
 
         return provider;

package/src/selectors.ts

@@ -4,12 +4,23 @@ import type { QueryContextResponse } from '@equinor/fusion-framework-module-serv
 import type { RelatedContextResponse } from '@equinor/fusion-framework-module-services/context/related';
 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.
+ */
 const parseContextItem = (item: ApiContextEntity<ApiVersion.v1>): ContextItem => {
     return {
         id: item.id,
@@ -25,16 +36,31 @@ const parseContextItem = (item: ApiContextEntity<ApiVersion.v1>): ContextItem =>
     };
 };
 
+/**
+ * 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);
 };
 
+/**
+ * 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'>;
     return result.map(parseContextItem);
 };
 
+/**
+ * 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'>;
     return result.map(parseContextItem);

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { enableContext } from './enable-context';
 export { resolveInitialContext } from './resolve-initial-context';
+export { extractContextIdFromPath, resolveContextFromPath } from './resolve-context-from-path';

package/src/utils/resolve-context-from-path.ts

@@ -1,24 +1,116 @@
-import { EMPTY } from 'rxjs';
+import { EMPTY, Observable } from 'rxjs';
 
-import { ModuleType } from '@equinor/fusion-framework-module';
+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;
 };
 
+// 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})$/;
 
-const extractContextIdFromPath = (path: string): string | undefined =>
-    path.replace(/^\/+/, '').split('/').shift();
+/**
+ * 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 const extractContextIdFromPath = (
+    path: string,
+    matcher: RegExp = matchGUID,
+): string | undefined =>
+    path
+        // remove leading slashes
+        .replace(/^\/+/, '')
+        // split path by slashes
+        .split('/')
+        // find the first path fragment that matches the matcher
+        .find((x) => x.match(matcher));
 
 const validateContextId = (contextId: string): boolean => !!contextId.match(matchGUID);
 
-export const resolveContextFromPath =
-    (context: ModuleType<ContextModule>, args?: ContextPathResolveArgs) => (path: string) => {
+/**
+ * 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>;
+}
+
+export function resolveContextFromPath(
+    context: ModuleType<ContextModule>,
+    args?: ContextPathResolveArgs,
+) {
+    return (path: string) => {
         const { extract = extractContextIdFromPath, validate = validateContextId } = args ?? {};
         const contextId = extract(path);
         if (!contextId) {
@@ -30,5 +122,6 @@ export const resolveContextFromPath =
 
         throw Error(`Failed to validate context [${contextId}] from path [${path}]`);
     };
+}
 
 export default resolveContextFromPath;

package/src/utils/resolve-initial-context.ts

@@ -1,27 +1,50 @@
-import { ModulesInstance } from '@equinor/fusion-framework-module';
-import { ContextModule } from '../module';
+import { type ModulesInstance } from '@equinor/fusion-framework-module';
+import { type ContextModule } from '../module';
 import { type ContextModuleConfig } from '../configurator';
 import { concat, EMPTY, first, of } from 'rxjs';
 
-import { ContextPathResolveArgs, resolveContextFromPath } from './resolve-context-from-path';
+import { type ContextPathResolveArgs, resolveContextFromPath } from './resolve-context-from-path';
+import { type NavigationModule } from '@equinor/fusion-framework-module-navigation';
 
+/**
+ * Resolves the initial context from the parent module.
+ *
+ * @param ref - parent modules.
+ * @returns An Observable of the resolved initial context.
+ */
 export const resolveContextFromParent: ContextModuleConfig['resolveInitialContext'] = ({ ref }) => {
     const parentContext = (ref as ModulesInstance<[ContextModule]>)?.context;
+    // check if the parent has context module
     if (!parentContext) {
         throw Error(['resolveContextFromNavigation', 'ref does not support context!'].join('\n'));
     }
+    // return the current context from the parent or empty if the parent does not have a context
     return parentContext.currentContext ? of(parentContext.currentContext) : EMPTY;
 };
 
+/**
+ * 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 const resolveInitialContext =
     (options?: {
         path?: ContextPathResolveArgs;
     }): Required<ContextModuleConfig>['resolveInitialContext'] =>
     ({ ref, modules }) => {
         const { context, navigation } = modules;
+        // create a path resolver from the context module
         const pathResolver = resolveContextFromPath(context, options?.path);
+        // use the path from the navigation module, or the path from the parent navigation module
+        const pathname =
+            navigation?.path.pathname ??
+            (ref as Partial<ModulesInstance<[NavigationModule]>>).navigation?.path.pathname;
+        // try to resolve the context from the path, and if that fails, try to resolve the context from the parent
         return concat(
-            navigation ? pathResolver(navigation.path.pathname) : EMPTY,
+            pathname ? pathResolver(pathname) : EMPTY,
             resolveContextFromParent({ ref, modules }),
         ).pipe(first());
     };

package/src/version.ts

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