Microcms-query-builder NPM

🏠 Homepage

Motivation

Want to use an fully-typed Eloquent-like query builder on the Japanese headless CMS "microCMS".

Install

yarn add microcms-query-builder

Usage

When you have those schema in your microCMS

field id	type	note
id	string	auto generated by microCMS
name	string
quantity	number?
flag	boolean
createdAt	string(formatted datetime)	auto generated by microCMS

then

import {
    FilterBuilder,
    MicroCMSQuery,
    IFilterBuilder,
    IMicroCMSQuery,
    IMicroCMSSearchable,
} from "microcms-query-builder";

interface YourSchema extends IMicroCMSSearchable {
    id: string;
    name: string;
    quantity: number;
    flag: boolean;
    createdAt: string;
}

const builder: IFilterBuilder<YourSchema> = new FilterBuilder<YourSchema>();
const query: IMicroCMSQuery<YourSchema> = builder
    .equals("name", "Bob")
    .exists("quantity")
    .equals("flag", true)
    .greaterThan("createdAt", "2020-01-01")
    .toQuery();

const queryParams: string = query.toString();
// => 'filters=(name[equals]Bob)[and](quantity[exists])[and](flag[equals]true)[and](createdAt[greaterThan]2020-01-01)'

Class and Methods

MicroCMSQuery Class

Class representing the query parameters to be passed to the microCMS list-endpoints. For more information, see official document.

setters

All of properties are optional.

draftKey(arg: string | undefined)
limit(arg: number | undefined)
offset(arg: number | undefined)
orders(arg: { field: keyof YourSchema; sort: "asc" | "desc" }[] | undefined)
q(arg: string | undefined)
fields(arg: keyof YourSchema[] | undefined)
ids(arg: string[] | undefined)
filters(arg: IFilter | undefined)
- Pass the filter object created by FilterBuilder class.
depth(arg: 1 | 2 | 3 | undefined)

toParam()

Create query parameters as object.

axios.get("https://micro.microcms.io/api/v1/{endpoint}?", query.toParam());

toString()

Create query parameters as string.

axios.get("https://micro.microcms.io/api/v1/{endpoint}?" + query.toString());

FilterBuilder Class

Class representing focused on "filters" property of query parameter. For more information, see official document.

where-clause methods

equals(propName, value)
notEquals(propName, value)
lessThan(propName, value)
greaterThan(propName, value)
contains(propName, value)
exists(propName)
notExists(propName)
beginsWith(propName, value)

All propName and value are typed and chainable.

interface YourSchema extends IMicroCMSSearchable {
    id: string;
    name: string;
    quantity: number;
    flag: boolean;
    createdAt: string;
}

const builder = new FilterBuilder<YourSchema>();

builder
    .equals("name", "Bob") // => OK
    .notEquals("quantity", "10") // => NG (value must be a number)
    .exists("notColumn"); // => NG (property 'notColumn' is not defined in YourSchema)

toFilter()

Return filter object, which can be passed to MicroCMSQuery::filters.

toQuery()

Directly create a instance of MicroCMSQuery class. Note that it does not contain any other properties like limit, offset, or else.

Each of these two processes has the same result;

const builder = new FilterBuilder<YourSchema>();
const query = builder.equals("flag", true).toQuery();
query.limit = 10;

const query = new MicroCMSQuery<YourSchema>();
const builder = new FilterBuilder<YourSchema>();
query.limit = 10;
query.filters = builder.equals("flag", true).toFilter();

Disclaimer

This project is under development. There are many missing features (contributions are welcome). For example, searching for custom fields and handling of Date.
I'm not from microCMS, and therefore cannot be held responsible for keeping up with changes in the service's specifications.