@cadenza.io/core 3.15.13 → 3.16.1

package/dist/index.d.mts

@@ -145,14 +145,16 @@ declare abstract class SignalEmitter {
      * Emits a signal via the broker.
      * @param signal The signal name.
      * @param data Optional payload (defaults to empty object).
+     * @param options
      */
-    emit(signal: string, data?: AnyObject): void;
+    emit(signal: string, data?: AnyObject, options?: EmitOptions): void;
     /**
      * Emits a signal via the broker if not silent.
      * @param signal The signal name.
      * @param data Optional payload (defaults to empty object).
+     * @param options
      */
-    emitMetrics(signal: string, data?: AnyObject): void;
+    emitMetrics(signal: string, data?: AnyObject, options?: EmitOptions): void;
 }
 
 /**
@@ -482,17 +484,19 @@ declare class GraphNode extends SignalEmitter implements Graph {
      * @param {string} signal - The name of the signal to be emitted.
      * @param {AnyObject} data - The data object to be sent along with the signal. Metadata
      * will be injected into this object before being emitted.
+     * @param options
      * @return {void} No return value.
      */
-    emitWithMetadata(signal: string, data: AnyObject): void;
+    emitWithMetadata(signal: string, data: AnyObject, options?: EmitOptions): void;
     /**
      * Emits metrics with additional metadata describing the task execution and context.
      *
      * @param {string} signal - The signal name being emitted.
      * @param {AnyObject} data - The data associated with the signal emission, enriched with metadata.
+     * @param options
      * @return {void} Emits the signal with enriched data and does not return a value.
      */
-    emitMetricsWithMetadata(signal: string, data: AnyObject): void;
+    emitMetricsWithMetadata(signal: string, data: AnyObject, options?: EmitOptions): void;
     /**
      * Updates the progress of a task and emits metrics with associated metadata.
      *
@@ -1394,6 +1398,15 @@ declare class GraphRunner extends SignalEmitter {
     setStrategy(strategy: GraphRunStrategy): void;
 }
 
+interface EmitOptions {
+    squash?: boolean;
+    squashId?: string | null;
+    mergeFunction?: ((oldContext: AnyObject, newContext: AnyObject) => AnyObject) | null;
+    debounce?: boolean;
+    delayMs?: number;
+    schedule?: boolean;
+    exactDateTime?: Date | null;
+}
 /**
  * This class manages signals and observers, enabling communication across different parts of an application.
  * It follows a singleton design pattern, allowing for centralized signal management.
@@ -1418,6 +1431,8 @@ declare class SignalBroker {
     runner: GraphRunner | undefined;
     metaRunner: GraphRunner | undefined;
     debouncedEmitters: Map<string, any>;
+    squashedEmitters: Map<string, any>;
+    squashedContexts: Map<string, any>;
     getSignalsTask: Task | undefined;
     registerSignalTask: Task | undefined;
     signalObservers: Map<string, {
@@ -1459,11 +1474,10 @@ declare class SignalBroker {
      *
      * @param {string} signal - The name of the signal to be emitted.
      * @param {AnyObject} context - The context to be passed along with the signal.
-     * @param {number} [timeoutMs=60000] - The delay in milliseconds before the signal is emitted. Defaults to 60,000 ms.
-     * @param {Date} [exactDateTime] - An exact date and time at which to emit the signal. If provided, this overrides the `timeoutMs`.
+     * @param options
      * @return {AbortController} An AbortController instance that can be used to cancel the scheduled signal emission.
      */
-    schedule(signal: string, context: AnyObject, timeoutMs?: number, exactDateTime?: Date): AbortController;
+    schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
     /**
      * Emits `signal` repeatedly with a fixed interval.
      *
@@ -1475,16 +1489,31 @@ declare class SignalBroker {
      * @returns a handle with `clear()` to stop the loop.
      */
     interval(signal: string, context: AnyObject, intervalMs?: number, leading?: boolean, startDateTime?: Date): ThrottleHandle;
