microcms-query-builder
🏠 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
- Github: @hache9669
🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Show your support
Give a
📝 License
Copyright © 2020 hache9669.
This project is MIT licensed.
This README was generated with