{"id":10944,"library":"ghutils","title":"GitHub API Utilities","description":"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`.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/rvagg/ghutils","tags":["javascript"],"install":[{"cmd":"npm install ghutils","lang":"bash","label":"npm"},{"cmd":"yarn add ghutils","lang":"bash","label":"yarn"},{"cmd":"pnpm add ghutils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ghutils is ESM-only since v5; CommonJS require() will result in an error. All methods return Promises.","wrong":"const ghget = require('ghutils').ghget","symbol":"ghget","correct":"import { ghget } from 'ghutils'"},{"note":"lister is a named export, not the default export. Attempting to import it as a default will fail. It returns a Promise.","wrong":"import lister from 'ghutils'","symbol":"lister","correct":"import { lister } from 'ghutils'"},{"note":"Destructuring directly from the named export is the idiomatic way. ghpost also returns a Promise.","wrong":"import * as ghutils from 'ghutils'; const { ghpost } = ghutils;","symbol":"ghpost","correct":"import { ghpost } from 'ghutils'"},{"note":"apiRoot is a string constant, not a function.","symbol":"apiRoot","correct":"import { apiRoot } from 'ghutils'"}],"quickstart":{"code":"import { ghget, lister } from 'ghutils';\n\nconst auth = { token: process.env.GITHUB_TOKEN ?? '' };\n\nif (!auth.token) {\n  console.error('Please set the GITHUB_TOKEN environment variable.');\n  process.exit(1);\n}\n\nasync function main() {\n  try {\n    // Make a single GET request to fetch the authenticated user's profile\n    const { data: user } = await ghget(auth, 'https://api.github.com/user');\n    console.log('Authenticated User:', user.login);\n\n    // List all open issues from a specific repository\n    const issues = await lister(auth, 'https://api.github.com/repos/rvagg/ghutils/issues', {\n      state: 'open',\n      per_page: 100 // Example: fetch 100 items per page\n    });\n    console.log(`Found ${issues.length} open issues in rvagg/ghutils.`);\n    if (issues.length > 0) {\n      console.log('First issue title:', issues[0].title);\n    }\n  } catch (error) {\n    console.error('Error interacting with GitHub API:', error.message);\n  }\n}\n\nmain();","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your code to use `await` with `async` functions or `.then().catch()` chains to handle asynchronous operations and retrieve results.","message":"All API methods (`ghget`, `ghpost`, `lister`, etc.) now exclusively return Promises. Callback-based patterns from previous major versions are removed.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` to manage multiple Node.js versions.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Authentication 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `ghutils` (v5+) with CommonJS `require()` syntax in a CommonJS module or environment.","error":"ERR_REQUIRE_ESM: require() of ES Module [path_to_ghutils] not supported."},{"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.","cause":"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.","error":"TypeError: ghget is not a function"},{"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.","cause":"The provided GitHub API URL is incorrect, the token lacks sufficient permissions (403 Forbidden), or the token is invalid/expired (401 Unauthorized).","error":"Error: Not Found (or similar 404/401/403 HTTP error from GitHub API)"},{"fix":"Upgrade your Node.js runtime to version 20 or newer. `ghutils` v5+ specifically targets Node.js >= 20, which includes native `fetch`.","cause":"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.","error":"ReferenceError: fetch is not defined"}],"ecosystem":"npm"}