feat: Add function and command-line option for clearing cache

BREAKING CHANGE: The package exports only named exports from now on.
If you imported the function `grab` as a default export, import it
by the name `grab` as a named export from now on. The command-line
tool works as it did with no breaking change.

Author: prantlf

README.md

@@ -12,7 +12,7 @@ If used to install a binary executable to a NPM package, [link-bin-executable] c
 ## Synopsis
 
 ```js
-import grab from 'grab-github-release'
+import { grab } from 'grab-github-release'
 
 try {
   const repository = 'prantlf/v-jsonlint'
@@ -57,6 +57,7 @@ Make sure, that you use [Node.js] version 18 or newer.
     Usage: [options]
 
     Options:
+      --clear-cache                 clears the cache, optionally for a "name"
       -r|--repository <repository>  GitHub repository formatted "owner/name"
       -i|--version-spec <semver>    semantic version specifier or "latest"
       -n|--name <file-name>         archive name without the platform suffix
@@ -108,6 +109,14 @@ interface GrabOptions {
   targetDirectory?: string
   // unpack the executable and remove the archive
   unpackExecutable?: boolean
+  // store the downloaded archives from GitHub releases to the cache
+  // in ~/.cache/grabghr; `true` is the default
+  cache?: boolean
+  // GitHub authentication token, overrides the environment variables
+  // GITHUB_TOKEN or GH_TOKEN
+  token?: string
+  // print details about the program execution
+  verbose?: boolean
 }
 
 interface GrabResult {
@@ -119,9 +128,20 @@ interface GrabResult {
   executable?: string
 }
 
+interface ClearCacheOptions {
+  // archive name without the platform and architecture suffix
+  // and without the ".zip" extension as well, used as a cache directory name
+  name?: string
+  // print details about the program execution
+  verbose?: boolean
+}
+
 // downloads and optionally unpacks an archive from GitHub release assets
 // for the current platform
-export default function grab(options: GrabOptions): GrabResult
+export function grab(options: GrabOptions): Promise<GrabResult>
+
+// clears the cache used for downloading archives from GitHub releases
+export function clearCache(options?: ClearCacheOptions): Promise<void>
 ```
 
 ## Contributing