-    debounce(signal: string, context: any, delayMs?: number): void;
+    debounce(signal: string, context: any, options?: {
+        delayMs: number;
+    }): void;
+    /**
+     * Aggregates and debounces multiple events with the same identifier to minimize redundant operations.
+     *
+     * @param {string} signal - The identifier for the event being emitted.
+     * @param {AnyObject} context - The context data associated with the event.
+     * @param {Object} [options] - Configuration options for handling the squashed event.
+     * @param {boolean} [options.squash=true] - Whether the event should be squashed.
+     * @param {string|null} [options.squashId=null] - A unique identifier for the squashed group of events. Defaults to the signal if null.
+     * @param {function|null} [options.mergeFunction=null] - A custom merge function that combines old and new contexts. If null, a default merge is used.
+     * @return {void} Does not return a value.
+     */
+    squash(signal: string, context: AnyObject, options?: EmitOptions): void;
     /**
      * Emits a signal with the specified context, triggering any associated handlers for that signal.
      *
      * @param {string} signal - The name of the signal to emit.
      * @param {AnyObject} [context={}] - An optional context object containing additional information or metadata
      * associated with the signal. If the context includes a `__routineExecId`, it will be handled accordingly.
+     * @param options
      * @return {void} This method does not return a value.
      */
-    emit(signal: string, context?: AnyObject): void;
+    emit(signal: string, context?: AnyObject, options?: EmitOptions): void;
     /**
      * Executes a signal by emitting events, updating context, and invoking listeners.
      * Creates a new execution trace if necessary and updates the context with relevant metadata.
@@ -1781,6 +1810,7 @@ declare class Cadenza {
      *
      * @param {string} event - The name of the event to emit.
      * @param {AnyObject} [data={}] - The data payload associated with the event.
+     * @param options
      * @return {void} - No return value.
      *
      * @example
@@ -1790,8 +1820,8 @@ declare class Cadenza {
      * Cadenza.emit('main.my_event', { foo: 'bar' });
      * ```
      */
-    static emit(event: string, data?: AnyObject): void;
-    static schedule(taskName: string, context: AnyObject, timeoutMs: number, exactDateTime?: Date): void;
+    static emit(event: string, data?: AnyObject, options?: EmitOptions): void;
+    static schedule(taskName: string, context: AnyObject, delayMs: number, exactDateTime?: Date): void;
     static interval(taskName: string, context: AnyObject, intervalMs: number, leading?: boolean, startDateTime?: Date): void;
     static debounce(signalName: string, context: any, delayMs: number): void;
     static get(taskName: string): Task | undefined;
@@ -2151,4 +2181,4 @@ declare class SignalTask extends Task {
     constructor(signal: string, description?: string);
 }
 
-export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, SignalTask, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };
+export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, SignalTask, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };

package/dist/index.d.ts

@@ -145,14 +145,16 @@ declare abstract class SignalEmitter {
      * Emits a signal via the broker.
      * @param signal The signal name.
      * @param data Optional payload (defaults to empty object).
+     * @param options
      */
-    emit(signal: string, data?: AnyObject): void;
+    emit(signal: string, data?: AnyObject, options?: EmitOptions): void;
     /**
      * Emits a signal via the broker if not silent.
      * @param signal The signal name.
      * @param data Optional payload (defaults to empty object).
+     * @param options
      */
-    emitMetrics(signal: string, data?: AnyObject): void;
+    emitMetrics(signal: string, data?: AnyObject, options?: EmitOptions): void;
 }
 
 /**
@@ -482,17 +484,19 @@ declare class GraphNode extends SignalEmitter implements Graph {
      * @param {string} signal - The name of the signal to be emitted.
      * @param {AnyObject} data - The data object to be sent along with the signal. Metadata
      * will be injected into this object before being emitted.
+     * @param options
      * @return {void} No return value.
      */
-    emitWithMetadata(signal: string, data: AnyObject): void;
+    emitWithMetadata(signal: string, data: AnyObject, options?: EmitOptions): void;
     /**
      * Emits metrics with additional metadata describing the task execution and context.
      *
      * @param {string} signal - The signal name being emitted.
      * @param {AnyObject} data - The data associated with the signal emission, enriched with metadata.
+     * @param options
      * @return {void} Emits the signal with enriched data and does not return a value.
      */
