@equinor/fusion-framework-module-bookmark 4.0.3 → 4.1.0-next.0

package/src/mock/BookmarkMockClient.ts

@@ -0,0 +1,310 @@
+import { of, throwError, type ObservableInput } from 'rxjs';
+import { v4 as generateGUID } from 'uuid';
+
+import type {
+  BookmarkNew,
+  BookmarksFilter,
+  BookmarkUpdate,
+  IBookmarkClient,
+} from '../BookmarkClient.interface';
+import type { Bookmark, BookmarkData, BookmarkUser, BookmarkWithoutData } from '../types';
+
+/** Attributed to every bookmark the mock client creates or updates. */
+const mockUser: BookmarkUser = { id: 'mock-user', name: 'Mock User' };
+
+/**
+ * Strips the `payload` field from a bookmark, mirroring what the real
+ * `BookmarkClient` does before returning a {@link BookmarkWithoutData}.
+ *
+ * @param bookmark - The bookmark to strip.
+ * @returns The bookmark without its payload.
+ */
+const stripPayload = (bookmark: Bookmark): BookmarkWithoutData => {
+  const { payload: _payload, ...rest } = bookmark;
+  return rest;
+};
+
+/**
+ * Checks whether a seeded bookmark matches the given {@link BookmarksFilter}.
+ *
+ * @remarks
+ * `appKey`, `contextId`, and `sourceSystem` are checked, mirroring what the real
+ * `BookmarkProvider` resolves and passes through as a filter (`BookmarkProvider.getAllBookmarks`
+ * always includes `sourceSystem`, so it must be matched even though it's rarely set explicitly).
+ *
+ * @param bookmark - The seeded bookmark to test.
+ * @param filter - The filter to match against, if any.
+ * @returns `true` when the bookmark satisfies every constraint in `filter`.
+ */
+const matchesFilter = (bookmark: Bookmark, filter?: BookmarksFilter): boolean => {
+  // no filter means every seeded bookmark matches
+  if (!filter) return true;
+  // an appKey constraint excludes bookmarks attributed to a different app
+  if (filter.appKey && bookmark.appKey !== filter.appKey) return false;
+  // a contextId constraint excludes bookmarks attributed to a different context
+  if (filter.contextId && bookmark.context?.id !== filter.contextId) return false;
+  // a sourceSystem constraint excludes bookmarks attributed to a different source system
+  if (filter.sourceSystem) {
+    const { identifier, name, subSystem } = filter.sourceSystem;
+    // an identifier constraint excludes bookmarks attributed to a different source system identifier
+    if (identifier && bookmark.sourceSystem?.identifier !== identifier) return false;
+    // a name constraint excludes bookmarks attributed to a different source system name
+    if (name !== undefined && bookmark.sourceSystem?.name !== name) return false;
+    // a subSystem constraint excludes bookmarks attributed to a different source sub-system
+    if (subSystem !== undefined && bookmark.sourceSystem?.subSystem !== subSystem) return false;
+  }
+  return true;
+};
+
+/**
+ * Runs `fn` synchronously and reports the outcome as an {@link ObservableInput},
+ * so a mock method can `throw` for a "not found" case exactly like the async
+ * real client would reject.
+ *
+ * @template T - The value `fn` produces.
+ * @param fn - The synchronous operation to run.
+ * @returns An observable emitting `fn`'s result, or erroring with what it threw.
+ */
+const resultOf = <T>(fn: () => T): ObservableInput<T> => {
+  try {
+    return of(fn());
+  } catch (error) {
+    return throwError(() => error);
+  }
+};
+
+/**
+ * In-memory {@link IBookmarkClient} backed by a `Map` of seeded bookmarks and a
+ * `Set` of favorite ids.
+ *
+ * @remarks
+ * Used by {@link BookmarkMockConfigurator} to swap out the real API client
+ * while leaving `BookmarkProvider` and the `bookmark-flows/` epics running
+ * unmodified — every create, update, delete, and favorite call still goes
+ * through the real flow logic, only the underlying data source is in-memory.
+ */
+export class BookmarkMockClient implements IBookmarkClient {
+  #bookmarks = new Map<string, Bookmark>();
+  #favorites = new Set<string>();
+
+  /**
+   * Replaces the seeded bookmarks with the given collection, keyed by `id`.
+   *
+   * @param items - The bookmarks to seed. Replaces any previously seeded bookmarks.
+   */
+  public setBookmarks(items: Iterable<Bookmark>): void {
+    this.#bookmarks = new Map(Array.from(items, (item) => [item.id, item]));
+  }
+
+  /**
+   * Marks a seeded bookmark as a favorite, or clears it.
+   *
+   * @param bookmarkId - The id of the bookmark to update.
+   * @param isFavorite - `true` to favorite the bookmark, `false` to clear it.
+   */
+  public setFavorite(bookmarkId: string, isFavorite: boolean): void {
+    // track favorites as a set membership rather than a boolean field on the bookmark
+    if (isFavorite) {
+      this.#favorites.add(bookmarkId);
+    } else {
+      this.#favorites.delete(bookmarkId);
+    }
+  }
+
+  /**
+   * Looks up a seeded bookmark by id without going through the `ObservableInput` API.
+   *
+   * @param bookmarkId - The id of the bookmark to look up.
+   * @returns The seeded bookmark, or `undefined` when no bookmark was seeded for that id.
+   */
+  public getBookmark(bookmarkId: string): Bookmark | undefined {
+    return this.#bookmarks.get(bookmarkId);
+  }
+
+  /**
+   * Looks up a seeded bookmark by id, throwing when none was seeded.
+   *
+   * @param bookmarkId - The id of the bookmark to look up.
+   * @returns The seeded bookmark.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  #requireBookmark(bookmarkId: string): Bookmark {
+    const bookmark = this.#bookmarks.get(bookmarkId);
+    // fail loudly so a missing seed reads as a test setup bug, not a silent no-op
+    if (!bookmark) {
+      throw new Error(`BookmarkMockClient: no bookmark seeded for id '${bookmarkId}'`);
+    }
+    return bookmark;
+  }
+
+  /**
+   * Returns every seeded bookmark that matches `filter`, without its payload.
+   *
+   * @remarks
+   * The real client strips payloads from list results (see `BookmarkClient.getAllBookmarks`),
+   * so the mock does the same here even though the interface's declared return type is `Bookmark[]`.
+   *
+   * @param filter - Optional constraints to narrow the returned bookmarks.
+   * @returns The matching bookmarks, without their payloads.
+   */
+  public getAllBookmarks(filter?: BookmarksFilter): ObservableInput<Array<Bookmark>> {
+    return resultOf(
+      () =>
+        Array.from(this.#bookmarks.values())
+          // only bookmarks matching every constraint in `filter` are returned
+          .filter((bookmark) => matchesFilter(bookmark, filter))
+          // list results never include payloads, mirroring the real client
+          .map(stripPayload) as Array<Bookmark>,
+    );
+  }
+
+  /**
+   * Returns a seeded bookmark by id, without its payload.
+   *
+   * @param bookmarkId - The id of the bookmark to look up.
+   * @returns The bookmark without its payload.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  public getBookmarkById(bookmarkId: string): ObservableInput<BookmarkWithoutData> {
+    return resultOf(() => stripPayload(this.#requireBookmark(bookmarkId)));
+  }
+
+  /**
+   * Returns the payload data of a seeded bookmark.
+   *
+   * @template T - The shape of the bookmark's payload.
+   * @param bookmarkId - The id of the bookmark to look up.
+   * @returns The bookmark's payload.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  public getBookmarkData<T extends BookmarkData>(bookmarkId: string): ObservableInput<T> {
+    return resultOf(() => this.#requireBookmark(bookmarkId).payload as T);
+  }
+
+  /**
+   * Replaces the payload data of a seeded bookmark.
+   *
+   * @template T - The shape of the bookmark's payload.
+   * @param bookmarkId - The id of the bookmark to update.
+   * @param data - The new payload data.
+   * @returns The payload that was set.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  public setBookmarkData<T extends BookmarkData | null>(
+    bookmarkId: string,
+    data: T,
+  ): ObservableInput<T> {
+    return resultOf(() => {
+      const existing = this.#requireBookmark(bookmarkId);
+      this.#bookmarks.set(bookmarkId, { ...existing, payload: data ?? undefined });
+      return data;
+    });
+  }
+
+  /**
+   * Marks a seeded bookmark as a favorite.
+   *
+   * @param bookmarkId - The id of the bookmark to favorite.
+   * @returns `true` once the bookmark is marked as a favorite.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  public addBookmarkToFavorites(bookmarkId: string): ObservableInput<boolean> {
+    return resultOf(() => {
+      this.#requireBookmark(bookmarkId);
+      this.#favorites.add(bookmarkId);
+      return true;
+    });
+  }
+
+  /**
+   * Clears a seeded bookmark's favorite status.
+   *
+   * @param bookmarkId - The id of the bookmark to unfavorite.
+   * @returns `true` once the bookmark is no longer a favorite.
+   */
+  public removeBookmarkFromFavorites(bookmarkId: string): ObservableInput<boolean> {
+    return resultOf(() => {
+      this.#favorites.delete(bookmarkId);
+      return true;
+    });
+  }
+
+  /**
+   * Checks whether a seeded bookmark is currently a favorite.
+   *
+   * @param bookmarkId - The id of the bookmark to check.
+   * @returns `true` when the bookmark is a favorite.
+   */
+  public isBookmarkFavorite(bookmarkId: string): ObservableInput<boolean> {
+    return of(this.#favorites.has(bookmarkId));
+  }
+
+  /**
+   * Seeds a new bookmark from create input, generating its id and audit fields.
+   *
+   * @template T - The shape of the bookmark's payload.
+   * @param bookmark - The data to create the bookmark from.
+   * @returns The created bookmark.
+   */
+  public createBookmark<T extends BookmarkData>(
+    bookmark: BookmarkNew<T>,
+  ): ObservableInput<Bookmark<T>> {
+    return resultOf(() => {
+      // `contextId` is a plain id on the client input, but a `{ id }` object on the bookmark itself
+      const { contextId, ...rest } = bookmark;
+      // merge the create input with generated audit fields and a normalized context
+      const created: Bookmark<T> = {
+        ...rest,
+        id: generateGUID(),
+        created: new Date(),
+        createdBy: mockUser,
+        ...(contextId ? { context: { id: contextId } } : {}),
+      };
+      this.#bookmarks.set(created.id, created);
+      return created;
+    });
+  }
+
+  /**
+   * Applies updates to a seeded bookmark, stamping new audit fields.
+   *
+   * @template T - The shape of the bookmark's payload.
+   * @param bookmarkId - The id of the bookmark to update.
+   * @param updates - The fields to update.
+   * @returns The updated bookmark.
+   * @throws {Error} When no bookmark was seeded for `bookmarkId`.
+   */
+  public updateBookmark<T extends BookmarkData>(
+    bookmarkId: string,
+    updates: BookmarkUpdate<T>,
+  ): ObservableInput<Bookmark<T>> {
+    return resultOf(() => {
+      const existing = this.#requireBookmark(bookmarkId);
+      // merge the updates onto the existing bookmark, then stamp new audit fields
+      const updated: Bookmark<T> = {
+        ...existing,
+        ...updates,
+        // `payload: null` clears data on a BookmarkUpdate, so normalize it to `undefined` like setBookmarkData does
+        payload: updates.payload === null ? undefined : (updates.payload ?? existing.payload),
+        updated: new Date(),
+        updatedBy: mockUser,
+      } as Bookmark<T>;
+      this.#bookmarks.set(bookmarkId, updated);
+      return updated;
+    });
+  }
+
+  /**
+   * Removes a seeded bookmark and clears its favorite status.
+   *
+   * @param bookmarkId - The id of the bookmark to delete.
+   * @returns `true` when a bookmark was seeded for `bookmarkId` and was removed.
+   */
+  public deleteBookmark(bookmarkId: string): ObservableInput<boolean> {
+    return resultOf(() => {
+      const existed = this.#bookmarks.delete(bookmarkId);
+      this.#favorites.delete(bookmarkId);
+      return existed;
+    });
+  }
+}

package/src/mock/BookmarkMockConfigurator.ts

@@ -0,0 +1,159 @@
+import { of } from 'rxjs';
+
+import type { ConfigBuilderCallbackArgs } from '@equinor/fusion-framework-module';
+
+import { BookmarkModuleConfigurator } from '../BookmarkModuleConfigurator';
+import type { IBookmarkProvider } from '../BookmarkProvider.interface';
+import type { Bookmark, BookmarkModuleConfig } from '../types';
+
+import { BookmarkMockClient } from './BookmarkMockClient';
+
+/**
+ * Fallback application resolver used when the mock is configured standalone,
+ * without a real `app` module registered.
+ */
+const mockApplicationResolver: BookmarkModuleConfig['resolve']['application'] = async () => ({
+  appKey: 'mock-app',
+});
+
+/**
+ * Fallback context resolver used when the mock is configured standalone,
+ * without a real `context` module registered.
+ */
+const mockContextResolver: BookmarkModuleConfig['resolve']['context'] = async () => undefined;
+
+/**
+ * The real bookmark configurator, backed by an in-memory {@link BookmarkMockClient}.
+ *
+ * @remarks
+ * Extends {@link BookmarkModuleConfigurator} directly, so the whole builder API
+ * (source system, filters, resolvers, `setParent`) stays available. Only a
+ * default client is added — through the same
+ * {@link BookmarkModuleConfigurator.setClient | setClient} seam a caller would
+ * use to plug in their own client — so an explicit `setClient()` call still
+ * replaces it outright, exactly as it would on the real configurator.
+ *
+ * Seeded bookmarks and favorites flow through the real `BookmarkProvider` and
+ * `bookmark-flows/` epics unmodified: create, update, delete, and favorite
+ * calls all reach {@link BookmarkMockClient}, not a stand-in.
+ *
+ * @example Seed bookmarks and a current bookmark
+ * ```typescript
+ * enableBookmarkMock(configurator, (builder) => {
+ *   builder.setBookmarks([myBookmark]);
+ *   builder.setCurrentBookmark(myBookmark.id);
+ *   builder.setFavorite(myBookmark.id, true);
+ * });
+ * ```
+ *
+ * @example Take full control of the client
+ * ```typescript
+ * enableBookmarkMock(configurator, (builder) => {
+ *   builder.setClient(myOwnBookmarkClient);
+ * });
+ * ```
+ */
+export class BookmarkMockConfigurator extends BookmarkModuleConfigurator {
+  #client = new BookmarkMockClient();
+  #currentId?: string;
+
+  /**
+   * Seeds the bookmarks the mock client resolves through `getAllBookmarks`,
+   * `getBookmarkById`, and `getBookmarkData`.
+   *
+   * @param items - The bookmarks to seed. Replaces any previously seeded bookmarks.
+   * @returns `this`, for chaining.
+   */
+  public setBookmarks(items: Iterable<Bookmark>): this {
+    this.#client.setBookmarks(items);
+    return this;
+  }
+
+  /**
+   * Declares which seeded bookmark `IBookmarkProvider.currentBookmark` reports
+   * as active once the module initializes.
+   *
+   * @remarks
+   * `BookmarkProvider` only reads its initial current bookmark from a parent
+   * provider (see {@link BookmarkModuleConfigurator.setParent}), so this
+   * registers a synthetic parent exposing the seeded bookmark — the same seam
+   * a real nested-portal provider would use, just standing in for one.
+   *
+   * @param bookmarkId - The id of a bookmark previously passed to {@link setBookmarks},
+   *   or `undefined` to leave the current bookmark unset.
+   * @returns `this`, for chaining.
+   */
+  public setCurrentBookmark(bookmarkId: string | undefined): this {
+    this.#currentId = bookmarkId;
+    return this;
+  }
+
+  /**
+   * Marks a seeded bookmark as a favorite, or clears it, reflected through
+   * `IBookmarkClient.isBookmarkFavorite`.
+   *
+   * @param bookmarkId - The id of the bookmark to update.
+   * @param isFavorite - `true` to favorite the bookmark, `false` to clear it. Defaults to `true`.
+   * @returns `this`, for chaining.
+   */
+  public setFavorite(bookmarkId: string, isFavorite = true): this {
+    this.#client.setFavorite(bookmarkId, isFavorite);
+    return this;
+  }
+
+  /**
+   * Installs the mock client and a synthetic current-bookmark parent before
+   * building the configuration, unless the caller already declared their own.
+   *
+   * @remarks
+   * Also falls back to trivial application/context resolvers when neither an
+   * `app` nor a `context` module is registered alongside this mock — both are
+   * required by {@link BookmarkModuleConfig}'s schema, but a standalone test
+   * has no reason to pull in either module just to satisfy it. Registering a
+   * real `app`/`context` module still wins, exactly as it does on the real
+   * configurator.
+   *
+   * @param init - The config builder callback arguments.
+   * @param initial - An optional initial config to merge into the returned config.
+   * @returns The observable configuration, produced by the real configurator.
+   */
+  protected override _createConfig(
+    init: ConfigBuilderCallbackArgs,
+    initial?: Partial<BookmarkModuleConfig>,
+  ) {
+    // only stand in a mock client when the caller hasn't set their own
+    if (!this._has('client')) {
+      this.setClient(this.#client);
+    }
+
+    // only stand in a synthetic parent when a current bookmark was seeded and
+    // the caller hasn't declared their own parent provider
+    if (this.#currentId && !this._has('parent')) {
+      const current = this.#client.getBookmark(this.#currentId) ?? null;
+      const parent: Pick<IBookmarkProvider, 'currentBookmark' | 'currentBookmark$'> = {
+        currentBookmark: current,
+        currentBookmark$: of(current),
+      };
+      this.setParent(parent as IBookmarkProvider);
+    }
+
+    // no app module means the real default resolver would resolve to `undefined`, which fails
+    // the required `resolve.application` schema field — but `initial.resolve.application` may
+    // already carry a resolver inherited from a parent config, which must not be overwritten
+    if (
+      !this._has('resolve.application') &&
+      !initial?.resolve?.application &&
+      !init.hasModule('app')
+    ) {
+      this.setApplicationResolver(async () => mockApplicationResolver);
+    }
+
+    // no context module means the real default resolver would resolve to `undefined`, which
+    // fails the required `resolve.context` schema field — same inherited-config caveat as above
+    if (!this._has('resolve.context') && !initial?.resolve?.context && !init.hasModule('context')) {
+      this.setContextResolver(async () => mockContextResolver);
+    }
+
+    return super._createConfig(init, initial);
+  }
+}

package/src/mock/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Mock bookmark module for tests: real provider, real configurator, in-memory client.
+ *
+ * @remarks
+ * Substituting `IBookmarkClient` is the smallest change that removes the
+ * Fusion Core Services backend from a test. Everything above it — the
+ * `BookmarkProvider` store, `bookmark-flows/` epics, payload generators, and
+ * events — is the production code path.
+ *
+ * @example
+ * ```typescript
+ * import { enableBookmarkMock } from '@equinor/fusion-framework-module-bookmark/mock';
+ *
+ * enableBookmarkMock(configurator, (builder) => {
+ *   builder.setBookmarks([myBookmark]);
+ *   builder.setCurrentBookmark(myBookmark.id);
+ *   builder.setFavorite(myBookmark.id, true);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { BookmarkMockClient } from './BookmarkMockClient';
+export { BookmarkMockConfigurator } from './BookmarkMockConfigurator';
+export { enableBookmarkMock, bookmarkMockModule, type BookmarkMockConfigFn } from './module';

package/src/mock/module.ts

@@ -0,0 +1,64 @@
+import type { AnyModule, IModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import { module, type BookmarkModule } from '../bookmark-module';
+
+import { BookmarkMockConfigurator } from './BookmarkMockConfigurator';
+
+/**
+ * The bookmark module with a mock, in-memory client instead of a live
+ * `@equinor/fusion-framework-module-services` connection.
+ *
+ * @remarks
+ * Only `configure` differs from the real module. `initialize` is the
+ * production one, untouched, so the real `BookmarkProvider` and
+ * `bookmark-flows/` epics run exactly as they do in production — a test
+ * observes the real create/update/delete/favorite flow, not a rehearsal of it.
+ */
+export const bookmarkMockModule: BookmarkModule = {
+  ...module,
+  configure: () => new BookmarkMockConfigurator(),
+};
+
+/**
+ * Configuration callback for {@link enableBookmarkMock}.
+ *
+ * @template TRef - Reference type forwarded to the callback, inferred from the configurator.
+ */
+export type BookmarkMockConfigFn<TRef = unknown> = (
+  configurator: BookmarkMockConfigurator,
+  ref?: TRef,
+) => void | Promise<void>;
+
+/**
+ * Enables the bookmark module against an in-memory mock client, so a test
+ * needs no network and no real Fusion Core Services backend.
+ *
+ * @remarks
+ * Registered last, this replaces whichever bookmark module the configurator
+ * already carries, so it works on a `FrameworkConfigurator` that pre-registers
+ * the real one.
+ *
+ * @param configurator - The modules configurator to register on.
+ * @param configure - Optional callback to seed bookmarks, the current bookmark, or favorites.
+ * @template TModules - The array of module descriptors managed by `configurator`.
+ * @template TRef - Reference type forwarded to `configure`, inferred from `configurator`.
+ *
+ * @example
+ * ```typescript
+ * enableBookmarkMock(configurator, (builder) => {
+ *   builder.setBookmarks([myBookmark]);
+ *   builder.setCurrentBookmark(myBookmark.id);
+ * });
+ * ```
+ */
+export const enableBookmarkMock = <
+  TModules extends Array<AnyModule> = Array<AnyModule>,
+  TRef = unknown,
+>(
+  configurator: IModulesConfigurator<TModules, TRef>,
+  configure?: BookmarkMockConfigFn<TRef>,
+): void => {
+  configurator.addConfig({ module: bookmarkMockModule, configure } as {
+    module: BookmarkModule;
+  });
+};

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '4.0.3';
+export const version = '4.1.0-next.0';

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineProject } from 'vitest/config';
+
+import { name, version } from './package.json' with { type: 'json' };
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['src/__tests__/**/*.test.ts'],
+    name: `${name}@${version}`,
+  },
+});