@equinor/fusion-framework-module-bookmark 4.0.2 → 4.0.4

package/dist/esm/BookmarkProvider.js

@@ -6,10 +6,10 @@ import deepEqual from 'fast-deep-equal/es6';
 import { FrameworkEvent, } from '@equinor/fusion-framework-module-event';
 import { isFailureAction } from '@equinor/fusion-observable';
 import { SemanticVersion } from '@equinor/fusion-framework-module';
-import { bookmarkActions } from './BookmarkProvider.actions';
-import { createBookmarkStore, } from './BookmarkProvider.store';
+import { bookmarkActions } from './bookmark-actions';
+import { createBookmarkStore, } from './create-bookmark-store';
 import { activeBookmarkSelector, bookmarkSelector, bookmarksSelector, errorsSelector, } from './BookmarkProvider.selectors';
-import { BookmarkProviderError } from './BookmarkProvider.error';
+import { BookmarkProviderError } from './BookmarkFlowError';
 import { version } from './version';
 // Default timeout for bookmark operations (2 minutes)
 const defaultTimeout = 2 * 60 * 1000;
@@ -38,7 +38,7 @@ export class BookmarkProvider {
         return {
             getCurrentAppIdentification() {
                 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-ignore
+                // @ts-expect-error
                 return window.Fusion.modules.app.current.appKey;
             },
         };
@@ -46,6 +46,9 @@ export class BookmarkProvider {
     /**
      * @deprecated
      * this will be removed as soon as applications have been migrated to use the bookmark provider
+     * @param fn - The payload generator callback to register.
+     * @template T - The bookmark data type produced by the generator.
+     * @returns A function that unregisters the payload generator when called.
      */
     addStateCreator(fn) {
         console.warn('addStateCreator is deprecated, use addPayloadGenerator instead');
@@ -54,6 +57,7 @@ export class BookmarkProvider {
     /**
      * @deprecated
      * this will be removed as soon as applications have been migrated to use the bookmark provider
+     * @param id - The ID of the bookmark to delete.
      */
     deleteBookmarkByIdAsync(id) {
         console.warn('deleteBookmarkByIdAsync is deprecated, use deleteBookmarkAsync instead');
@@ -62,6 +66,8 @@ export class BookmarkProvider {
     /**
      * @deprecated
      * this will be removed as soon as applications have been migrated to use the bookmark provider
+     * @param id - The ID of the bookmark to add as a favorite.
+     * @returns The updated bookmark, or undefined if it could not be found.
      */
     addBookmarkFavoriteAsync(id) {
         console.warn('addBookmarkFavoriteAsync is deprecated, use addBookmarkToFavoritesAsync instead');
@@ -70,6 +76,7 @@ export class BookmarkProvider {
     /**
      * @deprecated
      * this will be removed as soon as applications have been migrated to use the bookmark provider
+     * @param id - The ID of the bookmark to remove as a favorite.
      */
     removeBookmarkFavoriteAsync(id) {
         console.warn('removeBookmarkFavoriteAsync is deprecated, use removeBookmarkAsFavoriteAsync instead');
@@ -78,6 +85,8 @@ export class BookmarkProvider {
     /**
      * @deprecated
      * this will be removed as soon as applications have been migrated to use the bookmark provider
+     * @param id - The ID of the bookmark to get.
+     * @returns The bookmark, or null if it could not be found.
      */
     getBookmarkById(id) {
         console.warn('getBookmarkById is deprecated, use getBookmarkAsync instead');
@@ -85,28 +94,33 @@ export class BookmarkProvider {
     }
     /**
      * Gets the semantic version of the bookmark provider.
+     * @returns The semantic version of the bookmark provider.
      */
     get version() {
         return new SemanticVersion(version);
     }
+    /** @returns The configured bookmark filters. */
     get filters() {
-        // TODO - freeze the config object?
+        // TODO(#5136) - freeze the config object?
         return this.#config.filters;
     }
     /**
      * Gets the `IBookmarkClient` instance used by this `BookmarkProvider`.
+     * @returns The `IBookmarkClient` instance.
      */
     get client() {
         return this.#config.client;
     }
     /**
      * Gets the currently active bookmark (if any).
+     * @returns An observable of the currently active bookmark.
      */
     get currentBookmark$() {
         return this.#store.select(activeBookmarkSelector);
     }
     /**
      * Gets an observable that emits the current list of bookmarks.
+     * @returns An observable of the current list of bookmarks.
      */
     get bookmarks$() {
         this.getAllBookmarksAsync();
@@ -114,12 +128,14 @@ export class BookmarkProvider {
     }
     /**
      * Gets the current list of bookmarks.
+     * @returns The current list of bookmarks.
      */
     get bookmarks() {
         return bookmarksSelector(this.#store.value);
     }
     /**
      * Gets the currently active bookmark.
+     * @returns The currently active bookmark, or null/undefined if there is none.
      */
     get currentBookmark() {
         const bookmark = activeBookmarkSelector(this.#store.value);
@@ -127,65 +143,78 @@ export class BookmarkProvider {
     }
     /**
      * Represents an observable stream of the bookmark status.
+     * @returns An observable of the bookmark status.
      */
     get status$() {
         return this.#store.select((x) => x.status);
     }
     /**
      * Gets an observable that emits the current list of bookmark errors.
+     * @returns An observable of the current list of bookmark errors.
      */
     get errors$() {
-        // TODO - add deep diff
+        // TODO(#5137) - add deep diff
         return this.#store.select(errorsSelector, deepEqual);
     }
     /**
      * Determines whether there are any bookmark creators configured.
-     * `true` if there are any bookmark creators configured, `false` otherwise.
+     * @returns `true` if there are any bookmark creators configured, `false` otherwise.
      */
     get canCreateBookmarks() {
         return this.#payloadGenerators.length > 0;
     }
     /**
      * Gets the source system value from the configuration.
+     * @returns The source system value.
      */
     get sourceSystem() {
         return this.#config.sourceSystem;
     }
     /**
      * Gets the resolved application from the bookmark module configuration.
+     * @returns The resolved application resolver.
      */
     get resolvedApplication() {
         return this.#config.resolve.application;
     }
     /**
      * Gets the resolved context from the bookmark module configuration.
+     * @returns The resolved context resolver.
      */
     get resolvedContext() {
         return this.#config.resolve.context;
     }
+    /**
+     * @internal The API client used to communicate with the bookmark backend.
+     * @returns The configured `IBookmarkClient` instance.
+     */
     get _apiClient() {
         return this.#config.client;
     }
     /**
      * configured logger instance.
+     * @returns The configured logger.
      */
     get _log() {
         return this.#config.log;
     }
     /**
      * configured resolvers
+     * @returns The configured resolvers.
      */
     get _resolve() {
         return this.#config.resolve;
     }
     /**
      * configured event provider.
+     * @returns The configured event provider.
      */
     get _event() {
         return this.#config.eventProvider;
     }
     /**
      * configured parent bookmark provider
+     * @returns The configured parent bookmark provider.
      */
     get _parent() {
         return this.#config.parent;
@@ -205,6 +234,7 @@ export class BookmarkProvider {
         this.#subscriptions.add(() => this.#store.complete());
         // subscribe to the store actions and log them
         this.#subscriptions.add(this.#store.action$.subscribe((action) => {
+            // log failure actions as errors, everything else as debug
             if (isFailureAction(action)) {
                 this._log?.error(`Action: ${action.type}`, action);
             }
@@ -220,7 +250,7 @@ export class BookmarkProvider {
             }
         }));
         // subscribe to child bookmark provider changes
-        // TODO - add support for disabling this feature
+        // TODO(#5138) - add support for disabling this feature
         if (this._event) {
             this._event.addEventListener('onCurrentBookmarkChanged', (event) => {
                 const { source, detail } = event;
@@ -233,10 +263,11 @@ export class BookmarkProvider {
                 }
             });
         }
+        // if a parent bookmark provider is configured, subscribe to its current bookmark changes
         if (this._parent) {
-            // if a parent bookmark provider is configured, subscribe to its current bookmark changes
             try {
                 this.#subscriptions.add(this._parent.currentBookmark$
+                    // only forward defined bookmarks that differ from the current one
                     .pipe(filter((x) => x !== undefined), filter((x) => x !== this.currentBookmark))
                     .subscribe((bookmark) => {
                     this.#store.next(bookmarkActions.setCurrentBookmark(bookmark));
@@ -250,12 +281,14 @@ export class BookmarkProvider {
     /**
      * Registers an event listener for the specified event on the BookmarkProvider.
      *
+     * @template TType - The key of the `BookmarkProviderEventMap` identifying the event.
      * @param eventName - The name of the event to listen for. Must be a key of the `BookmarkProviderEventMap` type.
      * @param callback - The callback function to be invoked when the event is triggered.
      *      The callback will receive the event object as its parameter, which will be of the type corresponding to the `eventName`.
      * @returns A function that can be called to remove the event listener.
      */
     on(eventName, callback) {
+        // without an event provider, registering a listener would be a no-op
         if (!this._event) {
             this._log?.warn('Failed to register event listener, event provider not configured');
             return () => {
@@ -263,6 +296,7 @@ export class BookmarkProvider {
             };
         }
         return this._event.addEventListener(eventName, (event) => {
+            // only forward events originating from this provider instance
             if (event.source === this) {
                 callback(event);
             }
@@ -272,6 +306,7 @@ export class BookmarkProvider {
      * Adds a new payload generator function to the BookmarkProvider.
      * The payload generator function will be used to generate the payload for a bookmark-related action.
      *
+     * @template T - The type of the bookmark data the payload generator produces.
      * @param fn - The payload generator function to add. It should be of type `PayloadGenerator<T>`, where `T` is the type of the bookmark data.
      * @returns A function that can be called to remove the added payload generator.
      */
@@ -286,6 +321,7 @@ export class BookmarkProvider {
         // return a function to remove the added payload generator
         return () => {
             this._log?.debug(`removing bookmark payload generator: ${fn.name}`);
+            // drop the matching generator reference from the registered list
             this.#payloadGenerators = this.#payloadGenerators.filter((g) => g !== fn);
         };
     }
@@ -348,6 +384,7 @@ export class BookmarkProvider {
      * @param bookmarkId The unique identifier of the bookmark.
      * @param options An optional object that allows excluding the bookmark payload from the result.
      * @returns An observable that emits the combined result of fetching the bookmark and bookmark data.
+     * @throws The error encountered while fetching the bookmark or its data, after logging it.
      */
     getBookmark(bookmarkId, options) {
         this._log?.debug(`fetching bookmark: ${bookmarkId}`, options);
@@ -367,6 +404,7 @@ export class BookmarkProvider {
     /**
      * Retrieves a bookmark asynchronously.
      *
+     * @template T - The type of the bookmark payload.
      * @param id - The ID of the bookmark to retrieve.
      * @param options - Optional parameters for the retrieval.
      * @param options.excludePayload - Specifies whether to exclude the payload from the bookmark.
@@ -483,6 +521,7 @@ export class BookmarkProvider {
      * @param bookmark_or_id - The bookmark or ID to set as the current bookmark.
      * @returns An observable that emits the next bookmark or null.
      * @template T - The type of the bookmark data.
+     * @throws {BookmarkProviderError} If the onCurrentBookmarkChange event is canceled by a listener, or resolving the bookmark fails.
      */
     setCurrentBookmark(bookmark_or_id) {
         this._log?.debug('setting current bookmark', bookmark_or_id);
@@ -490,11 +529,13 @@ export class BookmarkProvider {
         const next$ = typeof bookmark_or_id === 'string'
             ? this.getBookmark(bookmark_or_id)
             : of(bookmark_or_id ?? null);
+        // notify listeners before committing the next bookmark to the store
         return next$.pipe(switchMap(async (next) => {
             const current = this.currentBookmark;
             const { type, canceled } = await this._dispatchEvent('onCurrentBookmarkChange', {
                 detail: { current, next },
             });
+            // throw an error if the event is canceled
             if (canceled) {
                 const error = new BookmarkProviderError(`event: ${type} was canceled by listener for change to ${next?.id ?? 'none'}, from ${current?.id ?? 'none'}`);
                 this._log?.info(error.message);
@@ -511,14 +552,11 @@ export class BookmarkProvider {
         }));
     }
     /**
-     * Sets the current bookmark.
-     * This method dispatches an event to notify listeners of a change in the current bookmark,
-     * and then dispatches a request to set the active bookmark in the application state.
+     * Sets the current bookmark asynchronously.
      *
-     * The request will be canceled if the subscription is unsubscribed before the request completes.
-     *
-     * @param bookmarkId - The ID of the bookmark to set as the current bookmark.
-     * @returns A subscription to the operation that sets the current bookmark.
+     * @template T - The type of the bookmark data.
+     * @param bookmark_or_id - The bookmark or ID to set as the current bookmark.
+     * @returns A promise that resolves to the next bookmark or null.
      */
     setCurrentBookmarkAsync(bookmark_or_id) {
         return lastValueFrom(this.setCurrentBookmark(bookmark_or_id));
@@ -529,6 +567,7 @@ export class BookmarkProvider {
      * @template T - The type of bookmark data.
      * @param {BookmarkCreateArgs<T>} newBookmarkData - The data for creating the bookmark.
      * @returns {Observable<Bookmark<T>>} - An observable that emits the created bookmark.
+     * @throws {BookmarkProviderError} If resolving the bookmark data fails, the onBookmarkCreate event is canceled, the create request fails, or the request times out.
      */
     createBookmark(newBookmarkData) {
         const { ref, action$ } = this._useScopedActions();
@@ -538,6 +577,7 @@ export class BookmarkProvider {
             appKey: newBookmarkData.appKey
                 ? of(newBookmarkData.appKey)
                 : defer(() => this._resolve.application()).pipe(map((app) => {
+                    // the application must resolve to a valid appKey to attribute the bookmark
                     if (!app?.appKey) {
                         throw new BookmarkProviderError('Failed to resolve application key');
                     }
@@ -610,7 +650,8 @@ export class BookmarkProvider {
     /**
      * Asynchronously creates a new bookmark.
      *
-     * @param bookmark - The new bookmark to create.
+     * @template T - The type of bookmark data.
+     * @param args - The data for creating the bookmark.
      * @returns A promise that resolves to the created bookmark with its associated data.
      */
     createBookmarkAsync(args) {
@@ -625,8 +666,10 @@ export class BookmarkProvider {
      * @param {BookmarkUpdate<T>} [bookmarkUpdates] - The updates to apply to the bookmark.
      * @param {BookmarkUpdateOptions} [options] - The options for updating the bookmark.
      * @returns {Observable<Bookmark<T>>} - An observable that emits the updated bookmark.
+     * @throws {BookmarkProviderError} If bookmarkUpdates is omitted while excludePayloadGeneration is set, generating the payload fails, the onBookmarkUpdate event is canceled, the update request fails, or the request times out.
      */
     updateBookmark(bookmarkId, bookmarkUpdates, options) {
+        // bookmarkUpdates is required unless the caller opts out of payload generation entirely
         if (!bookmarkUpdates && options?.excludePayloadGeneration) {
             throw new BookmarkProviderError('Cannot update bookmark without updates and excludePayloadGeneration option');
         }
@@ -653,6 +696,7 @@ export class BookmarkProvider {
                 },
                 cancelable: true,
             });
+            // throw an error if the event is canceled
             if (canceled) {
                 const error = new BookmarkProviderError(`event: ${type} was canceled by listener for updating bookmark: ${bookmarkId}, ref: ${ref}`);
                 this._log?.warn(error.message, updates);
@@ -685,7 +729,7 @@ export class BookmarkProvider {
         }));
         // monitor the success case when updating a bookmark
         const request$ = action$.pipe(filter(bookmarkActions.updateBookmark.success.match), map(
-        // TODO: add payload if current bookmark is the same as the updated bookmark
+        // TODO(#5139): add payload if current bookmark is the same as the updated bookmark
         ({ payload }) => ({
             ...bookmarkSelector(this.#store.value, payload.id),
             payload: payload.payload,
@@ -704,16 +748,23 @@ export class BookmarkProvider {
     /**
      * Updates a bookmark asynchronously.
      *
-     * @todo - remove the deprecated method in the next major version
+     * @todo TODO(#5140) - remove the deprecated overload accepting a full bookmark in the next major version
      *
-     * @param bookmark - The bookmark to update.
+     * @template T - The type of the bookmark data.
+     * @param id_or_bookmark - The ID of the bookmark to update, or (deprecated) the full bookmark object.
+     * @param updates_or_options - The updates to apply, or (deprecated) the update options when using the bookmark overload.
+     * @param options - The options for updating the bookmark.
      * @returns A promise that resolves to the updated bookmark with its associated data.
      */
     updateBookmarkAsync(id_or_bookmark, updates_or_options, options) {
+        // support the deprecated overload that accepted a full bookmark instead of an id
         if (typeof id_or_bookmark === 'object') {
             // @deprecated
             console.warn('updateBookmarkAsync(bookmark, updates, options) is deprecated, use updateBookmarkAsync(id, updates, options) instead');
             const { id, ...updates } = id_or_bookmark;
+            // `updates_or_options` is a union of `BookmarkUpdate<T> | BookmarkUpdateOptions` here,
+            // neither of which declares `updatePayload` — cast through `unknown` to probe for the
+            // legacy options shape at runtime.
             return lastValueFrom(this.updateBookmark(id, updates, {
                 excludePayloadGeneration: !updates_or_options.updatePayload,
             }));
@@ -740,6 +791,7 @@ export class BookmarkProvider {
             detail: bookmark,
             cancelable: true,
         })).pipe(map(({ canceled, type, detail }) => {
+            // throw an error if the event is canceled
             if (canceled) {
                 const error = new BookmarkProviderError(`event: ${type} was canceled by listener for removing bookmark: ${bookmarkId}, ref: ${ref}`);
                 this._log?.warn(error.message);
@@ -793,10 +845,11 @@ export class BookmarkProvider {
         return lastValueFrom(this.deleteBookmark(bookmarkId));
     }
     /**
-     * Adds a bookmark to the favorites.
+     * Adds a bookmark to favorites.
      *
      * @param bookmarkId - The ID of the bookmark to add.
-     * @returns A Promise that resolves to the added bookmark, or null if the bookmark was not added.
+     * @returns An observable that emits the added bookmark, or undefined if it could not be resolved.
+     * @throws {BookmarkProviderError} If the onBookmarkFavouriteAdd event is canceled, the add request fails, or the request times out.
      */
     addBookmarkToFavorites(bookmarkId) {
         /**
@@ -811,6 +864,7 @@ export class BookmarkProvider {
                 detail: { id: bookmarkId },
                 cancelable: true,
             })).pipe(map(({ canceled, type }) => {
+                // throw an error if the event is canceled
                 if (canceled) {
                     const error = new BookmarkProviderError(`event: ${type} was canceled by listener for adding favourite bookmark: ${bookmarkId}, ref: ${ref}`);
                     this._log?.info(error.message);
@@ -875,6 +929,7 @@ export class BookmarkProvider {
                 detail: bookmark,
                 cancelable: true,
             })).pipe(map(({ canceled, type, detail }) => {
+                // throw an error if the event is canceled
                 if (canceled) {
                     const error = new BookmarkProviderError(`event: ${type} was canceled by listener for removing favourite bookmark: ${bookmarkId}, ref: ${ref}`);
                     this._log?.warn(error.message);
@@ -925,7 +980,8 @@ export class BookmarkProvider {
     /**
      * Checks if a bookmark is in the favorites.
      * @param bookmarkId - The ID of the bookmark to check.
-     * @returns A promise that resolves to a boolean indicating whether the bookmark is in the favorites.
+     * @returns An observable that emits a boolean indicating whether the bookmark is in the favorites.
+     * @throws {BookmarkProviderError} If checking the favorite status fails.
      */
     isBookmarkInFavorites(bookmarkId) {
         this._log?.debug(`Checking if bookmark: ${bookmarkId} is in favourites`);
@@ -947,6 +1003,14 @@ export class BookmarkProvider {
     isBookmarkInFavoritesAsync(bookmarkId) {
         return lastValueFrom(this.isBookmarkInFavorites(bookmarkId));
     }
+    /**
+     * Fetches a single bookmark's metadata (without payload) via the store.
+     *
+     * @param bookmarkId - The unique identifier of the bookmark to fetch.
+     * @param options - Optional settings, including a custom `timeout` in milliseconds.
+     * @returns An observable that emits the bookmark's metadata once fetched.
+     * @throws {BookmarkProviderError} If the fetch fails or times out.
+     */
     _getBookmarkInfo(bookmarkId, options) {
         // only actions with the specified reference are considered
         const { action$ } = this._useScopedActions(bookmarkId);
@@ -962,8 +1026,18 @@ export class BookmarkProvider {
             },
         }));
         this.#store.next(bookmarkActions.fetchBookmark(bookmarkId, { ref: bookmarkId }));
+        // race the success and failure streams, whichever resolves first wins
         return success$.pipe(raceWith(failure$));
     }
+    /**
+     * Fetches a single bookmark's payload data via the store.
+     *
+     * @template T - The type of the bookmark payload.
+     * @param bookmarkId - The unique identifier of the bookmark whose data to fetch.
+     * @param options - Optional settings, including a custom `timeout` in milliseconds.
+     * @returns An observable that emits the bookmark's payload data once fetched.
+     * @throws {BookmarkProviderError} If the fetch fails or times out.
+     */
     _getBookmarkData(bookmarkId, options) {
         // only actions with the specified reference are considered
         const { action$ } = this._useScopedActions(bookmarkId);
@@ -980,11 +1054,13 @@ export class BookmarkProvider {
         }));
         // request the store to fetch the bookmark data
         this.#store.next(bookmarkActions.fetchBookmarkData(bookmarkId, { ref: bookmarkId }));
+        // race the success and failure streams, whichever resolves first wins
         return success$.pipe(raceWith(failure$));
     }
     /**
      * Dispatches an event of the specified type with the provided arguments.
      *
+     * @template TType - The specific event type key being dispatched.
      * @param type - The type of the event to dispatch.
      * @param args - The arguments to pass to the event.
      * @returns A promise that resolves with the result of the event dispatch.
@@ -996,15 +1072,25 @@ export class BookmarkProvider {
             canBubble: true,
             ...args,
         });
+        // only dispatch through the event bus when one is available
         if (this._event) {
             this._log?.debug(`dispatching event ${type}`, args);
             const { canceled } = await this._event.dispatchEvent(event);
+            // log when a listener canceled the event
             if (canceled) {
                 this._log?.debug(`event ${type} was canceled`, args);
             }
         }
         return event;
     }
+    /**
+     * Creates a scoped action reference and a filtered action stream containing only
+     * actions tagged with that reference (or the provided `ref`, if given).
+     *
+     * @template TAction - The specific action type emitted on the scoped stream.
+     * @param ref - An existing reference to scope actions to; a new GUID is generated when omitted.
+     * @returns An object containing the resolved `ref` and the `action$` stream filtered to it.
+     */
     _useScopedActions(ref) {
         /**
          * Generates a unique identifier for the operation
@@ -1023,6 +1109,9 @@ export class BookmarkProvider {
         this._log?.debug('disposing BookmarkProvider');
         this.#subscriptions.unsubscribe();
     }
+    /**
+     * Disposes the BookmarkProvider via the `Symbol.dispose` protocol.
+     */
     [Symbol.dispose]() {
         this.dispose();
     }