Tada5hi
rapiq 🌈
Rapiq (R*est *Api Q*uery) is a library to build an efficient interface between client- & server-side applications. It defines a scheme for the request, but *not for the response.
Table of Contents
Installation
npm install rapiq --saveDocumentation
To read the docs, visit https://rapiq.tada5hi.net
Parameters
fields- Description: Return only specific resource fields or extend the default selection.
- URL-Parameter: fields
filters- Description: Filter the resources, according to specific criteria.
- URL-Parameter: filter
relations- Description: Include related resources of the primary resource.
- URL-Parameter: include
pagination- Description: Limit the number of resources returned from the entire collection.
- URL-Parameter: page
sort- Description: Sort the resources according to one or more keys in asc/desc direction.
- URL-Parameter: sort
It is based on the JSON-API specification.
Usage
This is a small outlook on how to use the library. For detailed explanations and extended examples, read the docs.
Build 🔧
The first step is to construct a BuildInput object for a generic Record <T>.
Pass the object to the buildQuery method to convert it to a transportable string.
The BuildInput<T> can contain a configuration for each
Parameter/
URLParameter.
- Fields:
FieldsBuildInput<T> - Filter(s):
FiltersBuildInput<T> - Pagination:
PaginationBuildInput<T> - Relations:
RelationsBuildInput<T> - Sort:
SortBuildInput<T>
NOTE: Check out the API-Reference of each parameter for acceptable input formats and examples.
After building, the string can be passed to a backend application as http query string argument. The backend application can process the request, by parsing the query string.
Example
The following example is based on the assumption, that the following packages are installed:
It should give an insight on how to use this library.
Therefore, a type which will represent a User and a method getAPIUsers are defined.
The method should perform a request to the resource API to receive a collection of entities.
import axios from "axios";
import {
buildQuery,
BuildInput
} from "rapiq";
export type Realm = {
id: string,
name: string,
description: string,
}
export type Item = {
id: string,
realm: Realm,
user: User
}
export type User = {
id: number,
name: string,
email: string,
age: number,
realm: Realm,
items: Item[]
}
type ResponsePayload = {
data: User[],
meta: {
limit: number,
offset: number,
total: number
}
}
const record: BuildInput<User> = {
pagination: {
limit: 20,
offset: 10
},
filters: {
id: 1
},
fields: ['id', 'name'],
sort: '-id',
relations: ['realm']
};
const query = buildQuery(record);
// console.log(query);
// ?filter[id]=1&fields=id,name&page[limit]=20&page[offset]=10&sort=-id&include=realm
async function getAPIUsers(
record: BuildInput<User>
): Promise<ResponsePayload> {
const response = await axios.get('users' + buildQuery(record));
return response.data;
}
(async () => {
let response = await getAPIUsers(record);
// do something with the response :)
})();The next section will describe, how to parse the query string on the backend side.
Parse 🔎
The last step of the whole process is to parse the transpiled query string, to an efficient data structure.
The result object (ParseOutput) can contain an output for each
Parameter/
URLParameter.
- Fields:
FieldsParseOutput<T> - Filter(s):
FiltersParseOutput<T> - Pagination:
PaginationParseOutput<T> - Relations:
RelationsParseOutput<T> - Sort:
SortParseOutput<T>
NOTE: Check out the API-Reference of each parameter for output formats and examples.
Example
The following example is based on the assumption, that the following packages are installed:
For explanation purposes, three simple entities with relations between them are declared to demonstrate the usage on the backend side.
entities.ts
import {
Entity,
PrimaryGeneratedColumn,
Column,
OneToMany,
JoinColumn,
ManyToOne
} from "typeorm";
@Entity()
export class User {
@PrimaryGeneratedColumn({unsigned: true})
id: number;
@Column({type: 'varchar', length: 30})
@Index({unique: true})
name: string;
@Column({type: 'varchar', length: 255, default: null, nullable: true})
email: string;
@Column({type: 'int', nullable: true})
age: number
@ManyToOne(() => Realm, { onDelete: 'CASCADE' })
realm: Realm;
@OneToMany(() => User, { onDelete: 'CASCADE' })
items: Item[];
}
@Entity()
export class Realm {
@PrimaryColumn({ type: 'varchar', length: 36 })
id: string;
@Column({ type: 'varchar', length: 128, unique: true })
name: string;
@Column({ type: 'text', nullable: true, default: null })
description: string | null;
}
@Entity()
export class Item {
@PrimaryGeneratedColumn({unsigned: true})
id: number;
@ManyToOne(() => Realm, { onDelete: 'CASCADE' })
realm: Realm;
@ManyToOne(() => User, { onDelete: 'CASCADE' })
user: User;
}import { Request, Response } from 'express';
import {
applyQuery,
useDataSource
} from 'typeorm-extension';
/**
* Get many users.
*
* Request example
* - url: /users?page[limit]=10&page[offset]=0&include=realm&filter[id]=1&fields=id,name
*
* @param req
* @param res
*/
export async function getUsers(req: Request, res: Response) {
const dataSource = await useDataSource();
const repository = dataSource.getRepository(User);
const query = repository.createQueryBuilder('user');
// -----------------------------------------------------
// parse and apply data on the db query.
const { pagination } = applyQuery(query, req.query, {
defaultPath: 'user',
fields: {
allowed: ['id', 'name', 'realm.id', 'realm.name'],
},
filters: {
allowed: ['id', 'name', 'realm.id'],
},
relations: {
allowed: ['items', 'realm']
},
pagination: {
maxLimit: 20
},
sort: {
allowed: ['id', 'name', 'realm.id'],
}
});
// -----------------------------------------------------
const [entities, total] = await query.getManyAndCount();
return res.json({
data: {
data: entities,
meta: {
total,
...pagination
}
}
});
}License
Made with 💚
Published under MIT License.