@zola_do/crud 0.2.5 → 0.2.7

package/README.md

@@ -1,6 +1,23 @@
 # @zola_do/crud
 
-Generic CRUD controllers, services, and repositories for NestJS entities.
+[![npm version](https://img.shields.io/npm/v/@zola_do/crud.svg)](https://www.npmjs.com/package/@zola_do/crud)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/crud.svg)](https://www.npmjs.com/package/@zola_do/crud)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Generic CRUD controllers, services, and repositories for NestJS entities with built-in authorization, hooks, and pagination.
+
+## Overview
+
+`@zola_do/crud` provides reusable CRUD factories that generate type-safe controllers and services for any TypeORM entity. It includes:
+
+- **Controller Factories** — `EntityCrudController`, `ExtraCrudController`, `RelationCrudController`
+- **Service Classes** — Generic CRUD operations with hooks
+- **Repository Pattern** — EntityCrudRepository for data access
+- **Authorization Guards** — Permission-based access control
+- **Operation Hooks** — before/after callbacks for each operation
+- **Endpoint Control** — Hide or block specific operations
+- **Request Context** — Automatic tenant/user context mapping
+- **Global Exception Filter** — Safe JSON error responses
 
 ## Installation
 
@@ -12,74 +29,65 @@ npm install @zola_do/crud
 npm install @zola_do/nestjs-shared
 ```
 
-## Dependencies
-
-- `@zola_do/collection-query`
-- `@zola_do/authorization`
-- Optional (only for RPC exception filter): `@nestjs/microservices`
-
-## Recommended Imports
-
-`@zola_do/crud` root imports remain fully supported for backward compatibility.
-For new code, prefer focused subpath imports:
+### Dependencies
 
-```typescript
-import { EntityCrudController } from '@zola_do/crud/controller';
-import { EntityCrudService } from '@zola_do/crud/service';
-import { EntityCrudRepository } from '@zola_do/crud/repository';
-import {
-  CRUD_REQUEST_CONTEXT_RESOLVER,
-  CrudRequestContextResolver,
-} from '@zola_do/crud/request-context';
+```bash
+npm install @zola_do/collection-query @zola_do/authorization
 ```
 
-Optional RPC exception filter stays available at:
+### Optional Dependencies
 
-```typescript
-import { ExceptionFilter } from '@zola_do/crud/optional/rpc';
+```bash
+# For RPC exception filter
+npm install @nestjs/microservices
 ```
 
-## Usage
-
-### Entity Setup
+## Quick Start
 
-Extend `CommonEntity` (or `Audit` for tenant-aware entities) and use with the CRUD factories:
+### 1. Create an Entity
 
 ```typescript
-import { BaseAudit } from './base-audit';
-import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
-
-@Entity('products')
-export class Product extends BaseAudit {
-  @PrimaryGeneratedColumn('uuid')
+import { CommonEntity } from "@zola_do/nestjs-shared";
+import {
+  Entity,
+  Column,
+  PrimaryGeneratedColumn,
+  DeleteDateColumn,
+} from "typeorm";
+
+@Entity("products")
+export class Product extends CommonEntity {
+  @PrimaryGeneratedColumn("uuid")
   id: string;
 
   @Column()
   name: string;
 
-  @Column({ type: 'decimal', precision: 10, scale: 2 })
+  @Column({ type: "decimal", precision: 10, scale: 2 })
   price: number;
+
+  @Column({ default: "active" })
+  status: string;
+
+  @DeleteDateColumn()
+  deletedAt?: Date;
 }
 ```
 
-### Controller and Service
-
-Create a CRUD controller and service for your entity:
+### 2. Create Controller
 
 ```typescript
-import { Controller } from '@nestjs/common';
-import {
-  EntityCrudController,
-  EntityCrudService,
-} from '@zola_do/crud';
-import { Product } from './product.entity';
+import { Controller } from "@nestjs/common";
+import { EntityCrudController } from "@zola_do/crud";
+import { EntityCrudService } from "@zola_do/crud/service";
+import { Product } from "./product.entity";
 
-@Controller('products')
+@Controller("products")
 export class ProductsController extends EntityCrudController<Product>({
-  createPermission: 'product:create',
-  viewPermission: 'product:view',
-  updatePermission: 'product:update',
-  deletePermission: 'product:delete',
+  createPermission: "product:create",
+  viewPermission: "product:view",
+  updatePermission: "product:update",
+  deletePermission: "product:delete",
 }) {
   constructor(service: EntityCrudService<Product>) {
     super(service);
@@ -87,12 +95,14 @@ export class ProductsController extends EntityCrudController<Product>({
 }
 ```
 
+### 3. Create Module
+
 ```typescript
-import { Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
-import { EntityCrudService } from '@zola_do/crud';
-import { Product } from './product.entity';
-import { ProductsController } from './products.controller';
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+import { EntityCrudService } from "@zola_do/crud/service";
+import { Product } from "./product.entity";
+import { ProductsController } from "./products.controller";
 
 @Module({
   imports: [TypeOrmModule.forFeature([Product])],
@@ -102,149 +112,300 @@ import { ProductsController } from './products.controller';
 export class ProductsModule {}
 ```
 
-### Available Endpoints
+## Available Endpoints
 
-- `POST /` — Create
-- `GET /` — Find all (supports `?q=` collection query)
-- `GET /:id` — Find one
-- `PUT /:id` — Update
-- `DELETE /:id` — Soft delete
+| Method   | Endpoint       | Description                                  |
+| -------- | -------------- | -------------------------------------------- |
+| `POST`   | `/`            | Create a new entity                          |
+| `GET`    | `/`            | List all entities (with `?q=` query support) |
+| `GET`    | `/:id`         | Get single entity by ID                      |
+| `PUT`    | `/:id`         | Update entire entity                         |
+| `PATCH`  | `/:id`         | Partial update                               |
+| `DELETE` | `/:id`         | Soft delete                                  |
+| `PATCH`  | `/restore/:id` | Restore soft-deleted entity                  |
+| `GET`    | `/archived`    | List archived entities                       |
 
-You can disable specific endpoints via the `operations` option (supports `hide` and `block`).
+## EntityCrudOptions
 
-### EntityCrudOptions
+Full configuration options for the CRUD controller:
 
 ```typescript
 import { EntityCrudOptions } from '@zola_do/crud';
 
 const options: EntityCrudOptions = {
+  // DTOs for validation
   createDto: CreateProductDto,
   updateDto: UpdateProductDto,
+
+  // Permissions for guards
   createPermission: 'product:create',
   viewPermission: 'product:view',
   updatePermission: 'product:update',
   deletePermission: 'product:delete',
   restorePermission: 'product:restore',
   viewArchivedPermission: 'product:view_archived',
+
+  // Context mapping (deprecated)
   mapCreateContext: ({ req, itemData }) => ({
-    organizationId: req?.session?.org?.id,
-    organizationName: req?.session?.org?.name,
-    createdBy: req?.session?.user?.id,
+    organizationId: req?.user?.organizationId,
+    createdBy: req?.user?.id,
   }),
-  // Optional per-endpoint disabling
+
+  // Write field restrictions
+  allowedWriteFields: ['name', 'price'],
+  blockedWriteFields: ['id', 'createdAt'],
+
+  // Operation hooks
+  beforeCreate: async ({ service, req, itemData }) => {
+    itemData.createdBy = req.user.id;
+    itemData.status ??= 'draft';
+  },
+  afterCreate: async ({ service, req, result }) => {
+    await service.sendNotification(result.id);
+  },
+
+  beforeFindAll: async ({ service, req, where }) => {
+    where.organizationId = req.user.organizationId;
+  },
+  afterFindAll: async ({ service, req, result }) => {
+    result.items = result.items.filter(i => i.isActive);
+  },
+
+  beforeFindOne: async ({ service, req, where, params }) => {
+    where.id = params.id;
+  },
+
+  beforeUpdate: async ({ service, req, itemData, params }) => {
+    itemData.updatedBy = req.user.id;
+  },
+  afterUpdate: async ({ service, req, result }) => {
+    await service.invalidateCache(result.id);
+  },
+
+  beforeDelete: async ({ service, req, params }) => {
+    await service.assertCanDelete(params.id);
+  },
+
+  beforeRestore: async ({ service, req, params }) => {
+    await service.assertCanRestore(params.id);
+  },
+
+  // Authorization callbacks
+  authorize: async ({ req, operation }) => {
+    return req.user.isAdmin;
+  },
+  canCreate: async ({ service, req }) => /* boolean */,
+  canFindAll: async ({ service, req }) => /* boolean */,
+  canFindOne: async ({ service, req, params }) => /* boolean */,
+  canUpdate: async ({ service, req, params }) => /* boolean */,
+  canDelete: async ({ service, req, params }) => /* boolean */,
+  canRestore: async ({ service, req, params }) => /* boolean */,
+
+  // Delete behavior
+  deleteMode: 'soft', // 'auto' | 'soft' | 'hard'
+
+  // Endpoint control
   operations: {
-    create: 'hide',
-    findAll: { mode: 'block', reason: 'listing is temporarily disabled' },
+    create: 'hide', // Hide from routes (404)
+    findAll: { mode: 'block', reason: 'maintenance' }, // Block with 403
+    findOne: false, // Shorthand for 'hide'
+    update: 'block',
+    delete: 'hide',
+    restore: 'hide',
+    findAllArchived: 'hide',
   },
 };
 ```
 
-### Operation Hooks and Policy Callbacks
+## Operation Hooks
+
+Hooks are callbacks that run before or after CRUD operations. They receive a context object and can modify the request data or perform side effects.
+
+### Hook Types
+
+```typescript
+interface CrudHookContext {
+  req?: any; // Express request object
+  params?: any; // Route parameters
+  query?: any; // Query parameters
+  id?: string; // Entity ID (for single-entity operations)
+  itemData?: any; // Create/Update payload (mutable)
+  where?: any; // Query filter (mutable for reads)
+  entity?: any; // Existing entity (for updates)
+  result?: any; // Operation result
+  operation: string; // 'create' | 'findAll' | 'findOne' | 'update' | 'delete' | 'restore'
+  service?: any; // CRUD service instance
+  repository?: any; // TypeORM repository
+  setMeta?: (key: string, value: any) => void; // Cross-hook metadata
+  getMeta?: <T = any>(key: string) => T | undefined;
+}
+```
+
+### Hook Examples
+
+#### Before Create - Add Context Data
+
+```typescript
+beforeCreate: async ({ service, req, itemData }) => {
+  const userId = req?.user?.sub ?? req?.user?.id;
+  const orgId = req?.user?.organizationId;
 
-`EntityCrudOptions` and `ExtraCrudOptions` support reusable per-operation hooks:
+  if (!userId || !orgId) {
+    throw new UnauthorizedException('User context required');
+  }
 
-- `beforeCreate` / `afterCreate`
-- `beforeFindAll` / `afterFindAll`
-- `beforeFindOne` / `afterFindOne`
-- `beforeUpdate` / `afterUpdate`
-- `beforeDelete` / `afterDelete` (alias hooks)
-- `beforeRestore` / `afterRestore`
+  itemData.createdBy = userId;
+  itemData.organizationId = orgId;
+  itemData.status ??= 'pending';
+},
+```
 
-Delete hook compatibility is preserved:
+#### Before FindAll - Filter by Tenant
 
-- Legacy: `beforeSoftDelete` / `afterSoftDelete`
-- New alias: `beforeDelete` / `afterDelete`
-- If both are configured, both run (legacy first, then alias)
+```typescript
+beforeFindAll: async ({ service, req, where }) => {
+  where.organizationId = req.user.organizationId;
+  where.deletedAt = undefined; // Exclude soft-deleted
+},
+```
 
-Hooks receive operation context with request and mutable payload/filter data.
-`service` is the injected CRUD service instance (for example, your subclass of
-`EntityCrudService`), so hook code can call custom service methods directly:
+#### Before Update - Validate and Modify
 
 ```typescript
-const options: EntityCrudOptions = {
-  blockedWriteFields: ['eventId'],
+beforeUpdate: async ({ service, req, itemData, params }) => {
+  const existing = await service.findOne(params.id);
+
+  if (existing.status === 'completed') {
+    throw new BadRequestException('Cannot update completed items');
+  }
 
+  itemData.updatedBy = req.user.id;
+  itemData.updatedAt = new Date();
+},
+```
+
+#### After Create - Side Effects
+
+```typescript
+afterCreate: async ({ service, req, result }) => {
+  await service.sendWebhook('item.created', result);
+  await service.updateAnalytics(result);
+},
+```
+
+#### Using Metadata for Cross-Hook Communication
+
+```typescript
+beforeFindAll: async ({ req, setMeta }) => {
+  setMeta('userId', req.user.id);
+  setMeta('orgId', req.user.organizationId);
+},
+
+afterFindAll: async ({ service, req, result, getMeta }) => {
+  const userId = getMeta('userId');
+  await service.trackSearch(userId, result.items.length);
+},
+```
+
+## Authorization Callbacks
+
+Operation-specific authorization allows fine-grained access control:
+
+```typescript
+const options: EntityCrudOptions = {
+  // Global authorize (runs for all operations)
   authorize: async ({ req, operation }) => {
-    if (!req?.user && operation !== 'findAll') return false;
+    if (!req.user) return false;
+    return true;
   },
 
-  beforeCreate: async ({ service, req, params, itemData }) => {
-    const userId = req?.user?.sub ?? req?.user?.id;
-    const eventId = params?.eventId;
-    if (!userId || !eventId) throw new UnauthorizedException();
-
-    await service.assertCanEditEvent(eventId, userId);
-    itemData.eventId = eventId;
-    itemData.status ??= 'pending';
+  // Per-operation authorization
+  canCreate: async ({ service, req }) => {
+    return req.user.permissions.includes("product:create");
   },
 
-  beforeFindAll: async ({ service, req, params, where }) => {
-    const userId = req?.user?.sub ?? req?.user?.id;
-    await service.assertCanAccessEvent(params?.eventId, userId);
-    where.eventId = params?.eventId;
+  canFindAll: async ({ service, req }) => {
+    return true; // Public read
   },
 
   canUpdate: async ({ service, req, params }) => {
-    const userId = req?.user?.sub ?? req?.user?.id;
-    await service.assertCanEditEvent(params?.eventId, userId);
-    return true;
+    const entity = await service.findOne(params.id);
+    return entity.ownerId === req.user.id || req.user.isAdmin;
+  },
+
+  canDelete: async ({ service, req, params }) => {
+    const entity = await service.findOne(params.id);
+    return entity.ownerId === req.user.id;
+  },
+
+  canRestore: async ({ service, req, params }) => {
+    return req.user.isAdmin;
   },
 };
 ```
 
-When using this pattern, define those methods in your app service class that
-extends `EntityCrudService<T>` (or `ExtraCrudService<T>`).
+## Endpoint Disabling
 
-Hook context includes:
+Control which endpoints are available using the `operations` option:
 
-- `req`, `params`, `query`
-- `operation`, `id`
-- `itemData` (mutable create/update payload)
-- `where` (mutable filter scope for read/list operations)
-- `service`, `repository`
-- `entity`, `result` (when available)
-- `setMeta(key, value)` / `getMeta(key)` for cross-hook metadata
+```typescript
+operations: {
+  // 'hide' - Route not registered (404)
+  create: 'hide',
 
-### Endpoint Disabling (`operations`)
+  // 'block' - Route registered but denied (403)
+  findAll: { mode: 'block', reason: 'Under maintenance' },
 
-For `EntityCrudController` and `ExtraCrudController`, `operations` supports these keys:
+  // false - Same as 'hide'
+  findOne: false,
 
-- `create`
-- `findAll`
-- `findOne`
-- `update`
-- `delete` (soft-delete)
-- `restore`
-- `findAllArchived`
+  // 'block' with string shorthand
+  update: 'block',
 
-For `RelationCrudController`, `operations` supports these keys:
+  // All available keys
+  delete: 'hide',
+  restore: 'hide',
+  findAllArchived: 'hide',
+}
+```
 
-- `bulkSaveFirst`
-- `bulkSaveSecond`
-- `findAllFirst`
-- `findAllSecond`
+### Operation Keys
 
-Each operation can be configured as:
+| Key               | Endpoint             | Description       |
+| ----------------- | -------------------- | ----------------- |
+| `create`          | `POST /`             | Create new entity |
+| `findAll`         | `GET /`              | List entities     |
+| `findOne`         | `GET /:id`           | Get single entity |
+| `update`          | `PUT /:id`           | Full update       |
+| `delete`          | `DELETE /:id`        | Soft delete       |
+| `restore`         | `PATCH /restore/:id` | Restore entity    |
+| `findAllArchived` | `GET /archived`      | List deleted      |
 
-- `'hide'` — route is not registered (typically `404`)
-- `'block'` — route is registered but denied with a consistent `403`
+## Request Context Mapping
 
-### Request Context Mapping
+The CRUD package supports automatic context injection for create operations:
 
-`@zola_do/crud` supports three create-time mapping levels:
+### Method 1: Per-CRUD Options
 
-1. `mapCreateContext` in `EntityCrudOptions` / `ExtraCrudOptions` (highest priority)
-2. module-level resolver provider (`CRUD_REQUEST_CONTEXT_RESOLVER`)
-3. legacy fallback to `req.user.organization` (for backward compatibility)
+```typescript
+EntityCrudController<Product>({
+  mapCreateContext: ({ req, itemData }) => ({
+    organizationId: req?.user?.organizationId,
+    organizationName: req?.user?.organizationName,
+    createdBy: req?.user?.id,
+  }),
+});
+```
+
+### Method 2: Module-Level Resolver
 
 ```typescript
-import { Module } from '@nestjs/common';
 import {
   CRUD_REQUEST_CONTEXT_RESOLVER,
   CrudRequestContextResolver,
-} from '@zola_do/crud';
+} from "@zola_do/crud/request-context";
 
-const crudRequestContextResolver: CrudRequestContextResolver = {
+const resolver: CrudRequestContextResolver = {
   resolveCreateContext: ({ req }) => ({
     organizationId: req?.auth?.orgId,
     organizationName: req?.auth?.orgName,
@@ -256,28 +417,41 @@ const crudRequestContextResolver: CrudRequestContextResolver = {
   providers: [
     {
       provide: CRUD_REQUEST_CONTEXT_RESOLVER,
-      useValue: crudRequestContextResolver,
+      useValue: resolver,
     },
   ],
 })
 export class ProductsModule {}
 ```
 
-### Relation CRUD
+### Method 3: Legacy Fallback
 
-For many-to-many or relation management:
+If no resolver is configured, the system falls back to `req.user.organization`:
 
 ```typescript
-import { RelationCrudController, RelationCrudService } from '@zola_do/crud';
+// Automatically uses req.user.organization.organizationId
+// and req.user.organization.organizationName
+```
+
+## Relation CRUD
+
+For managing many-to-many relationships:
 
-@Controller('products/:productId/categories')
+```typescript
+import { RelationCrudController, RelationCrudService } from "@zola_do/crud";
+
+@Controller("products/:productId/categories")
 export class ProductCategoriesController extends RelationCrudController(
   {
-    firstEntityIdName: 'productId',
-    firstInclude: 'product',
-    secondEntityIdName: 'categoryId',
-    secondInclude: 'category',
-    viewPermission: 'product:view',
+    firstEntityIdName: "productId",
+    firstInclude: "product",
+    secondEntityIdName: "categoryId",
+    secondInclude: "category",
+    viewPermission: "product:view",
+    operations: {
+      bulkSaveFirst: "hide",
+      findAllSecond: "hide",
+    },
   },
   ProductCategory,
 ) {
@@ -287,29 +461,299 @@ export class ProductCategoriesController extends RelationCrudController(
 }
 ```
 
-## Exports
+### Relation CRUD Endpoints
+
+| Method | Endpoint            | Description                     |
+| ------ | ------------------- | ------------------------------- |
+| `POST` | `/bulk-save-first`  | Assign multiple first entities  |
+| `POST` | `/bulk-save-second` | Assign multiple second entities |
+| `GET`  | `/first-entities`   | List all first entities         |
+| `GET`  | `/second-entities`  | List all second entities        |
+
+## Extra CRUD
+
+Extended CRUD with parent entity scoping:
+
+```typescript
+import { ExtraCrudController, ExtraCrudService } from "@zola_do/crud";
+
+@Controller("events/:eventId/attendees")
+export class EventAttendeesController extends ExtraCrudController(
+  {
+    entityIdName: "eventId",
+    createPermission: "attendee:create",
+    viewPermission: "attendee:view",
+  },
+  Attendee,
+) {
+  constructor(service: ExtraCrudService<Attendee>) {
+    super(service);
+  }
+}
+```
+
+## Global Exception Filter
+
+The package includes a safe global exception filter:
+
+```typescript
+import { GlobalExceptionFilter } from "@zola_do/crud";
+
+// In your main.ts
+app.useGlobalFilters(new GlobalExceptionFilter());
+```
+
+### Response Format
+
+```typescript
+// Success response
+{
+  "statusCode": 200,
+  "data": { ... }
+}
+
+// Error response (production)
+{
+  "statusCode": 400,
+  "message": "Validation failed",
+  "error": "Bad Request",
+  "path": "/api/products",
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+**Note:** Raw exceptions and stack traces are never exposed to clients in production.
+
+## Delete Modes
+
+| Mode   | Behavior                       | Use Case                                   |
+| ------ | ------------------------------ | ------------------------------------------ |
+| `auto` | Uses entity metadata (default) | Standard entities with `@DeleteDateColumn` |
+| `soft` | Sets `deletedAt` timestamp     | Audit trail required                       |
+| `hard` | Physical delete                | Data that can be safely removed            |
+
+```typescript
+// Force hard delete
+EntityCrudController<Product>({
+  deleteMode: "hard",
+  beforeDelete: async ({ service, params }) => {
+    await service.cleanupRelatedData(params.id);
+  },
+});
+```
+
+## Query String Support
+
+List endpoints support collection query parameters via `?q=`:
+
+```bash
+GET /products?q=w=status$eq$active&t=20&o=createdAt$desc&i=category
+```
+
+See [@zola_do/collection-query](../collection-query) for full query syntax.
+
+## API Reference
+
+### Controllers
+
+#### `EntityCrudController<T>(options: EntityCrudOptions)`
+
+Generic CRUD controller factory.
+
+```typescript
+class EntityCrudController<T> {
+  constructor(
+    protected readonly service: EntityCrudService<T>,
+  ) {}
+
+  // POST /
+  create(@Body() dto: any, @Request() req: any): Promise<T>
+
+  // GET /
+  findAll(
+    @Query('q') query: string,
+    @Request() req: any,
+  ): Promise<CollectionResult<T>>
+
+  // GET /:id
+  findOne(@Param('id') id: string, @Request() req: any): Promise<T>
+
+  // PUT /:id
+  update(
+    @Param('id') id: string,
+    @Body() dto: any,
+    @Request() req: any,
+  ): Promise<T>
+
+  // PATCH /:id
+  patch(
+    @Param('id') id: string,
+    @Body() dto: any,
+    @Request() req: any,
+  ): Promise<T>
+
+  // DELETE /:id
+  delete(@Param('id') id: string, @Request() req: any): Promise<void>
+
+  // PATCH /restore/:id
+  restore(@Param('id') id: string, @Request() req: any): Promise<T>
+
+  // GET /archived
+  findAllArchived(@Request() req: any): Promise<T[]>
+}
+```
+
+#### `ExtraCrudController<T>(options: ExtraCrudOptions, entity: new () => T)`
+
+Extended CRUD with parent entity scope.
+
+#### `RelationCrudController(options: RelationCrudOptions, entity: new () => any)`
+
+Many-to-many relationship management.
+
+### Services
+
+#### `EntityCrudService<T>`
+
+Generic CRUD service with query builder.
+
+```typescript
+class EntityCrudService<T> {
+  constructor(protected readonly repository: Repository<T>) {}
+
+  findAll(query: CollectionQuery): Promise<CollectionResult<T>>;
+  findOne(id: string): Promise<T>;
+  create(data: any): Promise<T>;
+  update(id: string, data: any): Promise<T>;
+  patch(id: string, data: any): Promise<T>;
+  delete(id: string): Promise<void>;
+  restore(id: string): Promise<T>;
+}
+```
+
+### Repositories
+
+#### `EntityCrudRepository<T>`
+
+Repository with built-in query construction.
+
+## Recommended Imports
+
+Subpath imports are recommended for tree-shaking:
+
+```typescript
+import { EntityCrudController } from "@zola_do/crud/controller";
+import { EntityCrudService } from "@zola_do/crud/service";
+import { EntityCrudRepository } from "@zola_do/crud/repository";
+import {
+  CRUD_REQUEST_CONTEXT_RESOLVER,
+  CrudRequestContextResolver,
+} from "@zola_do/crud/request-context";
+import { EntityCrudOptions, GlobalExceptionFilter } from "@zola_do/crud";
+```
+
+Root import is supported for backward compatibility:
+
+```typescript
+import {
+  EntityCrudController,
+  EntityCrudService,
+  EntityCrudOptions,
+} from "@zola_do/crud";
+```
 
-- **Controllers:** `EntityCrudController`, `RelationCrudController`, `ExtraCrudController`
-- **Services:** `EntityCrudService`, `RelationCrudService`, `ExtraCrudService`
-- **Repositories:** `EntityCrudRepository`, `RelationCrudRepository`, `ExtraCrudRepository`
-- **Context Mapping:** `CRUD_REQUEST_CONTEXT_RESOLVER`, `CrudRequestContextResolver`
-- **Subpath entrypoints:** `@zola_do/crud/controller`, `@zola_do/crud/service`, `@zola_do/crud/repository`, `@zola_do/crud/request-context`
-- **Root entrypoint:** `@zola_do/crud` (supported for backward compatibility)
+## Optional Features
 
-### Optional Features
+### RPC Exception Filter
 
-`ExceptionFilter` for Nest microservices transport is available as an optional export:
+For NestJS microservices:
 
 ```typescript
-import { ExceptionFilter } from '@zola_do/crud/optional/rpc';
+import { ExceptionFilter } from "@zola_do/crud/optional/rpc";
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: ExceptionFilter,
+    },
+  ],
+})
+export class OrdersModule {}
 ```
 
-When using this filter, install `@nestjs/microservices` in your app.
+Requires `@nestjs/microservices` peer dependency.
+
+## Troubleshooting
+
+### Q: How do I add custom methods to the CRUD service?
+
+Extend the generic service:
+
+```typescript
+@Injectable()
+export class ProductService extends EntityCrudService<Product> {
+  constructor(
+    @InjectRepository(Product)
+    repository: Repository<Product>,
+  ) {
+    super(repository);
+  }
+
+  async findActive(): Promise<Product[]> {
+    return this.repository.find({ where: { status: "active" } });
+  }
+}
+```
+
+### Q: How do I validate the DTO?
+
+Use `class-validator` decorators:
+
+```typescript
+import { IsString, IsNumber, IsEnum, IsOptional } from "class-validator";
+
+export class CreateProductDto {
+  @IsString()
+  name: string;
+
+  @IsNumber()
+  price: number;
+
+  @IsEnum(["draft", "active", "archived"])
+  @IsOptional()
+  status?: string;
+}
+```
+
+### Q: How do I handle file uploads?
+
+Combine with `@nestjs/platform-express`:
+
+```typescript
+// Add to your DTO
+import { UploadedFile } from '@nestjs/common';
+
+async create(
+  @Body() dto: CreateProductDto,
+  @UploadedFile() file: Express.Multer.File,
+) {
+  if (file) {
+    dto.imageUrl = await this.uploadService.upload(file);
+  }
+  return this.productService.create(dto);
+}
+```
 
 ## Related Packages
 
 - [@zola_do/collection-query](../collection-query) — Query decoding for list endpoints
 - [@zola_do/authorization](../authorization) — Guards for protected CRUD
+- [@zola_do/typeorm](../typeorm) — Entity configuration
+
+## License
+
+ISC
 
 ## Community