@zdavison/matador 2.0.1

package/src/types/index.ts

@@ -0,0 +1,52 @@
+export type {
+  DeliveryMode,
+  Idempotency,
+  Importance,
+  ValidationError,
+  ValidationResult,
+} from './common.js';
+export { invalidResult, validResult } from './common.js';
+
+export type { CreateEnvelopeOptions, Docket, Envelope } from './envelope.js';
+export { createEnvelope } from './envelope.js';
+
+export type {
+  Event,
+  EventClass,
+  EventData,
+  EventKey,
+  EventOptions,
+  EventStatic,
+  JsonPrimitive,
+  JsonRecord,
+  JsonValue,
+} from './event.js';
+export { MatadorEvent } from './event.js';
+
+export type {
+  AnySubscriber,
+  BaseSubscriberOptions,
+  CreateResumableSubscriberInput,
+  CreateStandardSubscriberInput,
+  CreateSubscriberInput,
+  EnvelopeOf,
+  ResumableCallback,
+  ResumableSubscriber,
+  ResumableSubscriberOptions,
+  StandardCallback,
+  StandardSubscriber,
+  StandardSubscriberOptions,
+  Subscriber,
+  SubscriberCallback,
+  SubscriberDefinition,
+  SubscriberOptions,
+  SubscriberStub,
+} from './subscriber.js';
+export {
+  createSubscriber,
+  createSubscriberStub,
+  isResumableSubscriber,
+  isStandardSubscriber,
+  isSubscriber,
+  isSubscriberStub,
+} from './subscriber.js';

package/src/types/subscriber.ts

