@equinor/fusion-framework-module-event - npm Package Compare versions

Comparing version 4.1.2 to 4.2.0

CHANGELOG.md

 # Change Log
 
+## 4.2.0
+
+### Minor Changes
+
+-   [#2326](https://github.com/equinor/fusion-framework/pull/2326) [`b628e90`](https://github.com/equinor/fusion-framework/commit/b628e90500b62e0185c09eb665ce31025bc9b541) Thanks [@odinr](https://github.com/odinr)! - Added feature for allowing the event listener to mutate the event details.
+
+    **NOTE:** to not break the current behavior, the event creator needs to set the `allowMutate` flag to `true` in the event details.
+
+    ```ts
+    /** example of event listener */
+    eventModule.on('foo', (event) => {
+        event.updateDetails((details) => {
+            details.foo = 'bar';
+        });
+    });
+
+    /** example of event creation */
+    const event = new CustomEvent({ foo: 'foo' }, { allowMutate: true });
+    await eventModule.emit(event);
+
+    console.log(event.details.foo); // bar
+    console.log(event.originalDetails.foo); // foo
+    ```
+
+    The package now uses `immer` to allow for immutability of the event details. This means that the event details can be mutated in the event listener without affecting the original event details.
+
+### Patch Changes
+
+-   [#2333](https://github.com/equinor/fusion-framework/pull/2333) [`86d55b8`](https://github.com/equinor/fusion-framework/commit/86d55b8d27a572f3f62170b1e72aceda54f955e1) Thanks [@odinr](https://github.com/odinr)! - Updated `TypeScript` to 5.5.3
+
+-   [#2320](https://github.com/equinor/fusion-framework/pull/2320) [`1dd85f3`](https://github.com/equinor/fusion-framework/commit/1dd85f3a408a73df556d1812a5f280945cc100ee) Thanks [@odinr](https://github.com/odinr)! - Removed the `removeComments` option from the `tsconfig.base.json` file.
+
+    Removing the `removeComments` option allows TypeScript to preserve comments in the compiled JavaScript output. This can be beneficial for several reasons:
+
+    1. Improved debugging: Preserved comments can help developers understand the code better during debugging sessions.
+    2. Documentation: JSDoc comments and other important code documentation will be retained in the compiled output.
+    3. Source map accuracy: Keeping comments can lead to more accurate source maps, which is crucial for debugging and error tracking.
+
+    No action is required from consumers of the library. This change affects the build process and doesn't introduce any breaking changes or new features.
+
+    Before:
+
+    ```json
+    {
+        "compilerOptions": {
+            "module": "ES2022",
+            "target": "ES6",
+            "incremental": true,
+            "removeComments": true,
+            "preserveConstEnums": true,
+            "sourceMap": true,
+            "moduleResolution": "node"
+        }
+    }
+    ```
+
+    After:
+
+    ```json
+    {
+        "compilerOptions": {
+            "module": "ES2022",
+            "target": "ES6",
+            "incremental": true,
+            "preserveConstEnums": true,
+            "sourceMap": true,
+            "moduleResolution": "node"
+        }
+    }
+    ```
+
+    This change ensures that comments are preserved in the compiled output, potentially improving the development and debugging experience for users of the Fusion Framework.
+
+-   Updated dependencies [[`2f74edc`](https://github.com/equinor/fusion-framework/commit/2f74edcd4a3ea2b87d69f0fd63492145c3c01663), [`86d55b8`](https://github.com/equinor/fusion-framework/commit/86d55b8d27a572f3f62170b1e72aceda54f955e1), [`1dd85f3`](https://github.com/equinor/fusion-framework/commit/1dd85f3a408a73df556d1812a5f280945cc100ee)]:
+    -   @equinor/fusion-framework-module@4.3.2
+
 ## 4.1.2
@@ -4,0 +80,0 @@

dist/esm/event.js

@@ -12,3 +12,23 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
 };
-var _FrameworkEvent_detail, _FrameworkEvent_source, _FrameworkEvent_canceled, _FrameworkEvent_cancelable, _FrameworkEvent_canBubble, _FrameworkEvent_created;
+var _FrameworkEvent_detail, _FrameworkEvent_originalDetail, _FrameworkEvent_source, _FrameworkEvent_canceled, _FrameworkEvent_cancelable, _FrameworkEvent_mutableDetails, _FrameworkEvent_canBubble, _FrameworkEvent_created;
+import { produce } from 'immer';
+/**
+ * Represents a framework event with customizable details and behavior.
+ *
+ * The `FrameworkEvent` class implements the `IFrameworkEvent` interface and provides a way to create and manage events
+ * with custom details and behavior. It allows you to:
+ *
+ * - Specify the event type and initial event details
+ * - Access the event details, including the original details and any updates
+ * - Check if the event is cancelable and whether it has been canceled
+ * - Control whether the event can bubble up the event hierarchy
+ * - Update the event details during the event lifecycle
+ *
+ * The `FrameworkEvent` class is designed to be used as a base class for creating custom event types that fit the needs
+ * of your application or framework.
+ *
+ * @template TInit The type of the event details.
+ * @template TType The type of the event type.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class FrameworkEvent {
@@ -18,33 +38,88 @@ constructor(__type, args) {
         _FrameworkEvent_detail.set(this, void 0);
+        _FrameworkEvent_originalDetail.set(this, void 0);
         _FrameworkEvent_source.set(this, void 0);
         _FrameworkEvent_canceled.set(this, false);
         _FrameworkEvent_cancelable.set(this, void 0);
+        _FrameworkEvent_mutableDetails.set(this, void 0);
         _FrameworkEvent_canBubble.set(this, void 0);
         _FrameworkEvent_created.set(this, Date.now());
-        __classPrivateFieldSet(this, _FrameworkEvent_detail, args.detail, "f");
-        __classPrivateFieldSet(this, _FrameworkEvent_source, args.source, "f");
+        __classPrivateFieldSet(this, _FrameworkEvent_detail, produce(args.detail, () => { }), "f");
+        __classPrivateFieldSet(this, _FrameworkEvent_mutableDetails, !!args.mutableDetails, "f");
+        __classPrivateFieldSet(this, _FrameworkEvent_originalDetail, produce(args.detail, () => { }), "f");
+        __classPrivateFieldSet(this, _FrameworkEvent_source, produce(args.source, () => { }), "f");
         __classPrivateFieldSet(this, _FrameworkEvent_cancelable, !!args.cancelable, "f");
         __classPrivateFieldSet(this, _FrameworkEvent_canBubble, args.canBubble === undefined ? true : args.canBubble, "f");
     }
+    /**
+     * Indicates whether the event can bubble up the event hierarchy.
+     * The event will only bubble if this property is `true` and the event has not been canceled.
+     * @returns {boolean} `true` if the event can bubble, `false` otherwise.
+     */
     get bubbles() {
         return __classPrivateFieldGet(this, _FrameworkEvent_canBubble, "f") && !__classPrivateFieldGet(this, _FrameworkEvent_canceled, "f");
     }
+    /**
+     * Gets the timestamp when the `FrameworkEvent` was created.
+     * @returns {number} The timestamp of when the `FrameworkEvent` was created.
+     */
     get created() {
         return __classPrivateFieldGet(this, _FrameworkEvent_created, "f");
     }
+    /**
+     * Indicates whether the event is cancelable.
+     * If the event is cancelable, it can be prevented from occurring by calling the `preventDefault()` method.
+     * @returns {boolean} `true` if the event is cancelable, `false` otherwise.
+     */
     get cancelable() {
         return __classPrivateFieldGet(this, _FrameworkEvent_cancelable, "f");
     }
+    /**
+     * Indicates whether the event has been canceled.
+     * If the event is cancelable and `preventDefault()` has been called, this property will be `true`.
+     * @returns {boolean} `true` if the event has been canceled, `false` otherwise.
+     */
     get canceled() {
         return __classPrivateFieldGet(this, _FrameworkEvent_canceled, "f");
     }
+    /**
+     * Gets the current event details.
+     * @returns {FrameworkEventInitDetail<TInit>} The current event details.
+     */
     get detail() {
         return __classPrivateFieldGet(this, _FrameworkEvent_detail, "f");
     }
+    /**
+     * Gets the original event details that were passed to the `FrameworkEvent` constructor.
+     * This property provides access to the original event details, which may have been modified by the `updateDetails` method.
+     * @returns {FrameworkEventInitDetail<TInit>} The original event details.
+     */
+    get originalDetail() {
+        return __classPrivateFieldGet(this, _FrameworkEvent_originalDetail, "f");
+    }
+    /**
+     * Gets the source object that triggered the event.
+     * @returns {FrameworkEventInitSource<TInit> | undefined} The source object that triggered the event, or `undefined` if the source is not available.
+     */
     get source() {
         return __classPrivateFieldGet(this, _FrameworkEvent_source, "f");
     }
+    /**
+     * Gets the type of the `FrameworkEvent`.
+     * @returns {TType} The type of the `FrameworkEvent`.
+     */
     get type() {
         return this.__type;
     }
+    /**
+     * Indicates whether the event details can be mutated.
+     * If this property is `true`, the event details can be updated using the `updateDetails` method.
+     * @returns {boolean} `true` if the event details can be mutated, `false` otherwise.
+     */
+    get allowEventDetailsMutation() {
+        return __classPrivateFieldGet(this, _FrameworkEvent_mutableDetails, "f");
+    }
+    /**
+     * Prevents the default action of the event from occurring, if the event is cancelable.
+     * If the event is cancelable, this method sets the `canceled` property to `true`.
+     */
     preventDefault() {
@@ -55,7 +130,27 @@ if (this.cancelable) {
     }
+    /**
+     * Prevents the event from bubbling up the DOM tree, effectively stopping its propagation.
+     * This method sets the `#canBubble` property to `false`, which indicates that the event should not be propagated further.
+     */
     stopPropagation() {
         __classPrivateFieldSet(this, _FrameworkEvent_canBubble, false, "f");
     }
+    /**
+     * Updates the event details using the provided function.
+     *
+     * @note If the event details are not mutable, an error will be thrown.
+     *
+     * @see {FrameworkEvent.originalDetail}
+     *
+     * @param fn - A function that takes the current event details and returns an updated version of the details.
+     * The function can return `void` or `undefined` to indicate that no changes should be made.
+     */
+    updateDetails(fn) {
+        if (!__classPrivateFieldGet(this, _FrameworkEvent_mutableDetails, "f")) {
+            throw new Error('Event details are not mutable');
+        }
+        __classPrivateFieldSet(this, _FrameworkEvent_detail, produce(__classPrivateFieldGet(this, _FrameworkEvent_detail, "f"), fn), "f");
+    }
 }
-_FrameworkEvent_detail = new WeakMap(), _FrameworkEvent_source = new WeakMap(), _FrameworkEvent_canceled = new WeakMap(), _FrameworkEvent_cancelable = new WeakMap(), _FrameworkEvent_canBubble = new WeakMap(), _FrameworkEvent_created = new WeakMap();
+_FrameworkEvent_detail = new WeakMap(), _FrameworkEvent_originalDetail = new WeakMap(), _FrameworkEvent_source = new WeakMap(), _FrameworkEvent_canceled = new WeakMap(), _FrameworkEvent_cancelable = new WeakMap(), _FrameworkEvent_mutableDetails = new WeakMap(), _FrameworkEvent_canBubble = new WeakMap(), _FrameworkEvent_created = new WeakMap();
 //# sourceMappingURL=event.js.map

dist/esm/version.js

@@ -1,2 +0,3 @@
-export const version = '4.1.2';
+// Generated by genversion.
+export const version = '4.2.0';
 //# sourceMappingURL=version.js.map

dist/types/configurator.d.ts

 import { FrameworkEvent } from './event';
 export interface IEventModuleConfigurator {
+    /** Callback when events are dispatched (before other listeners) */
     onDispatch?: (event: FrameworkEvent) => Promise<void> | void;
+    /**
+     * Callback when listeners of providers are notified
+     *
+     *__NOTE__: if preventDefault or stopPropagation is called, this callback will not trigger
+     */
     onBubble?: (event: FrameworkEvent) => Promise<void> | void;
 }

dist/types/dispatcher.d.ts

 import { IFrameworkEvent } from './event';
 export type FrameworkEventHandler<TType extends IFrameworkEvent = IFrameworkEvent> = (event: TType) => Promise<void> | void;
+/**
+ * Interface for dispatching framework events.
+ * @template TEvent - The type of event to dispatch.
+ */
 export interface IFrameworkDispatcher<TEvent extends IFrameworkEvent> {
+    /**
+     * Dispatches the given event to the given listeners.
+     * @param event - The event to dispatch.
+     * @param listeners - The listeners to dispatch the event to.
+     */
     dispatch(event: TEvent, listeners: Array<FrameworkEventHandler<TEvent>>): Promise<void>;
@@ -5,0 +14,0 @@ }

dist/types/event.d.ts

 import type { ModuleInstance } from '@equinor/fusion-framework-module';
 import type { IEventModuleProvider } from './provider';
+import { type Draft } from 'immer';
 export declare interface FrameworkEventMap {
     onModulesLoaded: FrameworkEvent<FrameworkEventInit<ModuleInstance, IEventModuleProvider>>;
 }
+/**
+ * Represents a handler function for framework events.
+ * @template TType - The type of the framework event.
+ * @param event - The framework event object.
+ * @returns A promise that resolves when the handler has completed its execution, or void if no promise is returned.
+ */
 export type FrameworkEventHandler<TType extends IFrameworkEvent = IFrameworkEvent> = (event: TType) => Promise<void> | void;
+/**
+ * Represents a framework event.
+ *
+ * @template TInit - The type of the event initialization options.
+ * @template TType - The type of the event name.
+ */
 export interface IFrameworkEvent<TInit extends FrameworkEventInit = FrameworkEventInit, TType extends string = string> {
+    /** Name of the event. */
     readonly type: TType;
+    /** Timestamp of creation. */
     readonly created: number;
+    /** Payload of the event. */
     readonly detail: FrameworkEventInitDetail<TInit>;
+    /** Original payload of the event. */
+    readonly originalDetail: FrameworkEventInitDetail<TInit>;
+    /** Source of the event (dispatcher). */
     readonly source?: FrameworkEventInitSource<TInit>;
+    /** Indicates whether the event can be canceled. */
     readonly cancelable?: boolean;
+    /** Indicates whether the event detail is mutable */
+    readonly allowEventDetailsMutation: boolean;
+    /** Indicates whether the event has been canceled and should not be processed further. */
     readonly canceled?: boolean;
+    /** Indicates whether the event can bubble up. */
     readonly bubbles?: boolean;
+    /**
+     * Updates the details of the framework event.
+     *
+     * @note updating the details should only be allowed if the event is mutable.
+     *
+     * @param fn - A function that takes the current draft of the event details and returns the updated details, or `void` to cancel the update.
+     */
+    updateDetails(fn: (details: Draft<FrameworkEventInitDetail<TInit>>) => FrameworkEventInitDetail<TInit> | void | undefined): void;
 }
+/**
+ * initial args of event
+ *
+ * @template TDetail - type of event detail, event data payload
+ * @template TSource - type of event source
+ */
 export type FrameworkEventInit<TDetail = any, TSource = any> = {
+    /** Event data */
     detail: TDetail;
+    /** Flag for allowing to mutate event data */
+    mutableDetails?: boolean;
+    /** Source of the event trigger */
     source?: TSource;
+    /** Flag for allowing events to be canceled */
     cancelable?: boolean;
+    /** Timestamp of when event was created */
     created?: number;
+    /** Flag for allowing event to propagate to parent scope  */
     canBubble?: boolean;
 };
+/** defer init type args of event */
 export type FrameworkEventInitType<T> = T extends IFrameworkEvent<infer U> ? U : T extends FrameworkEvent<infer U> ? U : never;
+/** defer name type of event */
 export type FrameworkEventType<T> = T extends IFrameworkEvent<FrameworkEventInit, infer U> ? U : never;
 export type FrameworkEventInitDetail<T> = T extends FrameworkEventInit<infer U> ? U : never;
 export type FrameworkEventInitSource<T> = T extends FrameworkEventInit<unknown, infer U> ? U : never;
+/** defer detail type of event */
 export type FrameworkEventDetail<T> = T extends IFrameworkEvent<infer U> ? FrameworkEventInitDetail<U> : never;
+/** defer source type of event */
 export type FrameworkEventSource<T> = T extends IFrameworkEvent<infer U> ? FrameworkEventInitSource<U> : never;
+/** event constructor of mapped event  */
 export interface FrameworkEvent<TInit extends FrameworkEventInit> {
     new (type: keyof FrameworkEventMap, args: TInit): IFrameworkEvent<TInit>;
 }
+/** event constructor for unknown event */
 export interface FrameworkEvent<TInit extends FrameworkEventInit> {
     new (type: string, args: TInit): IFrameworkEvent<TInit>;
 }
+/**
+ * Represents a framework event with customizable details and behavior.
+ *
+ * The `FrameworkEvent` class implements the `IFrameworkEvent` interface and provides a way to create and manage events
+ * with custom details and behavior. It allows you to:
+ *
+ * - Specify the event type and initial event details
+ * - Access the event details, including the original details and any updates
+ * - Check if the event is cancelable and whether it has been canceled
+ * - Control whether the event can bubble up the event hierarchy
+ * - Update the event details during the event lifecycle
+ *
+ * The `FrameworkEvent` class is designed to be used as a base class for creating custom event types that fit the needs
+ * of your application or framework.
+ *
+ * @template TInit The type of the event details.
+ * @template TType The type of the event type.
+ */
 export declare class FrameworkEvent<TInit extends FrameworkEventInit = FrameworkEventInit, TType extends string = keyof FrameworkEventMap> implements IFrameworkEvent<TInit, TType> {
@@ -39,11 +108,73 @@ #private;
     constructor(__type: string, args: TInit);
+    /**
+     * Indicates whether the event can bubble up the event hierarchy.
+     * The event will only bubble if this property is `true` and the event has not been canceled.
+     * @returns {boolean} `true` if the event can bubble, `false` otherwise.
+     */
     get bubbles(): boolean;
+    /**
+     * Gets the timestamp when the `FrameworkEvent` was created.
+     * @returns {number} The timestamp of when the `FrameworkEvent` was created.
+     */
     get created(): number;
+    /**
+     * Indicates whether the event is cancelable.
+     * If the event is cancelable, it can be prevented from occurring by calling the `preventDefault()` method.
+     * @returns {boolean} `true` if the event is cancelable, `false` otherwise.
+     */
     get cancelable(): boolean;
+    /**
+     * Indicates whether the event has been canceled.
+     * If the event is cancelable and `preventDefault()` has been called, this property will be `true`.
+     * @returns {boolean} `true` if the event has been canceled, `false` otherwise.
+     */
     get canceled(): boolean;
+    /**
+     * Gets the current event details.
+     * @returns {FrameworkEventInitDetail<TInit>} The current event details.
+     */
     get detail(): FrameworkEventInitDetail<TInit>;
+    /**
+     * Gets the original event details that were passed to the `FrameworkEvent` constructor.
+     * This property provides access to the original event details, which may have been modified by the `updateDetails` method.
+     * @returns {FrameworkEventInitDetail<TInit>} The original event details.
+     */
+    get originalDetail(): FrameworkEventInitDetail<TInit>;
+    /**
+     * Gets the source object that triggered the event.
+     * @returns {FrameworkEventInitSource<TInit> | undefined} The source object that triggered the event, or `undefined` if the source is not available.
+     */
     get source(): FrameworkEventInitSource<TInit> | undefined;
+    /**
+     * Gets the type of the `FrameworkEvent`.
+     * @returns {TType} The type of the `FrameworkEvent`.
+     */
     get type(): TType;
+    /**
+     * Indicates whether the event details can be mutated.
+     * If this property is `true`, the event details can be updated using the `updateDetails` method.
+     * @returns {boolean} `true` if the event details can be mutated, `false` otherwise.
+     */
+    get allowEventDetailsMutation(): boolean;
+    /**
+     * Prevents the default action of the event from occurring, if the event is cancelable.
+     * If the event is cancelable, this method sets the `canceled` property to `true`.
+     */
     preventDefault(): void;
+    /**
+     * Prevents the event from bubbling up the DOM tree, effectively stopping its propagation.
+     * This method sets the `#canBubble` property to `false`, which indicates that the event should not be propagated further.
+     */
     stopPropagation(): void;
+    /**
+     * Updates the event details using the provided function.
+     *
+     * @note If the event details are not mutable, an error will be thrown.
+     *
+     * @see {FrameworkEvent.originalDetail}
+     *
+     * @param fn - A function that takes the current event details and returns an updated version of the details.
+     * The function can return `void` or `undefined` to indicate that no changes should be made.
+     */
+    updateDetails(fn: (details: Draft<FrameworkEventInitDetail<TInit>>) => FrameworkEventInitDetail<TInit> | void | undefined): void;
 }

dist/types/filter-event.d.ts

 import { FrameworkEventMap, IFrameworkEvent } from './event';
-export declare const filterEvent: <TType extends "onModulesLoaded">(type: TType) => import("rxjs").OperatorFunction<IFrameworkEvent<import("./event").FrameworkEventInit<any, any>, string>, FrameworkEventMap[TType]>;
+export declare const filterEvent: <TType extends keyof FrameworkEventMap>(type: TType) => import("rxjs").OperatorFunction<IFrameworkEvent<import("./event").FrameworkEventInit<any, any>, string>, FrameworkEventMap[TType]>;
 export default filterEvent;

dist/types/provider.d.ts

@@ -7,8 +7,21 @@ import { Observable, Observer, Subscription } from 'rxjs';
     readonly event$: Observable<IFrameworkEvent>;
+    /** subscribe to a known mapped event @see {@link FrameworkEventMap} */
     addEventListener<TKey extends keyof FrameworkEventMap>(type: TKey, handler: FrameworkEventHandler<FrameworkEventMap[TKey]>): VoidFunction;
+    /** subscribe to generic type */
     addEventListener<TType extends FrameworkEvent = FrameworkEvent>(type: string, handler: FrameworkEventHandler<TType>): VoidFunction;
+    /** dispatch a known mapped event type @see {@link FrameworkEventMap} */
     dispatchEvent<TType extends keyof FrameworkEventMap>(type: TType, args: FrameworkEventInitType<FrameworkEventMap[TType]>): Promise<FrameworkEvent>;
+    /** dispatch generic event */
     dispatchEvent<TDetail, TSource>(type: string, args: FrameworkEventInit<TDetail, TSource>): Promise<FrameworkEvent>;
+    /** dispatch event instance */
     dispatchEvent<TType extends IFrameworkEvent = FrameworkEvent>(event: TType): Promise<FrameworkEvent>;
+    /**
+     * subscribe to events
+     * __note__: does not allow side effects
+     */
     subscribe(observer?: Partial<Observer<IFrameworkEvent>>): Subscription;
+    /**
+     * subscribe to events
+     * __note__: does not allow side effects
+     */
     subscribe(next: (value: IFrameworkEvent) => void): Subscription;
@@ -15,0 +28,0 @@ dispose: VoidFunction;

dist/types/version.d.ts

@@ -1,1 +0,1 @@
-export declare const version = "4.1.2";
+export declare const version = "4.2.0";

package.json

 {
   "name": "@equinor/fusion-framework-module-event",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "Fusion module for events",
@@ -27,7 +27,8 @@ "main": "./dist/esm/index.js",
   "dependencies": {
-    "@equinor/fusion-framework-module": "^4.3.1"
+    "immer": "^9.0.16",
+    "@equinor/fusion-framework-module": "^4.3.2"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
-    "typescript": "^5.4.2"
+    "typescript": "^5.5.3"
   },
@@ -34,0 +35,0 @@ "types": "index.d.ts",

src/event.ts

 import type { ModuleInstance } from '@equinor/fusion-framework-module';
 import type { IEventModuleProvider } from './provider';
 
+import { produce, type Draft } from 'immer';
+
 export declare interface FrameworkEventMap {
@@ -8,2 +10,8 @@ onModulesLoaded: FrameworkEvent<FrameworkEventInit<ModuleInstance, IEventModuleProvider>>;
 
+/**
+ * Represents a handler function for framework events.
+ * @template TType - The type of the framework event.
+ * @param event - The framework event object.
+ * @returns A promise that resolves when the handler has completed its execution, or void if no promise is returned.
+ */
 export type FrameworkEventHandler<TType extends IFrameworkEvent = IFrameworkEvent> = (
@@ -13,2 +21,8 @@ event: TType,
 
+/**
+ * Represents a framework event.
+ *
+ * @template TInit - The type of the event initialization options.
+ * @template TType - The type of the event name.
+ */
 export interface IFrameworkEvent<
@@ -18,26 +32,62 @@ TInit extends FrameworkEventInit = FrameworkEventInit,
 > {
-    /** name of event */
+    /** Name of the event. */
     readonly type: TType;
 
-    /** timestamp of creation */
+    /** Timestamp of creation. */
     readonly created: number;
 
-    /** payload of event */
+    /** Payload of the event. */
     readonly detail: FrameworkEventInitDetail<TInit>;
 
-    /** source of event (dispatcher) */
+    /** Original payload of the event. */
+    readonly originalDetail: FrameworkEventInitDetail<TInit>;
+
+    /** Source of the event (dispatcher). */
     readonly source?: FrameworkEventInitSource<TInit>;
 
+    /** Indicates whether the event can be canceled. */
     readonly cancelable?: boolean;
+
+    /** Indicates whether the event detail is mutable */
+    readonly allowEventDetailsMutation: boolean;
+
+    /** Indicates whether the event has been canceled and should not be processed further. */
     readonly canceled?: boolean;
+
+    /** Indicates whether the event can bubble up. */
     readonly bubbles?: boolean;
+
+    /**
+     * Updates the details of the framework event.
+     *
+     * @note updating the details should only be allowed if the event is mutable.
+     *
+     * @param fn - A function that takes the current draft of the event details and returns the updated details, or `void` to cancel the update.
+     */
+    updateDetails(
+        fn: (
+            details: Draft<FrameworkEventInitDetail<TInit>>,
+        ) => FrameworkEventInitDetail<TInit> | void | undefined,
+    ): void;
 }
 
-/** initial args of event  */
+/**
+ * initial args of event
+ *
+ * @template TDetail - type of event detail, event data payload
+ * @template TSource - type of event source
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type FrameworkEventInit<TDetail = any, TSource = any> = {
+    /** Event data */
     detail: TDetail;
+    /** Flag for allowing to mutate event data */
+    mutableDetails?: boolean;
+    /** Source of the event trigger */
     source?: TSource;
+    /** Flag for allowing events to be canceled */
     cancelable?: boolean;
+    /** Timestamp of when event was created */
     created?: number;
+    /** Flag for allowing event to propagate to parent scope  */
     canBubble?: boolean;
@@ -78,3 +128,18 @@ };
 /**
- * Event Object
+ * Represents a framework event with customizable details and behavior.
+ *
+ * The `FrameworkEvent` class implements the `IFrameworkEvent` interface and provides a way to create and manage events
+ * with custom details and behavior. It allows you to:
+ *
+ * - Specify the event type and initial event details
+ * - Access the event details, including the original details and any updates
+ * - Check if the event is cancelable and whether it has been canceled
+ * - Control whether the event can bubble up the event hierarchy
+ * - Update the event details during the event lifecycle
+ *
+ * The `FrameworkEvent` class is designed to be used as a base class for creating custom event types that fit the needs
+ * of your application or framework.
+ *
+ * @template TInit The type of the event details.
+ * @template TType The type of the event type.
  */
@@ -88,5 +153,7 @@ // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
     #detail: FrameworkEventInitDetail<TInit>;
+    #originalDetail: FrameworkEventInitDetail<TInit>;
     #source?: FrameworkEventInitSource<TInit>;
     #canceled = false;
     #cancelable: boolean;
+    #mutableDetails: boolean;
     #canBubble: boolean;
@@ -99,4 +166,6 @@ #created: number = Date.now();
     ) {
-        this.#detail = args.detail as FrameworkEventInitDetail<TInit>;
-        this.#source = args.source as FrameworkEventInitSource<TInit>;
+        this.#detail = produce(args.detail, () => {}) as FrameworkEventInitDetail<TInit>;
+        this.#mutableDetails = !!args.mutableDetails;
+        this.#originalDetail = produce(args.detail, () => {}) as FrameworkEventInitDetail<TInit>;
+        this.#source = produce(args.source, () => {}) as FrameworkEventInitSource<TInit>;
         this.#cancelable = !!args.cancelable;
@@ -106,3 +175,7 @@ this.#canBubble = args.canBubble === undefined ? true : args.canBubble;
 
-    /** flag for if the event can propagate */
+    /**
+     * Indicates whether the event can bubble up the event hierarchy.
+     * The event will only bubble if this property is `true` and the event has not been canceled.
+     * @returns {boolean} `true` if the event can bubble, `false` otherwise.
+     */
     public get bubbles(): boolean {
@@ -112,2 +185,6 @@ return this.#canBubble && !this.#canceled;
 
+    /**
+     * Gets the timestamp when the `FrameworkEvent` was created.
+     * @returns {number} The timestamp of when the `FrameworkEvent` was created.
+     */
     public get created(): number {
@@ -117,2 +194,7 @@ return this.#created;
 
+    /**
+     * Indicates whether the event is cancelable.
+     * If the event is cancelable, it can be prevented from occurring by calling the `preventDefault()` method.
+     * @returns {boolean} `true` if the event is cancelable, `false` otherwise.
+     */
     public get cancelable(): boolean {
@@ -122,2 +204,7 @@ return this.#cancelable;
 
+    /**
+     * Indicates whether the event has been canceled.
+     * If the event is cancelable and `preventDefault()` has been called, this property will be `true`.
+     * @returns {boolean} `true` if the event has been canceled, `false` otherwise.
+     */
     public get canceled(): boolean {
@@ -127,2 +214,6 @@ return this.#canceled;
 
+    /**
+     * Gets the current event details.
+     * @returns {FrameworkEventInitDetail<TInit>} The current event details.
+     */
     public get detail(): FrameworkEventInitDetail<TInit> {
@@ -132,2 +223,15 @@ return this.#detail;
 
+    /**
+     * Gets the original event details that were passed to the `FrameworkEvent` constructor.
+     * This property provides access to the original event details, which may have been modified by the `updateDetails` method.
+     * @returns {FrameworkEventInitDetail<TInit>} The original event details.
+     */
+    public get originalDetail(): FrameworkEventInitDetail<TInit> {
+        return this.#originalDetail;
+    }
+
+    /**
+     * Gets the source object that triggered the event.
+     * @returns {FrameworkEventInitSource<TInit> | undefined} The source object that triggered the event, or `undefined` if the source is not available.
+     */
     public get source(): FrameworkEventInitSource<TInit> | undefined {
@@ -137,2 +241,6 @@ return this.#source;
 
+    /**
+     * Gets the type of the `FrameworkEvent`.
+     * @returns {TType} The type of the `FrameworkEvent`.
+     */
     public get type(): TType {
@@ -142,3 +250,15 @@ return this.__type as TType;
 
-    /** cancel the event */
+    /**
+     * Indicates whether the event details can be mutated.
+     * If this property is `true`, the event details can be updated using the `updateDetails` method.
+     * @returns {boolean} `true` if the event details can be mutated, `false` otherwise.
+     */
+    public get allowEventDetailsMutation(): boolean {
+        return this.#mutableDetails;
+    }
+
+    /**
+     * Prevents the default action of the event from occurring, if the event is cancelable.
+     * If the event is cancelable, this method sets the `canceled` property to `true`.
+     */
     public preventDefault() {
@@ -150,6 +270,30 @@ if (this.cancelable) {
 
-    /** prevent event to bubble */
+    /**
+     * Prevents the event from bubbling up the DOM tree, effectively stopping its propagation.
+     * This method sets the `#canBubble` property to `false`, which indicates that the event should not be propagated further.
+     */
     public stopPropagation(): void {
         this.#canBubble = false;
     }
+
+    /**
+     * Updates the event details using the provided function.
+     *
+     * @note If the event details are not mutable, an error will be thrown.
+     *
+     * @see {FrameworkEvent.originalDetail}
+     *
+     * @param fn - A function that takes the current event details and returns an updated version of the details.
+     * The function can return `void` or `undefined` to indicate that no changes should be made.
+     */
+    public updateDetails(
+        fn: (
+            details: Draft<FrameworkEventInitDetail<TInit>>,
+        ) => FrameworkEventInitDetail<TInit> | void | undefined,
+    ) {
+        if (!this.#mutableDetails) {
+            throw new Error('Event details are not mutable');
+        }
+        this.#detail = produce(this.#detail, fn) as FrameworkEventInitDetail<TInit>;
+    }
 }

src/version.ts

 // Generated by genversion.
-export const version = '4.1.2';
+export const version = '4.2.0';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

142010

increased by19.3%

Lines of code

1125

increased by53.27%

Worsened metrics

Dependency count

2

increased by100%

Dependency changes

• + Addedimmer@^9.0.16

• + Addedimmer@9.0.21(transitive)

• Updated@equinor/fusion-framework-module@^4.3.2