repository·master·Indexed 26 days ago
https://github.com/nestjsx/crudA microframework for NestJS that automates the creation of RESTful CRUD endpoints. It provides powerful query parsing for filtering, pagination, sorting, and relations across different databases. The project includes the core @nestjsx/crud package, @nestjsx/crud-request for request building and parsing, and @nestjsx/crud-typeorm for TypeORM-specific database operations.
The TypeOrmCrudService uses the createBuilder method to translate CrudRequest options into a TypeORM SelectQueryBuilder.
options.query.join. If a join is marked as eager: true in the configuration, it will be applied automatically. Otherwise, joins are applied based on the parsed.join array in the request.query.fields or via options.allow/options.exclude. The service always ensures primary columns are included in the selection.@DeleteDateColumn, the service supports soft deletion. You can toggle this behavior using options.query.softDelete and include deleted records using parsed.includeDeleted === 1.When setting up @nestjsx/crud-typeorm, you can define connection settings using TypeOrmModuleOptions. The configuration supports different database types (e.g., postgres, mysql) and can be driven by environment variables for connection type and logging behavior.
Key configuration properties:
type: The database engine (e.g., 'postgres', 'mysql'). Can be set via process.env.TYPEORM_CONNECTION.logging: Boolean flag to enable/disable logging. Can be controlled via process.env.TYPEORM_LOGGING (expects a numeric string like '1' for true).entities: An array of paths to entity files (e.g., join(__dirname, './**/*.entity{.ts,.js}')).The project is split into several specialized packages depending on your needs:
@nestjsx/crud: The core package. It provides the @Crud() decorator for automatic endpoint generation, global configuration, validation, and helper decorators.@nestjsx/crud-request: A request builder/parser package. It includes RequestQueryBuilder for frontend usage and RequestQueryParser for backend handling and validation of query/path parameters.@nestjsx/crud-typeorm: A TypeORM-specific package. It provides the TypeOrmCrudService which contains methods for standard CRUD database operations.CrudRequestInterceptor, if the incoming query fails validation or parsing, the interceptor catches RequestQueryException and rethrows it as a NestJS BadRequestException. This ensures that malformed CRUD queries result in a standard 400 Bad Request response instead of internal server errors.RequestQueryException is thrown by the @nestjsx/crud packages when a request query is invalid. This exception extends the standard JavaScript Error class and carries a specific error message describing the invalid query parameters.The ParamsOptions interface allows you to define configuration for route parameters using a dictionary where keys are parameter names and values are ParamOption objects. This is used to control how specific fields are handled in CRUD operations.
Each ParamOption can specify:
field: The underlying database field name associated with the parameter.type: The data type of the parameter (using ParamOptionType from @nestjsx/crud-request).enum: An enumeration type for the parameter (using SwaggerEnumType).primary: A boolean indicating if this is a primary parameter.disabled: A boolean to disable the parameter.export interface ParamsOptions {
[key: string]: ParamOption;
}
export interface ParamOption {
field?: string;
type?: ParamOptionType;
enum?: SwaggerEnumType;
primary?: boolean;
disabled?: boolean;
}The TypeOrmCrudService<T> is the TypeORM implementation of the CrudService. It provides asynchronous methods to perform standard CRUD operations using a TypeORM Repository.
Key methods include:
getMany(req: CrudRequest): Retrieves multiple records based on the request parameters (filtering, sorting, pagination, joins).getOne(req: CrudRequest): Retrieves a single record.createOne(req: CrudRequest, dto: T | Partial<T>): Creates a single record.createMany(req: CrudRequest, dto: CreateManyDto<T | Partial<T>>): Creates multiple records in bulk (using a chunk size of 50).updateOne(req: CrudRequest, dto: T | Partial<T>): Updates an existing record.replaceOne(req: CrudRequest, dto: T | Partial<T>): Replaces an existing record.deleteOne(req: CrudRequest): Deletes a record (supports soft delete if the entity has a delete column and softDelete: true is in the query options).recoverOne(req: CrudRequest): Recovers a soft-deleted record.@nestjsx/crud-typeorm package provides TypeOrmCrudService, which is the primary service used to integrate NestJS CRUD functionality with TypeORM. This service handles the mapping between CRUD requests and TypeORM repository operations.validateJoin to validate a QueryJoin object. It ensures the join is an object with a valid field string. If a select property is provided, it must be an array of strings.When constructing filters for CRUD requests, you can use either the QueryFilter object or the QueryFilterArr tuple format.
QueryFilter requires a field (string), an operator (from ComparisonOperator), and an optional value.
QueryFilterArr is a tuple in the format: [field, operator, value?].
RecoverOneRouteOptions interface extends BaseRouteOptions and includes the returnRecovered property. When set to true, the API will return the entity that was just recovered.