🏠 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;

or

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.

Author

👤 hache9669

• Github: @hache9669

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2020 hache9669. This project is MIT licensed.

This README was generated with ❤️ by readme-md-generator