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

package/src/ContextProvider.ts

@@ -23,11 +23,35 @@ import type {
 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 */
@@ -35,14 +59,48 @@ export interface IContextProvider {
   /** DANGER */
   readonly queryClient: Query<ContextItem[], QueryContextParameters>;
 
-  // stream of current context
+  /**
+   * 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>;
 
-  // current context of the current state
-  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.
    */
@@ -50,6 +108,14 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -57,6 +123,21 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -64,6 +145,29 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -71,6 +175,9 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -78,6 +185,7 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -87,6 +195,9 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -96,11 +207,13 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -108,6 +221,9 @@ export interface IContextProvider {
 
   /**
    * 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.
    */
@@ -115,6 +231,9 @@ export interface IContextProvider {
 
   /**
    * 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`.
@@ -128,6 +247,9 @@ export interface IContextProvider {
 
   /**
    * 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`.
@@ -142,14 +264,30 @@ 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
@@ -157,6 +295,36 @@ export interface IContextProvider {
   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 class ContextProvider implements IContextProvider {
   #contextClient: ContextClient;
   #contextQuery: Query<Array<ContextItem>, QueryContextParameters>;
@@ -219,8 +387,12 @@ export class ContextProvider implements IContextProvider {
     this.#event = event;
 
     // set the resolve and validate context functions
-    config.resolveContext && (this.resolveContext = config.resolveContext?.bind(this));
-    config.validateContext && (this.validateContext = config.validateContext?.bind(this));
+    if (config.resolveContext) {
+      this.resolveContext = config.resolveContext?.bind(this);
+    }
+    if (config.validateContext) {
+      this.validateContext = config.validateContext?.bind(this);
+    }
 
     if (config.extractContextIdFromPath) {
       // @ts-ignore
@@ -294,6 +466,22 @@ export class ContextProvider implements 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.
+   */
   public connectParentContext(
     provider: IContextProvider,
     opt?: { skipFirst: boolean },
@@ -354,6 +542,18 @@ export class ContextProvider implements IContextProvider {
     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 {
@@ -374,6 +574,18 @@ export class ContextProvider implements IContextProvider {
     });
   }
 
+  /**
+   * 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));
@@ -425,6 +637,47 @@ export class ContextProvider implements IContextProvider {
     );
   }
 
+  /**
+   * 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 },
@@ -523,6 +776,18 @@ export class ContextProvider implements IContextProvider {
     });
   }
 
+  /**
+   * 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.
+   */
   public async setCurrentContextAsync<T extends ContextItem<Record<string, unknown>> | null>(
     context: T,
     opt?: { validate?: boolean; resolve?: boolean },
@@ -530,6 +795,17 @@ export class ContextProvider implements IContextProvider {
     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.
+   */
   public queryContext(search: string): Observable<Array<ContextItem>> {
     const query$ = this.queryClient
       .query(
@@ -554,15 +830,43 @@ export class ContextProvider implements IContextProvider {
     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 {
     if (!this.#contextType) return true;
     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>>> {
@@ -590,12 +894,31 @@ export class ContextProvider implements IContextProvider {
     );
   }
 
+  /**
+   * 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>>>> {
@@ -618,16 +941,36 @@ export class ContextProvider implements IContextProvider {
     );
   }
 
+  /**
+   * 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();

package/src/client/ContextClient.ts

@@ -10,22 +10,62 @@ import type { ContextItem } from '../types';
 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 class ContextClient extends Observable<ContextItem | null | undefined> {
   #client: Query<ContextItem, { id: string }>;
   /** might change to reactive state, for comparing state with reducer */
   #currentContext$: BehaviorSubject<ContextItem | null | undefined>;
 
+  /**
+   * 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 {
     return this.#currentContext$.value;
   }
 
+  /**
+   * 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> {
     return this.#currentContext$.asObservable();
   }
 
+  /**
+   * 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 }> {
     return this.#client;
   }
@@ -36,7 +76,15 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
     this.#currentContext$ = new BehaviorSubject<ContextItem | null | undefined>(undefined);
   }
 
-  public setCurrentContext(idOrItem?: string | ContextItem | null) {
+  /**
+   * 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.
+   */
+  public setCurrentContext(idOrItem?: string | ContextItem | null): void {
     if (typeof idOrItem === 'string') {
       // TODO - compare context
       this.resolveContext(idOrItem)
@@ -49,6 +97,13 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
     }
   }
 
+  /**
+   * 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.
+   */
   public resolveContext(id: string): Observable<ContextItem> {
     return this.#client.query({ id }).pipe(
       map((x) => x.value),
@@ -62,6 +117,15 @@ export class ContextClient extends Observable<ContextItem | null | undefined> {
     );
   }
 
+  /**
+   * 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}.
+   */
   public resolveContextAsync(id: string, opt?: { awaitResolve: boolean }): Promise<ContextItem> {
     const fn = opt?.awaitResolve ? lastValueFrom : firstValueFrom;
     return fn(this.resolveContext(id));