@equinor/fusion-framework-module-bookmark 1.2.13 → 2.0.0

package/src/BookmarkProvider.ts

@@ -0,0 +1,1308 @@
+import { Observable, Subscription, forkJoin, from, lastValueFrom, of } from 'rxjs';
+
+import {
+    filter,
+    switchMap,
+    tap,
+    map,
+    mergeScan,
+    timeout,
+    raceWith,
+    first,
+    catchError,
+} from 'rxjs/operators';
+
+import { Draft, Patch, produce, enablePatches, castDraft } from 'immer';
+
+import { v4 as generateGUID } from 'uuid';
+
+import deepEqual from 'fast-deep-equal/es6';
+
+import { FrameworkEvent, FrameworkEventInitType } from '@equinor/fusion-framework-module-event';
+
+import { isFailureAction } from '@equinor/fusion-observable';
+
+import { SemanticVersion } from '@equinor/fusion-framework-module';
+
+import type {
+    Bookmark,
+    BookmarkData,
+    BookmarkWithoutData,
+    Bookmarks,
+    BookmarkModuleConfig,
+} from './types';
+
+import { BookmarkNew, BookmarkUpdate, type IBookmarkClient } from './BookmarkClient.interface';
+import { BookmarkActions, bookmarkActions } from './BookmarkProvider.actions';
+import { BookmarkState, createBookmarkStore, type BookmarkStore } from './BookmarkProvider.store';
+import {
+    activeBookmarkSelector,
+    bookmarkSelector,
+    bookmarksSelector,
+    errorsSelector,
+} from './BookmarkProvider.selectors';
+
+import { BookmarkFlowError, BookmarkProviderError } from './BookmarkProvider.error';
+
+import { BookmarkProviderEventMap } from './BookmarkProvider.events';
+import { version } from './version';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BookmarkPayloadGenerator<TData extends BookmarkData = any> = (
+    payload?: Draft<Partial<TData>> | null,
+    initial?: Partial<TData> | null,
+) => Promise<Partial<TData> | void> | Partial<TData> | void;
+
+export type BookmarkUpdateOptions = {
+    excludePayloadGeneration?: boolean;
+};
+
+export type BookmarkCreateArgs<T extends BookmarkData> = Omit<
+    BookmarkNew<T>,
+    'appKey' | 'contextId' | 'sourceSystem'
+> &
+    Partial<Pick<BookmarkNew<T>, 'appKey'>>;
+
+enablePatches();
+
+const defaultTimeout = 2 * 60 * 1000; // 2 minutes
+
+/**
+ * The `BookmarkProvider` class is responsible for managing bookmarks in the application.
+ * It provides methods for creating, updating, and removing bookmarks, as well as managing the current bookmark and the list of bookmarks.
+ *
+ * The `BookmarkProvider` uses a `BookmarkStore` to manage the state of the bookmarks, and an `IBookmarkClient` to interact with the backend API.
+ *
+ * The `BookmarkProvider` also supports event listeners for various bookmark-related events, such as when the current bookmark changes or when a bookmark is created, updated, or removed.
+ */
+export class BookmarkProvider {
+    /** provided configuration for the bookmark provider */
+    #config: BookmarkModuleConfig;
+
+    /** state machine of the bookmark provider */
+    #store: BookmarkStore;
+
+    /** collection of callback for creating bookmark payload */
+    #payloadGenerators: Array<BookmarkPayloadGenerator> = [];
+
+    /** collection of subscriptions for bookmark events */
+    #subscriptions = new Subscription();
+
+    /**
+     * Gets the semantic version of the bookmark provider.
+     */
+    public get version(): SemanticVersion {
+        return new SemanticVersion(version);
+    }
+
+    public get filters(): BookmarkModuleConfig['filters'] {
+        // TODO - freeze the config object?
+        return this.#config.filters;
+    }
+
+    /**
+     * Gets the `IBookmarkClient` instance used by this `BookmarkProvider`.
+     */
+    public get client(): IBookmarkClient {
+        return this.#config.client;
+    }
+
+    /**
+     * Gets the currently active bookmark (if any).
+     */
+    public get currentBookmark$(): Observable<Bookmark | null> {
+        return this.#store.select(activeBookmarkSelector, deepEqual);
+    }
+
+    /**
+     * Gets an observable that emits the current list of bookmarks.
+     */
+    public get bookmarks$(): Observable<Array<BookmarkWithoutData>> {
+        this.getAllBookmarksAsync();
+        return this.#store.select(bookmarksSelector, deepEqual);
+    }
+
+    /**
+     * Gets the current list of bookmarks.
+     */
+    public get bookmarks(): Array<BookmarkWithoutData> {
+        return bookmarksSelector(this.#store.value);
+    }
+
+    /**
+     * Gets the currently active bookmark.
+     */
+    public get currentBookmark(): Bookmark | null | undefined {
+        return activeBookmarkSelector(this.#store.value);
+    }
+
+    /**
+     * Represents an observable stream of the bookmark status.
+     */
+    public get status$(): Observable<BookmarkState['status']> {
+        return this.#store.select((x) => x.status);
+    }
+
+    /**
+     * Gets an observable that emits the current list of bookmark errors.
+     */
+    public get errors$(): Observable<Array<BookmarkFlowError>> {
+        // TODO - 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.
+     */
+    public get hasBookmarkCreators(): boolean {
+        return this.#payloadGenerators.length > 0;
+    }
+
+    /**
+     * Gets the source system value from the configuration.
+     */
+    public get sourceSystem(): BookmarkModuleConfig['sourceSystem'] {
+        return this.#config.sourceSystem;
+    }
+
+    /**
+     * Gets the resolved application from the bookmark module configuration.
+     */
+    public get resolvedApplication(): BookmarkModuleConfig['resolve']['application'] {
+        return this.#config.resolve.application;
+    }
+
+    /**
+     * Gets the resolved context from the bookmark module configuration.
+     */
+    public get resolvedContext(): BookmarkModuleConfig['resolve']['context'] {
+        return this.#config.resolve.context;
+    }
+
+    protected get _apiClient(): IBookmarkClient {
+        return this.#config.client;
+    }
+
+    /**
+     * configured logger instance.
+     */
+    protected get _log(): BookmarkModuleConfig['log'] {
+        return this.#config.log;
+    }
+
+    /**
+     * configured resolvers
+     */
+    protected get _resolve(): BookmarkModuleConfig['resolve'] {
+        return this.#config.resolve;
+    }
+
+    /**
+     * configured event provider.
+     */
+    protected get _event(): BookmarkModuleConfig['eventProvider'] {
+        return this.#config.eventProvider;
+    }
+
+    /**
+     * configured parent bookmark provider
+     */
+    protected get _parent(): BookmarkModuleConfig['parent'] {
+        return this.#config.parent;
+    }
+
+    /**
+     * Constructs a new `BookmarkProvider` instance.
+     *
+     * @param config - The configuration for the bookmark module, including the client, initial state, and optional parent provider.
+     */
+    constructor(config: BookmarkModuleConfig) {
+        this.#config = config;
+
+        this.#store = createBookmarkStore({
+            client: config.client,
+            initial: { currentBookmark: this._parent?.currentBookmark ?? null },
+        });
+
+        // add teardown logic for disposing the store
+        this.#subscriptions.add(() => this.#store.complete());
+
+        // subscribe to the store actions and log them
+        this.#subscriptions.add(
+            this.#store.action$.subscribe((action) => {
+                if (isFailureAction(action)) {
+                    this._log?.error(`Action: ${action.type}`, action);
+                } else {
+                    this._log?.debug(`Action: ${action.type}`, action);
+                }
+            }),
+        );
+
+        // subscribe to the current bookmark changes and dispatch events
+        this.#subscriptions.add(
+            this.#store.select(activeBookmarkSelector).subscribe((bookmark) => {
+                this._dispatchEvent('onCurrentBookmarkChanged', { detail: bookmark });
+            }),
+        );
+
+        // subscribe to child bookmark provider changes
+        // TODO - add support for disabling this feature
+        if (this._event) {
+            this._event.addEventListener('onCurrentBookmarkChanged', (event) => {
+                // only update the current bookmark if the event source is not this provider
+                if (event.source !== this) {
+                    this.setCurrentBookmarkAsync(event.detail);
+                }
+            });
+        }
+
+        if (this._parent) {
+            // if a parent bookmark provider is configured, subscribe to its current bookmark changes
+            try {
+                this.#subscriptions.add(
+                    this._parent.currentBookmark$.subscribe((bookmark) => {
+                        this.setCurrentBookmarkAsync(bookmark);
+                    }),
+                );
+            } catch (e) {
+                this._log?.error('Failed to subscribe to parent bookmark provider', e);
+            }
+        }
+    }
+
+    /**
+     * Registers an event listener for the specified event on the BookmarkProvider.
+     *
+     * @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.
+     */
+    public on<TType extends keyof BookmarkProviderEventMap>(
+        eventName: TType,
+        callback: (event: BookmarkProviderEventMap[TType]) => void,
+    ): VoidFunction {
+        if (!this._event) {
+            this._log?.warn('Failed to register event listener, event provider not configured');
+            return () => {};
+        }
+        return this._event?.addEventListener(eventName, callback);
+    }
+
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    public addPayloadGenerator<T extends BookmarkData>(
+        fn: BookmarkPayloadGenerator<T>,
+    ): VoidFunction {
+        this._log?.debug(`adding bookmark payload generator: ${fn.name}`);
+
+        // register the payload generator function
+        this.#payloadGenerators.push(fn as BookmarkPayloadGenerator);
+
+        // dispatch event to notify listeners of the added payload generator
+        this._dispatchEvent('onBookmarkPayloadCreatorAdded', {
+            detail: fn as BookmarkPayloadGenerator,
+        });
+
+        // return a function to remove the added payload generator
+        return () => {
+            this._log?.debug(`removing bookmark payload generator: ${fn.name}`);
+            this.#payloadGenerators = this.#payloadGenerators.filter((g) => g !== fn);
+        };
+    }
+
+    /**
+     * Generates a payload by applying registered generator functions to an accumulator object.
+     *
+     * @param initial - The initial value of the accumulator object.
+     * @returns An observable that emits the generated payload.
+     * @template T - The type of the generated payload.
+     */
+    public generatePayload<T extends BookmarkData>(
+        initial?: Partial<T> | null,
+    ): Observable<T | null | undefined> {
+        this._log?.debug(`generating payload`, initial);
+
+        /**
+         * Generates a payload by applying a generator function to an accumulator object.
+         * The generator function can modify the accumulator object using immer's draft mechanism.
+         *
+         * @param acc - The accumulator object.
+         * @param generator - The generator function that modifies the accumulator object.
+         * @returns A promise that resolves to the generated payload.
+         */
+        const generatePayload = async (acc: Partial<T>, generator: BookmarkPayloadGenerator<T>) => {
+            // produce payload from generator
+            return produce<Partial<T>, Draft<Partial<T>> | null>(
+                acc,
+                async (draft) => {
+                    // execute the generator
+                    const result = await Promise.resolve(generator(draft, initial));
+                    if (result) {
+                        this._log?.warn(
+                            `bookmark data generator ${generator.name} returned a value, but it should not do this, since the data is an immer draft object`,
+                        );
+                        return castDraft(result);
+                    } else if (result === null) {
+                        this._log?.info(
+                            `bookmark data generator ${generator.name} wish to clear the bookmark data`,
+                        );
+                        return null;
+                    }
+                },
+                (patches: Patch[]) => {
+                    if (patches.length > 0) {
+                        this._log?.debug(
+                            `bookmark data generator ${generator.name} produced patches`,
+                            patches,
+                        );
+                    }
+                },
+            );
+        };
+
+        /**
+         * Observable that emits the generated payload.
+         */
+        const result$ = from(this.#payloadGenerators).pipe(
+            mergeScan(generatePayload, initial ?? {}, 1),
+            tap((payload) => this._log?.debug(`generated payload`, { initial, payload })),
+        ) as Observable<T | null | undefined>;
+
+        return result$;
+    }
+
+    /**
+     * Retrieves a bookmark with the specified bookmarkId and returns an observable that emits the combined result of fetching the bookmark and bookmark data.
+     * @template T The type of the bookmark payload.
+     * @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.
+     */
+    public getBookmark<T extends BookmarkData>(
+        bookmarkId: string,
+        options?: { excludePayload?: boolean },
+    ) {
+        this._log?.debug(`fetching bookmark: ${bookmarkId}`, options);
+
+        // fetch the bookmark and bookmark data
+        return forkJoin({
+            bookmark: this._getBookmarkInfo(bookmarkId),
+            payload: options?.excludePayload ? of({}) : this._getBookmarkData(bookmarkId),
+        }).pipe(
+            catchError((error) => {
+                this._log?.error(`Failed to fetch bookmark: ${bookmarkId}`, error);
+                throw error;
+            }),
+            // combine the bookmark and payload into a single object
+            map(({ bookmark, payload }) => Object.assign({}, bookmark, { payload }) as Bookmark<T>),
+            tap((bookmark) => {
+                this._log?.debug(`Bookmark fetched: ${bookmark.id}`, bookmark);
+            }),
+        );
+    }
+
+    /**
+     * Retrieves a bookmark asynchronously.
+     *
+     * @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.
+     * @returns A promise that resolves to the retrieved bookmark, or null if the bookmark is not found.
+     */
+    public getBookmarkAsync<T extends BookmarkData>(
+        id: string,
+        options?: { excludePayload?: boolean },
+    ): Promise<Bookmark<T> | null> {
+        return lastValueFrom(this.getBookmark<T>(id, options));
+    }
+
+    /**
+     * Asynchronously retrieves all bookmarks from the store.
+     *
+     * @returns A Promise that resolves to the Bookmarks object containing all bookmarks.
+     */
+    public getAllBookmarks(): Observable<Bookmarks> {
+        return new Observable<Bookmarks>((observer) => {
+            this._log?.debug(`fetching all bookmarks`);
+
+            // generate the filter parameters
+            const filter$ = forkJoin({
+                sourceSystem: of(this.sourceSystem),
+                appKey: this.#config.filters?.application
+                    ? from(this._resolve.application()).pipe(map((x) => x?.appKey))
+                    : of(undefined),
+                contextId: this.#config.filters?.context
+                    ? from(this._resolve.context()).pipe(map((x) => x?.id))
+                    : of(undefined),
+            }).pipe(
+                catchError((err) => {
+                    const error = new BookmarkProviderError(
+                        'Could not fetch bookmarks, failed to resolve filter parameters',
+                        err,
+                    );
+                    this._log?.error(error.message, error);
+                    throw error;
+                }),
+            );
+
+            // execute the fetch bookmarks action when the filter parameters are resolved
+            observer.add(
+                filter$.subscribe((filter) => {
+                    this.#store.next(bookmarkActions.fetchBookmarks(filter));
+                }),
+            );
+
+            // monitor the failure case when fetching bookmarks
+            const failure$ = this.#store.action$.pipe(
+                filter(bookmarkActions.fetchBookmarks.failure.match),
+                map((action) => {
+                    this._log?.error('Failed to fetch bookmarks', action.payload);
+                    throw new BookmarkProviderError('Failed to fetch bookmarks', action.payload);
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError('Timeout while fetching bookmarks');
+                    },
+                }),
+            );
+
+            // monitor the success case when fetching bookmarks
+            const request$ = this.#store.action$.pipe(
+                filter(bookmarkActions.fetchBookmarks.success.match),
+                map((a) => a.payload),
+                first(),
+                tap((bookmarks) => {
+                    this._log?.debug(`fetched all bookmarks`, bookmarks);
+                }),
+                raceWith(failure$),
+            );
+
+            request$.subscribe(observer);
+        });
+    }
+
+    /**
+     * Asynchronously retrieves all bookmarks from the store.
+     *
+     * @returns A Promise that resolves to the Bookmarks object containing all bookmarks.
+     */
+    public async getAllBookmarksAsync(): Promise<Bookmarks> {
+        return lastValueFrom(this.getAllBookmarks());
+    }
+
+    /**
+     * Sets the current bookmark to the specified bookmark or ID.
+     * If the bookmark is already the current bookmark, it returns the bookmark directly.
+     * Otherwise, it emits the next bookmark or null through an observable.
+     *
+     * By proving `null` as the bookmark_or_id, the current bookmark will be cleared.
+     *
+     * @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.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public setCurrentBookmark<T extends BookmarkData = any>(
+        bookmark_or_id: Bookmark<T> | string | null,
+    ): Observable<Bookmark<T> | null> {
+        // check if the bookmark is already the current bookmark
+        if (bookmark_or_id == this.currentBookmark) return of(bookmark_or_id);
+
+        this._log?.debug(`setting current bookmark`, bookmark_or_id);
+
+        // resolve the next bookmark
+        const next$: Observable<Bookmark<T> | null> =
+            typeof bookmark_or_id === 'string'
+                ? this.getBookmark<T>(bookmark_or_id)
+                : of(bookmark_or_id ?? null);
+
+        return next$.pipe(
+            switchMap(async (next) => {
+                const current = this.currentBookmark;
+                const { type, canceled } = await this._dispatchEvent('onCurrentBookmarkChange', {
+                    detail: { current, next },
+                });
+                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);
+                    throw error;
+                }
+
+                return next;
+            }),
+            tap((next) => {
+                // set the current bookmark in the store
+                this.#store.next(bookmarkActions.setCurrentBookmark(next));
+            }),
+            catchError((err) => {
+                const error = new BookmarkProviderError(
+                    'Could not set current bookmark, resolve of bookmark failed',
+                    err,
+                );
+                this._log?.error(error.message, error);
+                throw error;
+            }),
+        );
+    }
+
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    public setCurrentBookmarkAsync<T extends BookmarkData>(
+        bookmark_or_id: Bookmark<T> | string | null,
+    ): Promise<Bookmark<T> | null> {
+        return lastValueFrom(this.setCurrentBookmark<T>(bookmark_or_id));
+    }
+
+    /**
+     * Creates a new bookmark with the provided bookmark data.
+     * @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.
+     */
+    public createBookmark<T extends BookmarkData>(
+        newBookmarkData: BookmarkCreateArgs<T>,
+    ): Observable<Bookmark<T>> {
+        return new Observable<Bookmark<T>>((subscriber) => {
+            const { ref, action$ } = this._useScopedActions();
+
+            this._log?.debug(`creating new bookmark, ref: ${ref}`, newBookmarkData);
+
+            // resolve the bookmark
+            const bookmark$ = forkJoin({
+                appKey: newBookmarkData.appKey
+                    ? of(newBookmarkData.appKey)
+                    : from(this._resolve.application()).pipe(
+                          map((app) => {
+                              if (!app?.appKey) {
+                                  throw new BookmarkProviderError(
+                                      'Failed to resolve application key',
+                                  );
+                              }
+                              return app.appKey;
+                          }),
+                      ),
+                contextId: this._resolve.context().then((context) => context?.id),
+                payload: this.generatePayload<T>(newBookmarkData.payload),
+                sourceSystem: of(this.sourceSystem),
+            }).pipe(
+                catchError((err) => {
+                    const error = new BookmarkProviderError(
+                        'Could not create new bookmark, failed to resolve bookmark data',
+                        err,
+                    );
+                    this._log?.error(error.message, error);
+                    throw error;
+                }),
+                // merge the resolved data with the new bookmark data
+                map(
+                    (resolvedData) =>
+                        ({
+                            ...newBookmarkData,
+                            ...resolvedData,
+                        }) as BookmarkNew<T>,
+                ),
+            );
+
+            // notify listeners that a bookmark is about to be created
+            const dispatch$ = bookmark$.pipe(
+                switchMap(async (bookmark) => {
+                    // notify listeners that a bookmark is about to be created
+                    const { canceled, type } = await this._dispatchEvent('onBookmarkCreate', {
+                        detail: bookmark,
+                        cancelable: true,
+                    });
+
+                    // throw an error if the event is canceled
+                    if (canceled) {
+                        const error = new BookmarkProviderError(
+                            `event: ${type} was canceled by listener for creating bookmark: ${ref}`,
+                        );
+                        this._log?.info(error.message);
+                        throw error;
+                    }
+
+                    return bookmark;
+                }),
+            );
+
+            // execute the create bookmark action when the bookmark is resolved and not canceled
+            subscriber.add(
+                dispatch$.subscribe({
+                    error: (error) => subscriber.error(error),
+                    next: (newBookmark) => {
+                        // request the store to create the bookmark
+                        this.#store.next(bookmarkActions.createBookmark(newBookmark, { ref }));
+                    },
+                }),
+            );
+
+            // monitor the failure case when creating a bookmark
+            const failure$ = action$.pipe(
+                filter(bookmarkActions.createBookmark.failure.match),
+                map(({ payload: cause }) => {
+                    const error = new BookmarkProviderError(`Failed to create bookmark: ${ref}`, {
+                        cause,
+                    });
+                    this._log?.warn(error.message);
+                    throw error;
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError(`Timeout while creating bookmark: ${ref}`);
+                    },
+                }),
+            );
+
+            // monitor the success case when creating a bookmark
+            const request$ = action$.pipe(
+                filter(bookmarkActions.createBookmark.success.match),
+                map(({ payload }) => payload as Bookmark<T>),
+                first(),
+                tap((bookmark) => {
+                    this._log?.info(`Bookmark created: ${bookmark.id}, ref: ${ref}`);
+                    this._dispatchEvent('onBookmarkCreated', { detail: bookmark });
+                }),
+                raceWith(failure$),
+            );
+
+            // emit the created bookmark
+            request$.subscribe(subscriber);
+        });
+    }
+
+    /**
+     * Asynchronously creates a new bookmark.
+     *
+     * @param bookmark - The new bookmark to create.
+     * @returns A promise that resolves to the created bookmark with its associated data.
+     */
+    public createBookmarkAsync<T extends BookmarkData>(
+        args: BookmarkCreateArgs<T>,
+    ): Promise<Bookmark<T>> {
+        return lastValueFrom(this.createBookmark<T>(args));
+    }
+
+    /**
+     * Updates a bookmark with the specified bookmarkId and bookmarkUpdates.
+     *
+     * @template T - The type of the bookmark data.
+     * @param {string} bookmarkId - The identifier of the bookmark to update.
+     * @param {BookmarkUpdate<T>} [bookmarkUpdates] - The updates to apply to the bookmark.
+     * @param {BookmarkUpdateOptions} [options] - The options for updating the bookmark.
+     * @returns {Promise<Bookmark<T>>} - A promise that resolves to the updated bookmark.
+     */
+    public updateBookmark<T extends BookmarkData>(
+        bookmarkId: string,
+        bookmarkUpdates?: BookmarkUpdate<T>,
+        options?: BookmarkUpdateOptions,
+    ): Observable<Bookmark<T>> {
+        if (!bookmarkUpdates && options?.excludePayloadGeneration) {
+            throw new BookmarkProviderError(
+                'Cannot update bookmark without updates and excludePayloadGeneration option',
+            );
+        }
+
+        return new Observable<Bookmark<T>>((subscriber) => {
+            const { ref, action$ } = this._useScopedActions();
+
+            this._log?.debug(`Updating bookmark: ${bookmarkId}, ref: ${ref}`);
+
+            /**
+             * Generate updates with payload
+             * @remarks
+             * If `excludePayloadGeneration` is `true`, it emits the `bookmarkUpdates` directly.
+             * If `excludePayloadGeneration` is `false`, it generates the payload using the `generatePayload` method and emits the updated `bookmarkUpdates` with the generated payload.
+             */
+            const updates$ = options?.excludePayloadGeneration
+                ? of(bookmarkUpdates as BookmarkUpdate<T>)
+                : this.generatePayload<T>(bookmarkUpdates?.payload).pipe(
+                      map(
+                          (payload) =>
+                              ({
+                                  ...bookmarkUpdates,
+                                  payload,
+                              }) as BookmarkUpdate<T>,
+                      ),
+                  );
+
+            // notify listeners that a bookmark is about to be updated
+            const dispatch$ = updates$.pipe(
+                switchMap(async (updates) => {
+                    const { canceled, type } = await this._dispatchEvent('onBookmarkUpdate', {
+                        detail: {
+                            current: bookmarkSelector(this.#store.value, bookmarkId),
+                            updates,
+                        },
+                        cancelable: true,
+                    });
+
+                    if (canceled) {
+                        const error = new BookmarkProviderError(
+                            `event: ${type} was canceled by listener for updating bookmark: ${bookmarkId}, ref: ${ref}`,
+                        );
+                        this._log?.warn(error.message, updates);
+                        throw error;
+                    }
+
+                    return updates;
+                }),
+            );
+
+            // execute the update bookmark action when the updates are resolved and not canceled
+            subscriber.add(
+                dispatch$.subscribe({
+                    error: (error) => subscriber.error(error),
+                    next: (updates) => {
+                        // trigger the store to update the bookmark
+                        this.#store.next(
+                            bookmarkActions.updateBookmark({ bookmarkId, updates }, { ref }),
+                        );
+                    },
+                }),
+            );
+
+            // monitor the failure case when updating a bookmark
+            const failure$ = action$.pipe(
+                filter(bookmarkActions.updateBookmark.failure.match),
+                map(({ payload: cause }) => {
+                    const error = new BookmarkProviderError(
+                        `Failed to update bookmark: ${bookmarkId}`,
+                        {
+                            cause,
+                        },
+                    );
+                    this._log?.info(error.message);
+                    throw error;
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError(
+                            `Timeout while updating bookmark: ${bookmarkId}`,
+                        );
+                    },
+                }),
+            );
+
+            // monitor the success case when updating a bookmark
+            const request$ = action$.pipe(
+                filter(bookmarkActions.updateBookmark.success.match),
+                first(),
+                map(
+                    // TODO: add payload if current bookmark is the same as the updated bookmark
+                    ({ payload }): Bookmark<T> =>
+                        ({
+                            ...bookmarkSelector(this.#store.value, payload.id),
+                            payload: payload.payload,
+                        }) as Bookmark<T>,
+                ),
+                tap((bookmark) => {
+                    this._log?.info(`Bookmark updated: ${bookmark.id}, ref: ${ref}`);
+                    this._dispatchEvent('onBookmarkUpdated', { detail: bookmark });
+                }),
+                raceWith(failure$),
+            );
+
+            // emit the updated bookmark
+            request$.subscribe(subscriber);
+        });
+    }
+
+    /**
+     * Updates a bookmark asynchronously.
+     *
+     * @param bookmark - The bookmark to update.
+     * @returns A promise that resolves to the updated bookmark with its associated data.
+     */
+    public updateBookmarkAsync<T extends BookmarkData>(
+        bookmarkId: string,
+        bookmarkUpdates?: BookmarkUpdate<T>,
+        options?: BookmarkUpdateOptions,
+    ): Promise<Bookmark<T>> {
+        return lastValueFrom(this.updateBookmark<T>(bookmarkId, bookmarkUpdates, options));
+    }
+
+    /**
+     * Deletes a bookmark with the specified bookmarkId.
+     *
+     * @param bookmarkId - The unique identifier of the bookmark to be deleted.
+     * @returns A Promise that resolves when the bookmark is successfully deleted.
+     * @throws {BookmarkProviderError} If there is an error deleting the bookmark.
+     */
+    public deleteBookmark(bookmarkId: string): Observable<void> {
+        return new Observable<void>((subscriber) => {
+            const { ref, action$ } = this._useScopedActions();
+
+            this._log?.debug(`Removing bookmark: ${bookmarkId}, ref: ${ref}`);
+
+            // bookmark to delete
+            const bookmark = bookmarkSelector(this.#store.value, bookmarkId) ?? {
+                id: bookmarkId,
+            };
+
+            // observable that dispatches the 'onBookmarkDelete' event and maps the result
+            const dispatch$ = from(
+                this._dispatchEvent('onBookmarkDelete', {
+                    detail: bookmark,
+                    cancelable: true,
+                }),
+            ).pipe(
+                map(({ canceled, type, detail }) => {
+                    if (canceled) {
+                        const error = new BookmarkProviderError(
+                            `event: ${type} was canceled by listener for removing bookmark: ${bookmarkId}, ref: ${ref}`,
+                        );
+                        this._log?.warn(error.message);
+                        throw error;
+                    }
+                    return detail;
+                }),
+            );
+
+            // execute the delete bookmark action when the event is not canceled
+            subscriber.add(
+                dispatch$.subscribe({
+                    error: (error) => subscriber.error(error),
+                    next: (bookmark) => {
+                        // request the store to delete the bookmark
+                        this.#store.next(bookmarkActions.deleteBookmark(bookmark.id, { ref }));
+                    },
+                }),
+            );
+
+            // monitor the failure case when deleting a bookmark
+            const failure$ = action$.pipe(
+                filter(bookmarkActions.deleteBookmark.failure.match),
+                map(({ payload: cause }) => {
+                    const error = new BookmarkProviderError(
+                        `Failed to update bookmark: ${bookmarkId}`,
+                        {
+                            cause,
+                        },
+                    );
+                    this._log?.warn(error.message);
+                    throw error;
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError(
+                            `Timeout while updating bookmark: ${bookmarkId}`,
+                        );
+                    },
+                }),
+            );
+
+            // monitor the success case when deleting a bookmark
+            const request$ = action$.pipe(
+                filter(bookmarkActions.deleteBookmark.success.match),
+                map(() => undefined),
+                first(),
+                tap(() => {
+                    this._log?.info(`Removed bookmark: ${bookmark.id}, ref: ${ref}`);
+                    this._dispatchEvent('onBookmarkDeleted', { detail: bookmark });
+                }),
+                raceWith(failure$),
+            );
+
+            // emit the deleted bookmark
+            request$.subscribe(subscriber);
+        });
+    }
+
+    /**
+     * Deletes a bookmark asynchronously.
+     *
+     * @param bookmarkId - The ID of the bookmark to delete.
+     * @returns A Promise that resolves when the bookmark is deleted.
+     */
+    public async deleteBookmarkAsync(bookmarkId: string): Promise<void> {
+        return lastValueFrom(this.deleteBookmark(bookmarkId));
+    }
+
+    /**
+     * Adds a bookmark to the 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.
+     */
+    public addBookmarkToFavorites(bookmarkId: string): Observable<BookmarkWithoutData | undefined> {
+        /**
+         * Observable that represents the result of adding a bookmark as a favorite.
+         * Emits a `Bookmark` object or `undefined` if the operation fails to resolve added bookmark.
+         */
+        const result$ = new Observable<Bookmark | undefined>((subscriber) => {
+            const { ref, action$ } = this._useScopedActions();
+
+            this._log?.debug(`Adding bookmark: ${bookmarkId} to favourites, ref: ${ref}`);
+
+            // observable that dispatches the 'onBookmarkFavouriteAdd' event and maps the result
+            const dispatch$ = from(
+                this._dispatchEvent('onBookmarkFavouriteAdd', {
+                    detail: { id: bookmarkId },
+                    cancelable: true,
+                }),
+            ).pipe(
+                map(({ canceled, type }) => {
+                    if (canceled) {
+                        const error = new BookmarkProviderError(
+                            `event: ${type} was canceled by listener for adding favourite bookmark: ${bookmarkId}, ref: ${ref}`,
+                        );
+                        this._log?.info(error.message);
+                        throw error;
+                    }
+                }),
+            );
+
+            // execute the add bookmark as a favorite action when the event is not canceled
+            subscriber.add(
+                dispatch$.subscribe({
+                    error: (error) => subscriber.error(error),
+                    next: () => {
+                        this.#store.next(
+                            bookmarkActions.addBookmarkAsFavourite(bookmarkId, { ref }),
+                        );
+                    },
+                }),
+            );
+
+            // monitor the failure case when adding a bookmark as a favorite
+            const failure$ = action$.pipe(
+                filter(bookmarkActions.addBookmarkAsFavourite.failure.match),
+                map(({ payload: cause }) => {
+                    const error = new BookmarkProviderError(
+                        `Failed to add bookmark to favorites: ${bookmarkId}`,
+                        { cause },
+                    );
+                    this._log?.warn(error.message);
+                    throw error;
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError(
+                            `Timeout while adding bookmark to favorites: ${bookmarkId}`,
+                        );
+                    },
+                }),
+            );
+
+            // monitor the success case when adding a bookmark as a favorite
+            const request$ = action$.pipe(
+                filter(bookmarkActions.addBookmarkAsFavourite.success.match),
+                switchMap(({ payload }) => this.getBookmark(payload, { excludePayload: true })),
+                tap((bookmark) => {
+                    this._log?.info(`Added bookmark: ${bookmarkId} to favourites, ref: ${ref}`);
+                    this._dispatchEvent('onBookmarkFavouriteAdded', { detail: bookmark });
+                }),
+                raceWith(failure$),
+            );
+
+            // emit the added bookmark
+            return request$.subscribe(subscriber);
+        });
+
+        return result$;
+    }
+
+    /**
+     * Asynchronously adds a bookmark to the user's favorites.
+     *
+     * @param bookmarkId - The ID of the bookmark to add to the user's favorites.
+     * @returns A Promise that resolves to the added Bookmark, or null if the operation failed.
+     */
+    public addBookmarkToFavoritesAsync(bookmarkId: string): Promise<Bookmark | undefined> {
+        return lastValueFrom(this.addBookmarkToFavorites(bookmarkId));
+    }
+
+    /**
+     * Removes a bookmark as a favorite.
+     *
+     * @param bookmarkId - The ID of the bookmark to remove as a favorite.
+     * @returns A Promise that resolves when the bookmark is successfully removed as a favorite.
+     * @throws {BookmarkProviderError} If the event is canceled or if there is a failure in removing the bookmark as a favorite.
+     */
+    public removeBookmarkAsFavorite(bookmarkId: string): Observable<void> {
+        /**
+         * Represents an observable that emits void values when a bookmark's favorite is removed.
+         */
+        const result$ = new Observable<void>((subscriber) => {
+            const { ref, action$ } = this._useScopedActions();
+
+            this._log?.debug(`Removing bookmark: ${bookmarkId} from favourites, ref: ${ref}`);
+
+            // get the bookmark to remove as a favorite
+            const bookmark = bookmarkSelector(this.#store.value, bookmarkId) ?? { id: bookmarkId };
+
+            // observable that dispatches the 'onBookmarkFavouriteRemove' event and maps the result
+            const dispatch$ = from(
+                this._dispatchEvent('onBookmarkFavouriteRemove', {
+                    detail: bookmark,
+                    cancelable: true,
+                }),
+            ).pipe(
+                map(({ canceled, type, detail }) => {
+                    if (canceled) {
+                        const error = new BookmarkProviderError(
+                            `event: ${type} was canceled by listener for removing favourite bookmark: ${bookmarkId}, ref: ${ref}`,
+                        );
+                        this._log?.warn(error.message);
+                        throw error;
+                    }
+                    return detail;
+                }),
+            );
+
+            // execute the remove bookmark as a favorite action when the event is not canceled
+            subscriber.add(
+                dispatch$.subscribe({
+                    error: (error) => subscriber.error(error),
+                    next: (detail) => {
+                        // request the store to remove the bookmark as a favorite
+                        this.#store.next(
+                            bookmarkActions.removeBookmarkAsFavourite(detail.id, { ref }),
+                        );
+                    },
+                }),
+            );
+
+            // monitor the failure case when removing a bookmark as a favorite
+            const failure$ = action$.pipe(
+                filter(bookmarkActions.removeBookmarkAsFavourite.failure.match),
+                map(({ payload: cause }) => {
+                    const error = new BookmarkProviderError(
+                        `Failed to remove bookmark: ${bookmarkId} from favourites`,
+                        {
+                            cause,
+                        },
+                    );
+                    this._log?.warn(error.message);
+                    throw error;
+                }),
+                timeout({
+                    each: defaultTimeout,
+                    with: () => {
+                        throw new BookmarkProviderError(
+                            `Timeout while removing bookmark: ${bookmarkId} from favourites`,
+                        );
+                    },
+                }),
+            );
+
+            // monitor the success case when removing a bookmark as a favorite
+            const request$ = action$.pipe(
+                filter(bookmarkActions.removeBookmarkAsFavourite.success.match),
+                tap(() => {
+                    this._log?.info(`Removed bookmark: ${bookmarkId} from favourites, ref: ${ref}`);
+                    this._dispatchEvent('onBookmarkFavouriteRemoved', { detail: bookmark });
+                }),
+                map(() => {}),
+                raceWith(failure$),
+            );
+
+            // emit the removed bookmark
+            request$.subscribe(subscriber);
+        });
+
+        return result$;
+    }
+
+    /**
+     * Removes a bookmark as a favorite asynchronously.
+     *
+     * @param bookmarkId - The ID of the bookmark to remove as a favorite.
+     * @returns A Promise that resolves when the bookmark is successfully removed as a favorite.
+     */
+    public removeBookmarkAsFavoriteAsync(bookmarkId: string): Promise<void> {
+        return lastValueFrom(this.removeBookmarkAsFavorite(bookmarkId));
+    }
+
+    /**
+     * 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.
+     */
+    public isBookmarkInFavorites(bookmarkId: string): Observable<boolean> {
+        this._log?.debug(`Checking if bookmark: ${bookmarkId} is in favourites`);
+
+        // Check if the bookmark is a favorite
+        return from(this._apiClient.isBookmarkFavorite(bookmarkId)).pipe(
+            catchError((err) => {
+                const error = new BookmarkProviderError(
+                    `Failed to check if bookmark: ${bookmarkId} is in favourites`,
+                    err,
+                );
+                this._log?.error(error.message, error);
+                throw error;
+            }),
+            tap((isFavorite) => {
+                this._log?.debug(
+                    `Bookmark: ${bookmarkId} is ${isFavorite ? 'in' : 'not in'} favourites`,
+                );
+            }),
+        );
+    }
+
+    /**
+     * Checks if the specified bookmark is in the user's 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 user's favorites.
+     */
+    public isBookmarkInFavoritesAsync(bookmarkId: string): Promise<boolean> {
+        return lastValueFrom(this.isBookmarkInFavorites(bookmarkId));
+    }
+
+    protected _getBookmarkInfo(
+        bookmarkId: string,
+        options?: { timeout?: number },
+    ): Observable<BookmarkWithoutData> {
+        // only actions with the specified reference are considered
+        const { action$ } = this._useScopedActions(bookmarkId);
+
+        // observable stream that emits the bookmark data when the fetch action is successful
+        const success$ = action$.pipe(
+            filter(bookmarkActions.fetchBookmark.success.match),
+            map((action) => action.payload),
+            first(),
+        );
+
+        // observable stream that emits an error when fetching bookmark data fails
+        const failure$ = this.#store.action$.pipe(
+            filter(bookmarkActions.fetchBookmark.failure.match),
+            map((action) => {
+                throw new BookmarkProviderError(
+                    `Failed to fetch bookmark data: ${bookmarkId}`,
+                    action.payload,
+                );
+            }),
+            timeout({
+                each: options?.timeout ?? 2 * 60 * 1000,
+                with: () => {
+                    throw new BookmarkProviderError(
+                        `Timeout while fetching bookmark data: ${bookmarkId}`,
+                    );
+                },
+            }),
+        );
+
+        this.#store.next(bookmarkActions.fetchBookmark(bookmarkId, { ref: bookmarkId }));
+
+        return success$.pipe(raceWith(failure$));
+    }
+
+    protected _getBookmarkData<T extends BookmarkData>(
+        bookmarkId: string,
+        options?: { timeout?: number },
+    ): Observable<T | null> {
+        // only actions with the specified reference are considered
+        const { action$ } = this._useScopedActions(bookmarkId);
+
+        // observable stream that emits the bookmark data when the fetch action is successful
+        const success$ = action$.pipe(
+            filter(bookmarkActions.fetchBookmarkData.success.match),
+            map((action) => action.payload.data as T),
+            first(),
+        );
+
+        // observable stream that emits an error when fetching bookmark data fails
+        const failure$ = this.#store.action$.pipe(
+            filter(bookmarkActions.fetchBookmarkData.failure.match),
+            map((action) => {
+                throw new BookmarkProviderError(
+                    `Failed to fetch bookmark data: ${bookmarkId}`,
+                    action.payload,
+                );
+            }),
+            timeout({
+                each: options?.timeout ?? defaultTimeout,
+                with: () => {
+                    throw new BookmarkProviderError(
+                        `Timeout while fetching bookmark data: ${bookmarkId}`,
+                    );
+                },
+            }),
+        );
+
+        // request the store to fetch the bookmark data
+        this.#store.next(bookmarkActions.fetchBookmarkData(bookmarkId, { ref: bookmarkId }));
+
+        return success$.pipe(raceWith(failure$));
+    }
+
+    /**
+     * Dispatches an event of the specified type with the provided arguments.
+     *
+     * @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.
+     */
+    protected async _dispatchEvent<TType extends keyof BookmarkProviderEventMap>(
+        type: TType,
+        args: FrameworkEventInitType<BookmarkProviderEventMap[NoInfer<TType>]>,
+    ): Promise<BookmarkProviderEventMap[NoInfer<TType>]> {
+        // create a new event instance
+        const event = new FrameworkEvent(type, {
+            source: this,
+            canBubble: true,
+            ...args,
+        }) as BookmarkProviderEventMap[NoInfer<TType>];
+
+        if (this._event) {
+            this._log?.debug(`dispatching event ${type}`, args);
+            const { canceled } = await this._event.dispatchEvent(event);
+            if (canceled) {
+                this._log?.debug(`event ${type} was canceled`, args);
+            }
+        }
+        return event;
+    }
+
+    protected _useScopedActions<TAction extends BookmarkActions>(
+        ref?: string,
+    ): {
+        ref: string;
+        action$: Observable<TAction>;
+    } {
+        /**
+         * Generates a unique identifier for the operation
+         */
+        ref ??= generateGUID();
+
+        /**
+         * Observable stream of actions filtered by a specific reference.
+         */
+        const action$ = this.#store.action$.pipe(
+            filter((action): action is TAction => 'meta' in action && action.meta?.ref === ref),
+        );
+
+        return { ref, action$ };
+    }
+
+    /**
+     * Disposes the BookmarkProvider.
+     */
+    dispose(): void {
+        this._log?.debug('disposing BookmarkProvider');
+        this.#subscriptions.unsubscribe();
+    }
+}