ghutils

library5.0.2jsnpmunverified

ghutils is a concise collection of utility functions designed to simplify interactions with the GitHub API. Currently stable at version 5.0.2, it has recently undergone a major overhaul, modernizing its codebase. The package now exclusively uses ES Modules (ESM), returns Promises for all asynchronous operations, and leverages the native `fetch` API for HTTP requests. It targets Node.js environments version 20 or higher. ghutils differentiates itself by providing a streamlined, promise-based interface over the GitHub API's various endpoints (GET, POST, PATCH, DELETE) and offers a powerful `lister` function for handling paginated results. It serves as a foundational library for other specialized GitHub interaction packages like `ghissues` and `ghpulls`.

http-networking devops

npm install ghutils

github ↗package ↗

INSTALL

IMPORT

SIG · GHUTILS

ghutils

http-networkingjavascriptv5.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ghget

✓ import { ghget } from 'ghutils'

✗ const ghget = require('ghutils').ghget

ghutils is ESM-only since v5; CommonJS require() will result in an error. All methods return Promises.

lister

✓ import { lister } from 'ghutils'

✗ import lister from 'ghutils'

lister is a named export, not the default export. Attempting to import it as a default will fail. It returns a Promise.

ghpost

✓ import { ghpost } from 'ghutils'

✗ import * as ghutils from 'ghutils'; const { ghpost } = ghutils;

Destructuring directly from the named export is the idiomatic way. ghpost also returns a Promise.

apiRoot

✓ import { apiRoot } from 'ghutils'

apiRoot is a string constant, not a function.

Demonstrates authenticating with a GitHub token, making a single GET request for user data, and listing paginated issues from a repository using `ghget` and `lister`.

import { ghget, lister } from 'ghutils'; const auth = { token: process.env.GITHUB_TOKEN ?? '' }; if (!auth.token) { console.error('Please set the GITHUB_TOKEN environment variable.'); process.exit(1); } async function main() { try { // Make a single GET request to fetch the authenticated user's profile const { data: user } = await ghget(auth, 'https://api.github.com/user'); console.log('Authenticated User:', user.login); // List all open issues from a specific repository const issues = await lister(auth, 'https://api.github.com/repos/rvagg/ghutils/issues', { state: 'open', per_page: 100 // Example: fetch 100 items per page }); console.log(`Found ${issues.length} open issues in rvagg/ghutils.`); if (issues.length > 0) { console.log('First issue title:', issues[0].title); } } catch (error) { console.error('Error interacting with GitHub API:', error.message); } } main();

Debug

Known issues

breakingVersion 5.0.0 is a major breaking change, converting the library to ES Modules (ESM) only. CommonJS `require()` is no longer supported and will cause a `ERR_REQUIRE_ESM` error.

fix

Migrate your project to use ES Modules `import` syntax. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions. For mixed environments, consider a tool like `cjstoesm` or dynamic `import()` for ESM-only modules.

affects: >=5.0.0

breakingAll API methods (`ghget`, `ghpost`, `lister`, etc.) now exclusively return Promises. Callback-based patterns from previous major versions are removed.

fix

Update your code to use `await` with `async` functions or `.then().catch()` chains to handle asynchronous operations and retrieve results.

affects: >=5.0.0

breakingThe minimum required Node.js version is now 20. Running `ghutils` on older Node.js versions may lead to errors, particularly related to the native `fetch` API.

fix

Upgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` to manage multiple Node.js versions.

affects: >=5.0.0

gotchaAuthentication requires an `auth` object with a `token` property, e.g., `{ token: 'your-github-token' }`. Incorrect or missing tokens will result in GitHub API authentication failures, often with HTTP 401 or 403 status codes.

fix

Ensure your `auth` object is correctly structured and contains a valid GitHub Personal Access Token. Verify the token has the necessary scopes for the API operations you are performing. Consider using `ghauth` for robust token management.

affects: >=1.0.0

gotchaThe `lister` function for paginated results accepts `afterDate` as a `Date` object, and other options (like `state`, `per_page`) are passed directly as query parameters. Misunderstanding these options can lead to unexpected filtering or pagination behavior.

fix

Consult the `lister` API documentation to ensure correct usage of options. For `afterDate`, pass a `Date` object. For query parameters, ensure they match GitHub API specifications (e.g., `per_page` maximum is 100).

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module [path_to_ghutils] not supported.

Attempting to use `ghutils` (v5+) with CommonJS `require()` syntax in a CommonJS module or environment.

fix

Change `const { ghget } = require('ghutils');` to `import { ghget } from 'ghutils';`. Ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension.

TypeError: ghget is not a function

Incorrectly importing named exports, such as attempting a default import when `ghget` is a named export, or attempting to access it on a module object when it's a direct named export.

fix

Ensure you are using named import syntax: `import { ghget } from 'ghutils';`. Do not use `import ghget from 'ghutils';` or `import * as ghutils from 'ghutils'; const ghget = ghutils.ghget;` unless you specifically intend to access it from the module object.

Error: Not Found (or similar 404/401/403 HTTP error from GitHub API)

The provided GitHub API URL is incorrect, the token lacks sufficient permissions (403 Forbidden), or the token is invalid/expired (401 Unauthorized).

fix

Double-check the URL against GitHub API documentation. Verify your GitHub Personal Access Token has the necessary scopes (e.g., `repo`, `public_repo`, `user`) for the specific API endpoint being called. Regenerate or update your token if necessary.

ReferenceError: fetch is not defined

Running `ghutils` in a Node.js environment older than v18, which does not natively support the global `fetch` API, or in an environment where `fetch` is not polyfilled. ghutils v5 requires Node.js >= 20.

fix

Upgrade your Node.js runtime to version 20 or newer. `ghutils` v5+ specifically targets Node.js >= 20, which includes native `fetch`.

Upgrade

Version history

5.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/rvagg/ghutils ↗

packagehttps://www.npmjs.com/package/ghutils ↗