nestjs-drizzle-crud 1.0.6 → 2.1.0

package/README.md

@@ -1,18 +1,64 @@
-# NestJS Drizzle CRUD
+# nestjs-drizzle-crud
 
-A complete, type-safe CRUD abstraction layer for Drizzle ORM in NestJS applications. Supports PostgreSQL and MySQL with advanced features like soft delete, transactions, bulk operations, and full-text search.
+A complete, type-safe CRUD abstraction layer for [Drizzle ORM](https://orm.drizzle.team/) in [NestJS](https://nestjs.com/) applications.
+
+Configure the database connection **once**, then every entity gets full CRUD (find / create / update / delete / soft-delete / bulk / pagination / filtering / full-text search) by extending one base class — no per-service connection wiring.
+
+```typescript
+// 1. configure once (app.module.ts)
+DrizzleCrudModule.forRoot({
+  dialect: 'postgresql',
+  connectionString: process.env.DATABASE_URL,
+  schema,
+});
+
+// 2. a fully-featured CRUD service is just:
+export class UsersService extends SqlBaseCrudService<User> {}
+
+// 3. bind it to a table (users.module.ts)
+DrizzleCrudModule.forFeature([{ service: UsersService, table: users }]);
+```
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Defining services](#defining-services)
+- [API reference](#api-reference)
+- [Filtering](#filtering)
+- [Pagination & sorting](#pagination--sorting)
+- [Relations](#relations)
+- [Primary keys (serial / uuid)](#primary-keys-serial--uuid)
+- [Soft delete](#soft-delete)
+- [Bulk operations](#bulk-operations)
+- [Transactions](#transactions)
+- [Full-text search (PostgreSQL)](#full-text-search-postgresql)
+- [Lifecycle hooks & validation](#lifecycle-hooks--validation)
+- [Testing](#testing)
+- [For AI agents / LLM tools](#for-ai-agents--llm-tools)
+
+---
 
 ## Features
 
-- 🚀 **Complete CRUD Operations** - find, create, update, delete, and more
-- 🗃️ **SQL Database Support** - PostgreSQL & MySQL with dialect-specific optimizations
-- ⚡ **Type-Safe** - Full TypeScript support with generics
-- 🔄 **Soft Delete** - Built-in soft delete with restore functionality
-- 📦 **Bulk Operations** - Mass create, update, delete with transaction support
-- 🔍 **Advanced Querying** - Filtering, pagination, sorting, full-text search
-- 🎯 **NestJS Native** - Seamless integration with NestJS dependency injection
-- 🧪 **Test Utilities** - Comprehensive testing helpers
-- 🛡️ **Production Ready** - Error handling, transactions, and validation hooks
+- 🚀 **Complete CRUD** — `find`, `findOne`, `findAll`, `create`, `update`, `delete`, and more
+- 🧩 **Configure once** — `forRoot()` owns the connection; services only declare a table
+- ⚡ **Type-safe** — generics over your entity, create/update DTOs and filter types
+- 🗃️ **PostgreSQL & MySQL** — dialect-aware (`RETURNING` vs `insertId`)
+- 🔄 **Soft delete** — opt-in soft delete with `restore`
+- 📦 **Bulk operations** — mass create/update/delete inside a transaction
+- 🔍 **Rich filtering** — equality, `in`, comparison operators, `like`/`ilike`, null checks
+- 🔎 **Full-text search** — PostgreSQL `tsvector`/`tsquery`
+- 🔗 **Relations** — many-to-one eager loading and filtering by related columns
+- 🔑 **Flexible primary keys** — `serial` / `int` / `bigint` / `bigserial` / `uuid`
+- 🪝 **Hooks & validation** — `before*`/`after*` hooks, `validateCreate`/`validateUpdate`
+- 🧪 **Test utilities** — mock db/table/entity factories
+
+---
 
 ## Installation
 
@@ -20,385 +66,583 @@ A complete, type-safe CRUD abstraction layer for Drizzle ORM in NestJS applicati
 npm install nestjs-drizzle-crud
 ```
 
-# Quick Start
+Peer dependencies (install the ones you use):
+
+```bash
+# always
+npm install @nestjs/common @nestjs/core drizzle-orm reflect-metadata
+
+# PostgreSQL (also required if you use `connectionString` with dialect 'postgresql')
+npm install postgres
+
+# MySQL
+npm install mysql2
+```
+
+> `postgres` is an **optional** peer dependency. It's only needed when you let the
+> module build the connection from a `connectionString` for the `postgresql` dialect.
+> If you pass a pre-built `db` instead, you don't need it.
+
+---
+
+## Quick start
+
+### 1. Define your Drizzle schema
+
+```typescript
+// db/schema.ts
+import { pgTable, serial, varchar } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: varchar('name', { length: 100 }).notNull(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+});
+
+export const schema = { users };
+export type User = typeof users.$inferSelect;
+```
 
-## 1. Basic Setup 
+### 2. Configure the module once
 
-``` typescript
+```typescript
 // app.module.ts
 import { Module } from '@nestjs/common';
 import { DrizzleCrudModule } from 'nestjs-drizzle-crud';
+import { schema } from './db/schema';
+import { UsersModule } from './users/users.module';
 
 @Module({
   imports: [
     DrizzleCrudModule.forRoot({
-      dialect: 'postgresql', // or 'mysql'
-      defaults: {
-        softDelete: true,
-        timestamps: true,
-        pagination: { defaultLimit: 20, maxLimit: 100 },
-      },
+      dialect: 'postgresql',
+      connectionString: process.env.DATABASE_URL,
+      schema,
     }),
+    UsersModule,
   ],
 })
 export class AppModule {}
 ```
 
-## 2. Create a CRUD Service
+The connection is created here, exposed globally, and closed automatically on
+application shutdown (when the module built it from a `connectionString`).
+
+### 3. Create a service
 
-``` typescript
-// user.service.ts
-import { Injectable } from '@nestjs/common';
+```typescript
+// users/users.service.ts
 import { SqlBaseCrudService } from 'nestjs-drizzle-crud';
+import type { User } from '../db/schema';
+
+export interface CreateUserDto { name: string; email: string }
+export interface UpdateUserDto { name?: string; email?: string }
+export interface UserFilters { name?: string; email?: string }
+
+export class UsersService extends SqlBaseCrudService<
+  User,
+  CreateUserDto,
+  UpdateUserDto,
+  UserFilters
+> {}
+```
 
-// Your Drizzle table schema
-export const users = {
-  id: 'id',
-  name: 'name',
-  email: 'email',
-  password: 'password',
-  created_at: 'created_at',
-  updated_at: 'updated_at',
-  deleted_at: 'deleted_at',
-};
-
-// DTOs and interfaces
-export interface User {
-  id: number;
-  name: string;
-  email: string;
-  password: string;
-  created_at: Date;
-  updated_at: Date;
-  deleted_at: Date | null;
-}
+### 4. Bind the service to a table
 
-export interface CreateUserDto {
-  name: string;
-  email: string;
-  password: string;
-}
+```typescript
+// users/users.module.ts
+import { Module } from '@nestjs/common';
+import { DrizzleCrudModule } from 'nestjs-drizzle-crud';
+import { users } from '../db/schema';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
 
-export interface UpdateUserDto {
-  name?: string;
-  email?: string;
-  password?: string;
-}
+@Module({
+  imports: [
+    DrizzleCrudModule.forFeature([{ service: UsersService, table: users }]),
+  ],
+  controllers: [UsersController],
+})
+export class UsersModule {}
+```
 
-export interface UserFilters {
-  name?: string;
-  email?: string;
-}
+### 5. Use it in a controller
 
-@Injectable()
-export class UserService extends SqlBaseCrudService<User, CreateUserDto, UpdateUserDto, UserFilters> {
-  constructor(@Inject('DRIZZLE_DB') db: any) {
-    super({
-      dialect: 'postgresql',
-      db,
-      table: users,
-      primaryKey: 'id',
-      primaryKeyType: 'serial',
-      softDelete: { enabled: true, column: 'deleted_at' },
-      timestamps: { createdAt: 'created_at', updatedAt: 'updated_at' },
-    });
-  }
+```typescript
+// users/users.controller.ts
+import { Body, Controller, Delete, Get, Param, ParseIntPipe, Post, Put, Query } from '@nestjs/common';
+import { CreateUserDto, UpdateUserDto, UsersService } from './users.service';
 
-  protected async validateCreate(data: CreateUserDto): Promise<void> {
-    if (!data.email.includes('@')) {
-      throw new Error('Invalid email format');
-    }
+@Controller('users')
+export class UsersController {
+  constructor(private readonly users: UsersService) {}
+
+  @Get()
+  findAll(@Query('page') page = '1', @Query('limit') limit = '20') {
+    return this.users.findAll({}, { page: +page, limit: +limit });
   }
 
-  protected async validateUpdate(id: number, data: UpdateUserDto): Promise<void> {
-    if (data.email && !data.email.includes('@')) {
-      throw new Error('Invalid email format');
-    }
+  @Get(':id')
+  find(@Param('id', ParseIntPipe) id: number) {
+    return this.users.find(id);
   }
 
-  protected mapCreateDtoToEntity(data: CreateUserDto): Record<string, any> {
-    return {
-      ...data,
-      created_at: new Date(),
-      updated_at: new Date(),
-    };
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    return this.users.create(dto);
   }
 
-  protected mapUpdateDtoToEntity(data: UpdateUserDto): Record<string, any> {
-    return {
-      ...data,
-      updated_at: new Date(),
-    };
+  @Put(':id')
+  update(@Param('id', ParseIntPipe) id: number, @Body() dto: UpdateUserDto) {
+    return this.users.update(id, dto);
   }
 
-  // Custom methods
-  async findByEmail(email: string): Promise<User | null> {
-    return this.findOne({ email });
+  @Delete(':id')
+  remove(@Param('id', ParseIntPipe) id: number) {
+    return this.users.delete(id);
   }
 }
 ```
 
-## 3. Use in Controller
+---
 
-``` typescript
-// user.controller.ts
-import { Controller, Get, Post, Put, Delete, Body, Param, Query } from '@nestjs/common';
-import { UserService } from './user.service';
+## Configuration
 
-@Controller('users')
-export class UserController {
-  constructor(private readonly userService: UserService) {}
+### `DrizzleCrudModule.forRoot(config)`
 
-  @Get()
-  async findAll(
-    @Query('page') page: number = 1,
-    @Query('limit') limit: number = 20
-  ) {
-    return this.userService.findAll({}, { page, limit });
-  }
+| Field | Type | Description |
+|---|---|---|
+| `dialect` | `'postgresql' \| 'mysql'` | **Required.** Database dialect. |
+| `connectionString` | `string` | Connection string. The module builds the connection (PostgreSQL only). |
+| `db` | `Drizzle instance` | Alternatively, pass a Drizzle instance you built yourself (any dialect). |
+| `schema` | `Record<string, unknown>` | Drizzle schema, used when building from `connectionString`. |
+| `defaults.softDelete` | `boolean` | Enable soft delete for all entities (default `true`). |
+| `defaults.timestamps` | `boolean` | Auto-manage `created_at`/`updated_at` for all entities (default `true`). |
+| `defaults.pagination` | `{ defaultLimit, maxLimit }` | Pagination defaults (default `{ 20, 100 }`). |
+| `sql` | `{ caseSensitive, useReturning, jsonSupport, enableFullTextSearch }` | Dialect tuning. `useReturning` defaults to `true` for PostgreSQL, `false` for MySQL. |
 
-  @Get(':id')
-  async find(@Param('id') id: string) {
-    return this.userService.find(+id);
-  }
+> **Provide exactly one of `connectionString` or `db`.** If your tables have no
+> `created_at`/`updated_at`/`deleted_at` columns, set
+> `defaults: { softDelete: false, timestamps: false }`.
 
-  @Post()
-  async create(@Body() createUserDto: CreateUserDto) {
-    return this.userService.create(createUserDto);
-  }
+**Build the connection yourself (any dialect, recommended for MySQL):**
 
-  @Put(':id')
-  async update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
-    return this.userService.update(+id, updateUserDto);
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+DrizzleCrudModule.forRoot({
+  dialect: 'postgresql',
+  db: drizzle(postgres(process.env.DATABASE_URL!), { schema }),
+});
+```
+
+### `DrizzleCrudModule.forRootAsync(options)`
+
+```typescript
+DrizzleCrudModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (cfg: ConfigService) => ({
+    dialect: 'postgresql',
+    connectionString: cfg.get('DATABASE_URL'),
+    schema,
+  }),
+});
+```
+
+### `DrizzleCrudModule.forFeature(entities)`
+
+Registers one or more services and binds each to its table. Per-entity overrides
+go in `config`:
+
+```typescript
+DrizzleCrudModule.forFeature([
+  { service: UsersService, table: users },
+  {
+    service: PostsService,
+    table: posts,
+    config: {
+      primaryKey: 'uuid',
+      primaryKeyType: 'uuid',
+      softDelete: { enabled: true, column: 'deleted_at' },
+    },
+  },
+]);
+```
+
+Anything in `config` overrides the project defaults for that entity. The shape is
+[`SqlCrudConfig`](#sqlcrudconfig) minus `db`/`dialect`.
+
+---
+
+## Defining services
+
+The minimal service is an empty class — connection, dialect and defaults are
+injected by the module:
+
+```typescript
+export class UsersService extends SqlBaseCrudService<User> {}
+```
+
+Add custom behaviour by overriding hooks (see [Lifecycle hooks](#lifecycle-hooks--validation))
+or add your own methods:
+
+```typescript
+export class UsersService extends SqlBaseCrudService<User, CreateUserDto, UpdateUserDto, UserFilters> {
+  findByEmail(email: string) {
+    return this.findOne({ email } as Partial<User>);
   }
 
-  @Delete(':id')
-  async delete(@Param('id') id: string) {
-    return this.userService.softDelete(+id);
+  protected async validateCreate(data: CreateUserDto): Promise<void> {
+    if (!data.email.includes('@')) throw new Error('Invalid email');
   }
 }
 ```
 
-## Advanced Usage
+---
 
-### Bulk Operations
+## API reference
 
-``` typescript
-// Mass create users
-const users = await this.userService.massCreate(userDtos);
+`SqlBaseCrudService<T, CreateDto = Partial<T>, UpdateDto = Partial<T>, FilterDto = Partial<T>>`
 
-// Mass update
-const updatedUsers = await this.userService.massUpdate(
-  [1, 2, 3], 
-  { status: 'active' }
-);
+### Read
 
-// Mass soft delete
-await this.userService.massSoftDelete([1, 2, 3]);
-```
+| Method | Returns | Notes |
+|---|---|---|
+| `find(id, options?)` | `Promise<T \| null>` | By primary key. Skips soft-deleted rows. |
+| `findOne(where, options?)` | `Promise<T \| null>` | `where` is a `Partial<T>` (equality only). |
+| `findAll(filters?, pagination?, options?)` | `Promise<{ data: T[]; total: number; page: number; limit: number }>` | See [Filtering](#filtering) / [Pagination](#pagination--sorting). |
+| `exists(id, options?)` | `Promise<boolean>` | |
+| `count(filters?, options?)` | `Promise<number>` | |
 
-### Full-Text Search (PostgreSQL)
+### Write
 
-``` typescript
-const results = await this.userService.fullTextSearch(
-  'john doe',
-  ['name', 'email', 'bio']
-);
-```
+| Method | Returns | Notes |
+|---|---|---|
+| `create(data, options?)` | `Promise<T>` | Runs `validateCreate` → `beforeCreate` → insert → `afterCreate`. |
+| `update(id, data, options?)` | `Promise<T>` | Throws `EntityNotFoundException` if missing. |
+| `delete(id, options?)` | `Promise<boolean>` | Hard delete. |
+| `softDelete(id, options?)` | `Promise<boolean>` | Requires soft delete enabled. |
+| `restore(id, options?)` | `Promise<T>` | Clears the soft-delete column. |
 
-### Transactions
+### Bulk (run inside a transaction)
 
-``` typescript
-await this.userService.executeSqlTransaction(async (tx) => {
-  await this.userService.create(user1, { transaction: tx });
-  await this.userService.create(user2, { transaction: tx });
-});
+| Method | Returns |
+|---|---|
+| `massCreate(data[], options?)` | `Promise<T[]>` |
+| `massUpdate(ids[], data, options?)` | `Promise<T[]>` |
+| `massSoftDelete(ids[], options?)` | `Promise<boolean>` |
+| `massRestore(ids[], options?)` | `Promise<T[]>` |
+| `massDelete(ids[], options?)` | `Promise<boolean>` |
+
+### Search
+
+| Method | Returns |
+|---|---|
+| `fullTextSearch(term, columns, pagination?, options?)` | `Promise<{ data: T[]; total: number }>` (PostgreSQL only) |
+
+### `SqlOperationOptions`
+
+```typescript
+interface SqlOperationOptions {
+  transaction?: any;            // run within an existing transaction
+  select?: string[];            // return only these columns
+  relations?: string[];         // eager-load these configured relations (see Relations)
+  hooks?: { skipBefore?: boolean; skipAfter?: boolean };
+  lock?: 'update' | 'share' | 'none';
+  forNoKeyUpdate?: boolean;
+}
 ```
 
-### Advanced Filtering
+> `relations` eager-loads relations declared in the entity's config — see [Relations](#relations).
 
-``` typescript
-// Complex filters
-const results = await this.userService.findAll({
-  name: { like: 'John%' },
-  age: { gt: 18, lt: 65 },
-  status: { in: ['active', 'pending'] }
-});
+---
+
+## Filtering
+
+`findAll(filters)` / `count(filters)` accept an object keyed by column name.
+Unknown keys and `null`/`undefined` values are ignored.
 
-// With relations and selection
-const user = await this.userService.find(1, {
-  relations: ['profile', 'posts'],
-  select: ['id', 'name', 'email']
+```typescript
+await service.findAll({
+  status: 'active',                // string: exact match (case-insensitive when sql.caseSensitive === false)
+  role: ['admin', 'editor'],       // array: IN (...)
+  age: { gte: 18, lt: 65 },        // comparison operators
+  name: { ilike: 'jo%' },          // pattern match — you supply the wildcards
+  deleted_at: { isNull: true },    // null checks
 });
 ```
 
-# Module Configuration
-## Async Configuration
+**Operators** (inside an object value):
 
-``` typescript
-DrizzleCrudModule.forRootAsync({
-  imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
-    dialect: configService.get('DATABASE_DIALECT'),
-    defaults: {
-      softDelete: true,
-      timestamps: true,
-    },
-  }),
-  inject: [ConfigService],
-}),
+| Operator | SQL |
+|---|---|
+| `gt` / `gte` / `lt` / `lte` | `>` `>=` `<` `<=` |
+| `neq` | `<>` |
+| `like` / `ilike` | `LIKE` / `ILIKE` — **pass your own `%` wildcards** |
+| `in` | `IN (...)` |
+| `isNull` / `isNotNull` | `IS NULL` / `IS NOT NULL` |
+
+> A bare string value is an **exact** match. When `sql.caseSensitive` is `false`
+> (the default) it uses `ILIKE` *without* wildcards (case-insensitive exact match).
+> For partial matching, use the explicit `like`/`ilike` operators with wildcards.
+
+---
+
+## Pagination & sorting
+
+```typescript
+await service.findAll(
+  {},
+  { page: 2, limit: 25, sortBy: 'created_at', sortOrder: 'desc' },
+);
+// → { data: [...], total: 240, page: 2, limit: 25 }
 ```
 
-## Multiple Entities
+`limit` is capped at `pagination.maxLimit`. `sortOrder` defaults to `'desc'`.
+
+---
+
+## Relations
+
+The package supports **many-to-one / belongs-to** relations: a foreign key on
+this entity's table points at another table's key. Declare them in the entity's
+`forFeature` config under `relations`, keyed by relation name:
+
+```typescript
+import { cities, states } from './db/schema';
 
-``` typescript
 DrizzleCrudModule.forFeature([
   {
-    name: 'User',
-    table: usersTable,
-    service: UserService,
-    config: { primaryKey: 'id' },
-  },
-  {
-    name: 'Post', 
-    table: postsTable,
-    service: PostService,
-    config: { softDelete: { enabled: false } },
+    service: CitiesService,
+    table: cities,
+    config: {
+      relations: {
+        // cities.state_id -> states.id   (`references` defaults to 'id')
+        state: { table: states, localKey: 'state_id', references: 'id' },
+      },
+    },
   },
-]),
+]);
 ```
 
-# Testing
-``` typescript
-// user.service.spec.ts
-import { TestCrudFactory } from 'nestjs-drizzle-crud/test-utils';
-
-describe('UserService', () => {
-  let service: UserService;
-  let mockDb: any;
-
-  beforeEach(() => {
-    mockDb = TestCrudFactory.createMockDb();
-    const mockTable = TestCrudFactory.createMockTable();
-    
-    service = TestCrudFactory.createTestService(
-      UserService,
-      mockDb,
-      mockTable
-    );
-  });
-
-  it('should create user', async () => {
-    const createDto = { name: 'John', email: 'john@test.com' };
-    const mockEntity = TestCrudFactory.createMockEntity();
-    
-    mockDb.insert.mockReturnValue({
-      values: jest.fn().mockReturnThis(),
-      returning: jest.fn().mockResolvedValue([mockEntity]),
-    });
-
-    const result = await service.create(createDto);
-    expect(result).toEqual(mockEntity);
-  });
-});
+Once declared, you get two capabilities:
+
+### 1. Eager loading
+
+Pass `relations` in the operation options to LEFT JOIN and nest the related row:
+
+```typescript
+await cities.find(1, { relations: ['state'] });
+// → { id: 1, name: 'Bengaluru', state_id: 7, state: { id: 7, name: 'Karnataka', country_id: 3 } }
+
+await cities.findAll({}, { page: 1, limit: 20 }, { relations: ['state'] });
 ```
 
-# API Reference
-## Core Methods
+If there's no match, the relation comes back as `null`.
 
-* find(id, options?) - Find by primary key
+### 2. Filtering by related columns
 
-* findOne(where, options?) - Find by criteria
+Use the relation name as a filter key with a nested object of the **related
+table's** columns. Supports the same [operators](#filtering) as normal filters:
 
-* findAll(filters?, pagination?, options?) - Find all with filtering & pagination
+```typescript
+// all cities whose state is named 'Karnataka' (case-insensitive exact)
+await cities.findAll({ state: { name: 'Karnataka' } });
 
-* create(data, options?) - Create new entity
+// all cities in a country — filter on the intermediate table's FK column
+await cities.findAll({ state: { country_id: 3 } });
 
-* update(id, data, options?) - Update entity
+// combine with normal column filters and operators
+await cities.findAll({ name: { ilike: 'B%' }, state: { country_id: 3 } });
+```
 
-* softDelete(id, options?) - Soft delete entity
+> **Scope:** only **many-to-one / one-to-one** (belongs-to) relations are
+> supported. Has-many collection loading and many-to-many (join tables) are not
+> handled — model those with a custom service method using `this.config.db`, or
+> orchestrate across services in a controller.
+>
+> **Multi-level filtering** works through the intermediate table's columns
+> (e.g. filter cities by `state.country_id`), so you usually don't need a
+> direct relation to the far table.
 
-* restore(id, options?) - Restore soft-deleted entity
+---
 
-* delete(id, options?) - Hard delete entity
+## Primary keys (serial / uuid)
 
-## Bulk Methods
-* massCreate(data[], options?) - Create multiple entities
+Each entity declares its primary key via `primaryKey` (column name, default
+`id`) and `primaryKeyType`. Both auto-increment and UUID keys are supported.
 
-* massUpdate(ids[], data, options?) - Update multiple entities
+```typescript
+// serial / auto-increment (default)
+{ service: UsersService, table: users }   // primaryKey 'id', primaryKeyType 'serial'
 
-* massSoftDelete(ids[], options?) - Soft delete multiple entities
+// UUID
+{
+  service: TagsService,
+  table: tags,                  // e.g. uuid('id').primaryKey().defaultRandom()
+  config: { primaryKey: 'id', primaryKeyType: 'uuid' },
+}
+```
 
-* massRestore(ids[], options?) - Restore multiple entities
+`primaryKeyType` accepts `'serial' | 'bigserial' | 'int' | 'bigint' | 'uuid'`.
+On PostgreSQL the created row (including a DB-generated UUID) is returned via
+`RETURNING`. On MySQL (no `RETURNING`), provide the UUID in your create payload
+so the row can be re-read — auto-increment keys use the driver's `insertId`.
 
-* massDelete(ids[], options?) - Hard delete multiple entities
+> Remember: with UUID keys, route params are strings — don't apply
+> `ParseIntPipe` in your controller.
 
-## Utility Methods
+---
 
-* exists(id, options?) - Check if entity exists
+## Soft delete
 
-* count(filters?, options?) - Count entities
+Enable per-project via `defaults.softDelete` or per-entity via `forFeature` config:
 
-* fullTextSearch(term, columns, pagination?, options?) - Full-text search (PostgreSQL)
+```typescript
+{ service: UsersService, table: users, config: { softDelete: { enabled: true, column: 'deleted_at' } } }
+```
 
+- `softDelete(id)` sets the column to the current timestamp.
+- `restore(id)` sets it back to `null`.
+- `find`/`findOne`/`findAll`/`count` automatically exclude soft-deleted rows.
 
-# Configuration Options
-``` typescript
-interface SqlCrudConfig {
-  dialect: 'postgresql' | 'mysql';
-  db: any; // Drizzle database instance
-  table: any; // Drizzle table
-  
-  // Primary key configuration
-  primaryKey: string;
-  primaryKeyType: 'serial' | 'bigserial' | 'int' | 'bigint' | 'uuid';
-  
-  // Soft delete
-  softDelete?: {
-    enabled: boolean;
-    column: string;
-  };
-  
-  // Timestamps
-  timestamps?: {
-    createdAt: string;
-    updatedAt: string;
-  };
-  
-  // Pagination
-  pagination?: {
-    defaultLimit: number;
-    maxLimit: number;
-  };
-}
+---
+
+## Bulk operations
+
+```typescript
+await service.massCreate([dto1, dto2, dto3]);
+await service.massUpdate([1, 2, 3], { status: 'archived' });
+await service.massSoftDelete([1, 2, 3]);
 ```
 
-# Supported Versions
-* NestJS: >=10.0.0
+All bulk methods run inside a single transaction; if any row fails, a
+`BulkOperationException` (carrying the per-row errors) is thrown and the
+transaction rolls back.
 
-* Drizzle ORM: >=0.28.0
+---
 
-* Node.js: >=18.0.0
+## Transactions
 
-* PostgreSQL: >=12.0
+```typescript
+await service.executeSqlTransaction(async (tx) => {
+  const user = await service.create(userDto, { transaction: tx });
+  await profileService.create({ userId: user.id }, { transaction: tx });
+});
+```
 
-* MySQL: >=8.0
+Pass `{ transaction: tx }` in `options` to any method to enlist it.
 
-# Contributing
-Contributions are welcome! Please feel free to submit a Pull Request.
+---
 
-# License
-MIT
+## Full-text search (PostgreSQL)
+
+```typescript
+const { data, total } = await service.fullTextSearch(
+  'john doe',
+  ['name', 'email', 'bio'],
+  { page: 1, limit: 20 },
+);
+```
+
+Builds `to_tsvector(...) @@ plainto_tsquery(...)` across the given columns and
+orders by `ts_rank`. Throws if the dialect is not `postgresql`.
+
+---
+
+## Lifecycle hooks & validation
+
+Override any of these `protected` methods in your service (all are optional;
+defaults are no-op / pass-through):
+
+```typescript
+protected validateCreate(data: CreateDto): Promise<void>
+protected validateUpdate(id: any, data: UpdateDto): Promise<void>
+protected mapCreateDtoToEntity(data: CreateDto): Record<string, any>
+protected mapUpdateDtoToEntity(data: UpdateDto): Record<string, any>
+
+protected beforeCreate(data: CreateDto): Promise<CreateDto>
+protected afterCreate(entity: T): Promise<void>
+protected beforeUpdate(id: any, data: UpdateDto): Promise<UpdateDto>
+protected afterUpdate(entity: T): Promise<void>
+protected beforeDelete(id: any): Promise<void>
+protected afterDelete(id: any): Promise<void>
+protected beforeSoftDelete(id: any): Promise<void>
+protected afterSoftDelete(id: any): Promise<void>
+protected beforeRestore(id: any): Promise<void>
+protected afterRestore(entity: T): Promise<void>
+```
 
+`mapCreateDtoToEntity` / `mapUpdateDtoToEntity` transform the incoming DTO into the
+row to persist (default returns a shallow copy). When `timestamps` is enabled, the
+service stamps `created_at`/`updated_at` automatically.
 
-This README provides:
+---
 
-1. **Clear installation instructions**
-2. **Quick start guide** with code examples
-3. **Advanced usage patterns**
-4. **Comprehensive API documentation**
-5. **Testing examples**
-6. **Configuration reference**
-7. **Version compatibility**
+## Testing
 
-It's ready to use and will help users understand how to implement your package quickly!
+```typescript
+import { TestCrudFactory } from 'nestjs-drizzle-crud';
+
+const mockDb = TestCrudFactory.createMockDb();
+const mockTable = TestCrudFactory.createMockTable();
+const service = TestCrudFactory.createTestService(UsersService, mockDb, mockTable);
+```
+
+`TestCrudFactory` provides `createMockDb()`, `createMockTable()`,
+`createMockEntity()` and `createTestService()` for unit tests without a database.
+
+---
+
+## For AI agents / LLM tools
+
+Concise, accurate facts for code generation. Prefer these over guessing.
+
+**Package:** `nestjs-drizzle-crud` · **Peers:** `@nestjs/common`, `@nestjs/core`, `drizzle-orm`, `reflect-metadata`; optional `postgres` (PG) / `mysql2` (MySQL).
+
+**Setup is two steps and no per-service connection wiring:**
+1. `DrizzleCrudModule.forRoot({ dialect, connectionString | db, schema, defaults })` once in `AppModule`.
+2. `DrizzleCrudModule.forFeature([{ service, table, config? }])` in each feature module.
+
+**A service is an empty subclass — do NOT inject the db or pass `dialect`/`db`:**
+```typescript
+export class XService extends SqlBaseCrudService<X, CreateXDto, UpdateXDto, XFilters> {}
+```
+
+**Rules / gotchas:**
+- Generics order: `SqlBaseCrudService<Entity, CreateDto, UpdateDto, FilterDto>`. All but `Entity` default to `Partial<Entity>`.
+- Do **not** add an `@Inject('DRIZZLE_DB')` constructor — `forFeature` constructs the service for you. Adding a constructor that calls `super({...})` is the legacy/manual pattern and is unnecessary.
+- The table is passed in `forFeature`, **not** in the service.
+- If tables lack timestamp/soft-delete columns, set `defaults: { softDelete: false, timestamps: false }`, else inserts will reference non-existent columns.
+- `findAll` returns `{ data, total, page, limit }` — not a bare array.
+- Filter operators live inside an object value: `{ age: { gte: 18 } }`. `like`/`ilike` require caller-supplied `%` wildcards; a bare string is exact match.
+- `delete`/`softDelete` return `boolean`; `update`/`restore` return the entity and throw `EntityNotFoundException` when missing.
+- Relations (many-to-one only): declare in forFeature `config.relations = { relName: { table, localKey, references? } }`. Then eager-load via `options.relations: ['relName']` (nested object on the result, `null` if unmatched) and filter via `findAll({ relName: { col: value } })` (same operators; multi-level via the intermediate table's columns, e.g. `state.country_id`). No has-many/many-to-many.
+- Primary keys: `primaryKey` (default `'id'`) + `primaryKeyType` (`'serial' | 'bigserial' | 'int' | 'bigint' | 'uuid'`) per entity in forFeature config. UUID works on Postgres via RETURNING; with uuid keys, route params are strings — don't use `ParseIntPipe`.
+- Full-text search is PostgreSQL-only.
+- Exports: `SqlBaseCrudService`, `DrizzleCrudModule`, `DRIZZLE_DB`, `DRIZZLE_CRUD_CONFIG`, `TestCrudFactory`, exceptions (`EntityNotFoundException`, `BulkOperationException`, …), and types (`SqlCrudConfig`, `SqlOperationOptions`, `DrizzleCrudConfig`, `CrudFeature`, `SqlDialect`, `PrimaryKeyType`).
+
+### `SqlCrudConfig`
+
+```typescript
+interface SqlCrudConfig {
+  dialect: 'postgresql' | 'mysql';
+  db: any;                         // Drizzle instance (injected by forFeature)
+  table: any;                      // Drizzle table (set by forFeature)
+  primaryKey: string;              // default 'id'
+  primaryKeyType: 'serial' | 'bigserial' | 'int' | 'bigint' | 'uuid';
+  softDelete?: { enabled: boolean; column: string };
+  timestamps?: { createdAt: string; updatedAt: string };
+  pagination?: { defaultLimit: number; maxLimit: number };
+  sql?: { caseSensitive: boolean; useReturning: boolean; jsonSupport: boolean; enableFullTextSearch: boolean };
+  relations?: Record<string, { table: any; localKey: string; references?: string }>;
+}
+```
+
+---
+
+## License
+
+MIT