microcms-query-builder

$3

Motivation

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

Install

``sh
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

`ts
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 = new FilterBuilder();
const query: IMicroCMSQuery = builder
.equals("name", "Bob")
.exists("quantity")
.equals("flag", true)
.greaterThan("createdAt", "2020-01-01")
.toQuery();

const queryParams: string = query.toString();
// => 'filters=(name[equals]Bob)andandand'
`

Class and Methods

$3

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.

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

#### toString()

Create query parameters as string.

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

$3

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.

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

const builder = new FilterBuilder();

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;

`ts
const builder = new FilterBuilder();
const query = builder.equals("flag", true).toQuery();
query.limit = 10;
`

or

`ts
const query = new MicroCMSQuery();
const builder = new FilterBuilder();
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_