@zdavison/matador 2.0.9 → 2.0.10

package/dist/types/event.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'bun:test';
+import { createEnvelope } from './envelope.js';
+import { MatadorEvent } from './event.js';
+class UserCreatedEvent extends MatadorEvent {
+    data;
+    static key = 'user.created';
+    static description = 'Fired when a new user is created';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class OrderPlacedEvent extends MatadorEvent {
+    data;
+    static key = 'order.placed';
+    static description = 'Fired when an order is placed';
+    static aliases = ['order.created'];
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+class MinimalEvent extends MatadorEvent {
+    data;
+    static key = 'minimal.event';
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+describe('Event', () => {
+    describe('static fields', () => {
+        it('should have static key field on class', () => {
+            expect(UserCreatedEvent.key).toBe('user.created');
+            expect(OrderPlacedEvent.key).toBe('order.placed');
+            expect(MinimalEvent.key).toBe('minimal.event');
+        });
+        it('should have static description field on class when defined', () => {
+            expect(UserCreatedEvent.description).toBe('Fired when a new user is created');
+            expect(OrderPlacedEvent.description).toBe('Fired when an order is placed');
+            expect(MinimalEvent.description).toBeUndefined();
+        });
+        it('should have static aliases field on class when defined', () => {
+            expect(UserCreatedEvent.aliases).toBeUndefined();
+            expect(OrderPlacedEvent.aliases).toEqual(['order.created']);
+            expect(MinimalEvent.aliases).toBeUndefined();
+        });
+    });
+    describe('instance data', () => {
+        it('should have instance data field', () => {
+            const event = new UserCreatedEvent({
+                userId: 'usr_001',
+                email: 'test@example.com',
+            });
+            expect(event.data).toEqual({
+                userId: 'usr_001',
+                email: 'test@example.com',
+            });
+        });
+    });
+});
+describe('Envelope with eventDescription', () => {
+    it('should include eventDescription in docket when provided', () => {
+        const event = new UserCreatedEvent({
+            userId: 'usr_123',
+            email: 'test@example.com',
+        });
+        const envelope = createEnvelope({
+            eventKey: UserCreatedEvent.key,
+            eventDescription: UserCreatedEvent.description,
+            targetSubscriber: 'test-subscriber',
+            data: event.data,
+            importance: 'should-investigate',
+        });
+        expect(envelope.docket.eventKey).toBe('user.created');
+        expect(envelope.docket.eventDescription).toBe('Fired when a new user is created');
+    });
+    it('should not include eventDescription in docket when undefined', () => {
+        const event = new MinimalEvent({ id: 'min_123' });
+        const envelope = createEnvelope({
+            eventKey: MinimalEvent.key,
+            eventDescription: MinimalEvent.description,
+            targetSubscriber: 'test-subscriber',
+            data: event.data,
+            importance: 'should-investigate',
+        });
+        expect(envelope.docket.eventKey).toBe('minimal.event');
+        expect(envelope.docket.eventDescription).toBeUndefined();
+    });
+    it('should serialize envelope with eventDescription for logging', () => {
+        const event = new OrderPlacedEvent({
+            orderId: 'ord_456',
+            amount: 99.99,
+        });
+        const envelope = createEnvelope({
+            eventKey: OrderPlacedEvent.key,
+            eventDescription: OrderPlacedEvent.description,
+            targetSubscriber: 'order-processor',
+            data: event.data,
+            importance: 'must-investigate',
+        });
+        const serialized = JSON.stringify(envelope);
+        const parsed = JSON.parse(serialized);
+        expect(parsed.docket.eventKey).toBe('order.placed');
+        expect(parsed.docket.eventDescription).toBe('Fired when an order is placed');
+        expect(parsed.data.orderId).toBe('ord_456');
+    });
+    it('should include eventDescription in hook logging context', () => {
+        const event = new UserCreatedEvent({
+            userId: 'usr_error',
+            email: 'error@example.com',
+        });
+        const envelope = createEnvelope({
+            eventKey: UserCreatedEvent.key,
+            eventDescription: UserCreatedEvent.description,
+            targetSubscriber: 'user-handler',
+            data: event.data,
+            importance: 'should-investigate',
+        });
+        // Simulating what would be logged in onEnqueueError hook
+        const errorLog = {
+            message: 'Failed to enqueue event',
+            eventKey: envelope.docket.eventKey,
+            eventDescription: envelope.docket.eventDescription,
+            data: envelope.data,
+        };
+        expect(errorLog.eventKey).toBe('user.created');
+        expect(errorLog.eventDescription).toBe('Fired when a new user is created');
+    });
+});

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export type { DeliveryMode, Idempotency, Importance, ValidationError, ValidationResult, } from './common.js';
+export { invalidResult, validResult } from './common.js';
+export type { Dispatcher } from './dispatcher.js';
+export type { CreateDummyEnvelopeOptions, CreateEnvelopeOptions, Docket, Envelope, } from './envelope.js';
+export { createDummyEnvelope, createEnvelope } from './envelope.js';
+export type { Event, EventClass, EventData, EventKey, EventOptions, EventStatic, JsonRecord, } from './event.js';
+export { MatadorEvent } from './event.js';
+export type { Jsonifiable } from 'type-fest';
+export type { AnySubscriber, BaseSubscriberOptions, CallbackContext, CreateResumableSubscriberInput, CreateStandardSubscriberInput, CreateSubscriberInput, EnvelopeOf, ResumableCallback, ResumableCallbackContext, ResumableSubscriber, ResumableSubscriberOptions, StandardCallback, StandardSubscriber, StandardSubscriberOptions, Subscriber, SubscriberCallback, SubscriberDefinition, SubscriberOptions, SubscriberStub, } from './subscriber.js';
+export { createSubscriber, createSubscriberStub, isResumableSubscriber, isStandardSubscriber, isSubscriber, isSubscriberStub, } from './subscriber.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,YAAY,EACV,0BAA0B,EAC1B,qBAAqB,EACrB,MAAM,EACN,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE,YAAY,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,8BAA8B,EAC9B,6BAA6B,EAC7B,qBAAqB,EACrB,UAAU,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+export { invalidResult, validResult } from './common.js';
+export { createDummyEnvelope, createEnvelope } from './envelope.js';
+export { MatadorEvent } from './event.js';
+export { createSubscriber, createSubscriberStub, isResumableSubscriber, isStandardSubscriber, isSubscriber, isSubscriberStub, } from './subscriber.js';

package/dist/types/subscriber.d.ts

@@ -0,0 +1,227 @@
+import type { SubscriberContext } from '../checkpoint/index.js';
+import type { Idempotency, Importance } from './common.js';
+import type { Dispatcher } from './dispatcher.js';
+import type { Envelope } from './envelope.js';
+import type { MatadorEvent } from './event.js';
+/**
+ * Context passed to subscriber callbacks.
+ * Provides access to the Matador instance for sending additional events.
+ */
+export interface CallbackContext {
+    /** Matador dispatcher for sending additional events from within a subscriber */
+    readonly matador: Dispatcher;
+}
+/**
+ * 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, plus a context
+ * with access to the matador instance for sending additional events.
+ *
+ * The callback may optionally return a value, which will be included in the
+ * onWorkerSuccess hook context for logging or observability purposes.
+ */
+export type StandardCallback<T = unknown> = (envelope: Envelope<T>, context: CallbackContext) => Promise<unknown> | unknown | void;
+/**
+ * Context for resumable subscriber callbacks.
+ * Combines checkpoint operations (io, all) with matador access.
+ */
+export type ResumableCallbackContext = SubscriberContext & CallbackContext;
+/**
+ * Callback function for resumable subscribers.
+ * Receives the envelope and a context with io() for checkpointed operations
+ * and matador for sending additional events.
+ *
+ * The callback may optionally return a value, which will be included in the
+ * onWorkerSuccess hook context for logging or observability purposes.
+ */
+export type ResumableCallback<T = unknown> = (envelope: Envelope<T>, context: ResumableCallbackContext) => Promise<unknown> | unknown | 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 Omit<StandardSubscriberOptions, 'description'> {
+    /** 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 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',
+ *   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 | undefined;
+    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,97 @@
+/**
+ * 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',
+ *   targetQueue: 'analytics-worker',
+ * });
+ * ```
+ */
+export function createSubscriberStub(input) {
+    return {
+        name: input.name,
+        isStub: true,
+        idempotent: input.idempotent ?? 'unknown',
+        importance: input.importance ?? 'should-investigate',
+        ...(input.targetQueue !== undefined && {
+            targetQueue: input.targetQueue,
+        }),
+        ...(input.enabled !== undefined && { enabled: input.enabled }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zdavison/matador",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "A batteries-included event system.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -63,5 +63,9 @@
     "kafka",
     "transport"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "files": [
+    "dist",
+    "cli.ts"
+  ]
 }

package/examples/config.ts

@@ -1,126 +0,0 @@
-/**
- * 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

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-{
-  "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"
-    }
-  }
-}