@equinor/fusion-framework-module-context 8.0.3 → 9.0.0

package/src/ContextModuleConfig.ts

@@ -0,0 +1,147 @@
+import type { AnyModuleInstance, ModuleInstance } from '@equinor/fusion-framework-module';
+import type { ObservableInput } from 'rxjs';
+import type { QueryCtorOptions } from '@equinor/fusion-query';
+
+import type {
+  ContextFilterFn,
+  ContextItem,
+  QueryContextParameters,
+  RelatedContextParameters,
+} from './types';
+import type { GetContextParameters } from './client/ContextClient';
+import type { IContextProvider } from './ContextProvider';
+
+/**
+ * Resolved configuration for the context module.
+ *
+ * Holds query clients, type filters, parent-connection settings, and
+ * optional callbacks for validation, resolution, and path integration.
+ * Produced by {@link ContextModuleConfigurator.createConfigAsync} after all
+ * registered config builders have run.
+ *
+ * @see IContextModuleConfigurator — fluent API for populating this config.
+ * @see ContextProvider — runtime consumer of this config.
+ */
+export interface ContextModuleConfig {
+  /**
+   * Query client options used to fetch, search, and resolve related context items.
+   *
+   * - `get` — retrieves a single context item by ID.
+   * - `query` — searches context items by text and optional type filter.
+   * - `related` — fetches context items related to a given item (used during resolution).
+   */
+  client: {
+    get: QueryCtorOptions<ContextItem, GetContextParameters>;
+    query: QueryCtorOptions<ContextItem[], QueryContextParameters>;
+    related?: QueryCtorOptions<ContextItem[], RelatedContextParameters>;
+  };
+
+  /**
+   * Allowed context type IDs (e.g. `['ProjectMaster', 'Facility']`).
+   *
+   * When set, {@link ContextProvider.validateContext} only accepts items
+   * whose `type.id` matches one of these values (case-insensitive).
+   */
+  contextType?: string[];
+
+  /**
+   * Optional post-query filter applied to the result set returned by
+   * {@link ContextProvider.queryContext}.
+   */
+  contextFilter?: ContextFilterFn;
+
+  /**
+   * Whether to connect the context module to a parent context module.
+   *
+   * When `true` (the default), the provider subscribes to the parent's
+   * `currentContext$` and mirrors changes into its own state.
+   *
+   * @defaultValue `true`
+   */
+  connectParentContext?: boolean;
+
+  /**
+   * When `true`, skips resolving an initial context from the path or parent
+   * during module post-initialization.
+   */
+  skipInitialContext?: boolean;
+
+  /**
+   * Extracts a context ID from a URL path segment.
+   *
+   * Used during initial context resolution and deep-link support.
+   * If not provided, the default GUID-based extractor is used.
+   *
+   * @param path - The URL path to inspect.
+   * @returns The extracted context ID, or `undefined` if none is found.
+   */
+  extractContextIdFromPath?: (path: string) => string | undefined;
+
+  /**
+   * Generates a URL path that embeds the given context item's ID.
+   *
+   * Used by navigation integrations to update the browser URL when
+   * the context changes.
+   *
+   * @param context - The active context item.
+   * @param path - The current URL path.
+   * @returns The updated path, or `undefined` to leave it unchanged.
+   */
+  generatePathFromContext?: (context: ContextItem, path: string) => string | undefined;
+
+  /**
+   * Transforms a user search string and the configured context type into
+   * the query parameters sent to the context API.
+   *
+   * Override this to customise how free-text searches are mapped to the
+   * backend query contract.
+   */
+  contextParameterFn?: (args: {
+    search: string;
+    type: ContextModuleConfig['contextType'];
+  }) => string | QueryContextParameters;
+
+  /**
+   * Custom context resolution strategy.
+   *
+   * Called with `this` bound to the {@link IContextProvider} when a context
+   * item fails validation and the caller requests resolution.
+   *
+   * @param item - The context item to resolve, or `null`.
+   * @returns An observable emitting the resolved context item.
+   */
+  resolveContext?: (
+    this: IContextProvider,
+    item: ContextItem | null,
+  ) => ReturnType<IContextProvider['resolveContext']>;
+
+  /**
+   * Custom context validation strategy.
+   *
+   * Called with `this` bound to the {@link IContextProvider} to decide
+   * whether a candidate context item is acceptable.
+   *
+   * @param item - The context item to validate, or `null`.
+   * @returns `true` if the item is valid.
+   */
+  validateContext?: (
+    this: IContextProvider,
+    item: ContextItem | null,
+  ) => ReturnType<IContextProvider['validateContext']>;
+
+  /**
+   * Resolves the initial context during module post-initialization.
+   *
+   * The default implementation tries to extract a context ID from the
+   * current navigation path, falling back to the parent provider's context.
+   *
+   * @param args - Module reference and instance map.
+   * @returns An observable input emitting the initial context item, or void.
+   */
+  resolveInitialContext?: (args: {
+    // 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>;
+}

package/src/ContextModuleConfigurator.interface.ts

@@ -0,0 +1,145 @@
+import type { Modules, ModuleType } from '@equinor/fusion-framework-module';
+import type { QueryCtorOptions, QueryFn } from '@equinor/fusion-query';
+
+import type { ContextModuleConfig } from './ContextModuleConfig';
+import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
+import type { GetContextParameters } from './client/ContextClient';
+
+/**
+ * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
+ *
+ * Receives the {@link IContextModuleConfigurator} itself and may use its
+ * setter methods to populate the context module configuration. The
+ * callback may be async.
+ */
+export type ContextConfigBuilderCallback = (
+  builder: IContextModuleConfigurator,
+) => void | Promise<void>;
+
+/**
+ * Public configurator contract for the context module.
+ *
+ * Consumers call {@link addConfigBuilder} to register one or more
+ * {@link ContextConfigBuilderCallback} functions that will run during
+ * module initialization to populate the {@link ContextModuleConfig}, using
+ * the fluent setter methods declared below.
+ */
+export interface IContextModuleConfigurator {
+  /**
+   * Registers a configuration callback that receives this configurator.
+   *
+   * Multiple builders can be added; they execute sequentially against the
+   * same configurator instance, so later calls win when they touch the
+   * same field.
+   *
+   * @param init - Builder callback invoked during module initialization.
+   */
+  addConfigBuilder: (init: ContextConfigBuilderCallback) => void;
+
+  /**
+   * Requires a module instance by its registered key or name.
+   *
+   * Only resolvable from within a {@link ContextConfigBuilderCallback} —
+   * throws if called before module initialization has started.
+   *
+   * @param module - The key or name 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]>>;
+  requireInstance<T>(module: string): Promise<T>;
+
+  /**
+   * Sets the context type for the current configuration.
+   *
+   * @param type - The context type to assign, as defined by `ContextModuleConfig['contextType']`.
+   */
+  setContextType(type: ContextModuleConfig['contextType']): void;
+
+  /**
+   * 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']): void;
+
+  /**
+   * 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']): void;
+
+  /**
+   * 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']): void;
+
+  /**
+   * 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']): void;
+
+  /**
+   * 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']): void;
+
+  /**
+   * Sets the function responsible for extracting the context ID from a given path.
+   *
+   * @param fn - A function that defines how to extract the context ID from a path.
+   *             This function should match the type defined in `ContextModuleConfig['extractContextIdFromPath']`.
+   */
+  setContextPathExtractor(fn: ContextModuleConfig['extractContextIdFromPath']): void;
+
+  /**
+   * Sets the function responsible for generating a path from the context.
+   *
+   * @param fn - A function that takes a context and generates a corresponding path.
+   */
+  setContextPathGenerator(fn: ContextModuleConfig['generatePathFromContext']): void;
+
+  /**
+   * Sets the function used to resolve the initial context during module post-initialization.
+   *
+   * @param fn - A function that returns an observable input emitting the initial context item.
+   *             The default resolver extracts a context ID from the navigation path, falling
+   *             back to the parent provider's current context.
+   */
+  setResolveInitialContext(fn: ContextModuleConfig['resolveInitialContext']): void;
+
+  /**
+   * 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:
+        | QueryFn<ContextItem, GetContextParameters>
+        | QueryCtorOptions<ContextItem, GetContextParameters>;
+      query:
+        | QueryFn<ContextItem[], QueryContextParameters>
+        | QueryCtorOptions<ContextItem[], QueryContextParameters>;
+      related?:
+        | QueryFn<ContextItem[], RelatedContextParameters>
+        | QueryCtorOptions<ContextItem[], RelatedContextParameters>;
+    },
+    expire?: number,
+  ): void;
+}

package/src/ContextModuleConfigurator.ts

@@ -0,0 +1,295 @@
+import { from, lastValueFrom } from 'rxjs';
+
+import {
+  BaseConfigBuilder,
+  type ModuleInitializerArgs,
+  type ModulesInstanceType,
+  type Modules,
+  type ModuleType,
+} 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 type { QueryCtorOptions, QueryFn } from '@equinor/fusion-query';
+import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
+import type { GetContextParameters } from './client/ContextClient';
+import resolveInitialContext from './utils/resolve-initial-context';
+import type { ContextModuleConfig } from './ContextModuleConfig';
+import type {
+  ContextConfigBuilderCallback,
+  IContextModuleConfigurator,
+} from './ContextModuleConfigurator.interface';
+
+export type { ContextModuleConfig } from './ContextModuleConfig';
+export type {
+  ContextConfigBuilderCallback,
+  IContextModuleConfigurator,
+} from './ContextModuleConfigurator.interface';
+
+/**
+ * Default implementation of {@link IContextModuleConfigurator}.
+ *
+ * Collects {@link ContextConfigBuilderCallback} registrations and, when
+ * {@link createConfigAsync} is called, runs them in order — each callback
+ * receives this configurator itself and populates the config through its
+ * setter methods, which register into {@link BaseConfigBuilder._set} — to
+ * produce the final {@link ContextModuleConfig}.
+ *
+ * If no custom client is configured, the configurator falls back to
+ * creating one from the {@link ServicesModule} API provider.
+ *
+ * @remarks
+ * Extends {@link BaseConfigBuilder} and fully reuses its `_set`/`_buildConfig`
+ * machinery. Setters always pass an `async () => value` callback to `_set`,
+ * never the raw value directly — `_set` decides whether it received a value
+ * or a deferred callback by checking `typeof value_or_cb === 'function'`, so
+ * fields that are themselves functions (e.g. `validateContext`) would
+ * otherwise be misread as callbacks and invoked instead of stored.
+ */
+export class ContextModuleConfigurator
+  extends BaseConfigBuilder<ContextModuleConfig>
+  implements IContextModuleConfigurator
+{
+  /** Default cache TTL (in ms) for context query results. */
+  defaultExpireTime = 1 * 60 * 1000;
+
+  #configBuilders: Array<ContextConfigBuilderCallback> = [];
+  #init?: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>;
+
+  /** @inheritdoc */
+  addConfigBuilder(init: ContextConfigBuilderCallback): void {
+    this.#configBuilders.push(init);
+  }
+
+  /** @inheritdoc */
+  requireInstance<TKey extends string = Extract<keyof Modules, string>>(
+    module: TKey,
+  ): Promise<ModuleType<Modules[TKey]>>;
+  /** @inheritdoc */
+  requireInstance<T>(module: string): Promise<T>;
+  /** @inheritdoc */
+  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> {
+    // requireInstance is only meaningful once module initialization has begun and #init is set
+    if (!this.#init) {
+      throw Error('requireInstance can only be called during module configuration');
+    }
+    // #init's requireInstance is narrowed to this module's own declared deps; widen for the public any-module overload above
+    return this.#init.requireInstance(module as never);
+  }
+
+  /** @inheritdoc */
+  setContextType(type: ContextModuleConfig['contextType']): void {
+    this._set('contextType', async () => type);
+  }
+
+  /** @inheritdoc */
+  setContextFilter(filter: ContextModuleConfig['contextFilter']): void {
+    this._set('contextFilter', async () => filter);
+  }
+
+  /** @inheritdoc */
+  connectParentContext(connect: ContextModuleConfig['connectParentContext']): void {
+    this._set('connectParentContext', async () => connect);
+  }
+
+  /** @inheritdoc */
+  setContextParameterFn(fn: ContextModuleConfig['contextParameterFn']): void {
+    this._set('contextParameterFn', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setValidateContext(fn: ContextModuleConfig['validateContext']): void {
+    this._set('validateContext', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setResolveContext(fn: ContextModuleConfig['resolveContext']): void {
+    this._set('resolveContext', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setContextPathExtractor(fn: ContextModuleConfig['extractContextIdFromPath']): void {
+    this._set('extractContextIdFromPath', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setContextPathGenerator(fn: ContextModuleConfig['generatePathFromContext']): void {
+    this._set('generatePathFromContext', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setResolveInitialContext(fn: ContextModuleConfig['resolveInitialContext']): void {
+    this._set('resolveInitialContext', async () => fn);
+  }
+
+  /** @inheritdoc */
+  setContextClient(
+    client: {
+      get:
+        | QueryFn<ContextItem, GetContextParameters>
+        | QueryCtorOptions<ContextItem, GetContextParameters>;
+      query:
+        | QueryFn<ContextItem[], QueryContextParameters>
+        | QueryCtorOptions<ContextItem[], QueryContextParameters>;
+      related?:
+        | QueryFn<ContextItem[], RelatedContextParameters>
+        | QueryCtorOptions<ContextItem[], RelatedContextParameters>;
+    },
+    expire = 1 * 60 * 1000,
+  ): void {
+    const clientConfig: ContextModuleConfig['client'] = {
+      get:
+        typeof client.get === 'function'
+          ? {
+              key: ({ id }) => id,
+              client: {
+                fn: client.get,
+              },
+              expire,
+            }
+          : client.get,
+      query:
+        typeof client.query === 'function'
+          ? {
+              // TODO(#5118) - might cast to checksum
+              key: (args) => JSON.stringify(args),
+              client: {
+                fn: client.query,
+              },
+              expire,
+            }
+          : client.query,
+    };
+    // only override the related-context client config if one was provided
+    if (client.related) {
+      clientConfig.related =
+        typeof client.related === 'function'
+          ? {
+              // TODO(#5118) - might cast to checksum
+              key: (args) => JSON.stringify(args),
+              client: {
+                fn: client.related,
+              },
+              expire,
+            }
+          : client.related;
+    }
+    this._set('client', async () => clientConfig);
+  }
+
+  /**
+   * Resolves the services API provider, preferring the local module
+   * instance and falling back to the parent module.
+   *
+   * @param init - Module initializer arguments.
+   * @returns The resolved API provider.
+   * @throws Error if no services module is available.
+   */
+  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]');
+    }
+    return parentServiceModule;
+  }
+
+  /**
+   * Runs all registered config builders, then resolves the accumulated
+   * `_set` registrations into the final {@link ContextModuleConfig}.
+   *
+   * @param init - Module initializer arguments including dependency instances.
+   * @param initial - Optional partial config inherited from a parent module.
+   * @returns The fully resolved context module configuration.
+   */
+  protected async _createConfig(
+    init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
+    initial?: Partial<ContextModuleConfig>,
+  ): Promise<ContextModuleConfig> {
+    // requireInstance resolves lazily against this init for the remainder of config building
+    this.#init = init;
+
+    // run each registered config builder in sequence; each calls setXxx(), registering into _set
+    await this.#configBuilders.reduce((prev, cb) => prev.then(() => cb(this)), Promise.resolve());
+
+    // resolve every registered _set callback into the actual config object
+    const config = await lastValueFrom(from(this._buildConfig(init, initial)));
+
+    // route through _processConfig, so a subclass overriding it (e.g. ContextMockConfigurator) still runs
+    return lastValueFrom(from(this._processConfig(config, init)));
+  }
+
+  /**
+   * Defaults `resolveInitialContext` and `client` when a builder callback
+   * didn't set them.
+   *
+   * If no `resolveInitialContext` was set, the default path + parent
+   * resolver is used. If no `client` was set, one is created from the
+   * {@link ServicesModule} API provider.
+   *
+   * @param config - The config accumulated from registered builder callbacks.
+   * @param init - Module initializer arguments including dependency instances.
+   * @returns The fully resolved context module configuration.
+   */
+  protected async _processConfig(
+    config: Partial<ContextModuleConfig>,
+    init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
+  ): Promise<ContextModuleConfig> {
+    config.resolveInitialContext ??= resolveInitialContext({
+      path: {
+        extract: config.extractContextIdFromPath,
+        validate: config.extractContextIdFromPath ? () => true : undefined,
+      },
+    });
+
+    // TODO(#5119) - make less lazy
+    config.client ??= await (async (): Promise<ContextModuleConfig['client']> => {
+      const apiProvider = await this._getServiceProvider(init);
+      const contextClient = await apiProvider.createContextClient('json$');
+      return {
+        get: {
+          client: {
+            fn: (args) => contextClient.get('v1', args, { selector: getContextSelector }),
+          },
+          key: ({ id }) => id,
+          expire: this.defaultExpireTime,
+        },
+        query: {
+          client: {
+            fn: (query) => contextClient.query('v1', { query }, { selector: queryContextSelector }),
+          },
+          // TODO(#5118) - might cast to checksum
+          key: (args) => JSON.stringify(args),
+          expire: this.defaultExpireTime,
+        },
+        related: {
+          client: {
+            fn: (args) => {
+              return contextClient.related(
+                'v1',
+                { id: args.item.id, query: { filter: args.filter } },
+                { selector: relatedContextSelector },
+              );
+            },
+          },
+          // TODO(#5118) - might cast to checksum
+          key: (args) => JSON.stringify(args),
+          expire: this.defaultExpireTime,
+        },
+      };
+    })();
+
+    return config as ContextModuleConfig;
+  }
+}
+
+export default ContextModuleConfigurator;

package/src/ContextProvider.ts

@@ -10,7 +10,7 @@ import {
   tap,
 } from 'rxjs/operators';
 
-import type { ContextModuleConfig } from './configurator';
+import type { ContextModuleConfig } from './ContextModuleConfig';
 
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 import { version } from './version.js';
@@ -505,7 +505,6 @@ export class ContextProvider
         .pipe(
           // resolve context item from queue
           switchMap((next) => next),
-          tap((x) => console.debug('ContextProvider::#contextQueue', x)),
         )
         .subscribe((context) => {
           // set context from resolved context item from queue