bin/grab-github-release.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
-import grab from '../dist/index.mjs'
+import { grab, clearCache as clear } from '../dist/index.mjs'
 
 function help() {
   console.log(`Generates a unique build number with a human-readable build time.
 
 Usage: [options]
 
 Options:
+  --clear-cache                 clears the cache, optionally for a "name"
   -r|--repository <repository>  GitHub repository formatted "owner/name"
   -i|--version-spec <semver>    semantic version specifier or "latest"
   -n|--name <file-name>         archive name without the platform suffix
@@ -37,7 +38,7 @@ function fail(message) {
 }
 
 const { argv } = process
-let   repository, version, name, platformSuffixes, archSuffixes,
+let   clearCache, repository, version, name, platformSuffixes, archSuffixes,
       targetDirectory, unpackExecutable, cache, token, verbose
 
 for (let i = 2, l = argv.length; i < l; ++i) {
@@ -47,6 +48,9 @@ for (let i = 2, l = argv.length; i < l; ++i) {
     const parseArg = async (arg, flag) => {
       let entries
       switch (arg) {
+        case 'clear-cache':
+          clearCache = flag
+          return
         case 'r': case 'repository':
           repository = match[4] || argv[++i]
           return
@@ -116,26 +120,35 @@ for (let i = 2, l = argv.length; i < l; ++i) {
   fail(`unrecognized argument: "${arg}"`)
 }
 
-if (!repository) {
-  if (argv.length > 2) fail('missing repository')
-  help()
-  process.exit(0)
-}
+if (clearCache) {
+  try {
+    await clear({ name, verbose })
+  } catch(err) {
+    console.error(err.message)
+    process.exitCode = 1
+  }
+} else {
+  if (!repository) {
+    if (argv.length > 2) fail('missing repository')
+    help()
+    process.exit(0)
+  }
 
-try {
-  await grab({
-    repository,
-    version,
-    name,
-    platformSuffixes,
-    archSuffixes,
-    targetDirectory,
-    unpackExecutable,
-    cache,
-    token,
-    verbose
-  })
-} catch(err) {
-  console.error(err.message)
-  process.exitCode = 1
-}
+  try {
+    await grab({
+      repository,
+      version,
+      name,
+      platformSuffixes,
+      archSuffixes,
+      targetDirectory,
+      unpackExecutable,
+      cache,
+      token,
+      verbose
+    })
+  } catch(err) {
+    console.error(err.message)
+    process.exitCode = 1
+  }
+}

src/index.d.ts

@@ -45,6 +45,15 @@ interface GrabOptions {
    * in ~/.cache/grabghr; `true` is the default
    */
   cache?: boolean
+  /**
+   * GitHub authentication token, overrides the environment variables
+   * GITHUB_TOKEN or GH_TOKEN
+   */
+  token?: string
+  /**
+   * print details about the program execution
+   */
+  verbose?: boolean
 }
 
 interface GrabResult {
@@ -62,10 +71,29 @@ interface GrabResult {
   executable?: string
 }
 
+interface ClearCacheOptions {
+  /**
+   * archive name without the platform and architecture suffix
+   * and without the ".zip" extension as well, used as a cache directory name
+   */
+  name?: string
+  /**
+   * print details about the program execution
+   */
+  verbose?: boolean
+}
+
 /**
  * downloads and optionally unpacks an archive from GitHub release assets
  * for the current platform
  * 
  * @param options see properties of `GrabOptions` for more information
  */
-export default function grab(options: GrabOptions): GrabResult
+export function grab(options: GrabOptions): Promise<GrabResult>
+
+/**
+ * clears the cache used for downloading archives from GitHub releases
+ * 
+ * @param options see properties of `ClearCacheOptions` for more information
+ */
+export function clearCache(options?: ClearCacheOptions): Promise<void>

src/index.js

@@ -7,7 +7,7 @@ import { Readable } from 'stream'
 import { open as openArchive } from 'yauzl'
 
 let log = debug('grabghr')
-const { access, chmod, copyFile, mkdir, rename, unlink } = promises
+const { access, chmod, copyFile, mkdir, rm, rename, unlink } = promises
 const { arch, platform } = process
 
 async function exists(file) {
@@ -192,6 +192,13 @@ async function storeCache(cacheDir, cachePath, archivePath, copy) {
   }
 }
 
+async function removeCache(name) {
+  const cacheDir = name ? join(homedir(), '.cache/grabghr', name)
+    : join(homedir(), '.cache/grabghr')
+  log('remove "%s"', cacheDir)
+  await rm(cacheDir, { recursive: true, force: true })
+}
+
 async function download(url, archive, token) {
   const res = await fetchSafely(url, token)
   await new Promise((resolve, reject) => {
@@ -268,7 +275,7 @@ async function makeExecutable(executable) {
   }
 }
 
-export default async function grab({ name, repository, version, platformSuffixes, archSuffixes, targetDirectory, unpackExecutable, cache, token, verbose }) {
+export async function grab({ name, repository, version, platformSuffixes, archSuffixes, targetDirectory, unpackExecutable, cache, token, verbose }) {
   if (verbose) log = console.log.bind(console)
   if (!version) version = 'latest'
   const verspec = clean(version) || version
@@ -286,3 +293,8 @@ export default async function grab({ name, repository, version, platformSuffixes
   }
   return { archive: archivePath, version }
 }
+
+export async function clearCache({ name, verbose } = {}) {
+  if (verbose) log = console.log.bind(console)
+  await removeCache(name)
+}

test/cjs.cjs

@@ -1,4 +1,7 @@
 const { ok } = require('assert')
-const grab = require('../dist/index.cjs')
+const exported = require('../dist/index.cjs')
 
-ok(typeof grab === 'function')
+ok(exported)
+ok(typeof exported === 'object')
+ok(typeof exported.grab === 'function')
+ok(typeof exported.clearCache === 'function')

test/mocked.js

@@ -4,7 +4,7 @@ import { after, before, beforeEach, test, mock } from 'node:test'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
-import grab from 'grab-github-release'
+import { grab, clearCache } from 'grab-github-release'
 import releases from './data/releases.json' assert { type: 'json' }
 
 const exists = file => access(file).then(() => true, () => false)
@@ -30,7 +30,8 @@ const content = new Blob(
   { type: 'application.zip' }
 )
 const targetDirectory = join(__dirname, 'tmp')
-const cacheDirectory = join(homedir(), '.cache/grabghr/', name)
+const wholeCacheDirectory = join(homedir(), '.cache/grabghr')
+const cacheDirectory = join(wholeCacheDirectory, name)
 
 async function cleanup() {
   // failed on Windows on GitHub
@@ -174,3 +175,18 @@ test('copy archive of the latest implicit version from cache and unpack executab
   strictEqual(actualVersion, version)
   ok(actualExecutable.endsWith(executable))
 })
+
+test('clear cache for a name', async () => {
+  await grab({ repository, version })
+  ok(await exists(cacheDirectory), 'cache not found')
+  await clearCache({ name, verbose: true })
+  ok(!await exists(cacheDirectory), 'cache found')
+  ok(await exists(wholeCacheDirectory), 'whole cache not found')
+})
+
+test('clear the whole cache', async () => {
+  await grab({ repository, version })
+  ok(await exists(cacheDirectory), 'cache not found')
+  await clearCache()
+  ok(!await exists(wholeCacheDirectory), 'whole cache found')
+})

test/real.js

@@ -3,7 +3,7 @@ import { access, rm } from 'fs/promises'
 import { after, before, test } from 'node:test'
 import { homedir } from 'os'
 import { join } from 'path'
-import grab from 'grab-github-release'
+import { grab } from 'grab-github-release'
 
 const exists = file => access(file).then(() => true, () => false)
 const { platform, arch } = process
@@ -17,7 +17,7 @@ const platformSuffixes = {
   win32: 'windows'
 }
 const archive = `${name}-${platformSuffixes[platform]}-${arch}.zip`
-const cacheDir = join(homedir(), '.cache/grabghr/', name)
+const cacheDir = join(homedir(), '.cache/grabghr', name)
 
 function cleanup() {
   return Promise.all([

test/types.test.ts

@@ -1,4 +1,4 @@
-import grab from 'grab-github-release'
+import { grab, clearCache } from 'grab-github-release'
 
 declare type testCallback = () => void
 declare function test (label: string, callback: testCallback)
@@ -22,6 +22,16 @@ test('Type declarations for TypeScript', () => {
       x64: ['']
     },
     targetDirectory: '',
-    unpackExecutable: true
+    unpackExecutable: true,
+    cache: true,
+    token: '',
+    verbose: true
+  })
+
+  clearCache()
+
+  clearCache({
+    name: '',
+    verbose: true
   })
 })