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

package/src/ContextProvider.ts

@@ -1,1158 +0,0 @@
-import { EMPTY, lastValueFrom, Observable, of, Subject, Subscription, throwError } from 'rxjs';
-import {
-  catchError,
-  filter,
-  finalize,
-  map,
-  pairwise,
-  switchMap,
-  takeUntil,
-  tap,
-} from 'rxjs/operators';
-
-import type { ContextModuleConfig } from './ContextModuleConfig';
-
-import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
-import { version } from './version.js';
-
-import { ContextClient } from './client/ContextClient';
-import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
-import type { ModuleType } from '@equinor/fusion-framework-module';
-import type {
-  EventModule,
-  FrameworkEvent,
-  FrameworkEventInit,
-} from '@equinor/fusion-framework-module-event';
-import Query from '@equinor/fusion-query';
-import type { SemVer } from 'semver';
-
-/**
- * Interface representing a provider for managing and interacting with context items within an application.
- *
- * The `IContextProvider` interface defines a contract for querying, validating, resolving, and managing the current context state.
- * It supports both synchronous and asynchronous operations, as well as observable streams for reactive programming.
- * This interface is intended to be implemented by modules that encapsulate context-related logic, such as user, tenant, or environment context.
- *
- * ## Core Responsibilities
- * - **Querying Contexts:** Search and retrieve context items based on search criteria, both as observables and promises.
- * - **Current Context Management:** Get, set, and clear the current context, with support for validation and resolution.
- * - **Context Resolution:** Resolve context items to their full representation, synchronously or asynchronously.
- * - **Related Contexts:** Retrieve related context items based on specific parameters.
- * - **Path Utilities:** Extract context IDs from paths and generate paths from context items, supporting deep linking and routing.
- * - **Reactive State:** Expose the current context as an observable stream for reactive UI updates.
- *
- * ## Usage Example
- * ```ts
- * const provider: IContextProvider = ...;
- * provider.currentContext$.subscribe(ctx => {
- *   // React to context changes
- * });
- * const items = await provider.queryContextAsync('search-term');
- * ```
- *
- * ## Notes
- * - Some members are marked as **DANGER** and are intended for advanced or internal use only.
- * - Implementations should ensure thread safety and consistency of the current context state.
- * - Optional methods for path extraction and generation enable integration with routing systems.
- *
- * @template T - The shape of the context item data.
- */
-export interface IContextProvider {
-  /** DANGER */
-  readonly contextClient: ContextClient;
-  /** DANGER */
-  readonly queryClient: Query<ContextItem[], QueryContextParameters>;
-
-  /**
-   * Observable stream emitting the current context item.
-   *
-   * - Emits `undefined` if the context has not been initialized.
-   * - Emits `null` when the current context is cleared.
-   * - Emits a `ContextItem` when a valid context is set.
-   *
-   * @example
-   * ```ts
-   * portal.context.currentContext$.subscribe(context => {
-   *   if (context) {
-   *     console.log('Current context:', context);
-   *   } else if (context === null) {
-   *     console.log('Current context cleared');
-   *   }
-   * });
-   * ```
-   */
-  readonly currentContext$: Observable<ContextItem | null | undefined>;
-
-  /**
-   * Snapshot of the current context item.
-   *
-   * @remarks
-   * This property provides the current context item as a snapshot.
-   * It may be `null` or `undefined` if no context is set or if the context is not initialized.
-   * It is intended for synchronous access to the current context state.
-   *
-   * __Use {@link currentContext$} instead of this property to get the current context as an observable stream.__
-   */
-  readonly currentContext: ContextItem | null | undefined;
-
-  /**
-   * Queries the context items based on the provided search string.
-   *
-   * @example
-   * ```ts
-   * portal.context.queryContext('search-term').subscribe(contextItems => {
-   *   console.log('Queried context items:', contextItems);
-   * });
-   * ```
-   *
-   * @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.
-   *
-   * @example
-   * ```ts
-   * portal.context.queryContextAsync('search-term').then(contextItems => {
-   *   console.log('Queried context items:', contextItems);
-   * });
-   * ```
-   *
-   * @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.
-   * This method is used to check if the context item meets the criteria defined in the provider's configuration.
-   *
-   * @example
-   * ```ts
-   * const currentContext = portal.context.currentContext;
-   * if(app.context.validateContext(currentContext)) {
-   *   // the application can safely use the context item
-   * } else {
-   *   // the context item is not valid, handle accordingly
-   * }
-   * ```
-   *
-   * @remarks
-   * This method will use the configured validation function to check if the context item is valid.
-   *
-   * @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.
-   *
-   * This method will try to resolve the context item based on the current context.
-   * This is useful when transferring context items between different parts of the application.
-   *
-   * @remarks
-   * A normal implementation of this method will first validate the context item and if it is not valid,
-   * it will use the {@link relatedContexts} method to find related context items.
-   *
-   * @example
-   *  ```ts
-   * app.context.resolveContext(portal.context.currentContext).subscribe({
-   *   next: (resolvedContext) => {
-   *     // the application can safely use the resolved context item
-   *   },
-   *   error: (err) => {
-   *      // handle error during context resolution
-   *    },
-   *    complete: () => {
-   *      // context resolution completed
-   *    }
-   * });
-   * ```
-   *
-   * @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.
-   *
-   * @see {@link resolveContext} for more details.
-   *
-   * @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.
-   *
-   * @see {@link relatedContexts}
-   *
-   * @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.
-   * This method will set the current context to `null`.
-   */
-  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.
-   *
-   * @see {@link setCurrentContextById}
-   *
-   * @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.
-   *
-   * Optionally validates and resolves the context item based on the provided settings.
-   *
-   * @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.
-   *
-   * @see {@link setCurrentContext}
-   *
-   * @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 },
-  ): Promise<ContextItem<Record<string, unknown>> | null>;
-
-  /**
-   * Method for extracting context id from a path.
-   *
-   * @remarks
-   * This method extracts the context ID from a given path using the extraction method
-   * provided to the provider via the configuration. If no extraction method is configured,
-   * it returns undefined.
-   *
-   * @param path path to resolve context from
-   * @returns the resolved context item id
-   *
-   * @example
-   * ```ts
-   * // configured with extracting id from path like '/context/:id'
-   * provider.extractContextIdFromPath('/context/1234'); // returns '1234'
-   * ```
-   */
-  extractContextIdFromPath?: (path: string) => string | undefined;
-
-  /**
-   * Method for generating path from a context item.
-   *
-   * @remarks
-   * This method generates a path for the context item using the generation method
-   * provided to the provider via the configuration. If no generation method is configured,
-   * it returns undefined.
-   *
-   * @param context context item to generate path from
-   * @param path current path
-   * @returns path for the context item
-   */
-  generatePathFromContext?: (context: ContextItem, path: string) => string | undefined;
-  /**
-   * The version of the context provider.
-   *
-   * @remarks
-   * This property represents the version of the context provider, which can be a string or a SemVer object.
-   */
-  readonly version: string | SemVer;
-}
-
-/**
- * Provides context management functionality, including querying, setting, validating, and resolving context items.
- *
- * The `ContextProvider` class acts as a central service for handling context state, supporting asynchronous operations,
- * event-driven updates, and integration with parent/child context providers. It manages a queue for context changes,
- * supports validation and resolution logic, and can interact with related context items.
- *
- * Key Features:
- * - Maintains the current context and exposes it as both an observable and a property.
- * - Allows querying for context items based on search criteria and filters.
- * - Supports setting the current context by ID or by context item, with optional validation and resolution.
- * - Handles context changes asynchronously, queuing tasks and supporting cancellation.
- * - Integrates with an event module to dispatch and listen for context-related events.
- * - Supports connecting to a parent context provider to synchronize context state.
- * - Provides methods for resolving related contexts and validating context items.
- * - Manages subscriptions and ensures proper resource cleanup via `dispose`.
- *
- * @template T The type of context item managed by the provider.
- *
- * @remarks
- * - Some methods and properties are marked as deprecated and may be removed in future versions.
- * - Event integration is optional and depends on the presence of an event module.
- * - The provider is designed to be extensible and can be configured via the `ContextModuleConfig`.
- *
- * @example
- * ```typescript
- * const provider = new ContextProvider({ config: myConfig, event: myEventModule });
- * provider.setCurrentContextById('context-id').subscribe(...);
- * ```
- */
-export class ContextProvider
-  extends BaseModuleProvider<ContextModuleConfig>
-  implements IContextProvider
-{
-  #contextClient: ContextClient;
-  #contextQuery: Query<Array<ContextItem>, QueryContextParameters>;
-  #contextRelated?: Query<Array<ContextItem>, RelatedContextParameters>;
-
-  #event?: ModuleType<EventModule>;
-
-  #subscriptions = new Subscription();
-
-  #contextType?: ContextModuleConfig['contextType'];
-  #contextFilter: ContextModuleConfig['contextFilter'];
-  #contextParameterFn: Required<ContextModuleConfig>['contextParameterFn'];
-
-  #contextQueue = new Subject<Observable<ContextItem<Record<string, unknown>>>>();
-
-  /**
-   * The underlying context client used to resolve and hold the current context item.
-   * @returns The internal {@link ContextClient} instance.
-   */
-  public get contextClient() {
-    return this.#contextClient;
-  }
-
-  /**
-   * The query client used to search for context items.
-   * @returns The internal `Query` instance used by {@link queryContext}.
-   */
-  public get queryClient() {
-    return this.#contextQuery;
-  }
-
-  /**
-   * Observable stream emitting the current context item.
-   * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
-   */
-  get currentContext$(): Observable<ContextItem | null | undefined> {
-    return this.#contextClient.currentContext$;
-  }
-
-  /**
-   * Snapshot of the current context item.
-   * @returns The current `ContextItem`, or `null`/`undefined` if not set.
-   */
-  get currentContext(): ContextItem | undefined | null {
-    return this.#contextClient.currentContext;
-  }
-
-  /**
-   * Sets the current context item.
-   * @deprecated do not use, will be removed
-   * @param context - The context item to set as current. Must not be `undefined`.
-   * @throws Error if `context` is `undefined`.
-   */
-  set currentContext(context: ContextItem | null | undefined) {
-    console.warn(
-      '@deprecated',
-      'ContextProvider.currentContext',
-      'use setCurrentContextById|setCurrentContext|clearCurrentContext',
-    );
-    // undefined is reserved to mean "not yet initialized", so it cannot be set explicitly
-    if (context === undefined) {
-      throw Error('not allowed to set current context as undefined undefined!');
-    }
-    this.setCurrentContextAsync(context);
-  }
-
-  /**
-   * Creates a new instance of `ContextProvider`.
-   * @param args - Constructor arguments.
-   * @param args.config - The context module configuration.
-   * @param args.event - Optional event module instance for dispatching context change events.
-   * @param args.parentContext - Optional parent context provider. Deprecated, use {@link connectParentContext}.
-   */
-  constructor(args: {
-    config: ContextModuleConfig;
-    event?: ModuleType<EventModule>;
-    /** @deprecated use  ContextProvider.connectParentContext */
-    parentContext?: IContextProvider;
-  }) {
-    const { config, event } = args;
-
-    super({ version, config });
-
-    // warn about deprecated parentContext constructor arg
-    if (args.parentContext) {
-      console.warn(
-        '@deprecated',
-        'parentContext as arg is deprecated, use ContextProvider.connectParentContext',
-      );
-    }
-
-    this.#event = event;
-
-    // set the resolve and validate context functions
-    if (config.resolveContext) {
-      this.resolveContext = config.resolveContext?.bind(this);
-    }
-    // override validateContext if configured
-    if (config.validateContext) {
-      this.validateContext = config.validateContext?.bind(this);
-    }
-
-    // override extractContextIdFromPath if configured
-    if (config.extractContextIdFromPath) {
-      // @ts-expect-error - this is to avoid breaking change, the signature will be updated in future major release
-      this.extractContextIdFromPath = config.extractContextIdFromPath;
-    }
-    // override generatePathFromContext if configured
-    if (config.generatePathFromContext) {
-      // @ts-expect-error - this is to avoid breaking change, the signature will be updated in future major release
-      this.generatePathFromContext = config.generatePathFromContext;
-    }
-
-    this.#contextType = config.contextType;
-    this.#contextFilter = config.contextFilter;
-
-    // create clients
-    this.#contextClient = new ContextClient(config.client.get);
-    this.#contextQuery = new Query(config.client.query);
-
-    // only create the related-context query when the config provides one
-    if (config.client.related) {
-      this.#contextRelated = new Query(config.client.related);
-    }
-
-    // set the context parameter function
-    this.#contextParameterFn =
-      config.contextParameterFn ??
-      // fallback to default
-      ((args: Parameters<Required<ContextModuleConfig>['contextParameterFn']>[0]) => ({
-        search: args.search,
-        filter: { type: args.type },
-      }));
-
-    // if event module is available, setup event listeners
-    if (this.#event) {
-      this.#subscriptions.add(
-        // observe current context changes
-        this.currentContext$
-          // emit previous and next context together for change comparisons
-          .pipe(pairwise())
-          .subscribe(([previous, next]) => {
-            this.#event?.dispatchEvent('onCurrentContextChanged', {
-              source: this,
-              canBubble: true,
-              detail: { previous, next },
-            });
-          }),
-      );
-      this.#subscriptions.add(
-        // observe current context changes from child modules
-        this.#event.addEventListener('onCurrentContextChanged', (e) => {
-          // prevent infinite loop, only set context if source is not this
-          if (e.source !== this && e.detail.next !== undefined) {
-            this.setCurrentContext(e.detail.next);
-          }
-        }),
-      );
-    }
-
-    // wire up context queue
-    this.#subscriptions.add(
-      this.#contextQueue
-        .pipe(
-          // resolve context item from queue
-          switchMap((next) => next),
-        )
-        .subscribe((context) => {
-          // set context from resolved context item from queue
-          this.#contextClient.setCurrentContext(context ?? null);
-        }),
-    );
-  }
-
-  /**
-   * Connects this context provider to a parent context provider, subscribing to changes in the parent's context.
-   *
-   * When the parent context changes, this method will:
-   * - Optionally skip the first emitted value from the parent (if `opt.skipFirst` is true).
-   * - Only update the current context if the context ID has changed.
-   * - Dispatch an `onParentContextChanged` event before updating, allowing for cancellation.
-   * - Set the current context with validation and resolution, handling errors gracefully.
-   *
-   * The subscription is automatically managed and will be cleaned up with the provider.
-   *
-   * @param provider - The parent context provider to connect to.
-   * @param opt - Optional settings.
-   * @param opt.skipFirst - If true, skips the first emitted value from the parent context.
-   * @returns A `Subscription` object representing the connection to the parent context.
-   */
-  public connectParentContext(
-    provider: IContextProvider,
-    opt?: { skipFirst: boolean },
-  ): Subscription {
-    // build a stream of validated context changes from the parent provider
-    const parentContext$ = provider.currentContext$.pipe(
-      // do not set context if parent has not initialized
-      filter((x): x is ContextItem | null => x !== undefined),
-      filter((next, index) => {
-        // skip first item if opt.skipFirst is true
-        // TODO(#5121): this is a bit hacky, should be handled in a better way
-        if (opt?.skipFirst && index <= 1) {
-          console.debug('ContextProvider::connectParentContext', 'skipping first item', next);
-          return false;
-        }
-        // only set context if it has changed
-        return this.currentContext?.id !== next?.id;
-      }),
-      switchMap(async (next) => {
-        // if parent context is null, just return
-        if (!next) {
-          return { next };
-        }
-        // notify event observers that parent context is about to change and await for cancelation
-        const onParentContextChanged = await this.#event?.dispatchEvent('onParentContextChanged', {
-          source: this,
-          detail: next,
-          cancelable: true,
-        });
-        return { next, canceled: onParentContextChanged?.canceled };
-      }),
-      // filter out canceled context changes
-      filter((x) => !x.canceled),
-      switchMap(({ next }) => {
-        // set current context with validation and resolution
-        return (
-          this.setCurrentContext(next, {
-            validate: true,
-            resolve: true,
-          })
-            // swallow errors so a failed context change doesn't break the parent subscription
-            .pipe(
-              catchError((err) => {
-                console.warn('ContextProvider::onParentContextChanged', 'setCurrentContext', err);
-                // do not emit any value if an error occurs
-                return EMPTY;
-              }),
-            )
-        );
-      }),
-      catchError((err) => {
-        console.warn('ContextProvider::onParentContextChanged', 'unhandled exception', err);
-        // do not emit any value if an error occurs
-        return EMPTY;
-      }),
-    );
-
-    // subscribe to parent context changes
-    const subscription = parentContext$.subscribe();
-
-    // add subscription to internal teardown
-    this.#subscriptions.add(subscription);
-    return subscription;
-  }
-
-  /**
-   * Sets the current context by resolving a context item using the provided ID.
-   *
-   * This method attempts to resolve a context item by its unique identifier,
-   * filters out any invalid or undefined items, and then sets the current context
-   * using the resolved item. The operation is performed as an Observable stream,
-   * allowing subscribers to react to the context change or handle errors.
-   *
-   * @param id - The unique identifier of the context item to resolve and set as current.
-   * @returns An Observable that emits the resolved and set {@link ContextItem}.
-   *          Emits an error if the context cannot be resolved or set.
-   */
-  public setCurrentContextById(id: string): Observable<ContextItem<Record<string, unknown>>> {
-    return new Observable((subscriber) => {
-      try {
-        this.#contextClient
-          // resolve context item by id
-          .resolveContext(id)
-          // filter out invalid items and set as current context
-          .pipe(
-            // filter out invalid context items
-            filter((item): item is ContextItem => !!item),
-            // set current context with validation and resolution
-            switchMap((item) => this.setCurrentContext(item)),
-          )
-          .subscribe(subscriber);
-      } catch (err) {
-        // catch any unhandled exceptions and emit error
-        subscriber.error(err);
-      }
-    });
-  }
-
-  /**
-   * Asynchronously sets the current context by its unique identifier and returns a promise
-   * that resolves to the corresponding `ContextItem`.
-   *
-   * This method wraps the observable returned by `setCurrentContextById` into a promise,
-   * allowing for async/await usage.
-   *
-   * @see {@link setCurrentContextById} for more details.
-   *
-   * @param id - The unique identifier of the context to set as current.
-   * @returns A promise that resolves to the `ContextItem` associated with the given ID.
-   */
-  public setCurrentContextByIdAsync(id: string): Promise<ContextItem<Record<string, unknown>>> {
-    // return last value from observable
-    return lastValueFrom(this.setCurrentContextById(id));
-  }
-
-  /**
-   * 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
-   * @param opt Optional settings.
-   * @param opt.validate Whether to validate the context item before setting it.
-   * @param opt.resolve Whether to attempt to resolve the context item if validation fails.
-   * @template T The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
-   * @returns An observable that emits the context item once the queued task completes.
-   */
-  public setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(
-    context: T,
-    opt?: { validate?: boolean; resolve?: boolean },
-  ): Observable<T> {
-    // signal for aborting the queue entry
-    const abort$ = new Subject();
-
-    // wrapper for returning an observable to the caller
-    const subject$ = new Subject<T>();
-
-    // run the actual context-setting logic and relay results/errors to the caller's subject
-    const task$ = this._setCurrentContext(context, opt).pipe(
-      // send context item which was set to the caller
-      tap((x) => subject$.next(x)),
-      // abort task on signal
-      takeUntil(abort$),
-      // close the observable sent to the caller
-      finalize(() => subject$.complete()),
-      // catch any unhandled exceptions to not stall the queue
-      catchError((err) => {
-        // emit error to caller
-        subject$.error(err);
-        // skip setting any context
-        return EMPTY;
-      }),
-    );
-
-    // add task to internal queue
-    this.#contextQueue.next(task$ as Observable<ContextItem<Record<string, unknown>>>);
-
-    // tear down the queued task if the caller unsubscribes
-    return subject$.pipe(
-      // if caller subscribes, unsubscribe should abort queue entry
-      finalize(() => abort$.next(true)),
-    );
-  }
-
-  /**
-   * Sets the current context, optionally validating and resolving it.
-   *
-   * This method emits the provided context as an observable. If the context is the same as the current one,
-   * it emits and completes immediately. If validation is requested and fails, it either emits an error or,
-   * if resolution is enabled, attempts to resolve the context before setting it. The method dispatches various
-   * events to notify listeners about validation failures, resolution steps, and context changes, allowing
-   * cancellation at several stages.
-   *
-   * ### Step-by-step process:
-   * 1. **Check if the context is the same as the current one:**
-   *    - If so, emit the context and complete the observable immediately.
-   * 2. **Validate the context (if requested):**
-   *    - If validation fails and resolution is not enabled:
-   *      - Dispatch the `onSetContextValidationFailed` event.
-   *      - Emit an error and complete.
-   *    - If validation fails but resolution is enabled:
-   *      - Dispatch the `onSetContextResolve` event (cancelable).
-   *      - If canceled, throw an error and abort.
-   *      - Attempt to resolve the context using `resolveContext`.
-   *      - Dispatch the `onSetContextResolved` event (cancelable) after resolution.
-   *      - If canceled, throw an error and abort.
-   *      - Recursively call `_setCurrentContext` with the resolved context (without validation/resolution).
-   * 3. **If validation passes or not requested:**
-   *    - Dispatch the `onCurrentContextChange` event (cancelable).
-   *    - If canceled, throw an error and abort.
-   *    - Emit the context and complete the observable.
-   *
-   * @protected
-   * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
-   * @param context - The new context to set.
-   * @param opt - Optional settings:
-   *   - `validate`: Whether to validate the context before setting.
-   *   - `resolve`: Whether to attempt to resolve the context if validation fails.
-   * @returns An `Observable<T>` that emits the context when set, or errors if validation or resolution fails.
-   * @fires onSetContextValidationFailed - When context validation fails and resolution is not enabled.
-   * @fires onSetContextResolve - Before attempting to resolve the context.
-   * @fires onSetContextResolved - After the context has been resolved.
-   * @fires onCurrentContextChange - Before changing the current context.
-   * @throws Error if validation fails and resolution is not enabled, or if any event handler cancels the operation.
-   */
-  protected _setCurrentContext<T extends ContextItem<Record<string, unknown>> | null>(
-    context: T,
-    opt?: { validate?: boolean; resolve?: boolean },
-  ): Observable<T> {
-    return new Observable((subscriber) => {
-      // if context is the same as current, just emit and complete
-      if (context === this.currentContext) {
-        subscriber.next(context);
-        return subscriber.complete();
-      }
-      // check if context is provided and should be validated
-      if (context && opt?.validate && !this.validateContext(context)) {
-        // check if the resolve context is provided
-        if (!opt.resolve) {
-          // notify event observers that context validation failed since resolve is not provided
-          this.#event?.dispatchEvent('onSetContextValidationFailed', {
-            source: this,
-            detail: { context },
-          });
-          // emit error and complete
-          return subscriber.error(Error('failed to validate provided context'));
-        }
-        // if resolve is enabled, attempt to resolve the invalid context before setting it
-        if (opt.resolve) {
-          // the recursive `_setCurrentContext` call below is re-entered with the already
-          // validated/resolved context, so the generic `T` cast is safe here.
-          return of(context)
-            .pipe(
-              // notify event observers that context is about to get resolved
-              switchMap(async (context) => {
-                // wait for event listeners to handle the event
-                const event = await this.#event?.dispatchEvent('onSetContextResolve', {
-                  source: this,
-                  cancelable: true,
-                  detail: { context },
-                });
-                // check if event was canceled and abort if so
-                if (event?.canceled) {
-                  throw Error('resolving of context was canceled');
-                }
-                return context;
-              }),
-              // resolve context
-              switchMap((context) =>
-                // Pair the resolved context alongside the original for downstream consumers.
-                this.resolveContext(context).pipe(
-                  map((resolved) => ({
-                    context,
-                    resolved,
-                  })),
-                ),
-              ),
-              // notify event listeners that context was resolved
-              switchMap(async ({ context, resolved }) => {
-                // wait for event listeners to handle the event
-                const event = await this.#event?.dispatchEvent('onSetContextResolved', {
-                  source: this,
-                  cancelable: true,
-                  detail: { context, resolved },
-                });
-                // check if event was canceled and abort if so
-                if (event?.canceled) {
-                  throw Error('resolving of context was canceled');
-                }
-                return resolved;
-              }),
-              // recursive call to set current context without validation and resolution
-              switchMap((resolved) => this._setCurrentContext(resolved as unknown as T)),
-            )
-            .subscribe(subscriber);
-        }
-      }
-
-      // make the context an observable
-      return of(context)
-        .pipe(
-          // alert event listeners that context is about to change
-          switchMap(async (context) => {
-            const event = await this.#event?.dispatchEvent('onCurrentContextChange', {
-              source: this,
-              canBubble: true,
-              cancelable: true,
-              detail: { context: context },
-            });
-
-            // check if event was canceled and abort if so
-            if (event?.canceled) {
-              throw Error('change of context was aborted');
-            }
-
-            return context;
-          }),
-        )
-        .subscribe((context) => {
-          // emit context to the caller
-          subscriber.next(context);
-          // only take the first value and complete
-          subscriber.complete();
-        });
-    });
-  }
-
-  /**
-   * Asynchronously sets the current context and returns a promise that resolves with the provided context.
-   *
-   * @see {@link setCurrentContext} for more details.
-   *
-   * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
-   * @param context - The context item to set as the current context, or `null` to clear it.
-   * @param opt - Optional settings for context handling.
-   * @param opt.validate - If `true`, validates the context before setting it.
-   * @param opt.resolve - If `true`, resolves any dependencies or references in the context before setting it.
-   * @returns A promise that resolves with the context item that was set.
-   */
-  public async setCurrentContextAsync<T extends ContextItem<Record<string, unknown>> | null>(
-    context: T,
-    opt?: { validate?: boolean; resolve?: boolean },
-  ): Promise<T> {
-    return lastValueFrom(this.setCurrentContext(context, opt));
-  }
-
-  /**
-   * Queries the context for items matching the provided search string.
-   *
-   * This method constructs query parameters using the given search term and the current context type,
-   * then executes the query using the internal query client. If a context filter is defined, it is applied
-   * to the results before emitting them. Errors thrown by the query client of type `QueryClientError` will
-   * have their underlying cause re-thrown.
-   *
-   * @param search - The search string to filter context items.
-   * @returns An Observable that emits an array of `ContextItem` objects matching the search criteria.
-   * @throws Re-throws the underlying cause of a `QueryClientError`, otherwise re-throws the original error.
-   */
-  public queryContext(search: string): Observable<Array<ContextItem>> {
-    const query$ = this.queryClient
-      .query(
-        // generate query parameters
-        this.#contextParameterFn({
-          search,
-          type: this.#contextType,
-        }) as QueryContextParameters,
-      )
-      // unwrap query-client errors and expose the underlying cause to subscribers
-      .pipe(
-        catchError((err) => {
-          // if query client throws a QueryClientError, extract the cause and throw it
-          if (err.name === 'QueryClientError') {
-            throw err.cause;
-          }
-          throw err;
-        }),
-        map((x) => x.value),
-      );
-
-    // apply context filter if available
-    return this.#contextFilter ? query$.pipe(map(this.#contextFilter)) : query$;
-  }
-
-  /**
-   * Asynchronously queries the context for items matching the provided search string.
-   *
-   * @see {@link queryContext} for more details.
-   *
-   * @param search - The search string used to filter context items.
-   * @returns A promise that resolves to an array of `ContextItem` objects matching the search criteria.
-   */
-  public queryContextAsync(search: string): Promise<Array<ContextItem>> {
-    return lastValueFrom(this.queryContext(search));
-  }
-
-  /**
-   * Validates whether the provided context item matches one of the allowed context types.
-   *
-   * @param item - The context item to validate, containing a type with an `id` property.
-   * @returns `true` if the context type is not set or if the item's type ID matches one of the allowed types (case-insensitive); otherwise, `false`.
-   */
-  public validateContext(item: ContextItem<Record<string, unknown>>): boolean {
-    // no context type configured means every context item is considered valid
-    if (!this.#contextType) return true;
-    // normalize allowed types for a case-insensitive comparison
-    return this.#contextType.map((x) => x.toLowerCase()).includes(item.type.id.toLowerCase());
-  }
-
-  /**
-   * Resolves a context item by fetching related context items of the same type as configured in the provider.
-   *
-   * This method:
-   * - Requests related context items matching the provider's context type.
-   * - Filters out invalid context items using `validateContext`.
-   * - Selects the first valid context item, throwing an error if none are found.
-   * - Logs a warning if multiple valid context items are found.
-   * - Returns the resolved context item as an observable.
-   *
-   * @param item - The context item for which to resolve related context.
-   * @returns An observable emitting the resolved context item.
-   * @throws Error if no valid related context item is found.
-   */
-  public resolveContext(
-    item: ContextItem<Record<string, unknown>>,
-  ): Observable<ContextItem<Record<string, unknown>>> {
-    // request related context items for the given context item with the same context type which the provider is configured with
-    return this.relatedContexts({ item, filter: { type: this.#contextType } }).pipe(
-      // filter out invalid context items
-      map((x) =>
-        // keep only context items that validate against the provider's context type
-        x.filter((item) => this.validateContext(item)),
-      ),
-      map((values) => {
-        // related context should be resolved to a single context item
-        const value = values.shift();
-
-        // if no value is found, throw an error
-        if (!value) {
-          throw Error('failed to resolve context');
-        }
-
-        // if multiple items are found, log a warning
-        if (values.length) {
-          console.warn('ContextProvider::relatedContext', 'multiple items found 🤣', values);
-        }
-
-        // return the resolved context item
-        return value;
-      }),
-    );
-  }
-
-  /**
-   * Asynchronously resolves the provided context item.
-   *
-   * @see {@link resolveContext} for more details.
-   *
-   * @param item - The context item to resolve.
-   * @returns A promise that resolves to the resolved context item.
-   */
-  public resolveContextAsync(
-    item: ContextItem<Record<string, unknown>>,
-  ): Promise<ContextItem<Record<string, unknown>>> {
-    return lastValueFrom(this.resolveContext(item));
-  }
-
-  /**
-   * Retrieves related context items based on the provided parameters.
-   *
-   * This method queries the related context client to fetch an array of context items
-   * that are related to the specified parameters. If the related context client is not
-   * available, it returns an observable that emits an error.
-   *
-   * @param args - The parameters used to query for related context items.
-   * @returns An Observable that emits an array of related context items.
-   * @throws Error if no related context client is defined or if the query fails.
-   */
-  public relatedContexts(
-    args: RelatedContextParameters,
-  ): Observable<Array<ContextItem<Record<string, unknown>>>> {
-    // check if related context client is available
-    if (!this.#contextRelated) {
-      return throwError(() =>
-        Error('ContextProvider::relatedContexts - no client defined for resolving related context'),
-      );
-    }
-
-    // request related context items
-    return this.#contextRelated.query(args).pipe(
-      map(({ value }) => value),
-      catchError((err) => {
-        // unwrap the underlying cause so callers see the original error
-        if (err.cause) {
-          throw err.cause;
-        }
-        throw err;
-      }),
-    );
-  }
-
-  /**
-   * Asynchronously retrieves an array of related context items based on the provided parameters.
-   *
-   * @see {@link relatedContexts} for more details.
-   *
-   * @param args - The parameters used to determine which related contexts to retrieve.
-   * @returns A promise that resolves to an array of `ContextItem` objects containing generic records.
-   */
-  public relatedContextsAsync(
-    args: RelatedContextParameters,
-  ): Promise<Array<ContextItem<Record<string, unknown>>>> {
-    return lastValueFrom(this.relatedContexts(args));
-  }
-
-  /**
-   * Clears the current context by setting it to null.
-   *
-   * This method is typically used to reset or remove the active context,
-   * ensuring that subsequent operations do not reference any previous context state.
-   */
-  public clearCurrentContext(): void {
-    this.setCurrentContext(null);
-  }
-
-  /**
-   * Disposes of resources held by the context provider.
-   *
-   * Unsubscribes from all active subscriptions and disposes of the context client,
-   * ensuring that any allocated resources are properly released.
-   */
-  dispose() {
-    this.#subscriptions.unsubscribe();
-    this.#contextClient.dispose();
-  }
-}
-
-export default ContextProvider;
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    /**
-     * Dispatched **before** the current context is changed.
-     *
-     * The event is cancelable — calling `event.preventDefault()` in a
-     * listener will abort the context change.
-     */
-    onCurrentContextChange: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem | null;
-        },
-        IContextProvider
-      >
-    >;
-    /**
-     * Dispatched **after** the current context has changed.
-     *
-     * Contains both the previous and next context items, enabling
-     * listeners to react to transitions.
-     */
-    onCurrentContextChanged: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          next: ContextItem | null;
-          previous?: ContextItem | null;
-        },
-        IContextProvider
-      >
-    >;
-
-    /**
-     * Dispatched **before** a parent context change is applied locally.
-     *
-     * Cancelable — prevents the parent context from being mirrored into
-     * this provider.
-     */
-    onParentContextChanged: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem | null;
-        },
-        IContextProvider
-      >
-    >;
-
-    /**
-     * Dispatched **before** context resolution begins (when validation
-     * fails and the caller requested resolution).
-     *
-     * Cancelable — aborting prevents the resolution attempt.
-     */
-    onSetContextResolve: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem;
-        },
-        IContextProvider
-      >
-    >;
-
-    /**
-     * Dispatched **after** the context has been resolved to a new item.
-     *
-     * Cancelable — aborting prevents the resolved item from being
-     * set as the current context.
-     */
-    onSetContextResolved: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem;
-          resolved?: ContextItem | null;
-        },
-        IContextProvider
-      >
-    >;
-
-    /**
-     * Dispatched when context validation fails and resolution is not
-     * enabled.
-     */
-    onSetContextValidationFailed: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem;
-        },
-        IContextProvider
-      >
-    >;
-
-    /**
-     * Dispatched when context resolution fails with an error.
-     */
-    onSetContextResolveFailed: FrameworkEvent<
-      FrameworkEventInit<
-        {
-          context: ContextItem;
-          error: unknown;
-        },
-        IContextProvider
-      >
-    >;
-  }
-}