npmpackage.info

Gathering detailed insights and metrics for @octokit/graphql

Other packages similar to @octokit/graphql

@octokit/core

6.1.3

Extendable client for GitHub's REST & GraphQL APIs

@octokit/plugin-paginate-graphql

5.2.4

Octokit plugin to paginate GraphQL API endpoint responses

@octokit/graphql-schema

15.25.0

GitHubâs GraphQL Schema with validation. Automatically updated.

@octokit-next/graphql

2.8.0

GitHub GraphQL API client for browsers and Node

@octokit/graphql

GitHub GraphQL API client for browsers and Node

8.2.0

474

MIT

TypeScript

28.19 kB

1,192,849,639 7.6

Installations

npm install @octokit/graphql

Developer Guide

BETA

Typescript

Yes

Module System

ESM

Min. Node Version

>= 18

Node Version

22.13.1

NPM Version

10.9.2 Score

98.5

Supply Chain

99.5

Quality

92.5

Maintenance

100

Vulnerability

100

License

Pull Requests

Open

3

Total

534

Closed

34

Merged

497

Issues

Open

9

Total

84

Closed

75

Releases

v8.2.0

Published on 31 Jan 2025

v8.1.2

Published on 31 Dec 2024

v8.1.1

Published on 15 Apr 2024

v7.1.0

Published on 05 Apr 2024

v8.1.0

Published on 03 Apr 2024

v8.0.2

Published on 03 Apr 2024

View all 60 releases

Contributors

View all 29 contributors

Languages

TypeScript

JavaScript

TypeScript (93.56%)

JavaScript (6.44%)

Developer

octokit

Download Statistics

Total Downloads

1,192,849,639

Last Day

1,863,439

Last Week

8,516,064

Last Month

37,625,336

Last Year

434,556,262

GitHub Statistics

474 Stars

589 Commits

86 Forks

22 Watching

11 Branches

29 Contributors

Maintainers

Package Meta Information

Latest Version

8.2.0

Package Id

@octokit/graphql@8.2.0

Unpacked Size

28.19 kB

Size

7.96 kB

File Count

NPM Version

10.9.2

Node Version

22.13.1

Publised On

31 Jan 2025

Total Downloads

Cumulative downloads

Total Downloads

1,192,849,639

Last day

-4%

1,863,439

Compared to previous day

Last week

-12.5%

8,516,064

Compared to previous week

Last month

5.7%

37,625,336

Compared to previous month

Last year

30.7%

434,556,262

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

@octokit/request @octokit/types universal-user-agent

Dev Dependencies

@octokit/tsconfig @types/fetch-mock @types/node @vitest/coverage-v8 esbuild fetch-mock glob prettier semantic-release-plugin-update-version-in-files typescript vitest

Versions

graphql.js

GitHub GraphQL API client for browsers and Node

Usage
TypeScript
- Additional Types
Errors
Partial responses
Writing tests
License

Usage

Browsers

Browsers	Load `@octokit/graphql` directly from esm.sh `1<script type="module"> 2 import { graphql } from "https://esm.sh/@octokit/graphql"; 3</script>`
Node	Install with `npm install @octokit/graphql` `1import { graphql } from "@octokit/graphql";`

Load @octokit/graphql directly from esm.sh

1<script type="module">
2  import { graphql } from "https://esm.sh/@octokit/graphql";
3</script>

Node

Install with npm install @octokit/graphql

1import { graphql } from "@octokit/graphql";

Send a simple query

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);

Authentication

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);

Variables

⚠️ 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);

Pass query together with headers and variables

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});

Use with GitHub Enterprise

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`);

Use custom `@octokit/request` instance

1import { 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

TypeScript

@octokit/graphql is exposing proper types for its usage with TypeScript projects.

Additional Types

Additionally, GraphQlQueryResponseData has been exposed to users:

1import type { GraphQlQueryResponseData } from "@octokit/graphql";

Errors

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}

Partial responses

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}

Writing tests

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});

License

MIT

No vulnerabilities found.

10

Maintained

Determines if the project is "actively maintained".

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

10

License

Determines if the project has defined a license.

10

Packaging

Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.

10

SAST

Determines if the project uses static code analysis.

9

Security-Policy

Determines if the project has published a security policy.

9

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

5

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 5

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/add_to_octokit_project.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/add_to_octokit_project.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/codeql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/codeql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/codeql.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/codeql.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/immediate-response.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/immediate-response.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/release.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/release.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/test.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/test.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/test.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/update-prettier.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/update-prettier.yml/main?enable=pin
Warn: third-party GitHubAction not pinned by hash: .github/workflows/update-prettier.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/octokit/graphql.js/update-prettier.yml/main?enable=pin
Info: 0 out of 12 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 2 third-party GitHubAction dependencies pinned
Info: 4 out of 4 npmCommand dependencies pinned

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

Fuzzing

Determines if the project uses fuzzing.

Score

7.6

/10

Last Scanned on 2025-01-27

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

Other packages similar to @octokit/graphql

@octokit/graphql

Installations

Developer Guide

Yes

ESM

>= 18

22.13.1

10.9.2

Score

Pull Requests

3

534

34

497

Issues

9

84

75

Releases

Contributors

Languages

Developer

octokit

Download Statistics

GitHub Statistics

Maintainers

Package Meta Information

Total Downloads

1,192,849,639

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Dev Dependencies

graphql.js

Usage

Send a simple query

Authentication

Variables

Pass query together with headers and variables

Use with GitHub Enterprise

Use custom @octokit/request instance

TypeScript

Additional Types

Errors

Partial responses

Writing tests

License

10

10

10

10

10

10

10

9

9

5

0

0

0

7.6

/10

Use custom `@octokit/request` instance