@geekmidas/events 0.0.1

package/dist/types-DEGUg5BA.d.cts

@@ -0,0 +1,65 @@
+import { InferStandardSchema } from "@geekmidas/schema";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/types.d.ts
+
+/**
+ * Represents a publishable event message with a type and payload.
+ *
+ * @template TType - The event type/name (e.g., 'user.created')
+ * @template TPayload - The event payload data
+ */
+type PublishableMessage<TType extends string, TPayload> = {
+  type: TType;
+  payload: TPayload;
+};
+/**
+ * Event publisher/subscriber types
+ */
+declare enum EventPublisherType {
+  Basic = "basic",
+  EventBridge = "eventbridge",
+  SQS = "sqs",
+  SNS = "sns",
+  Kafka = "kafka",
+  RabbitMQ = "rabbitmq",
+}
+/**
+ * Base interface for event connections
+ * Connections manage the underlying transport (RabbitMQ channel, SQS client, etc.)
+ */
+interface EventConnection {
+  readonly type: EventPublisherType;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  isConnected(): boolean;
+}
+/**
+ * Interface for event publishers that handle the actual publishing of events.
+ * Implementations can send to EventBridge, SQS, Kafka, or any other event system.
+ *
+ * @template TMessage - The union type of all publishable messages
+ */
+type EventPublisher<TMessage extends PublishableMessage<string, any>> = {
+  publish: (message: TMessage[]) => Promise<void>;
+};
+/**
+ * Interface for event subscribers that handle receiving and processing events.
+ *
+ * @template TMessage - The union type of all publishable messages
+ */
+type EventSubscriber<TMessage extends PublishableMessage<string, any>> = {
+  subscribe: (messages: TMessage['type'][], listener: (payload: TMessage) => Promise<void>) => Promise<void>;
+};
+/**
+ * Utility type to extract the message from EventPublisher
+ */
+type ExtractPublisherMessage<T> = T extends EventPublisher<infer M> ? M : never;
+type MappedEvent<T extends EventPublisher<any> | undefined, OutSchema extends StandardSchemaV1 | undefined = undefined> = {
+  type: ExtractPublisherMessage<T>['type'];
+  payload: (ctx: InferStandardSchema<OutSchema>) => ExtractPublisherMessage<T>['payload'];
+  when?: (ctx: InferStandardSchema<OutSchema>) => boolean;
+};
+//#endregion
+export { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, ExtractPublisherMessage, MappedEvent, PublishableMessage };
+//# sourceMappingURL=types-DEGUg5BA.d.cts.map

package/dist/types.cjs

@@ -0,0 +1,3 @@
+const require_types = require('./types-CvSMEO5z.cjs');
+
+exports.EventPublisherType = require_types.EventPublisherType;

package/dist/types.d.cts

@@ -0,0 +1,2 @@
+import { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, ExtractPublisherMessage, MappedEvent, PublishableMessage } from "./types-DEGUg5BA.cjs";
+export { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, ExtractPublisherMessage, MappedEvent, PublishableMessage };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, ExtractPublisherMessage, MappedEvent, PublishableMessage } from "./types-D0g-o6wX.mjs";
+export { EventConnection, EventPublisher, EventPublisherType, EventSubscriber, ExtractPublisherMessage, MappedEvent, PublishableMessage };

package/dist/types.mjs

