diff --git a/README.md b/README.md index 211087d..fcd7d46 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,37 @@ # mongodb-query-validator - - -> ✅ Zero Dependency MongoDB Query Operator Validator, why bother the database when you can save network rount-trip and CPU cycles? +> ✅ Zero Dependency MongoDB Query Operator Validator. Why bother the database when you can save network round trips and CPU cycles? ## Table of Contents - - [About](#about) * [Benefits](#benefits) * [Use Cases](#use-cases) - [Installation](#installation) - [Usage](#usage) -- [Valid query Operators](#valid-query-operators) +- [API](#api) +- [Valid query operators](#valid-query-operators) - [Contributing](#contributing) +- [Development](#development) - [License](#license) - [Contact](#contact) - ## About -Do you ever find yourself squinting at your MongoDB queries, only to realize you've made a tiny typo that's causing a big headache? We've been there too. That's why we built this nifty little tool – to save you from those pesky errors and wasted database trips. +Do you ever find yourself squinting at your MongoDB queries, only to realize you've made a tiny typo that's causing a big headache? We've been there too. That's why this library exists: to catch those mistakes before they hit the database. ### Benefits -- **Error-Free Queries**: Say goodbye to query typos and syntax errors. Our validator catches them before they cause any trouble. -- **Efficiency Boost**: Streamline your development process by validating queries upfront, saving you time and resources. +- **Error-Free Queries** – Say goodbye to query typos and syntax errors. The validator catches them before they cause trouble. +- **Efficiency Boost** – Streamline your development process by validating queries upfront, saving you time and resources. ### Use Cases -- **Production Systems**: Enhance the robustness of production systems by validating queries before executing them in live environments, minimizing downtime and errors. -- **Development Environments**: Validate queries during development to catch errors early and streamline the debugging process. -- **Testing Processes**: Integrate query validation into testing pipelines to ensure query correctness and reliability. - - +- **Production Systems** – Validate queries before executing them in live environments to minimize downtime and errors. +- **Development Environments** – Catch mistakes early while you're building features. +- **Testing Processes** – Integrate query validation into your testing pipelines to ensure correctness and reliability. ## Installation @@ -45,47 +41,60 @@ npm i --save mongodb-query-validator yarn add mongodb-query-validator ``` - - ## Usage ```ts -import { validateQuery } from './src/index'; +import { validateQuery } from 'mongodb-query-validator'; const { isValidQuery } = validateQuery({ myField: { nested: { $gte: 123 } } }); // isValidQuery = true -const { isValidQuery, invalidFields } = validateQuery({ +const { isValidQuery: valid, invalidFields } = validateQuery({ myField: { nested: { $exist: true } }, }); -// isValidQuery = false -// invalidFields = ["myField.nexted.$exist"] +// valid = false +// invalidFields = ["myField.nested.$exist"] ``` -## Valid query Operators +## API + +`validateQuery(query[, maxDepth])` -You can find all supported query operator [here](./src/allowed.ts) +- **query** – An object representing your MongoDB query. +- **maxDepth** *(optional)* – Limit how deep the validator should traverse nested objects. `0` (default) means unlimited depth. + +Returns an object with: + +- `isValidQuery` – `true` if no invalid operators are found. +- `invalidFields` – an array of paths to the invalid fields. + +Type definitions are available in [`types/index.d.ts`](./types/index.d.ts). + +## Valid query operators + +The full list of supported operators can be found in [`src/allowed.ts`](./src/allowed.ts). ## Contributing -Project is pretty simple and straight forward for what is my needs, but if you have any idea you're welcome. +Contributions are welcome! Please use [Conventional Commits](https://www.conventionalcommits.org/) when crafting your commit messages. -This projects uses [commitlint](https://commitlint.js.org/) with Angular configuration so be sure to use standard commit format or PR won't be accepted. +1. Fork the repository and create your branch (`git checkout -b feat/my-feature`). +2. Install dependencies with `npm i`. +3. Add your changes and tests. +4. Run the test suite with `npm test`. +5. Commit using the `feat`, `fix`, or other conventional prefixes. +6. Push your branch and open a pull request. -1. Fork the Project -2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -3. Commit your Changes (`git commit -m 'feat(scope): some AmazingFeature'`) -4. Push to the Branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +## Development - +- **Build** – `npm run build` compiles TypeScript to `dist/`. +- **Tests** – `npm test` runs the tap test suite. Use this before submitting PRs. +- **Coverage** – `npm run coverage` generates an HTML coverage report. ## License -Distributed under the MIT License. See `LICENSE` for more information. - - +Distributed under the MIT License. See [`LICENSE`](LICENSE.md) for more information. ## Contact -Simone Corsi - [@im_simonecorsi](https://twitter.com/im_simonecorsi) +Simone Corsi – [@im_simonecorsi](https://twitter.com/im_simonecorsi)