-    emitMetricsWithMetadata(signal: string, data: AnyObject): void;
+    emitMetricsWithMetadata(signal: string, data: AnyObject, options?: EmitOptions): void;
     /**
      * Updates the progress of a task and emits metrics with associated metadata.
      *
@@ -1394,6 +1398,15 @@ declare class GraphRunner extends SignalEmitter {
     setStrategy(strategy: GraphRunStrategy): void;
 }
 
+interface EmitOptions {
+    squash?: boolean;
+    squashId?: string | null;
+    mergeFunction?: ((oldContext: AnyObject, newContext: AnyObject) => AnyObject) | null;
+    debounce?: boolean;
+    delayMs?: number;
+    schedule?: boolean;
+    exactDateTime?: Date | null;
+}
 /**
  * This class manages signals and observers, enabling communication across different parts of an application.
  * It follows a singleton design pattern, allowing for centralized signal management.
@@ -1418,6 +1431,8 @@ declare class SignalBroker {
     runner: GraphRunner | undefined;
     metaRunner: GraphRunner | undefined;
     debouncedEmitters: Map<string, any>;
+    squashedEmitters: Map<string, any>;
+    squashedContexts: Map<string, any>;
     getSignalsTask: Task | undefined;
     registerSignalTask: Task | undefined;
     signalObservers: Map<string, {
@@ -1459,11 +1474,10 @@ declare class SignalBroker {
      *
      * @param {string} signal - The name of the signal to be emitted.
      * @param {AnyObject} context - The context to be passed along with the signal.
-     * @param {number} [timeoutMs=60000] - The delay in milliseconds before the signal is emitted. Defaults to 60,000 ms.
-     * @param {Date} [exactDateTime] - An exact date and time at which to emit the signal. If provided, this overrides the `timeoutMs`.
+     * @param options
      * @return {AbortController} An AbortController instance that can be used to cancel the scheduled signal emission.
      */
-    schedule(signal: string, context: AnyObject, timeoutMs?: number, exactDateTime?: Date): AbortController;
+    schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
     /**
      * Emits `signal` repeatedly with a fixed interval.
      *
@@ -1475,16 +1489,31 @@ declare class SignalBroker {
      * @returns a handle with `clear()` to stop the loop.
      */
     interval(signal: string, context: AnyObject, intervalMs?: number, leading?: boolean, startDateTime?: Date): ThrottleHandle;
-    debounce(signal: string, context: any, delayMs?: number): void;
+    debounce(signal: string, context: any, options?: {
+        delayMs: number;
+    }): void;
+    /**
+     * Aggregates and debounces multiple events with the same identifier to minimize redundant operations.
+     *
+     * @param {string} signal - The identifier for the event being emitted.
+     * @param {AnyObject} context - The context data associated with the event.
+     * @param {Object} [options] - Configuration options for handling the squashed event.
+     * @param {boolean} [options.squash=true] - Whether the event should be squashed.
+     * @param {string|null} [options.squashId=null] - A unique identifier for the squashed group of events. Defaults to the signal if null.
+     * @param {function|null} [options.mergeFunction=null] - A custom merge function that combines old and new contexts. If null, a default merge is used.
+     * @return {void} Does not return a value.
+     */
+    squash(signal: string, context: AnyObject, options?: EmitOptions): void;
     /**
      * Emits a signal with the specified context, triggering any associated handlers for that signal.
      *
      * @param {string} signal - The name of the signal to emit.
      * @param {AnyObject} [context={}] - An optional context object containing additional information or metadata
      * associated with the signal. If the context includes a `__routineExecId`, it will be handled accordingly.
+     * @param options
      * @return {void} This method does not return a value.
      */
-    emit(signal: string, context?: AnyObject): void;
+    emit(signal: string, context?: AnyObject, options?: EmitOptions): void;
     /**
      * Executes a signal by emitting events, updating context, and invoking listeners.
      * Creates a new execution trace if necessary and updates the context with relevant metadata.
@@ -1781,6 +1810,7 @@ declare class Cadenza {
      *
      * @param {string} event - The name of the event to emit.
      * @param {AnyObject} [data={}] - The data payload associated with the event.
+     * @param options
      * @return {void} - No return value.
      *
      * @example
@@ -1790,8 +1820,8 @@ declare class Cadenza {
      * Cadenza.emit('main.my_event', { foo: 'bar' });
      * ```
      */
-    static emit(event: string, data?: AnyObject): void;
-    static schedule(taskName: string, context: AnyObject, timeoutMs: number, exactDateTime?: Date): void;
+    static emit(event: string, data?: AnyObject, options?: EmitOptions): void;
+    static schedule(taskName: string, context: AnyObject, delayMs: number, exactDateTime?: Date): void;
     static interval(taskName: string, context: AnyObject, intervalMs: number, leading?: boolean, startDateTime?: Date): void;
     static debounce(signalName: string, context: any, delayMs: number): void;
     static get(taskName: string): Task | undefined;
@@ -2151,4 +2181,4 @@ declare class SignalTask extends Task {
     constructor(signal: string, description?: string);
 }
 
-export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, SignalTask, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };
+export { type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type SchemaConstraints, type SchemaDefinition, type SchemaType, SignalBroker, SignalEmitter, SignalTask, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default };