@zdavison/matador 2.0.9 → 2.0.11

package/{src/core/index.ts → dist/core/index.d.ts}

@@ -1,12 +1,7 @@
 export type { SendError, SendResult, FanoutConfig } from './fanout.js';
 export { FanoutEngine } from './fanout.js';
-
-export type {
-  HandlersState,
-  ShutdownConfig,
-  ShutdownState,
-} from './shutdown.js';
+export type { HandlersState, ShutdownConfig, ShutdownState, } from './shutdown.js';
 export { defaultShutdownConfig, ShutdownManager } from './shutdown.js';
-
 export type { MatadorConfig } from './matador.js';
 export { Matador } from './matador.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEvE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { FanoutEngine } from './fanout.js';
+export { defaultShutdownConfig, ShutdownManager } from './shutdown.js';
+export { Matador } from './matador.js';

package/dist/core/matador.d.ts

@@ -0,0 +1,133 @@
+import type { CheckpointStore } from '../checkpoint/index.js';
+import type { Codec } from '../codec/index.js';
+import type { MatadorHooks } from '../hooks/index.js';
+import type { RetryPolicy } from '../retry/index.js';
+import type { MatadorSchema } from '../schema/index.js';
+import type { Topology } from '../topology/index.js';
+import type { Transport } from '../transport/index.js';
+import type { AnySubscriber, Dispatcher, Event, EventClass, EventOptions } from '../types/index.js';
+import type { SendResult } from './fanout.js';
+import type { HandlersState, ShutdownConfig } from './shutdown.js';
+/**
+ * Configuration for Matador.
+ */
+export interface MatadorConfig {
+    /** Transport for message delivery */
+    readonly transport: Transport;
+    /** Topology configuration */
+    readonly topology: Topology;
+    /** Event schema mapping event keys to event classes and subscribers */
+    readonly schema: MatadorSchema;
+    /** Queues to consume from (empty = no consumption) */
+    readonly consumeFrom?: readonly string[] | undefined;
+    /** Custom codec (defaults to JSON) */
+    readonly codec?: Codec | undefined;
+    /** Custom retry policy */
+    readonly retryPolicy?: RetryPolicy | undefined;
+    /** Shutdown configuration */
+    readonly shutdownConfig?: Partial<ShutdownConfig> | undefined;
+    /**
+     * Checkpoint store for resumable subscribers.
+     * Required for persisting io() results across retries.
+     * If not provided, resumable subscribers will work but checkpoints
+     * won't persist across retries.
+     */
+    readonly checkpointStore?: CheckpointStore | undefined;
+}
+/**
+ * Matador - Transport-agnostic event processing library.
+ *
+ * Main orchestrator that wires together:
+ * - Transport: Message delivery
+ * - Schema: Event-subscriber registry
+ * - Pipeline: Message processing
+ * - Fanout: Event sending
+ * - Shutdown: Graceful termination
+ */
+export declare class Matador implements Dispatcher {
+    private readonly transport;
+    private readonly topology;
+    private readonly schema;
+    private readonly codec;
+    private readonly retryPolicy;
+    private readonly hooks;
+    private readonly pipeline;
+    private readonly fanout;
+    private readonly shutdownManager;
+    private readonly consumeFrom;
+    private readonly subscriptions;
+    private started;
+    /**
+     * Creates a new Matador instance.
+     *
+     * @param config - Static configuration (transport, topology, schema, etc.)
+     * @param hooks - Lifecycle hooks for logging, monitoring, and dynamic configuration.
+     *                Passed separately to support NestJS dependency injection.
+     */
+    constructor(config: MatadorConfig, hooks?: MatadorHooks);
+    /**
+     * Registers an event class with its subscribers.
+     */
+    register<T>(eventClass: EventClass<T>, subscribers: readonly AnySubscriber[]): this;
+    /**
+     * Registers events from a schema object.
+     * Supports both object format and tuple format entries.
+     *
+     * @example
+     * ```typescript
+     * // Tuple format
+     * matador.registerSchema({
+     *   [UserCreatedEvent.key]: [UserCreatedEvent, [emailSubscriber]],
+     *   [OrderPlacedEvent.key]: [OrderPlacedEvent, [invoiceSubscriber]],
+     * });
+     *
+     * // Object format
+     * matador.registerSchema({
+     *   [UserCreatedEvent.key]: { eventClass: UserCreatedEvent, subscribers: [emailSubscriber] },
+     * });
+     * ```
+     */
+    registerSchema(schema: MatadorSchema): this;
+    /**
+     * Starts Matador - connects transport and begins consuming.
+     * This method is idempotent - calling it multiple times is safe.
+     */
+    start(): Promise<void>;
+    /**
+     * Sends an event to all registered subscribers.
+     *
+     * @example
+     * ```typescript
+     * // Pass the event class and data directly
+     * await matador.send(UserCreatedEvent, { userId: '123' });
+     *
+     * // Or pass an event instance
+     * const event = new UserCreatedEvent({ userId: '123' });
+     * await matador.send(event);
+     * ```
+     */
+    send<T>(eventClass: EventClass<T>, data: T, options?: EventOptions): Promise<SendResult>;
+    send<T>(event: Event<T>, options?: EventOptions): Promise<SendResult>;
+    /**
+     * Gets current handler state.
+     */
+    getHandlersState(): HandlersState;
+    /**
+     * Checks if Matador is idle (no processing or enqueuing).
+     */
+    isIdle(): boolean;
+    /**
+     * Waits for all handlers to become idle.
+     */
+    waitForIdle(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Gracefully shuts down Matador.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Checks if transport is connected.
+     */
+    isConnected(): boolean;
+    private stopReceiving;
+}
+//# sourceMappingURL=matador.d.ts.map

package/dist/core/matador.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matador.d.ts","sourceRoot":"","sources":["../../src/core/matador.ts"],"names":[],"mappings":"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"}

package/dist/core/matador.js

@@ -0,0 +1,228 @@
+import { JsonCodec } from '../codec/index.js';
+import { InvalidSchemaError, NotStartedError, ShutdownInProgressError, } from '../errors/index.js';
+import { SafeHooks } from '../hooks/index.js';
+import { ProcessingPipeline } from '../pipeline/index.js';
+import { StandardRetryPolicy } from '../retry/index.js';
+import { SchemaRegistry, isSchemaEntryTuple } from '../schema/index.js';
+import { getQualifiedQueueName } from '../topology/index.js';
+import { FanoutEngine } from './fanout.js';
+import { ShutdownManager } from './shutdown.js';
+/**
+ * Matador - Transport-agnostic event processing library.
+ *
+ * Main orchestrator that wires together:
+ * - Transport: Message delivery
+ * - Schema: Event-subscriber registry
+ * - Pipeline: Message processing
+ * - Fanout: Event sending
+ * - Shutdown: Graceful termination
+ */
+export class Matador {
+    transport;
+    topology;
+    schema;
+    codec;
+    retryPolicy;
+    hooks;
+    pipeline;
+    fanout;
+    shutdownManager;
+    consumeFrom;
+    subscriptions = [];
+    started = false;
+    /**
+     * Creates a new Matador instance.
+     *
+     * @param config - Static configuration (transport, topology, schema, etc.)
+     * @param hooks - Lifecycle hooks for logging, monitoring, and dynamic configuration.
+     *                Passed separately to support NestJS dependency injection.
+     */
+    constructor(config, hooks) {
+        this.transport = config.transport;
+        this.topology = config.topology;
+        this.consumeFrom = config.consumeFrom ?? [];
+        // Initialize components
+        this.schema = new SchemaRegistry();
+        this.codec = config.codec ?? new JsonCodec();
+        this.retryPolicy = config.retryPolicy ?? new StandardRetryPolicy();
+        this.hooks = new SafeHooks(hooks);
+        // Register schema from config
+        this.registerSchema(config.schema);
+        // Create pipeline
+        this.pipeline = new ProcessingPipeline({
+            transport: this.transport,
+            schema: this.schema,
+            codec: this.codec,
+            retryPolicy: this.retryPolicy,
+            hooks: this.hooks,
+            checkpointStore: config.checkpointStore,
+            dispatcher: this,
+        });
+        // Create fanout engine
+        const defaultQueue = this.topology.queues[0]?.name ?? 'default';
+        this.fanout = new FanoutEngine({
+            transport: this.transport,
+            schema: this.schema,
+            hooks: this.hooks,
+            namespace: this.topology.namespace,
+            defaultQueue,
+        });
+        // Create shutdown manager
+        this.shutdownManager = new ShutdownManager(() => this.fanout.eventsBeingEnqueuedCount, () => this.stopReceiving(), () => this.transport.disconnect(), config.shutdownConfig);
+    }
+    /**
+     * Registers an event class with its subscribers.
+     */
+    register(eventClass, subscribers) {
+        this.schema.register(eventClass, subscribers);
+        return this;
+    }
+    /**
+     * Registers events from a schema object.
+     * Supports both object format and tuple format entries.
+     *
+     * @example
+     * ```typescript
+     * // Tuple format
+     * matador.registerSchema({
+     *   [UserCreatedEvent.key]: [UserCreatedEvent, [emailSubscriber]],
+     *   [OrderPlacedEvent.key]: [OrderPlacedEvent, [invoiceSubscriber]],
+     * });
+     *
+     * // Object format
+     * matador.registerSchema({
+     *   [UserCreatedEvent.key]: { eventClass: UserCreatedEvent, subscribers: [emailSubscriber] },
+     * });
+     * ```
+     */
+    registerSchema(schema) {
+        for (const entry of Object.values(schema)) {
+            if (isSchemaEntryTuple(entry)) {
+                // Tuple format: [EventClass, Subscriber[]]
+                const [eventClass, subscribers] = entry;
+                this.schema.register(eventClass, subscribers);
+            }
+            else {
+                // Object format: { eventClass, subscribers }
+                this.schema.register(entry.eventClass, entry.subscribers);
+            }
+        }
+        return this;
+    }
+    /**
+     * Starts Matador - connects transport and begins consuming.
+     * This method is idempotent - calling it multiple times is safe.
+     */
+    async start() {
+        // Idempotent: if already started, just return
+        if (this.started) {
+            return;
+        }
+        // Validate schema
+        const validation = this.schema.validate();
+        if (!validation.valid) {
+            const errors = validation.issues.filter((i) => i.severity === 'error');
+            throw new InvalidSchemaError('Schema validation failed', errors.map((e) => e.message).join(', '));
+        }
+        // Connect transport
+        this.hooks.logger.info(`[Matador] ⏳ Starting backend '${this.transport.name}'...`);
+        await this.transport.connect();
+        this.hooks.logger.info(`[Matador] 🟢 Backend '${this.transport.name}' started.`);
+        // Apply topology
+        await this.transport.applyTopology(this.topology);
+        // Subscribe to queues
+        if (this.consumeFrom.length > 0) {
+            this.hooks.logger.info(`[Matador] 🟢 Worker subscribing to '${this.consumeFrom.join(',')}'.`);
+        }
+        for (const queueName of this.consumeFrom) {
+            const qualifiedName = getQualifiedQueueName(this.topology.namespace, queueName);
+            const queueDef = this.topology.queues.find((q) => q.name === queueName);
+            const subscription = await this.transport.subscribe(qualifiedName, async (envelope, receipt) => {
+                this.shutdownManager.incrementProcessing();
+                try {
+                    const rawMessage = this.codec.encode(envelope);
+                    await this.pipeline.process(rawMessage, receipt);
+                }
+                finally {
+                    this.shutdownManager.decrementProcessing();
+                }
+            }, queueDef?.concurrency !== undefined
+                ? { concurrency: queueDef.concurrency }
+                : undefined);
+            this.subscriptions.push(subscription);
+        }
+        this.started = true;
+    }
+    async send(eventOrClass, dataOrOptions, maybeOptions) {
+        if (!this.started) {
+            throw new NotStartedError('send');
+        }
+        if (!this.shutdownManager.isEnqueueAllowed) {
+            throw new ShutdownInProgressError();
+        }
+        // Determine if first arg is an event instance or event class
+        const isEventClass = typeof eventOrClass === 'function' && 'key' in eventOrClass;
+        if (isEventClass) {
+            // Called as: send(EventClass, data, options?)
+            const eventClass = eventOrClass;
+            const data = dataOrOptions;
+            const options = maybeOptions;
+            const event = new eventClass(data);
+            return this.fanout.send(eventClass, event, options);
+        }
+        else {
+            // Called as: send(event, options?)
+            const event = eventOrClass;
+            const options = dataOrOptions;
+            const eventClass = event.constructor;
+            return this.fanout.send(eventClass, event, options);
+        }
+    }
+    /**
+     * Gets current handler state.
+     */
+    getHandlersState() {
+        return this.shutdownManager.getHandlersState();
+    }
+    /**
+     * Checks if Matador is idle (no processing or enqueuing).
+     */
+    isIdle() {
+        return this.shutdownManager.getHandlersState().isIdle;
+    }
+    /**
+     * Waits for all handlers to become idle.
+     */
+    async waitForIdle(timeoutMs = 30000) {
+        const deadline = Date.now() + timeoutMs;
+        while (!this.isIdle()) {
+            if (Date.now() > deadline) {
+                return false;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        return true;
+    }
+    /**
+     * Gracefully shuts down Matador.
+     */
+    async shutdown() {
+        if (!this.started) {
+            return;
+        }
+        await this.shutdownManager.shutdown();
+        this.started = false;
+    }
+    /**
+     * Checks if transport is connected.
+     */
+    isConnected() {
+        return this.transport.isConnected();
+    }
+    async stopReceiving() {
+        for (const subscription of this.subscriptions) {
+            await subscription.unsubscribe();
+        }
+        this.subscriptions.length = 0;
+    }
+}

package/dist/core/matador.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=matador.test.d.ts.map

package/dist/core/matador.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matador.test.d.ts","sourceRoot":"","sources":["../../src/core/matador.test.ts"],"names":[],"mappings":""}