crudman-nestjs
Minimal, adapter-driven CRUD layer for NestJS.
Website · NPM · GitHub
> Creating CRUD is so simple. See how a simple States CRUD is defined:
```ts
// states.controller.ts
import { Controller } from '@nestjs/common'
import { UseCrud, CrudControllerBase } from 'crudman-nestjs'
import { State } from './state.entity'
@UseCrud({ sections: { states: { model: State } } })
@Controller('api/states')
export class StatesController extends CrudControllerBase('states') {}
```
That single snippet gives you:
- GET /api/states (with filters, sorting, pagination, keyword)
- GET /api/states/:id (includes relations by default)
- POST /api/states
- PATCH /api/states/:id
- DELETE /api/states/:id
And built-in bulk and export capabilities:
- Bulk import (JSON or CSV)
- Bulk delete (JSON list or CSV ids)
- CSV and Excel export (set `x-content-type: csv` or `excel`)
We believe everyone building RESTful services with NestJS—especially CRUD‑heavy backends—will find this library helpful. It gives you out‑of‑the‑box CRUD endpoints, a clear configuration model, and the freedom to override anything when you need custom behavior. The design centers on adapters (ORM and validator), safe query handling, and simple developer ergonomics so you can start fast and customize when needed.
## Features
- 🔌 Launch-ready CRUD endpoints in minutes
- 🐙 Adapter-first design (TypeORM today; Sequelize-ready)
- 🔎 Powerful querying: filters, sorting, pagination, keyword search
- 🧭 Relations and attributes control (include/exclude, sensible defaults)
- 🧪 Validation built-in (fastest-validator) and swappable (Joi/Zod adapters)
- 🎬 Elegant overrides via decorators or custom handlers
- 🔧 Minimal config: global options + per-section tuning
- 🎁 Base controller for zero-boilerplate auto routes
- ✏️ Swagger-native with entity-driven schemas and envelopes
- 📦 File uploads: multipart/base64/blob with local/S3 adapters and shorthand
- 🧊 NodeCache per-endpoint caching with smart invalidation
## At-a-glance capabilities
| Capability | What you get |
| --- | --- |
| Auto CRUD endpoints | List, details, create, update, delete with a single decorator or base class |
| PATCH-first updates | Modern partial updates by default (configurable to PUT) |
| Relations by default | Include all relations automatically; refine with include/exclude |
| Attributes selection | All columns by default; include/exclude to shape payloads |
| Powerful querying | Clean filters, sorting, pagination, keyword search with safe whitelists |
| Validation built-in | fastest-validator out of the box; Joi/Zod via adapters |
| Caching | NodeCache per-endpoint with invalidation on writes |
| Hooks | Before/after action, query, validation to extend behavior |
| Swagger enhancer | Auto envelopes for list/details/create/update/delete; entity schemas from metadata |
| Save (upsert) | Single endpoint that creates or updates based on id presence |
| Programmatic calls | Safely call other sections' actions from hooks/services |
## UseCrud and sections (quick overview)
`UseCrud` is a class decorator that wires your controller to one or more CRUD "sections". A section is just a named configuration object that points to a model (entity) and optional per-action settings. Each section name becomes the logical key you use in decorators or in the base controller.
- A section maps to a resource (e.g., `users`, `companies`).
- `UseCrud({ sections: { companies: { model: Company, ... } } })` registers the section and its options.
- You then either:
- Extend `CrudControllerBase('companies')` to get all endpoints for that section automatically, or
- Use the route decorators like `@CrudList('companies')` to bind specific methods.
Minimal single-section controller (zero handlers):
```ts
import { Controller } from '@nestjs/common'
import { UseCrud, CrudControllerBase } from 'crudman-nestjs'
import { Company } from './company.entity'
@UseCrud({ sections: { companies: { model: Company } } })
@Controller('api/companies')
export class CompaniesController extends CrudControllerBase('companies') {}
```
Multiple sections in one controller (explicit endpoints):
```ts
import { Controller, Get, Post, Patch, Delete } from '@nestjs/common'
import { UseCrud, CrudList, CrudDetails, CrudCreate, CrudUpdate, CrudDelete } from 'crudman-nestjs'
import { User } from './user.entity'
import { Company } from './company.entity'
@UseCrud({ sections: { users: { model: User }, companies: { model: Company } } })
@Controller('api')
export class ApiController {
@Get('users') @CrudList('users') listUsers() {}
@Get('users/:id') @CrudDetails('users') getUser() {}
@Post('users') @CrudCreate('users') createUser() {}
@Patch('users/:id') @CrudUpdate('users') updateUser() {}
@Delete('users/:id') @CrudDelete('users') deleteUser() {}
}
```
Section options (selected):
```ts
@UseCrud({
sections: {
companies: {
model: Company,
list: {
relations: '*', // include all relations by default
attributes: { exclude: ['secret'] }, // all columns except listed
filtersWhitelist: ['name','isActive','createdAt'],
additionalSettings: { repo: companyRepository } // TypeORM repo
},
details: { relations: ['contacts'], additionalSettings: { repo: companyRepository } },
create: { additionalSettings: { repo: companyRepository } },
update: { additionalSettings: { repo: companyRepository } },
delete: { additionalSettings: { repo: companyRepository } },
}
}
})
```
How it links together:
- `UseCrud` stores the sections configuration once on the controller class.
- The library reads that config inside `CrudmanService` and the ORM adapter to resolve repositories, relations, attributes, filters, etc.
- Decorators like `@CrudList('companies')` or the base `CrudControllerBase('companies')` tell the library which section's settings to apply for a given route.
## Shorthand: UseCrud({ models })
Create CRUD endpoints for multiple models in one controller without writing section objects. This plays nicely with everything else (validation, swagger, caching, relations/attributes, updateMethod, etc.).
Minimal usage (entities):
```ts
@UseCrud({
models: [User, Company, State],
defaults: {
pathStyle: 'kebab', // 'kebab'|'snake'|'camel'|'pascal'; default 'kebab'
updateMethod: 'patch', // override module default if needed
attributes: { read: '*', write: '*' },
relations: '*'
}
})
@Controller('api')
export class ApiController extends CrudControllerBase('*') {} // '*' mounts all sections in this controller
```
Routes generated:
- User → `/api/users`
- Company → `/api/companies`
- State → `/api/states`
Per-model overrides (tuple form):
```ts
@UseCrud({
models: [
User,
[Company, { attributes: { read: { exclude: ['secret'] }, write: { exclude: ['id','createdAt'] } } }],
[State, { relations: { include: ['country'] }, filtersWhitelist: ['name','countryId'] }],
]
})
@Controller('api')
export class ApiController extends CrudControllerBase('*') {}
```
Per-model overrides (map form):
```ts
@UseCrud({
models: {
User: {},
Company: { attributes: { write: { exclude: ['id','createdAt'] } } },
State: { relations: { exclude: ['country'] } }
}
})
```
Model-first (no entity class):
```ts
@UseCrud({
models: [
{
name: 'FeatureFlag',
fields: {
key: { type: 'string', primary: true },
enabled: { type: 'boolean' },
createdAt: { type: 'date', readonly: true }
},
attributes: { read: '*', write: { exclude: ['createdAt'] } },
}
]
})
```
Notes:
- Section/route naming derives from `model.name` (pluralized); can be overridden per model.
- Explicit `sections` and decorator methods always override the shorthand.
- For TypeORM, repositories resolve by entity. For model specs, provide `additionalSettings.repo` or a custom adapter.
## Attributes: read vs write
You can control which fields are returned to clients (read) and which fields clients can send (write). Defaults include all fields `'*'`.
Where to configure:
- Shared: `defaults.attributes` (applied to all actions unless overridden)
- Per action: `list.details.create.update.delete.attributes`
Shapes:
```ts
attributes: {
read: '*' | { include?: string[]; exclude?: string[] },
write: '*' | { include?: string[]; exclude?: string[] }
}
```
Examples:
Return fewer fields in list, allow only safe fields on create:
```ts
list: { attributes: { read: { exclude: ['internalNotes'] } } },
create: { attributes: { write: { include: ['name','email','role'] } } }
```
Keep all fields readable, but prevent writes to system fields:
```ts
defaults: { attributes: { read: '*', write: { exclude: ['id','createdAt','updatedAt'] } } }
```
With shorthand models:
```ts
@UseCrud({
models: [
[Company, { attributes: { read: { exclude: ['secret'] }, write: { exclude: ['id','createdAt'] } } }]
]
})
```
### Attribute inclusion/exclusion examples
Global defaults (apply to all actions unless overridden):
```ts
CrudmanModule.forRoot({
// keep all fields readable, but protect system fields from writes globally
defaults: { attributes: { read: '*', write: { exclude: ['id','createdAt','updatedAt'] } } }
})
```
Per-section defaults:
```ts
@UseCrud({ sections: {
users: {
model: User,
// only expose a minimal public profile across list/details
attributes: { read: { include: ['id','firstName','lastName','avatarUrl'] } }
}
}})
```
Per-action read narrowing (exclude sensitive columns on list only):
```ts
list: { attributes: { read: { exclude: ['internalNotes','lastLoginIp'] } } },
details:{ attributes: { read: '*' } }
```
Per-action write allow-list (create allows only safe inputs):
```ts
create: { attributes: { write: { include: ['name','email','role'] } } },
update: { attributes: { write: { exclude: ['id','createdAt','updatedAt'] } } }
```
Combine include/exclude (exclude wins outside include scope):
```ts
attributes: {
read: { include: ['id','name','email','profile'], exclude: ['email'] }, // → effectively ['id','name','profile']
write: { include: ['name','email','role'], exclude: ['role'] } // → effectively ['name','email']
}
```
Shorthand models (per-model override):
```ts
@UseCrud({
models: [
[Company, { attributes: { read: { exclude: ['secret'] }, write: { exclude: ['id','createdAt'] } } }],
[User, { attributes: { read: { include: ['id','firstName','lastName','avatarUrl'] } } }]
]
})
```
## CrudControllerBase explained
`CrudControllerBase(sectionName: string)` is a tiny base class that auto-binds the five standard routes for a single section:
- `GET /` → list
- `GET /:id` → details
- `POST /` → create
- `PATCH /:id` (default) → update (verb configurable via `updateMethod`)
- `DELETE /:id` → delete
You pass the section name you registered in `UseCrud`:
```ts
@UseCrud({ sections: { users: { model: User } } })
@Controller('api/users')
export class UsersController extends CrudControllerBase('users') {}
```
This is ideal when one controller maps to one resource (section) and you don't need custom method bodies. If you later need to override one route, you can add a method and use the decorator variant, e.g.:
```ts
@Get(':id')
@CrudDetails('users')
details(@Req() req) { /* custom logic */ }
```
## File uploads (create/update/save)
CrudMan supports files in requests via a simple, pluggable system. You can accept files as multipart/form-data, base64 strings (in JSON), or even blobs, and choose how they are stored per field.
### Quick start: enable avatar upload in `users` (minimal)
```ts
@UseCrud({ sections: {
users: {
model: User,
common: {
// one-field image preset → adds avatarKey + avatarUrl columns with filename storage
uploadable: { avatar: 'image' },
uploadDefaults: { storage: 'local' }
}
}
}})
@Controller('api/users')
export class UsersController extends CrudControllerBase('users') {}
```
Requests you can send:
- Multipart: form-data with field `avatar` as file
- JSON (base64): `{ "avatar": "data:image/png;base64,iVBORw0..." }`
Entity columns created/expected (filename mode):
- `avatarKey: string | null`, `avatarUrl: string | null`
List response excerpt (avatar URL in data; base URLs under meta):
```json
{
"data": [{ "id": 1, "name": "Alice", "avatarUrl": "uploads/avatars/1.png" }],
"success": true,
"meta": { "baseUrls": { "uploads": "http://localhost:3000" } },
"pagination": { "page": 1, "perPage": 20 }
}
```
Note: Full image URL = `meta.baseUrls.uploads + '/' + data[i].avatarUrl` → e.g., `http://localhost:3000/uploads/avatars/1.png`.
- Sources: `multipart` (form-data), `base64` (JSON); streams/presigned (advanced)
- Storage modes:
- `filename` (recommended): upload using a storage adapter (Local/S3/etc.), store only key/filename and optional URL in your entity
- `base64`: store the base64 string in a text column
- `blob`: store a Buffer in a BLOB/bytea column, with an adjacent mime column
- Validation: `maxSizeMB`, `allowedMimeTypes`, `allowedExtensions`; shorthands: `image`, `video`, `pdf`, `doc`
- Extras: an optional `extra` field is appended to responses; with shorthand image fields, `imageBases` is auto-populated with public URLs
### Quick start (shorthand)
```ts
@UseCrud({ sections: {
profiles: {
model: Profile,
common: {
uploadable: { avatar: 'image' }, // → avatarKey + avatarUrl on entity
uploadDefaults: { storage: 'local' }
}
}
}})
```
Request forms:
- Multipart: form-data with field `avatar` as a file
- JSON base64: `{ "avatar": "data:image/png;base64,iVBORw0..." }`
Entity columns for `avatar: 'image'` (filename mode):
- `avatarKey: string | null`, `avatarUrl: string | null`
### Full control (per-action or common)
```ts
sections: {
documents: {
model: Doc,
common: {
upload: {
sources: ['multipart','base64'],
map: [
{ sourceField: 'file', storageMode: 'filename', storage: 's3', targetField: { key: 'fileKey', url: 'fileUrl' }, validators: { maxSizeMB: 10, allowedExtensions: ['.pdf'] }, typeHint: 'pdf' },
{ sourceField: 'thumbnail', storageMode: 'base64', targetField: 'thumbnailBase64', typeHint: 'image' }
]
}
}
}
}
```
### Direct-field storage (no keys)
Store the uploaded filename directly into an existing column (no `...Key`/`...Url` fields).
```ts
sections: {
users: {
model: User,
common: {
upload: {
sources: ['multipart'],
map: [
{
sourceField: 'avatar',
storageMode: 'filename_in_field', // write relative filename directly to the target field
storage: 'local',
targetField: 'avatar', // your entity must have `avatar: string | null`
typeHint: 'image-jpg',
validators: { maxSizeMB: 2 }
}
]
}
}
}
}
``;
Result:
- Multipart field `avatar` → stored via `local` storage → entity `avatar` receives a relative filename (e.g. `uploads/u1/avatar.jpg`).
- No extra key/url columns are created or used.
### Preset examples (image-jpg, image-png, avatar)
```ts
// JPEG only
uploadable: { avatar: 'image-jpg' }
// PNG only
uploadable: { logo: 'image-png' }
// Avatar constraints (min/max dimensions, ~1:1)
uploadable: { avatar: 'image-avatar' }
// Array of images (JPEG)
upload: {
sources: ['multipart'],
map: [
{ sourceField: 'gallery', isArray: true, storageMode: 'filename', storage: 'local',
targetField: { keys: 'galleryKeys', urls: 'galleryUrls' }, typeHint: 'image-jpg' }
]
}
```
### Upload options reference
- `uploadable: Record`
- Shorthand that expands to an `upload.map` entry per field.
- Value is a preset/typeHint (e.g., `'image' | 'image-jpg' | 'image-png' | 'pdf' | 'doc' | 'video' | ...`).
- Array value indicates multiple files for that field.
- `upload: { sources?: ('multipart'|'base64')[]; map: UploadMapEntry[] }`
- `sources`: allowed input sources. Default often `['multipart','base64']` depending on context.
- `map`: array of rules mapping incoming fields to entity fields.
- `UploadMapEntry` fields:
- `sourceField: string` (form/base64 field name)
- `targetField: string | { key?: string; url?: string; keys?: string; urls?: string }`
- `isArray?: boolean` → multiple files under the same field
- `storageMode: 'filename' | 'filename_in_field' | 'blob' | 'base64'`
- `filename`: upload via storage adapter, keep only key/url in entity (recommended)
- `filename_in_field`: write relative filename directly into a single string column
- `blob`: store Buffer in a BLOB/bytea column (set `targetField` to the blob column; consider also storing mime)
- `base64`: keep base64 as text in the target field
- `storage?: string` → name of a configured storage (e.g., `'local'`, `'s3'`)
- `typeHint?: string` → preset that sets default validators (e.g., `image`, `image-jpg`, `pdf`)
- `validators?: { maxSizeMB?: number; allowedMimeTypes?: string[]; allowedExtensions?: string[] }`
- `sources?: ('multipart'|'base64')[]` → narrow sources per entry
Response notes:
- Create/Update responses include `meta.baseUrls` (when configured) and merged extra metadata.
- Swagger shows three request body tabs (json/form/multipart) by default; file fields appear as binary in multipart.
### Validation and rules
- Uploads are processed into `req.body` first; then your validator runs.
- Shorthands (`image`, `video`, `pdf`, `doc`) infer typical mime/extension allow lists.
- Use `getFinalValidationRules` to merge with or override generated rules.
### Swagger
- Create/Update endpoints are annotated with `multipart/form-data` and normal `application/json`.
- Responses include a `meta` object (non-resource data). For shorthand image fields, responses include `meta.baseUrls` automatically.
## Supported upload types (presets)
Use these presets in `uploadable` (or explicit `upload.map` → `typeHint`) to get sensible defaults for MIME, extensions, and size. All limits are defaults; override with `validators` per field/section. Avatar presets also enforce image dimensions.
| Type | Allowed MIME types | Extensions | Max size (MB) | Image constraints | Notes |
|--------------------------|--------------------------------------------------------------|------------------------------------------|---------------|----------------------------------------------------|-------|
| image | image/jpeg, image/png, image/gif, image/webp, image/avif | .jpg, .jpeg, .png, .gif, .webp, .avif | 5 | — | group |
| image-jpg | image/jpeg | .jpg, .jpeg | 5 | — | |
| image-png | image/png | .png | 5 | — | |
| image-gif | image/gif | .gif | 5 | — | |
| image-webp | image/webp | .webp | 5 | — | |
| image-avif | image/avif | .avif | 5 | — | |
| image-avatar | jpeg, png, gif, webp, avif | .jpg, .jpeg, .png, .gif, .webp, .avif | 2 | min 128x128, max 4096x4096, aspect ~1:1 | avatars |
| image-jpg-avatar | image/jpeg | .jpg, .jpeg | 2 | min 128x128, max 4096x4096, aspect ~1:1 | avatars |
| image-png-avatar | image/png | .png | 2 | min 128x128, max 4096x4096, aspect ~1:1 | avatars |
| image-webp-avatar | image/webp | .webp | 2 | min 128x128, max 4096x4096, aspect ~1:1 | avatars |
| image-avif-avatar | image/avif | .avif | 2 | min 128x128, max 4096x4096, aspect ~1:1 | avatars |
| video | video/mp4, video/webm, video/ogg | .mp4, .webm, .ogg | 100 | — | |
| video-mp4 | video/mp4 | .mp4 | 100 | — | |
| video-webm | video/webm | .webm | 100 | — | |
| video-ogg | video/ogg | .ogg | 100 | — | |
| video-short | video/mp4, video/webm | .mp4, .webm | 25 | — | short clips |
| audio | audio/mpeg, audio/mp4, audio/aac, audio/ogg, audio/wav | .mp3, .m4a, .aac, .ogg, .wav | 20 | — | |
| pdf | — | .pdf | 10 | — | |
| doc | — | .pdf, .doc, .docx, .odt | 10 | — | |
| spreadsheet | — | .xls, .xlsx, .csv | 10 | — | group |
| spreadsheet-csv | text/csv | .csv | 5 | — | |
| spreadsheet-xls | application/vnd.ms-excel | .xls | 10 | — | |
| spreadsheet-xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx | 10 | — | |
| csv | text/csv | .csv | 5 | — | |
| xml | application/xml, text/xml | .xml | 2 | — | |
| html | text/html | .html, .htm | 2 | — | |
| json | application/json | .json | 2 | — | |
| text | text/plain, text/markdown | .txt, .md | 2 | — | |
| archive | — | .zip, .tar, .gz, .rar, .7z | 200 | — | |
| binary | application/octet-stream | any | 50 | — | raw blobs |
Notes:
- These are defaults; override with `validators` on each upload rule or via `uploadDefaults.validators`.
- Default storage mode is `filename_in_field` (relative filename saved directly in your entity field).
- By default, list/details include `meta.baseUrls` so clients can build full URLs. Per-request override header: `x-file-url=full|key_only`.
Usage (shorthand):
```ts
@UseCrud({ sections: {
profiles: {
model: Profile,
uploadable: { avatar: 'image-avatar' },
uploadDefaults: { storage: 'local' } // storage is defined in module forRoot
}
}})
```
## Overview
crudman-nestjs is a plug-and-play CRUD layer for NestJS. It auto-generates REST endpoints (list, details, create, update, delete) from a simple section config that references your entity model.
- Auto routes: extend `CrudControllerBase('section')` to get CRUD endpoints with zero handler code.
- Decorator overrides: use `@CrudList`, `@CrudDetails`, `@CrudCreate`, `@CrudUpdate`, `@CrudDelete` to customize any endpoint.
- TypeORM-first: works with repositories you provide (in `additionalSettings.repo`). A Sequelize adapter can be added later without changing configs.
- Validation-first: fastest-validator by default; swap validators (Joi/Zod) through a small adapter interface.
- Safe filtering/sorting: allow-list fields to prevent abuse in public endpoints.
- Caching: NodeCache with per-endpoint control and global invalidation on writes.
- OpenAPI-ready: enable/disable swagger globally or per endpoint, pass DTOs to describe `data`.
## Installation
```bash
npm i crudman-nestjs
```
### Zero-config TypeORM DataSource
From v1.0.0+, Crudman attempts to auto-discover your TypeORM `DataSource` at app startup. In most apps this is enough. If your app initializes the DataSource later or uses a custom pattern, set it manually once after bootstrap as shown below. We also recommend registering `ModuleRef` and `DataSource` explicitly in your `main.ts` for determinism.
```ts
import { DataSource } from 'typeorm'
import { setCrudmanDataSource } from 'crudman-nestjs'
// In your bootstrap function (after await app.init())
const ds = app.get(DataSource)
setCrudmanDataSource(ds)
// Optionally (recommended): also register ModuleRef and DataSource
import { setCrudmanModuleRef } from 'crudman-nestjs'
setCrudmanModuleRef(app)
### Error handling mode
You can choose between thrown HttpExceptions (default) or JSON envelopes for errors.
```ts
CrudmanModule.forRoot({
throwOnError: true // default true; set false to keep envelope-style error bodies
})
```
```
## Swagger Configuration
Crudman automatically generates comprehensive Swagger documentation for all your CRUD endpoints. Here's how to configure it:
### Basic Setup
1. **Install Swagger dependencies** (if not already installed):
```bash
npm install @nestjs/swagger swagger-ui-express
```
2. **Configure Swagger in your main.ts**:
```ts
import 'reflect-metadata'
import { NestFactory } from '@nestjs/core'
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'
import { enhanceCrudSwaggerDocument } from 'crudman-nestjs'
import { AppModule } from './app.module'
async function bootstrap() {
const app = await NestFactory.create(AppModule)
// Set up Swagger
const config = new DocumentBuilder()
.setTitle('Your API Title')
.setVersion('1.0')
.build()
const document = SwaggerModule.createDocument(app, config)
enhanceCrudSwaggerDocument(document) // This enhances CRUD endpoints
SwaggerModule.setup('docs', app, document)
await app.listen(3000)
console.log('Application is running on: http://localhost:3000')
console.log('Swagger docs available at: http://localhost:3000/docs')
}
bootstrap()
```
3. **Access your API documentation**:
- **Swagger UI**: `http://localhost:3000/docs`
- **JSON Schema**: `http://localhost:3000/docs-json`
### What's Auto-Generated
The `enhanceCrudSwaggerDocument()` function automatically adds:
- **Complete API endpoints** for all CRUD operations (GET, POST, PATCH/PUT, DELETE)
- **Request/Response schemas** based on your TypeORM entities
- **Pagination details** for list endpoints
- **Query parameters** (filters, sorting, search, pagination)
- **File upload specifications** for endpoints with file uploads
- **Response envelopes** with proper data structure
- **Validation rules** and error responses
### Request body content types (write endpoints)
- By default, POST/PUT/PATCH show three tabs:
- `application/json`: inline JSON properties derived from your entity (create: required fields; update: all optional)
- `application/x-www-form-urlencoded`: same inline properties as form fields
- `multipart/form-data`: file inputs (when uploads configured) + scalar entity fields
- Relations are excluded from write bodies by default.
You can customize globally via `CrudmanModule.forRoot`:
```ts
CrudmanModule.forRoot({
swagger: {
enabled: true,
// How JSON request body is shown: inline object vs $ref to component schema
requestBodySchemaMode: 'inline', // 'inline' | 'ref'
// Which content types to include for write endpoints
requestBodyContentTypes: ['json','form','multipart'],
// Include relation properties in write bodies
includeRelationsInWriteBody: false
}
})
```
Per-section override:
```ts
@UseCrud({
sections: {
companies: {
model: Company,
swagger: {
requestBodySchemaMode: 'inline',
requestBodyContentTypes: ['json','form'],
includeRelationsInWriteBody: false
}
}
}
})
```
Notes:
- Inline JSON schema excludes readonly fields (id/createdAt/updatedAt) and upload target fields.
- multipart shows only scalar fields; complex fields are stringified.
- You can use any path for docs (e.g., `'docs'` or `'swagger'`) in `SwaggerModule.setup(path, app, document)`.
### Global Swagger Configuration
You can set global Swagger metadata via the module options:
```ts
CrudmanModule.forRoot({
swagger: { enabled: true },
swaggerMeta: {
title: 'My Awesome API',
version: '2.0.0',
description: 'Internal platform APIs'
}
})
```
**Defaults** (if not provided):
- title: humanized package.json name (e.g., `crudman-nestjs` → `Crudman Nestjs`)
- version: package.json version (e.g., `1.0.0`)
- description: `CRUD APIs for {title}`
### Export Content Types
Control which response content types are available for list/details via the `x-content-type` header:
```ts
CrudmanModule.forRoot({
swagger: { enabled: true },
exportContentTypes: ['json','csv'] // disable excel globally
})
```
The Swagger docs will only show the allowed values in the header enum.
### TypeORM Integration
If you're using TypeORM, make sure to set the DataSource:
```ts
import { DataSource } from 'typeorm'
import { setCrudmanDataSource } from 'crudman-nestjs'
// In your bootstrap function (after await app.init()):
const ds = app.get(DataSource)
setCrudmanDataSource(ds)
```
## Quick start (auto routes)
Minimal controller with auto-generated endpoints:
```ts
import { Controller } from '@nestjs/common';
import { UseCrud, CrudControllerBase } from 'crudman-nestjs';
import { User } from '../entities/user.entity';
@UseCrud({ sections: { users: { model: User } } })
@Controller('api/users')
export class UsersController extends CrudControllerBase('users') {}
```
Routes available:
- GET /api/users
- GET /api/users/:id
- POST /api/users
- PATCH /api/users/:id
- DELETE /api/users/:id
To override any one, add your own method and decorate it with `@CrudList`, `@CrudDetails`, etc.
### List APIs and pagination (quick reference)
The list endpoint is available at `GET /api/{section}` (e.g., `GET /api/companies`).
- **Pagination params**
- `page` (default: 1)
- `perPage` (default: 30; alias `per_page` supported)
- `paginate` = `false|0|no` to disable pagination (when allowed by config)
- **Sorting**
- `sort.=asc|desc` (repeatable for multi-sort)
- **Filters**
- Equals: `field=value`
- Like: `field.like=value`
- Ranges: `field.min=value`, `field.max=value`, `field.gt=value`, `field.lt=value`
- Between: `field.between=start,end`
Examples:
```text
# Page 2 with 20 items per page
GET /api/companies?page=2&perPage=20
# Multi-sort: newest first, then name ascending
GET /api/companies?sort.createdAt=desc&sort.name=asc&page=1&perPage=25
# Disable pagination (returns all when allowed)
GET /api/companies?paginate=false
```
Response excerpt (pagination meta):
```json
{
"data": [/* ...items... */],
"success": true,
"pagination": {
"page": 2,
"perPage": 25,
"totalItemsCount": 137,
"totalPagesCount": 6,
"isHavingNextPage": true,
"isHavingPreviousPage": true
},
"filters": [],
"sorting": []
}
```
Notes:
- Snake_case aliases are accepted and normalized (e.g., `per_page` → `perPage`).
- Allowed filter/sort fields are controlled by `filtersWhitelist`/`sortingWhitelist` (or all columns by default).
### Release notes
- **Known issue**: Swagger UI may not show individual input fields for `multipart/form-data` in create/update endpoints in some setups. JSON and form-urlencoded render inline correctly; multipart fallback may appear as a generic object. Work in progress.
## Example project (TypeORM + SQLite)
A ready-to-run example lives in `examples/nest-typeorm-sqlite`. It wires multiple entities, uploads, and Swagger.
Run it locally:
```bash
cd examples/nest-typeorm-sqlite
npm install
npm run build
npm start
# Swagger: http://localhost:3001/docs
# API base: http://localhost:3001/api
```
Developer mode:
```bash
cd examples/nest-typeorm-sqlite
npm install
npm run start:dev
```
Optional seed:
```bash
cd examples/nest-typeorm-sqlite
npm run seed
```
Notes:
- SQLite files and `uploads/` are Git-ignored inside the example project.
- The example serves `/uploads/*` statically when the folder exists.
- Swagger is initialized before `app.init()` and enhanced via `enhanceCrudSwaggerDocument` to avoid `/docs` 404.
## Module registration
Register the module once with sensible defaults:
```ts
import { Module } from '@nestjs/common';
import { CrudmanModule, defaultResponseFormatter } from 'crudman-nestjs';
@Module({
imports: [
CrudmanModule.forRoot({
swagger: { enabled: true },
cache: { enabled: true, stdTTL: 60, checkperiod: 120, invalidateListsOnWrite: true },
defaultResponseFormatter,
identityAccessor: (req) => req.identity || req.user || {},
roleChecker: (identity, roles) => !roles?.length || roles.includes(identity?.role),
// HTTP verb for update endpoints: default 'patch'. Set to 'put' to use PUT.
updateMethod: 'patch',
// defaultOrm, defaultValidator can be supplied to replace built-ins
}),
],
})
export class AppModule {}
```
Parameters (forRoot):
- swagger.enabled: boolean. Enables swagger decorators by default. You can disable per endpoint in decorator options.
- cache: { enabled, stdTTL, checkperiod, maxKeys?, invalidateListsOnWrite }
- enabled: turn on/off NodeCache integration.
- stdTTL: default TTL (seconds).
- checkperiod: cache cleanup interval (seconds).
- invalidateListsOnWrite: when true, writes will invalidate list caches globally.
- defaultResponseFormatter: function to shape API responses (see Response formatter).
- identityAccessor(req): returns `{ id, role, merchant_id? }` extracted from request.
- roleChecker(identity, roles): returns boolean; simple role check logic.
- defaultOrm: override the default ORM adapter (e.g., custom TypeORM adapter).
- defaultValidator: override the validator adapter (e.g., Joi).
## Section config
Minimal:
```ts
{ model: User }
```
Expanded (TypeORM example):
```ts
{
model: User,
list: {
relations: ['profile'],
getRelations: async (req) => (req.query.withRoles ? ['profile','roles'] : ['profile']),
filtersWhitelist: ['email','createdAt','role'],
sortingWhitelist: ['createdAt','email'],
orderBy: [['createdAt','DESC']],
onBeforeQuery: async (opts) => {
// opts is a TypeORM FindManyOptions-like object
opts.where = { ...(opts.where||{}), isActive: true }
return opts
},
onBeforeValidate: async (req, res, rules, validator) => true,
onAfterValidate: async (req, res, errors, validator) => true,
enableCache: { ttl: 60 },
additionalSettings: { repo: userRepository }, // your TypeORM repository
},
details: { relations: ['profile'], enableCache: true, additionalSettings: { repo: userRepository } },
create: { fieldsForUniquenessValidation: ['email'], additionalSettings: { repo: userRepository } },
update: { fieldsForUniquenessValidation: ['email'], additionalSettings: { repo: userRepository } },
delete: { additionalSettings: { repo: userRepository } },
requiredRoles: ['admin'],
ownership: { field: 'user_id' },
}
```
Keys (per action, unless noted):
- model (required): Entity class.
- relations (optional): '*' | string[] | { include?: string[]; exclude?: string[] }.
- getRelations(req,res,cfg) (optional): Promise | (string[] | { include?: string[]; exclude?: string[] } | '*' | undefined).
- Semantics:
- '*' → include all relations by default.
- string[] → include only the listed relations.
- { include } → include only the listed relations.
- { exclude } → include all except the listed relations.
- filtersWhitelist (optional): string[]. If not provided, all entity columns are allowed (derived from repository metadata).
- sortingWhitelist (optional): string[]. If not provided, all entity columns are allowed (derived from repository metadata).
- orderBy (optional): Array<[field, "ASC"|"DESC"]>.
- recordSelectionField (optional): string, default "id".
- fieldsForUniquenessValidation (optional): string[].
- conditionTypeForUniquenessValidation (optional): "or"|"and".
- hooks (optional): onBeforeAction, onAfterAction, onBeforeQuery, onAfterFetch, onBeforeValidate, onAfterValidate.
- additionalResponse (optional): object or function `(req, res, currentResponse) => object` whose returned properties are merged into the response `meta`.
- getAdditionalResponse (optional): function `(req, res, currentResponse) => object | Promise