Gathering detailed insights and metrics for @octokit/graphql
Gathering detailed insights and metrics for @octokit/graphql
Gathering detailed insights and metrics for @octokit/graphql
Gathering detailed insights and metrics for @octokit/graphql
@octokit/core
Extendable client for GitHub's REST & GraphQL APIs
@octokit/plugin-paginate-graphql
Octokit plugin to paginate GraphQL API endpoint responses
@octokit/graphql-schema
GitHubâs GraphQL Schema with validation. Automatically updated.
@octokit-next/graphql
GitHub GraphQL API client for browsers and Node
GitHub GraphQL API client for browsers and Node
npm install @octokit/graphql
Typescript
Module System
Min. Node Version
Node Version
NPM Version
98.5
Supply Chain
99.5
Quality
91
Maintenance
100
Vulnerability
100
License
TypeScript (93.56%)
JavaScript (6.44%)
Love this project? Help keep it running — sponsor us today! 🚀
Total Downloads
1,215,577,855
Last Day
2,093,838
Last Week
10,834,559
Last Month
44,625,200
Last Year
442,598,696
MIT License
475 Stars
591 Commits
86 Forks
22 Watchers
11 Branches
29 Contributors
Updated on Feb 12, 2025
Latest Version
8.2.0
Package Id
@octokit/graphql@8.2.0
Unpacked Size
28.19 kB
Size
7.96 kB
File Count
16
NPM Version
10.9.2
Node Version
22.13.1
Published on
Jan 31, 2025
Cumulative downloads
Total Downloads
Last Day
7.7%
2,093,838
Compared to previous day
Last Week
5.1%
10,834,559
Compared to previous week
Last Month
42.2%
44,625,200
Compared to previous month
Last Year
32.1%
442,598,696
Compared to previous year
GitHub GraphQL API client for browsers and Node
Browsers |
Load
|
---|---|
Node |
Install with
|
1const { repository } = await graphql( 2 ` 3 { 4 repository(owner: "octokit", name: "graphql.js") { 5 issues(last: 3) { 6 edges { 7 node { 8 title 9 } 10 } 11 } 12 } 13 } 14 `, 15 { 16 headers: { 17 authorization: `token secret123`, 18 }, 19 }, 20);
The simplest way to authenticate a request is to set the Authorization
header, e.g. to a personal access token.
1const graphqlWithAuth = graphql.defaults({ 2 headers: { 3 authorization: `token secret123`, 4 }, 5}); 6const { repository } = await graphqlWithAuth(` 7 { 8 repository(owner: "octokit", name: "graphql.js") { 9 issues(last: 3) { 10 edges { 11 node { 12 title 13 } 14 } 15 } 16 } 17 } 18`);
For more complex authentication strategies such as GitHub Apps or Basic, we recommend the according authentication library exported by @octokit/auth
.
1const { createAppAuth } = await import("@octokit/auth-app"); 2const auth = createAppAuth({ 3 appId: process.env.APP_ID, 4 privateKey: process.env.PRIVATE_KEY, 5 installationId: 123, 6}); 7const graphqlWithAuth = graphql.defaults({ 8 request: { 9 hook: auth.hook, 10 }, 11}); 12 13const { repository } = await graphqlWithAuth( 14 `{ 15 repository(owner: "octokit", name: "graphql.js") { 16 issues(last: 3) { 17 edges { 18 node { 19 title 20 } 21 } 22 } 23 } 24 }`, 25);
⚠️ Do not use template literals in the query strings as they make your code vulnerable to query injection attacks (see #2). Use variables instead:
1const { repository } = await graphql( 2 ` 3 query lastIssues($owner: String!, $repo: String!, $num: Int = 3) { 4 repository(owner: $owner, name: $repo) { 5 issues(last: $num) { 6 edges { 7 node { 8 title 9 } 10 } 11 } 12 } 13 } 14 `, 15 { 16 owner: "octokit", 17 repo: "graphql.js", 18 headers: { 19 authorization: `token secret123`, 20 }, 21 }, 22);
1import { graphql } from("@octokit/graphql"); 2const { repository } = await graphql({ 3 query: `query lastIssues($owner: String!, $repo: String!, $num: Int = 3) { 4 repository(owner: $owner, name: $repo) { 5 issues(last: $num) { 6 edges { 7 node { 8 title 9 } 10 } 11 } 12 } 13 }`, 14 owner: "octokit", 15 repo: "graphql.js", 16 headers: { 17 authorization: `token secret123`, 18 }, 19});
1import { graphql } from "@octokit/graphql"; 2graphql = graphql.defaults({ 3 baseUrl: "https://github-enterprise.acme-inc.com/api", 4 headers: { 5 authorization: `token secret123`, 6 }, 7}); 8const { repository } = await graphql(` 9 { 10 repository(owner: "acme-project", name: "acme-repo") { 11 issues(last: 3) { 12 edges { 13 node { 14 title 15 } 16 } 17 } 18 } 19 } 20`);
@octokit/request
instance1import { request } from "@octokit/request"; 2import { withCustomRequest } from "@octokit/graphql"; 3 4let requestCounter = 0; 5const myRequest = request.defaults({ 6 headers: { 7 authorization: "bearer secret123", 8 }, 9 request: { 10 hook(request, options) { 11 requestCounter++; 12 return request(options); 13 }, 14 }, 15}); 16const myGraphql = withCustomRequest(myRequest); 17await request("/"); 18await myGraphql(` 19 { 20 repository(owner: "acme-project", name: "acme-repo") { 21 issues(last: 3) { 22 edges { 23 node { 24 title 25 } 26 } 27 } 28 } 29 } 30`); 31// requestCounter is now 2
@octokit/graphql
is exposing proper types for its usage with TypeScript projects.
Additionally, GraphQlQueryResponseData
has been exposed to users:
1import type { GraphQlQueryResponseData } from "@octokit/graphql";
In case of a GraphQL error, error.message
is set to a combined message describing all errors returned by the endpoint.
All errors can be accessed at error.errors
. error.request
has the request options such as query, variables and headers set for easier debugging.
1import { graphql, GraphqlResponseError } from "@octokit/graphql"; 2graphql = graphql.defaults({ 3 headers: { 4 authorization: `token secret123`, 5 }, 6}); 7const query = `{ 8 viewer { 9 bioHtml 10 } 11}`; 12 13try { 14 const result = await graphql(query); 15} catch (error) { 16 if (error instanceof GraphqlResponseError) { 17 // do something with the error, allowing you to detect a graphql response error, 18 // compared to accidentally catching unrelated errors. 19 20 // server responds with an object like the following (as an example) 21 // class GraphqlResponseError { 22 // "headers": { 23 // "status": "403", 24 // }, 25 // "data": null, 26 // "errors": [{ 27 // "message": "Field 'bioHtml' doesn't exist on type 'User'", 28 // "locations": [{ 29 // "line": 3, 30 // "column": 5 31 // }] 32 // }] 33 // } 34 35 console.log("Request failed:", error.request); // { query, variables: {}, headers: { authorization: 'token secret123' } } 36 console.log(error.message); // Field 'bioHtml' doesn't exist on type 'User' 37 } else { 38 // handle non-GraphQL error 39 } 40}
A GraphQL query may respond with partial data accompanied by errors. In this case we will throw an error but the partial data will still be accessible through error.data
1import { graphql } from "@octokit/graphql"; 2graphql = graphql.defaults({ 3 headers: { 4 authorization: `token secret123`, 5 }, 6}); 7const query = `{ 8 repository(name: "probot", owner: "probot") { 9 name 10 ref(qualifiedName: "master") { 11 target { 12 ... on Commit { 13 history(first: 25, after: "invalid cursor") { 14 nodes { 15 message 16 } 17 } 18 } 19 } 20 } 21 } 22}`; 23 24try { 25 const result = await graphql(query); 26} catch (error) { 27 // server responds with 28 // { 29 // "data": { 30 // "repository": { 31 // "name": "probot", 32 // "ref": null 33 // } 34 // }, 35 // "errors": [ 36 // { 37 // "type": "INVALID_CURSOR_ARGUMENTS", 38 // "path": [ 39 // "repository", 40 // "ref", 41 // "target", 42 // "history" 43 // ], 44 // "locations": [ 45 // { 46 // "line": 7, 47 // "column": 11 48 // } 49 // ], 50 // "message": "`invalid cursor` does not appear to be a valid cursor." 51 // } 52 // ] 53 // } 54 55 console.log("Request failed:", error.request); // { query, variables: {}, headers: { authorization: 'token secret123' } } 56 console.log(error.message); // `invalid cursor` does not appear to be a valid cursor. 57 console.log(error.data); // { repository: { name: 'probot', ref: null } } 58}
You can pass a replacement for the built-in fetch implementation as request.fetch
option. For example, using fetch-mock works great to write tests
1import assert from "assert"; 2import fetchMock from "fetch-mock"; 3 4import { graphql } from "@octokit/graphql"; 5 6graphql("{ viewer { login } }", { 7 headers: { 8 authorization: "token secret123", 9 }, 10 request: { 11 fetch: fetchMock 12 .sandbox() 13 .post("https://api.github.com/graphql", (url, options) => { 14 assert.strictEqual(options.headers.authorization, "token secret123"); 15 assert.strictEqual( 16 options.body, 17 '{"query":"{ viewer { login } }"}', 18 "Sends correct query", 19 ); 20 return { data: {} }; 21 }), 22 }, 23});
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
all changesets reviewed
Reason
19 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10
Reason
license file detected
Details
Reason
packaging workflow detected
Details
Reason
SAST tool is run on all commits
Details
Reason
0 existing vulnerabilities detected
Reason
security policy file detected
Details
Reason
dependency not pinned by hash detected -- score normalized to 5
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
project is not fuzzed
Details
Score
Last Scanned on 2025-02-03
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More