@jetit/publisher 1.0.2 → 1.0.3

package/index.d.ts

@@ -0,0 +1,222 @@
+declare module "src/lib/redis/types" {
+    export type EventData<T> = {
+        data: T;
+        eventName: string;
+        eventId?: string;
+    };
+    export type PendingMessages = [never, never, string, string, Array<[string, number]>];
+    export type ClaimedMessages = Array<[never, string]>;
+    import { ClusterNode, ClusterOptions, RedisOptions } from 'ioredis';
+    export interface IOptions {
+        redis?: RedisOptions;
+        cluster?: {
+            options: ClusterOptions;
+            nodes: Array<ClusterNode>;
+        };
+    }
+}
+declare module "src/lib/redis/registry" {
+    import Redis, { Cluster } from 'ioredis';
+    import { IOptions } from "src/lib/redis/types";
+    export type RedisType = Redis | Cluster;
+    export class RedisRegistry {
+        private static registry;
+        private static options;
+        static attemptConnection(connectionKey: string, storeRef?: number): Redis;
+        static getConnection(connectionType?: string, storeRef?: number): RedisType;
+        static setOptions(options: IOptions): void;
+        static _getOptions(): IOptions;
+    }
+    /**
+     * This function is used to set Redis Connection options per instance. If no
+     * options are provided, then the service connects as to a single instance
+     * with the environment values from REDIS_PORT and REDIS_HOST. if those
+     * environment values are not provided, it attempts to connect to localhost:6379
+     *
+     * @param options
+     */
+    export function setRedisConnectionSettings(options: IOptions): void;
+}
+declare module "src/lib/redis/groups" {
+    import { RedisType } from "src/lib/redis/registry";
+    export function getAllConsumerGroups(eventName: string, redisConnection: RedisType): Promise<string[]>;
+}
+declare module "src/lib/redis/streams" {
+    import { RedisType } from "src/lib/redis/registry";
+    import { EventData } from "src/lib/redis/types";
+    import { Observable } from 'rxjs';
+    export class Streams {
+        private _redisPublisher?;
+        private _redisSubscriber?;
+        private _redisGroups?;
+        private consumerGroupName;
+        private instanceId;
+        private cleanUpTimer;
+        private eventsListened;
+        get redisPublisher(): RedisType;
+        get redisSubscriber(): RedisType;
+        get redisGroups(): RedisType;
+        /**
+         * Creates a new Streams instance for a given service.
+         *
+         * The constructor initializes the Redis connections for publishers, subscribers, and consumer groups.
+         * It also sets up an interval timer for clearing expired messages from Redis and another interval timer
+         * for processing scheduled events at regular intervals.
+         *
+         * @param serviceName - A unique name for the service that will be using this Streams instance.
+         *
+         * @example
+         *
+         * // Create a new Streams instance for the "POS" service
+         * const streams = new Streams('POS');
+         */
+        constructor(serviceName: string);
+        private createConsumerGroup;
+        private isDuplicateMessage;
+        private clearDuplicationCheckKeys;
+        /**
+         * Publishes an event with the given data to the Redis event stream.
+         *
+         * The method generates a unique event ID for each event, and adds it to the event data to handle message
+         * deduplication.
+         *
+         * @param data - An EventData<T> object containing the data for the event.
+         *
+         * @returns A Promise that resolves when the event has been published to the Redis stream.
+         *
+         * @example
+         *
+         * // Publish an "order.created" event with the given order data
+         * const orderData = { id: '123', customerName: 'John Doe', amount: 100 };
+         * const eventData = { eventName: 'order.created', data: orderData };
+         * await streams.publish(eventData);
+         */
+        publish<T>(data: EventData<T>): Promise<void>;
+        /**
+         * Schedules an event to be published at a specified future time. Thee event gets published if the
+         * differnece between the current time and the scheduled time is less than 500ms.
+         *
+         * @param scheduledTime - The Date object representing the future time when the event should be published.
+         * @param eventData - The event data object, containing the event name and its associated data.
+         *
+         * @throws Error - Throws an error if the scheduled time is in the past.
+         *
+         * @example
+         *
+         * const streams = new Streams('app-service');
+         *
+         * const futureTime = new Date(Date.now() + 10000); // 10 seconds from now
+         * const eventData: EventData<string> = {
+         *   eventName: 'order.created',
+         *   data: 'Order data'
+         * };
+         *
+         * await streams.scheduledPublish(futureTime, eventData);
+         */
+        scheduledPublish<T>(scheduledTime: Date, eventData: EventData<T>, uniquePerInstance?: boolean): Promise<void>;
+        /**
+         * Listens for events with the given name and returns an Observable that emits an EventData<T> object
+         * each time a new event is received.
+         *
+         * The method uses a BehaviorSubject to emit the events as Observables. The BehaviorSubject ensures
+         * that new subscribers receive the last emitted event, even if they subscribe after the event has been emitted.
+         *
+         * If an error occurs while subscribing, the method logs the error to the console and throws
+         * an error. This is done to prevent the service from continuing without a proper event subscription.
+         *
+         * There is retry logic with exponential backoff to handle error cases. These are also controllable by the
+         * calling service
+         *
+         * @param eventName - The name of the event to listen for.
+         *
+         * @returns An Observable that emits an EventData<T> object each time a new event is received.
+         *
+         * @example
+         *
+         * // Listen for "order.created" events
+         * const orderCreated = streams.listen<OrderCreatedEvent>('order.created');
+         *
+         * // Subscribe to the Observable and log each new event
+         * orderCreated.subscribe((event) => {
+         *   console.log('New order created:', event.data);
+         * });
+         */
+        listen<T>(eventName: string, maxRetries?: number, initialDelay?: number): Observable<EventData<T>>;
+        private listenInternals;
+        /**
+         * This method takes all messages allocated to this instance and republishes them so
+         * that other instances of this service can receive and process them.
+         *
+         * This needs to be handled every 1-2 minutes if the queue becomes too long and messages
+         * are not being processed.
+         *
+         * Ideal implementation would be to wrap this inside a setInterval
+         * @param streamName
+         */
+        republishUnprocessedEvents(eventName: string): Promise<void>;
+        /**
+         * This method is used to claim messages in the event of a service crash. This library currently
+         * does not detect a service crash. This needs to be built as an extension of Kubernetes and
+         * a standalone service that notifies this service to process the events that are marked as
+         * pending
+         *
+         * @param streamName
+         * @param idleTimeout
+         *
+         *  * @example
+         *
+         * // Attempt to recover messages from the "order.created" stream with an idle timeout of 10 seconds
+         * await streams.recoverCrashedConsumerMessages('order.created', 10000);
+         */
+        recoverCrashedConsumerMessages(eventName: string, idleTimeout: number): Promise<void>;
+        /**
+         * This method allows the possibility of a graceful shutdown by cleaning up the
+         * redis connections.
+         *
+         * In all services where the library is used, its better to implement this method
+         *
+         * process.on('SIGTERM', shutdown);
+         * process.on('SIGINT', shutdown);
+         *
+         * async function shutdown(): Promise<void> {
+         *   console.log('Graceful shutdown initiated.');
+         *   try {
+         *     await streams.close();
+         *     console.log('Resources and connections successfully closed.');
+         *   } catch (error) {
+         *     console.error('Error during graceful shutdown:', error);
+         *   }
+         *   process.exit(0);
+         * }
+         */
+        close(): Promise<void>;
+        private clearSubscribedEvents;
+        private registerConsumerGroup;
+        private cleanupAcknowledgedMessages;
+    }
+}
+declare module "src/lib/redis/scheduler" {
+    import { RedisType } from "src/lib/redis/registry";
+    /**
+     * DO NOT USE THIS CLASS IF YOU DON'T KNOW WHAT YOU ARE DOING. This class is
+     * meant to be used internally by the scheduler application
+     */
+    export class ScheduledProcessor {
+        private scheduledMessagesTimer;
+        private _redisPublisher?;
+        private previousTaskCompleted;
+        get redisPublisher(): RedisType;
+        constructor(duration?: number);
+        private processScheduledEvents;
+        getAllScheduledEvents(): Promise<Array<string>>;
+        close(): Promise<void>;
+    }
+}
+declare module "src/lib/publisher" {
+    export { Streams as Publisher } from "src/lib/redis/streams";
+    export { setRedisConnectionSettings as setRedisConfig } from "src/lib/redis/registry";
+    export { ScheduledProcessor as __SCHEDULER_INTERNALS__ } from "src/lib/redis/scheduler";
+}
+declare module "src/index" {
+    export * from "src/lib/publisher";
+}