@lifespikes/cogent-ts

CogentTS

A TypeScript version of CogentJS made by Joel Male

---

Basic Usage

To use CogentTS, it's pretty simple. You just need to import the library and create a new instance of the Cogent class.

import { queryBuilder } from '@lifespikes/cogent-ts';

const builder = queryBuilder();

// /posts?filter[name]=Bob&include=posts,comments&orderBy=-created_at
const url = builder()
    .forModel('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
	.sort(['-created_at']) // order by -created_at desc
	.get(); // generate the url and pass it into fetch!

Also, queryBuilder receives a generic type that is the type of the model you're querying. This is used to provide type safety.

import { queryBuilder } from '@lifespikes/cogent-ts';

interface Post {
    id: number;
    title: string;
    body: string;
}

const builder = queryBuilder<Post>();

// /posts?filter[name]=Bob&include=posts,comments&orderBy=-created_at

const url = builder()
    .forModel('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
    .sort(['-created_at']) // order by -created_at desc
    .get(); // generate the url and pass it into fetch!

Installation

Npm

npm install @lifespikes/cogent-ts

Yarn

yarn add @lifespikes/cogent-ts

Additional Configuration

Base URL

If you want to set a base url for all of your queries, you can do so by passing it into the queryBuilder function.

import { queryBuilder } from '@lifespikes/cogent-ts';

const builder = queryBuilder({
    baseUrl: 'https://api.example.com'
});

// https://api.example.com/posts?filter[name]=Bob&include=posts,comments&orderBy=-created_at
const url = builder()
    .forModel('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
    .sort(['-created_at']) // order by -created_at desc
    .get(); // generate the url and pass it into fetch!

Available Methods

Method	Description	Example
forModel	The model you're querying.	builder().forModel('posts')
where	Where clause.	builder().where('name', 'Bob')
includes	Include the models related relationships.	builder().includes(['posts', 'comments'])
sort	Order by clause.	builder().sort(['-created_at'])
orderBy	Same as sort	builder().orderBy(['-created_at'])
select	Select specific fields.	builder().select(['id', 'name'])
get	Generate the url.	builder().get()
appends	Append additional fields.	builder().appends(['full_name'])
limit	Limit the number of results.	builder().limit(10)
page	Paginate the results.	builder().page(2)
params	Add additional query params.	builder().params({ foo: 'bar' })

Customizing Query Parameters

The query parameters can be customized by passing in an configuration object to the queryBuilder function.

import { queryBuilder } from '@lifespikes/cogent-ts';

const builder = queryBuilder({
    queryParams: {
        include: 'include_custom',
        filters: 'filter_custom',
        sort: 'sort_custom',
        fields: 'fields_custom',
        append: 'append_custom',
        page: 'page_custom',
        limit: 'limit_custom'
    }
});