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

package/dist/types/{BookmarkProvider.reducer.d.ts → create-bookmark-reducer.d.ts}

@@ -1,10 +1,10 @@
-import type { BookmarkState } from './BookmarkProvider.store';
-import type { BookmarkFlowError } from './BookmarkProvider.error';
+import type { BookmarkState } from './create-bookmark-store';
+import type { BookmarkFlowError } from './BookmarkFlowError';
 import type { BookmarkWithoutData } from './types';
 /**
  * Creates a reducer for managing the state of bookmarks.
  *
- * @todo add fast-deep-equal to compare bookmarks
+ * @todo TODO(#5135) - add fast-deep-equal to compare bookmarks
  *
  * @param initialState - The initial state of the bookmarks.
  * @returns A reducer function for managing the bookmarks state.
@@ -18,67 +18,67 @@ export declare const createBookmarkReducer: (initialState?: Partial<BookmarkStat
 } | {
     payload: import("./types").Bookmark<any> | null;
     type: "set_current_bookmark";
-} | import("@equinor/fusion-observable").PayloadAction<string, "fetch_bookmark::request", {
+} | import("@equinor/fusion-observable").PayloadAction<string, "add_favourite_bookmark::request", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<string, "fetch_bookmark_payload::request", {
-    ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<import("./BookmarkClient.interface").BookmarksFilter | undefined, "fetch_bookmarks::request", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<string, "add_favourite_bookmark::success", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<{
-    bookmarkId: string;
-    updates: import("./BookmarkClient.interface").BookmarkUpdate;
-}, "set_bookmark::request", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<string, "delete_bookmark::request", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<import("./BookmarkClient.interface").BookmarkNew, "create_bookmark::request", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<string, "delete_bookmark::success", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "delete_bookmark::request", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<string, "fetch_bookmark::request", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "remove_bookmark::request", {
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<string, "fetch_bookmark_payload::request", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "add_favourite_bookmark::request", {
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<string, "remove_bookmark::request", {
     ref: string;
 }, never> | import("@equinor/fusion-observable").PayloadAction<string, "remove_favourite_bookmark::request", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkWithoutData, "fetch_bookmark::success", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<string, "remove_favourite_bookmark::success", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "fetch_bookmark::failure", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmark<any>, "create_bookmark::success", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<{
-    bookmarkId: string;
-    data: import("./types").BookmarkData;
-}, "fetch_bookmark_payload::success", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmark<any>, "set_bookmark::success", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "fetch_bookmark_payload::failure", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "add_favourite_bookmark::failure", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmarks, "fetch_bookmarks::success", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "create_bookmark::failure", {
+    ref: string;
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "delete_bookmark::failure", {
+    ref: string;
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "fetch_bookmark::failure", {
+    ref: string;
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "fetch_bookmark_payload::failure", {
     ref: string;
 } | undefined, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "fetch_bookmarks::failure", {
     ref: string;
-} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmark<any>, "set_bookmark::success", {
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "remove_bookmark::failure", {
+    ref: string;
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "remove_favourite_bookmark::failure", {
     ref: string;
 }, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "set_bookmark::failure", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmark<any>, "create_bookmark::success", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<import("./BookmarkClient.interface").BookmarkNew, "create_bookmark::request", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "create_bookmark::failure", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkWithoutData, "fetch_bookmark::success", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "delete_bookmark::success", {
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<import("./types").Bookmarks, "fetch_bookmarks::success", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "delete_bookmark::failure", {
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<{
+    bookmarkId: string;
+    data: import("./types").BookmarkData;
+}, "fetch_bookmark_payload::success", {
+    ref: string;
+} | undefined, never> | import("@equinor/fusion-observable").PayloadAction<{
+    bookmarkId: string;
+    updates: import("./BookmarkClient.interface").BookmarkUpdate;
+}, "set_bookmark::request", {
     ref: string;
 }, never> | import("@equinor/fusion-observable").PayloadAction<{
-    type: "delete_bookmark" | "remove_favourite_bookmark";
+    type: 'delete_bookmark' | 'remove_favourite_bookmark';
     bookmarkId: string;
 }, "remove_bookmark::success", {
     ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "remove_bookmark::failure", {
-    ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "add_favourite_bookmark::success", {
-    ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "add_favourite_bookmark::failure", {
-    ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<string, "remove_favourite_bookmark::success", {
-    ref: string;
-}, never> | import("@equinor/fusion-observable").PayloadAction<BookmarkFlowError, "remove_favourite_bookmark::failure", {
+}, never> | import("@equinor/fusion-observable").PayloadAction<import("./BookmarkClient.interface").BookmarksFilter | undefined, "fetch_bookmarks::request", {
     ref: string;
-}, never>>;
+} | undefined, never>>;

package/dist/types/{BookmarkProvider.store.d.ts → create-bookmark-store.d.ts}

@@ -1,6 +1,6 @@
 import { FlowSubject, type ActionBaseType } from '@equinor/fusion-observable';
-import type { BookmarkActions } from './BookmarkProvider.actions';
-import type { BookmarkFlowError } from './BookmarkProvider.error';
+import type { BookmarkActions } from './bookmark-actions';
+import type { BookmarkFlowError } from './BookmarkFlowError';
 import type { IBookmarkClient } from './BookmarkClient.interface';
 import type { Bookmark, BookmarkWithoutData } from './types';
 /**

package/dist/types/enable-bookmark.d.ts

@@ -1,5 +1,5 @@
 import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-import type { BookmarkModuleConfigurator } from './BookmarkConfigurator';
+import type { BookmarkModuleConfigurator } from './BookmarkModuleConfigurator';
 /**
  * Enables the bookmark module on a Fusion Framework module configurator.
  *

package/dist/types/index.d.ts

@@ -1,4 +1,15 @@
-export { BookmarkModuleConfigurator } from './BookmarkConfigurator';
+/**
+ * Bookmark module for the Fusion Framework.
+ *
+ * Provides bookmark management (create, update, delete, favourite) with
+ * application-scoped payloads and event-driven state updates.
+ *
+ * @see {@link enableBookmark} to enable the module in a configurator.
+ * @see {@link BookmarkProvider} for the runtime provider API.
+ *
+ * @packageDocumentation
+ */
+export { BookmarkModuleConfigurator } from './BookmarkModuleConfigurator';
 export type { IBookmarkClient, BookmarkNew, BookmarkUpdate, BookmarksFilter, } from './BookmarkClient.interface';
 export { default, BookmarkModule, module as bookmarkModule, moduleKey as bookmarkModuleKey, } from './bookmark-module';
 export { BookmarkProvider } from './BookmarkProvider';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "4.0.2";
