@zdavison/matador 2.0.1

package/dist/types/subscriber.d.ts

@@ -0,0 +1,207 @@
+import type { SubscriberContext } from '../checkpoint/index.js';
+import type { Idempotency, Importance } from './common.js';
+import type { Envelope } from './envelope.js';
+import type { MatadorEvent } from './event.js';
+/**
+ * Helper type to get the envelope type for a subscriber callback.
+ * Extracts the data type from a MatadorEvent and wraps it in an Envelope.
+ *
+ * @example
+ * async callback(envelope: EnvelopeOf<MyEvent>) {
+ *   console.log(envelope.data.someField); // Type-safe access
+ * }
+ */
+export type EnvelopeOf<T extends MatadorEvent> = Envelope<T['data']>;
+/**
+ * Callback function executed when an event is received (standard subscribers).
+ * Receives the full envelope containing id, data, and docket.
+ */
+export type StandardCallback<T = unknown> = (envelope: Envelope<T>) => Promise<void> | void;
+/**
+ * Callback function for resumable subscribers.
+ * Receives the envelope and a SubscriberContext with io() for checkpointed operations.
+ */
+export type ResumableCallback<T = unknown> = (envelope: Envelope<T>, context: SubscriberContext) => Promise<void> | void;
+/**
+ * Callback function executed when an event is received.
+ * @deprecated Use StandardCallback or ResumableCallback instead.
+ */
+export type SubscriberCallback<T = unknown> = StandardCallback<T>;
+/**
+ * Base configuration options shared by all subscriber types.
+ */
+export interface BaseSubscriberOptions {
+    /** Human-readable description of what this subscriber does */
+    readonly description: string;
+    /** Route this subscriber's events to a specific queue */
+    readonly targetQueue?: string | undefined;
+    /** Importance level for monitoring and alerting */
+    readonly importance?: Importance | undefined;
+    /** Feature flag function to conditionally enable/disable the subscriber */
+    readonly enabled?: (() => boolean | Promise<boolean>) | undefined;
+}
+/**
+ * Options for standard (non-resumable) subscribers.
+ */
+export interface StandardSubscriberOptions extends BaseSubscriberOptions {
+    /** Idempotency declaration for retry handling (non-resumable) */
+    readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
+}
+/**
+ * Options for resumable subscribers that use io() for checkpointed operations.
+ */
+export interface ResumableSubscriberOptions extends BaseSubscriberOptions {
+    /** Must be 'resumable' to enable checkpoint-based idempotency */
+    readonly idempotent: 'resumable';
+}
+/**
+ * Configuration options for a subscriber.
+ * Discriminated union based on idempotent value.
+ */
+export type SubscriberOptions = StandardSubscriberOptions | ResumableSubscriberOptions;
+/**
+ * Standard subscriber definition with standard callback.
+ */
+export interface StandardSubscriber<T extends MatadorEvent> extends StandardSubscriberOptions {
+    /** Human-readable name for the subscriber */
+    readonly name: string;
+    /** Callback function to execute when event is received */
+    readonly callback: StandardCallback<T['data']>;
+}
+/**
+ * Resumable subscriber definition with resumable callback.
+ */
+export interface ResumableSubscriber<T extends MatadorEvent> extends ResumableSubscriberOptions {
+    /** Human-readable name for the subscriber */
+    readonly name: string;
+    /** Callback function with SubscriberContext for checkpointed operations */
+    readonly callback: ResumableCallback<T['data']>;
+}
+/**
+ * Full subscriber definition with callback (either standard or resumable).
+ */
+export type Subscriber<T extends MatadorEvent> = StandardSubscriber<T> | ResumableSubscriber<T>;
+/**
+ * Subscriber stub for multi-codebase scenarios where subscriber implementation
+ * is in a remote service. Declares the subscriber contract without providing
+ * the callback.
+ */
+export interface SubscriberStub extends StandardSubscriberOptions {
+    /** Human-readable name for the subscriber */
+    readonly name: string;
+    /** Indicates this is a stub without implementation */
+    readonly isStub: true;
+}
+/**
+ * Union type for any subscriber definition (full or stub).
+ * This is the type-erased version for use in collections and schema.
+ * Uses `any` because Subscriber<T> is contravariant in T (callback parameter),
+ * making it impossible to assign Subscriber<SpecificEvent> to Subscriber<MatadorEvent<unknown>>.
+ */
+export type AnySubscriber = Subscriber<MatadorEvent<any>> | SubscriberStub;
+/**
+ * Type guard to check if a subscriber is a stub.
+ */
+export declare function isSubscriberStub(subscriber: AnySubscriber): subscriber is SubscriberStub;
+/**
+ * Type guard to check if a subscriber has a callback implementation.
+ */
+export declare function isSubscriber(subscriber: AnySubscriber): subscriber is Subscriber<MatadorEvent<any>>;
+/**
+ * Type guard to check if a subscriber is resumable.
+ */
+export declare function isResumableSubscriber(subscriber: AnySubscriber): subscriber is ResumableSubscriber<MatadorEvent<any>>;
+/**
+ * Type guard to check if a subscriber is a standard (non-resumable) subscriber.
+ */
+export declare function isStandardSubscriber(subscriber: AnySubscriber): subscriber is StandardSubscriber<MatadorEvent<any>>;
+/**
+ * Input options for createSubscriber with standard callback.
+ */
+export interface CreateStandardSubscriberInput<T extends MatadorEvent> {
+    readonly name: string;
+    readonly description: string;
+    readonly callback: StandardCallback<T['data']>;
+    readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
+    readonly importance?: Importance | undefined;
+    readonly targetQueue?: string | undefined;
+    readonly enabled?: (() => boolean | Promise<boolean>) | undefined;
+}
+/**
+ * Input options for createSubscriber with resumable callback.
+ */
+export interface CreateResumableSubscriberInput<T extends MatadorEvent> {
+    readonly name: string;
+    readonly description: string;
+    readonly callback: ResumableCallback<T['data']>;
+    readonly idempotent: 'resumable';
+    readonly importance?: Importance | undefined;
+    readonly targetQueue?: string | undefined;
+    readonly enabled?: (() => boolean | Promise<boolean>) | undefined;
+}
+/**
+ * Input options for createSubscriber (discriminated union).
+ */
+export type CreateSubscriberInput<T extends MatadorEvent> = CreateStandardSubscriberInput<T> | CreateResumableSubscriberInput<T>;
+/**
+ * Creates a subscriber definition.
+ *
+ * @example Standard subscriber
+ * ```typescript
+ * const subscriber = createSubscriber<MyEvent>({
+ *   name: 'my-subscriber',
+ *   description: 'Handles MyEvent by logging the data',
+ *   callback: async (envelope) => {
+ *     console.log(envelope.data);
+ *   },
+ * });
+ * ```
+ *
+ * @example Resumable subscriber with io()
+ * ```typescript
+ * const subscriber = createSubscriber<MyEvent>({
+ *   name: 'my-resumable-subscriber',
+ *   description: 'Processes MyEvent with checkpoint-based idempotency',
+ *   idempotent: 'resumable',
+ *   callback: async (envelope, { io }) => {
+ *     await io('step-1', () => doSomething());
+ *   },
+ * });
+ * ```
+ */
+export declare function createSubscriber<T extends MatadorEvent>(input: CreateSubscriberInput<T>): Subscriber<T>;
+/**
+ * Input options for createSubscriberStub.
+ */
+export interface CreateSubscriberStubInput {
+    readonly name: string;
+    readonly description: string;
+    readonly idempotent?: 'yes' | 'no' | 'unknown' | undefined;
+    readonly importance?: Importance | undefined;
+    readonly targetQueue?: string | undefined;
+    readonly enabled?: (() => boolean | Promise<boolean>) | undefined;
+}
+/**
+ * Creates a subscriber stub for remote implementations.
+ *
+ * @example
+ * ```typescript
+ * const stub = createSubscriberStub({
+ *   name: 'remote-analytics',
+ *   description: 'Sends events to remote analytics service',
+ *   targetQueue: 'analytics-worker',
+ * });
+ * ```
+ */
+export declare function createSubscriberStub(input: CreateSubscriberStubInput): SubscriberStub;
+/**
+ * Definition interface used by the pipeline (excludes event class reference).
+ */
+export interface SubscriberDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly idempotent: Idempotency;
+    readonly importance: Importance;
+    readonly targetQueue?: string | undefined;
+}
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/types/subscriber.d.ts.map

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

