gql

Graphql sevice which watches project files and provides useful information.

Installation

1. Install node package yarn add @playlyfe/gql --dev or npm install @playlyfe/gql --dev
2. Make sure watchman is installed.
3. Create .gqlconfig file in project root.

.gqlconfig

Configuration file in json5 format.

type GQLConfig = {
  schema: {
    files: FileMatchConfig,
    validate?: ValidateConfig
  },
  query?: { // query optional
    files: Array<{
      match: FileMatchConfig, // match files
      parser: QueryParser, 
      isRelay?: boolean,
      validate?: ValidateConfig,
    }>
  }
};

type FileMatchConfig = Globs | { include: Globs, ignore?: Globs };
type Globs = string | Array<string>; // eg **/*.js  **/*.gql

type QueryParser = (
  'QueryParser'
  | ['EmbeddedQueryParser', { startTag: regexpStr, endTag: regexpStr }];
);

type ValidateConfig = {
  extends: 'gql-rules-schema' | 'gql-rules-query' | 'gql-rules-query-relay',
  rules?: {
    [ruleName: string]: 'off' | 'warn' | 'error',
  },
};

// .gqlconfig (only schema)
{
  schema: {
    files: 'schema/**/*.gql'
  }
}

// .gqlconfig (with query)
{
  schema: {
    files: 'schema/**/*.gql',
  },
  query: {
    files: [
      // query gql files
      {
        match: 'path/to/files/**/*.gql',
        parser: 'QueryParser',
      },
      // [Embedded queries] relay files
      {
        match: { include: 'path/to/code/**/*.js', ignore: '**/tests/**/*.js' },
        parser: [ 'EmbeddedQueryParser', { startTag: 'Relay\\.QL`', endTag: '`' } ],
        isRelay: true,
      },
      // [Embedded queries] gql tag files
      {
        match: { include: 'path/to/code/**/*.js', ignore: '**/tests/**/*.js' },
        parser: [ 'EmbeddedQueryParser', { startTag: 'gql`', endTag: '`' } ],
      },
      // [Embedded queries] some other tags 
      {
        match: 'path/to/code/**/*.xyz',
        parser: [ 'EmbeddedQueryParser', { startTag: '"""' endTag: '"""' } ],
      },
      // [Embedded queries] some other tags and modify validation rules
      {
        match: 'path/to/code/**/*.xyz',
        parser: [ 'EmbeddedQueryParser', { startTag: '"""' endTag: '"""' } ],
        validate: {
          extends: 'gql-rules-query',
          rules: {
            LoneAnonymousOperation: 'off',
            NoUnusedVariables: 'warn',
          },
        }
      },
    ]
  }
}

Plugins

• vscode: graphql-for-vscode
• SublimeText: @TODO
• cli: @TODO

Features

Schema

• [x] Validation
• [x] Autocompletion
• [x] Get Defintion
• [x] Find References
• [x] Get Info of symbol at position.
• [x] Watch files and auto update

Query

• [x] Validation
• [x] Autocompletion
• [x] Get Definition
• [x] Support Embedded queries (Relay.QL, gql, others)
• [x] Get Info of symbol
• [ ] Find References
• [ ] Provide query schema dependency graph.

API

class GQLService {
  constructor(options: ?Options)
  
  /*** List of supported commands ***/
  
  // query errors
  status(): Array<GQLError>
  
  // autocomplete suggestion at position
  autocomplete(params: CommandParams): Array<GQLHint>

  // Gets the definition location
  getDef(params: CommandParams): ?DefLocation

  // Find all refs of symbol at position
  findRefs(params: CommandParams): Array<DefLocation>

  // gets the info of symbol at position
  getInfo(params: CommandParams): ?GQLInfo

  /*** Helpers ***/

  // return different file extensions found in .gqlconfig
  getFileExtensions(): Array<string>
}

type Options = {
  cwd?: string,
  onChange?: () => void, // called when something changes
  onInit?: () => void, // called once after initialization
  debug?: boolean, // enable debug logs
  watchman?: boolean, // (default: true) option to disable watchman
};

type CommandParams = {
  sourceText: string,
  sourcePath: string,
  position: { 
    line: number, // starts with 1
    column: number, // starts with 1
  }
};

type DefLocation = {
  start: { line: number, column: number },
  end: { line: number, column: number },
  path: AbsoluteFilePath,
};

type GQLError = {
  message: string,
  severity: 'warn' | 'error',
  locations: ?Array<{ line: number, column: number, path: AbsolutePath }>
};

type GQLHint = {
  text: string,
  type?: string,
  description?: string,
};