@fruits-chain/graphql-kit-cli NPM

@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
}