Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tricinel/cuddy
An aggregation pipeline built in a functional programming style that lets you search, group, order and transform a collection.
https://github.com/tricinel/cuddy
aggregation functional-programming javascript pipeline query-builder search typescript
Last synced: about 2 months ago
JSON representation
An aggregation pipeline built in a functional programming style that lets you search, group, order and transform a collection.
- Host: GitHub
- URL: https://github.com/tricinel/cuddy
- Owner: tricinel
- License: mit
- Created: 2020-12-17T12:05:39.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2021-12-27T16:46:37.000Z (almost 3 years ago)
- Last Synced: 2024-10-03T10:04:43.220Z (3 months ago)
- Topics: aggregation, functional-programming, javascript, pipeline, query-builder, search, typescript
- Language: TypeScript
- Homepage:
- Size: 723 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- Changelog: Changelog.md
- Contributing: Contributing.md
- License: License.md
Awesome Lists containing this project
README
cuddy
cuddy is an aggregation pipeline built in a functional programming style. If you ever wanted to search through a collection using logical operators, sort, group, transform and return only the fields you care about, then cuddy is for you.
The cuddy donkey logo designed by the talented Laura Dinulescu.
## Install
This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:
`npm install cuddy --save` or `yarn add cuddy`
### Usage
Import cuddy and create the query.
```js
import cuddy from 'cuddy';
import { copyFrom } from 'cuddy/transform/helpers';
const query = {
fields: ['title', 'permalink', 'runTime'],
match: {
in: { genre: 'Comedy', cast: 'Adam Sandler' },
eq: { lang: 'en' }
},
orderBy: {
reviews: 'asc'
},
groupBy: 'director',
transform: {
permalink: copyFrom('url')
},
limit: 2,
skip: 1
};
```
The above query translates into:
- I want all the items where the `genre` contains `Comedy` and `cast` contains `Adam Sandler` and the `lang` is `en`.
- I want only 2 results and I want to skip the first item in the list.
- I want to order the items by `reviews` in ascending order.
- I want to group the items by `director`.
- I want to create a new field called `permalink` and set its value to that of the `url` field.
- From all the fields of each item, I only want the `title`, `permalink` and `runTime`.
Next, build the pipeline and aggregate your data.
```js
const { aggregate } = cuddy(query, data);
const results = aggregate();
```
Depending on the shape of your data, the results could look like this:
```json
{
"Robert Smigel": [
{
"title": "The Week Of",
"permalink": "https://www.imdb.com/title/tt6821012",
"runTime": 116
}
]
}
```
> For more query examples, see the [Books test cases](./src/__tests__/books.test.ts) and the associated [Books collection](./src/__mocks__/books.ts).
>
> If it looks like mongodb's query language, it's because lots of inspirations came from there. :)
### Stages
The aggregation pipeline contains the following stages:
- [Matching](./docs/match.md). Filter out any items that do not match the criteria.
- [Sorting](./docs/sort.md). Sort the items in the specified order.
- [Pagination](./docs/pagination.md). Limit the number of results and/or skip over the first results.
- [Grouping](./docs/group.md). Group the items by a specified field.
- [Count](./docs/count.md). Count the items by a specified field.
- [Project](./docs/project.md). Limit the fields that are returned for each item.
- [Transform](./docs/transform.md). Transform existing properties and add new properties to the matched items.
### Pipeline functions
Once you've built your pipeline, you can use it to aggregate your data and return results. Depending on whether you want one result, all of them or just a count of the total results, you will need to call the appropriate method:
* `aggregate()` will return all the results from your query.
* `first()` will return the first result in the list of results from your query.
* `last()` will return the last result in the list of results from your query.
* `count()` will return the total number of results from your query.
* `explain()` will return an object explaining the set of steps resulted from your query. For details on the output, see the [Explanation](./docs/explain.md) section.
#### Why cuddy?
> _noun_
>
> cud·dy | \ ˈku̇-dē
>
> Synonyms: donkey (British slang)
The donkey is used as a working animal and is considered the cheapest form of labor.
#### Contributing
- Run tests with `npm run test` or `yarn test`.
- Run the lint with `npm run lint` or `yarn lint`.
For details, check out the [Contributing][./Contributing.md] guide.
##### LICENSE
MIT