{"id":15917619,"url":"https://github.com/dsfields/spleen-mongodb-node","last_synced_at":"2025-04-03T11:42:03.388Z","repository":{"id":57367591,"uuid":"120686739","full_name":"dsfields/spleen-mongodb-node","owner":"dsfields","description":"Convert spleen filters into MongoDB Query Documents.","archived":false,"fork":false,"pushed_at":"2018-03-12T00:31:18.000Z","size":60,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T18:15:35.151Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/dsfields.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-07T23:50:41.000Z","updated_at":"2018-03-12T00:34:12.000Z","dependencies_parsed_at":"2022-08-23T19:30:45.504Z","dependency_job_id":null,"html_url":"https://github.com/dsfields/spleen-mongodb-node","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-mongodb-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-mongodb-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-mongodb-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-mongodb-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dsfields","download_url":"https://codeload.github.com/dsfields/spleen-mongodb-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246998104,"owners_count":20866690,"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":[],"created_at":"2024-10-06T18:11:55.088Z","updated_at":"2025-04-03T11:42:03.368Z","avatar_url":"https://github.com/dsfields.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spleen-mongodb\n\nThe [`spleen`](https://www.npmjs.com/package/spleen) module provides high-level abstractions for dynamic filters.  This module will convert a `spleen` [`Filter`](https://www.npmjs.com/package/spleen#class-filter) into a [MongoDB Query Filter Document](https://docs.mongodb.com/manual/core/document/#document-query-filter) object.\n\n__Contents__\n* [Usage](#usage)\n* [API](#api)\n* [Security](#security)\n\n## Usage\n\nAdd `spleen-mongodb` to your `package.json` file's `dependencies`:\n\n```sh\n$ npm install spleen-mongodb -S\n```\n\nThen use it in your code:\n\n```js\nconst spleen = require('spleen');\nconst splongo = require('spleen-mongodb');\n\nconst filter = spleen.parse('/foo/bar eq 42 and /baz in [1,2,3] or /qux gt 0');\nconst result = splongo.convert(filter);\n\nconsole.log(result.value);\n// {\n//   \"$or\": [\n//     {\n//       \"$and\": [\n//         { \"foo.bar\": 42 },\n//         { \"baz\": { \"$in\": [1, 2, 3,] } }\n//       ]\n//     },\n//     { \"qux\": { \"$gt\": 0 } }\n//   ]\n// }\n```\n\n## API\n\nThe `spleen-mongodb` module provides the following interface.\n\n### `splongo.convert(filter [, strategy])`\n\nConverts an instance of [`spleen`](https://www.npmjs.com/package/spleen)'s [`Filter`](https://www.npmjs.com/package/spleen#class-filter) class into an MongoDB Query Filter Document object.\n\n__Parameters__\n\n* `filter`: _(required)_ the instance of `Filter` to convert.\n\n* `strategy`: _(optional)_ an instance of [`Strategy`](#splongostrategy).\n\n__Returns__\n\nAn object with the following keys:\n\n* `fields`: an array of [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901) values, representing the fields referenced by the converted `Fitler`.\n\n* `value`: the MongoDB Query Filter Document.\n\n----------\n\n### `splongo.errors.ConvertError`\n\nA general error thrown when `spleen-mongodb` is unable to convert a given [`Filter`](https://www.npmjs.com/package/spleen#class-filter) instance into a Query Filter Document object.  This should generally never happen, and is here as a safeguard in the event a `Filter` instance is corrupted.\n\n----------\n\n### `splongo.errors.DeniedFieldError`\n\nAn error thrown when a field is encountered that has been explicitly black-listed by the `deny` option.\n\n----------\n\n### `splongo.errors.InvalidTargetError`\n\nAn error thrown if a target is encountered with an invalid format.  For example, if a segment of the path contains reserved characters.\n\n----------\n\n### `splongo.errors.UnallowedFieldError`\n\nAn error thrown when a field is encountered that has not been white-listed by the `allow` option.\n\n----------\n\n### `splongo.errors.RequiredFieldError`\n\nAn error thrown when a [`Filter`](https://www.npmjs.com/package/spleen#class-filter) instance is passed to [`convert()`](#splongoconvertfilter-strategy) missing a required field.\n\n----------\n\n### `splongo.Strategy`\n\nA class that represents a conversion strategy.  Instances are meant to be cached in memory to prevent having to recompute this information with every call to [`convert()`](#splongoconvertfilter-strategy).\n\n#### `Strategy.prototype.constructor([options])`\n\nCreate a new instance of `Strategy`.\n\n* `options`: _(optional)_ an object that provides conversion options. This object can have the keys:\n\n  + `allow`: _(optional)_ an array of [RFC 6901 JSON pointer](https://tools.ietf.org/html/rfc6901) strings that are allowed to be in a `Filter`'s list of targets.  Any targets in a [`Filter`](https://www.npmjs.com/package/spleen#class-filter) instance not found in the `allow` or `require` lists will result in an error being thrown.  This list functions as a white list, and can only be present if `deny` is absent.  An empty array is the logical equivalent of the `allow` key being absent.\n\n  + `deny`: _(optional)_ an array of RFC 6901 JSON pointer strings that are not allowed to be in a `Filter`'s list of targets.  Any targets in a `Filter` instance found in this list will result in an error being thrown.  This list functions as a black list, and can only be present if `allow` is absent.\n\n  + `require`: _(optional)_  object that specifies required field target behavior. This object can have the following keys:\n\n    - `fields`: _(optional)_ an array of RFC 6901 JSON pointer strings that are required to be in a `Filter`'s list of targets (`Filter.prototype.targets`).  If a required target is missing, an error is thrown.  If this key is omitted or empty, there are assumed to be no required fields.\n\n    - `which`: _(optional)_ a string specifying which fields are required to be in a given `Filter`. This can be either `any` or `all`. If omitted, this value defaults to `any`.\n\n## Security\n\nThe combination of `spleen` and `spleen-mongodb` add a number of layers of protection to prevent [NoSQL-injection attacks](https://www.owasp.org/index.php/Testing_for_NoSQL_injection) vulnerabilities.  Either `spleen` will refuse to parse a given filter, or `spleen-mongodb` will throw an error if reserved MongoDB tokens are encountered.\n\nThat said, there are a couple of other things to consider:\n\n1. It is advised that implementers make use of the [`Strategy`](#splongostrategy) class' `allow`/`deny` and `require` functionality.  The idea is to prevent a DoS attack vector by ensuring expensive queries against un-indexed fields cannot be executed.\n\n2. The `spleen` and `spleen-mongodb` libraries do not, and cannot, ensure queries are not executed against data to which a user lacks sufficient permission.  When required, implementers should append static authorization checks to all queries taken as input.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fspleen-mongodb-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsfields%2Fspleen-mongodb-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fspleen-mongodb-node/lists"}