microcms-query-builder
TypeScript icon, indicating that this package has built-in type declarations

0.2.9 • Public • Published

microcms-query-builder

build status npm version npm downloads maintenance license: MIT

🏠 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

🤝 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

Package Sidebar

Install

npm i microcms-query-builder

Weekly Downloads

0

Version

0.2.9

License

MIT

Unpacked Size

49.3 kB

Total Files

39

Last publish

Collaborators

  • hache9669