@cadenza.io/core 3.25.0 → 3.26.0

package/dist/index.d.mts

@@ -355,6 +355,7 @@ interface InquiryOptions {
     timeout?: number;
     rejectOnTimeout?: boolean;
     includePendingTasks?: boolean;
+    requireComplete?: boolean;
 }
 declare class InquiryBroker extends SignalEmitter {
     static instance_: InquiryBroker;
@@ -1070,14 +1071,14 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {...string[]} signals - The array of signal names to observe.
      * @return {this} The current instance after adding the specified signals.
      */
-    doOn(...signals: string[]): this;
+    doOn(...signals: SignalDefinitionInput[]): this;
     /**
      * Registers the specified signals to be emitted after the Task executes successfully and attaches them for further processing.
      *
      * @param {...string} signals - The list of signals to be registered for emission.
      * @return {this} The current instance for method chaining.
      */
-    emits(...signals: string[]): this;
+    emits(...signals: SignalDefinitionInput[]): this;
     /**
      * Configures the instance to emit specified signals when the task execution fails.
      * A failure is defined as anything that does not return a successful result.
@@ -1085,14 +1086,14 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {...string} signals - The names of the signals to emit upon failure.
      * @return {this} Returns the current instance for chaining.
      */
-    emitsOnFail(...signals: string[]): this;
+    emitsOnFail(...signals: SignalDefinitionInput[]): this;
     /**
      * Attaches a signal to the current context and emits metadata if the register flag is set.
      *
      * @param {...string} signals - The names of the signals to attach.
      * @return {void} This method does not return a value.
      */
-    attachSignal(...signals: string[]): Task;
+    attachSignal(...signals: SignalDefinitionInput[]): Task;
     /**
      * Unsubscribes the current instance from the specified signals.
      * This method removes the signals from the observedSignals set, unsubscribes
@@ -1485,6 +1486,22 @@ interface EmitOptions {
     throttleBatch?: number;
     flushStrategy?: string;
 }
+type SignalDeliveryMode = "single" | "broadcast";
+type SignalReceiverFilter = {
+    serviceNames?: string[];
+    serviceInstanceIds?: string[];
+    origins?: string[];
+    roles?: string[];
+    protocols?: string[];
+    runtimeStates?: string[];
+};
+type SignalMetadata = {
+    deliveryMode?: SignalDeliveryMode;
+    broadcastFilter?: SignalReceiverFilter | null;
+};
+type SignalDefinitionInput = string | ({
+    name: string;
+} & SignalMetadata);
 type FlushStrategyName = string;
 interface FlushStrategy {
     intervalMs: number;
@@ -1513,12 +1530,17 @@ declare class SignalBroker {
         registered: boolean;
     }>;
     emittedSignalsRegistry: Set<string>;
+    signalMetadataRegistry: Map<string, SignalMetadata>;
     private flushStrategies;
     private strategyData;
     private strategyTimers;
     private isStrategyFlushing;
     private readonly defaultStrategyName;
     constructor();
+    private resolveSignalMetadataKey;
+    private normalizeSignalMetadata;
+    setSignalMetadata(signal: string, metadata?: SignalMetadata | null): void;
+    getSignalMetadata(signal: string): SignalMetadata | undefined;
     logMemoryFootprint(label?: string): void;
     /**
      * Validates the provided signal name string to ensure it adheres to specific formatting rules.
@@ -1617,15 +1639,15 @@ declare class SignalBroker {
      * @param {string} signal - The name of the signal to be added.
      * @return {void} This method does not return any value.
      */
-    addSignal(signal: string): void;
+    addSignal(signal: string, metadata?: SignalMetadata | null): 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;
+    observe(signal: string, routineOrTask: Task | GraphRoutine, metadata?: SignalMetadata | null): void;
+    registerEmittedSignal(signal: string, metadata?: SignalMetadata | null): void;
     /**
      * Unsubscribes a routine/task from a signal.
      * @param signal The signal.
@@ -2082,6 +2104,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private readonly stateByKey;
     private readonly sessionByKey;
     private readonly idempotencyByKey;
+    private readonly writeQueueByKey;
     private nextTaskBindingIndex;
     /**
      * Creates an actor instance and optionally materializes the default key.
@@ -2133,6 +2156,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private ensureStateRecord;
     private touchSession;
     private runWithOptionalIdempotency;
+    private runWithPerKeyWriteSerialization;
     private getActiveIdempotencyRecord;
     private persistDurableStateIfConfigured;
     private emitActorCreatedSignal;
@@ -2666,4 +2690,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorFactoryOptions, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLoadPolicy, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorTaskRuntimeMetadata, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default, getActorTaskRuntimeMetadata };
+export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorFactoryOptions, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLoadPolicy, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorTaskRuntimeMetadata, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, type SignalDefinitionInput, type SignalDeliveryMode, SignalEmitter, type SignalMetadata, type SignalReceiverFilter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default, getActorTaskRuntimeMetadata };

package/dist/index.d.ts

@@ -355,6 +355,7 @@ interface InquiryOptions {
     timeout?: number;
     rejectOnTimeout?: boolean;
     includePendingTasks?: boolean;
+    requireComplete?: boolean;
 }
 declare class InquiryBroker extends SignalEmitter {
     static instance_: InquiryBroker;
@@ -1070,14 +1071,14 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {...string[]} signals - The array of signal names to observe.
      * @return {this} The current instance after adding the specified signals.
      */
-    doOn(...signals: string[]): this;
+    doOn(...signals: SignalDefinitionInput[]): this;
     /**
      * Registers the specified signals to be emitted after the Task executes successfully and attaches them for further processing.
      *
      * @param {...string} signals - The list of signals to be registered for emission.
      * @return {this} The current instance for method chaining.
      */
-    emits(...signals: string[]): this;
+    emits(...signals: SignalDefinitionInput[]): this;
     /**
      * Configures the instance to emit specified signals when the task execution fails.
      * A failure is defined as anything that does not return a successful result.
@@ -1085,14 +1086,14 @@ declare class Task extends SignalEmitter implements Graph {
      * @param {...string} signals - The names of the signals to emit upon failure.
      * @return {this} Returns the current instance for chaining.
      */
-    emitsOnFail(...signals: string[]): this;
+    emitsOnFail(...signals: SignalDefinitionInput[]): this;
     /**
      * Attaches a signal to the current context and emits metadata if the register flag is set.
      *
      * @param {...string} signals - The names of the signals to attach.
      * @return {void} This method does not return a value.
      */
-    attachSignal(...signals: string[]): Task;
+    attachSignal(...signals: SignalDefinitionInput[]): Task;
     /**
      * Unsubscribes the current instance from the specified signals.
      * This method removes the signals from the observedSignals set, unsubscribes
@@ -1485,6 +1486,22 @@ interface EmitOptions {
     throttleBatch?: number;
     flushStrategy?: string;
 }
+type SignalDeliveryMode = "single" | "broadcast";
+type SignalReceiverFilter = {
+    serviceNames?: string[];
+    serviceInstanceIds?: string[];
+    origins?: string[];
+    roles?: string[];
+    protocols?: string[];
+    runtimeStates?: string[];
+};
+type SignalMetadata = {
+    deliveryMode?: SignalDeliveryMode;
+    broadcastFilter?: SignalReceiverFilter | null;
+};
+type SignalDefinitionInput = string | ({
+    name: string;
+} & SignalMetadata);
 type FlushStrategyName = string;
 interface FlushStrategy {
     intervalMs: number;
@@ -1513,12 +1530,17 @@ declare class SignalBroker {
         registered: boolean;
     }>;
     emittedSignalsRegistry: Set<string>;
+    signalMetadataRegistry: Map<string, SignalMetadata>;
     private flushStrategies;
     private strategyData;
     private strategyTimers;
     private isStrategyFlushing;
     private readonly defaultStrategyName;
     constructor();
+    private resolveSignalMetadataKey;
+    private normalizeSignalMetadata;
+    setSignalMetadata(signal: string, metadata?: SignalMetadata | null): void;
+    getSignalMetadata(signal: string): SignalMetadata | undefined;
     logMemoryFootprint(label?: string): void;
     /**
      * Validates the provided signal name string to ensure it adheres to specific formatting rules.
@@ -1617,15 +1639,15 @@ declare class SignalBroker {
      * @param {string} signal - The name of the signal to be added.
      * @return {void} This method does not return any value.
      */
-    addSignal(signal: string): void;
+    addSignal(signal: string, metadata?: SignalMetadata | null): 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;
+    observe(signal: string, routineOrTask: Task | GraphRoutine, metadata?: SignalMetadata | null): void;
+    registerEmittedSignal(signal: string, metadata?: SignalMetadata | null): void;
     /**
      * Unsubscribes a routine/task from a signal.
      * @param signal The signal.
@@ -2082,6 +2104,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private readonly stateByKey;
     private readonly sessionByKey;
     private readonly idempotencyByKey;
+    private readonly writeQueueByKey;
     private nextTaskBindingIndex;
     /**
      * Creates an actor instance and optionally materializes the default key.
@@ -2133,6 +2156,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private ensureStateRecord;
     private touchSession;
     private runWithOptionalIdempotency;
+    private runWithPerKeyWriteSerialization;
     private getActiveIdempotencyRecord;
     private persistDurableStateIfConfigured;
     private emitActorCreatedSignal;
@@ -2666,4 +2690,4 @@ declare class Cadenza {
     static reset(): void;
 }
 
-export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorFactoryOptions, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLoadPolicy, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorTaskRuntimeMetadata, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, SignalEmitter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default, getActorTaskRuntimeMetadata };
+export { Actor, type ActorConsistencyProfileName, type ActorDefinition, type ActorFactoryOptions, type ActorInvocationOptions, type ActorKeyDefinition, type ActorKind, type ActorLoadPolicy, type ActorRuntimeReadGuard, type ActorSpec, type ActorStateDefinition, type ActorStateReducer, type ActorStateStore, type ActorTaskBindingDefinition, type ActorTaskBindingOptions, type ActorTaskContext, type ActorTaskHandler, type ActorTaskMode, type ActorTaskRuntimeMetadata, type ActorWriteContract, type AnyObject, type CadenzaMode, type DebounceOptions, DebounceTask, type EmitOptions, EphemeralTask, type EphemeralTaskOptions, GraphContext, GraphRegistry, GraphRoutine, GraphRun, GraphRunner, type IdempotencyPolicy, InquiryBroker, type InquiryOptions, type Intent, META_ACTOR_SESSION_STATE_PERSIST_INTENT, type ResolvedRuntimeValidationPolicy, type RetryPolicy, type RuntimeValidationMode, type RuntimeValidationPolicy, type RuntimeValidationScope, type Schema, type SchemaConstraints, type SchemaDefinition, type SchemaType, type SessionPolicy, SignalBroker, type SignalDefinitionInput, type SignalDeliveryMode, SignalEmitter, type SignalMetadata, type SignalReceiverFilter, Task, type TaskFunction, type TaskOptions, type TaskResult, type ThrottleTagGetter, Cadenza as default, getActorTaskRuntimeMetadata };