package/dist/types/subscriber.js

@@ -0,0 +1,99 @@
+/**
+ * Type guard to check if a subscriber is a stub.
+ */
+export function isSubscriberStub(subscriber) {
+    return 'isStub' in subscriber && subscriber.isStub === true;
+}
+/**
+ * Type guard to check if a subscriber has a callback implementation.
+ */
+export function isSubscriber(subscriber) {
+    return 'callback' in subscriber && typeof subscriber.callback === 'function';
+}
+/**
+ * Type guard to check if a subscriber is resumable.
+ */
+export function isResumableSubscriber(subscriber) {
+    return isSubscriber(subscriber) && subscriber.idempotent === 'resumable';
+}
+/**
+ * Type guard to check if a subscriber is a standard (non-resumable) subscriber.
+ */
+export function isStandardSubscriber(subscriber) {
+    return isSubscriber(subscriber) && subscriber.idempotent !== 'resumable';
+}
+/**
+ * Creates a subscriber definition.
+ *
+ * @example Standard subscriber
+ * ```typescript
+ * const subscriber = createSubscriber<MyEvent>({
+ *   name: 'my-subscriber',
+ *   description: 'Handles MyEvent by logging the data',
+ *   callback: async (envelope) => {
+ *     console.log(envelope.data);
+ *   },
+ * });
+ * ```
+ *
+ * @example Resumable subscriber with io()
+ * ```typescript
+ * const subscriber = createSubscriber<MyEvent>({
+ *   name: 'my-resumable-subscriber',
+ *   description: 'Processes MyEvent with checkpoint-based idempotency',
+ *   idempotent: 'resumable',
+ *   callback: async (envelope, { io }) => {
+ *     await io('step-1', () => doSomething());
+ *   },
+ * });
+ * ```
+ */
+export function createSubscriber(input) {
+    const base = {
+        name: input.name,
+        description: input.description,
+        callback: input.callback,
+        importance: input.importance ?? 'should-investigate',
+        ...(input.targetQueue !== undefined && {
+            targetQueue: input.targetQueue,
+        }),
+        ...(input.enabled !== undefined && { enabled: input.enabled }),
+    };
+    if (input.idempotent === 'resumable') {
+        return {
+            ...base,
+            idempotent: 'resumable',
+            callback: input.callback,
+        };
+    }
+    return {
+        ...base,
+        idempotent: input.idempotent ?? 'unknown',
+        callback: input.callback,
+    };
+}
+/**
+ * Creates a subscriber stub for remote implementations.
+ *
+ * @example
+ * ```typescript
+ * const stub = createSubscriberStub({
+ *   name: 'remote-analytics',
+ *   description: 'Sends events to remote analytics service',
+ *   targetQueue: 'analytics-worker',
+ * });
+ * ```
+ */
+export function createSubscriberStub(input) {
+    return {
+        name: input.name,
+        description: input.description,
+        isStub: true,
+        idempotent: input.idempotent ?? 'unknown',
+        importance: input.importance ?? 'should-investigate',
+        ...(input.targetQueue !== undefined && {
+            targetQueue: input.targetQueue,
+        }),
+        ...(input.enabled !== undefined && { enabled: input.enabled }),
+    };
+}

