@ciscode/database-kit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- MySQL adapter support
+- Redis caching layer
+- Query builder interface
+- Soft delete built-in support
+- Audit logging
+
+---
+
+## [1.0.0] - 2026-01-31
+
+### 🎉 Initial Release
+
+Complete refactoring following CISCODE AuthKit patterns and best practices.
+
+### Added
+
+#### Core Features
+
+- **Unified Repository API** - Same interface for MongoDB and PostgreSQL
+  - `create(data)` - Create new records
+  - `findById(id)` - Find by primary key
+  - `findAll(filter)` - Find all matching records
+  - `findPage(options)` - Paginated queries
+  - `updateById(id, data)` - Update by primary key
+  - `deleteById(id)` - Delete by primary key
+  - `count(filter)` - Count matching records
+  - `exists(filter)` - Check if records exist
+
+#### NestJS Integration
+
+- **DatabaseKitModule** - NestJS module with DI support
+  - `forRoot(options)` - Synchronous configuration
+  - `forRootAsync(options)` - Async configuration with factory
+  - `forFeature(token, config)` - Multiple database connections
+
+#### Database Adapters
+
+- **MongoAdapter** - MongoDB support via Mongoose
+  - Connection pooling
+  - Auto-reconnection
+  - Lean queries by default
+- **PostgresAdapter** - PostgreSQL support via Knex
+  - Connection pooling
+  - Advanced filter operators (gt, gte, lt, lte, in, nin, like, etc.)
+  - Column whitelisting for security
+
+#### Services
+
+- **DatabaseService** - Main facade for database operations
+  - Unified interface for both databases
+  - Connection lifecycle management
+  - Repository factory methods
+- **LoggerService** - Structured logging
+  - NestJS Logger integration
+  - Context-aware logging
+
+#### Middleware
+
+- **@InjectDatabase()** - Decorator for injecting DatabaseService
+- **@InjectDatabaseByToken(token)** - Decorator for named connections
+
+#### Filters
+
+- **DatabaseExceptionFilter** - Global exception handling
+  - MongoDB error parsing
+  - PostgreSQL error parsing
+  - Consistent error response format
+
+#### Utilities
+
+- Pagination helpers (`normalizePaginationOptions`, `calculatePagination`)
+- Validation helpers (`isValidMongoId`, `isValidUuid`, `sanitizeFilter`)
+
+#### Configuration
+
+- Environment-driven configuration
+- Config validation with fail-fast errors
+- Connection string validation
+
+#### Documentation
+
+- Comprehensive README with examples
+- SECURITY.md with vulnerability reporting guidelines
+- TROUBLESHOOTING.md with common issues
+- CONTRIBUTING.md with development guidelines
+- copilot-instructions.md for AI-assisted development
+
+### Changed
+
+#### Architecture Improvements
+
+- Restructured to follow AuthKit patterns
+- Separated concerns into adapters, services, and contracts
+- Moved from `core/` structure to proper layer separation
+
+#### Naming Conventions
+
+- All files now use kebab-case with suffixes
+- Consistent class naming (PascalCase)
+- Consistent function naming (camelCase)
+
+#### TypeScript Improvements
+
+- Added path aliases for clean imports
+- Stricter TypeScript configuration
+- Full type coverage with no implicit any
+
+### Fixed
+
+- N/A (initial release)
+
+### Security
+
+- Column whitelisting for PostgreSQL repositories
+- Parameterized queries to prevent injection
+- Error sanitization in exception filter
+- No credentials in error messages
+
+### Breaking Changes
+
+- N/A (initial release)
+
+---
+
+## Pre-1.0 History
+
+### [0.x.x] - Development
+
+- Initial development and prototyping
+- Basic MongoDB and PostgreSQL adapters
+- Simple NestJS module integration
+
+---
+
+## Migration Guide
+
+### From Pre-1.0 to 1.0.0
+
+If you were using a pre-release version, follow these steps:
+
+1. **Update imports:**
+
+   ```typescript
+   // Before
+   import { Database } from "@ciscode/database-kit/core/database";
+
+   // After
+   import { DatabaseService } from "@ciscode/database-kit";
+   ```
+
+2. **Update module configuration:**
+
+   ```typescript
+   // Before
+   DatabaseModule.forRoot(config);
+
+   // After
+   DatabaseKitModule.forRoot({ config });
+   ```
+
+3. **Update decorator usage:**
+
+   ```typescript
+   // Before
+   @InjectDatabase() private db: Database
+
+   // After
+   @InjectDatabase() private db: DatabaseService
+   ```
+
+4. **Update repository creation:**
+   ```typescript
+   // Methods remain the same
+   const repo = db.createMongoRepository<User>({ model: UserModel });
+   ```
+
+---
+
+## Release Schedule
+
+We follow semantic versioning:
+
+- **Patch releases (x.x.X)**: Bug fixes, released as needed
+- **Minor releases (x.X.0)**: New features, ~monthly
+- **Major releases (X.0.0)**: Breaking changes, ~annually
+
+---
+
+## Links
+
+- [GitHub Releases](https://github.com/CISCODE-MA/DatabaseKit/releases)
+- [npm Package](https://www.npmjs.com/package/@ciscode/database-kit)
+- [Documentation](https://github.com/CISCODE-MA/DatabaseKit#readme)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 **Ciscode**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,446 @@
+# @ciscode/database-kit
+
+A NestJS-friendly, OOP-style database library providing a unified repository API for **MongoDB** and **PostgreSQL**.
+
+[![npm version](https://img.shields.io/npm/v/@ciscode/database-kit.svg)](https://www.npmjs.com/package/@ciscode/database-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@ciscode/database-kit.svg)](https://nodejs.org)
+
+---
+
+## ✨ Features
+
+- ✅ **Unified Repository API** - Same interface for MongoDB and PostgreSQL
+- ✅ **NestJS Integration** - First-class support with `DatabaseKitModule`
+- ✅ **TypeScript First** - Full type safety and IntelliSense
+- ✅ **Pagination Built-in** - Consistent pagination across databases
+- ✅ **Environment-Driven** - Zero hardcoding, all config from env vars
+- ✅ **Exception Handling** - Global exception filter for database errors
+- ✅ **Clean Architecture** - Follows CISCODE standards and best practices
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @ciscode/database-kit
+```
+
+### Peer Dependencies
+
+Make sure you have NestJS installed:
+
+```bash
+npm install @nestjs/common @nestjs/core reflect-metadata
+```
+
+### Database Drivers
+
+Install the driver for your database:
+
+```bash
+# For MongoDB
+npm install mongoose
+
+# For PostgreSQL
+npm install pg
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+```typescript
+// app.module.ts
+import { Module } from "@nestjs/common";
+import { DatabaseKitModule } from "@ciscode/database-kit";
+
+@Module({
+  imports: [
+    DatabaseKitModule.forRoot({
+      config: {
+        type: "mongo", // or 'postgres'
+        connectionString: process.env.MONGO_URI!,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Inject and Use
+
+```typescript
+// users.service.ts
+import { Injectable } from "@nestjs/common";
+import {
+  InjectDatabase,
+  DatabaseService,
+  Repository,
+} from "@ciscode/database-kit";
+import { UserModel } from "./user.model";
+
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+}
+
+@Injectable()
+export class UsersService {
+  private readonly usersRepo: Repository<User>;
+
+  constructor(@InjectDatabase() private readonly db: DatabaseService) {
+    this.usersRepo = db.createMongoRepository<User>({ model: UserModel });
+  }
+
+  async createUser(data: Partial<User>): Promise<User> {
+    return this.usersRepo.create(data);
+  }
+
+  async getUser(id: string): Promise<User | null> {
+    return this.usersRepo.findById(id);
+  }
+
+  async listUsers(page = 1, limit = 10) {
+    return this.usersRepo.findPage({ page, limit });
+  }
+}
+```
+
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+| Variable                      | Description                              | Required       |
+| ----------------------------- | ---------------------------------------- | -------------- |
+| `DATABASE_TYPE`               | Database type (`mongo` or `postgres`)    | Yes            |
+| `MONGO_URI`                   | MongoDB connection string                | For MongoDB    |
+| `DATABASE_URL`                | PostgreSQL connection string             | For PostgreSQL |
+| `DATABASE_POOL_SIZE`          | Connection pool size (default: 10)       | No             |
+| `DATABASE_CONNECTION_TIMEOUT` | Connection timeout in ms (default: 5000) | No             |
+
+### Synchronous Configuration
+
+```typescript
+DatabaseKitModule.forRoot({
+  config: {
+    type: "postgres",
+    connectionString: "postgresql://user:pass@localhost:5432/mydb",
+  },
+  autoConnect: true, // default: true
+});
+```
+
+### Async Configuration (Recommended)
+
+```typescript
+import { ConfigModule, ConfigService } from "@nestjs/config";
+
+DatabaseKitModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    config: {
+      type: config.get("DATABASE_TYPE") as "mongo" | "postgres",
+      connectionString: config.get("DATABASE_URL")!,
+    },
+  }),
+  inject: [ConfigService],
+});
+```
+
+### Multiple Databases
+
+```typescript
+@Module({
+  imports: [
+    // Primary database
+    DatabaseKitModule.forRoot({
+      config: { type: "mongo", connectionString: process.env.MONGO_URI! },
+    }),
+    // Analytics database
+    DatabaseKitModule.forFeature("ANALYTICS_DB", {
+      type: "postgres",
+      connectionString: process.env.ANALYTICS_DB_URL!,
+    }),
+  ],
+})
+export class AppModule {}
+
+// Usage
+@Injectable()
+export class AnalyticsService {
+  constructor(
+    @InjectDatabaseByToken("ANALYTICS_DB")
+    private readonly analyticsDb: DatabaseService,
+  ) {}
+}
+```
+
+---
+
+## 📖 Repository API
+
+Both MongoDB and PostgreSQL repositories expose the same interface:
+
+```typescript
+interface Repository<T> {
+  create(data: Partial<T>): Promise<T>;
+  findById(id: string | number): Promise<T | null>;
+  findAll(filter?: Filter): Promise<T[]>;
+  findPage(options?: PageOptions): Promise<PageResult<T>>;
+  updateById(id: string | number, update: Partial<T>): Promise<T | null>;
+  deleteById(id: string | number): Promise<boolean>;
+  count(filter?: Filter): Promise<number>;
+  exists(filter?: Filter): Promise<boolean>;
+}
+```
+
+### Pagination
+
+```typescript
+const result = await repo.findPage({
+  filter: { status: "active" },
+  page: 1,
+  limit: 20,
+  sort: "-createdAt", // or { createdAt: -1 }
+});
+
+// Result:
+// {
+//   data: [...],
+//   page: 1,
+//   limit: 20,
+//   total: 150,
+//   pages: 8
+// }
+```
+
+### MongoDB Repository
+
+```typescript
+import { Model } from "mongoose";
+
+// Create your Mongoose model as usual
+const usersRepo = db.createMongoRepository<User>({ model: UserModel });
+```
+
+### PostgreSQL Repository
+
+```typescript
+interface Order {
+  id: string;
+  user_id: string;
+  total: number;
+  created_at: Date;
+}
+
+const ordersRepo = db.createPostgresRepository<Order>({
+  table: "orders",
+  primaryKey: "id",
+  columns: ["id", "user_id", "total", "created_at", "is_deleted"],
+  defaultFilter: { is_deleted: false }, // Soft delete support
+});
+```
+
+### PostgreSQL Advanced Filters
+
+```typescript
+// Comparison operators
+await repo.findAll({
+  price: { gt: 100, lte: 500 },
+  status: { ne: "cancelled" },
+});
+
+// IN / NOT IN
+await repo.findAll({
+  category: { in: ["electronics", "books"] },
+});
+
+// LIKE (case-insensitive)
+await repo.findAll({
+  name: { like: "%widget%" },
+});
+
+// NULL checks
+await repo.findAll({
+  deleted_at: { isNull: true },
+});
+```
+
+---
+
+## 🛡️ Error Handling
+
+### Global Exception Filter
+
+Register the filter globally to catch and format database errors:
+
+```typescript
+// main.ts
+import { DatabaseExceptionFilter } from "@ciscode/database-kit";
+
+app.useGlobalFilters(new DatabaseExceptionFilter());
+```
+
+Or in a module:
+
+```typescript
+import { APP_FILTER } from "@nestjs/core";
+import { DatabaseExceptionFilter } from "@ciscode/database-kit";
+
+@Module({
+  providers: [{ provide: APP_FILTER, useClass: DatabaseExceptionFilter }],
+})
+export class AppModule {}
+```
+
+### Error Response Format
+
+```json
+{
+  "statusCode": 409,
+  "message": "A record with this value already exists",
+  "error": "DuplicateKeyError",
+  "timestamp": "2026-01-31T12:00:00.000Z",
+  "path": "/api/users"
+}
+```
+
+---
+
+## 🔧 Utilities
+
+### Pagination Utilities
+
+```typescript
+import {
+  normalizePaginationOptions,
+  parseSortString,
+  calculateOffset,
+} from "@ciscode/database-kit";
+
+const normalized = normalizePaginationOptions({ page: 1 });
+const sortObj = parseSortString("-createdAt,name");
+const offset = calculateOffset(2, 10); // 10
+```
+
+### Validation Utilities
+
+```typescript
+import {
+  isValidMongoId,
+  isValidUuid,
+  sanitizeFilter,
+  pickFields,
+} from "@ciscode/database-kit";
+
+isValidMongoId("507f1f77bcf86cd799439011"); // true
+isValidUuid("550e8400-e29b-41d4-a716-446655440000"); // true
+
+const clean = sanitizeFilter({ name: "John", age: undefined });
+// { name: 'John' }
+
+const picked = pickFields(data, ["name", "email"]);
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Run with coverage
+npm run test:cov
+```
+
+### Mocking in Tests
+
+```typescript
+const mockDb = {
+  createMongoRepository: jest.fn().mockReturnValue({
+    create: jest.fn(),
+    findById: jest.fn(),
+    // ...
+  }),
+};
+
+const module = await Test.createTestingModule({
+  providers: [UsersService, { provide: DATABASE_TOKEN, useValue: mockDb }],
+}).compile();
+```
+
+---
+
+## 📁 Project Structure
+
+```
+src/
+├── index.ts                       # Public API exports
+├── database-kit.module.ts         # NestJS module
+├── adapters/                      # Database adapters
+│   ├── mongo.adapter.ts
+│   └── postgres.adapter.ts
+├── config/                        # Configuration
+│   ├── database.config.ts
+│   └── database.constants.ts
+├── contracts/                     # TypeScript contracts
+│   └── database.contracts.ts
+├── filters/                       # Exception filters
+│   └── database-exception.filter.ts
+├── middleware/                    # Decorators
+│   └── database.decorators.ts
+├── services/                      # Business logic
+│   ├── database.service.ts
+│   └── logger.service.ts
+└── utils/                         # Utilities
+    ├── pagination.utils.ts
+    └── validation.utils.ts
+```
+
+---
+
+## 🔒 Security
+
+See [SECURITY.md](SECURITY.md) for:
+
+- Vulnerability reporting
+- Security best practices
+- Security checklist
+
+---
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup
+- Git workflow
+- Code standards
+- PR process
+
+---
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+## 📄 License
+
+MIT © [C International Service](https://ciscode.com)
+
+---
+
+## 🙋 Support
+
+- 📧 Email: info@ciscode.com
+- 🐛 Issues: [GitHub Issues](https://github.com/CISCODE-MA/DatabaseKit/issues)
+- 📖 Docs: [GitHub Wiki](https://github.com/CISCODE-MA/DatabaseKit/wiki)

package/dist/adapters/mongo.adapter.d.ts

@@ -0,0 +1,44 @@
+import mongoose, { ConnectOptions } from 'mongoose';
+import { MongoDatabaseConfig, MongoRepositoryOptions, Repository } from '../contracts/database.contracts';
+/**
+ * MongoDB adapter for DatabaseKit.
+ * Handles MongoDB connection and repository creation via Mongoose.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MongoAdapter({ type: 'mongo', connectionString: 'mongodb://...' });
+ * await adapter.connect();
+ * const repo = adapter.createRepository({ model: UserModel });
+ * ```
+ */
+export declare class MongoAdapter {
+    private readonly logger;
+    private readonly config;
+    private connectionPromise?;
+    constructor(config: MongoDatabaseConfig);
+    /**
+     * Establishes connection to MongoDB.
+     * Connection is lazy-loaded and cached for reuse.
+     *
+     * @param options - Additional Mongoose connection options
+     * @returns Promise resolving to mongoose instance
+     */
+    connect(options?: ConnectOptions): Promise<typeof mongoose>;
+    /**
+     * Gracefully disconnects from MongoDB.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Checks if connected to MongoDB.
+     */
+    isConnected(): boolean;
+    /**
+     * Creates a repository for a Mongoose model.
+     * The repository provides a standardized CRUD interface.
+     *
+     * @param opts - Options containing the Mongoose model
+     * @returns Repository instance with CRUD methods
+     */
+    createRepository<T = unknown>(opts: MongoRepositoryOptions): Repository<T>;
+}
+//# sourceMappingURL=mongo.adapter.d.ts.map

package/dist/adapters/mongo.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo.adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/mongo.adapter.ts"],"names":[],"mappings":"AAEA,OAAO,QAAQ,EAAE,EAAE,cAAc,EAAS,MAAM,UAAU,CAAC;AAE3D,OAAO,EACH,mBAAmB,EACnB,sBAAsB,EACtB,UAAU,EAGb,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,qBACa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,iBAAiB,CAAC,CAA2B;gBAEzC,MAAM,EAAE,mBAAmB;IAKvC;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,QAAQ,CAAC;IA0BrE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAAC,CAAC,CAAC;CAwE7E"}