@cadenza.io/core 3.18.2 → 3.19.1

package/dist/index.d.mts

@@ -1468,6 +1468,12 @@ interface EmitOptions {
     schedule?: boolean;
     exactDateTime?: Date | null;
     throttleBatch?: number;
+    flushStrategy?: string;
+}
+type FlushStrategyName = string;
+interface FlushStrategy {
+    intervalMs: number;
+    maxBatchSize: number;
 }
 /**
  * This class manages signals and observers, enabling communication across different parts of an application.
@@ -1480,21 +1486,8 @@ declare class SignalBroker {
     verbose: boolean;
     setDebug(value: boolean): void;
     setVerbose(value: boolean): void;
-    /**
-     * Validates the provided signal name string to ensure it adheres to specific formatting rules.
-     * Throws an error if any of the validation checks fail.
-     *
-     * @param {string} signalName - The signal name to be validated.
-     * @return {void} - Returns nothing if the signal name is valid.
-     * @throws {Error} - Throws an error if the signal name is longer than 100 characters, contains spaces,
-     *                   contains backslashes, or contains uppercase letters in restricted parts of the name.
-     */
-    validateSignalName(signalName: string): void;
     runner: GraphRunner | undefined;
     metaRunner: GraphRunner | undefined;
-    debouncedEmitters: Map<string, any>;
-    squashedEmitters: Map<string, any>;
-    squashedContexts: Map<string, any[]>;
     throttleEmitters: Map<string, any>;
     throttleQueues: Map<string, any>;
     getSignalsTask: Task | undefined;
@@ -1505,7 +1498,22 @@ declare class SignalBroker {
         registered: boolean;
     }>;
     emittedSignalsRegistry: Set<string>;
+    private flushStrategies;
+    private strategyData;
+    private strategyTimers;
+    private isStrategyFlushing;
+    private readonly defaultStrategyName;
     constructor();
+    /**
+     * Validates the provided signal name string to ensure it adheres to specific formatting rules.
+     * Throws an error if any of the validation checks fail.
+     *
+     * @param {string} signalName - The signal name to be validated.
+     * @return {void} - Returns nothing if the signal name is valid.
+     * @throws {Error} - Throws an error if the signal name is longer than 100 characters, contains spaces,
+     *                   contains backslashes, or contains uppercase letters in restricted parts of the name.
+     */
+    validateSignalName(signalName: string): void;
     /**
      * Initializes with runners.
      * @param runner Standard runner for user signals.
@@ -1518,30 +1526,28 @@ declare class SignalBroker {
      * @return {void} This method does not return a value.
      */
     init(): void;
-    /**
-     * Observes a signal with a routine/task.
-     * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
-     * @param routineOrTask The observer.
-     * @edge Duplicates ignored; supports wildcards for broad listening.
-     */
-    observe(signal: string, routineOrTask: Task | GraphRoutine): void;
-    registerEmittedSignal(signal: string): void;
-    /**
-     * Unsubscribes a routine/task from a signal.
-     * @param signal The signal.
-     * @param routineOrTask The observer.
-     * @edge Removes all instances if duplicate; deletes if empty.
-     */
-    unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
-    /**
-     * Schedules a signal to be emitted after a specified delay or at an exact date and time.
-     *
-     * @param {string} signal - The name of the signal to be emitted.
-     * @param {AnyObject} context - The context to be passed along with the signal.
-     * @param options
-     * @return {AbortController} An AbortController instance that can be used to cancel the scheduled signal emission.
-     */
+    setFlushStrategy(name: FlushStrategyName, config: {
+        intervalMs: number;
+        maxBatchSize?: number;
+    }): void;
+    updateFlushStrategy(name: FlushStrategyName, config: FlushStrategy): void;
+    removeFlushStrategy(name: FlushStrategyName): void;
+    getFlushStrategies(): Record<FlushStrategyName, FlushStrategy>;
+    private readonly MAX_FLUSH_DURATION_MS;
+    squash(signal: string, context: AnyObject, options?: EmitOptions): void;
+    private flushGroup;
+    private flushStrategy;
+    clearSquashState(): void;
+    private scheduledBuckets;
+    private scheduleTimer;
     schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
+    private flushScheduled;
+    private debouncedEmitters;
+    private readonly MAX_DEBOUNCERS;
+    debounce(signal: string, context: any, options?: {
+        delayMs: number;
+    }): void;
+    throttle(signal: string, context: any, options?: EmitOptions): void;
     /**
      * Emits `signal` repeatedly with a fixed interval.
      *
@@ -1553,22 +1559,6 @@ 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, options?: {
-        delayMs: number;
-    }): void;
-    throttle(signal: string, context: any, options?: EmitOptions): 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.
      *
@@ -1609,6 +1599,21 @@ declare class SignalBroker {
      * @return {void} This method does not return any value.
      */
     addSignal(signal: string): void;
