{"id":13453826,"url":"https://github.com/khaosdoctor/gotql","last_synced_at":"2025-05-16T11:06:23.082Z","repository":{"id":27441680,"uuid":"112392972","full_name":"khaosdoctor/gotql","owner":"khaosdoctor","description":"GraphQL query utility for serverside apps","archived":false,"fork":false,"pushed_at":"2024-12-18T15:26:43.000Z","size":1468,"stargazers_count":412,"open_issues_count":1,"forks_count":21,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-09T06:26:04.132Z","etag":null,"topics":["got","graphql","graphql-endpoint","graphql-query","hacktoberfest","http","http-client","javascript","nodejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khaosdoctor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["khaosdoctor","irontitan"]}},"created_at":"2017-11-28T21:46:58.000Z","updated_at":"2025-02-24T20:40:03.000Z","dependencies_parsed_at":"2023-09-29T08:55:14.747Z","dependency_job_id":"6d934366-289b-4f59-a8b8-de9c0b914f8a","html_url":"https://github.com/khaosdoctor/gotql","commit_stats":{"total_commits":345,"total_committers":11,"mean_commits":"31.363636363636363","dds":"0.11304347826086958","last_synced_commit":"b547941e6e39f76537885e1f2b91afde0226fcab"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaosdoctor%2Fgotql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaosdoctor%2Fgotql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaosdoctor%2Fgotql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khaosdoctor%2Fgotql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khaosdoctor","download_url":"https://codeload.github.com/khaosdoctor/gotql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253980311,"owners_count":21994077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["got","graphql","graphql-endpoint","graphql-query","hacktoberfest","http","http-client","javascript","nodejs"],"created_at":"2024-07-31T08:00:48.109Z","updated_at":"2025-05-16T11:06:18.072Z","avatar_url":"https://github.com/khaosdoctor.png","language":"TypeScript","funding_links":["https://github.com/sponsors/khaosdoctor","https://github.com/sponsors/irontitan","https://opencollective.com/gotql","https://opencollective.com/gotql/contribute","https://opencollective.com/gotql/organization/0/website","https://opencollective.com/gotql/organization/1/website","https://opencollective.com/gotql/organization/2/website","https://opencollective.com/gotql/organization/3/website","https://opencollective.com/gotql/organization/4/website","https://opencollective.com/gotql/organization/5/website","https://opencollective.com/gotql/organization/6/website","https://opencollective.com/gotql/organization/7/website","https://opencollective.com/gotql/organization/8/website","https://opencollective.com/gotql/organization/9/website"],"categories":["Packages","TypeScript","Repository","JavaScript","包","HTTP","目录","📦 Legacy \u0026 Inactive Projects"],"sub_categories":["HTTP"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg width=\"360\" height=\"\" src=\"https://cdn.rawgit.com/khaosdoctor/gotql/main/media/gotql.svg\" alt=\"GotQL\"\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003e Write GraphQL queries as objects instead of strings\n\n\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://opencollective.com/gotql\" alt=\"Financial Contributors on Open Collective\"\u003e\n    \u003cimg src=\"https://opencollective.com/gotql/all/badge.svg?label=financial+contributors\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/khaosdoctor/gotql/actions?query=workflow%3A%22Build+and+Publish%22\"\u003e\n    \u003cimg src=\"https://github.com/khaosdoctor/gotql/workflows/Build%20and%20Publish/badge.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://standardjs.com\"\u003e\n    \u003cimg src= \"https://img.shields.io/badge/code_style-standard-brightgreen.svg\" alt=\"JavaScript Style Guide\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\nThis is a better implementation of the [GraphQL](https://github.com/facebook/graphql) query API via NodeJS, created as a wrapper of [Got](http://github.com/sindresorhus/got). It works like a transpiler, with a built in HTTPRequest Client (Got), allowing you to write your GraphQL queries as Javascript Objects instead of strings.\n\nBuilt because manipulating strings is a real pain.\n\n# Table of Contents\n\n\u003c!-- TOC --\u003e\n\n- [Table of Contents](#table-of-contents)\n  - [Install](#install)\n  - [Basic Usage](#basic-usage)\n  - [What is it?](#what-is-it)\n    - [Motivation](#motivation)\n  - [API](#api)\n    - [Option Object](#option-object)\n    - [Returns](#returns)\n  - [The JSON query format](#the-json-query-format)\n    - [Description](#description)\n    - [Examples](#examples)\n      - [Simple query](#simple-query)\n      - [Named query](#named-query)\n      - [Query with simple args](#query-with-simple-args)\n      - [Query with variables](#query-with-variables)\n      - [Nested fields](#nested-fields)\n      - [Enum args](#enum-args)\n    - [Fragment Support](#fragment-support)\n  - [Contributing to this project](#contributing-to-this-project)\n\n\u003c!-- /TOC --\u003e\n\n## Install\n\n```sh\n$ npm install gotql\n```\n\nOr\n\n```sh\n$ yarn install gotql\n```\n\n## Basic Usage\n\n```js\nconst gotQl = require('gotql')\n\nconst query = {\n  operation: {\n    name: 'users',\n    fields: ['name', 'age', 'id']\n  }\n}\n\nconst options = {\n  headers: {\n    Authorization: 'Bearer \u003ctoken\u003e'\n  },\n  debug: false,\n  useHttp2: false\n}\n\ngotQL\n  .query('mygraphqlendpoint.com.br/api', query, options)\n  .then((response) =\u003e console.log(response.data))\n  .catch(console.error)\n```\n\n## What is it?\n\nGotQL is a better interface for GraphQL queries. It provides a way for developers to run queries using JSON instead of strings. Which is a way more usable data format than the string itself.\n\n\u003e See more on: https://hasura.io/blog/fluent-graphql-clients-how-to-write-queries-like-a-boss/\n\n### Motivation\n\nManipulating strings is very smelly, even on dynamically typed languages. So, in order to avoid things such as this:\n\n![](./media/motivation-example.png)\n\nWhich can be translated to something waay more readable in a JSON format like this:\n\n```js\nconst mutation = {\n  operation: {\n    name: 'addLog',\n    args: {\n      logType: literal`status_change`, // Enum Value\n      fromState: variables.fromState,\n      toState: variables.toState,\n      idUser: variables.idUser,\n      idCampaign: variables.idCampaign,\n      owner: {\n        ownerType: variables.ownerType,\n        username: variables.username,\n        picture: variables.picture,\n        name: variables.name,\n        id: variables.id\n      }\n    },\n    fields: ['uuid']\n  }\n}\n```\n\nThis is why GotQL was created.\n\n## API\n\n```js\ngotQl.query(graphQLEndpoint, query, [options])\n```\n\n- **Description**: Performs a graphQL query\n\n**GraphQLEndpoint**\n\n- Type: `string`\n- Description: The GraphQL endpoint to query on\n\n**query**\n\n- Type: `object`\n- Description: The JSON-typed query following the [json-query format](#the-json-query-format)\n\n**options**\n\nSee [option object](#option-object) for more information.\n\n---\n\n```js\ngotQl.mutation(graphQLEndpoint, query, [options])\n```\n\n- **Description**: Performs a graphQL mutation\n\n**GraphQLEndpoint**\n\n- Type: `string`\n- Description: The GraphQL endpoint to query on\n\n**query**\n\n- Type: `object`\n- Description: The JSON-typed query following the [json-query format](#the-json-query-format)\n\n**options**\n\nSee [option object](#option-object) for more information.\n\n---\n\n```js\ngotQl.parser(query, type)\n```\n\n- **Description**: Parses a JSON-Like query and returns the query's string\n\n**query**\n\n- Type: `object`\n- Description: The JSON-typed query following the [json-query format](#the-json-query-format)\n\n**type**\n\n- Type: `string`\n- Description: Must be either `'query'` or `'mutation'`\n\n### Option Object\n\nBoth `gotql.query` and `gotql.mutation` accept an optional user option object with the following API:\n\n- Type: `object`\n- Description: The option object with the following properties.\n  - _errorStatusCode_: Default HTTP status code to be returned on error\n    - Type: `number`\n  - _headers_: Additional headers to be sent\n    - Type: `object`, in the form of `[headerName: string]: headerValue: string`\n  - _gotInstance_: Customized Got instance to be used when calling the endpoint\n    - Type: `got`. Internally this will be called as `got.post(prependHttp(endPoint), gotPayload)`\n  - _useHttp2_: Boolean defining if the call should be made using HTTP2, defaults to `false` (see [release 11 of got](https://github.com/sindresorhus/got/releases/tag/v11.0.0))\n    - Type: `boolean`\n\n\u003e **Note:** GotQL uses [`debug`](https://npmjs.com/package/debug) internally as default debugger, so you can set debug levels by setting the `DEBUG` environment variable. These are the current levels:\n\u003e\n\u003e - `gotql:info`\n\u003e - `gotql:info:parser`\n\u003e - `gotql:info:runner`\n\u003e - `gotql:errors`\n\n### Returns\n\nAll methods return a `string` like this:\n\n```js\nconst response = 'query { test { name args } }'\n```\n\n## The JSON query format\n\nThe JSON format gotQL uses is a simple and intuitive description based on the [anatomy of a GraphQL query](https://dev-blog.apollodata.com/the-anatomy-of-a-graphql-query-6dffa9e9e747) blog post.\n\nThis is a generic model of a JSONLike query:\n\n```js\nconst query = {\n  name?: string,\n  operation: {\n    name: string,\n    alias?: string,\n    args?: { [argName: string]: any } | {\n      [argName: string]: {\n        value: string,\n        escape: boolean\n      }\n    },\n    fields: (string | {\n      [fieldName: string]: [{\n        args?: { [argName: string]: any } | {\n          [argName: string]: {\n            value: string,\n            escape: boolean\n          }\n        },\n        fields?: (string | { [fieldName: string]: [any] })[]\n      }]\n    })[]\n  },\n  variables?: {\n    [varName: string]: {\n      type: string,\n      value: string\n    }\n  }\n}\n```\n\n### Description\n\n- Query:\n  - Type: `object`\n  - Description: The full query object\n  - Properties:\n    - _name_: [optional]: Query name\n      - Type: `string`\n    - _variables_: [optional] Query variable declaration\n      - Type: `object` with signature like `[varName: string]: { type: string, value: string }`\n      - Properties:\n        - _varName_: Variable name\n          - Type: `string`\n        - _type_: Variable type. Can be a GraphQL definition of type (i.e: `string!`)\n          - Type: `string`\n        - _value_: Variable value\n          - Type: `any`\n    - _operation_: The query operation (action that will be executed)\n      - Type: `object`\n      - Properties:\n        - _name_: The operation name\n          - Type: `string`\n        - _alias_: [optional] An alias to give the operation\n          - Type: `string`\n        - _args_: [optional] The operation args\n          - Type: `[argName: string]: any` or a detailed arg object\n            - **_Simple args_**: An `object` where the key is the argument name and its value. Accepts variables in the format of `argName: '$value'`\n              - Example: `args { name: 'myName' }`\n            - **_Detailed args_**: A tagged template. This will give more control over escaping (mostly to use enums). Argument name should be the key\n              - Type: `tagged template`\n              - Examples: `` args: { status: literal`an_enum` } `` should output `operation (status: an_enum)...`\n        - _fields_: The field list to get back from the operation\n          - Type: An `array` of `object` (to use nested fields) or `string`, or both.\n          - Properties (for nested fields):\n            - Type: `object` where the field name is the key\n            - _fields_: Recursive definition, accepts another array just like the _fields_ above.\n            - _args_: [optional] The field args\n              - Type: `[argName: string]: any` or a detailed arg object\n                - **_Simple args_**: An `object` where the key is the argument name and its value. Accepts variables in the format of `argName: '$value'`\n                  - Example: `args { name: 'myName' }`\n                - **_Detailed args_**: A tagged template. This will give more control over escaping (mostly to use enums). Argument name should be the key\n                  - Type: `tagged template`\n                  - Examples: `` args: { status: literal`an_enum` } `` should output `operation (status: an_enum)...`\n    - **_fragments_**: The fragments of the query, see [Fragments Support](#fragment-support) for more information\n      - Type: `string[]`\n\n### Examples\n\n#### Simple query\n\n```js\nconst query = {\n  operation: {\n    name: 'users',\n    fields: ['name', 'age']\n  }\n}\n```\n\nOutputs:\n\n```js\nquery { users { name age } }\n```\n\n#### Named query\n\n```js\nconst query = {\n  name: 'myQuery',\n  operation: {\n    name: 'users',\n    fields: ['name', 'age']\n  }\n}\n```\n\nOutputs:\n\n```js\nquery myQuery { users { name age } }\n```\n\n#### Query with simple args\n\n```js\nconst query = {\n  operation: {\n    name: 'users',\n    args: {\n      name: 'Joe'\n    },\n    fields: ['name', 'age']\n  }\n}\n```\n\nOutputs:\n\n```js\nquery { users(name: \"Joe\") { name age } }\n```\n\n#### Query with variables\n\n```js\nconst query = {\n  variables: {\n    name: {\n      type: 'string!',\n      value: 'Joe'\n    }\n  },\n  operation: {\n    name: 'users',\n    args: {\n      name: '$name'\n    },\n    fields: ['name', 'age']\n  }\n}\n```\n\nOutputs:\n\n```js\nquery ($name: string!) { users(name: $name) { name age } }\n```\n\nVariables are sent on a separate object to graphQL.\n\n```json\n{\n  \"variables\": { \"name\": \"Joe\" }\n}\n```\n\n#### Nested fields\n\n```js\nconst query = {\n  operation: {\n    name: 'users',\n    fields: [\n      'name',\n      'age',\n      {\n        friends: {\n          fields: ['name', 'age']\n        }\n      }\n    ]\n  }\n}\n```\n\nOutputs:\n\n```js\nquery { users { name age friends { name age } } }\n```\n\nRecursive fields can go forever.\n\n#### Enum and literal args\n\nEnum or literal values should not be escaped, to do that, GotQL has a helper called `literal` which can be used to tell the query that value will not be escaped:\n\n```js\nconst { literal } = require('gotql')\n\nconst query = {\n  operation: {\n    name: 'users',\n    args: {\n      type: literal`internal`\n    },\n    fields: ['name', 'age']\n  }\n}\n```\n\nThe code above outputs:\n\n```js\nquery { users(type: internal) { name age } }\n```\n\nThe `literal` helper is just a shorthand to the old-style `{value: string, escape: boolean}` object like below:\n\n```js\nconst query = {\n  operation: {\n    name: 'users',\n    args: {\n      type: {\n        value: 'internal',\n        escape: false\n      }\n    },\n    fields: ['name', 'age']\n  }\n}\n```\n\nIf `literal` is omitted, or if `escape` is set to `true`, the output would be:\n\n```js\nquery { users(type: \"internal\") { name age } }\n```\n\n\u003e **Note:** Variables such as described [here](#query-with-variables) will **not** be recognized. If the arg object is not an `[argName]: value`, variables will not pass through the definition check (GotQL warns if a variable is not declared but used on operation).\n\n### Fragment support\n\nFragment support is in an alpha state (see #55), this means that, while the lib\nsupports fragments, it's not as pretty or as tested as I'd like it to be, but\nPR's are welcome if you want to use it thoroughly.\n\nYou can use fragments by adding a new key in the query JSON, besides\n`operation`, just like you do with variables. This key is called `fragments` and\nit's an array of strings that represent fragments in operations, for example:\n\n```js\nconst query = {\n  operation: {\n    fields: ['f1']\n  },\n  fragments: [`fragment Test on Character { name id }`]\n}\n```\n\nYou can then reference those fragments using the literal struct `fragment`:\n\n```js\nconst query = {\n  operation: {\n    fields: [fragment`Test`]\n  },\n  fragments: [`fragment Test on Character { name id }`]\n}\n```\n\n## Contributing to this project\n\n\u003e Please note that this project is released with a [Contributor Code of Conduct](code-of-conduct.md). By participating in this project you agree to abide by its terms.\n\nHey! If you want to contribute, please read the [contributing guidelines](./.github/CONTRIBUTING.md) :smile:\n\n## Contributors\n\n### Code Contributors\n\nThis project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].\n\u003ca href=\"https://github.com/khaosdoctor/gotql/graphs/contributors\"\u003e\u003cimg src=\"https://opencollective.com/gotql/contributors.svg?width=890\u0026button=false\" /\u003e\u003c/a\u003e\n\n### Financial Contributors\n\nBecome a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/gotql/contribute)]\n\n#### Individuals\n\n\u003ca href=\"https://opencollective.com/gotql\"\u003e\u003cimg src=\"https://opencollective.com/gotql/individuals.svg?width=890\"\u003e\u003c/a\u003e\n\n#### Organizations\n\nSupport this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/gotql/contribute)]\n\n\u003ca href=\"https://opencollective.com/gotql/organization/0/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/0/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/1/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/1/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/2/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/2/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/3/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/3/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/4/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/4/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/5/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/5/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/6/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/6/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/7/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/7/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/8/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/8/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/gotql/organization/9/website\"\u003e\u003cimg src=\"https://opencollective.com/gotql/organization/9/avatar.svg\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhaosdoctor%2Fgotql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhaosdoctor%2Fgotql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhaosdoctor%2Fgotql/lists"}