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

package/src/mock/index.ts

@@ -1,33 +0,0 @@
-/**
- * Mock context module for tests: real provider, real configurator, in-memory data.
- *
- * @remarks
- * Substituting the data source is the smallest change that removes the context
- * API, HTTP mocking, and service-discovery mocking from a test. Everything
- * above it — validation, resolution, parent-context propagation, initial-context
- * selection — is the production code path.
- *
- * This is one of two ways to mock context data in tests: a small, static,
- * in-memory pool (this module — no HTTP layer involved at all). The other is
- * mocking the context API's HTTP responses directly (e.g. with MSW), which
- * exercises the real `ContextModuleConfigurator`/services/HTTP pipeline —
- * reach for that instead when the test needs to cover that pipeline itself.
- * For fixture generators with realistic fake data, see
- * `@equinor/fusion-framework-module-context/mock/fixtures`.
- *
- * @example
- * ```typescript
- * import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
- *
- * enableContextMock(configurator, (mock) => {
- *   mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
- * });
- * ```
- *
- * @packageDocumentation
- */
-export {
-  ContextMockConfigurator,
-  type ContextResolverFn,
-} from './ContextMockConfigurator';
-export { enableContextMock, contextMockModule, type ContextMockConfigFn } from './module';

package/src/mock/module.ts

@@ -1,54 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-
-import { module, type ContextModule } from '../module';
-
-import { ContextMockConfigurator } from './ContextMockConfigurator';
-
-/**
- * The context module with an in-memory mock configurator instead of a real
- * context API.
- *
- * @remarks
- * Only `configure` differs from the real module. `initialize` is the production
- * one, untouched, so a test exercises the real `ContextProvider` startup path,
- * `validateContext`/`resolveContext`, and parent-context propagation — a
- * rehearsal of the module, not a stand-in for it.
- */
-export const contextMockModule: ContextModule = {
-  ...module,
-  configure: () => new ContextMockConfigurator(),
-};
-
-/**
- * Configuration callback for {@link enableContextMock}.
- */
-export type ContextMockConfigFn = (mock: ContextMockConfigurator) => void | Promise<void>;
-
-/**
- * Enables the context module against in-memory seeded data, so a test needs no
- * context API, no HTTP mock, and no service-discovery mock.
- *
- * @remarks
- * Registered last, this replaces whichever context module the configurator
- * already carries, so it works on a `FrameworkConfigurator` that pre-registers
- * the real one.
- *
- * @param configurator - The modules configurator to register on.
- * @param configure - Optional callback to seed context items or override resolution.
- *
- * @example
- * ```ts
- * enableContextMock(configurator, (mock) => {
- *   mock.setCurrentContext({ id: 'my-ctx', type: { id: 'ProjectMaster' }, value: {} });
- * });
- * ```
- */
-export const enableContextMock = (
-  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
-  configurator: IModulesConfigurator<any, any>,
-  configure?: ContextMockConfigFn,
-): void => {
-  configurator.addConfig({ module: contextMockModule, configure } as {
-    module: ContextModule;
-  });
-};

package/src/module.ts

