Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joelwmale/cogent-js
A simple and elegant way to build urls for your REST API
https://github.com/joelwmale/cogent-js
api javascript laravel laravel-query-builder query rest
Last synced: 8 days ago
JSON representation
A simple and elegant way to build urls for your REST API
- Host: GitHub
- URL: https://github.com/joelwmale/cogent-js
- Owner: joelwmale
- License: mit
- Archived: true
- Created: 2019-04-29T22:13:37.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2023-01-09T17:02:09.000Z (almost 2 years ago)
- Last Synced: 2024-09-21T10:25:44.721Z (about 2 months ago)
- Topics: api, javascript, laravel, laravel-query-builder, query, rest
- Language: JavaScript
- Size: 821 KB
- Stars: 54
- Watchers: 1
- Forks: 13
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# CogentJS
## A beautiful and elegant way to build urls for your REST API
This package helps you to quickly build urls for a REST API, using fluent syntax.
🔥 If you use [Laravel](https://github.com/laravel/laravel) - the defaults of this package will work with [spatie/laravel-query-builder](https://github.com/spatie/laravel-query-builder).
# Basic usage
Make a url by calling the functions you need in a beautiful and elegant way:
```js
// Import
const { Query } = require("cogent-js");
// If custom configuration is required, see the Additional Configuration section
const query = new Query();
// /posts?filter[name]=Bob&include=posts,comments&orderBy=-created_at
const url = query
.for('posts') // the model you're selecting
.where('name', 'Bob') // where the models `name` is 'Bob'
.includes('posts', 'comments') // include the models related relationships: posts and comments
.orderBy('-created_at') // order by -created_at desc
.get(); // generate the url and pass it into fetch!
```
# Installation
## Npm
```js
npm i cogent-js
```
## Yarn
```js
yarn add cogent-js
```
# Additional Configuration
## Base Url
You can optionally set the `base_url` property when instantiating the class to automatically preprend the url to all urls:
```js
const { Query } = require('cogent-js');
const query = new Query({
base_url: 'http://api.example.com'
});
// http://api.example.com/users?filter[name]=Bob
const url = query.for('users').where('name', 'Bob').url(); // or .get();
```
# Available Methods
## where()
```js
// /users?filter[name]=Bob
const url = query.for('users').where('name', 'Bob').url(); // or .get();
```
## whereIn()
```js
// /users?filter[name]=bob,jerry
const url = query.for('users').whereIn('name', ['bob', 'jerry']).url(); // or .get();
```
## select()
```js
// /users?fields=name,age,date_of_birth
const url = query.for('users').select('name', 'age', 'date_of_birth').url(); // or .get();
```
## includes()
```js
// /users?include=posts
const url = query.for('users').includes('posts').url(); // or .get();
```
## appends()
```js
// /users?append=full_name,age
const url = query.for('users').appends('full_name', 'age').url(); // or .get();
```
## limit()
```js
// /users?limit=5
const url = query.for('users').limit(5).url(); // or .get();
```
## limit() | Pagination
```js
// /users?page=2&limit=5
const url = query.for('users').limit(5).page(2).url(); // or .get();
```
## sort()
```js
// /users?sort=-name,age
const url = query.for('users').sort('-name', 'age').url(); // or .get();
```
## Custom parameters
If required, you can also append your own custom parameters to the url by passing an object to the `params()` function.
```js
// /users?format=admin
const url = query.for('users').params({ format: 'admin' }).url(); // or .get();
```
# Customizing Query Parameters
If you need to change the default values for the query parameters, you can optionally pass in a configuration object when initializing your query object.
```js
const { Query } = require("cogent-js");
const query = new Query({
queryParameters: {
include: 'include_custom',
filters: 'filter_custom',
sort: 'sort_custom',
fields: 'fields_custom',
append: 'append_custom',
page: 'page_custom',
limit: 'limit_custom'
}
});
```
# Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
# Contact
Twitter [@joelwmale](https://twitter.com/joelwxd)