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

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

@@ -1,8 +1,9 @@
-import type { AnyModule, IModulesConfigurator, ModuleInitializerArgs } from '@equinor/fusion-framework-module';
-import { BookmarkConfigBuilder } from './bookmark-config-builder';
-import { IBookmarkModuleConfigurator } from './configurator';
+import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
+import { BookmarkModuleConfigurator } from './BookmarkConfigurator';
 /**
- * Method for enabling Bookmark module
- * @param configurator - configuration object
+ * Enables the Bookmark module
+ *
+ * @param configurator - The configuration object for the modules.
+ * @param callback - An optional callback function that receives the `BookmarkModuleConfigurator` instance, allowing for further configuration.
  */
-export declare const enableBookmark: (configurator: IModulesConfigurator<any, any>, builder?: <TDeps extends Array<AnyModule> = []>(builder: BookmarkConfigBuilder<TDeps, ModuleInitializerArgs<IBookmarkModuleConfigurator, TDeps>>) => void | Promise<void>) => void;
+export declare const enableBookmark: (configurator: IModulesConfigurator<any>, callback?: (builder: BookmarkModuleConfigurator) => void | Promise<void>) => void;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
-export { BookmarkModuleConfigurator, IBookmarkModuleConfigurator, BookmarkModuleConfig, } from './configurator';
-export { default, BookmarkModule, module as bookmarkModule, moduleKey as bookmarkModuleKey, } from './module';
-export { IBookmarkModuleProvider, BookmarkModuleProvider } from './bookmark-provider';
+export { BookmarkModuleConfigurator } from './BookmarkConfigurator';
+export type { IBookmarkClient, BookmarkNew, BookmarkUpdate, BookmarksFilter, } from './BookmarkClient.interface';
+export { default, BookmarkModule, module as bookmarkModule, moduleKey as bookmarkModuleKey, } from './bookmark-module';
+export { BookmarkProvider, type BookmarkPayloadGenerator, type BookmarkCreateArgs, type BookmarkUpdateOptions, } from './BookmarkProvider';
 export { enableBookmark } from './enable-bookmark';
 export * from './types';

package/dist/types/types.d.ts

