{"id":15917590,"url":"https://github.com/dsfields/spleen-n1ql-node","last_synced_at":"2025-04-03T11:42:01.586Z","repository":{"id":57367573,"uuid":"85082460","full_name":"dsfields/spleen-n1ql-node","owner":"dsfields","description":"Convert spleen filters into N1QL WHERE clauses.","archived":false,"fork":false,"pushed_at":"2017-07-18T03:46:18.000Z","size":19,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T18:15:35.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-15T14:30:49.000Z","updated_at":"2017-07-17T16:35:44.000Z","dependencies_parsed_at":"2022-08-23T20:10:50.965Z","dependency_job_id":null,"html_url":"https://github.com/dsfields/spleen-n1ql-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-n1ql-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-n1ql-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-n1ql-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fspleen-n1ql-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dsfields","download_url":"https://codeload.github.com/dsfields/spleen-n1ql-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246998102,"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:45.385Z","updated_at":"2025-04-03T11:42:01.566Z","avatar_url":"https://github.com/dsfields.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spleen-n1ql\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 string that is usable within a N1QL statement's `WHERE` clause.\n\n__Contents__\n* [Usage](#usage)\n* [API](#api)\n* [Security Considerations](#security-considerations)\n* [Stringify Behavior](#stringify-behavior)\n\n## Usage\n\nAdd `spleen-n1ql` to your `package.json` file's `dependencies`:\n\n```sh\n$ npm install spleen-n1ql -S\n```\n\nThen use it in your code:\n\n```js\nconst N1ql = require('spleen-n1ql');\nconst spleen = require('spleen');\n\nconst filter = spleen.parse('/foo/bar eq 42 and /baz in [1,2,3]');\nconst n1qlWhere = N1ql.stringify(filter, { parameterize: true });\n\nconsole.log(n1qlWhere); // `foo`.`bar` == $1 AND `baz` IN [$2,$3,$4]\n```\n\n## API\n\nThe `spleen-n1ql` module has a single class.\n\n### Class: `N1ql`\n\nProvides services for converting `spleen` filters into N1QL.\n\n  * __Properties__\n\n    + `errors`: an object that contains references to the various possible errors thrown by `spleen-n1ql`.  This object has the following keys:\n\n      - `DeniedFieldError`: thrown when a field is encountered that has been explicitly black-listed by the `deny` option.\n\n      - `InvalidTargetError`: thrown if a target is encountered with an invalid format.  For example, if a segment of the path contains disallowed characters.\n\n      - `NonallowedFieldError`: thrown when a field is encountered that not been white-listed by the `allow` option.\n\n      - `RequiredFieldError`: thrown when a field that has been required by the `require` option is not present in the given `Filter`.\n\n      - `StringifyError`: a general error thrown when `sleen-n1ql` is unable to convert a given `Filter` instance into a N1QL statement.  This should generally never happen, and is here as a safeguard in the event a `Filter` instance is corrupted.\n\n  * __Methods__\n\n    + `N1ql.stringify(filter [, options])`: converts an instance of `spleen`'s `Filter`' class into a N1QL statement.\n\n      _Parameters_\n\n      - `filter`: _(required)_ the instance of `Filter` to stringify.\n\n      - `options`: _(optional)_ an object that controls various aspects of the stringification process.  This object can have the keys:\n\n        - `allow`: 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` 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`: 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        - `identifier`: a string to use as a contextual identifier with each field reference.\n\n        - `parameterize`: a Boolean value indicating whether or not literals in the `spleen` expression should be parameterized.  When `true` (the default), all string, number, and Boolean literals are set as numeric parameters.\n\n        - `require`: 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.\n\n      This method returns an object with the following keys:\n\n      - `params`: an array of values, where the index of each entry corresponds to its `$#` placeholder in the filter statement.\n\n      - `value`: a string containing the N1QL filter statement.\n\n## Security Considerations\n\nIt is highly recommended that you leave the `parameterize` option as `true` to help prevent SQL-injection attacks.\n\nAdditionally, as `spleen-n1ql` converts `Target` field references into dot-notation field references, it will throw an `InvalidTargetError` if any part of the path contains a single quote or backtick character as counter measure to SQL-injection attacks.\n\nTo provide an additional layer of security it is recommended that you utilize the `allow` option to white-list possible fields passed in from user input.\n\nIt is also highly recommend that you give leverge `spleen`'s `Filter.prototype.prioritize()` method before converting to a N1QL expression.  This allows you to reorder a `Filter`, and optimally utilize known indexes.\n\n## Stringify Behavior\n\nThere are situations where a `spleen` filter does not neatly translate into a N1QL expression.  This is particularly true in the case of `spleen`'s `nil` operator.  For example, performing a greater-than on `nil` is technically valid with a `spleen` filter, but does not make much sense when translated to N1QL.  The `N1ql.stringify()` method will make attempts to reconcile this:\n\n* The operators `eq`, `lt`, `lte` when used with `nil` will result in an `IS NULL` N1QL expression.\n\n* The operators `neq`, `gt`, `gte` when used with `nil` will result in an `IS NOT NULL` N1QL expression.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fspleen-n1ql-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsfields%2Fspleen-n1ql-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fspleen-n1ql-node/lists"}