ghrepos 2.1.0 → 3.0.0

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
+        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
+        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,13 @@
+## [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)
+  }
+}

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "ghrepos",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Interact with the GitHub repos API",
-  "main": "ghrepos.js",
+  "type": "module",
+  "exports": "./ghrepos.js",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "test": "node test.js | faucet"
+    "lint": "standard",
+    "build": "true",
+    "test:unit": "node --test test.js",
+    "test": "npm run lint && npm run test:unit"
   },
   "repository": {
     "type": "git",
@@ -19,12 +26,98 @@
   "author": "Rod Vagg <r@va.gg>",
   "license": "MIT",
   "dependencies": {
-    "ghutils": "~3.2.0"
+    "ghutils": "^5.0.0"
   },
   "devDependencies": {
-    "faucet": "0.0.1",
-    "ghauth": "^3.2.1",
-    "tape": "~4.3.0",
-    "xtend": "~4.0.0"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.0",
+    "@semantic-release/npm": "^13.0.0",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "semantic-release": "^25.0.0",
+    "standard": "^17.1.2"
+  },
+  "release": {
+    "branches": [
+      "master"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "breaking": true,
+              "release": "major"
+            },
+            {
+              "revert": true,
+              "release": "patch"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            },
+            {
+              "scope": "no-release",
+              "release": false
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "docs",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      "@semantic-release/git"
+    ]
   }
 }