@artstesh/postboy 1.4.6 → 1.5.0

package/lib/index.d.mts

@@ -37,7 +37,6 @@ declare abstract class PostboyMessage {
  */
 declare abstract class PostboyGenericMessage extends PostboyMessage {
 }
-declare function checkId(message: new (...args: any[]) => any): string;
 
 declare abstract class PostboyExecutor<T> extends PostboyMessage {
     protected readonly _postboyResultType?: T;
@@ -205,43 +204,52 @@ declare abstract class PostboyAbstractRegistrator {
     recordSubject<T extends PostboyGenericMessage>(type: MessageType<T>): this;
 }
 
-interface PostboyMiddleware {
-    handle(message: PostboyMessage): void;
+declare enum MiddlewareStage {
+    Publish = 1,
+    Callback = 2,
+    Execute = 3
 }
 
-/**
- * A service class that manages middleware functions for processing PostboyMessage objects.
- * It provides methods to add, remove, and execute middlewares in sequence.
- */
-declare class PostboyMiddlewareService {
-    protected middlewares: PostboyMiddleware[];
-    /**
-     * Adds a middleware function to the collection of middlewares.
-     *
-     * @param {PostboyMiddleware} middleware - The middleware function to be added.
-     * @return {void}
-     */
-    addMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Removes a middleware from the list of registered middlewares.
-     *
-     * @param {PostboyMiddleware} middleware - The middleware instance to be removed.
-     * @return {void} No return value.
-     */
-    removeMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Manages the processing of a PostboyMessage by sequentially applying all middlewares.
-     *
-     * @param {PostboyMessage} msg - The message object to be processed by the middlewares.
-     * @return {void} - This method does not return any value.
-     */
-    manage(msg: PostboyMessage): void;
-    /**
-     * Disposes of the current object by clearing its middlewares array.
-     *
-     * @return {void} This method does not return a value.
-     */
-    dispose(): void;
+interface PipelineContext<T extends PostboyMessage = PostboyMessage> {
+    stage: MiddlewareStage;
+    message: T;
+}
+
+declare enum MiddlewareDecisionType {
+    Continue = 1,
+    Interrupt = 2
+}
+
+interface MiddlewareDecision {
+    type: MiddlewareDecisionType;
+}
+
+interface CancelDetails {
+    stage: MiddlewareStage;
+    reason?: string;
+    middleware?: string;
+    messageId?: string;
+    namespace?: string;
+}
+
+declare class CancelError extends Error {
+    readonly details: CancelDetails;
+    constructor(details: CancelDetails);
+}
+
+type PipelineResult = {
+    cancelled: boolean;
+    cancelledBy?: string;
+    reason?: string;
+};
+
+interface PostboyMessageContext {
+    correlationId: string;
+    currentMessageId: string;
+    parentMessageId?: string;
+    depth: number;
+    startedAt: Date;
+    tags?: Set<string>;
 }
 
 /**
@@ -282,6 +290,56 @@ declare class PostboySubscription<T> {
     finish(): void;
 }
 
+/**
+ * Abstract base class for defining middleware in a pipeline.
+ * Middleware acts on various stages of pipeline execution, allowing operations
+ * to be intercepted, modified, or monitored.
+ */
+declare abstract class PostboyMiddleware {
+    readonly name: string;
+    /**
+     * Creates an instance of a class, optionally assigning a name.
+     *
+     * @param {string} [name] - An optional name to be assigned. If not provided, defaults to the class name.
+     */
+    constructor(name?: string);
+    /**
+     * Optional filter to skip middleware for unrelated messages/stages.
+     */
+    canHandle(_context: PipelineContext): boolean;
+    /**
+     * Called before the stage is executed.
+     * Return Interrupt to cancel the operation.
+     */
+    before(_context: PipelineContext): MiddlewareDecision;
+    /**
+     * Called after the stage has finished successfully.
+     * `result` is typically set for execute-stage.
+     */
+    after(_context: PipelineContext, _result?: unknown): void;
+    /**
+     * Optional cleanup hook.
+     */
+    dispose(): void;
+}
+
+declare class PostboyMiddlewareService {
+    protected middlewares: PostboyMiddleware[];
+    addMiddleware(middleware: PostboyMiddleware): void;
+    removeMiddleware(middleware: PostboyMiddleware): void;
+    dispose(): void;
+    before<T extends PostboyMessage>(stage: MiddlewareStage, message: T): void;
+    after<T extends PostboyMessage, R = unknown>(stage: MiddlewareStage, message: T, result?: R): void;
+    beforePublish(message: PostboyMessage): void;
+    afterPublish(message: PostboyMessage): void;
+    beforeCallback(message: PostboyMessage): void;
+    afterCallback(message: PostboyMessage, result?: unknown): void;
+    beforeExecute<T>(message: PostboyExecutor<T>): void;
+    afterExecute<T>(message: PostboyExecutor<T>, result: T): void;
+    private buildContext;
+    private throwIfCancelled;
+}
+
 /**
  * The PostboyMessageStore is a utility class for managing message subscriptions and executors.
  * It provides functionality to register, retrieve, and unregister subscription-based messages and executors.
@@ -368,46 +426,6 @@ declare class PostboyService {
     private dependencyResolver;
     constructor(resolver?: PostboyDependencyResolver);
     private registerInfrastructureMessages;
-    /**
-     * Locks a specific message type to prevent further modifications or actions.
-     *
-     * @deprecated The method should be replaced with firing {@link LockMessage} message.
-     * @param {MessageType<T>} type - The message type to be locked. It must extend from the `PostboyGenericMessage`.
-     * @return {void} This method does not return a value.
-     */
-    lock<T extends PostboyGenericMessage>(type: MessageType<T>): void;
-    /**
-     * Unlocks a previously locked message type by removing its ID from the locked set.
-     *
-     * @deprecated The method should be replaced with firing {@link UnlockMessage} message.
-     * @param {MessageType<T>} type - The message type to unlock, which is a generic type extending PostboyGenericMessage.
-     * @return {void} This method does not return any value.
-     */
-    unlock<T extends PostboyGenericMessage>(type: MessageType<T>): void;
-    /**
-     * Adds a middleware to the middleware stack.
-     *
-     * @deprecated The method should be replaced with firing {@link AddMiddleware} message.
-     * @param {PostboyMiddleware} middleware - The middleware instance to be added.
-     * @return {void}
-     */
-    addMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Removes a middleware from the current middleware stack.
-     *
-     * @deprecated The method should be replaced with firing {@link RemoveMiddleware} message.
-     * @param {PostboyMiddleware} middleware - The middleware instance to be removed.
-     * @return {void} No return value.
-     */
-    removeMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Unregisters a message identified by the given ID from the store.
-     *
-     * @deprecated The method should be replaced with firing {@link DisconnectMessage} message.
-     * @param {string} id - The unique identifier of the item to unregister.
-     * @return {void} No value is returned.
-     */
-    unregister(id: string): void;
     /**
      * Fires a registered event and passes the message to its subscribers.
      *
@@ -484,22 +502,6 @@ declare class PostboyService {
      * @return void
      */
     recordHandler<E extends PostboyExecutor<R>, R>(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>): void;
-    /**
-     * Adds a namespace to the namespace store.
-     *
-     * @deprecated The method should be replaced with firing {@link AddNamespace} message.
-     * @param {string} space - The name of the namespace to be added.
-     * @return {PostboyAbstractRegistrator} The instance of the namespace after adding the specified namespace.
-     */
-    addNamespace(space: string): PostboyAbstractRegistrator;
-    /**
-     * Removes the specified namespace from the namespace store.
-     *
-     * @deprecated The method should be replaced with firing {@link EliminateNamespace} message.
-     * @param {string} space - The name of the namespace to be removed.
-     * @return {void} This method does not return a value.
-     */
-    eliminateNamespace(space: string): void;
     /**
      * Disposes of resources and cleans up any internal components or stores associated with the instance.
      * This method ensures that all resources are properly released to avoid memory leaks.
@@ -698,4 +700,4 @@ declare class ConnectMessage<T extends PostboyGenericMessage> extends PostboyExe
     constructor(type: MessageType<T>, sub: Subject<T>, pipe?: ((s: Subject<T>) => Observable<T>) | undefined);
 }
 
-export { AddMiddleware, AddNamespace, ConnectExecutor, ConnectHandler, ConnectMessage, DisconnectMessage, EliminateNamespace, type IPostboyDependingService, LockMessage, type MessageType, PostboyAbstractRegistrator, PostboyCallbackMessage, PostboyExecutionHandler, PostboyExecutor, PostboyGenericMessage, PostboyMessage, PostboyMessageStore, type PostboyMiddleware, PostboyMiddlewareService, PostboyNamespaceStore, PostboyService, PostboySubscription, RemoveMiddleware, UnlockMessage, checkId };
+export { AddMiddleware, AddNamespace, type CancelDetails, CancelError, ConnectExecutor, ConnectHandler, ConnectMessage, DisconnectMessage, EliminateNamespace, type IPostboyDependingService, LockMessage, type MessageType, type MiddlewareDecision, MiddlewareDecisionType, MiddlewareStage, type PipelineContext, type PipelineResult, PostboyAbstractRegistrator, PostboyCallbackMessage, PostboyExecutionHandler, PostboyExecutor, PostboyGenericMessage, PostboyMessage, type PostboyMessageContext, type PostboyMessageMetadata, PostboyMessageStore, PostboyMiddleware, PostboyMiddlewareService, PostboyNamespaceStore, PostboyService, PostboySubscription, RemoveMiddleware, UnlockMessage };

package/lib/index.d.ts

@@ -37,7 +37,6 @@ declare abstract class PostboyMessage {
  */
 declare abstract class PostboyGenericMessage extends PostboyMessage {
 }
-declare function checkId(message: new (...args: any[]) => any): string;
 
 declare abstract class PostboyExecutor<T> extends PostboyMessage {
     protected readonly _postboyResultType?: T;
@@ -205,43 +204,52 @@ declare abstract class PostboyAbstractRegistrator {
     recordSubject<T extends PostboyGenericMessage>(type: MessageType<T>): this;
 }
 
-interface PostboyMiddleware {
-    handle(message: PostboyMessage): void;
+declare enum MiddlewareStage {
+    Publish = 1,
+    Callback = 2,
+    Execute = 3
 }
 
-/**
- * A service class that manages middleware functions for processing PostboyMessage objects.
- * It provides methods to add, remove, and execute middlewares in sequence.
- */
-declare class PostboyMiddlewareService {
-    protected middlewares: PostboyMiddleware[];
-    /**
-     * Adds a middleware function to the collection of middlewares.
-     *
-     * @param {PostboyMiddleware} middleware - The middleware function to be added.
-     * @return {void}
-     */
-    addMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Removes a middleware from the list of registered middlewares.
-     *
-     * @param {PostboyMiddleware} middleware - The middleware instance to be removed.
-     * @return {void} No return value.
-     */
-    removeMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Manages the processing of a PostboyMessage by sequentially applying all middlewares.
-     *
-     * @param {PostboyMessage} msg - The message object to be processed by the middlewares.
-     * @return {void} - This method does not return any value.
-     */
-    manage(msg: PostboyMessage): void;
-    /**
-     * Disposes of the current object by clearing its middlewares array.
-     *
-     * @return {void} This method does not return a value.
-     */
-    dispose(): void;
+interface PipelineContext<T extends PostboyMessage = PostboyMessage> {
+    stage: MiddlewareStage;
+    message: T;
+}
+
+declare enum MiddlewareDecisionType {
+    Continue = 1,
+    Interrupt = 2
+}
+
+interface MiddlewareDecision {
+    type: MiddlewareDecisionType;
+}
+
+interface CancelDetails {
+    stage: MiddlewareStage;
+    reason?: string;
+    middleware?: string;
+    messageId?: string;
+    namespace?: string;
+}
+
+declare class CancelError extends Error {
+    readonly details: CancelDetails;
+    constructor(details: CancelDetails);
+}
+
+type PipelineResult = {
+    cancelled: boolean;
+    cancelledBy?: string;
+    reason?: string;
+};
+
+interface PostboyMessageContext {
+    correlationId: string;
+    currentMessageId: string;
+    parentMessageId?: string;
+    depth: number;
+    startedAt: Date;
+    tags?: Set<string>;
 }
 
 /**
@@ -282,6 +290,56 @@ declare class PostboySubscription<T> {
     finish(): void;
 }
 
+/**
+ * Abstract base class for defining middleware in a pipeline.
+ * Middleware acts on various stages of pipeline execution, allowing operations
+ * to be intercepted, modified, or monitored.
+ */
+declare abstract class PostboyMiddleware {
+    readonly name: string;
+    /**
+     * Creates an instance of a class, optionally assigning a name.
+     *
+     * @param {string} [name] - An optional name to be assigned. If not provided, defaults to the class name.
+     */
+    constructor(name?: string);
+    /**
+     * Optional filter to skip middleware for unrelated messages/stages.
+     */
+    canHandle(_context: PipelineContext): boolean;
+    /**
+     * Called before the stage is executed.
+     * Return Interrupt to cancel the operation.
+     */
+    before(_context: PipelineContext): MiddlewareDecision;
+    /**
+     * Called after the stage has finished successfully.
+     * `result` is typically set for execute-stage.
+     */
+    after(_context: PipelineContext, _result?: unknown): void;
+    /**
+     * Optional cleanup hook.
+     */
+    dispose(): void;
+}
+
+declare class PostboyMiddlewareService {
+    protected middlewares: PostboyMiddleware[];
+    addMiddleware(middleware: PostboyMiddleware): void;
+    removeMiddleware(middleware: PostboyMiddleware): void;
+    dispose(): void;
+    before<T extends PostboyMessage>(stage: MiddlewareStage, message: T): void;
+    after<T extends PostboyMessage, R = unknown>(stage: MiddlewareStage, message: T, result?: R): void;
+    beforePublish(message: PostboyMessage): void;
+    afterPublish(message: PostboyMessage): void;
+    beforeCallback(message: PostboyMessage): void;
+    afterCallback(message: PostboyMessage, result?: unknown): void;
+    beforeExecute<T>(message: PostboyExecutor<T>): void;
+    afterExecute<T>(message: PostboyExecutor<T>, result: T): void;
+    private buildContext;
+    private throwIfCancelled;
+}
+
 /**
  * The PostboyMessageStore is a utility class for managing message subscriptions and executors.
  * It provides functionality to register, retrieve, and unregister subscription-based messages and executors.
@@ -368,46 +426,6 @@ declare class PostboyService {
     private dependencyResolver;
     constructor(resolver?: PostboyDependencyResolver);
     private registerInfrastructureMessages;
-    /**
-     * Locks a specific message type to prevent further modifications or actions.
-     *
-     * @deprecated The method should be replaced with firing {@link LockMessage} message.
-     * @param {MessageType<T>} type - The message type to be locked. It must extend from the `PostboyGenericMessage`.
-     * @return {void} This method does not return a value.
-     */
-    lock<T extends PostboyGenericMessage>(type: MessageType<T>): void;
-    /**
-     * Unlocks a previously locked message type by removing its ID from the locked set.
-     *
-     * @deprecated The method should be replaced with firing {@link UnlockMessage} message.
-     * @param {MessageType<T>} type - The message type to unlock, which is a generic type extending PostboyGenericMessage.
-     * @return {void} This method does not return any value.
-     */
-    unlock<T extends PostboyGenericMessage>(type: MessageType<T>): void;
-    /**
-     * Adds a middleware to the middleware stack.
-     *
-     * @deprecated The method should be replaced with firing {@link AddMiddleware} message.
-     * @param {PostboyMiddleware} middleware - The middleware instance to be added.
-     * @return {void}
-     */
-    addMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Removes a middleware from the current middleware stack.
-     *
-     * @deprecated The method should be replaced with firing {@link RemoveMiddleware} message.
-     * @param {PostboyMiddleware} middleware - The middleware instance to be removed.
-     * @return {void} No return value.
-     */
-    removeMiddleware(middleware: PostboyMiddleware): void;
-    /**
-     * Unregisters a message identified by the given ID from the store.
-     *
-     * @deprecated The method should be replaced with firing {@link DisconnectMessage} message.
-     * @param {string} id - The unique identifier of the item to unregister.
-     * @return {void} No value is returned.
-     */
-    unregister(id: string): void;
     /**
      * Fires a registered event and passes the message to its subscribers.
      *
@@ -484,22 +502,6 @@ declare class PostboyService {
      * @return void
      */
     recordHandler<E extends PostboyExecutor<R>, R>(executor: new (...args: any[]) => E, handler: PostboyExecutionHandler<R, E>): void;
-    /**
-     * Adds a namespace to the namespace store.
-     *
-     * @deprecated The method should be replaced with firing {@link AddNamespace} message.
-     * @param {string} space - The name of the namespace to be added.
-     * @return {PostboyAbstractRegistrator} The instance of the namespace after adding the specified namespace.
-     */
-    addNamespace(space: string): PostboyAbstractRegistrator;
-    /**
-     * Removes the specified namespace from the namespace store.
-     *
-     * @deprecated The method should be replaced with firing {@link EliminateNamespace} message.
-     * @param {string} space - The name of the namespace to be removed.
-     * @return {void} This method does not return a value.
-     */
-    eliminateNamespace(space: string): void;
     /**
      * Disposes of resources and cleans up any internal components or stores associated with the instance.
      * This method ensures that all resources are properly released to avoid memory leaks.
@@ -698,4 +700,4 @@ declare class ConnectMessage<T extends PostboyGenericMessage> extends PostboyExe
     constructor(type: MessageType<T>, sub: Subject<T>, pipe?: ((s: Subject<T>) => Observable<T>) | undefined);
 }
 
-export { AddMiddleware, AddNamespace, ConnectExecutor, ConnectHandler, ConnectMessage, DisconnectMessage, EliminateNamespace, type IPostboyDependingService, LockMessage, type MessageType, PostboyAbstractRegistrator, PostboyCallbackMessage, PostboyExecutionHandler, PostboyExecutor, PostboyGenericMessage, PostboyMessage, PostboyMessageStore, type PostboyMiddleware, PostboyMiddlewareService, PostboyNamespaceStore, PostboyService, PostboySubscription, RemoveMiddleware, UnlockMessage, checkId };
+export { AddMiddleware, AddNamespace, type CancelDetails, CancelError, ConnectExecutor, ConnectHandler, ConnectMessage, DisconnectMessage, EliminateNamespace, type IPostboyDependingService, LockMessage, type MessageType, type MiddlewareDecision, MiddlewareDecisionType, MiddlewareStage, type PipelineContext, type PipelineResult, PostboyAbstractRegistrator, PostboyCallbackMessage, PostboyExecutionHandler, PostboyExecutor, PostboyGenericMessage, PostboyMessage, type PostboyMessageContext, type PostboyMessageMetadata, PostboyMessageStore, PostboyMiddleware, PostboyMiddlewareService, PostboyNamespaceStore, PostboyService, PostboySubscription, RemoveMiddleware, UnlockMessage };