package/examples/config.ts

@@ -0,0 +1,126 @@
+/**
+ * Example Matador configuration for CLI testing
+ *
+ * This file demonstrates how to structure a config file for the CLI.
+ * It exports:
+ *   - schema: MatadorSchema mapping event keys to event classes and subscribers
+ *   - topology: Topology configuration
+ */
+
+import {
+  MatadorEvent,
+  type MatadorSchema,
+  type Topology,
+  TopologyBuilder,
+  createSubscriber,
+} from '../src/index.js';
+
+// ============================================================================
+// Events
+// ============================================================================
+
+export class UserCreatedEvent extends MatadorEvent {
+  static readonly key = 'user.created';
+  static readonly description = 'Fired when a new user is created';
+
+  constructor(
+    public data: {
+      userId: string;
+      email: string;
+      name: string;
+    },
+  ) {
+    super();
+  }
+}
+
+export class OrderPlacedEvent extends MatadorEvent {
+  static readonly key = 'order.placed';
+  static readonly description = 'Fired when a new order is placed';
+
+  constructor(
+    public data: {
+      orderId: string;
+      userId: string;
+      amount: number;
+      items: Array<{ productId: string; quantity: number }>;
+    },
+  ) {
+    super();
+  }
+}
+
+// ============================================================================
+// Subscribers
+// ============================================================================
+
+const sendWelcomeEmail = createSubscriber({
+  name: 'send-welcome-email',
+  description: 'Sends a welcome email to newly registered users',
+  callback: async ({ data, docket }) => {
+    console.log(`  📧 Sending welcome email to ${data.email}`);
+    console.log(`     User: ${data.name} (${data.userId})`);
+    if (docket.correlationId) {
+      console.log(`     Correlation ID: ${docket.correlationId}`);
+    }
+  },
+  idempotent: 'yes',
+  importance: 'should-investigate',
+});
+
+const trackUserAnalytics = createSubscriber({
+  name: 'track-user-analytics',
+  description: 'Tracks user creation in analytics system',
+  callback: async ({ data }) => {
+    console.log(`  📊 Tracking analytics for new user: ${data.userId}`);
+  },
+  idempotent: 'yes',
+  importance: 'can-ignore',
+});
+
+const processOrder = createSubscriber({
+  name: 'process-order',
+  description: 'Processes order for fulfillment',
+  callback: async ({ data }) => {
+    console.log(`  📦 Processing order ${data.orderId}`);
+    console.log(`     Amount: $${data.amount.toFixed(2)}`);
+    console.log(`     Items: ${data.items.length} item(s)`);
+  },
+  idempotent: 'no',
+  importance: 'must-investigate',
+});
+
+const sendOrderConfirmation = createSubscriber({
+  name: 'send-order-confirmation',
+  description: 'Sends order confirmation email to customer',
+  callback: async ({ data }) => {
+    console.log(`  📧 Sending order confirmation for ${data.orderId}`);
+  },
+  idempotent: 'yes',
+  importance: 'should-investigate',
+});
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+/**
+ * Matador schema mapping event keys to event classes and their subscribers.
+ * Uses the tuple format: [EventClass, Subscribers[]]
+ */
+export const schema: MatadorSchema = {
+  [UserCreatedEvent.key]: [
+    UserCreatedEvent,
+    [sendWelcomeEmail, trackUserAnalytics],
+  ],
+  [OrderPlacedEvent.key]: [
+    OrderPlacedEvent,
+    [processOrder, sendOrderConfirmation],
+  ],
+};
+
+export const topology: Topology = TopologyBuilder.create()
+  .withNamespace('example')
+  .addQueue('events', { concurrency: 5 })
+  .withoutDeadLetter()
+  .build();

