@ooneex/repository 0.0.1 → 0.0.4

package/README.md

@@ -1 +1,664 @@
 # @ooneex/repository
+
+A base repository decorator and interface for data access layer abstraction in TypeScript applications. This package provides the foundation for creating injectable repository classes with dependency injection support, standardized CRUD operations, and paginated query results.
+
+![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
+
+✅ **Repository Decorator** - Register repositories with the DI container using decorators
+
+✅ **Interface Contract** - Standard interface for repository implementations
+
+✅ **Paginated Results** - Built-in support for paginated query results
+
+✅ **Scope Control** - Configure singleton, transient, or request-scoped repositories
+
+✅ **Type-Safe** - Full TypeScript support with generic entity and criteria types
+
+✅ **Container Integration** - Seamless integration with @ooneex/container
+
+✅ **Search Support** - Built-in query string parameter for search functionality
+
+## Installation
+
+### Bun
+```bash
+bun add @ooneex/repository
+```
+
+### pnpm
+```bash
+pnpm add @ooneex/repository
+```
+
+### Yarn
+```bash
+yarn add @ooneex/repository
+```
+
+### npm
+```bash
+npm install @ooneex/repository
+```
+
+## Usage
+
+### Basic Repository
+
+```typescript
+import { decorator, type IRepository } from '@ooneex/repository';
+import type { FilterResultType } from '@ooneex/types';
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+interface UserCriteria {
+  email?: string;
+  name?: string;
+  isActive?: boolean;
+}
+
+@decorator.repository()
+class UserRepository implements IRepository<User, UserCriteria> {
+  private connection: unknown = null;
+
+  public async open(): Promise<unknown> {
+    // Open database connection
+    this.connection = await this.createConnection();
+    return this.connection;
+  }
+
+  public async close(): Promise<void> {
+    // Close database connection
+    this.connection = null;
+  }
+
+  public async find(
+    criteria: UserCriteria & { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<User>> {
+    const { page = 1, limit = 10, q, ...filters } = criteria;
+    
+    // Query implementation
+    const users = await this.queryUsers(filters, q);
+    const total = await this.countUsers(filters, q);
+    
+    return {
+      resources: users,
+      total,
+      totalPages: Math.ceil(total / limit),
+      page,
+      limit
+    };
+  }
+
+  private async createConnection(): Promise<unknown> {
+    // Connection logic
+    return {};
+  }
+
+  private async queryUsers(filters: UserCriteria, q?: string): Promise<User[]> {
+    // Query logic
+    return [];
+  }
+
+  private async countUsers(filters: UserCriteria, q?: string): Promise<number> {
+    // Count logic
+    return 0;
+  }
+}
+```
+
+### Resolving Repositories
+
+```typescript
+import { container } from '@ooneex/container';
+import { UserRepository } from './repositories/UserRepository';
+
+// Repository is automatically registered by the decorator
+const userRepo = container.get(UserRepository);
+
+// Open connection
+await userRepo.open();
+
+// Find users with pagination
+const result = await userRepo.find({
+  isActive: true,
+  page: 1,
+  limit: 20,
+  q: 'john'
+});
+
+console.log(result.resources);  // User[]
+console.log(result.total);      // Total count
+console.log(result.totalPages); // Number of pages
+
+// Close connection
+await userRepo.close();
+```
+
+### Repository with TypeORM
+
+```typescript
+import { decorator, type IRepository } from '@ooneex/repository';
+import { container } from '@ooneex/container';
+import type { FilterResultType } from '@ooneex/types';
+import type { IDatabase } from '@ooneex/database';
+import type { Repository } from 'typeorm';
+
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+  category: string;
+}
+
+interface ProductCriteria {
+  category?: string;
+  minPrice?: number;
+  maxPrice?: number;
+}
+
+@decorator.repository()
+class ProductRepository implements IRepository<Product, ProductCriteria> {
+  private readonly database = container.get<IDatabase>('database');
+  private repository: Repository<Product> | null = null;
+
+  public async open(): Promise<Repository<Product>> {
+    this.repository = await this.database.open(ProductEntity);
+    return this.repository;
+  }
+
+  public async close(): Promise<void> {
+    // TypeORM manages connection lifecycle
+  }
+
+  public async find(
+    criteria: ProductCriteria & { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<Product>> {
+    const { page = 1, limit = 10, q, category, minPrice, maxPrice } = criteria;
+    
+    const queryBuilder = this.repository!
+      .createQueryBuilder('product');
+
+    if (category) {
+      queryBuilder.andWhere('product.category = :category', { category });
+    }
+
+    if (minPrice !== undefined) {
+      queryBuilder.andWhere('product.price >= :minPrice', { minPrice });
+    }
+
+    if (maxPrice !== undefined) {
+      queryBuilder.andWhere('product.price <= :maxPrice', { maxPrice });
+    }
+
+    if (q) {
+      queryBuilder.andWhere('product.name ILIKE :q', { q: `%${q}%` });
+    }
+
+    const [resources, total] = await queryBuilder
+      .skip((page - 1) * limit)
+      .take(limit)
+      .getManyAndCount();
+
+    return {
+      resources,
+      total,
+      totalPages: Math.ceil(total / limit),
+      page,
+      limit
+    };
+  }
+}
+```
+
+### Transient Repositories
+
+```typescript
+import { decorator, type IRepository } from '@ooneex/repository';
+import { EContainerScope } from '@ooneex/container';
+
+@decorator.repository(EContainerScope.Transient)
+class TransientRepository implements IRepository {
+  private readonly instanceId = crypto.randomUUID();
+
+  public async open(): Promise<unknown> {
+    console.log(`Opening connection for instance: ${this.instanceId}`);
+    return {};
+  }
+
+  public async close(): Promise<void> {
+    console.log(`Closing connection for instance: ${this.instanceId}`);
+  }
+
+  public async find(criteria: { page?: number; limit?: number; q?: string }) {
+    return {
+      resources: [],
+      total: 0,
+      totalPages: 0,
+      page: criteria.page ?? 1,
+      limit: criteria.limit ?? 10
+    };
+  }
+}
+
+// Each resolution creates a new instance
+const repo1 = container.get(TransientRepository);
+const repo2 = container.get(TransientRepository);
+// repo1 and repo2 have different instanceIds
+```
+
+## API Reference
+
+### Decorators
+
+#### `@decorator.repository(scope?)`
+
+Decorator to register a repository 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/repository';
+import { EContainerScope } from '@ooneex/container';
+
+// Singleton (default)
+@decorator.repository()
+class MySingletonRepository {}
+
+// Transient
+@decorator.repository(EContainerScope.Transient)
+class MyTransientRepository {}
+
+// Request-scoped
+@decorator.repository(EContainerScope.Request)
+class MyRequestRepository {}
+```
+
+### Interfaces
+
+#### `IRepository<T, TCriteria>`
+
+Interface for repository implementations.
+
+```typescript
+interface IRepository<T = unknown, TCriteria = unknown> {
+  open: () => Promise<unknown>;
+  close: () => Promise<void>;
+  find: (criteria: TCriteria & { page?: number; limit?: number; q?: string }) => Promise<FilterResultType<T>>;
+}
+```
+
+**Type Parameters:**
+- `T` - The entity type returned by the repository
+- `TCriteria` - The criteria type for filtering results
+
+**Methods:**
+
+##### `open(): Promise<unknown>`
+
+Open or initialize the data source connection.
+
+**Returns:** Promise resolving to the connection or data source
+
+##### `close(): Promise<void>`
+
+Close the data source connection.
+
+**Returns:** Promise that resolves when connection is closed
+
+##### `find(criteria): Promise<FilterResultType<T>>`
+
+Find entities matching the given criteria with pagination support.
+
+**Parameters:**
+- `criteria` - Filter criteria including:
+  - Custom filter fields from `TCriteria`
+  - `page` - Page number (default: 1)
+  - `limit` - Items per page (default: 10)
+  - `q` - Search query string
+
+**Returns:** Promise resolving to paginated results
+
+### Types
+
+#### `RepositoryClassType`
+
+Type for repository class constructors.
+
+```typescript
+type RepositoryClassType = new (...args: any[]) => IRepository;
+```
+
+#### `FilterResultType<T>`
+
+Type for paginated query results (from @ooneex/types).
+
+```typescript
+type FilterResultType<T> = {
+  resources: T[];
+  total: number;
+  totalPages: number;
+  page: number;
+  limit: number;
+};
+```
+
+## Advanced Usage
+
+### Repository with Caching
+
+```typescript
+import { decorator, type IRepository } from '@ooneex/repository';
+import { container } from '@ooneex/container';
+import type { ICache } from '@ooneex/cache';
+import type { FilterResultType } from '@ooneex/types';
+
+interface Article {
+  id: string;
+  title: string;
+  content: string;
+}
+
+@decorator.repository()
+class CachedArticleRepository implements IRepository<Article> {
+  private readonly cache = container.get<ICache>('cache');
+
+  public async open(): Promise<unknown> {
+    return {};
+  }
+
+  public async close(): Promise<void> {}
+
+  public async find(
+    criteria: { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<Article>> {
+    const cacheKey = `articles:${JSON.stringify(criteria)}`;
+    
+    // Check cache first
+    const cached = await this.cache.get<FilterResultType<Article>>(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    // Query database
+    const result = await this.queryDatabase(criteria);
+
+    // Cache for 5 minutes
+    await this.cache.set(cacheKey, result, 300);
+
+    return result;
+  }
+
+  private async queryDatabase(
+    criteria: { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<Article>> {
+    // Database query logic
+    return {
+      resources: [],
+      total: 0,
+      totalPages: 0,
+      page: criteria.page ?? 1,
+      limit: criteria.limit ?? 10
+    };
+  }
+}
+```
+
+### Repository with Logging
+
+```typescript
+import { decorator, type IRepository } from '@ooneex/repository';
+import { container } from '@ooneex/container';
+import type { ILogger } from '@ooneex/logger';
+import type { FilterResultType } from '@ooneex/types';
+
+@decorator.repository()
+class LoggedRepository<T> implements IRepository<T> {
+  private readonly logger = container.get<ILogger>('logger');
+
+  public async open(): Promise<unknown> {
+    this.logger.info('Opening repository connection');
+    const connection = await this.createConnection();
+    this.logger.success('Repository connection opened');
+    return connection;
+  }
+
+  public async close(): Promise<void> {
+    this.logger.info('Closing repository connection');
+    await this.closeConnection();
+    this.logger.success('Repository connection closed');
+  }
+
+  public async find(
+    criteria: { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<T>> {
+    this.logger.info('Finding resources', { criteria });
+    
+    const startTime = Date.now();
+    const result = await this.queryResources(criteria);
+    const duration = Date.now() - startTime;
+
+    this.logger.info('Found resources', {
+      total: result.total,
+      page: result.page,
+      duration: `${duration}ms`
+    });
+
+    return result;
+  }
+
+  private async createConnection(): Promise<unknown> {
+    return {};
+  }
+
+  private async closeConnection(): Promise<void> {}
+
+  private async queryResources(
+    criteria: { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<T>> {
+    return {
+      resources: [],
+      total: 0,
+      totalPages: 0,
+      page: criteria.page ?? 1,
+      limit: criteria.limit ?? 10
+    };
+  }
+}
+```
+
+### Abstract Base Repository
+
+```typescript
+import { type IRepository } from '@ooneex/repository';
+import type { FilterResultType } from '@ooneex/types';
+
+abstract class BaseRepository<T, TCriteria = Record<string, unknown>> 
+  implements IRepository<T, TCriteria> {
+  
+  protected connection: unknown = null;
+
+  public async open(): Promise<unknown> {
+    this.connection = await this.createConnection();
+    return this.connection;
+  }
+
+  public async close(): Promise<void> {
+    await this.closeConnection();
+    this.connection = null;
+  }
+
+  public abstract find(
+    criteria: TCriteria & { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<T>>;
+
+  protected abstract createConnection(): Promise<unknown>;
+  protected abstract closeConnection(): Promise<void>;
+
+  protected paginate<R>(
+    resources: R[],
+    total: number,
+    page: number,
+    limit: number
+  ): FilterResultType<R> {
+    return {
+      resources,
+      total,
+      totalPages: Math.ceil(total / limit),
+      page,
+      limit
+    };
+  }
+}
+
+// Usage
+@decorator.repository()
+class OrderRepository extends BaseRepository<Order, OrderCriteria> {
+  protected async createConnection(): Promise<unknown> {
+    // Implementation
+    return {};
+  }
+
+  protected async closeConnection(): Promise<void> {
+    // Implementation
+  }
+
+  public async find(
+    criteria: OrderCriteria & { page?: number; limit?: number; q?: string }
+  ): Promise<FilterResultType<Order>> {
+    const { page = 1, limit = 10 } = criteria;
+    
+    const orders = await this.queryOrders(criteria);
+    const total = await this.countOrders(criteria);
+
+    return this.paginate(orders, total, page, limit);
+  }
+}
+```
+
+### Controller Integration
+
+```typescript
+import { Route } from '@ooneex/routing';
+import { container } from '@ooneex/container';
+import type { IController, ContextType } from '@ooneex/controller';
+import { UserRepository } from './repositories/UserRepository';
+
+@Route.http({
+  name: 'api.users.list',
+  path: '/api/users',
+  method: 'GET',
+  description: 'List users with pagination'
+})
+class UserListController implements IController {
+  private readonly userRepository = container.get(UserRepository);
+
+  public async index(context: ContextType): Promise<IResponse> {
+    const { page, limit, q, ...filters } = context.queries;
+
+    const result = await this.userRepository.find({
+      ...filters,
+      page: Number(page) || 1,
+      limit: Number(limit) || 10,
+      q: q as string
+    });
+
+    return context.response.json(result);
+  }
+}
+```
+
+### Testing Repositories
+
+```typescript
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { container } from '@ooneex/container';
+import { UserRepository } from './UserRepository';
+
+describe('UserRepository', () => {
+  let repository: UserRepository;
+
+  beforeEach(async () => {
+    repository = container.get(UserRepository);
+    await repository.open();
+  });
+
+  afterEach(async () => {
+    await repository.close();
+  });
+
+  test('should return paginated results', async () => {
+    const result = await repository.find({ page: 1, limit: 10 });
+
+    expect(result).toHaveProperty('resources');
+    expect(result).toHaveProperty('total');
+    expect(result).toHaveProperty('totalPages');
+    expect(result).toHaveProperty('page', 1);
+    expect(result).toHaveProperty('limit', 10);
+    expect(Array.isArray(result.resources)).toBe(true);
+  });
+
+  test('should filter by criteria', async () => {
+    const result = await repository.find({
+      isActive: true,
+      page: 1,
+      limit: 10
+    });
+
+    expect(result.resources.every(user => user.isActive)).toBe(true);
+  });
+
+  test('should search with query string', async () => {
+    const result = await repository.find({
+      q: 'john',
+      page: 1,
+      limit: 10
+    });
+
+    expect(result.resources.every(
+      user => user.name.toLowerCase().includes('john')
+    )).toBe(true);
+  });
+});
+```
+
+## 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,10 +1,9 @@
+import { EContainerScope } from "@ooneex/container";
 import { FilterResultType } from "@ooneex/types";
 type RepositoryClassType = new (...args: any[]) => IRepository;
 interface IRepository<
 	T = unknown,
-	TCriteria = unknown,
-	TSaveOptions = unknown,
-	TDeleteResult = unknown
+	TCriteria = unknown
 > {
 	open: () => Promise<unknown>;
 	close: () => Promise<void>;
@@ -13,13 +12,8 @@ interface IRepository<
 		limit?: number;
 		q?: string;
 	}) => Promise<FilterResultType<T>>;
-	findOne: (id: string) => Promise<T | null>;
-	findOneBy: (criteria: TCriteria) => Promise<T | null>;
-	create: (entity: T, options?: TSaveOptions) => Promise<T>;
-	createMany: (entities: T[], options?: TSaveOptions) => Promise<T[]>;
-	update: (entity: T, options?: TSaveOptions) => Promise<T>;
-	updateMany: (entities: T[], options?: TSaveOptions) => Promise<T[]>;
-	delete: (criteria: TCriteria | TCriteria[]) => Promise<TDeleteResult>;
-	count: (criteria?: TCriteria | TCriteria[]) => Promise<number>;
 }
-export { RepositoryClassType, IRepository };
+declare const decorator: {
+	repository: (scope?: EContainerScope) => (target: RepositoryClassType) => void;
+};
+export { decorator, RepositoryClassType, IRepository };

package/dist/index.js

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

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 { RepositoryClassType } from \"./types\";\n\nexport const decorator = {\n  repository: (scope: EContainerScope = EContainerScope.Singleton) => {\n    return (target: RepositoryClassType): void => {\n      container.add(target, scope);\n    };\n  },\n};\n"
   ],
-  "mappings": "",
-  "debugId": "BC4C8D5165931A0D64756E2164756E21",
+  "mappings": "AAAA,oBAAS,qBAAW,0BAGb,IAAM,EAAY,CACvB,WAAY,CAAC,EAAyB,EAAgB,YAAc,CAClE,MAAO,CAAC,IAAsC,CAC5C,EAAU,IAAI,EAAQ,CAAK,GAGjC",
+  "debugId": "1D18A0E1C9F4487464756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ooneex/repository",
-  "description": "",
-  "version": "0.0.1",
+  "description": "Base repository classes and decorators for data access layer with dependency injection support",
+  "version": "0.0.4",
   "type": "module",
   "files": [
     "dist",
@@ -25,11 +25,22 @@
     "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"
+    "publish": "bun publish --access public || true"
   },
-  "dependencies": {},
-  "devDependencies": {},
-  "peerDependencies": {}
+  "dependencies": {
+    "@ooneex/container": "0.0.2"
+  },
+  "devDependencies": {
+    "@ooneex/types": "0.0.1"
+  },
+  "keywords": [
+    "bun",
+    "dao",
+    "data-access",
+    "decorator",
+    "ooneex",
+    "pattern",
+    "repository",
+    "typescript"
+  ]
 }