@zdavison/matador 2.0.8 → 2.0.10

package/src/types/event.ts

@@ -1,112 +0,0 @@
-import type { Jsonifiable } from 'type-fest';
-
-/**
- * Unique event routing key type alias.
- */
-export type EventKey = string;
-
-/**
- * JSON-serializable record type for metadata.
- * Uses type-fest's Jsonifiable which accepts:
- * - Primitives (string, number, boolean, null)
- * - Arrays of Jsonifiable values
- * - Objects with Jsonifiable values
- * - Objects with a toJSON() method
- */
-export type JsonRecord = Record<string, Jsonifiable>;
-
-/**
- * Static properties required on Event classes for schema registration.
- */
-export interface EventStatic<T = unknown> {
-  /** Unique routing key for the event */
-  readonly key: string;
-
-  /** Human-readable description of the event */
-  readonly description?: string;
-
-  /** Alternative names/keys for backwards compatibility */
-  readonly aliases?: readonly string[];
-
-  /** Create an instance from data (for deserialization) */
-  new (data: T): Event<T>;
-}
-
-/**
- * Base interface for all events.
- * Events represent something that happened in the system.
- */
-export interface Event<T = unknown> {
-  /** The event data/payload */
-  readonly data: T;
-
-  /** Event-specific metadata (merged with EventOptions metadata on dispatch) */
-  readonly metadata?: JsonRecord | undefined;
-}
-
-/**
- * Options for dispatching an event.
- */
-export interface EventOptions {
-  /** Delay processing by this many milliseconds */
-  readonly delayMs?: number | undefined;
-
-  /** Correlation ID for request tracing */
-  readonly correlationId?: string | undefined;
-
-  /**
-   * Event-specific metadata to include in the docket.
-   * This metadata will be merged with:
-   * 1. Event instance metadata (if defined on the event)
-   * 2. Universal metadata from the loadUniversalMetadata hook
-   * With EventOptions metadata taking precedence over event metadata,
-   * and both taking precedence over universal metadata.
-   */
-  readonly metadata?: JsonRecord | undefined;
-}
-
-/**
- * Abstract base class for creating Matador events.
- * Extend this class to define custom events.
- *
- * @example
- * ```typescript
- * 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 },
- *     public metadata?: JsonRecord,
- *   ) {
- *     super()
- *   }
- * }
- * ```
- */
-export abstract class MatadorEvent<T = unknown> implements Event<T> {
-  static readonly key: string;
-  static readonly description?: string;
-  static readonly aliases?: readonly string[];
-
-  /** The event data/payload - must be defined by subclass */
-  abstract readonly data: T;
-
-  /** Event-specific metadata */
-  readonly metadata?: JsonRecord | undefined;
-}
-
-/**
- * Type helper to extract the data type from an event class.
- */
-export type EventData<E extends Event<unknown>> = E extends Event<infer T>
-  ? T
-  : never;
-
-/**
- * Type helper to get the event class type.
- */
-export type EventClass<T = unknown> = EventStatic<T> &
-  (new (
-    data: T,
-  ) => Event<T>);

package/src/types/index.ts

@@ -1,62 +0,0 @@
-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';
-
-// Re-export Jsonifiable from type-fest for convenience
-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';

package/src/types/subscriber.ts

@@ -1,333 +0,0 @@
-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>>.
- */
-// 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 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 function createSubscriberStub(
-  input: CreateSubscriberStubInput,
-): SubscriberStub {
-  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 }),
-  };
-}
-
-/**
- * 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;
-}