@@ -0,0 +1,3 @@
+import { EventPublisherType } from "./types-B63qHVOG.mjs";
+
+export { EventPublisherType };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@geekmidas/events",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./basic": {
+      "types": "./dist/basic/index.d.ts",
+      "import": "./dist/basic/index.mjs",
+      "require": "./dist/basic/index.cjs"
+    },
+    "./rabbitmq": {
+      "types": "./dist/rabbitmq/index.d.ts",
+      "import": "./dist/rabbitmq/index.mjs",
+      "require": "./dist/rabbitmq/index.cjs"
+    },
+    "./sqs": {
+      "types": "./dist/sqs/index.d.ts",
+      "import": "./dist/sqs/index.mjs",
+      "require": "./dist/sqs/index.cjs"
+    },
+    "./sns": {
+      "types": "./dist/sns/index.d.ts",
+      "import": "./dist/sns/index.mjs",
+      "require": "./dist/sns/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "lodash.chunk": "~4.2.0",
+    "@geekmidas/schema": "0.0.1"
+  },
+  "peerDependencies": {
+    "amqplib": "^0.10.3",
+    "@aws-sdk/client-sqs": "~3.908.0",
+    "@aws-sdk/client-sns": "~3.908.0"
+  },
+  "devDependencies": {
+    "@types/amqplib": "~0.10.7",
+    "@types/lodash.chunk": "~4.2.0"
+  }
+}

package/src/EventConnection.ts

@@ -0,0 +1,39 @@
+import type { EventConnection } from './types';
+import { EventPublisherType } from './types';
+
+export class EventConnectionFactory {
+  /**
+   * Create an EventConnection from a connection string
+   * Dynamically imports the appropriate connection implementation
+   */
+  static async fromConnectionString(
+    connectionStr: string,
+  ): Promise<EventConnection> {
+    const url = new URL(connectionStr);
+    const protocol = url.protocol.replace(':', '') as EventPublisherType;
+
+    switch (protocol) {
+      case EventPublisherType.Basic: {
+        const { BasicConnection } = await import('./basic');
+        return BasicConnection.fromConnectionString(connectionStr);
+      }
+      case EventPublisherType.RabbitMQ: {
+        const { RabbitMQConnection } = await import('./rabbitmq');
+        return RabbitMQConnection.fromConnectionString(connectionStr);
+      }
+      case EventPublisherType.SQS: {
+        const { SQSConnection } = await import('./sqs');
+        return SQSConnection.fromConnectionString(connectionStr);
+      }
+      case EventPublisherType.SNS: {
+        const { SNSConnection } = await import('./sns');
+        return SNSConnection.fromConnectionString(connectionStr);
+      }
+      default:
+        throw new Error(`Unsupported connection type: ${protocol}`);
+    }
+  }
+}
+
+export { EventPublisherType } from './types';
+export type { EventConnection } from './types';

package/src/Publisher.ts

@@ -0,0 +1,87 @@
+import type {
+  EventConnection,
+  EventPublisher,
+  PublishableMessage,
+} from './types';
+import { EventPublisherType } from './types';
+
+export class Publisher {
+  /**
+   * Create a publisher from a connection string
+   * This creates both a connection and a publisher
+   */
+  static async fromConnectionString<
+    TMessage extends PublishableMessage<string, any>,
+  >(
+    connectionStr: EventPublisherConnectionString,
+  ): Promise<EventPublisher<TMessage>> {
+    const url = new URL(connectionStr);
+    switch (url.protocol.replace(':', '')) {
+      case EventPublisherType.Basic: {
+        const { BasicConnection, BasicPublisher } = await import('./basic');
+        const connection =
+          await BasicConnection.fromConnectionString(connectionStr);
+        return new BasicPublisher<TMessage>(connection);
+      }
+      case EventPublisherType.RabbitMQ: {
+        const { RabbitMQPublisher } = await import('./rabbitmq');
+        return RabbitMQPublisher.fromConnectionString<TMessage>(connectionStr);
+      }
+      case EventPublisherType.SQS: {
+        const { SQSPublisher } = await import('./sqs');
+        return SQSPublisher.fromConnectionString<TMessage>(connectionStr);
+      }
+      case EventPublisherType.SNS: {
+        const { SNSPublisher } = await import('./sns');
+        return SNSPublisher.fromConnectionString<TMessage>(connectionStr);
+      }
+      // Future implementations for EventBridge, Kafka, etc.
+      default:
+        throw new Error(`Unsupported event publisher type: ${url.protocol}`);
+    }
+  }
+
+  /**
+   * Create a publisher from an existing connection
+   * This allows sharing connections between publishers and subscribers
+   */
+  static async fromConnection<TMessage extends PublishableMessage<string, any>>(
+    connection: EventConnection,
+  ): Promise<EventPublisher<TMessage>> {
+    switch (connection.type) {
+      case EventPublisherType.Basic: {
+        const { BasicPublisher } = await import('./basic');
+        const { BasicConnection } = await import('./basic');
+        return new BasicPublisher<TMessage>(
+          connection as InstanceType<typeof BasicConnection>,
+        );
+      }
+      case EventPublisherType.RabbitMQ: {
+        const { RabbitMQPublisher } = await import('./rabbitmq');
+        const { RabbitMQConnection } = await import('./rabbitmq');
+        return new RabbitMQPublisher<TMessage>(
+          connection as InstanceType<typeof RabbitMQConnection>,
+        );
+      }
+      case EventPublisherType.SQS: {
+        const { SQSPublisher } = await import('./sqs');
+        const { SQSConnection } = await import('./sqs');
+        return new SQSPublisher<TMessage>(
+          connection as InstanceType<typeof SQSConnection>,
+        );
+      }
+      case EventPublisherType.SNS: {
+        const { SNSPublisher } = await import('./sns');
+        const { SNSConnection } = await import('./sns');
+        return new SNSPublisher<TMessage>(
+          connection as InstanceType<typeof SNSConnection>,
+        );
+      }
+      default:
+        throw new Error(`Unsupported connection type: ${connection.type}`);
+    }
+  }
+}
+
+export type EventPublisherConnectionString =
+  `${EventPublisherType}://${string}`;