@@ -1,178 +0,0 @@
-import { catchError, EMPTY, from, Observable, switchMap, filter, Subscription } from 'rxjs';
-
-import type { Module, ModulesInstance } from '@equinor/fusion-framework-module';
-
-import type { EventModule } from '@equinor/fusion-framework-module-event';
-import type { ServicesModule } from '@equinor/fusion-framework-module-services';
-import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
-import {
-  TelemetryLevel,
-  TelemetryScope,
-  type TelemetryModule,
-} from '@equinor/fusion-framework-module-telemetry';
-
-import {
-  type IContextModuleConfigurator,
-  ContextModuleConfigurator,
-} from './ContextModuleConfigurator';
-import { type IContextProvider, ContextProvider } from './ContextProvider';
-import type { ContextItem } from './types';
-
-/**
- * Literal type identifying the context module within the Fusion Framework module system.
- *
- * Used as the key when registering or looking up the module in a `Modules` map.
- */
-export type ContextModuleKey = 'context';
-
-/**
- * Module registration key for the context module.
- *
- * Pass this value—or reference it as `contextModuleKey`—when you need to
- * identify the context module by name at runtime (e.g., `hasModule(contextModuleKey)`).
- */
-export const moduleKey: ContextModuleKey = 'context';
-
-/**
- * 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, TelemetryModule] - The tuple of dependent modules required by the context module.
- *
- * @see Module
- */
-export type ContextModule = Module<
-  ContextModuleKey,
-  IContextProvider,
-  IContextModuleConfigurator,
-  [ServicesModule, EventModule, NavigationModule, TelemetryModule]
->;
-
-/**
- * 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 const module: ContextModule = {
-  name: moduleKey,
-  configure: () => new ContextModuleConfigurator(),
-  initialize: async function (args) {
-    // create config from configurator
-    const config = await (args.config as ContextModuleConfigurator).createConfigAsync(args);
-
-    // get event module if available
-    const event = args.hasModule('event') ? await args.requireInstance('event') : undefined;
-
-    // get telemetry module if available, for tracking context resolution outcomes
-    const telemetry = args.hasModule('telemetry')
-      ? await args.requireInstance('telemetry')
-      : undefined;
-
-    // get parent context provider if available
-    const parentProvider = (args.ref as ModulesInstance<[ContextModule]>)?.context;
-
-    // create context provider; parent context is wired up later via connectParentContext, not the deprecated ctor arg
-    const provider = new ContextProvider({ config, event });
-
-    // 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; // if no initial context is available, complete immediately
-
-        // add teardown to resolve initial context
-        subscriber.add(
-          resolveInitialContext$
-            .pipe(
-              catchError((err) => {
-                const exception = err instanceof Error ? err : new Error(String(err));
-                // report through telemetry when available, otherwise fall back to console.warn below
-                if (telemetry) {
-                  telemetry.trackException({
-                    name: 'Context::postInitialize.resolveInitialContext',
-                    exception,
-                    level: TelemetryLevel.Warning,
-                    scope: ['context', TelemetryScope.Framework],
-                  });
-                } else {
-                  // no telemetry module registered - fall back to a visible warning so a
-                  // genuine resolution failure isn't silently swallowed
-                  console.warn('Context::postInitialize.resolveInitialContext', exception);
-                }
-                // failed to resolve initial context, complete immediately
-                return EMPTY;
-              }),
-            )
-            .subscribe({
-              next: (item) => {
-                telemetry?.trackEvent({
-                  name: 'Context::postInitialize.initialContextResolved',
-                  level: TelemetryLevel.Debug,
-                  scope: ['context', TelemetryScope.Framework],
-                  properties: { contextId: item ? item.id : 'none' },
-                });
-              },
-              complete: () => {
-                // connect parent context if available when stream completes
-                if (config.connectParentContext !== false && parentProvider) {
-                  provider.connectParentContext(parentProvider);
-                  telemetry?.trackEvent({
-                    name: 'Context::postInitialize.parentContextConnected',
-                    level: TelemetryLevel.Debug,
-                    scope: ['context', TelemetryScope.Framework],
-                  });
-                }
-                subscriber.complete();
-              },
-            }),
-        );
-      });
-
-    // add teardown to module
-    this.dispose = () => subscription.unsubscribe();
-
-    return provider;
-  },
-};
-
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    context: ContextModule;
-  }
-}
-
-export default module;

package/src/selectors/get-context-selector.ts

@@ -1,14 +0,0 @@
-import type { GetContextResponse } from '@equinor/fusion-framework-module-services/context/get';
-
-import { parseContextItem } from '../utils/parse-context-item';
-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 const getContextSelector = async (response: Response): Promise<ContextItem> => {
-  const result = (await response.json()) as GetContextResponse<'v1'>;
-  return parseContextItem(result);
-};

package/src/selectors/index.ts

@@ -1,12 +0,0 @@
-/**
- * Response selectors that parse raw context API responses into {@link ContextItem}s.
- *
- * - {@link getContextSelector} — parses a single-item GetContext response.
- * - {@link queryContextSelector} — parses a multi-item QueryContext response.
- * - {@link relatedContextSelector} — parses a multi-item RelatedContext response.
- *
- * @packageDocumentation
- */
-export { getContextSelector } from './get-context-selector';
-export { queryContextSelector } from './query-context-selector';
-export { relatedContextSelector } from './related-context-selector';

package/src/selectors/query-context-selector.ts

@@ -1,15 +0,0 @@
-import type { QueryContextResponse } from '@equinor/fusion-framework-module-services/context/query';
-
-import { parseContextItem } from '../utils/parse-context-item';
-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 const queryContextSelector = async (response: Response): Promise<ContextItem[]> => {
-  const result = (await response.json()) as QueryContextResponse<'v1'>;
-  // parse each raw API entry into a ContextItem
-  return result.map(parseContextItem);
-};

package/src/selectors/related-context-selector.ts

@@ -1,15 +0,0 @@
-import type { RelatedContextResponse } from '@equinor/fusion-framework-module-services/context/related';
-
-import { parseContextItem } from '../utils/parse-context-item';
-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 const relatedContextSelector = async (response: Response): Promise<ContextItem[]> => {
-  const result = (await response.json()) as RelatedContextResponse<'v1'>;
-  // parse each raw API entry into a ContextItem
-  return result.map(parseContextItem);
-};