package/examples/event.ts

@@ -0,0 +1,26 @@
+/**
+ * Example event file for CLI testing
+ *
+ * This file demonstrates how to structure an event file for the CLI.
+ * It exports:
+ *   - eventKey: The key of the event to dispatch (must match an event in config)
+ *   - data: The event payload
+ *   - before: (optional) Previous state for change events
+ *   - options: (optional) Dispatch options like correlationId, metadata
+ */
+
+export const eventKey = 'user.created';
+
+export const data = {
+  userId: 'usr_12345',
+  email: 'alice@example.com',
+  name: 'Alice Smith',
+};
+
+export const options = {
+  correlationId: 'req_abc123',
+  metadata: {
+    source: 'cli-test',
+    timestamp: new Date().toISOString(),
+  },
+};

package/examples/order-event.json

@@ -0,0 +1,19 @@
+{
+  "eventKey": "order.placed",
+  "data": {
+    "orderId": "ord_98765",
+    "userId": "usr_12345",
+    "amount": 149.99,
+    "items": [
+      { "productId": "prod_001", "quantity": 2 },
+      { "productId": "prod_002", "quantity": 1 }
+    ]
+  },
+  "options": {
+    "correlationId": "req_xyz789",
+    "metadata": {
+      "source": "cli-test",
+      "channel": "web"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@zdavison/matador",
+  "version": "2.0.1",
+  "description": "A batteries-included event system.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "bin": {
+    "matador": "./cli.ts"
+  },
+  "scripts": {
+    "build": "rm -rf dist *.tsbuildinfo && tsup && tsc --build && cp dist/index.d.ts dist/index.d.cts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:integration": "bun test --grep integration",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check . --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "cli": "bun ./cli.ts",
+    "send-test-event": "bun ./cli.ts ./examples/config.ts ./examples/event.ts"
+  },
+  "dependencies": {
+    "amqplib": "^0.10.4"
+  },
+  "devDependencies": {
+    "@testcontainers/rabbitmq": "^10.16.0",
+    "@types/amqplib": "^0.10.5",
+    "testcontainers": "^10.16.0",
+    "tsup": "^8.3.5"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "events",
+    "messaging",
+    "queue",
+    "rabbitmq",
+    "bullmq",
+    "kafka",
+    "transport"
+  ],
+  "license": "MIT"
+}