package/src/Subscriber.ts

@@ -0,0 +1,102 @@
+import type {
+  EventConnection,
+  EventSubscriber,
+  PublishableMessage,
+} from './types';
+import { EventPublisherType } from './types';
+
+export class Subscriber {
+  /**
+   * Create a subscriber from a connection string
+   * This creates both a connection and a subscriber
+   */
+  static async fromConnectionString<
+    TMessage extends PublishableMessage<string, any>,
+  >(
+    connectionStr: EventSubscriberConnectionString,
+  ): Promise<EventSubscriber<TMessage>> {
+    const url = new URL(connectionStr);
+    switch (url.protocol.replace(':', '')) {
+      case EventPublisherType.Basic: {
+        const { BasicConnection, BasicSubscriber } = await import('./basic');
+        const connection =
+          await BasicConnection.fromConnectionString(connectionStr);
+        return new BasicSubscriber<TMessage>(connection);
+      }
+      case EventPublisherType.RabbitMQ: {
+        const { RabbitMQSubscriber } = await import('./rabbitmq');
+        return RabbitMQSubscriber.fromConnectionString<TMessage>(connectionStr);
+      }
+      case EventPublisherType.SNS: {
+        const { SNSSubscriber } = await import('./sns');
+        return SNSSubscriber.fromConnectionString<TMessage>(connectionStr);
+      }
+      case EventPublisherType.SQS: {
+        const url = new URL(connectionStr);
+        const topicArn = url.searchParams.get('topicArn');
+
+        // If topicArn is present, use managed SNS→SQS subscription
+        if (topicArn) {
+          const { SNSSubscriber } = await import('./sns');
+          // Convert SQS connection string to SNS connection string
+          const snsConnectionStr = connectionStr.replace('sqs://', 'sns://');
+          return SNSSubscriber.fromConnectionString<TMessage>(snsConnectionStr);
+        }
+
+        // Direct SQS subscriber
+        const { SQSSubscriber } = await import('./sqs');
+        const { SQSConnection } = await import('./sqs');
+        const connection =
+          await SQSConnection.fromConnectionString(connectionStr);
+        return new SQSSubscriber<TMessage>(connection);
+      }
+      // Future implementations for EventBridge, Kafka, etc.
+      default:
+        throw new Error(`Unsupported event subscriber type: ${url.protocol}`);
+    }
+  }
+
+  /**
+   * Create a subscriber from an existing connection
+   * This allows sharing connections between publishers and subscribers
+   */
+  static async fromConnection<TMessage extends PublishableMessage<string, any>>(
+    connection: EventConnection,
+  ): Promise<EventSubscriber<TMessage>> {
+    switch (connection.type) {
+      case EventPublisherType.Basic: {
+        const { BasicSubscriber } = await import('./basic');
+        const { BasicConnection } = await import('./basic');
+        return new BasicSubscriber<TMessage>(
+          connection as InstanceType<typeof BasicConnection>,
+        );
+      }
+      case EventPublisherType.RabbitMQ: {
+        const { RabbitMQSubscriber } = await import('./rabbitmq');
+        const { RabbitMQConnection } = await import('./rabbitmq');
+        return new RabbitMQSubscriber<TMessage>(
+          connection as InstanceType<typeof RabbitMQConnection>,
+        );
+      }
+      case EventPublisherType.SNS: {
+        const { SNSSubscriber } = await import('./sns');
+        const { SNSConnection } = await import('./sns');
+        return new SNSSubscriber<TMessage>(
+          connection as InstanceType<typeof SNSConnection>,
+        );
+      }
+      case EventPublisherType.SQS: {
+        const { SQSSubscriber } = await import('./sqs');
+        const { SQSConnection } = await import('./sqs');
+        return new SQSSubscriber<TMessage>(
+          connection as InstanceType<typeof SQSConnection>,
+        );
+      }
+      default:
+        throw new Error(`Unsupported connection type: ${connection.type}`);
+    }
+  }
+}
+
+export type EventSubscriberConnectionString =
+  `${EventPublisherType}://${string}`;

