GitHub Search API Client

A modern, fully-typed client for the GitHub Search API with automatic pagination, transparent rate-limit handling, and batteries-included developer tooling.

Why this exists

Working with GitHub's Search API quickly gets tricky once you need to:

• respect hard caps (100 results per page, 1,000 total)
• recover from Retry-After / rate-limit responses without sprinkling setTimeout
• stream large result sets efficiently
• ship code that can run both in ESM and CommonJS consumers

This package solves those edges for you and ships with documentation, tests, and examples so you can publish it immediately under your own scope.

Features

• ✅ TypeScript-first API with generated declaration files
• ✅ Automatic pagination + AsyncGenerator helpers
• ✅ Built-in rate limit + Retry-After handling
• ✅ Zero-dependency runtime (axios only)
• ✅ Works in Node.js ≥ 18 (ESM + CJS)
• ✅ Example scripts for everyday workflows (single search + batch from file)

Requirements

• Node.js 18.17+
• A GitHub Personal Access Token (classic or fine-grained) with public_repo or repo scope if you need private data.

Store the token as GITHUB_TOKEN in your shell or .env file (not committed).

Installation

npm install @ynevet/github-search-api-client
# or
yarn add @ynevet/github-search-api-client

Quick start

import { GitHubSearchClient } from "@ynevet/github-search-api-client";

const client = new GitHubSearchClient({ token: process.env.GITHUB_TOKEN! });

const result = await client.searchAll(
  "repositories",
  "language:typescript stars:>5000",
  { sort: "stars", order: "desc", maxItems: 200 }
);

console.log(result.items.map(repo => repo.full_name));

Streaming with async iterators

const names: string[] = [];
for await (const repo of client.iterate("repositories", "topic:ai")) {
  names.push(repo.full_name);
  if (names.length === 50) break; // stop whenever you want
}

Batch a list of queries from disk

GITHUB_TOKEN=xxx npm run examples:batch

Edit examples/queries.txt to fit your workflow. Each line uses:

resource|query|maxItems|perPage

API reference

new GitHubSearchClient(config)

| Option | Type | Default | Description | | --- | --- | --- | --- | | token | string | required | GitHub PAT | | baseUrl | string | https://api.github.com | Use GitHub Enterprise if needed | | userAgent | string | github-search-api-client | Custom UA string | | logger | console subset | console | Provide your own logger |

Methods

• search(resource, query, options?) → single page (perPage, page, sort, order, textMatch, signal)
• searchAll(resource, query, options?) → aggregates up to 1,000 results with maxItems
• iterate(resource, query, options?) → async iterator over items

Utilities like buildSearchUrl, clampPerPage, and constants are also exported for advanced scenarios.

Running the examples locally

npm install
GITHUB_TOKEN=ghp_yourtoken npm run examples:repos
GITHUB_TOKEN=ghp_yourtoken npm run examples:batch

Development workflow

npm install
npm run lint
npm run test
npm run build

Tests use vitest + nock, run quickly, and do not hit the real API.

Releasing it under your GitHub & npm accounts

1. Create a repo

   git init
   git add .
   git commit -m "feat: initial GitHub Search API client"
   gh repo create <your-handle>/github-search-api-client --public --source=. --remote=origin --push

   (Or use the GitHub UI if you prefer.)
2. Publish to npm

   npm login # once
   npm version patch # or minor/major
   npm publish --access public
   git push origin main --follow-tags

ℹ️ I cannot publish on your behalf from this environment. Follow the steps above with your own credentials to push the repo and publish the package.

License

ISC © ynevet