{"id":26830639,"url":"https://github.com/guichaguri/crud-query-parser","last_synced_at":"2025-04-30T08:13:46.139Z","repository":{"id":89786077,"uuid":"525464417","full_name":"Guichaguri/crud-query-parser","owner":"Guichaguri","description":"Parses queries from HTTP requests and adapts them to database queries","archived":false,"fork":false,"pushed_at":"2025-04-18T04:52:09.000Z","size":462,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-30T08:13:42.480Z","etag":null,"topics":["crud-api","crud-requests","dynamodb","express","mongodb","mongoose","nextjs","sequelize","typeorm"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/crud-query-parser","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Guichaguri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-08-16T16:42:59.000Z","updated_at":"2025-04-18T04:52:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"cbb1ce36-9a14-468d-9338-e85f9b919998","html_url":"https://github.com/Guichaguri/crud-query-parser","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guichaguri%2Fcrud-query-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guichaguri%2Fcrud-query-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guichaguri%2Fcrud-query-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Guichaguri%2Fcrud-query-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Guichaguri","download_url":"https://codeload.github.com/Guichaguri/crud-query-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251666361,"owners_count":21624298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crud-api","crud-requests","dynamodb","express","mongodb","mongoose","nextjs","sequelize","typeorm"],"created_at":"2025-03-30T14:16:52.032Z","updated_at":"2025-04-30T08:13:46.132Z","avatar_url":"https://github.com/Guichaguri.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# crud-query-parser\n\n[![NPM](https://img.shields.io/npm/v/crud-query-parser)](https://www.npmjs.com/package/crud-query-parser) [![Coverage](https://img.shields.io/codecov/c/github/Guichaguri/crud-query-parser?token=KFJIJ220HD)](https://codecov.io/github/Guichaguri/crud-query-parser)\n\nThis library parses query parameters from HTTP requests and converts them to database queries, allowing advanced filtering, column selection, pagination and relation joining.\n\n## Features\n\n- Modular architecture, can be extended as needed\n- Flexible request manipulation and filtering\n- Supports the `@nestjsx/crud` query parameter syntax\n- [TypeORM support](./docs/adapters/typeorm.md)\n- [Sequelize support](./docs/adapters/sequelize.md)\n- [MongoDB and Mongoose support](./docs/adapters/mongodb.md)\n- [DynamoDB support](./docs/adapters/dynamodb.md)\n- [JS arrays support](./docs/adapters/array.md)\n- Framework-agnostic\n  - Supports [NestJS](./docs/frameworks/nestjs.md), [NextJS](./docs/frameworks/nextjs.md), [Express](./docs/frameworks/express.md), [Fastify](./docs/frameworks/fastify.md), [h3](./docs/frameworks/h3.md), [tinyhttp](./docs/frameworks/tinyhttp.md), [http package](./docs/frameworks/nodejs-http.md) and many more\n\n## Install\n\n```sh\nnpm install crud-query-parser\n```\n\n## Usage\n\n```mermaid\nflowchart LR\n    A(RequestParser) --\u003e B(Filters) --\u003e C(QueryAdapter)\n```\n\nYou have to pick a request parser and a query adapter.\n\n```ts\nconst parser = new CrudRequestParser();\nconst adapter = new TypeOrmQueryAdapter();\nconst userRepository = AppDataSource.getRepository(UserEntity); // TypeORM repository\n\n// ...\n\n// The request query object\n// This object will likely come from the HTTP request\nconst requestQuery = { ... };\n\n// Parses the query into a CrudRequest object\nlet crudRequest = parser.parse(requestQuery);\n\n// Apply filters\n// crudRequest = filterRelations(crudRequest, ['posts']);\n// crudRequest = ensureLimit(crudRequest, 25, 100);\n\n// Using the query adapter, you can run the query through your ORM by using the CrudRequest\nconst result = await adapter.getMany(userRepository.createQueryBuilder(), crudRequest); // GetManyResult\u003cUserEntity\u003e\n\n// The result object has properties like data, page, total\nconsole.log(result);\n```\n\n## Request parsers\n\n### CRUD Request\n\nThe CRUD Request parser is an implementation of the `@nestjsx/crud` [query params format](https://github.com/nestjsx/crud/wiki/Requests#query-params).\n\n```ts\nimport { CrudRequestParser } from 'crud-query-parser/parsers/crud';\n\nconst parser = new CrudRequestParser();\n\n// Then, you have to pass a query string object to it\n// const crudRequest = parser.parse(request.query);\n```\n\nRead more about the [CRUD Request parser](./docs/parsers/crud.md).\n\n## Database adapters\n\n### TypeORM\n\nThis adapter works with TypeORM 0.3.x and 0.2.x\n\n```ts\nimport { TypeOrmQueryAdapter } from 'crud-query-parser/adapters/typeorm';\n\nconst adapter = new TypeOrmQueryAdapter();\n\n// Then, you can pass a query builder to it:\n// const result = await adapter.getMany(repository.createQueryBuilder(), crudRequest);\n```\n\nRead more about the [TypeORM adapter](./docs/adapters/typeorm.md).\n\n### Sequelize\n\nThis adapter works with Sequelize 6\n\n```ts\nimport { SequelizeQueryAdapter } from 'crud-query-parser/adapters/sequelize';\n\nconst adapter = new SequelizeQueryAdapter();\n\n// Then, you can pass a FindOptions to it:\n// const result = await adapter.getMany({}, crudRequest);\n```\n\nRead more about the [Sequelize adapter](./docs/adapters/sequelize.md).\n\n### DynamoDB\n\nThis adapter requires [@aws-sdk/client-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb) and [@aws-sdk/util-dynamodb](https://www.npmjs.com/package/@aws-sdk/util-dynamodb) 3.x.x\n\n```ts\nimport { DynamoDBQueryAdapter } from 'crud-query-parser/adapters/dynamodb';\nimport { DynamoDBClient } from '@aws-sdk/client-dynamodb';\n\nconst adapter = new DynamoDBQueryAdapter({\n  client: new DynamoDBClient(),\n  tableName: 'posts',\n  partitionKey: 'id',\n});\n\n// Then, you can pass a partial Query/Scan input to it:\n// const result = await adapter.getMany({}, crudRequest);\n```\n\nRead more about the [DynamoDB adapter](./docs/adapters/dynamodb.md).\n\n### MongoDB\n\n```ts\nimport { MongoDBQueryAdapter } from 'crud-query-parser/adapters/mongodb';\n\nconst adapter = new MongoDBQueryAdapter();\n\n// Then, you can pass a collection to it:\n// const result = await adapter.getMany(collection, crudRequest);\n```\n\nRead more about the [MongoDB adapter](./docs/adapters/mongodb.md).\n\n### Mongoose\n\n```ts\nimport { MongooseQueryAdapter } from 'crud-query-parser/adapters/mongodb';\n\nconst adapter = new MongooseQueryAdapter();\n\n// Then, you can pass a Query to it:\n// const result = await adapter.getMany(Model.find(), crudRequest);\n```\n\nRead more about the [Mongoose adapter](./docs/adapters/mongodb.md).\n\n### Array\n\nThis adapter can filter, sort and map plain JS arrays.\n\n```ts\nimport { ArrayQueryAdapter } from 'crud-query-parser/adapters/array';\n\nconst adapter = new ArrayQueryAdapter();\n\n// Then, you can pass an array of entities to it:\n// const result = await adapter.getMany([], crudRequest);\n```\n\nRead more about the [array adapter](./docs/adapters/array.md).\n\n## Frameworks\n\ncrud-query-parser is framework-agnostic. You can pass any query parameters object to the parser and it should work out-of-the-box.\nWe have a few examples for the frameworks listed below:\n\n- [NestJS](./docs/frameworks/nestjs.md)\n- [NextJS](./docs/frameworks/nextjs.md)\n- [Express](./docs/frameworks/express.md)\n- [Fastify](./docs/frameworks/fastify.md)\n- [h3](./docs/frameworks/h3.md)\n- [tinyhttp](./docs/frameworks/tinyhttp.md)\n- [Node.js http](./docs/frameworks/nodejs-http.md)\n\nWe also have special integrations to improve DX: \n\n### NestJS Integration\n\nThe NestJS Integration has decorators that automatically parses the request. It also has built-in OpenAPI support.\n\n```ts\nimport { Crud, ParseCrudRequest } from 'crud-query-parser/helpers/nestjs';\nimport { CrudRequestParser } from 'crud-query-parser/parsers/crud';\n\n@Controller('users')\nexport class UserController {\n\n  @Get()\n  @Crud(CrudRequestParser) // \u003c- You specify which parser to use\n  public async getMany(@ParseCrudRequest() crudRequest: CrudRequest) { // \u003c- The request query will be automatically parsed\n    // ...\n  }\n\n}\n```\n\nRead more about the [NestJS Integration](docs/frameworks/nestjs.md).\n\n### Express Integration\n\nThe Express Integration has a middleware that automatically parses and memoizes the request.\n\n```ts\nimport { crud } from 'crud-query-parser/helpers/express';\nimport { CrudRequestParser } from 'crud-query-parser/parsers/crud';\n\napp.use(crud(CrudRequestParser)); // \u003c- You specify which parser to use\n\napp.get('/users', (req, res) =\u003e {\n  const crudRequest = req.getCrudRequest(); // \u003c- The request will be automatically parsed and memoized\n\n  // ...\n});\n```\n\nRead more about the [Express Integration](docs/frameworks/express.md).\n\n## Filters\n\nYou may need to filter what the user can or cannot query. You are free to modify the `CrudRequest` object however you like.\n\nThere are a few filters provided by the library, which are listed below.\n\n### Enforce a \"where\" condition\n\nThis filter will add the condition on top of all other where conditions\n\n```ts\nimport { ensureCondition, ensureEqCondition } from 'crud-query-parser/filters';\n\n// ...\n\ncrudRequest = ensureCondition(crudRequest, {\n  field: ['isActive'],\n  operator: CrudRequestWhereOperator.EQ,\n  value: true,\n});\n\n// Alternatively, a shorthand for equals conditions:\ncrudRequest = ensureEqCondition(crudRequest, {\n  isActive: true,\n});\n```\n\n### Ensure page limit\n\nThis filter will ensure that the requested limit does not go above the maximum.\nIt also sets a default value whenever the limit is omitted. \n\n```ts\nimport { ensureLimit } from 'crud-query-parser/filters';\n\n// ...\n\nconst defaultLimit = 25;\nconst maxLimit = 100;\n\ncrudRequest = ensureLimit(crudRequest, defaultLimit, maxLimit);\n```\n\n### Filter property access\n\nThis filter removes any property from the request that is not in the allowlist.\nIt removes unallowed properties from the select fields, where conditions, relations and sorting.\n\n```ts\nimport { filterProperties } from 'crud-query-parser/filters';\n\n// ...\n\ncrudRequest = filterProperties(crudRequest, [\n  'id',\n  'name',\n  'posts',\n  'posts.id',\n  'posts.name',\n]);\n```\n\n### Filter relations\n\nThis filter removes any relation from the request that is not in the allowlist.\nIt's the same as the `filterProperties` but only filters relations.\n\n```ts\nimport { filterRelations } from 'crud-query-parser/filters';\n\n// ...\n\ncrudRequest = filterRelations(crudRequest, ['posts']);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguichaguri%2Fcrud-query-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguichaguri%2Fcrud-query-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguichaguri%2Fcrud-query-parser/lists"}