generate-query

generate-query

Generate GraphQL queries from JavaScript objects.

This module was originally designed to be used with the generate-graphql-code module. It can generate TypeScript code for you from your GraphQL introspection.

Table of contents:

• Installation
• Examples
  • 1. Overview
  • 2. Simple query
  • 3. Query with arguments
  • 4. Query with alias
  • 5. Multiple alias
  • 6. Arguments of fields
  • 7. Alias of fields
  • 8. Directives
  • 9. Variables
  • 10. Enums

Installation

# with pnpm
pnpm i generate-query

# or with npm
npm i generate-query

Examples

1. Overview

import generateQuery from 'generate-query'

const query = generateQuery({
  /**
   * Operation type, can be 'query', 'mutation' or 'subscription'.
   *
   * Default: 'query'.
   */
  type: 'query',

  /**
   * Operation body.
   */
  body: {
    /**
     * Describe the field we want to fetch.
     */
    users: {
      /**
       * Optional arguments.
       */
      args: {
        first: 10,

        /**
         * If the value is `undefined`, the field will be skipped.
         */
        after: undefined,

        /**
         * Argument value can be nested objects.
         */
        where: {
          verified: true,
          deletedAt: null
        },

        orderBy: {
          field: 'created_at',

          /**
           * If the value is an object with only one key named `$enum`,
           * the value will be processed as enum.
           *
           * Enum value will not be double-quoted.
           */
          direction: { $enum: 'DESC' }
        }
      },

      /**
       * Specify the fields we want to fetch.
       */
      fields: {
        id: true,

        /**
         * If the value type is `number`, it will be treated as `true`
         * if it is not `0`.
         */
        name: 1,

        /**
         * If the value is a string and it is not an empty string,
         * the string will be used as the alias of this field.
         * If the value is an empty string, the field will be skipped.
         */
        lastName: 'familyName',

        /**
         * The fields with falsy values will be ignored.
         */
        nickname: '',
        createdAt: false,
        updatedAt: null,
        deletedAt: undefined,
        verifiedAt: 0,

        /**
         * Example of selecting sub-fields.
         */
        friends: {
          id: 1,
          name: 1
        },

        /**
         * The array value will be special treated.
         * The objects in the array is used to describe the field.
         * We can specify the alias, arguments, directives and fields
         * of sub-fields by passing an array of object.
         */
        posts: [
          {
            /**
             * Optional alias.
             */
            alias: 'top5posts',

            /**
             * Optional arguments.
             */
            args: {
              first: 5,
              orderBy: {
                field: 'total_like',
                direction: { $enum: 'DESC' }
              }
            },

            /**
             * Optional directives.
             */
            directives: {
              name: '@include',
              args: {
                if: true
              }
            },

            /**
             * Optional fields.
             */
            fields: {
              id: true,
              title: true
            }
          }
        ]
      }
    }
  }
})

console.log(query)

The output is:

query {
  users (
    first: 10
    where: {
      verified: true
      deletedAt: null
    }
    orderBy: {
      field: "created_at"
      direction: DESC
    }
  ) {
    id
    name
    familyName: lastName
    friends {
      id
      name
    }
    top5posts: posts (
      first: 5
      orderBy: {
        field: "total_like"
        direction: DESC
      }
    ) @include (
      if: true
    ) {
      id
      title
    }
  }
}

2. Simple query

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    users: {
      fields: {
        id: true,

        /**
         * If the type of the value is `number`,
         * it will be treated as `true` if it is not `0`.
         */
        name: 1,

        posts: {
          id: true,
          title: true
        }
      }
    }
  }
})

console.log(query)

The output is:

query {
  users {
    id
    name
    posts {
      id
      title
    }
  }
}

3. Query with arguments

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    users: {
      args: {
        first: 10,
        after: undefined, // The `undefined` value will be skipped
        where: {
          statusIn: [1, 2],
          deletedAt: null
        }
      },
      fields: {
        id: true,
        name: true
      }
    }
  }
})

console.log(query)

The output is:

query {
  users (
    first: 10
    where: {
      statusIn: [1, 2]
      deletedAt: null
    }
  ) {
    id
    name
  }
}

4. Query with alias

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    users: {
      alias: 'first_10_users',
      args: { first: 10 },
      fields: { id: true }
    }
  }
})

console.log(query)

The output is:

query {
  first_10_users: users (
    first: 10
  ) {
    id
  }
}

5. Multiple alias

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    users: [
      {
        alias: 'first_10_users',
        args: { first: 10 },
        fields: { id: true }
      },
      {
        alias: 'deleted_users',
        args: { first: 10, deleted: true },
        fields: { id: true }
      }
    ]
  }
})

console.log(query)

The output is:

query {
  first_10_users: users (
    first: 10
  ) {
    id
  }
  deleted_users: users (
    first: 10
    deleted: true
  ) {
    id
  }
}

6. Arguments of fields

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    users: {
      fields: {
        id: true,
        name: true,
        posts: [
          {
            args: {
              first: 5,
              orderBy: 'total_like'
            },
            fields: {
              id: true,
              title: true
            }
          }
        ]
      }
    }
  }
})

console.log(query)

The output is:

query {
  users {
    id
    name
    posts (
      first: 5
      orderBy: "total_like"
    ) {
      id
      title
    }
  }
}

7. Alias of fields

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    countries: {
      fields: {
        code: 'country_code',
        name: [
          {
            alias: 'country_name',
            args: {
              lang: 'en'
            }
          }
        ]
      }
    }
  }
})

console.log(query)

The output is:

query {
  countries {
    country_code: code
    country_name: name (
      lang: "en"
    )
  }
}

8. Directives

import generateQuery from 'generate-query'

const query = generateQuery({
  directives: '@example_directive_1',
  body: {
    users: {
      directives: '@example_directive_2',
      fields: {
        id: true,
        name: [
          {
            directives: [
              '@example_directive_3',
              {
                name: '@example_directive_4',
                args: {
                  directiveArg: 'example'
                }
              }
            ]
          }
        ]
      }
    }
  }
})

console.log(query)

The output is:

query @example_directive_1 {
  users @example_directive_2 {
    id
    name @example_directive_3 @example_directive_4 (
      directiveArg: "example"
    )
  }
}

9. Variables

import generateQuery from 'generate-query'

const query = generateQuery({
  variables: {
    $codes: '[String!]!'
  },
  body: {
    countries: {
      args: {
        codeIn: { $var: '$codes' }
      },
      fields: {
        code: true,
        name: true
      }
    }
  }
})

console.log(query)

The output is:

query (
  $codes: [String!]!
) {
  countries (
    codeIn: $codes
  ) {
    code
    name
  }
}

10. Enums

import generateQuery from 'generate-query'

const query = generateQuery({
  body: {
    posts: {
      args: {
        orderBy: 'total_like',

        /**
         * An object with only one key named `$enum` will be processed
         * as enum value.
         */
        orderDirection: { $enum: 'DESC' }
      },
      fields: {
        id: true,
        title: true,
        totalLike: true
      }
    }
  }
})

console.log(query)

The output is:

query {
  posts (
    orderBy: "total_like"
    orderDirection: DESC
  ) {
    id
    title
    totalLike
  }
}

Please note that the DESC value is not double-quoted for it is enum.