feat: first example with services (#1)

* feat: first example with services

* chore: connect on service start

* chore: readme updated

Author: hmbanan666

README.md

@@ -6,7 +6,7 @@ The `@nextorders/queue` is a TypeScript library designed to simplify working wit
 
 ![RabbitMQ Dashboard](https://github.com/user-attachments/assets/b330e911-bc74-404d-9999-c720b04ca9f7)
 
-## Key Features
+## 😨 Key Features
 
 - Type-safe operations with message queues
 - Automatic connection to the RabbitMQ server
@@ -15,97 +15,165 @@ The `@nextorders/queue` is a TypeScript library designed to simplify working wit
 - Support for various message types
 - Flexible connection configuration
 
-## Installation
+## 📦 Installation
 
 You can install the library via npm:
 
 ```bash
 npm install @nextorders/queue
 ```
 
-## Usage
+## 🚀 Usage
 
-Prepare types:
+### 1. Define Event Types
+
+Create type definitions for your events:
 
 ```typescript
 import type { BaseEventMessage } from '@nextorders/queue'
 
 export enum Events {
-  TICKET_MESSAGE_CREATED = 'ticketMessageCreated',
-  OTHER_ACTION = 'otherAction',
+  UserCreated = 'userCreated',
+  EmailSent = 'emailSent',
 }
 
-export type EventMessage = BaseEventMessage<Events>
+export type EventMessage = UserCreated | EmailSent
+
+export interface UserCreated extends BaseEventMessage {
+  event: typeof Events.UserCreated
+  data: {
+    id: string
+    name: string
+    email: string
+  }
+}
 
-export interface TicketMessageCreated extends EventMessage {
-  type: typeof Events.TICKET_MESSAGE_CREATED
+export interface EmailSent extends BaseEventMessage {
+  event: typeof Events.EmailSent
   data: {
-    ticketId: string
-    ticketOwnerId: string
-    messageId: string
-    userId: string
-    userName: string
-    userSurname: string | undefined
-    userText: string
+    email: string
   }
 }
 ```
 
-Create Entities:
+### 2. Create Entities
+
+Define entities that represent your services:
 
 ```typescript
 import { Entity, Repository } from '@nextorders/queue'
+import { Events } from './types'
+
+export class User extends Entity {
+  constructor(repository: Repository) {
+    super({
+      name: 'user',
+      eventsToConsume: [],
+      repository,
+    })
+  }
+}
 
-export class Telegram extends Entity {
+export class Email extends Entity {
   constructor(repository: Repository) {
     super({
-      name: 'telegram',
-      eventsToConsume: ['ticketMessageCreated'],
+      name: 'email',
+      eventsToConsume: [Events.UserCreated],
       repository,
     })
   }
 }
 ```
 
-Create Repository with Entities:
+### 3. Create Repository
+
+Create a repository that manages your entities:
 
 ```typescript
+import type { EventMessage } from './types'
 import { Repository } from '@nextorders/queue'
-import { Telegram, Ticket } from './entities'
+import { Email, User } from './entities'
 
 class QueueRepository extends Repository {
-  telegram: Telegram = new Telegram(this)
-  ticket: Ticket = new Ticket(this)
+  user: User = new User(this)
+  email: Email = new Email(this)
+
+  // Override publish method with proper typing
+  publish<T extends EventMessage>(
+    event: T['event'],
+    data: T['data']
+  ): Promise<void> {
+    return super.publish(event, data)
+  }
 }
 
 export const repository = new QueueRepository()
 ```
 
-On server start (for example in Nuxt server plugin):
+### 4. Connect to RabbitMQ
+
+On service start, connect to your RabbitMQ instance:
 
 ```typescript
-await repository.connect(process.env.QUEUE_URL)
+import { repository } from './repository'
+
+await repository.connect('amqp://guest:guest@localhost:5672')
+```
+
+### 5. Publish Events
+
+Create and publish events from your services:
+
+```typescript
+await repository.publish(Events.UserCreated, {
+  id: newUser.id,
+  name: newUser.name,
+  email: newUser.email,
+})
 ```
 
-And thats it! Use repository in app:
+### 6. Consume Events
+
+Subscribe to events and handle them:
 
 ```typescript
-// Publisher
-await repository.publisher.send({
-  exchange: repository.exchanges.events.exchange,
-  routingKey: Events.TICKET_MESSAGE_CREATED,
-}, body)
-
-// Consumer
-await repository.telegram.consume(async (msg) => {
-  if (msg.type === 'ticketMessageCreated') {
-    return handleTicketMessageCreated(msg) // ack on finish
+import type { UserCreated } from './types'
+import { repository } from './repository'
+import { Events } from './types'
+
+// Define event handlers
+async function handleUserCreated(data: UserCreated['data']): Promise<boolean> {
+  try {
+    await sendEmail(data.email)
+    return true
+  } catch (error) {
+    console.error('Error handling UserCreated event:', error)
+    return false
   }
+}
+
+async function sendEmail(email: string): Promise<void> {
+  console.warn('Sending email to:', email)
+
+  // Publish EmailSent event
+  await repository.publish(Events.EmailSent, { email })
+}
 
-  return queue.ignore()
+// Subscribe to events
+await repository.consume(repository.email.name, {
+  [Events.UserCreated]: handleUserCreated,
 })
 ```
 
-## License
+## 💁‍♂️ Example: Microservices Architecture
+
+Check out the examples/microservices directory for a complete working example with:
+
+- Service 1: User creation service
+- Service 2: Email notification service
+- Shared repository with entities
+- Type-safe event definitions
+
+## 🤝 License
 
 This project is licensed under the MIT License.

examples/microservices/repository/entities/email.ts

@@ -0,0 +1,15 @@
+import type { Repository } from '@nextorders/queue'
+import { Entity } from '@nextorders/queue'
+import { Events } from '../types'
+
+export class Email extends Entity {
+  constructor(repository: Repository) {
+    super({
+      name: 'email',
+      eventsToConsume: [
+        Events.UserCreated,
+      ],
+      repository,
+    })
+  }
+}

examples/microservices/repository/entities/user.ts

@@ -0,0 +1,12 @@
+import type { Repository } from '@nextorders/queue'
+import { Entity } from '@nextorders/queue'
+
+export class User extends Entity {
+  constructor(repository: Repository) {
+    super({
+      name: 'user',
+      eventsToConsume: [],
+      repository,
+    })
+  }
+}

examples/microservices/repository/index.ts

@@ -0,0 +1,15 @@
+import type { EventMessage } from './types'
+import { Repository } from '@nextorders/queue'
+import { Email } from './entities/email'
+import { User } from './entities/user'
+
+class QueueRepository extends Repository {
+  user = new User(this)
+  email = new Email(this)
+
+  async publish<T extends EventMessage>(event: T['event'], data: T['data']) {
+    return super.publish(event, data)
+  }
+}
+
+export const repository = new QueueRepository()

examples/microservices/repository/types.ts

@@ -0,0 +1,30 @@
+import type { BaseEventMessage, Status } from '@nextorders/queue'
+
+// All possible events
+export enum Events {
+  UserCreated = 'userCreated',
+  EmailSent = 'emailSent',
+}
+
+export type EventMessage = UserCreated | EmailSent
+
+export type EventHandler = (msg: EventMessage) => Promise<Status>
+export type EventMessageHandler<T = EventMessage['data']> = (data: T) => Promise<boolean>
+
+export type EventHandlerMap = Record<EventMessage['event'], EventMessageHandler>
+
+export interface UserCreated extends BaseEventMessage {
+  event: typeof Events.UserCreated
+  data: {
+    id: string
+    name: string
+    email: string
+  }
+}
+
+export interface EmailSent extends BaseEventMessage {
+  event: typeof Events.EmailSent
+  data: {
+    email: string
+  }
+}

examples/microservices/service1/index.ts

@@ -0,0 +1,21 @@
+import { repository } from '../repository'
+import { Events } from '../repository/types'
+
+// Service 1: User Service
+const body = {
+  name: 'John Doe',
+  email: '5Tt9o@example.com',
+}
+
+// DB: Save user in database
+const newUser = {
+  id: '123',
+  ...body,
+}
+
+// Publish Event for other services
+repository.publish(Events.UserCreated, {
+  id: newUser.id,
+  name: newUser.name,
+  email: newUser.email,
+})

examples/microservices/service1/service-start.ts

@@ -0,0 +1,5 @@
+// On service start
+import { repository } from '../repository'
+
+// Connect to RabbitMQ
+repository.connect('amqp://guest:guest@localhost:5672')

examples/microservices/service2/index.ts

@@ -0,0 +1,31 @@
+import type { EventHandlerMap, UserCreated } from '../repository/types'
+import { repository } from '../repository'
+import { Events } from '../repository/types'
+
+// Service 2: Email Service
+
+// Consume to Events
+repository.consume(repository.email.name, {
+  [Events.UserCreated]: handleUserCreated,
+} as EventHandlerMap)
+
+// Business logic
+async function handleUserCreated(data: UserCreated['data']): Promise<boolean> {
+  try {
+    // Service logic: Send email
+    await sendEmail(data.email)
+    return true
+  } catch (error) {
+    console.error('Failed to send email:', error)
+    return false
+  }
+}
+
+async function sendEmail(email: string) {
+  console.warn('Sending email to', email)
+
+  // Publish Event for other services
+  await repository.publish(Events.EmailSent, {
+    email,
+  })
+}

examples/microservices/service2/service-start.ts

@@ -0,0 +1,5 @@
+// On service start
+import { repository } from '../repository'
+
+// Connect to RabbitMQ
+repository.connect('amqp://guest:guest@localhost:5672')