@fruits-chain/graphql-kit-cli

1.0.8 • Public • Published

@fruits-chain/graphql-kit-cli

A cli for graphql-kit. Its main purpose is to serve a mock server and api docs for your graphql service.

Install

Install with npm:

npm install @fruits-chain/graphql-kit-cli --save-dev

Install with yarn:

yarn add @fruits-chain/graphql-kit-cli --dev

Usage

First, you should set up a configuration file:

yarn gk init

After that, you can start the server:

yarn gk start

Now, you can click the link to view docs or proxy your api to the mock server.

Configuration

After running yarn gk init, you'll have a graphql-kit.config.js file in your directory.

interface GraphqlKitConfig {
  /** your gk service port */
  port: number
  /** backend service config */
  endpoint: ServiceConfig
  /** local graphql schema file path */
  localSchemaFile?: string
  /** use either local schema or remote schema, if unset, remote will be used */
  schemaPolicy?: SchemaPolicy
  /** mock config */
  mock?: MockConfig
  /** playground config */
  playground?: PlaygroundConfig
}

interface ServiceConfig {
  /** backend service url */
  url: string
}

interface MockConfig {
  /** enable the mock ability while it's true */
  enable: boolean
  /** the default value of enable arg in mock directive, default is true */
  mockDirectiveDefaultEnableValue: boolean
  /** schema files used for dev env, valid when enable is true */
  schemaFiles?: string[]
  /** value map rules, you should add all your scalar type mappers here or you'll get an error */
  scalarMap: IMockOptions['mocks']
  /** context for mock script in mock directive */
  context?: Record<string, unknown>
  /** graphql resolvers for operations, you can custom operation response here */
  resolvers?: IMockOptions['resolvers']
}

type SchemaPolicy = 'local' | 'remote'

interface PlaygroundConfig {
  /** request headers */
  headers?: Record<string, string>
}

Directives

@mock

Args

  • enable

    Type: Boolean
    Locations: QUERY | MUTATION

    If set and the value is true, the query will be mocked, otherwise the query will be forwarded to backend.

    example

    query customers($page: Page, $customersInput: CustomersInput)
    @mock(enable: true) {
      customers(page: $page, customersInput: $customersInput) {
        records {
          customerId
          customerStatus
        }
        pageCurrent
        pageSize
        totalRecords
      }
    }
  • err

    Type: { code: Int!, message: String! }
    Locations: FIELD

    If set, the query will response a result with errors you provided.

    example

    query customers($page: Page, $customersInput: CustomersInput)
    @mock(enable: true) {
      customers(page: $page, customersInput: $customersInput)
        @mock(err: { code: 500, message: "Internal error" }) {
        records {
          customerId
          customerStatus
        }
        pageCurrent
        pageSize
        totalRecords
      }
    }
  • len

    Type: String | Int
    Locations: FIELD

    If set and the field is of type Array, the result of this field will be an array with length of len.

    example

    query customers($page: Page, $customersInput: CustomersInput)
    @mock(enable: true) {
      customers(page: $page, customersInput: $customersInput) {
        records @mock(len: 10) {
          customerId
          customerStatus
        }
        pageCurrent
        pageSize
        totalRecords
      }
    }
  • val

    Type: String | Number | Boolean | Null
    Locations: FIELD

    If set, the result of this field will be the value you specified.

    example

    query customers($page: Page, $customersInput: CustomersInput)
    @mock(enable: true) {
      customers(page: $page, customersInput: $customersInput) {
        records @mock(len: 10) {
          customerId @mock(val: 1111)
          customerStatus
        }
        pageCurrent
        pageSize
        totalRecords
      }
    }
  • fallback

    Type: Boolean
    Locations: FIELD

    Sometimes, the value of val may cause an validation/runtime error, you can ignore the error by setting fallback to true, then the result will behave as if val is not set. Be aware that if the error is thrown by graphql, it's not effect.

    example

    query customers($page: Page, $customersInput: CustomersInput)
    @mock(enable: true) {
      customers(page: $page, customersInput: $customersInput) {
        records @mock(len: 10) {
          customerId @mock(val: {}, fallback: true)
          customerStatus
        }
        pageCurrent
        pageSize
        totalRecords
      }
    }

Micro script

When the value of val arg is of type String and matches the pattern %{.*}, you'll get this power.

example

document

query customers($page: Page, $customersInput: CustomersInput)
@mock(enable: true) {
  customers(page: $page, customersInput: $customersInput) {
    records @mock(len: "%{page.pageSize}") {
      customerId
        @mock(
          val: "%{path.prev.key + (page.pageCurrent - 1) * page.pageSize + 1}"
        )
      customerStatus
    }
    pageCurrent @mock(val: "%{page.pageCurrent}")
    pageSize @mock(val: "%{page.pageSize}")
    totalRecords @mock(val: "%{100}")
  }
}

variables

{
  "page": {
    "pageCurrent": 2,
    "pageSize": 5
  },
  "customersInput": {
    "keyword": "str",
    "attribute": "INTERNAL"
  }
}

response

{
  "data": {
    "customers": {
      "records": [
        {
          "customerId": 6,
          "customerStatus": "SUSPENSION"
        },
        {
          "customerId": 7,
          "customerStatus": "RESIGN"
        },
        {
          "customerId": 8,
          "customerStatus": "SUSPENSION"
        },
        {
          "customerId": 9,
          "customerStatus": "RESIGN"
        },
        {
          "customerId": 10,
          "customerStatus": "NORMAL"
        }
      ],
      "pageCurrent": 2,
      "pageSize": 5,
      "totalRecords": 100
    }
  }
}

As you can see, the query can response a result associated with your operation variables and some special global vars.

Global vars

  • path

    interface Path {
      // parent field path
      readonly prev: Path | undefined
      // current field name
      readonly key: string | number
      // parent field type
      readonly typename: string | undefined
    }

CLI Commands

init

Run config initialization wizard

start

Start a graphql server

check

Check some config options

help

Display help for command

FAQ

  • I run yarn gk start successfully, but i can't access the doc service in chrome.

    Be sure that your port is not in unsafe port list of chrome.

Readme

Keywords

Package Sidebar

Install

npm i @fruits-chain/graphql-kit-cli

Weekly Downloads

13

Version

1.0.8

License

MIT

Unpacked Size

26.3 kB

Total Files

6

Last publish

Collaborators

  • hemuxue
  • nietao
  • changhuali
  • never-w
  • limoer
  • winljm001
  • onlyling