{"_id":"@alt-point/spleen-postgresql","name":"@alt-point/spleen-postgresql","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@alt-point/spleen-postgresql","longName":"spleen-postgresql","description":"Convert spleen filters into Postgresql statements.","version":"1.1.0","dependencies":{"elv":"^1.0.0","spleen":"^1.2.0"},"devDependencies":{"chai":"~3.5.0","eslint":"^3.13.1","eslint-config-airbnb":"^14.0.0","eslint-plugin-import":"^2.2.0","eslint-plugin-jsx-a11y":"^3.0.2","eslint-plugin-react":"^6.9.0","mocha":"^3.2.0","nyc":"^10.2.0"},"keywords":["conditional","filter","graph","dynamic","if","where","search","api","input","param","postgresql","couchbase"],"license":"MIT","main":"./lib","peerDependencies":{"spleen":">=1.1.0"},"private":false,"scripts":{"lint":"eslint ./*","test":"NODE_ENV=test nyc --reporter=lcov  --reporter=text mocha --recursive ./test"},"publishConfig":{"access":"public"},"_id":"@alt-point/spleen-postgresql@1.1.0","gitHead":"d33e739eb316b74c86c7d54b8a62a78e94f48179","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-lAg+5xtVwYHPZm5T6i1cY4XZz0HIkHoA6H7KfdPcTFPtCQo+PgJ3E68WoISJq3jAMWS9QbiufgEtUsAiADMJvg==","shasum":"7e45beee183277b4916d7f8416ae6345b851f5f6","tarball":"https://registry.npmjs.org/@alt-point/spleen-postgresql/-/spleen-postgresql-1.1.0.tgz","fileCount":6,"unpackedSize":16883,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIEIQgH8jTpi/b8hyTADPURNMB1rB1CWDWSR7Di+Z5ELyAiAQB2q5yIfHIYyttABfzmSb/Cn2l3HvAOkWRX859jVs5g=="}]},"_npmUser":{"name":"evil_dwarf","email":"froncast@alt-point.ru"},"directories":{},"maintainers":[{"name":"evil_dwarf","email":"froncast@alt-point.ru"},{"name":"vladismus","email":"i@vlad.guru"},{"name":"surrealistik","email":"surrealistik74@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/spleen-postgresql_1.1.0_1705033490195_0.9660789026122789"},"_hasShrinkwrap":false}},"time":{"created":"2024-01-12T04:24:50.102Z","1.1.0":"2024-01-12T04:24:50.355Z","modified":"2024-01-12T04:24:50.662Z"},"maintainers":[{"name":"evil_dwarf","email":"froncast@alt-point.ru"},{"name":"vladismus","email":"i@vlad.guru"},{"name":"surrealistik","email":"surrealistik74@gmail.com"}],"description":"Convert spleen filters into Postgresql statements.","keywords":["conditional","filter","graph","dynamic","if","where","search","api","input","param","postgresql","couchbase"],"license":"MIT","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","readmeFilename":"README.md"}