Merge pull request #3 from oalders/status

Add --status flag

Author: oalders

.github/workflows/test.yml

@@ -1,6 +1,9 @@
 ---
 name: test
 
+env:
+  GITHUB_TOKEN: ${{ github.token }}
+
 on:
   pull_request:
   push:
@@ -32,7 +35,7 @@ jobs:
         run: npm install -g bats
 
       - name: bats test
-        run: echo $PWD && ls && bats test
+        run: echo $PWD && ls && bats --verbose-run test
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
@@ -84,6 +87,8 @@ jobs:
       - run: env | sort
       - name: mkdir
         run: mkdir -p ~/.local/bin
+      - name: npm i
+        run: npm i
       - name: Install ubi
         run: curl --silent --location https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh | TARGET=~/.local/bin sh
       - name: Install omegasort

.gitignore

@@ -2,4 +2,5 @@ c.out
 coverage.out
 debounce
 dist/
+node_modules/
 bin/debounce

.golangci.yaml

@@ -107,10 +107,10 @@ linters-settings:
     line-length: 100
   wrapcheck:
     ignorePackageGlobs:
-    - github.com/oalders/is/*
+      - github.com/oalders/is/*
 issues:
   exclude-rules:
     # disable funlen for test funcs
-    - source: "^func Test"
+    - source: '^func Test'
       linters:
         - funlen

.prettierrc

@@ -0,0 +1,14 @@
+{
+  "printWidth": 80,
+  "proseWrap": "always",
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "parser": "markdown",
+        "printWidth": 80,
+        "proseWrap": "always"
+      }
+    }
+  ]
+}

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changes
 
+## 0.3.0 - 2024-09-25
+
+- Add --status flag
+
 ## 0.2.0 - 2024-09-13
 
 - Obfuscate cache file names

README.md

@@ -1,37 +1,49 @@
 # debounce
 
 <p align="center">
-  <img src="logo.jpeg" />
+  <img src="logo.jpeg" alt="debounce logo" />
 </p>
 
-
 <!-- vim-markdown-toc GFM -->
 
-* [Introduction](#introduction)
-* [Examples](#examples)
-  * [A command without arguments](#a-command-without-arguments)
-  * [A command with arguments](#a-command-with-arguments)
-  * [Using Shell Variables](#using-shell-variables)
-  * [More Complex Commands](#more-complex-commands)
-* [Installation](#installation)
+- [Introduction](#introduction)
+- [Installation](#installation)
+  - [Go Install](#go-install)
+  - [Using Ubi](#using-ubi)
+  - [Download a Release](#download-a-release)
+- [Examples](#examples)
+  - [A command without arguments](#a-command-without-arguments)
+  - [A command with arguments](#a-command-with-arguments)
+  - [Using Shell Variables](#using-shell-variables)
+  - [More Complex Commands](#more-complex-commands)
+- [Available Flags](#available-flags)
+  - [--cache-dir](#--cache-dir)
+  - [--status](#--status)
+    - [Resetting the Cache](#resetting-the-cache)
+  - [--version](#--version)
+  - [--help](#--help)
+- [Caveats](#caveats)
 
 <!-- vim-markdown-toc -->
 
 ## Introduction
 
-debounce is a simple utility to limit the rate at which a command can fire.
+`debounce` is a simple utility to limit the rate at which a command can fire.
+This is useful in scenarios where you want to avoid repetitive command
+executions, like in automation scripts, cron jobs, or continuous integration
+pipelines.
 
-The arguments are:
+The command format is:
 
 ```bash
 debounce <integer> <unit> <command>
 ```
 
 Available units are:
 
-* seconds (s)
-* minutes (m)
-* hours (h)
+- seconds (s)
+- minutes (m)
+- hours (h)
 
 The following are equivalent:
 
@@ -53,10 +65,55 @@ debounce 1 hour date
 debounce 1 hours date
 ```
 
+## Installation
+
+Choose from the following options to install `debounce`.
+
+### Go Install
+
+```bash
+go install github.com/oalders/debounce@latest
+```
+
+or for a specific version:
+
+```bash
+go install github.com/oalders/debounce@v0.3.0
+```
+
+### Using Ubi
+
+You can use [ubi](https://github.com/houseabsolute/ubi) to install `debounce`.
+
+```bash
+#!/usr/bin/env bash
+
+set -eux -o pipefail
+
+# Choose a directory in your $PATH
+dir="$HOME/local/bin"
+
+if [ ! "$(command -v ubi)" ]; then
+    curl --silent --location \
+        https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh |
+        TARGET=$dir sh
+fi
+
+ubi --project oalders/debounce --in "$dir"
+```
+
+### Download a Release
+
+You can download the latest release directly from
+[here](https://github.com/oalders/debounce/releases).
+
 ## Examples
 
 ### A command without arguments
 
+This runs the command without any parameters but prevents repeated execution
+within the set time window.
+
 ```bash
 $ debounce 2 seconds date
 Mon Aug  5 23:09:09 EDT 2024
@@ -66,9 +123,9 @@ $ debounce 2 seconds date
 
 ### A command with arguments
 
-This command uses <https://github.com/houseabsolute/ubi> to install
-<https://github.com/oalders/is> into the current directory.  The command will
-not be run more than once every 8 hours.
+This example uses [ubi](https://github.com/houseabsolute/ubi) to install
+[is](https://github.com/oalders/is) into the current directory. The command
+won't be executed more than once every 8 hours.
 
 ```bash
 $ debounce 8 hours ubi --verbose --project oalders/is --in .
@@ -79,45 +136,119 @@ $ debounce 8 hours ubi --verbose --project oalders/is --in .
 
 ### Using Shell Variables
 
-Remember to single quote variables which shouldn't be expanded until the
-command is run.
+Remember to single quote variables which shouldn't be expanded until the command
+is run.
 
 ```bash
 debounce 10 s zsh -c 'echo $PWD'
 ```
 
 ### More Complex Commands
 
-You can use `&&` and `||` in your commands. You'll want to quote your command
-to ensure that the entire command is passed to `debounce`.
+You can use `&&` and `||` in your commands. You'll want to quote your command to
+ensure that the entire command is passed to `debounce`.
 
 ```bash
 debounce 2 s bash -c 'sleep 2 && date'
 ```
 
-## Installation
+## Available Flags
 
-Choose from the following options to install `debounce`.
+It's important to add `debounce` flags before other command arguments to avoid
+confusion between `debounce` flags and flags meant for your command.
+
+Good: ✅
+
+```shell
+debounce --debug 90 s curl https://www.olafalders.com
+```
+
+Bad: 💥
+
+```shell
+$ debounce 90 s curl https://www.prettygoodping.com --debug
+🚀 Running command: curl https://www.prettygoodping.com --debug
+curl: option --debug: is unknown
+```
+
+You could be explicit about this by using `--` as a visual indicator that flag
+parsing has ended.
 
-1. [Download a release](https://github.com/oalders/debounce/releases)
-1. Use `go install`
-  * `go install github.com/oalders/debounce@latest`
-  * `go install github.com/oalders/debounce@v0.2.0`
-1. Use [ubi](https://github.com/houseabsolute/ubi)
+```shell
+debounce --debug 90 s -- curl https://www.prettygoodping.com
+```
+
+### --cache-dir
+
+Specify an alternate cache directory to use. The directory must already exist.
 
 ```bash
-#!/usr/bin/env bash
+debounce --cache-dir /tmp 30 s date
+```
 
-set -e -u -x -o pipefail
+### --status
 
-# Or choose a different dir in your $PATH
-dir="$HOME/local/bin"
+Print debounce status information for a command.
 
-if [ ! "$(command -v ubi)" ]; then
-    curl --silent --location \
-        https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh |
-        TARGET=$dir sh
-fi
+```bash
+debounce --status 30 s date
+📁 cache location: /Users/olaf/.cache/debounce/0e87632cd46bd4907c516317eb6d81fe0f921a23c7643018f21292894b470681
+🚧 cache last modified: Thu, 19 Sep 2024 08:28:20 EDT
+⏲️ debounce interval: 00:00:30
+🕰️ cache age: 00:00:12
+⏳ time remaining: 00:00:17
+```
 
-ubi --project oalders/debounce --in "$dir"
+#### Resetting the Cache
+
+Since the cache is just a file, you can `rm` the cache location file whenever
+you'd like to start fresh.
+
+```shell
+rm /Users/olaf/.cache/debounce/0e87632cd46bd4907c516317eb6d81fe0f921a23c7643018f21292894b470681
+```
+
+### --version
+
+Prints current version.
+
+```bash
+debounce --version
+0.3.0
+```
+
+### --help
+
+Displays usage instructions.
+
+```text
+debounce --help
+Usage: debounce <quantity> <unit> <command> ... [flags]
+
+limit the rate at which a command can fire
+
+Arguments:
+  <quantity>       Quantity of time
+  <unit>           s,second,seconds,m,minute,minutes,h,hour,hours
+  <command> ...    Command to run
+
+Flags:
+  -h, --help                Show context-sensitive help.
+      --debug               Print debugging info to screen
+      --version             Print version to screen
+      --status              Print cache information for a command without running it
+      --cache-dir=STRING    Override the default cache directory
 ```
+
+## Caveats
+
+Under the hood, `debounce` creates or updates a cache file to track when a
+command was run successfully. This means that, under the right conditions, it's
+entirely possible to kick off two long-running tasks in parallel without
+`debounce` knowing about it.
+
+Additionally, if a command fails, the cache file will not be created or updated.
+
+I've created this tool in a way that meets my needs. I will consider pull
+requests for additional functionality to address issues like these. Please get
+in touch with me first to discuss your feature if you'd like to add something.

age/age.go

@@ -15,7 +15,7 @@ func Compare(path, ageValue, ageUnit string) (bool, error) {
 		if os.IsNotExist(err) {
 			return false, nil
 		}
-		return false, errors.Join(errors.New("could not stat command"), err)
+		return false, errors.Join(errors.New("could not stat cache file"), err)
 	}
 
 	dur, err := age.StringToDuration(ageValue, ageUnit)

go.mod

@@ -3,6 +3,7 @@ module github.com/oalders/debounce
 go 1.20
 
 require (
+	github.com/alecthomas/kong v1.2.1
 	github.com/oalders/is v0.5.4-0.20240716215244-33e0acf2ac19
 	github.com/stretchr/testify v1.9.0
 )

go.sum

@@ -1,5 +1,10 @@
+github.com/alecthomas/assert/v2 v2.10.0 h1:jjRCHsj6hBJhkmhznrCzoNpbA3zqy0fYiUcYZP/GkPY=
+github.com/alecthomas/kong v1.2.1 h1:E8jH4Tsgv6wCRX2nGrdPyHDUCSG83WH2qE4XLACD33Q=
+github.com/alecthomas/kong v1.2.1/go.mod h1:rKTSFhbdp3Ryefn8x5MOEprnRFQ7nlmMC01GKhehhBM=
+github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
 github.com/oalders/is v0.5.4-0.20240716215244-33e0acf2ac19 h1:9BaO8F7ovJseyo119hfahMm1UDU98/cEQ2LN8m+TCmY=
 github.com/oalders/is v0.5.4-0.20240716215244-33e0acf2ac19/go.mod h1:11gTLN1BHxrg8PYn+73Iuspq7kOsQVbl4ccOlj8rHj0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=