package/src/__tests__/Subscriber.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { Subscriber } from '../Subscriber';
+import { SNSSubscriber } from '../sns/SNSSubscriber';
+import { SQSSubscriber } from '../sqs/SQSSubscriber';
+import type { PublishableMessage } from '../types';
+
+type TestMessage = PublishableMessage<'test.event', { data: string }>;
+
+describe('Subscriber', () => {
+  describe('fromConnectionString', () => {
+    it('should create SQS subscriber without topicArn', async () => {
+      const connectionStr =
+        'sqs://?queueUrl=https://sqs.us-east-1.amazonaws.com/123456789/test-queue&region=us-east-1&endpoint=http://localhost:4566';
+
+      const subscriber =
+        await Subscriber.fromConnectionString<TestMessage>(connectionStr);
+
+      expect(subscriber).toBeInstanceOf(SQSSubscriber);
+    });
+
+    it('should create SNS subscriber when topicArn is present in SQS connection string', async () => {
+      const connectionStr =
+        'sqs://?topicArn=arn:aws:sns:us-east-1:123456789:test-topic&queueName=test-queue&region=us-east-1&endpoint=http://localhost:4566&accessKeyId=test&secretAccessKey=test';
+
+      const subscriber =
+        await Subscriber.fromConnectionString<TestMessage>(connectionStr);
+
+      expect(subscriber).toBeInstanceOf(SNSSubscriber);
+    });
+
+    it('should create SNS subscriber from sns:// connection string', async () => {
+      const connectionStr =
+        'sns://?topicArn=arn:aws:sns:us-east-1:123456789:test-topic&region=us-east-1&endpoint=http://localhost:4566&accessKeyId=test&secretAccessKey=test';
+
+      const subscriber =
+        await Subscriber.fromConnectionString<TestMessage>(connectionStr);
+
+      expect(subscriber).toBeInstanceOf(SNSSubscriber);
+    });
+  });
+});

package/src/basic/BasicConnection.ts