@@ -1,65 +1,29 @@
-import { QueryFn, QueryCtorOptions } from '@equinor/fusion-query';
-export interface PatchBookmark<TData = unknown> extends Partial<Bookmark<TData>> {
-    id: string;
-    appKey: string;
-}
-export interface Bookmark<TData = unknown> {
-    id: string;
-    name: string;
-    description: string;
-    isShared: boolean;
-    payload: TData;
-    appKey: string;
-    context?: Context;
-    createdBy: CreatedBy;
-    updatedBy: CreatedBy;
-    created: string;
-    updated: string;
-    sourceSystem?: SourceSystem;
-}
-export type CreateBookmark<TData = unknown> = {
-    /** Display name of the bookmark */
-    name: string;
-    description?: string;
-    /** Is the bookmark shared with others */
-    isShared: boolean;
-    /** Name of the app it belongs too, should correspond to a fusion appkey */
-    appKey: string;
-    contextId?: string;
-    /** Any JSON object to store as the bookmark payload */
-    payload: TData;
-    sourceSystem?: Partial<SourceSystem>;
-};
-export interface SourceSystem {
-    identifier: string;
-    name: string;
-    subSystem: string;
-}
-interface CreatedBy {
-    azureUniqueId: string;
-    mail: string;
-    name: string;
-    phoneNumber: string;
-    jobTitle: string;
-    accountType: number;
-    accountClassification: number;
-}
-interface Context {
-    id: string;
-    name: string;
-    type: string;
-}
-export type GetBookmarkParameters = {
-    id: string;
-};
-export type GetAllBookmarksParameters = {
-    isValid: boolean;
-};
-export interface BookmarkQueryClient {
-    getAllBookmarks: QueryFn<Array<Bookmark<unknown>>, GetAllBookmarksParameters> | QueryCtorOptions<Array<Bookmark<unknown>>, GetAllBookmarksParameters>;
-    getBookmarkById: QueryFn<Bookmark<unknown>, GetBookmarkParameters> | QueryCtorOptions<Bookmark<unknown>, GetBookmarkParameters>;
-}
-export type UpdateBookmarkOptions = {
-    updatePayload: boolean;
-};
-export {};
+import z from 'zod';
+import { bookmarkSchema, bookmarkSourceSystemSchema, bookmarksSchema, bookmarkWithDataSchema } from './bookmark.schemas';
+import { bookmarkConfigSchema } from './bookmark-config.schema';
+/**
+ * Represents the source system for a bookmark.
+ */
+export type SourceSystem = z.infer<typeof bookmarkSourceSystemSchema>;
+/**
+ * Represents the data associated with a bookmark.
+ * This is a generic type that can hold any arbitrary data as a key-value map.
+ */
+export type BookmarkData = Record<string, any> | string;
+/**
+ * Represents a collection of bookmarks.
+ */
+export type Bookmarks = z.infer<typeof bookmarksSchema>;
+/**
+ * Represents a bookmark without any associated data.
+ */
+export type BookmarkWithoutData = z.infer<typeof bookmarkSchema>;
+/**
+ * Represents a bookmark with associated data.
+ * @template T - The type of the bookmark data.
+ */
+export type Bookmark<T extends BookmarkData = any> = z.infer<ReturnType<typeof bookmarkWithDataSchema<T>>>;
+/**
+ * Represents the configuration options for a bookmark module.
+ */
+export type BookmarkModuleConfig = z.infer<typeof bookmarkConfigSchema>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.2.13";
+export declare const version = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-bookmark",
-  "version": "1.2.13",
+  "version": "2.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {
@@ -34,18 +34,24 @@
     "directory": "packages/modules/context"
   },
   "dependencies": {
+    "fast-deep-equal": "^3.1.3",
+    "immer": "^9.0.16",
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^4.3.5",
+    "uuid": "^9.0.1",
+    "@equinor/fusion-log": "^1.1.0",
     "@equinor/fusion-observable": "^8.4.2",
-    "@equinor/fusion-query": "^5.1.4"
+    "@equinor/fusion-query": "^5.1.4",
+    "@equinor/fusion-framework-module": "^4.3.5"
   },
   "devDependencies": {
+    "@types/uuid": "^9.0.8",
     "typescript": "^5.5.4",
-    "@equinor/fusion-framework-module-app": "^6.0.2",
+    "zod": "^3.23.8",
     "@equinor/fusion-framework-module-context": "^5.0.13",
+    "@equinor/fusion-framework-module-app": "^6.0.2",
     "@equinor/fusion-framework-module-event": "^4.2.4",
     "@equinor/fusion-framework-module-http": "^6.2.0",
-    "@equinor/fusion-framework-module-services": "^4.1.5"
+    "@equinor/fusion-framework-module-services": "^5.0.0"
   },
   "scripts": {
     "build": "tsc -b"

package/src/BookmarkClient.interface.ts

@@ -0,0 +1,157 @@
+import { type ObservableInput } from 'rxjs';
+import type { Bookmark, BookmarkData, BookmarkWithoutData } from './types';
+
+/**
+ * Defines the shape of a filter for querying bookmarks.
+ * @property {string} [appKey] - The app key to filter bookmarks by.
+ * @property {string} [contextId] - The context ID to filter bookmarks by.
+ * @property {object} [sourceSystem] - The source system to filter bookmarks by.
+ * @property {string} [sourceSystem.identifier] - The identifier of the source system.
+ * @property {string} [sourceSystem.name] - The name of the source system.
+ * @property {string} [sourceSystem.subSystem] - The sub-system of the source system.
+ */
+export type BookmarksFilter = {
+    appKey?: string;
+    contextId?: string;
+    sourceSystem?: {
+        identifier?: string;
+        name?: string;
+        subSystem?: string;
+    };
+};
+
+/**
+ * Defines the shape of an update to an existing bookmark.
+ * @template T - The type of the payload data for the bookmark.
+ * @property {string} [name] - The updated name of the bookmark.
+ * @property {string} [description] - The updated description of the bookmark.
+ * @property {boolean} [isShared] - Whether the bookmark is shared or not.
+ * @property {T} [payload] - The updated payload data for the bookmark.
+ */
+export type BookmarkUpdate<T extends BookmarkData = BookmarkData> = {
+    name?: string;
+    description?: string;
+    isShared?: boolean;
+    payload?: T | null;
+    sourceSystem?: {
+        identifier: string;
+        name?: string | null;
+        subSystem?: string | null;
+    } | null;
+};
+
+/**
+ * Defines the shape of a new bookmark to be created.
+ * @template T - The type of the payload data for the bookmark.
+ * @property {string} name - The name of the bookmark.
+ * @property {string} appKey - The app key associated with the bookmark.
+ * @property {string} [description] - The description of the bookmark.
+ * @property {boolean} [isShared] - Whether the bookmark is shared or not.
+ * @property {string} [contextId] - The context ID associated with the bookmark.
+ * @property {object} [sourceSystem] - Information about the source system of the bookmark.
+ * @property {string} [sourceSystem.identifier] - The identifier of the source system.
+ * @property {string} [sourceSystem.name] - The name of the source system.
+ * @property {string} [sourceSystem.subSystem] - The sub-system of the source system.
+ * @property {T} [payload] - The payload data for the bookmark.
+ */
+export type BookmarkNew<T extends BookmarkData = BookmarkData> = {
+    name: string;
+    appKey: string;
+    description?: string;
+    isShared?: boolean;
+    contextId?: string;
+    sourceSystem?: {
+        identifier: string;
+        name?: string;
+        subSystem?: string;
+    };
+    payload?: T;
+};
+
+/**
+ * Defines the interface for a Bookmarks client, which provides methods for managing bookmarks.
+ */
+export interface IBookmarkClient {
+    /**
+     * Retrieves all bookmarks for the current user.
+     * @template TPayload - The type of the payload data for the bookmarks.
+     * @param args - Optional arguments to filter or customize the bookmark retrieval.
+     * @returns An observable input containing an array of bookmarks.
+     */
+    getAllBookmarks: (filter?: BookmarksFilter) => ObservableInput<Array<Bookmark>>;
+
+    /**
+     * Retrieves a single bookmark by id.
+     * @template TPayload - The type of the payload data for the bookmark.
+     * @param bookmarkId - The id of the bookmark to retrieve.
+     * @returns An observable input containing the requested bookmark.
+     */
+    getBookmarkById: (bookmarkId: string) => ObservableInput<BookmarkWithoutData>;
+
+    /**
+     * Retrieves the bookmark data for the specified bookmark ID.
+     *
+     * @param bookmarkId - The ID of the bookmark to retrieve data for.
+     * @returns An observable that emits the bookmark data.
+     */
+    getBookmarkData: <T extends BookmarkData>(bookmarkId: string) => ObservableInput<T>;
+
+    /**
+     * Updates the data associated with a bookmark.
+     *
+     * @template T - The type of the data to be associated with the bookmark. Can be a record or null.
+     * @param bookmarkId - The ID of the bookmark to update.
+     * @param data - The new data to be associated with the bookmark.
+     * @returns An observable that emits the updated data.
+     */
+    setBookmarkData<T extends BookmarkData | null>(bookmarkId: string, data: T): ObservableInput<T>;
+
+    /**
+     * Adds a bookmark to the current user's favorites.
+     * @param bookmarkId - The id of the bookmark to add to favorites.
+     * @returns An observable input containing a boolean indicating whether the operation was successful.
+     */
+    addBookmarkToFavorites: (bookmarkId: string) => ObservableInput<boolean>;
+
+    /**
+     * Removes a bookmark from the current user's favorites.
+     * @param bookmarkId - The id of the bookmark to remove from favorites.
+     * @returns An observable input containing a boolean indicating whether the operation was successful.
+     */
+    removeBookmarkFromFavorites: (bookmarkId: string) => ObservableInput<boolean>;
+
+    /**
+     * Verifies whether a bookmark is a favorite of the current user.
+     * @param bookmarkId - The id of the bookmark to verify.
+     * @returns An observable input containing a boolean indicating whether the bookmark is a favorite.
+     */
+    isBookmarkFavorite: (bookmarkId: string) => ObservableInput<boolean>;
+
+    /**
+     * Creates a new bookmark.
+     * @template TPayload - The type of the payload data for the bookmark.
+     * @param bookmark - The bookmark data to create.
+     * @returns An observable input containing the created bookmark.
+     */
+    createBookmark: <T extends BookmarkData>(
+        bookmark: BookmarkNew<T>,
+    ) => ObservableInput<Bookmark<T>>;
+
+    /**
+     * Updates an existing bookmark.
+     * @template TPayload - The type of the payload data for the bookmark.
+     * @param bookmark - The bookmark data to update.
+     * @returns An observable input containing the updated bookmark.
+     */
+    updateBookmark: <T extends BookmarkData>(
+        bookmarkId: string,
+        updates: BookmarkUpdate<T>,
+    ) => ObservableInput<Bookmark<T>>;
+
+    /**
+     * Deletes a bookmark by id.
+     * @param bookmarkId - The id of the bookmark to delete.
+     * @returns An observable input containing a boolean indicating whether the operation was successful.
+     */
+    deleteBookmark: (bookmarkId: string) => ObservableInput<boolean>;
+}

package/src/BookmarkClient.ts

@@ -0,0 +1,226 @@
+import { Observable, type ObservableInput } from 'rxjs';
+import { map, shareReplay, tap } from 'rxjs/operators';
+
+/**
+ * Imports the `Query` type from the `@equinor/fusion-query` package.
+ * This type is used to cache the results of API requests.
+ */
+import { Query } from '@equinor/fusion-query';
+
+/**
+ * Imports the `BookmarksApiClient` and `ApiBookmarkEntityV1` types from the `@equinor/fusion-framework-module-services/bookmarks` package.
+ * These types are used to interact with the Fusion Bookmarks API and represent the API response entities.
+ */
+import type { BookmarksApiClient } from '@equinor/fusion-framework-module-services/bookmarks';
+
+import type {
+    IBookmarkClient,
+    BookmarksFilter,
+    BookmarkNew,
+    BookmarkUpdate,
+} from './BookmarkClient.interface';
+
+import type { Bookmark, BookmarkData, BookmarkWithoutData, Bookmarks } from './types';
+import { bookmarkSchema, bookmarkWithDataSchema, bookmarksSchema } from './bookmark.schemas';
+
+/**
+ * Represents a client for interacting with the Fusion Bookmarks API.
+ * This class provides methods for retrieving, creating, updating, and deleting bookmarks, as well as managing favorites.
+ *
+ * This implementation consumes the `@equinor/fusion-framework-module-services/bookmarks` package.
+ * This is the default implementation of the bookmarks API client.
+ *
+ * This class is intended to be used by the Fusion framework with the Fusion Core Services (Backend)
+ *
+ * Fetching single and all bookmarks will use Query from '@equinor/fusion-query' to cache the results.
+ *
+ * @note if you wish to implement your own bookmarks API client, you can do so by implementing the {@link IBookmarkClient} interface.
+ */
+export class BookmarkClient implements IBookmarkClient {
+    #api: BookmarksApiClient<'json$'>;
+
+    #queryBookmark: Query<BookmarkWithoutData, { bookmarkId: string }>;
+    #queryBookmarks: Query<Bookmarks, BookmarksFilter | undefined>;
+    #queryBookmarkData: Query<BookmarkData | undefined, { bookmarkId: string }>;
+
+    /**
+     * Constructs a new `BookmarkClient` instance with the provided `BookmarksApiClient`.
+     *
+     * @param api - The `BookmarksApiClient` instance to use for making API requests.
+     */
+    constructor(api: BookmarksApiClient<'json$'>, options?: { expire?: number }) {
+        this.#api = api;
+
+        const { expire = 5 * 60 * 1000 } = options ?? {};
+
+        // set up the query for fetching a single bookmark
+        this.#queryBookmark = new Query({
+            client: {
+                fn: (args: { bookmarkId: string }) => {
+                    return this.#api.get('v2', args).pipe(map((res) => bookmarkSchema.parse(res)));
+                },
+            },
+            key: (args) => args.bookmarkId,
+            expire,
+        });
+
+        // set up the query for fetching all bookmarks
+        this.#queryBookmarks = new Query({
+            client: {
+                fn: (filter?: BookmarksFilter) => {
+                    return this.#api
+                        .query('v1', { filter })
+                        .pipe(map((res) => bookmarksSchema.parse(res)));
+                },
+            },
+            key: (args) => JSON.stringify(args ?? ''),
+            expire,
+        });
+
+        this.#queryBookmarkData = new Query({
+            client: {
+                fn: (args: { bookmarkId: string }) => {
+                    return this.#api.getPayload('v1', args).pipe(map((res) => res.payload));
+                },
+            },
+            key: (args) => args.bookmarkId,
+            expire,
+            cache: {
+                trimming: {
+                    size: 3,
+                },
+            },
+        });
+    }
+
+    public getAllBookmarks(filter?: BookmarksFilter): ObservableInput<Bookmark[]> {
+        return this.#queryBookmarks.query(filter).pipe(map((res) => res.value as Bookmark[]));
+    }
+
+    public getBookmarkById(bookmarkId: string): ObservableInput<BookmarkWithoutData> {
+        return this.#queryBookmark.query({ bookmarkId }).pipe(map((res) => res.value));
+    }
+
+    public getBookmarkData<T extends BookmarkData>(bookmarkId: string): ObservableInput<T> {
+        return this.#queryBookmarkData.query({ bookmarkId }).pipe(map((res): T => res.value as T));
+    }
+
+    public setBookmarkData<T extends BookmarkData | null>(
+        bookmarkId: string,
+        data: T,
+    ): ObservableInput<T> {
+        return this.#api.patch('v1', { bookmarkId, updates: { payload: data } }).pipe(
+            map((res) => res.payload as T),
+            tap((updatedData) => {
+                if (updatedData) {
+                    this.#queryBookmarkData.mutate(
+                        { bookmarkId },
+                        { value: updatedData, updated: Date.now() },
+                        { allowCreation: true },
+                    );
+                }
+            }),
+        );
+    }
+
+    public createBookmark<T extends BookmarkData>(
+        newBookmark: BookmarkNew<T>,
+    ): ObservableInput<Bookmark<T>> {
+        return this.#api.create('v1', newBookmark).pipe(
+            map((response) => bookmarkWithDataSchema<T>().parse(response) as Bookmark<T>),
+            /** update the bookmark cache */
+            tap((createdBookmark) => {
+                const { payload, ...bookmark } = createdBookmark;
+                this.#queryBookmark.mutate(
+                    { bookmarkId: bookmark.id },
+                    { value: bookmark, updated: Date.now() },
+                    { allowCreation: true },
+                );
+                if (payload) {
+                    this.#queryBookmarkData.mutate(
+                        { bookmarkId: bookmark.id },
+                        { value: payload, updated: Date.now() },
+                        { allowCreation: true },
+                    );
+                }
+                this.#queryBookmarks.invalidate();
+            }),
+        );
+    }
+
+    public updateBookmark<T extends BookmarkData>(
+        bookmarkId: string,
+        updates: BookmarkUpdate<T>,
+    ): ObservableInput<Bookmark<T>> {
+        const update$ = this.#api.patch('v1', { bookmarkId, updates: updates }).pipe(
+            map((response) => bookmarkWithDataSchema().parse(response) as Bookmark<T>),
+            shareReplay(),
+        );
+        return new Observable((subscriber) => {
+            // update the query cache for the specific bookmark
+            subscriber.add(
+                update$.subscribe((updatedBookmark) => {
+                    const { payload, ...bookmark } = updatedBookmark;
+                    // payload should not be included in the bookmark object
+                    payload;
+                    this.#queryBookmark.mutate(
+                        { bookmarkId },
+                        { value: bookmark, updated: Date.now() },
+                        { allowCreation: false },
+                    );
+                }),
+            );
+
+            // update the cache for bookmark data
+            subscriber.add(
+                update$.subscribe((updatedBookmark) => {
+                    const { payload } = updatedBookmark;
+                    if (payload) {
+                        this.#queryBookmarkData.mutate(
+                            {
+                                bookmarkId: updatedBookmark.id,
+                            },
+                            { value: payload, updated: Date.now() },
+                            { allowCreation: true },
+                        );
+                    } else {
+                        const cacheKey = this.#queryBookmarkData.generateCacheKey({
+                            bookmarkId: updatedBookmark.id,
+                        });
+                        this.#queryBookmarkData.cache.removeItem(cacheKey);
+                    }
+                }),
+            );
+
+            // invalidate the bookmarks query cache
+            subscriber.add(
+                update$.subscribe(() => {
+                    this.#queryBookmarks.invalidate();
+                }),
+            );
+
+            // emit the update to the subscriber
+            update$.subscribe(subscriber);
+        });
+    }
+
+    public deleteBookmark(bookmarkId: string): ObservableInput<boolean> {
+        return this.#api.delete('v1', { bookmarkId });
+    }
+
+    public addBookmarkToFavorites(bookmarkId: string): ObservableInput<boolean> {
+        return this.#api
+            .addFavourite('v1', { bookmarkId })
+            .pipe(tap(() => this.#queryBookmarks.invalidate()));
+    }
+
+    public removeBookmarkFromFavorites(bookmarkId: string): ObservableInput<boolean> {
+        return this.#api
+            .removeFavourite('v1', { bookmarkId })
+            .pipe(tap(() => this.#queryBookmarks.invalidate()));
+    }
+
+    public isBookmarkFavorite(bookmarkId: string): ObservableInput<boolean> {
+        return this.#api.isFavorite('v1', { bookmarkId });
+    }
+}