@equinor/fusion-framework-module-context 8.0.2 → 9.0.0-next.0

package/src/ContextConfigBuilder.ts

@@ -1,258 +0,0 @@
-import type {
-  AnyModule,
-  ModuleInitializerArgs,
-  Modules,
-  ModuleType,
-} from '@equinor/fusion-framework-module';
-
-import type { QueryCtorOptions, QueryFn } from '@equinor/fusion-query';
-
-import type { GetContextParameters } from './client/ContextClient';
-
-import type {
-  ContextModuleConfig,
-  ContextModuleConfigurator,
-  IContextModuleConfigurator,
-} from './configurator';
-
-import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
-
-/**
- * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
- *
- * Receives a {@link ContextConfigBuilder} and may use its setter methods
- * to populate the context module configuration. The callback may be async.
- *
- * @typeParam TDeps - Module dependency array inferred from the configurator.
- */
-export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>(
-  builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>,
-) => void | Promise<void>;
-
-/**
- * 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(#5120) - this should extend the BaseConfigBuilder
- *
- * @see ContextModuleConfig
- * @see ModuleInitializerArgs
- */
-export class ContextConfigBuilder<
-  TModules extends Array<AnyModule> = [],
-  // biome-ignore lint/suspicious/noExplicitAny: `ModuleInitializerArgs<any, any>` widens the constraint to accept initializer args for any configurator/module set \u2014 `unknown` breaks assignability of the concrete default type argument
-  TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<
-    ContextModuleConfigurator,
-    TModules
-  >,
-> {
-  #init: TInit;
-  /**
-   * Creates a new `ContextConfigBuilder`.
-   * @param init - Module initializer arguments used to resolve module instances.
-   * @param config - The partial context module config to build upon.
-   */
-  constructor(
-    init: TInit,
-    public config: Partial<ContextModuleConfig> = {},
-  ) {
-    this.#init = init;
-  }
-
-  /**
-   * Requires a module instance by its registered key.
-   * @param module - The key 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]>>;
-
-  /**
-   * Requires a module instance by name.
-   * @param module - The name of the module to resolve.
-   * @returns A promise that resolves to the requested module instance.
-   */
-  requireInstance<T>(module: string): Promise<T>;
-
-  /**
-   * Requires a module instance by key or name.
-   * @param module - The key or name of the module to resolve.
-   * @returns A promise that resolves to the requested module instance.
-   */
-  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> {
-    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;
-  }
-
-  /**
-   * 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']) {
-    this.config.extractContextIdFromPath = fn;
-  }
-
-  /**
-   * 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']) {
-    this.config.generatePathFromContext = fn;
-  }
-
-  /**
-   * 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']) {
-    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:
-        | 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,
-    };
-    this.config.client = clientConfig;
-    // 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;
-    }
-  }
-}

package/src/configurator.ts

@@ -1,295 +0,0 @@
-import type { ObservableInput } from 'rxjs';
-
-import type {
-  AnyModuleInstance,
-  ModuleInitializerArgs,
-  ModuleInstance,
-  ModulesInstanceType,
-} 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 './get-context-selector';
-import type { QueryCtorOptions } from '@equinor/fusion-query';
-import type {
-  ContextFilterFn,
-  ContextItem,
-  QueryContextParameters,
-  RelatedContextParameters,
-} from './types';
-import type { GetContextParameters } from './client/ContextClient';
-import { ContextConfigBuilder, type ContextConfigBuilderCallback } from './ContextConfigBuilder';
-import type { IContextProvider } from './ContextProvider';
-import resolveInitialContext from './utils/resolve-initial-context';
-
-/**
- * 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.createConfig} after all
- * {@link ContextConfigBuilder} callbacks have run.
- *
- * @see ContextConfigBuilder — 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>;
-}
-
-/**
- * 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}.
- */
-export interface IContextModuleConfigurator {
-  /**
-   * Registers a configuration callback that receives a {@link ContextConfigBuilder}.
-   *
-   * Multiple builders can be added; they execute sequentially and merge
-   * their results into a single {@link ContextModuleConfig}.
-   *
-   * @param init - Builder callback invoked during module initialization.
-   */
-  addConfigBuilder: (init: ContextConfigBuilderCallback) => void;
-}
-
-/**
- * Default implementation of {@link IContextModuleConfigurator}.
- *
- * Collects {@link ContextConfigBuilderCallback} registrations and, when
- * {@link createConfig} is called, runs them in order against a
- * {@link ContextConfigBuilder} 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.
- */
-export class ContextModuleConfigurator implements IContextModuleConfigurator {
-  /** Default cache TTL (in ms) for context query results. */
-  defaultExpireTime = 1 * 60 * 1000;
-
-  #configBuilders: Array<ContextConfigBuilderCallback> = [];
-
-  /** @inheritdoc */
-  addConfigBuilder(init: ContextConfigBuilderCallback): void {
-    this.#configBuilders.push(init);
-  }
-
-  /**
-   * 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 and produces the final
-   * {@link ContextModuleConfig}.
-   *
-   * 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 init - Module initializer arguments including dependency instances.
-   * @returns The fully resolved context module configuration.
-   */
-  public async createConfig(
-    init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
-  ): Promise<ContextModuleConfig> {
-    // run each registered config builder in sequence, merging results into the accumulated config
-    const config = await this.#configBuilders.reduce(
-      async (cur, cb) => {
-        // biome-ignore lint/suspicious/noExplicitAny: builder generics are erased here — `unknown` breaks assignability of the concrete `ContextConfigBuilder` instance passed to consumer callbacks
-        const builder = new ContextConfigBuilder<any, any>(init, await cur);
-        await Promise.resolve(cb(builder));
-        // Merge this builder's config into the accumulator for the next iteration.
-        return Object.assign(cur, builder.config);
-      },
-      Promise.resolve({} as Partial<ContextModuleConfig>),
-    );
-
-    config.resolveInitialContext ??= resolveInitialContext();
-
-    // 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;