@@ -0,0 +1,47 @@
+import { EventEmitter } from 'node:events';
+import type { EventConnection } from '../types';
+import { EventPublisherType } from '../types';
+
+export class BasicConnection implements EventConnection {
+  readonly type = EventPublisherType.Basic;
+  private emitter: EventEmitter;
+  private connected = false;
+
+  constructor() {
+    this.emitter = new EventEmitter();
+  }
+
+  /**
+   * Create a BasicConnection from a connection string
+   * Format: basic://
+   */
+  static async fromConnectionString(
+    _connectionString: string,
+  ): Promise<BasicConnection> {
+    // Basic connection doesn't need any configuration
+    const connection = new BasicConnection();
+    await connection.connect();
+    return connection;
+  }
+
+  async connect(): Promise<void> {
+    this.connected = true;
+  }
+
+  async close(): Promise<void> {
+    this.emitter.removeAllListeners();
+    this.connected = false;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /**
+   * Get the underlying EventEmitter
+   * Used by BasicPublisher and BasicSubscriber
+   */
+  get eventEmitter(): EventEmitter {
+    return this.emitter;
+  }
+}

package/src/basic/BasicPublisher.ts

@@ -0,0 +1,15 @@
+import type { EventPublisher, PublishableMessage } from '../types';
+import type { BasicConnection } from './BasicConnection';
+
+export class BasicPublisher<TMessage extends PublishableMessage<string, any>>
+  implements EventPublisher<TMessage>
+{
+  constructor(private connection: BasicConnection) {}
+
+  async publish(messages: TMessage[]) {
+    const emitter = this.connection.eventEmitter;
+    for (const message of messages) {
+      emitter.emit(message.type, message);
+    }
+  }
+}

package/src/basic/BasicSubscriber.ts

@@ -0,0 +1,24 @@
+import type { EventSubscriber, PublishableMessage } from '../types';
+import type { BasicConnection } from './BasicConnection';
+
+export class BasicSubscriber<TMessage extends PublishableMessage<string, any>>
+  implements EventSubscriber<TMessage>
+{
+  constructor(private connection: BasicConnection) {}
+
+  async subscribe(
+    messages: TMessage['type'][],
+    listener: (payload: TMessage) => Promise<void>,
+  ): Promise<void> {
+    const emitter = this.connection.eventEmitter;
+
+    for (const messageType of messages) {
+      emitter.on(messageType, (message: TMessage) => {
+        listener(message).catch((error) => {
+          // Log error but don't throw to prevent unhandled promise rejections
+          console.error(`Error processing message ${messageType}:`, error);
+        });
+      });
+    }
+  }
+}

package/src/basic/__tests__/BasicSubscriber.spec.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+import type { PublishableMessage } from '../../types';
+import { BasicConnection } from '../BasicConnection';
+import { BasicPublisher } from '../BasicPublisher';
+import { BasicSubscriber } from '../BasicSubscriber';
+
+type TestMessage = PublishableMessage<'user.created' | 'user.updated', any>;
+
+describe('BasicSubscriber', () => {
+  it('should receive published messages', async () => {
+    const connection = new BasicConnection();
+    await connection.connect();
+
+    const publisher = new BasicPublisher<TestMessage>(connection);
+    const subscriber = new BasicSubscriber<TestMessage>(connection);
+
+    const receivedMessages: TestMessage[] = [];
+
+    await subscriber.subscribe(['user.created'], async (message) => {
+      receivedMessages.push(message);
+    });
+
+    await publisher.publish([
+      { type: 'user.created', payload: { userId: '123' } },
+    ]);
+
+    // Give event emitter time to process
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(receivedMessages).toHaveLength(1);
+    expect(receivedMessages[0]).toEqual({
+      type: 'user.created',
+      payload: { userId: '123' },
+    });
+
+    await connection.close();
+  });
+
+  it('should receive multiple message types', async () => {
+    const connection = new BasicConnection();
+    await connection.connect();
+
+    const publisher = new BasicPublisher<TestMessage>(connection);
+    const subscriber = new BasicSubscriber<TestMessage>(connection);
+
+    const receivedMessages: TestMessage[] = [];
+
+    await subscriber.subscribe(
+      ['user.created', 'user.updated'],
+      async (message) => {
+        receivedMessages.push(message);
+      },
+    );
+
+    await publisher.publish([
+      { type: 'user.created', payload: { userId: '1' } },
+      { type: 'user.updated', payload: { userId: '2' } },
+      { type: 'user.created', payload: { userId: '3' } },
+    ]);
+
+    // Give event emitter time to process
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(receivedMessages).toHaveLength(3);
+    expect(receivedMessages[0].type).toBe('user.created');
+    expect(receivedMessages[1].type).toBe('user.updated');
+    expect(receivedMessages[2].type).toBe('user.created');
+
+    await connection.close();
+  });
+
+  it('should only receive subscribed message types', async () => {
+    const connection = new BasicConnection();
+    await connection.connect();
+
+    const publisher = new BasicPublisher<TestMessage>(connection);
+    const subscriber = new BasicSubscriber<TestMessage>(connection);
+
+    const receivedMessages: TestMessage[] = [];
+
+    // Only subscribe to user.created
+    await subscriber.subscribe(['user.created'], async (message) => {
+      receivedMessages.push(message);
+    });
+
+    await publisher.publish([
+      { type: 'user.created', payload: { userId: '1' } },
+      { type: 'user.updated', payload: { userId: '2' } },
+      { type: 'user.created', payload: { userId: '3' } },
+    ]);
+
+    // Give event emitter time to process
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(receivedMessages).toHaveLength(2);
+    expect(receivedMessages.every((m) => m.type === 'user.created')).toBe(true);
+
+    await connection.close();
+  });
+
+  it('should handle multiple subscribers on same connection', async () => {
+    const connection = new BasicConnection();
+    await connection.connect();
+
+    const publisher = new BasicPublisher<TestMessage>(connection);
+    const subscriber1 = new BasicSubscriber<TestMessage>(connection);
+    const subscriber2 = new BasicSubscriber<TestMessage>(connection);
+
+    const messages1: TestMessage[] = [];
+    const messages2: TestMessage[] = [];
+
+    await subscriber1.subscribe(['user.created'], async (message) => {
+      messages1.push(message);
+    });
+
+    await subscriber2.subscribe(['user.created'], async (message) => {
+      messages2.push(message);
+    });
+
+    await publisher.publish([
+      { type: 'user.created', payload: { userId: '123' } },
+    ]);
+
+    // Give event emitter time to process
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Both subscribers should receive the message
+    expect(messages1).toHaveLength(1);
+    expect(messages2).toHaveLength(1);
+
+    await connection.close();
+  });
+
+  it('should handle async listener errors gracefully', async () => {
+    const connection = new BasicConnection();
+    await connection.connect();
+
+    const publisher = new BasicPublisher<TestMessage>(connection);
+    const subscriber = new BasicSubscriber<TestMessage>(connection);
+
+    const receivedMessages: TestMessage[] = [];
+
+    await subscriber.subscribe(['user.created'], async (message) => {
+      if (message.payload.userId === '2') {
+        throw new Error('Test error');
+      }
+      receivedMessages.push(message);
+    });
+
+    await publisher.publish([
+      { type: 'user.created', payload: { userId: '1' } },
+      { type: 'user.created', payload: { userId: '2' } },
+      { type: 'user.created', payload: { userId: '3' } },
+    ]);
+
+    // Give event emitter time to process
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Should receive messages 1 and 3 (2 throws error)
+    expect(receivedMessages).toHaveLength(2);
+    expect(receivedMessages[0].payload.userId).toBe('1');
+    expect(receivedMessages[1].payload.userId).toBe('3');
+
+    await connection.close();
+  });
+});

package/src/basic/index.ts

@@ -0,0 +1,3 @@
+export { BasicConnection } from './BasicConnection';
+export { BasicPublisher } from './BasicPublisher';
+export { BasicSubscriber } from './BasicSubscriber';