{"_id":"@drftgyhuji7npm/fuga-molestiae-illo","name":"@drftgyhuji7npm/fuga-molestiae-illo","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@drftgyhuji7npm/fuga-molestiae-illo","version":"1.0.0","description":"[![CircleCI](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master.svg?style=svg)](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master) [![Coverage Status](https://coveralls.io/repos/github","main":"index.js","author":{"name":"drftgyhuji7"},"license":"MIT","dependencies":{"@drftgyhuji7npm/adipisci-ad-reiciendis-temporibus":"^1.0.0","@drftgyhuji7npm/aliquid-mollitia-est-illo":"^1.0.0","@drftgyhuji7npm/animi-a-ab-earum":"^1.0.0","@drftgyhuji7npm/aut-dolores-numquam-dolorem":"^1.0.0","@drftgyhuji7npm/corporis-facere-ut-suscipit":"^1.0.0","@drftgyhuji7npm/debitis-error-dolores-sit":"^1.0.0","@drftgyhuji7npm/ea-numquam-maiores-voluptas":"^1.0.0","@drftgyhuji7npm/earum-adipisci-error-est":"^1.0.0","@drftgyhuji7npm/esse-eveniet-nobis-dolores":"^1.0.0","@drftgyhuji7npm/impedit-omnis-molestiae-dolores":"^1.0.0","@drftgyhuji7npm/iure-possimus-nihil-tempore":"^1.0.0","@drftgyhuji7npm/laboriosam-molestias-quo-quia":"^1.0.0","@drftgyhuji7npm/magni-eaque-quo-tempore":"^1.0.0","@drftgyhuji7npm/natus-praesentium-nisi-praesentium":"^1.0.0","@drftgyhuji7npm/necessitatibus-necessitatibus-nulla-ducimus":"^1.0.0","@drftgyhuji7npm/nisi-unde-debitis-porro":"^1.0.0","@drftgyhuji7npm/perspiciatis-quis-ducimus-maiores":"^1.0.0","@drftgyhuji7npm/quasi-reprehenderit-dolore-deserunt":"^1.0.0","@drftgyhuji7npm/rem-sint-necessitatibus-possimus":"^1.0.0","@drftgyhuji7npm/repellendus-eum-et-itaque":"^1.0.0","@drftgyhuji7npm/temporibus-omnis-modi-ipsa":"^1.0.0","@drftgyhuji7npm/vitae-rerum-dignissimos-eos":"^1.0.0","@drftgyhuji7npm/voluptas-temporibus-cupiditate-cum":"^1.0.0","@drftgyhuji7npm/voluptatibus-numquam-neque-veritatis":"^1.0.0","@drftgyhuji7npm/voluptatum-molestiae-aliquid-ullam":"^1.0.0"},"keywords":["fantasy-land","names","fastclone","filter","exit-code","ES2019","browserslist","argument","jest","toStringTag","lesscss","generics","framework","serialization","take","variables in css","chrome","operating-system","writable","transpile","ECMAScript 3","Array.prototype.includes","package","lockfile","syntaxerror","watch","bdd","deep","callbind","every","style","ts","ES2021","limited","group","iterator","validator","immer","parse","wordwrap","xdg","uninstall","typescript","fetch","Object.values","optimizer","util","negative","rate","path","authentication","Symbol.toStringTag","directory","StyleSheet","make dir","array","installer","jasmine","weakmap",".env","weakset","assertion","diff","matchAll","toArray","match","JSON","set","[[Prototype]]","querystring","pure","forms","functions","ECMAScript 2017","ES2016","https","ES2022","CSSStyleDeclaration","performant","enumerable","ponyfill","user-streams","plugin","let","text","censor","higher-order","valid","intrinsic","launch","Object.defineProperty","regexp","popmotion","less","positive","-0","assign","fixed-width","internal","fast-clone","symlinks","number","CSS","eslint","a11y","busy","spring","babel","three","env","obj","fullwidth","module","WeakMap","Set","buffers","watching","drop","immutable","width","exec","tape","protocol-buffers","byte","less css","performance","mime-db","accessibility","trimEnd","Push","ES7","task","utilities","forEach","Rx","macos","arktype","accessor","warning","random","commander","styled-components","ansi","less compiler","key","es6","es-shims","zod","config","shared","guid"],"repository":{"type":"git","url":"git+https://github.com/drftgyhuji7npm/fuga-molestiae-illo.git"},"homepage":"https://github.com/drftgyhuji7npm/fuga-molestiae-illo/#readme","bugs":{"url":"https://github.com/drftgyhuji7npm/fuga-molestiae-illo/issues"},"packageManager":"yarn@4.1.1","_id":"@drftgyhuji7npm/fuga-molestiae-illo@1.0.0","gitHead":"53c8b5c0f84c177d83cb2b38a4df79cd61b45385","_nodeVersion":"20.12.2","_npmVersion":"10.5.0","dist":{"integrity":"sha512-LiDERaTiyHj0sy3M3mpR0gBM4wlFIc5ZOlGiH+6cmeM0uesqeNWn8FxgB0H+BCyKiZXa1I1ZVfnpEcwwpN8zNA==","shasum":"dcca9102f94e1fe69c405511c02e49278826c090","tarball":"https://registry.npmjs.org/@drftgyhuji7npm/fuga-molestiae-illo/-/fuga-molestiae-illo-1.0.0.tgz","fileCount":10,"unpackedSize":16457,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIB0+iifA4iHBDZ7qDG1fix7E4hAMXOmqgZPFkJ+z9lkHAiEAx7CSrN7Lwfa3D57+nwzicpxCHwhWK9bdZXP1kBQMD4Q="}]},"_npmUser":{"name":"thidong8461","email":"thidong8461@gmail.com"},"directories":{},"maintainers":[{"name":"thidong8461","email":"thidong8461@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/fuga-molestiae-illo_1.0.0_1714037841091_0.3333944536986049"},"_hasShrinkwrap":false}},"time":{"created":"2024-04-25T09:37:20.990Z","1.0.0":"2024-04-25T09:37:21.264Z","modified":"2024-04-25T09:37:21.544Z"},"maintainers":[{"name":"thidong8461","email":"thidong8461@gmail.com"}],"description":"[![CircleCI](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master.svg?style=svg)](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master) [![Coverage Status](https://coveralls.io/repos/github","homepage":"https://github.com/drftgyhuji7npm/fuga-molestiae-illo/#readme","keywords":["fantasy-land","names","fastclone","filter","exit-code","ES2019","browserslist","argument","jest","toStringTag","lesscss","generics","framework","serialization","take","variables in css","chrome","operating-system","writable","transpile","ECMAScript 3","Array.prototype.includes","package","lockfile","syntaxerror","watch","bdd","deep","callbind","every","style","ts","ES2021","limited","group","iterator","validator","immer","parse","wordwrap","xdg","uninstall","typescript","fetch","Object.values","optimizer","util","negative","rate","path","authentication","Symbol.toStringTag","directory","StyleSheet","make dir","array","installer","jasmine","weakmap",".env","weakset","assertion","diff","matchAll","toArray","match","JSON","set","[[Prototype]]","querystring","pure","forms","functions","ECMAScript 2017","ES2016","https","ES2022","CSSStyleDeclaration","performant","enumerable","ponyfill","user-streams","plugin","let","text","censor","higher-order","valid","intrinsic","launch","Object.defineProperty","regexp","popmotion","less","positive","-0","assign","fixed-width","internal","fast-clone","symlinks","number","CSS","eslint","a11y","busy","spring","babel","three","env","obj","fullwidth","module","WeakMap","Set","buffers","watching","drop","immutable","width","exec","tape","protocol-buffers","byte","less css","performance","mime-db","accessibility","trimEnd","Push","ES7","task","utilities","forEach","Rx","macos","arktype","accessor","warning","random","commander","styled-components","ansi","less compiler","key","es6","es-shims","zod","config","shared","guid"],"repository":{"type":"git","url":"git+https://github.com/drftgyhuji7npm/fuga-molestiae-illo.git"},"author":{"name":"drftgyhuji7"},"bugs":{"url":"https://github.com/drftgyhuji7npm/fuga-molestiae-illo/issues"},"license":"MIT","readme":"[![CircleCI](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master.svg?style=svg)](https://circleci.com/gh/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/tree/master) [![Coverage Status](https://coveralls.io/repos/github/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo/badge.svg?branch=master)](https://coveralls.io/github/tandg-digital/@drftgyhuji7npm/fuga-molestiae-illo?branch=master)\n\n# What is @drftgyhuji7npm/fuga-molestiae-illo?\n@drftgyhuji7npm/fuga-molestiae-illo is a plugin for the [objection.js](https://github.com/Vincit/objection.js) ORM. It's designed to allow powerful filters and aggregations on your API.\n\nSome examples of what you can do include:\n\n#### 1. Filtering on nested relations\nFor example, if you have the models _Customer_ belongsTo _City_ belongsTo _Country_, we can query all _Customers_ where the _Country_ starts with `A`.\n\n#### 2. Eagerly loading data\nEagerly load a bunch of related data in a single query. This is useful for getting a list models e.g. _Customers_ then including all their _Orders_ in the same query.\n\n#### 3. Aggregation and reporting\nCreating quick counts and sums on a model can speed up development significantly. An example could be the _numberOfOrders_ for a _Customer_ model.\n\n# Shortcuts\n\n* [Changelog](doc/CHANGELOG.md)\n* [Recipes](doc/RECIPES.md)\n* [Aggregation](doc/AGGREGATIONS.md)\n\n# Installation\n\n`npm i @drftgyhuji7npm/fuga-molestiae-illo --save`\n\n> @drftgyhuji7npm/fuga-molestiae-illo >= 1.0.0 is fully backwards compatible with older queries, but now supports nested [and/or filtering](#logical-expressions) as well as the new objection.js object notation. The 1.0.0 denotation was used due to these changes and the range of query combinations possible. In later major versions of @drftgyhuji7npm/fuga-molestiae-illo, the top level \"where\" and \"require\" filters will be deprecated.\n\n# Usage\n\nThe filtering library can be applied onto every _findAll_ REST endpoint e.g. `GET /api/{Model}?filter={\"limit\": 1}`\n\nA typical express route handler with a filter applied:\n```js\nconst { buildFilter } = require('@drftgyhuji7npm/fuga-molestiae-illo');\nconst { Customer } = require('./models');\n\napp.get('/Customers', function(req, res, next) {\n  buildFilter(Customer)\n    .build(JSON.parse(req.query.filter))\n    .then(customers => res.send(customers))\n    .catch(next);\n});\n```\n\nAvailable filter properties include:\n```js\n// GET /api/Customers\n{\n  // Filtering and eager loading\n  \"eager\": {\n    // Top level $where filters on the root model\n    \"$where\": {\n      \"firstName\": \"John\"\n      \"profile.isActivated\": true,\n      \"city.country\": { \"$like\": \"A\" }\n    },\n    // Nested $where filters on each related model\n    \"orders\": {\n      \"$where\": {\n        \"state.isComplete\": true\n      },\n      \"products\": {\n        \"$where\": {\n          \"category.name\": { \"$like\": \"A\" }\n        }\n      }\n    }\n  },\n  // An objection.js order by expression\n  \"order\": \"firstName desc\",\n  \"limit\": 10,\n  \"offset\": 10,\n  // An array of dot notation fields to select on the root model and eagerly loaded models\n  \"fields\": [\"firstName\", \"lastName\", \"orders.code\", \"products.name\"]\n}\n```\n\n> The `where` operator from < v1.0.0 is still available and can be combined with the `eager` string type notation. The same is applicable to the `require` operator. For filtering going forward, it's recommended to use the objection object-notation for eager loading along with `$where` definitions at each level.\n\n# Filter Operators\n\nThere are a number of built-in operations that can be applied to columns (custom ones can also be created). These include:\n\n1. **$like** - The SQL _LIKE_ operator, can be used with expressions such as _ab%_ to search for strings that start with _ab_\n2. **$gt/$lt/$gte/$lte** - Greater than and Less than operators for numerical fields\n3. **=/$equals** - Explicitly specify equality\n4. **$in** - Whether the target value is in an array of values\n5. **$exists** - Whether a property is not null\n6. **$or** - A top level _OR_ conditional operator\n\nFor any operators not available (eg _ILIKE_, refer to the custom operators section below).\n\n#### Example\n\nAn example of operator usage\n```json\n{\n  \"eager\": {\n    \"$where\": {\n      \"property0\": \"Exactly Equals\",\n      \"property1\": {\n        \"$equals\": 5\n      },\n      \"property2\": {\n        \"$gt\": 5\n      },\n      \"property3\": {\n        \"$lt\": 10,\n        \"$gt\": 5\n      },\n      \"property4\": {\n        \"$in\": [ 1, 2, 3 ]\n      },\n      \"property5\": {\n        \"$exists\": false\n      },\n      \"property6\": {\n        \"$or\": [\n          { \"$in\": [ 1, 2, 3 ] },\n          { \"$equals\": 100 }\n        ]\n      }\n    }\n  }\n}\n```\n\n#### Custom Operators\n\nIf the built in filter operators aren't quite enough, custom operators can be added. A common use case for this may be to add a `lower case LIKE` operator, which may vary in implementation depending on the SQL dialect.\n\nExample:\n\n```js\nconst options = {\n  operators: {\n    $ilike: (property, operand, builder) =>\n      builder.whereRaw('?? ILIKE ?', [property, operand])\n  }\n};\n\nbuildFilter(Person, null, options)\n  .build({\n    eager: {\n      $where: {\n        firstName: { $ilike: 'John' }\n      }\n    }\n  })\n```\n\nThe `$ilike` operator can now be used as a new operator and will use the custom operator callback specified.\n\n# Logical Expressions\nLogical expressions can be applied to both the `eager` and `require` helpers. The `where` top level operator will eventually be deprecated and replaced by the new `eager` [object notation](https://vincit.github.io/objection.js/#relationexpression-object-notation) in objection.js.\n\n#### Examples using `$where`\nThe `$where` expression is used to \"filter models\". Given this, related fields between models can be mixed anywhere in the logical expression.\n\n```json\n{\n  \"eager\": {\n    \"$where\": {\n      \"$or\": [\n        { \"city.country.name\": \"Australia\" },\n        { \"city.code\": \"09\" }\n      ]\n    }\n  }\n}\n```\n\nLogical expressions can also be nested\n```json\n{\n  \"eager\": {\n    \"$where\": {\n      \"$and\": {\n        \"name\": \"John\",\n        \"$or\": [\n          { \"city.country.name\": \"Australia\" },\n          { \"city.code\": { \"$like\": \"01\" }}\n        ]\n      }\n    }\n  }\n}\n```\n\nNote that in these examples, all logical expressions come _before_ the property name. However, logical expressions can also come _after_ the property name.\n\n```json\n{\n  \"eager\": {\n    \"$where\": {\n      \"$or\": [\n        { \"city.country.name\": \"Australia\" },\n        {\n          \"city.code\": {\n            \"$or\": [\n              { \"$equals\": \"12\" },\n              { \"$like\": \"13\" }\n            ]\n          }\n        }\n      ]\n    }\n  }\n}\n```\n\nThe `$where` will apply to the relation that immediately precedes it in the tree, in the above case \"city\". The `$where` will apply to relations of the eager model using dot notation. For example, you can query `Customers`, eager load their `orders` and filter those orders by the `product.name`. Note that `product.name` is a related field of the order model, not the customers model.\n\n# Aggregations\n\n[Aggregations](doc/AGGREGATIONS.md) such as _count, sum, min, max, avg_ can be applied to the queried model.\n\nAdditionally for any aggregations, you can use them in other expressions above including:\n\n* Filtering using `$where`\n* Ordering using `order`\n\nFor more detailed descriptions of each feature, refer to the [aggregations section](doc/AGGREGATIONS.md).\n\nTransform a basic aggregation like this on a `GET /Customers` endpoint:\n\n```js\n{\n  \"eager\": {\n    \"$aggregations\": [\n        {\n          \"type\": \"count\",\n          \"alias\": \"numberOfOrders\",\n          \"relation\": \"orders\"\n        }\n    ]\n  }\n}\n```\n\n...into a result set like this:\n\n```json\n[\n  {\n    \"firstName\": \"John\",\n    \"lastName\": \"Smith\",\n    \"numberOfOrders\": 10\n  },{\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Bright\",\n    \"numberOfOrders\": 5\n  },{\n    \"firstName\": \"Greg\",\n    \"lastName\": \"Parker\",\n    \"numberOfOrders\": 7\n  }\n]\n```","readmeFilename":"README.md"}