+export declare const version = "4.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-bookmark",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -41,19 +41,19 @@
     "immer": "^11.0.0",
     "rxjs": "^7.8.1",
     "uuid": "^14.0.0",
-    "@equinor/fusion-framework-module": "^6.0.0",
-    "@equinor/fusion-observable": "^9.0.1",
-    "@equinor/fusion-log": "^2.0.0",
-    "@equinor/fusion-query": "^7.0.1"
+    "@equinor/fusion-framework-module": "^6.1.1",
+    "@equinor/fusion-query": "^7.0.2",
+    "@equinor/fusion-observable": "^9.1.1",
+    "@equinor/fusion-log": "^2.0.1"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module-event": "^6.0.0",
-    "@equinor/fusion-framework-module-app": "^8.0.2",
-    "@equinor/fusion-framework-module-http": "^8.0.1",
-    "@equinor/fusion-framework-module-context": "^8.0.0",
-    "@equinor/fusion-framework-module-services": "^8.0.1"
+    "@equinor/fusion-framework-module-app": "^8.0.3",
+    "@equinor/fusion-framework-module-event": "^6.0.1",
+    "@equinor/fusion-framework-module-context": "^8.0.1",
+    "@equinor/fusion-framework-module-http": "^8.0.4",
+    "@equinor/fusion-framework-module-services": "^8.0.2"
   },
   "scripts": {
     "build": "tsc -b"

package/src/BookmarkClient.ts

@@ -82,6 +82,7 @@ export class BookmarkClient implements IBookmarkClient {
    * Constructs a new `BookmarkClient` instance with the provided `BookmarksApiClient`.
    *
    * @param api - The `BookmarksApiClient` instance to use for making API requests.
+   * @param options - Optional client options, such as the cache expiry time.
    */
   constructor(api: BookmarksApiClient<'json$'>, options?: { expire?: number }) {
     this.#api = api;
@@ -92,6 +93,7 @@ export class BookmarkClient implements IBookmarkClient {
     this.#queryBookmark = new Query({
       client: {
         fn: (args: { bookmarkId: string }) => {
+          // strip the payload from the fetched bookmark before caching
           return this.#api.get('v2', args).pipe(map(parseBookmarkWithoutPayload));
         },
       },
@@ -103,9 +105,13 @@ export class BookmarkClient implements IBookmarkClient {
     this.#queryBookmarks = new Query({
       client: {
         fn: (filter?: BookmarksFilter) => {
-          return this.#api
-            .query('v2', { filter })
-            .pipe(map((res) => res.map(parseBookmarkWithoutPayload)));
+          // strip the payload from each fetched bookmark before caching
+          return this.#api.query('v2', { filter }).pipe(
+            map((res) =>
+              // strip the payload field from each bookmark
+              res.map(parseBookmarkWithoutPayload),
+            ),
+          );
         },
       },
       key: (args) => JSON.stringify(args ?? ''),
@@ -115,6 +121,7 @@ export class BookmarkClient implements IBookmarkClient {
     this.#queryBookmarkData = new Query({
       client: {
         fn: (args: { bookmarkId: string }) => {
+          // extract only the payload from the API response
           return this.#api.getPayload('v1', args).pipe(map((res) => res.payload));
         },
       },
@@ -130,16 +137,19 @@ export class BookmarkClient implements IBookmarkClient {
 
   /** @inheritdoc */
   public getAllBookmarks(filter?: BookmarksFilter): ObservableInput<Bookmark[]> {
+    // unwrap the query result value
     return this.#queryBookmarks.query(filter).pipe(map((res) => res.value as Bookmark[]));
   }
 
   /** @inheritdoc */
   public getBookmarkById(bookmarkId: string): ObservableInput<BookmarkWithoutData> {
+    // unwrap the query result value
     return this.#queryBookmark.query({ bookmarkId }).pipe(map((res) => res.value));
   }
 
   /** @inheritdoc */
   public getBookmarkData<T extends BookmarkData>(bookmarkId: string): ObservableInput<T> {
+    // unwrap the query result value
     return this.#queryBookmarkData.query({ bookmarkId }).pipe(map((res): T => res.value as T));
   }
 
@@ -148,9 +158,11 @@ export class BookmarkClient implements IBookmarkClient {
     bookmarkId: string,
     data: T,
   ): ObservableInput<T> {
+    // update the payload cache once the mutation succeeds
     return this.#api.patch('v1', { bookmarkId, updates: { payload: data } }).pipe(
       map((res) => res.payload as T),
       tap((updatedData) => {
+        // only update the cache when data was actually returned
         if (updatedData) {
           this.#queryBookmarkData.mutate(
             { bookmarkId },
@@ -166,6 +178,7 @@ export class BookmarkClient implements IBookmarkClient {
   public createBookmark<T extends BookmarkData>(
     newBookmark: BookmarkNew<T>,
   ): ObservableInput<Bookmark<T>> {
+    // parse the response and update caches once the bookmark is created
     return this.#api.create('v1', newBookmark).pipe(
       map((response) => parseBookmark<T>(response)),
       /** update the bookmark cache */
@@ -177,6 +190,7 @@ export class BookmarkClient implements IBookmarkClient {
           { value: bookmark, updated: Date.now() },
           { allowCreation: true },
         );
+        // only cache the payload if the created bookmark has one
         if (payload) {
           this.#queryBookmarkData.mutate(
             { bookmarkId: bookmark.id },
@@ -194,6 +208,7 @@ export class BookmarkClient implements IBookmarkClient {
     bookmarkId: string,
     updates: BookmarkUpdate<T>,
   ): ObservableInput<Bookmark<T>> {
+    // parse the response and share it across the cache-update subscriptions below
     const update$ = this.#api.patch('v1', { bookmarkId, updates: updates }).pipe(
       map((response) => parseBookmark<T>(response)),
       shareReplay(),
@@ -217,6 +232,7 @@ export class BookmarkClient implements IBookmarkClient {
       subscriber.add(
         update$.subscribe((updatedBookmark) => {
           const { payload } = updatedBookmark;
+          // only cache the payload when present, otherwise clear any stale cache entry
           if (payload) {
             this.#queryBookmarkData.mutate(
               {
@@ -253,6 +269,7 @@ export class BookmarkClient implements IBookmarkClient {
 
   /** @inheritdoc */
   public addBookmarkToFavorites(bookmarkId: string): ObservableInput<boolean> {
+    // invalidate the bookmarks list cache once favorited
     return this.#api
       .addFavourite('v1', { bookmarkId })
       .pipe(tap(() => this.#queryBookmarks.invalidate()));
@@ -260,6 +277,7 @@ export class BookmarkClient implements IBookmarkClient {
 
   /** @inheritdoc */
   public removeBookmarkFromFavorites(bookmarkId: string): ObservableInput<boolean> {
+    // invalidate the bookmarks list cache once unfavorited
     return this.#api
       .removeFavourite('v1', { bookmarkId })
       .pipe(tap(() => this.#queryBookmarks.invalidate()));

package/src/{BookmarkProvider.error.ts → BookmarkFlowError.ts}

@@ -1,6 +1,6 @@
 import type { ActionWithSuffix } from '@equinor/fusion-observable';
 
-import type { BookmarkActions } from './BookmarkProvider.actions';
+import type { BookmarkActions } from './bookmark-actions';
 
 /**
  * Error thrown inside bookmark store flows (side-effect pipelines) when an
@@ -10,6 +10,13 @@ import type { BookmarkActions } from './BookmarkProvider.actions';
  * correlate errors back to specific operations.
  */
 export class BookmarkFlowError extends Error {
+  /**
+   * Constructs a new `BookmarkFlowError`.
+   *
+   * @param message - Human-readable error message.
+   * @param action - The request action that triggered the failed flow.
+   * @param options - Optional `ErrorOptions` (e.g. `cause`).
+   */
   constructor(
     message: string,
     /** The request action that triggered the failed flow. */
@@ -28,9 +35,4 @@ export class BookmarkFlowError extends Error {
  * Distinct from {@link BookmarkFlowError}, which is scoped to internal
  * store flow pipelines.
  */
-export class BookmarkProviderError extends Error {
-  constructor(message: string, options?: ErrorOptions) {
-    super(message, options);
-    this.name = 'BookmarkProviderError';
-  }
-}
+export { BookmarkProviderError } from './BookmarkProviderError';

package/src/{BookmarkConfigurator.ts → BookmarkModuleConfigurator.ts}

@@ -1,4 +1,4 @@
-import type { z, ZodError } from 'zod';
+import type { ZodError } from 'zod';
 
 import {
   BaseConfigBuilder,
@@ -45,6 +45,13 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
   #log?: ILogger;
   defaultExpireTime = 1 * 60 * 1000; // Default expiration time for bookmarks
 
+  /**
+   * Constructs a new `BookmarkModuleConfigurator`.
+   *
+   * @param options - Optional configurator options.
+   * @param options.log - Logger instance inherited from the parent module, if any.
+   * @param options.ref - Reference to sibling module instances available during configuration.
+   */
   constructor(options?: { log?: ILogger; ref?: ModulesInstanceType<[BookmarkModule]> }) {
     super();
     const { log } = options ?? {};
@@ -64,6 +71,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    */
   public setLogLevel(level: LogLevel) {
     this._set('logLevel', async () => level);
+    // propagate the level to the configurator's own logger, if one is set
     if (this.#log) {
       this.#log.level = level;
     }
@@ -84,6 +92,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
   public setClient(
     client: ConfigBuilderCallback<BookmarkModuleConfig['client']> | BookmarkModuleConfig['client'],
   ) {
+    // a callback receives the module initializer and resolves the client itself
     if (typeof client === 'function') {
       this._set('client', (init) => client(init));
     } else {
@@ -102,6 +111,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
   public setParent(
     parent: ConfigBuilderCallback<BookmarkModuleConfig['parent']> | BookmarkModuleConfig['parent'],
   ) {
+    // a callback receives the module initializer and resolves the parent itself
     if (typeof parent === 'function') {
       this._set('parent', (init) => parent(init));
     } else {
@@ -128,6 +138,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
       | ConfigBuilderCallback<BookmarkModuleConfig['sourceSystem']>
       | BookmarkModuleConfig['sourceSystem'],
   ) {
+    // a callback receives the module initializer and resolves the source system itself
     if (typeof sourceSystem === 'function') {
       this._set('sourceSystem', sourceSystem);
     } else {
@@ -167,6 +178,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
 
   /**
    * Sets a filter for the bookmark module.
+   * @template TKey - The filter key being set.
    * @param key - The key of the filter to set.
    * @param value - The value to set for the filter.
    *
@@ -179,7 +191,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
     value: BookmarkModuleConfig['filters'][TKey],
   ) {
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
+    // @ts-expect-error
     this._set(`filters.${key}`, async () => value);
   }
 
@@ -204,12 +216,14 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
 
       // Check if parent and parent version compatible
       const parentModules = init.ref as ModulesInstanceType<[BookmarkModule]>;
+      // only use the parent module's bookmark provider if it's actually present
       if (parentModules && 'bookmark' in parentModules) {
         const parent = parentModules.bookmark;
-        if (
-          'version' in parent &&
-          (parent as unknown as BookmarkProvider).version.satisfies('>=2.0.0')
-        ) {
+        // `parent` is narrowed to `{ version: unknown }` by the `'version' in parent` check below,
+        // so it must be cast through `unknown` to access `BookmarkProvider`-specific members.
+        const parentProvider = parent as unknown as BookmarkProvider;
+        // only inherit from a parent whose version satisfies the minimum supported range
+        if ('version' in parent && parentProvider.version.satisfies('>=2.0.0')) {
           this._set('parent', async () => parent);
         } else {
           this.#log?.warn('invalid version of parent BookmarkProvider provided');
@@ -254,7 +268,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    */
   protected async _createDefaultContextResolver(
     init: ConfigBuilderCallbackArgs,
-  ): Promise<BookmarkModuleConfig['resolve']['context'] | void> {
+  ): Promise<BookmarkModuleConfig['resolve']['context'] | undefined> {
     // Check if context module is available and use context provider if available
     if (init.hasModule('context')) {
       this.#log?.debug('Context module available, awaiting instance');
@@ -276,7 +290,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    */
   protected async _createDefaultApplicationResolver(
     init: ConfigBuilderCallbackArgs,
-  ): Promise<BookmarkModuleConfig['resolve']['application'] | void> {
+  ): Promise<BookmarkModuleConfig['resolve']['application'] | undefined> {
     // Check if app module is available and use app provider if available
     if (init.hasModule('app')) {
       this.#log?.debug('App module available, awaiting instance');
@@ -285,6 +299,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
       this.#log?.debug('App provider available, creating application resolver');
       return async () => {
         const app = appProvider.current;
+        // only resolve the application if there is a currently loaded app
         if (app) {
           return {
             appKey: app.appKey,
@@ -297,6 +312,11 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
     }
   }
 
+  /**
+   * @internal Resolves the {@link AppModuleProvider} for the bookmark module.
+   * @param init - The configuration initialization object.
+   * @returns A promise that resolves to the app module provider, or undefined if unavailable.
+   */
   protected async _resolveAppProvider(
     init: ConfigBuilderCallbackArgs,
   ): Promise<AppModuleProvider | undefined> {
@@ -316,7 +336,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    */
   protected async _resolveEventProvider(
     init: ConfigBuilderCallbackArgs,
-  ): Promise<BookmarkModuleConfig['eventProvider'] | void> {
+  ): Promise<BookmarkModuleConfig['eventProvider'] | undefined> {
     // Check if event module is available
     if (init.hasModule('event')) {
       this.#log?.debug('Event module available, awaiting instance');
@@ -331,12 +351,12 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    */
   protected async _createDefaultClient(
     init: ConfigBuilderCallbackArgs,
-  ): Promise<BookmarkModuleConfig['client'] | void> {
+  ): Promise<BookmarkModuleConfig['client'] | undefined> {
     try {
       const apiProvider = await this._getServiceProvider(init);
       const api = await apiProvider.createBookmarksClient('json$');
       return new BookmarkClient(api);
-    } catch (err) {
+    } catch (_err) {
       this.#log?.warn('Failed to create bookmark api client');
     }
   }
@@ -345,6 +365,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
    * @internal retrieves the service provider from the configuration initialization object.
    * @param init - The configuration initialization object.
    * @returns A promise that resolves to the service provider.
+   * @throws {Error} When no services module or parent service module is available.
    */
   protected async _getServiceProvider(init: ConfigBuilderCallbackArgs): Promise<IApiProvider> {
     // check if services module is available
@@ -357,6 +378,7 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
 
     // check if parent has services module
     const parentServiceModule = (init.ref as ModulesInstanceType<[ServicesModule]>)?.services;
+    // reuse the parent's service module if one is available
     if (parentServiceModule) {
       return parentServiceModule;
     }
@@ -366,6 +388,13 @@ export class BookmarkModuleConfigurator extends BaseConfigBuilder<BookmarkModule
     throw Error('[BookmarkConfigurator] No service provider configures [ServicesModule] ');
   }
 
+  /**
+   * @internal Validates and normalizes the resolved config before it's returned from `build`.
+   * @param config - The partially-resolved bookmark module config.
+   * @param _init - The configuration initialization object (unused).
+   * @returns The validated {@link BookmarkModuleConfig}.
+   * @throws {ZodError} When the config fails schema validation.
+   */
   protected async _processConfig(
     config: Partial<BookmarkModuleConfig>,
     _init: ConfigBuilderCallbackArgs,

package/src/BookmarkProvider.interface.ts

@@ -1,9 +1,9 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
+// biome-ignore-all lint/suspicious/noExplicitAny: `BookmarkData = any` generic defaults must remain bivariant — `unknown` breaks assignability of concrete `Bookmark<T>`/`BookmarkPayloadGenerator<TData>` instances to the default-typed generic
 import type { Observable, ObservableInput } from 'rxjs';
 import type { Bookmark, BookmarkData, BookmarkWithoutData } from './types';
 import type { BookmarkNew, BookmarkUpdate } from './BookmarkClient.interface';
 import type { BookmarkProviderEventMap } from './BookmarkProvider.events';
-import type { BookmarkState } from './BookmarkProvider.store';
+import type { BookmarkState } from './create-bookmark-store';
 
 /**
  * Arguments for creating a bookmark via {@link IBookmarkProvider.createBookmark}.
@@ -45,6 +45,7 @@ export type BookmarkUpdateOptions = {
 export type BookmarkPayloadGenerator<TData extends BookmarkData = any> = (
   payload?: Partial<TData> | null,
   initial?: Partial<TData> | null,
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior for draft-mutating generators — `undefined` would break assignability of generators that only conditionally return a partial payload
 ) => Promise<Partial<TData> | void> | Partial<TData> | void;
 
 /**

package/src/BookmarkProvider.selectors.ts

@@ -1,5 +1,5 @@
-import type { BookmarkFlowError } from './BookmarkProvider.error';
-import type { BookmarkState } from './BookmarkProvider.store';
+import type { BookmarkFlowError } from './BookmarkFlowError';
+import type { BookmarkState } from './create-bookmark-store';
 import type { Bookmark, BookmarkData } from './types';
 
 /**
@@ -20,6 +20,8 @@ export const bookmarksSelector = (state: BookmarkState): Bookmark[] => {
  * @param id - The bookmark identifier to look up.
  * @returns The matching bookmark, or `undefined` if not found.
  */
+// tightly coupled group of store selectors
+// fusion-lint-disable-next-line single-export-per-file
 export const bookmarkSelector = <T extends BookmarkData>(
   state: BookmarkState,
   id: string,
@@ -34,6 +36,8 @@ export const bookmarkSelector = <T extends BookmarkData>(
  * @param state - The current bookmark store state.
  * @returns The active bookmark, `null` if explicitly cleared, or `undefined` if never set.
  */
+// tightly coupled group of store selectors
+// fusion-lint-disable-next-line single-export-per-file
 export const activeBookmarkSelector = <T extends BookmarkData>(
   state: BookmarkState,
 ): Bookmark<T> | null | undefined => {
@@ -46,6 +50,8 @@ export const activeBookmarkSelector = <T extends BookmarkData>(
  * @param state - The bookmark state.
  * @returns The status from the bookmark state.
  */
+// tightly coupled group of store selectors
+// fusion-lint-disable-next-line single-export-per-file
 export const statusSelector = (state: BookmarkState): BookmarkState['status'] => {
   return state.status;
 };
@@ -56,6 +62,8 @@ export const statusSelector = (state: BookmarkState): BookmarkState['status'] =>
  * @param state - The bookmark state.
  * @returns An array of bookmark flow errors.
  */
+// tightly coupled group of store selectors
+// fusion-lint-disable-next-line single-export-per-file
 export const errorsSelector = (state: BookmarkState): Array<BookmarkFlowError> => {
   return Object.values(state.errors);
 };