@stackra/pipeline 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,447 @@
+import { DynamicModule, IApplication } from '@stackra/contracts';
+
+/**
+ * @file pipeline.module.ts
+ * @module @stackra/pipeline
+ * @description DI module for the pipeline system.
+ *   Registers the PipelineHub as a global singleton and provides a
+ *   PIPELINE_FACTORY token for creating fresh Pipeline instances on demand.
+ *
+ *   The Pipeline class itself is NOT a singleton — each usage creates a new
+ *   instance via the factory. This ensures no state leaks between usages.
+ */
+
+/**
+ * Pipeline DI module.
+ *
+ * Provides:
+ * - `PipelineHub` — global singleton for named pipeline presets
+ * - `PIPELINE_FACTORY` — factory function for creating fresh Pipeline instances
+ *
+ * The Pipeline is intentionally NOT registered as a singleton. Each call to
+ * the factory produces a new instance with clean state. This mirrors Laravel's
+ * pattern where `app(Pipeline::class)` always returns a fresh pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { PipelineModule } from '@stackra/pipeline';
+ *
+ * @Module({
+ *   imports: [PipelineModule.forRoot()],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Injecting the factory in a service
+ * @Injectable()
+ * class OrderService {
+ *   constructor(
+ *     @Inject(PIPELINE_FACTORY) private readonly createPipeline: PipelineFactory,
+ *   ) {}
+ *
+ *   processOrder(order: Order): Order {
+ *     return this.createPipeline<Order>()
+ *       .send(order)
+ *       .through([ValidateOrder, CalculateTax, ApplyDiscount])
+ *       .thenReturn();
+ *   }
+ * }
+ * ```
+ */
+declare class PipelineModule {
+    /**
+     * Register the pipeline module globally.
+     *
+     * @returns Dynamic module definition with PipelineHub and factory
+     */
+    static forRoot(): DynamicModule;
+}
+
+/**
+ * @file pipeline-options.interface.ts
+ * @module @stackra/pipeline/interfaces
+ * @description Internal pipeline configuration interfaces.
+ *   Defines the types used for pipe resolution and pipeline definition callbacks.
+ */
+/**
+ * Function pipe — a closure that receives the passable and a next callback.
+ *
+ * @typeParam TPassable - The type of value flowing through the pipeline
+ * @typeParam TReturn - The return type of the pipeline
+ */
+type PipeClosure<TPassable = unknown, TReturn = unknown> = (passable: TPassable, next: (passable: TPassable) => TReturn) => TReturn;
+/**
+ * Tuple pipe — a class reference (or string) paired with additional parameters.
+ * Equivalent to Laravel's `'ClassName:param1,param2'` syntax.
+ *
+ * The first element is the pipe (class or string), and subsequent elements
+ * are parameters passed to the pipe's handler method after `passable` and `next`.
+ */
+type PipeTuple = [pipe: PipeEntry, ...params: unknown[]];
+/**
+ * A single pipe entry (without parameters).
+ * Can be a closure, a string for container resolution, or an object instance.
+ */
+type PipeEntry = PipeClosure | string | object;
+/**
+ * Union of all supported pipe types.
+ *
+ * - `PipeClosure` — function `(passable, next) => result`
+ * - `string` — class name resolved from DI container
+ * - `object` — pipe instance with a handler method (default: `handle`)
+ * - `PipeTuple` — `[pipe, ...params]` for parameterized pipes
+ */
+type PipeType = PipeClosure | string | object | PipeTuple;
+/**
+ * Pipeline definition callback used by the Hub.
+ *
+ * Receives a fresh Pipeline instance and the passable, configures the pipeline,
+ * and returns the result.
+ */
+type PipelineDefinition = (pipeline: unknown, passable: unknown) => unknown;
+
+/**
+ * @file pipeline.service.ts
+ * @module @stackra/pipeline/services
+ * @description Laravel-style middleware Pipeline with fluent API and DI container integration.
+ *   Implements the classic array_reduce(reverse(pipes), carry(), destination) pattern
+ *   for composing middleware chains with type safety.
+ */
+
+/**
+ * Laravel-style middleware pipeline with fluent API.
+ *
+ * Composes a chain of pipes (middleware) that process a passable value
+ * sequentially. Each pipe can inspect, modify, or short-circuit the passable
+ * before passing it to the next pipe in the chain.
+ *
+ * The pipeline supports four pipe types:
+ * - **Closure** — `(passable, next) => result`
+ * - **String** — resolved from the DI container by name
+ * - **Object** — instance with a handler method (default: `handle`)
+ * - **Tuple** — `[pipe, ...params]` for parameterized pipes
+ *
+ * Core algorithm (mirrors Laravel):
+ * ```
+ * pipeline = array_reduce(reverse(pipes), carry(), prepareDestination(destination))
+ * return pipeline(passable)
+ * ```
+ *
+ * @typeParam TPassable - The type of value flowing through the pipeline
+ * @typeParam TReturn - The type returned by the pipeline's `then()` method
+ *
+ * @example
+ * ```typescript
+ * const result = new Pipeline<Request, Response>(container)
+ *   .send(request)
+ *   .through([AuthMiddleware, LoggingMiddleware])
+ *   .then((req) => handleRequest(req));
+ * ```
+ */
+declare class Pipeline<TPassable = unknown, TReturn = TPassable> {
+    /** The value flowing through the pipeline. */
+    private passable;
+    /** The ordered list of pipes to execute. */
+    private pipes;
+    /** The method name to call on pipe objects. */
+    private method;
+    /** Optional callback invoked after pipeline execution. */
+    private finallyCallback?;
+    /** Optional DI container for resolving string pipes. */
+    private readonly container?;
+    /**
+     * @param container - Optional application context for resolving string-based pipes.
+     *   When provided, string pipes are resolved via `container.get(pipeName)`.
+     *   When omitted, string pipes will throw a PipelineError.
+     */
+    constructor(container?: IApplication);
+    /**
+     * Set the passable object being sent through the pipeline.
+     *
+     * @param passable - The value to send through the pipes
+     * @returns This pipeline instance for chaining
+     */
+    send(passable: TPassable): this;
+    /**
+     * Set the array of pipes (replaces any existing pipes).
+     *
+     * @param pipes - Array of pipe definitions to process the passable through
+     * @returns This pipeline instance for chaining
+     */
+    through(pipes: PipeType[]): this;
+    /**
+     * Append additional pipes to the pipeline.
+     *
+     * Unlike `through()` which replaces all pipes, `pipe()` adds to the
+     * existing chain. Useful for conditionally extending a pipeline.
+     *
+     * @param pipes - One or more pipe definitions to append
+     * @returns This pipeline instance for chaining
+     */
+    pipe(...pipes: PipeType[]): this;
+    /**
+     * Change the handler method name called on pipe objects.
+     *
+     * By default, the pipeline calls `handle(passable, next)` on pipe objects.
+     * Use `via()` to call a different method (e.g., `process`, `transform`).
+     *
+     * @param method - The method name to invoke on pipe objects
+     * @returns This pipeline instance for chaining
+     */
+    via(method: string): this;
+    /**
+     * Register a finally callback invoked after pipeline execution.
+     *
+     * The callback receives the passable after all pipes and the destination
+     * have processed it. Useful for cleanup, logging, or telemetry.
+     *
+     * @param callback - Function to call with the passable after execution
+     * @returns This pipeline instance for chaining
+     */
+    finally(callback: (passable: TPassable) => void): this;
+    /**
+     * Execute the pipeline with a final destination closure.
+     *
+     * The destination is the innermost function — it receives the passable
+     * after all pipes have processed it. The pipeline is built using
+     * `reduceRight` (equivalent to Laravel's `array_reduce(array_reverse(...))`).
+     *
+     * @typeParam R - The return type of the destination
+     * @param destination - Final handler that produces the pipeline's return value
+     * @returns The result of the destination function
+     * @throws {PipelineError} When a pipe cannot be resolved or executed
+     */
+    then<R = TReturn>(destination: (passable: TPassable) => R): R;
+    /**
+     * Execute the pipeline and return the passable as-is.
+     *
+     * Equivalent to `then((passable) => passable)`. Useful when the pipeline
+     * transforms the passable in place and no final destination is needed.
+     *
+     * @returns The passable after all pipes have processed it
+     */
+    thenReturn(): TPassable;
+    /**
+     * Wrap the destination in a closure matching the pipeline's signature.
+     *
+     * @param destination - The final handler
+     * @returns A closure compatible with the reduce chain
+     */
+    private prepareDestination;
+    /**
+     * Invoke a single pipe with the passable and next callback.
+     *
+     * Resolves the pipe type and delegates to the appropriate handler:
+     * - Function → called directly
+     * - String → resolved from container, method called
+     * - Array (tuple) → first element resolved, rest are params
+     * - Object → method called directly
+     *
+     * @param pipe - The pipe to invoke
+     * @param passable - The current passable value
+     * @param next - The next function in the chain
+     * @returns The result of invoking the pipe
+     * @throws {PipelineError} When the pipe cannot be resolved or invoked
+     */
+    private carry;
+    /**
+     * Handle a tuple pipe by extracting the pipe and its parameters.
+     *
+     * @param tuple - The [pipe, ...params] tuple
+     * @param passable - The current passable
+     * @param next - The next function
+     * @returns The result of invoking the pipe
+     */
+    private handleTuplePipe;
+    /**
+     * Resolve a string pipe from the container and invoke its handler method.
+     *
+     * @param name - The service name/token to resolve
+     * @param passable - The current passable
+     * @param next - The next function
+     * @param params - Additional parameters to pass to the handler
+     * @returns The result of invoking the resolved pipe
+     * @throws {PipelineError} When no container is available or resolution fails
+     */
+    private handleStringPipe;
+    /**
+     * Invoke a handler method on a pipe object instance.
+     *
+     * @param pipe - The pipe object instance
+     * @param passable - The current passable
+     * @param next - The next function
+     * @param params - Additional parameters to pass after passable and next
+     * @returns The result of invoking the method
+     * @throws {PipelineError} When the method does not exist on the pipe
+     */
+    private handleObjectPipe;
+}
+
+/**
+ * @file pipeline-hub.service.ts
+ * @module @stackra/pipeline/services
+ * @description Named pipeline presets registry (Hub).
+ *   Allows registering named pipeline definitions and executing them by name.
+ *   Equivalent to Laravel's Pipeline Hub concept for reusable pipeline configurations.
+ */
+
+/**
+ * Named pipeline presets registry.
+ *
+ * The Hub stores named pipeline definitions that can be executed by name.
+ * This enables reusable pipeline configurations that multiple consumers
+ * can invoke without knowing the pipe chain details.
+ *
+ * A `defaults` pipeline is used as the fallback when no specific pipeline
+ * name is provided to `pipe()`.
+ *
+ * @example
+ * ```typescript
+ * const hub = new PipelineHub(container);
+ *
+ * hub.pipeline('order-validation', (pipeline, passable) =>
+ *   pipeline
+ *     .send(passable)
+ *     .through([ValidateStock, ValidatePayment, ValidateAddress])
+ *     .thenReturn()
+ * );
+ *
+ * const result = hub.pipe(orderData, 'order-validation');
+ * ```
+ */
+declare class PipelineHub {
+    /** Registry of named pipeline definitions. */
+    private readonly pipelines;
+    /** Default pipeline definition (fallback when no name specified). */
+    private defaultPipeline?;
+    /** Optional DI container for creating Pipeline instances. */
+    private readonly container?;
+    /**
+     * @param container - Optional application context passed to created Pipeline instances
+     */
+    constructor(container?: IApplication);
+    /**
+     * Register the default pipeline definition.
+     *
+     * The default pipeline is used when `pipe()` is called without a name.
+     *
+     * @param callback - Pipeline definition that configures and executes a pipeline
+     */
+    defaults(callback: PipelineDefinition): void;
+    /**
+     * Register a named pipeline definition.
+     *
+     * @param name - Unique name for this pipeline preset
+     * @param callback - Pipeline definition that configures and executes a pipeline
+     * @throws {PipelineError} When the name is empty
+     */
+    pipeline(name: string, callback: PipelineDefinition): void;
+    /**
+     * Execute a named (or default) pipeline with the given passable.
+     *
+     * Creates a fresh Pipeline instance, passes it along with the passable
+     * to the registered definition, and returns the result.
+     *
+     * @typeParam T - The type of the passable value
+     * @param passable - The value to send through the pipeline
+     * @param pipelineName - Optional name of the pipeline preset to execute.
+     *   Falls back to the default pipeline if omitted.
+     * @returns The result of the pipeline execution
+     * @throws {PipelineError} When the named pipeline or default is not registered
+     */
+    pipe<T>(passable: T, pipelineName?: string): unknown;
+    /**
+     * Check if a named pipeline definition exists in the registry.
+     *
+     * @param name - The pipeline name to check
+     * @returns True if the pipeline is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Resolve a pipeline definition by name or fall back to the default.
+     *
+     * @param name - Optional pipeline name
+     * @returns The resolved pipeline definition
+     * @throws {PipelineError} When the definition cannot be found
+     */
+    private resolveDefinition;
+}
+
+/**
+ * @file pipeline.constant.ts
+ * @module @stackra/pipeline/constants
+ * @description DI tokens and constants for the pipeline module.
+ */
+/**
+ * DI token for the pipeline factory function.
+ *
+ * Inject this token to obtain a factory that creates fresh Pipeline instances.
+ * Each call to the factory produces a new Pipeline with no residual state.
+ *
+ * @example
+ * ```typescript
+ * @Inject(PIPELINE_FACTORY) private readonly createPipeline: PipelineFactory
+ * ```
+ */
+declare const PIPELINE_FACTORY: unique symbol;
+
+/**
+ * @file pipeline-factory.type.ts
+ * @module @stackra/pipeline/types
+ * @description PipelineFactory type.
+ */
+/**
+ * Factory function type for creating fresh Pipeline instances.
+ *
+ * Returns a new Pipeline typed with the specified passable type.
+ * The factory encapsulates container injection so consumers don't need
+ * to manage container references.
+ *
+ * @typeParam T - The passable type for the created pipeline
+ */
+type PipelineFactory = <T = unknown>() => Pipeline<T>;
+
+/**
+ * @file pipeline.error.ts
+ * @module @stackra/pipeline/errors
+ * @description Pipeline-specific error class for all pipeline operation failures.
+ *   Thrown when a pipe cannot be resolved, the pipeline is misconfigured,
+ *   or a pipe throws during execution.
+ */
+/**
+ * Error thrown when a pipeline operation fails.
+ *
+ * Covers scenarios such as:
+ * - Pipe resolution failure (string pipe not found in container)
+ * - Invalid pipe type provided
+ * - Pipeline method not found on a pipe object
+ * - Pipe execution failure (wrapped original error)
+ *
+ * @example
+ * ```typescript
+ * throw new PipelineError(
+ *   'Pipe "ValidateInput" could not be resolved from the container.',
+ *   'PIPE_RESOLUTION_FAILED',
+ * );
+ * ```
+ */
+declare class PipelineError extends Error {
+    /**
+     * Machine-readable error code for programmatic handling.
+     */
+    readonly code: string;
+    /**
+     * The original error that caused this pipeline error, if any.
+     */
+    readonly cause?: Error;
+    /**
+     * @param message - Human-readable description of what went wrong
+     * @param code - Machine-readable error code
+     * @param cause - The original error that triggered this pipeline error
+     */
+    constructor(message: string, code?: string, cause?: Error);
+}
+
+export { PIPELINE_FACTORY, type PipeClosure, type PipeEntry, type PipeTuple, type PipeType, Pipeline, type PipelineDefinition, PipelineError, type PipelineFactory, PipelineHub, PipelineModule };