@yuva-devlab/events 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,425 @@
+import { z } from 'zod';
+
+/**
+ * @file packages/events/src/contracts/envelope.ts
+ * @description Standard transactional outbox and event bus envelope schema for DevLab.
+ *
+ * Guarantees cross-service traceability, event ordering, and idempotency across all services.
+ *
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Standard Zod validator for RFC UUID strings.
+ */
+declare const UuidSchema: z.ZodString;
+/**
+ * Zod schema defining the canonical metadata envelope wrapping all domain events.
+ */
+declare const DomainEventEnvelopeSchema: z.ZodObject<{
+    /** Unique event occurrence UUID for deduplication */
+    eventId: z.ZodString;
+    /** Qualified dot-notated or uppercase event type (e.g. AGENT.EXECUTION.COMPLETED) */
+    eventType: z.ZodString;
+    /** Optional execution or correlation identifier */
+    executionId: z.ZodOptional<z.ZodString>;
+    /** Optional tenant partition identifier */
+    tenantId: z.ZodOptional<z.ZodString>;
+    /** Distributed trace identifier for end-to-end telemetry */
+    traceId: z.ZodOptional<z.ZodString>;
+    /** ISO-8601 string or Date object representing event generation time */
+    timestamp: z.ZodDefault<z.ZodString>;
+    /** Domain-specific event payload matching the eventType */
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    eventId: string;
+    eventType: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+    executionId?: string | undefined;
+    tenantId?: string | undefined;
+    traceId?: string | undefined;
+}, {
+    eventId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    executionId?: string | undefined;
+    tenantId?: string | undefined;
+    traceId?: string | undefined;
+    timestamp?: string | undefined;
+}>;
+/**
+ * Inferred type of the canonical domain event envelope.
+ */
+type DomainEventEnvelope<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<z.infer<typeof DomainEventEnvelopeSchema>, "payload"> & {
+    payload: TPayload;
+};
+/**
+ * Factory options for generating a new DomainEventEnvelope.
+ */
+interface CreateEventEnvelopeOptions<TPayload extends Record<string, unknown>> {
+    eventId?: string;
+    eventType: string;
+    payload: TPayload;
+    executionId?: string;
+    tenantId?: string;
+    traceId?: string;
+    timestamp?: string;
+}
+/**
+ * Generates a valid domain event envelope with defaults.
+ *
+ * @param options - Factory configuration options.
+ * @returns Fully constructed DomainEventEnvelope.
+ */
+declare function createEventEnvelope<TPayload extends Record<string, unknown>>(options: CreateEventEnvelopeOptions<TPayload>): DomainEventEnvelope<TPayload>;
+
+/**
+ * @file packages/events/src/contracts/event-bus.interface.ts
+ * @description Master publisher, subscriber, and event bus interfaces for DevLab services.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Callback handler invoked when a matching domain event is received.
+ */
+type EventHandler<TEvent extends DomainEventEnvelope = DomainEventEnvelope> = (event: TEvent) => void | Promise<void>;
+/**
+ * Handle returned to subscribers allowing idempotent unsubscription.
+ */
+interface EventSubscription {
+    /** Unregisters the subscriber from receiving further events */
+    unsubscribe: () => void;
+}
+/**
+ * Contract for components capable of publishing domain events.
+ */
+interface IEventPublisher {
+    /**
+     * Emits a single domain event envelope.
+     *
+     * @param event - The validated event envelope to emit.
+     */
+    publish(event: DomainEventEnvelope): Promise<void>;
+    /**
+     * Emits an atomic or contiguous sequence of domain events.
+     *
+     * @param events - Array of validated event envelopes.
+     */
+    publishBatch(events: DomainEventEnvelope[]): Promise<void>;
+}
+/**
+ * Contract for components that subscribe to domain event topics or wildcards.
+ */
+interface IEventSubscriber {
+    /**
+     * Registers a listener for an exact domain event type or wildcard ("*" or "domain.*").
+     *
+     * @param eventType - Target event type or wildcard pattern.
+     * @param handler - Callback function executing on event receipt.
+     * @returns Subscription handle with an unsubscribe method.
+     */
+    subscribe(eventType: string, handler: EventHandler): EventSubscription;
+}
+/**
+ * Unified bi-directional event bus uniting publisher and subscriber capabilities.
+ */
+interface IEventBus extends IEventPublisher, IEventSubscriber {
+    /**
+     * Removes all registered subscribers and releases memory.
+     */
+    clear(): void;
+}
+
+/**
+ * @file packages/events/src/bus/in-memory-event-bus.ts
+ * @description Fast, non-blocking in-memory event bus implementation supporting wildcards.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * In-memory event bus with pattern matching, asynchronous execution, and fault isolation.
+ */
+declare class InMemoryEventBus implements IEventBus {
+    /** Map of event pattern to set of subscribed callback handlers */
+    private readonly subscribers;
+    /**
+     * Emits a single domain event envelope to all matching listeners.
+     *
+     * @param event - The validated event envelope.
+     */
+    publish(event: DomainEventEnvelope): Promise<void>;
+    /**
+     * Emits an array of domain events sequentially or concurrently.
+     *
+     * @param events - List of event envelopes to publish.
+     */
+    publishBatch(events: DomainEventEnvelope[]): Promise<void>;
+    /**
+     * Registers a listener for an exact event type or wildcard pattern (*, domain.*).
+     *
+     * @param eventPattern - Topic pattern to subscribe to.
+     * @param handler - Asynchronous callback handler.
+     * @returns Unsubscribe handle.
+     */
+    subscribe(eventPattern: string, handler: EventHandler): EventSubscription;
+    /**
+     * Clears all active subscribers from memory.
+     */
+    clear(): void;
+    /**
+     * Resolves all handlers matching the given concrete event type.
+     *
+     * @param concreteType - The incoming eventType string.
+     * @returns Array of unique matching handlers.
+     */
+    private getMatchingHandlers;
+    /**
+     * Evaluates if a concrete event type matches a subscription pattern.
+     * Supports global wildcard "*" and prefix wildcards "prefix.*".
+     *
+     * @param pattern - Registered pattern.
+     * @param target - Concrete event type.
+     * @returns True if matched.
+     */
+    private matchesPattern;
+}
+
+/**
+ * @file packages/events/src/outbox/outbox-record.ts
+ * @description Outbox table record model and validation schema for the Transactional Outbox pattern.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Lifecycle status of an outbox record awaiting dispatch.
+ */
+declare const OutboxStatus: {
+    readonly PENDING: "PENDING";
+    readonly PROCESSING: "PROCESSING";
+    readonly PUBLISHED: "PUBLISHED";
+    readonly FAILED: "FAILED";
+};
+type OutboxStatus = (typeof OutboxStatus)[keyof typeof OutboxStatus];
+/**
+ * Zod schema validating a persisted outbox record.
+ */
+declare const OutboxRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    envelope: z.ZodObject<{
+        eventId: z.ZodString;
+        eventType: z.ZodString;
+        executionId: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+        traceId: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodDefault<z.ZodString>;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        eventId: string;
+        eventType: string;
+        timestamp: string;
+        payload: Record<string, unknown>;
+        executionId?: string | undefined;
+        tenantId?: string | undefined;
+        traceId?: string | undefined;
+    }, {
+        eventId: string;
+        eventType: string;
+        payload: Record<string, unknown>;
+        executionId?: string | undefined;
+        tenantId?: string | undefined;
+        traceId?: string | undefined;
+        timestamp?: string | undefined;
+    }>;
+    status: z.ZodEnum<["PENDING", "PROCESSING", "PUBLISHED", "FAILED"]>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+    lastError: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    publishedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "PENDING" | "PROCESSING" | "PUBLISHED" | "FAILED";
+    id: string;
+    envelope: {
+        eventId: string;
+        eventType: string;
+        timestamp: string;
+        payload: Record<string, unknown>;
+        executionId?: string | undefined;
+        tenantId?: string | undefined;
+        traceId?: string | undefined;
+    };
+    attempts: number;
+    maxAttempts: number;
+    createdAt: string;
+    updatedAt: string;
+    lastError?: string | undefined;
+    publishedAt?: string | undefined;
+}, {
+    status: "PENDING" | "PROCESSING" | "PUBLISHED" | "FAILED";
+    id: string;
+    envelope: {
+        eventId: string;
+        eventType: string;
+        payload: Record<string, unknown>;
+        executionId?: string | undefined;
+        tenantId?: string | undefined;
+        traceId?: string | undefined;
+        timestamp?: string | undefined;
+    };
+    createdAt: string;
+    updatedAt: string;
+    attempts?: number | undefined;
+    maxAttempts?: number | undefined;
+    lastError?: string | undefined;
+    publishedAt?: string | undefined;
+}>;
+type OutboxRecord = z.infer<typeof OutboxRecordSchema>;
+
+/**
+ * @file packages/events/src/outbox/outbox-store.interface.ts
+ * @description Storage contract for transactional outbox persistence and status updates.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Storage contract implemented by relational or KV databases for outbox buffering.
+ */
+interface IOutboxStore {
+    /**
+     * Persists a domain event inside an existing database transaction or atomically.
+     *
+     * @param envelope - Domain event envelope to queue for publication.
+     * @returns Persisted outbox record.
+     */
+    save(envelope: DomainEventEnvelope): Promise<OutboxRecord>;
+    /**
+     * Retrieves a batch of pending outbox records ready for dispatch.
+     *
+     * @param limit - Maximum number of records to retrieve in a single polling tick.
+     * @returns Array of pending outbox records.
+     */
+    fetchPending(limit: number): Promise<OutboxRecord[]>;
+    /**
+     * Marks a record as successfully published.
+     *
+     * @param recordId - Unique identifier of the outbox entry.
+     */
+    markPublished(recordId: string): Promise<void>;
+    /**
+     * Records a dispatch failure and increments retry attempts.
+     *
+     * @param recordId - Unique identifier of the outbox entry.
+     * @param error - Error description message.
+     */
+    markFailed(recordId: string, error: string): Promise<void>;
+}
+
+/**
+ * @file packages/events/src/outbox/outbox-relay.ts
+ * @description Background polling relay engine delivering transactional outbox events to the event bus.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Configuration options for the background outbox dispatch relay.
+ */
+interface OutboxRelayOptions {
+    /** Polling interval in milliseconds (default: 1000ms) */
+    pollIntervalMs?: number;
+    /** Max records to drain in each tick (default: 50) */
+    batchSize?: number;
+}
+/**
+ * Background poller ensuring guaranteed at-least-once delivery of outbox records.
+ */
+declare class OutboxRelay {
+    private readonly store;
+    private readonly publisher;
+    private isRunning;
+    private timer;
+    private readonly pollIntervalMs;
+    private readonly batchSize;
+    constructor(store: IOutboxStore, publisher: IEventPublisher, options?: OutboxRelayOptions);
+    /**
+     * Starts the background relay polling loop.
+     */
+    start(): void;
+    /**
+     * Stops the background relay polling loop.
+     */
+    stop(): void;
+    /**
+     * Executes a single polling tick, draining pending outbox records.
+     *
+     * @returns Number of events successfully processed during this tick.
+     */
+    drainOnce(): Promise<number>;
+    /**
+     * Schedules the next execution tick with timer guard.
+     */
+    private scheduleNextTick;
+}
+
+/**
+ * @file packages/events/src/idempotency/idempotency-store.interface.ts
+ * @description Contract for distributed idempotency stores preventing duplicate event processing.
+ * @module @yuva-devlab/events
+ */
+/**
+ * Result returned when attempting to acquire an idempotency lock for an event key.
+ */
+type IdempotencyAcquireResult = {
+    state: "ACQUIRED";
+} | {
+    state: "ALREADY_COMPLETED";
+    completedAt: string;
+} | {
+    state: "IN_FLIGHT";
+};
+/**
+ * Interface implemented by Redis, memory, or database idempotency backends.
+ */
+interface IIdempotencyStore {
+    /**
+     * Attempts to acquire an execution lock for a given idempotency key.
+     *
+     * @param key - The unique event or transaction key.
+     * @param ttlSeconds - Lock TTL in seconds.
+     * @returns Result indicating whether the lock was acquired, in-flight, or already completed.
+     */
+    acquire(key: string, ttlSeconds?: number): Promise<IdempotencyAcquireResult>;
+    /**
+     * Marks the operation as successfully finished with a retention TTL.
+     *
+     * @param key - The idempotency key.
+     * @param retentionSeconds - How long to retain the completed state (default: 86400s / 24h).
+     */
+    markCompleted(key: string, retentionSeconds?: number): Promise<void>;
+    /**
+     * Releases an in-flight lock, typically on unexpected processing error to allow retry.
+     *
+     * @param key - The idempotency key to release.
+     */
+    release(key: string): Promise<void>;
+}
+
+/**
+ * @file packages/events/src/idempotency/in-memory-idempotency-store.ts
+ * @description In-memory TTL idempotency store implementation for testing and single-node services.
+ * @module @yuva-devlab/events
+ */
+
+/**
+ * Single-process in-memory idempotency store with active expiration.
+ */
+declare class InMemoryIdempotencyStore implements IIdempotencyStore {
+    private readonly records;
+    acquire(key: string, ttlSeconds?: number): Promise<IdempotencyAcquireResult>;
+    markCompleted(key: string, retentionSeconds?: number): Promise<void>;
+    release(key: string): Promise<void>;
+    private cleanExpired;
+}
+
+export { type CreateEventEnvelopeOptions, type DomainEventEnvelope, DomainEventEnvelopeSchema, type EventHandler, type EventSubscription, type IEventBus, type IEventPublisher, type IEventSubscriber, type IIdempotencyStore, type IOutboxStore, type IdempotencyAcquireResult, InMemoryEventBus, InMemoryIdempotencyStore, type OutboxRecord, OutboxRecordSchema, OutboxRelay, type OutboxRelayOptions, OutboxStatus, UuidSchema, createEventEnvelope };