+    /**
+     * Observes a signal with a routine/task.
+     * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
+     * @param routineOrTask The observer.
+     * @edge Duplicates ignored; supports wildcards for broad listening.
+     */
+    observe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    registerEmittedSignal(signal: string): void;
+    /**
+     * Unsubscribes a routine/task from a signal.
+     * @param signal The signal.
+     * @param routineOrTask The observer.
+     * @edge Removes all instances if duplicate; deletes if empty.
+     */
+    unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
     /**
      * Lists all observed signals.
      * @returns Array of signals.
@@ -1616,6 +1621,7 @@ declare class SignalBroker {
     listObservedSignals(): string[];
     listEmittedSignals(): string[];
     reset(): void;
+    shutdown(): void;
 }
 
 /**

package/dist/index.d.ts

@@ -1468,6 +1468,12 @@ interface EmitOptions {
     schedule?: boolean;
     exactDateTime?: Date | null;
     throttleBatch?: number;
+    flushStrategy?: string;
+}
+type FlushStrategyName = string;
+interface FlushStrategy {
+    intervalMs: number;
+    maxBatchSize: number;
 }
 /**
  * This class manages signals and observers, enabling communication across different parts of an application.
@@ -1480,21 +1486,8 @@ declare class SignalBroker {
     verbose: boolean;
     setDebug(value: boolean): void;
     setVerbose(value: boolean): void;
-    /**
-     * Validates the provided signal name string to ensure it adheres to specific formatting rules.
-     * Throws an error if any of the validation checks fail.
-     *
-     * @param {string} signalName - The signal name to be validated.
-     * @return {void} - Returns nothing if the signal name is valid.
-     * @throws {Error} - Throws an error if the signal name is longer than 100 characters, contains spaces,
-     *                   contains backslashes, or contains uppercase letters in restricted parts of the name.
-     */
-    validateSignalName(signalName: string): void;
     runner: GraphRunner | undefined;
     metaRunner: GraphRunner | undefined;
-    debouncedEmitters: Map<string, any>;
-    squashedEmitters: Map<string, any>;
-    squashedContexts: Map<string, any[]>;
     throttleEmitters: Map<string, any>;
     throttleQueues: Map<string, any>;
     getSignalsTask: Task | undefined;
@@ -1505,7 +1498,22 @@ declare class SignalBroker {
         registered: boolean;
     }>;
     emittedSignalsRegistry: Set<string>;
+    private flushStrategies;
+    private strategyData;
+    private strategyTimers;
+    private isStrategyFlushing;
+    private readonly defaultStrategyName;
     constructor();
+    /**
+     * Validates the provided signal name string to ensure it adheres to specific formatting rules.
+     * Throws an error if any of the validation checks fail.
+     *
+     * @param {string} signalName - The signal name to be validated.
+     * @return {void} - Returns nothing if the signal name is valid.
+     * @throws {Error} - Throws an error if the signal name is longer than 100 characters, contains spaces,
+     *                   contains backslashes, or contains uppercase letters in restricted parts of the name.
+     */
+    validateSignalName(signalName: string): void;
     /**
      * Initializes with runners.
      * @param runner Standard runner for user signals.
@@ -1518,30 +1526,28 @@ declare class SignalBroker {
      * @return {void} This method does not return a value.
      */
     init(): void;
-    /**
-     * Observes a signal with a routine/task.
-     * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
-     * @param routineOrTask The observer.
-     * @edge Duplicates ignored; supports wildcards for broad listening.
-     */
-    observe(signal: string, routineOrTask: Task | GraphRoutine): void;
-    registerEmittedSignal(signal: string): void;
-    /**
-     * Unsubscribes a routine/task from a signal.
-     * @param signal The signal.
-     * @param routineOrTask The observer.
-     * @edge Removes all instances if duplicate; deletes if empty.
-     */
-    unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
-    /**
-     * Schedules a signal to be emitted after a specified delay or at an exact date and time.
-     *
-     * @param {string} signal - The name of the signal to be emitted.
-     * @param {AnyObject} context - The context to be passed along with the signal.
-     * @param options
-     * @return {AbortController} An AbortController instance that can be used to cancel the scheduled signal emission.
-     */
+    setFlushStrategy(name: FlushStrategyName, config: {
+        intervalMs: number;
+        maxBatchSize?: number;
+    }): void;
+    updateFlushStrategy(name: FlushStrategyName, config: FlushStrategy): void;
+    removeFlushStrategy(name: FlushStrategyName): void;
+    getFlushStrategies(): Record<FlushStrategyName, FlushStrategy>;
+    private readonly MAX_FLUSH_DURATION_MS;
+    squash(signal: string, context: AnyObject, options?: EmitOptions): void;
+    private flushGroup;
+    private flushStrategy;
+    clearSquashState(): void;
+    private scheduledBuckets;
+    private scheduleTimer;
     schedule(signal: string, context: AnyObject, options?: EmitOptions): AbortController;
+    private flushScheduled;
+    private debouncedEmitters;
+    private readonly MAX_DEBOUNCERS;
+    debounce(signal: string, context: any, options?: {
+        delayMs: number;
+    }): void;
+    throttle(signal: string, context: any, options?: EmitOptions): void;
     /**
      * Emits `signal` repeatedly with a fixed interval.
      *
@@ -1553,22 +1559,6 @@ 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, options?: {
-        delayMs: number;
-    }): void;
-    throttle(signal: string, context: any, options?: EmitOptions): 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.
      *
@@ -1609,6 +1599,21 @@ declare class SignalBroker {
      * @return {void} This method does not return any value.
      */
     addSignal(signal: string): void;
+    /**
+     * Observes a signal with a routine/task.
+     * @param signal The signal (e.g., 'domain.action', 'domain.*' for wildcards).
+     * @param routineOrTask The observer.
+     * @edge Duplicates ignored; supports wildcards for broad listening.
+     */
+    observe(signal: string, routineOrTask: Task | GraphRoutine): void;
+    registerEmittedSignal(signal: string): void;
+    /**
+     * Unsubscribes a routine/task from a signal.
+     * @param signal The signal.
+     * @param routineOrTask The observer.
+     * @edge Removes all instances if duplicate; deletes if empty.
+     */
+    unsubscribe(signal: string, routineOrTask: Task | GraphRoutine): void;
     /**
      * Lists all observed signals.
      * @returns Array of signals.
@@ -1616,6 +1621,7 @@ declare class SignalBroker {
     listObservedSignals(): string[];
     listEmittedSignals(): string[];
     reset(): void;
+    shutdown(): void;
 }
 
 /**