@@ -0,0 +1,310 @@
+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>>.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Required for variance compatibility in heterogeneous collections
+export type AnySubscriber = Subscriber<MatadorEvent<any>> | SubscriberStub;
+
+/**
+ * Type guard to check if a subscriber is a stub.
+ */
+export function isSubscriberStub(
+  subscriber: AnySubscriber,
+): subscriber is SubscriberStub {
+  return 'isStub' in subscriber && subscriber.isStub === true;
+}
+
+/**
+ * Type guard to check if a subscriber has a callback implementation.
+ */
+export function isSubscriber(
+  subscriber: AnySubscriber,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for variance compatibility
+): subscriber is Subscriber<MatadorEvent<any>> {
+  return 'callback' in subscriber && typeof subscriber.callback === 'function';
+}
+
+/**
+ * Type guard to check if a subscriber is resumable.
+ */
+export function isResumableSubscriber(
+  subscriber: AnySubscriber,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for variance compatibility
+): subscriber is ResumableSubscriber<MatadorEvent<any>> {
+  return isSubscriber(subscriber) && subscriber.idempotent === 'resumable';
+}
+
+/**
+ * Type guard to check if a subscriber is a standard (non-resumable) subscriber.
+ */
+export function isStandardSubscriber(
+  subscriber: AnySubscriber,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for variance compatibility
+): subscriber is StandardSubscriber<MatadorEvent<any>> {
+  return isSubscriber(subscriber) && subscriber.idempotent !== 'resumable';
+}
+
+/**
+ * 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 function createSubscriber<T extends MatadorEvent>(
+  input: CreateSubscriberInput<T>,
+): Subscriber<T> {
+  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,
+    } as ResumableSubscriber<T>;
+  }
+
+  return {
+    ...base,
+    idempotent: input.idempotent ?? 'unknown',
+    callback: input.callback,
+  } as StandardSubscriber<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 function createSubscriberStub(
+  input: CreateSubscriberStubInput,
+): SubscriberStub {
+  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 }),
+  };
+}
+
+/**
+ * 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;
+}

package/test/e2e/multi-transport.e2e.test.ts

@@ -0,0 +1,236 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'bun:test';
+import {
+  RabbitMQContainer,
+  type StartedRabbitMQContainer,
+} from '@testcontainers/rabbitmq';
+import type { TransportFallbackContext } from '../../src/hooks/index.js';
+import type { Subscription } from '../../src/transport/index.js';
+import { LocalTransport } from '../../src/transport/local/local-transport.js';
+import { MultiTransport } from '../../src/transport/multi/multi-transport.js';
+import { RabbitMQTransport } from '../../src/transport/rabbitmq/rabbitmq-transport.js';
+import {
+  createTestEnvelope,
+  createTestTopology,
+} from './transport-compliance.e2e.test.js';
+
+// Skip tests if docker is not available
+const SKIP_E2E = process.env.SKIP_E2E_TESTS === 'true';
+
+describe.skipIf(SKIP_E2E)('MultiTransport E2E', () => {
+  let container: StartedRabbitMQContainer;
+  let connectionUrl: string;
+
+  beforeAll(async () => {
+    container = await new RabbitMQContainer('rabbitmq:3.13-management')
+      .withExposedPorts(5672, 15672)
+      .start();
+
+    connectionUrl = container.getAmqpUrl();
+    console.log(`RabbitMQ container started at ${connectionUrl}`);
+  }, 120_000);
+
+  afterAll(async () => {
+    if (container) {
+      await container.stop();
+    }
+  });
+
+  describe('fallback to local transport when RabbitMQ fails', () => {
+    let rabbitTransport: RabbitMQTransport;
+    let localTransport: LocalTransport;
+    let multiTransport: MultiTransport;
+    let subscriptions: Subscription[];
+    let fallbackEvents: TransportFallbackContext[];
+
+    beforeEach(async () => {
+      subscriptions = [];
+      fallbackEvents = [];
+
+      rabbitTransport = new RabbitMQTransport({
+        url: connectionUrl,
+        quorumQueues: false,
+      });
+
+      localTransport = new LocalTransport();
+
+      multiTransport = new MultiTransport(
+        { transports: [rabbitTransport, localTransport] },
+        { onEnqueueFallback: (ctx) => fallbackEvents.push(ctx) },
+      );
+
+      await multiTransport.connect();
+    });
+
+    afterEach(async () => {
+      for (const sub of subscriptions) {
+        if (sub.isActive) {
+          await sub.unsubscribe();
+        }
+      }
+      if (multiTransport.isConnected()) {
+        await multiTransport.disconnect();
+      }
+    });
+
+    it('should send to RabbitMQ when healthy', async () => {
+      const topology = createTestTopology(`healthy-${Date.now()}`);
+      await multiTransport.applyTopology(topology);
+      const queueName = `${topology.namespace}.events`;
+
+      const receivedMessages: string[] = [];
+
+      const subscription = await multiTransport.subscribe(
+        queueName,
+        async (env, receipt) => {
+          receivedMessages.push(env.id);
+          await multiTransport.complete(receipt);
+        },
+      );
+      subscriptions.push(subscription);
+
+      const envelope = createTestEnvelope();
+      await multiTransport.send(queueName, envelope);
+
+      await waitFor(() => receivedMessages.length >= 1, 5000);
+
+      expect(receivedMessages).toContain(envelope.id);
+      expect(fallbackEvents).toHaveLength(0); // No fallback occurred
+    });
+
+    it('should fallback to memory transport when RabbitMQ send fails', async () => {
+      const topology = createTestTopology(`fallback-${Date.now()}`);
+      await multiTransport.applyTopology(topology);
+      const queueName = `${topology.namespace}.events`;
+
+      const receivedMessages: string[] = [];
+
+      // Subscribe BEFORE disconnecting RabbitMQ
+      const subscription = await multiTransport.subscribe(
+        queueName,
+        async (env, receipt) => {
+          receivedMessages.push(env.id);
+          await multiTransport.complete(receipt);
+        },
+      );
+      subscriptions.push(subscription);
+
+      // Disconnect RabbitMQ to simulate failure
+      await rabbitTransport.disconnect();
+
+      // Send should fallback to memory transport
+      const envelope = createTestEnvelope();
+      await multiTransport.send(queueName, envelope);
+
+      // Message should be processed by subscriber on memory transport
+      await waitFor(() => receivedMessages.length >= 1, 5000);
+
+      expect(receivedMessages).toContain(envelope.id);
+
+      // Verify fallback was triggered
+      expect(fallbackEvents).toHaveLength(1);
+      expect(fallbackEvents[0]!.failedTransport).toBe('rabbitmq');
+      expect(fallbackEvents[0]!.nextTransport).toBe('local');
+      expect(fallbackEvents[0]!.queue).toBe(queueName);
+    });
+
+    it('should process multiple messages via fallback', async () => {
+      const topology = createTestTopology(`multi-${Date.now()}`);
+      await multiTransport.applyTopology(topology);
+      const queueName = `${topology.namespace}.events`;
+
+      const receivedMessages: string[] = [];
+
+      const subscription = await multiTransport.subscribe(
+        queueName,
+        async (env, receipt) => {
+          receivedMessages.push(env.id);
+          await multiTransport.complete(receipt);
+        },
+      );
+      subscriptions.push(subscription);
+
+      // Disconnect RabbitMQ
+      await rabbitTransport.disconnect();
+
+      // Send multiple messages
+      const envelopes = [
+        createTestEnvelope({ id: 'msg-1' }),
+        createTestEnvelope({ id: 'msg-2' }),
+        createTestEnvelope({ id: 'msg-3' }),
+      ];
+
+      for (const env of envelopes) {
+        await multiTransport.send(queueName, env);
+      }
+
+      await waitFor(() => receivedMessages.length >= 3, 5000);
+
+      expect(receivedMessages).toContain('msg-1');
+      expect(receivedMessages).toContain('msg-2');
+      expect(receivedMessages).toContain('msg-3');
+      expect(fallbackEvents).toHaveLength(3);
+    });
+
+    it('should handle mixed success/fallback sends', async () => {
+      const topology = createTestTopology(`mixed-${Date.now()}`);
+      await multiTransport.applyTopology(topology);
+      const queueName = `${topology.namespace}.events`;
+
+      const receivedMessages: string[] = [];
+
+      const subscription = await multiTransport.subscribe(
+        queueName,
+        async (env, receipt) => {
+          receivedMessages.push(env.id);
+          await multiTransport.complete(receipt);
+        },
+      );
+      subscriptions.push(subscription);
+
+      // Send first message to RabbitMQ (should succeed)
+      const env1 = createTestEnvelope({ id: 'rabbit-msg' });
+      await multiTransport.send(queueName, env1);
+
+      await waitFor(() => receivedMessages.includes('rabbit-msg'), 5000);
+
+      // Disconnect RabbitMQ
+      await rabbitTransport.disconnect();
+
+      // Send second message (should fallback to memory)
+      const env2 = createTestEnvelope({ id: 'memory-msg' });
+      await multiTransport.send(queueName, env2);
+
+      await waitFor(() => receivedMessages.includes('memory-msg'), 5000);
+
+      expect(receivedMessages).toContain('rabbit-msg');
+      expect(receivedMessages).toContain('memory-msg');
+      expect(fallbackEvents).toHaveLength(1);
+      expect(fallbackEvents[0]!.envelope.id).toBe('memory-msg');
+    });
+  });
+});
+
+/**
+ * Waits for a condition to be true, with timeout.
+ */
+async function waitFor(
+  condition: () => boolean,
+  timeoutMs: number,
+  intervalMs = 50,
+): Promise<void> {
+  const startTime = Date.now();
+  while (!condition()) {
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for condition after ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}