ghrepos 2.1.0 → 3.0.1

package/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+    cooldown:
+      default-days: 5
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    commit-message:
+      prefix: 'chore'
+      include: 'scope'
+    cooldown:
+      default-days: 5

package/.github/workflows/test-and-release.yml

@@ -0,0 +1,56 @@
+name: Test & Maybe Release
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [lts/*, current]
+        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install Dependencies
+        run: npm install --no-progress
+      - name: Check build is up to date
+        run: |
+          npm run build
+          git diff --exit-code || (echo "::error::Build artifacts not committed. Run 'npm run build' and commit the changes." && exit 1)
+      - name: Run tests
+        run: npm test
+
+  release:
+    name: Release
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version: lts/*
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm install --no-progress --no-package-lock --no-save
+      - name: Build
+        run: npm run build
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+        run: npx semantic-release

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+## [3.0.1](https://github.com/rvagg/ghrepos/compare/v3.0.0...v3.0.1) (2026-04-28)
+
+### Trivial Changes
+
+* **deps:** bump actions/setup-node from 6 to 6.3.0 ([#8](https://github.com/rvagg/ghrepos/issues/8)) ([77f2065](https://github.com/rvagg/ghrepos/commit/77f2065c68d0b875c91b877a8ee95a9d92109fdb))
+
+## [3.0.0](https://github.com/rvagg/ghrepos/compare/v2.1.0...v3.0.0) (2026-01-27)
+
+### ⚠ BREAKING CHANGES
+
+* modernise, ESM, promises, update deps, GHA, auto-release (#7)
+
+### Bug Fixes
+
+* add release config ([8fcbd12](https://github.com/rvagg/ghrepos/commit/8fcbd128551da685b0f227289dfe1e441b90ece1))
+
+### Trivial Changes
+
+* modernise, ESM, promises, update deps, GHA, auto-release ([#7](https://github.com/rvagg/ghrepos/issues/7)) ([8ad433d](https://github.com/rvagg/ghrepos/commit/8ad433d162b20c64f0331cdd1e2afd369027db87))

package/README.md

@@ -1,201 +1,119 @@
 # ghrepos
 
-[![Build Status](https://secure.travis-ci.org/rvagg/ghrepos.png)](http://travis-ci.org/rvagg/ghrepos)
+**A Node.js library to interact with the GitHub repos API**
 
-**A node library to interact with the GitHub repos API**
+[![NPM](https://nodei.co/npm/ghrepos.svg?style=flat&data=n,v&color=blue)](https://nodei.co/npm/ghrepos/)
 
-[![NPM](https://nodei.co/npm/ghrepos.png?mini=true)](https://nodei.co/npm/ghrepos/)
+## Requirements
 
-See also:
+- Node.js >= 20
 
-* https://github.com/rvagg/ghissues
-* https://github.com/rvagg/ghusers
-* https://github.com/rvagg/ghteams
-* https://github.com/rvagg/ghauth
+## Example usage
 
-## API
+```js
+import * as ghrepos from 'ghrepos'
 
-### listUser(auth[, user][, options], callback)
+const auth = { token: 'your-github-token' }
 
-List all repos for a user. If `user` and `options` are omitted the current user is assumed.
+// list all repos for a user
+const repos = await ghrepos.listUser(auth, 'rvagg')
+console.log(repos)
 
-List all repos for user `'rvagg'`:
+// list all repos for an org
+const orgRepos = await ghrepos.listOrg(auth, 'nodejs')
+console.log(orgRepos)
 
-```js
-const ghrepos     = require('ghrepos')
-    , authOptions = { user: 'rvagg', token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }
+// get branch data
+const branch = await ghrepos.getBranch(auth, 'nodejs', 'node', 'main')
+console.log(branch)
 
-ghrepos.listUser(authOptions, 'rvagg', function (err, repolist) {
-  console.log(reposlist)
-})
+// get commit comments
+const comments = await ghrepos.getCommitComments(auth, 'nodejs', 'node', '75318e46b')
+console.log(comments)
 ```
 
-### listOrg(auth, org[, options], callback)
-
-List all repos for a organisation. If `org` and `options` are omitted the current org is assumed.
-
-List all repos for org `'nodejs'`:
+The auth data is compatible with [ghauth](https://github.com/rvagg/ghauth) so you can connect them together:
 
 ```js
-const ghrepos     = require('ghrepos')
-    , authOptions = { user: 'rvagg', token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }
+import ghauth from 'ghauth'
+import * as ghrepos from 'ghrepos'
 
-ghrepos.listOrg(authOptions, 'nodejs', function (err, repolist) {
-  console.log(reposlist)
+const auth = await ghauth({
+  configName: 'repo-lister',
+  scopes: ['user']
 })
-```
 
-### listRefs(auth, org, repo[, options], callback)
-
-Get git ref data for all refs in a repo.
-
-Get all ref data for `nodejs/node` repo:
-
-```js
-ghrepos.listRefs(authOptions, 'nodejs', 'node', function (err, refData) {
-  // data containing ref information including sha and github url
-  console.log(refData)
+const repos = await ghrepos.listUser(auth, 'rvagg')
+console.log('Repos for rvagg:')
+repos.forEach((r) => {
+  console.log('%s: %s (fork: %s)', r.name, r.description, r.fork)
 })
 ```
 
-### listBranches(auth, org, repo[, options], callback)
+## API
 
-List git branches for a repo.
+All methods return Promises.
 
-Get all branches for `nodejs/node` repo:
+### ghrepos.listUser(auth, user, options)
 
-```js
-ghrepos.listBranches(authOptions, 'nodejs', 'node', function (err, refData) {
-  // data containing branch information including sha and github API url
-  console.log(refData)
-})
-```
+List all repos for a user. If `user` is falsy, lists repos for the authenticated user.
 
-### listCommits(auth, org, repo[, options], callback)
+### ghrepos.listOrg(auth, org, options)
 
-List git commits for a repo.
+List all repos for an organisation.
 
-Get all commits for `nodejs/node` repo:
+### ghrepos.listRefs(auth, org, repo, options)
 
-```js
-ghrepos.listCommits(authOptions, 'nodejs', 'node', function (err, refData) {
-  // data containing commit information including sha and github API url
-  console.log(refData)
-})
-```
+Get git ref data for all refs in a repo.
 
-### listTags(auth, org, repo[, options], callback)
+### ghrepos.listTags(auth, org, repo, options)
 
 List git tags for a repo.
 
-Get all tag for `nodejs/node` repo:
+### ghrepos.listBranches(auth, org, repo, options)
 
-```js
-ghrepos.listTags(authOptions, 'nodejs', 'node', function (err, refData) {
-  // data containing tag information including sha and github API url
-  console.log(refData)
-})
-```
-
-### getRef(auth, org, repo, ref[, options], callback)
-
-Get git ref data for a particular ref string.
-
-Get git ref data for `v1.x` branch in `nodejs/node` repo:
-
-```js
-ghrepos.getRef(authOptions, 'nodejs', 'node', 'heads/v1.x', function (err, refData) {
-  // data containing ref information including sha and github url
-  console.log(refData)
-})
-```
-
-### getBranch(auth, org, repo, branch[, options], callback)
-
-Get git branch data for a given branch name
+List git branches for a repo.
 
-Get git branch data for `v1.x` branch in `nodejs/node` repo:
+### ghrepos.listCommits(auth, org, repo, options)
 
-```js
-ghrepos.getBranch(authOptions, 'nodejs', 'node', 'v1.x', function (err, refData) {
-  // data containing branch information including sha and github API url
-  console.log(refData)
-})
-```
+List git commits for a repo.
 
-### getCommit(auth, org, repo, sha1[, options], callback)
+### ghrepos.getRef(auth, org, repo, ref, options)
 
-Get git commit data for a given sha1
+Get git ref data for a particular ref string. The `refs/` prefix is automatically stripped if present.
 
-Get git commit data for sha1 `75318e46b` in `nodejs/node` repo:
+### ghrepos.getBranch(auth, org, repo, branch, options)
 
-```js
-ghrepos.getCommit(authOptions, 'nodejs', 'node', '75318e46b', function (err, refData) {
-  // data containing commit information including sha and github API url
-  console.log(refData)
-})
-```
+Get git branch data for a given branch name.
 
-### getCommitComments(auth, org, repo, sha1[, options], callback)
+### ghrepos.getCommit(auth, org, repo, sha, options)
 
-Get git commit comments data for a given sha1
+Get git commit data for a given SHA.
 
-Get git commit comments data for sha1 `75318e46b` in `nodejs/node` repo:
+### ghrepos.getCommitComments(auth, org, repo, sha, options)
 
-```js
-ghrepos.getCommitComments(authOptions, 'nodejs', 'node', '75318e46b', function (err, comments) {
-  // array containing commit comments information
-  console.log(JSON.stringify(comments.map(function (i) {
-    return { user: i.user.login, body: i.body }
-  }), null, 2))
-})
-```
+Get commit comments for a given SHA.
 
-Yields:
-
-```json
-[
-  {
-    "user": "Trott",
-    "body": "@cjihrig There's no PR-URL on this commit message. (`core-validate-commit` FTW as usual!)"
-  },
-  {
-    "user": "mscdex",
-    "body": "PR-URL is: https://github.com/nodejs/node/pull/15745"
-  }
-]
-```
+### ghrepos.createLister(type)
 
-### createLister(type)
+Creates a function that lists sub-resources under `/repos/:org/:repo/:type`, e.g. `'issues'`, `'pulls'` or `'releases'`. The returned function has the signature: `async function (auth, org, repo, options)`.
 
-Creates a function that lists different sub types related to the `'/repos'` api, e.g. list `'issues'`, `'pulls'` or `'releases'`. The function returned has the signature: `function list (auth, org, repo, options, callback)`.
+### ghrepos.baseUrl(org, repo, options)
 
-_More methods coming .. as I need them or as you PR them in._
+Returns the base API URL for a repo: `https://api.github.com/repos/:org/:repo`.
 
+## Authentication
 
-The auth data is compatible with [ghauth](https://github.com/rvagg/ghauth) so you can just connect them together to make a simple command-line application:
+See [ghauth](https://github.com/rvagg/ghauth) for an easy way to obtain and cache GitHub authentication tokens. The `auth` object returned by ghauth is directly compatible with all ghrepos methods.
 
-```js
-const ghauth     = require('ghauth')
-    , ghrepos    = require('ghrepos')
-    , authOptions = {
-          configName : 'lister'
-        , scopes     : [ 'user' ]
-      }
-
-ghauth(authOptions, function (err, authData) {
-  ghrepos.listUser(authData, 'rvagg', function (err, list) {
-    console.log('Repos for rvagg:')
-    console.log(util.inspect(list.map(function (i) { return {
-        name: i.name
-      , desc: i.description
-      , fork: i.fork
-    }})))
-  })
-})
-```
+## See also
 
+* [ghissues](https://github.com/rvagg/ghissues) - interact with the GitHub issues API
+* [ghusers](https://github.com/rvagg/ghusers) - interact with the GitHub users API
+* [ghteams](https://github.com/rvagg/ghteams) - interact with the GitHub teams API
+* [ghpulls](https://github.com/rvagg/ghpulls) - interact with the GitHub pull requests API
+* [ghauth](https://github.com/rvagg/ghauth) - GitHub authentication
 
 ## License
 
-**ghrepos** is Copyright (c) 2015 Rod Vagg [@rvagg](https://github.com/rvagg) and licensed under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.
+**ghrepos** is Copyright (c) 2014-2025 Rod Vagg [@rvagg](https://github.com/rvagg) and licensed under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.

package/examples/commit-comments.js

@@ -1,15 +1,13 @@
-const ghauth      = require('ghauth')
-    , ghrepos     = require('..')
-    , authOptions = {
-          configName : 'lister'
-        , scopes     : [ 'user' ]
-      }
+import ghauth from 'ghauth'
+import { getCommitComments } from '../ghrepos.js'
 
-ghauth(authOptions, function (err, authData) {
-  ghrepos.getCommitComments(authData, 'nodejs', 'node', '75318e46b', function (err, comments) {
-    if (err) throw err
-    console.log(JSON.stringify(comments.map(function (i) {
-      return { user: i.user.login, body: i.body }
-    }), null, 2))
-  })
+const authData = await ghauth({
+  configName: 'lister',
+  clientId: 'your-client-id',
+  scopes: ['user']
 })
+
+const comments = await getCommitComments(authData, 'nodejs', 'node', '75318e46b')
+console.log(JSON.stringify(comments.map((i) => {
+  return { user: i.user.login, body: i.body }
+}), null, 2))

package/ghrepos.js

@@ -1,109 +1,72 @@
-const ghutils = require('ghutils')
-    , apiRoot = ghutils.apiRoot
+import { apiRoot, ghget, lister } from 'ghutils'
 
+const defaultApiUrl = apiRoot
 
-function listUser (auth, user, options, callback) {
-  return list (auth, 'user', user, options, callback)
+export function baseUrl (org, repo, options = {}) {
+  const api = options._apiUrl || defaultApiUrl
+  return `${api}/repos/${org}/${repo}`
 }
 
-
-function listOrg (auth, org, options, callback) {
-  return list (auth, 'org', org, options, callback)
+export async function listUser (auth, user, options = {}) {
+  const api = options._apiUrl || defaultApiUrl
+  const url = user ? `${api}/users/${user}/repos` : `${api}/user/repos`
+  return lister(auth, url, options)
 }
 
-
-function list (auth, type, org, options, callback) {
-  if (typeof org == 'function') { // list for this user
-    callback = org
-    options = {}
-    org = null
-  } else if (typeof options == 'function') { // no options
-    callback = options
-    options  = {}
-  }
-
-  var urlbase = apiRoot
-
-  if (org == null) {
-    urlbase += '/user/repos'
-  } else {
-    if (type == 'org')
-      urlbase += '/orgs/' + org + '/repos?'
-    else
-      urlbase += '/users/' + org + '/repos?'
-  }
-
-  ghutils.lister(auth, urlbase, options, callback)
+export async function listOrg (auth, org, options = {}) {
+  const api = options._apiUrl || defaultApiUrl
+  const url = `${api}/orgs/${org}/repos`
+  return lister(auth, url, options)
 }
 
-
-;[ 'refs', 'tags', 'branches', 'commits' ].forEach(function (type) {
-  var singular = type.replace(/e?s$/, '')
-
-  var lister = function (auth, org, repo, options, callback) {
-    if (typeof options == 'function') { // no options
-      callback = options
-      options  = {}
-    }
-
-    var url = refsBaseUrl(org, repo, type)
-    ghutils.lister(auth, url, options, callback)
-  }
-
-  module.exports['list' + type[0].toUpperCase() + type.substring(1)] = lister
-
-  if (type == 'tag')
-    return
-
-  // no getTag API
-  var getter = function (auth, org, repo, ref, options, callback) {
-    if (typeof options == 'function') {
-      callback = options
-      options  = {}
-    }
-
-    // a valid ref but we're not using this format
-    ref = ref.replace(/^refs\//, '')
-
-    var url = refsBaseUrl(org, repo, type) + '/' + ref
-    ghutils.ghget(auth, url, options, callback)
-  }
-
-  module.exports['get' + singular[0].toUpperCase() + singular.substring(1)] = getter
-})
-
-function getCommitComments (auth, org, repo, sha1, options, callback) {
-  var ref = sha1 + '/comments'
-  return module.exports.getCommit(auth, org, repo, ref, options, callback)
+export async function listRefs (auth, org, repo, options = {}) {
+  const url = baseUrl(org, repo, options) + '/git/refs'
+  return lister(auth, url, options)
 }
 
-function createLister (type) {
-  return function list (auth, org, repo, options, callback) {
-    if (typeof options == 'function') {
-      callback = options
-      options  = {}
-    }
+export async function listTags (auth, org, repo, options = {}) {
+  const url = baseUrl(org, repo, options) + '/tags'
+  return lister(auth, url, options)
+}
 
-    var url = baseUrl(org, repo) + '/' + type
-    ghutils.lister(auth, url, options, callback)
-  }
+export async function listBranches (auth, org, repo, options = {}) {
+  const url = baseUrl(org, repo, options) + '/branches'
+  return lister(auth, url, options)
 }
 
+export async function listCommits (auth, org, repo, options = {}) {
+  const url = baseUrl(org, repo, options) + '/commits'
+  return lister(auth, url, options)
+}
 
-function refsBaseUrl (org, repo, type) {
-  if (type == 'refs')
-    type = 'git/' + type
-  return baseUrl(org, repo) + '/' + type
+export async function getRef (auth, org, repo, ref, options = {}) {
+  ref = ref.replace(/^refs\//, '')
+  const url = baseUrl(org, repo, options) + '/git/refs/' + ref
+  const { data } = await ghget(auth, url, options)
+  return data
 }
 
+export async function getBranch (auth, org, repo, branch, options = {}) {
+  const url = baseUrl(org, repo, options) + '/branches/' + branch
+  const { data } = await ghget(auth, url, options)
+  return data
+}
 
-function baseUrl (org, repo) {
-  return apiRoot + '/repos/' + org + '/' + repo
+export async function getCommit (auth, org, repo, sha, options = {}) {
+  const url = baseUrl(org, repo, options) + '/commits/' + sha
+  const { data } = await ghget(auth, url, options)
+  return data
 }
 
+export async function getCommitComments (auth, org, repo, sha, options = {}) {
+  const url = baseUrl(org, repo, options) + '/commits/' + sha + '/comments'
+  const { data } = await ghget(auth, url, options)
+  return data
+}
 
-module.exports.listUser          = listUser
-module.exports.listOrg           = listOrg
-module.exports.baseUrl           = baseUrl
-module.exports.getCommitComments = getCommitComments
-module.exports.createLister      = createLister
+export function createLister (type) {
+  return async function (auth, org, repo, options = {}) {
+    const url = baseUrl(org, repo, options) + '/' + type
+    return lister(auth, url, options)
+  }
+}