package/src/types.ts

@@ -1,98 +0,0 @@
-/**
- * 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(#5122) - convert to Zod schema for validation and type safety.
- */
-export type ContextItem<TType extends Record<string, unknown> = Record<string, unknown>> = {
-  id: string;
-  externalId?: string;
-  source?: string;
-  type: ContextItemType;
-  value: TType;
-  title?: string;
-  subTitle?: string;
-  isActive?: boolean;
-  isDeleted?: boolean;
-  created?: Date;
-  updated?: Date;
-  graphic?:
-    | string
-    | {
-        type: 'html' | 'svg';
-        content: string;
-      };
-  meta?:
-    | string
-    | {
-        type: 'html' | 'svg';
-        content: string;
-      };
-};
-
-/**
- * Describes the type classification of a {@link ContextItem}.
- *
- * Every context item carries a `type` that identifies what kind of
- * entity it represents (e.g. `ProjectMaster`, `Facility`, `Contract`).
- * The optional hierarchy fields indicate parent–child relationships
- * between context types.
- */
-export interface ContextItemType {
-  /** Unique identifier for the context type (e.g. `'ProjectMaster'`). */
-  id: string;
-  /** Whether this type is a child of another context type. */
-  isChildType?: boolean;
-  /** IDs of parent context types, when `isChildType` is `true`. */
-  parentTypeIds?: string[];
-}
-
-/**
- * Parameters for querying context items from the context API.
- *
- * Used by {@link ContextProvider.queryContext} and the underlying
- * query client to search and filter context results.
- *
- * @property search - Free-text search term.
- * @property filter - Optional structured filters.
- * @property filter.type - Restrict results to specific context type IDs.
- * @property filter.externalId - Filter by an external system identifier.
- */
-export type QueryContextParameters = {
-  search?: string;
-  filter?: {
-    type?: string[];
-    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/src/utils/enable-context.ts

@@ -1,40 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-import type {
-  ContextConfigBuilderCallback,
-  IContextModuleConfigurator,
-} from '../ContextModuleConfigurator.interface';
-
-import { module } from '../module';
-
-/**
- * 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 the {@link IContextModuleConfigurator}. 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 const enableContext = (
-  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
-  configurator: IModulesConfigurator<any, any>,
-  builder?: ContextConfigBuilderCallback,
-): void => {
-  configurator.addConfig({
-    module,
-    configure: (contextConfigurator) => {
-      builder && contextConfigurator.addConfigBuilder(builder);
-    },
-  });
-};

package/src/utils/extract-context-id-from-path.ts

@@ -1,39 +0,0 @@
-// 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})$/;
-
-/**
- * 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 const extractContextIdFromPath = (
-  path: string,
-  matcher: RegExp = matchGUID,
-): string | undefined =>
-  //
-  path
-    // remove query-string and hash fragments before segment matching
-    .split(/[?#]/)[0]
-    // remove leading slashes
-    .replace(/^\/+/, '')
-    // split path by slashes
-    .split('/')
-    // find the first path fragment that matches the matcher
-    .find((x) => x.match(matcher));

package/src/utils/index.ts

@@ -1,15 +0,0 @@
-/**
- * Utility functions for context module configuration and initialization.
- *
- * - {@link enableContext} — register the context module on a configurator.
- * - {@link resolveInitialContext} — default initial-context resolver (path → parent fallback).
- * - {@link extractContextIdFromPath} — extract a GUID context ID from a URL path.
- * - {@link resolveContextFromPath} — resolve a context item from a URL path.
- * - {@link parseContextItem} — parse a raw API context entity into a `ContextItem`.
- *
- * @packageDocumentation
- */
-export { enableContext } from './enable-context';
-export { resolveInitialContext } from './resolve-initial-context';
-export { extractContextIdFromPath, resolveContextFromPath } from './resolve-context-from-path';
-export { parseContextItem } from './parse-context-item';

package/src/utils/parse-context-item.ts

@@ -1,39 +0,0 @@
-import type {
-  ApiVersion,
-  ApiContextEntity,
-} from '@equinor/fusion-framework-module-services/context';
-import type { GetContextResponse } from '@equinor/fusion-framework-module-services/context/get';
-
-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.
- */
-export const parseContextItem = (item: ApiContextEntity<ApiVersion.v1>): ContextItem => {
-  return {
-    id: item.id,
-    externalId: item.externalId ?? undefined,
-    isActive: item.isActive,
-    isDeleted: item.isDeleted,
-    created: new Date(item.created),
-    source: item.source ?? undefined,
-    title: item.title ?? undefined,
-    type: parseContextType(item.type),
-    // TODO(#5115): parse and map the raw `value` payload into a typed context item value
-    value: item.value ?? {},
-  };
-};