@equinor/fusion-framework-module-context 6.0.7-next.0 → 7.0.1

package/dist/types/ContextConfigBuilder.d.ts

@@ -4,17 +4,75 @@ import type { GetContextParameters } from './client/ContextClient';
 import type { ContextModuleConfig, ContextModuleConfigurator, IContextModuleConfigurator } from './configurator';
 import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
 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 - this should extend the BaseConfigBuilder
+ *
+ * @see ContextModuleConfig
+ * @see ModuleInitializerArgs
+ */
 export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = [], TInit extends ModuleInitializerArgs<any, any> = ModuleInitializerArgs<ContextModuleConfigurator, TModules>> {
     #private;
     config: Partial<ContextModuleConfig>;
     constructor(init: TInit, config?: Partial<ContextModuleConfig>);
     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.
@@ -30,6 +88,18 @@ export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = []
      */
     setContextPathGenerator(fn: ContextModuleConfig['generatePathFromContext']): void;
     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>;

package/dist/types/ContextProvider.d.ts

@@ -6,79 +6,200 @@ 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';
 /**
- * WARNING: this is an initial out cast.
- * api clients will most probably not be exposed in future!
- */
-/**
- * Represents a context provider that manages the current context and provides methods for querying and manipulating context items.
+ * 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>;
-    currentContext: 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`.
@@ -91,6 +212,9 @@ export interface IContextProvider {
     }): 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`.
@@ -104,19 +228,65 @@ export interface IContextProvider {
     /**
      * 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;
 }
+/**
+ * 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 declare class ContextProvider implements IContextProvider {
     #private;
     get contextClient(): ContextClient;
@@ -131,10 +301,50 @@ export declare class ContextProvider implements IContextProvider {
         /** @deprecated use  ContextProvider.connectParentContext */
         parentContext?: IContextProvider;
     });
+    /**
+     * 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.
+     */
     connectParentContext(provider: IContextProvider, opt?: {
         skipFirst: boolean;
     }): 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.
+     */
     setCurrentContextById(id: string): Observable<ContextItem<Record<string, unknown>>>;
+    /**
+     * 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.
+     */
     setCurrentContextByIdAsync(id: string): Promise<ContextItem<Record<string, unknown>>>;
     /**
      * Setting context is a complex operation, and might not happen immediately.
@@ -151,22 +361,153 @@ export declare class ContextProvider implements IContextProvider {
         validate?: boolean;
         resolve?: boolean;
     }): Observable<T>;
+    /**
+     * 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
+     * @typeParam 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>;
+    /**
+     * Asynchronously sets the current context and returns a promise that resolves with the provided context.
+     *
+     * @see {@link setCurrentContext} for more details.
+     *
+     * @typeParam 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.
+     */
     setCurrentContextAsync<T extends ContextItem<Record<string, unknown>> | null>(context: T, opt?: {
         validate?: boolean;
         resolve?: boolean;
     }): Promise<T>;
+    /**
+     * 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.
+     */
     queryContext(search: string): Observable<Array<ContextItem>>;
+    /**
+     * 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.
+     */
     queryContextAsync(search: string): Promise<Array<ContextItem>>;
+    /**
+     * 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`.
+     */
     validateContext(item: ContextItem<Record<string, unknown>>): boolean;
+    /**
+     * 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.
+     */
     resolveContext(item: ContextItem<Record<string, unknown>>): Observable<ContextItem<Record<string, unknown>>>;
+    /**
+     * 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.
+     */
     resolveContextAsync(item: ContextItem<Record<string, unknown>>): Promise<ContextItem<Record<string, unknown>>>;
+    /**
+     * 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.
+     */
     relatedContexts(args: RelatedContextParameters): Observable<Array<ContextItem<Record<string, unknown>>>>;
+    /**
+     * 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.
+     */
     relatedContextsAsync(args: RelatedContextParameters): Promise<Array<ContextItem<Record<string, unknown>>>>;
+    /**
+     * 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.
+     */
     clearCurrentContext(): void;
+    /**
+     * 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(): void;
 }
 export default ContextProvider;

package/dist/types/client/ContextClient.d.ts

@@ -5,19 +5,83 @@ export type GetContextParameters = {
     id: string;
 };
 /**
- * @todo - add documentation
+ * `ContextClient` is an observable client for managing and retrieving context items.
+ *
+ * This class extends `Observable<ContextItem | null | undefined>`, allowing consumers to subscribe to context changes.
+ * It encapsulates a `Query` instance for fetching context items by ID and maintains the current context state using a `BehaviorSubject`.
+ *
+ * ### Features
+ * - Exposes the current context synchronously and as an observable stream.
+ * - Provides methods to set the current context by ID or item, resolving and updating as needed.
+ * - Supports asynchronous context resolution with optional await behavior.
+ * - Handles errors during context resolution, unwrapping nested causes.
+ * - Implements a `dispose` method to clean up internal subscriptions.
+ *
+ * @template ContextItem The type of the context item managed by the client.
+ * @extends Observable<ContextItem | null | undefined>
+ *
  * @todo - should this have `undefined` as a valid value?
+ *
+ * @example
+ * ```typescript
+ * const client = new ContextClient(options);
+ * client.setCurrentContext('context-id');
+ * client.currentContext$.subscribe(ctx => { ... });
+ * ```
  */
 export declare class ContextClient extends Observable<ContextItem | null | undefined> {
     #private;
+    /**
+     * Gets the current context item.
+     *
+     * @returns The current {@link ContextItem}, or `null` if no context is set, or `undefined` if the context has not been initialized.
+     */
     get currentContext(): ContextItem | null | undefined;
+    /**
+     * An observable stream that emits the current context item.
+     *
+     * @remarks
+     * This observable emits the current `ContextItem` whenever it changes.
+     * It can emit `null` or `undefined` if there is no current context.
+     *
+     * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
+     */
     get currentContext$(): Observable<ContextItem | null | undefined>;
+    /**
+     * Gets the query client for retrieving a specific `ContextItem` by its ID.
+     *
+     * @returns A `Query` instance configured to fetch a `ContextItem` using an object containing an `id` property.
+     */
     get client(): Query<ContextItem, {
         id: string;
     }>;
     constructor(options: QueryCtorOptions<ContextItem, GetContextParameters>);
+    /**
+     * Sets the current context based on the provided identifier or context item.
+     *
+     * If a string identifier is provided, attempts to resolve the corresponding context asynchronously.
+     * If a `ContextItem` or `null` is provided, updates the current context only if it differs from the existing one.
+     *
+     * @param idOrItem - The context identifier (string), a `ContextItem`, or `null`. If omitted, the current context may be cleared.
+     */
     setCurrentContext(idOrItem?: string | ContextItem | null): void;
+    /**
+     * Resolves a context item by its unique identifier.
+     *
+     * @param id - The unique identifier of the context item to resolve.
+     * @returns An Observable that emits the resolved {@link ContextItem}.
+     * @throws Rethrows the underlying error cause if present, otherwise throws the original error.
+     */
     resolveContext(id: string): Observable<ContextItem>;
+    /**
+     * Resolves a context item asynchronously by its ID.
+     *
+     * @param id - The unique identifier of the context item to resolve.
+     * @param opt - Optional settings for resolution.
+     * @param opt.awaitResolve - If true, waits for the observable to complete and returns the last emitted value;
+     * otherwise, returns the first emitted value.
+     * @returns A promise that resolves to the requested {@link ContextItem}.
+     */
     resolveContextAsync(id: string, opt?: {
         awaitResolve: boolean;
     }): Promise<ContextItem>;