@ooneex/service 0.0.1 → 0.0.5

package/README.md

@@ -1 +1,505 @@
 # @ooneex/service
+
+A service layer decorator and base interface for business logic encapsulation in TypeScript applications. This package provides the foundation for creating injectable service classes with dependency injection support through the Ooneex container.
+
+![Browser](https://img.shields.io/badge/Browser-Compatible-green?style=flat-square&logo=googlechrome)
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![Deno](https://img.shields.io/badge/Deno-Compatible-blue?style=flat-square&logo=deno)
+![Node.js](https://img.shields.io/badge/Node.js-Compatible-green?style=flat-square&logo=node.js)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **Service Decorator** - Register services with the DI container using decorators
+
+✅ **Interface Contract** - Standard interface for service implementations
+
+✅ **Scope Control** - Configure singleton, transient, or request-scoped services
+
+✅ **Type-Safe** - Full TypeScript support with proper type definitions
+
+✅ **Container Integration** - Seamless integration with @ooneex/container
+
+✅ **Zero Boilerplate** - Simple decorator-based registration
+
+## Installation
+
+### Bun
+```bash
+bun add @ooneex/service
+```
+
+### pnpm
+```bash
+pnpm add @ooneex/service
+```
+
+### Yarn
+```bash
+yarn add @ooneex/service
+```
+
+### npm
+```bash
+npm install @ooneex/service
+```
+
+## Usage
+
+### Basic Service
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+
+interface SendEmailData {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+@decorator.service()
+class EmailService implements IService<SendEmailData> {
+  public async execute(data?: SendEmailData): Promise<void> {
+    if (!data) return;
+    
+    await this.sendEmail(data.to, data.subject, data.body);
+  }
+
+  private async sendEmail(to: string, subject: string, body: string): Promise<void> {
+    // Email sending logic
+    console.log(`Sending email to ${to}: ${subject}`);
+  }
+}
+```
+
+### Resolving Services
+
+```typescript
+import { container } from '@ooneex/container';
+import { EmailService } from './services/EmailService';
+
+// Service is automatically registered by the decorator
+const emailService = container.get(EmailService);
+
+await emailService.execute({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  body: 'Thank you for signing up.'
+});
+```
+
+### Service with Dependencies
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+import { container } from '@ooneex/container';
+import type { ILogger } from '@ooneex/logger';
+import type { ICache } from '@ooneex/cache';
+
+interface ProcessOrderData {
+  orderId: string;
+  items: Array<{ productId: string; quantity: number }>;
+}
+
+@decorator.service()
+class OrderProcessingService implements IService<ProcessOrderData> {
+  private readonly logger = container.get<ILogger>('logger');
+  private readonly cache = container.get<ICache>('cache');
+
+  public async execute(data?: ProcessOrderData): Promise<void> {
+    if (!data) return;
+
+    this.logger.info('Processing order', { orderId: data.orderId });
+
+    // Process order items
+    for (const item of data.items) {
+      await this.processItem(item);
+    }
+
+    // Cache the result
+    await this.cache.set(`order:${data.orderId}:status`, 'processed', 3600);
+
+    this.logger.success('Order processed', { orderId: data.orderId });
+  }
+
+  private async processItem(item: { productId: string; quantity: number }): Promise<void> {
+    // Item processing logic
+  }
+}
+```
+
+### Transient Services
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+import { EContainerScope } from '@ooneex/container';
+
+@decorator.service(EContainerScope.Transient)
+class RequestContextService implements IService {
+  private readonly requestId = crypto.randomUUID();
+
+  public async execute(): Promise<void> {
+    console.log(`Request ID: ${this.requestId}`);
+  }
+
+  public getRequestId(): string {
+    return this.requestId;
+  }
+}
+
+// Each resolution creates a new instance
+const service1 = container.get(RequestContextService);
+const service2 = container.get(RequestContextService);
+console.log(service1.getRequestId() !== service2.getRequestId()); // true
+```
+
+### Request-Scoped Services
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+import { EContainerScope } from '@ooneex/container';
+
+@decorator.service(EContainerScope.Request)
+class UserSessionService implements IService {
+  private userId: string | null = null;
+
+  public async execute(): Promise<void> {
+    // Initialize session
+  }
+
+  public setUserId(id: string): void {
+    this.userId = id;
+  }
+
+  public getUserId(): string | null {
+    return this.userId;
+  }
+}
+```
+
+## API Reference
+
+### Decorators
+
+#### `@decorator.service(scope?)`
+
+Decorator to register a service class with the DI container.
+
+**Parameters:**
+- `scope` - Container scope (default: `EContainerScope.Singleton`)
+  - `Singleton` - Single instance shared across all requests
+  - `Transient` - New instance created on every resolution
+  - `Request` - New instance per request context
+
+**Example:**
+```typescript
+import { decorator } from '@ooneex/service';
+import { EContainerScope } from '@ooneex/container';
+
+// Singleton (default)
+@decorator.service()
+class MySingletonService {}
+
+// Transient
+@decorator.service(EContainerScope.Transient)
+class MyTransientService {}
+
+// Request-scoped
+@decorator.service(EContainerScope.Request)
+class MyRequestService {}
+```
+
+### Interfaces
+
+#### `IService<T>`
+
+Interface for service implementations.
+
+```typescript
+interface IService<T = Record<string, unknown>> {
+  execute: (data?: T) => Promise<void>;
+}
+```
+
+**Type Parameter:**
+- `T` - The type of data the service accepts (default: `Record<string, unknown>`)
+
+**Methods:**
+
+##### `execute(data?: T): Promise<void>`
+
+Execute the service's main logic.
+
+**Parameters:**
+- `data` - Optional data to process
+
+**Returns:** Promise that resolves when execution completes
+
+### Types
+
+#### `ServiceClassType`
+
+Type for service class constructors.
+
+```typescript
+type ServiceClassType = new (...args: any[]) => IService;
+```
+
+## Advanced Usage
+
+### Service Composition
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+import { container } from '@ooneex/container';
+
+interface CreateUserData {
+  email: string;
+  name: string;
+}
+
+@decorator.service()
+class ValidationService {
+  public validateEmail(email: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  }
+}
+
+@decorator.service()
+class NotificationService implements IService<{ userId: string; message: string }> {
+  public async execute(data?: { userId: string; message: string }): Promise<void> {
+    if (!data) return;
+    // Send notification
+  }
+}
+
+@decorator.service()
+class UserCreationService implements IService<CreateUserData> {
+  private readonly validationService = container.get(ValidationService);
+  private readonly notificationService = container.get(NotificationService);
+
+  public async execute(data?: CreateUserData): Promise<void> {
+    if (!data) return;
+
+    // Validate
+    if (!this.validationService.validateEmail(data.email)) {
+      throw new Error('Invalid email');
+    }
+
+    // Create user
+    const userId = await this.createUser(data);
+
+    // Notify
+    await this.notificationService.execute({
+      userId,
+      message: 'Welcome to our platform!'
+    });
+  }
+
+  private async createUser(data: CreateUserData): Promise<string> {
+    // User creation logic
+    return crypto.randomUUID();
+  }
+}
+```
+
+### Service with Controller Integration
+
+```typescript
+import { Route } from '@ooneex/routing';
+import { decorator, type IService } from '@ooneex/service';
+import { container } from '@ooneex/container';
+import type { IController, ContextType } from '@ooneex/controller';
+
+interface SubscriptionData {
+  userId: string;
+  plan: 'basic' | 'premium' | 'enterprise';
+}
+
+@decorator.service()
+class SubscriptionService implements IService<SubscriptionData> {
+  public async execute(data?: SubscriptionData): Promise<void> {
+    if (!data) return;
+    await this.processSubscription(data.userId, data.plan);
+  }
+
+  private async processSubscription(userId: string, plan: string): Promise<void> {
+    // Subscription logic
+  }
+}
+
+@Route.http({
+  name: 'api.subscriptions.create',
+  path: '/api/subscriptions',
+  method: 'POST',
+  description: 'Create a subscription'
+})
+class SubscriptionController implements IController {
+  private readonly subscriptionService = container.get(SubscriptionService);
+
+  public async index(context: ContextType): Promise<IResponse> {
+    const { plan } = context.payload;
+    const userId = context.user?.id;
+
+    if (!userId) {
+      return context.response.exception('Unauthorized', { status: 401 });
+    }
+
+    await this.subscriptionService.execute({ userId, plan });
+
+    return context.response.json({ success: true });
+  }
+}
+```
+
+### Error Handling in Services
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+import { Exception } from '@ooneex/exception';
+
+interface PaymentData {
+  amount: number;
+  currency: string;
+  cardToken: string;
+}
+
+class PaymentException extends Exception {
+  constructor(message: string, public readonly code: string) {
+    super(message, { status: 400, data: { code } });
+    this.name = 'PaymentException';
+  }
+}
+
+@decorator.service()
+class PaymentService implements IService<PaymentData> {
+  public async execute(data?: PaymentData): Promise<void> {
+    if (!data) {
+      throw new PaymentException('Payment data required', 'MISSING_DATA');
+    }
+
+    if (data.amount <= 0) {
+      throw new PaymentException('Invalid amount', 'INVALID_AMOUNT');
+    }
+
+    try {
+      await this.processPayment(data);
+    } catch (error) {
+      throw new PaymentException('Payment processing failed', 'PROCESSING_ERROR');
+    }
+  }
+
+  private async processPayment(data: PaymentData): Promise<void> {
+    // Payment processing logic
+  }
+}
+```
+
+### Generic Service Pattern
+
+```typescript
+import { decorator, type IService } from '@ooneex/service';
+
+interface CrudData<T> {
+  action: 'create' | 'read' | 'update' | 'delete';
+  entity: T;
+  id?: string;
+}
+
+@decorator.service()
+class GenericCrudService<T extends { id?: string }> implements IService<CrudData<T>> {
+  constructor(private readonly entityName: string) {}
+
+  public async execute(data?: CrudData<T>): Promise<void> {
+    if (!data) return;
+
+    switch (data.action) {
+      case 'create':
+        await this.create(data.entity);
+        break;
+      case 'read':
+        await this.read(data.id);
+        break;
+      case 'update':
+        await this.update(data.id, data.entity);
+        break;
+      case 'delete':
+        await this.delete(data.id);
+        break;
+    }
+  }
+
+  private async create(entity: T): Promise<void> {
+    console.log(`Creating ${this.entityName}:`, entity);
+  }
+
+  private async read(id?: string): Promise<void> {
+    console.log(`Reading ${this.entityName}:`, id);
+  }
+
+  private async update(id?: string, entity?: T): Promise<void> {
+    console.log(`Updating ${this.entityName}:`, id, entity);
+  }
+
+  private async delete(id?: string): Promise<void> {
+    console.log(`Deleting ${this.entityName}:`, id);
+  }
+}
+```
+
+### Testing Services
+
+```typescript
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { container } from '@ooneex/container';
+import { EmailService } from './EmailService';
+
+describe('EmailService', () => {
+  let emailService: EmailService;
+
+  beforeEach(() => {
+    emailService = container.get(EmailService);
+  });
+
+  test('should execute without data', async () => {
+    await expect(emailService.execute()).resolves.toBeUndefined();
+  });
+
+  test('should execute with valid data', async () => {
+    await expect(
+      emailService.execute({
+        to: 'test@example.com',
+        subject: 'Test',
+        body: 'Test body'
+      })
+    ).resolves.toBeUndefined();
+  });
+});
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+
+---
+
+Made with ❤️ by the Ooneex team

package/dist/index.d.ts

@@ -1,5 +1,9 @@
+import { EContainerScope } from "@ooneex/container";
 type ServiceClassType = new (...args: any[]) => IService;
-interface IService {
-	execute: () => Promise<void>;
+interface IService<T = Record<string, unknown>> {
+	execute: (data?: T) => Promise<void>;
 }
-export { ServiceClassType, IService };
+declare const decorator: {
+	service: (scope?: EContainerScope) => (target: ServiceClassType) => void;
+};
+export { decorator, ServiceClassType, IService };

package/dist/index.js

@@ -1,2 +1,3 @@
+import{container as o,EContainerScope as t}from"@ooneex/container";var i={service:(e=t.Singleton)=>{return(r)=>{o.add(r,e)}}};export{i as decorator};
 
-//# debugId=BC4C8D5165931A0D64756E2164756E21
+//# debugId=D88AC999764E45C964756E2164756E21

package/dist/index.js.map

@@ -1,9 +1,10 @@
 {
   "version": 3,
-  "sources": [],
+  "sources": ["src/decorators.ts"],
   "sourcesContent": [
+    "import { container, EContainerScope } from \"@ooneex/container\";\nimport type { ServiceClassType } from \"./types\";\n\nexport const decorator = {\n  service: (scope: EContainerScope = EContainerScope.Singleton) => {\n    return (target: ServiceClassType): void => {\n      container.add(target, scope);\n    };\n  },\n};\n"
   ],
-  "mappings": "",
-  "debugId": "BC4C8D5165931A0D64756E2164756E21",
+  "mappings": "AAAA,oBAAS,qBAAW,0BAGb,IAAM,EAAY,CACvB,QAAS,CAAC,EAAyB,EAAgB,YAAc,CAC/D,MAAO,CAAC,IAAmC,CACzC,EAAU,IAAI,EAAQ,CAAK,GAGjC",
+  "debugId": "D88AC999764E45C964756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ooneex/service",
-  "description": "",
-  "version": "0.0.1",
+  "description": "Service layer decorator and base classes for business logic encapsulation with dependency injection support",
+  "version": "0.0.5",
   "type": "module",
   "files": [
     "dist",
@@ -22,13 +22,23 @@
   },
   "license": "MIT",
   "scripts": {
+    "test": "bun test tests",
     "build": "bunup",
     "lint": "tsgo --noEmit && bunx biome lint",
-    "publish:prod": "bun publish --tolerate-republish --access public",
-    "publish:pack": "bun pm pack --destination ./dist",
-    "publish:dry": "bun publish --dry-run"
+    "npm:publish": "bun publish --tolerate-republish --access public"
+  },
+  "dependencies": {
+    "@ooneex/container": "0.0.2"
   },
-  "dependencies": {},
   "devDependencies": {},
-  "peerDependencies": {}
+  "keywords": [
+    "bun",
+    "business-logic",
+    "decorator",
+    "layer",
+    "ooneex",
+    "service",
+    "services",
+    "typescript"
+  ]
 }