philiprehberger-timeout_kit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80b321def31fd94ffb7e7800f957ed9dcc2037245dfbe90a1213a2bad9e0366d
-  data.tar.gz: cdff9dc81339f285c3209a505644d0ed772943d415c9e58dd731a270b8e0b0db
+  metadata.gz: 9dfc9b63782aba549dbc26a8ee6d86dda684966ecdad05feef37e76c76b711ef
+  data.tar.gz: 701cb726e36b5fc249ba29e4f21b4c870e4a1f26239b67661ec6e749798876c2
 SHA512:
-  metadata.gz: 34fa84c7798b419ba9ba807ecd824a5f20f143cd304e4b96874648c8dec0de012461543ab3af08411898f05011c2967a23e5ff8a488acb88f3a83d35d710bc58
-  data.tar.gz: 2234c624205be2928d8dc09d5257222116d7983af96f88e4d05c3610baf02e7fceb2a5d80ffc8412375562f522f7e99e93ec0704e7106bb6bf0bbf77193828df
+  metadata.gz: 97067f5fb32a46696cc861eacdf1f4f986b4031694affc5a7ee905666cfd240e05323beebd32819c6b5b7cdc220b1f91b29c88e68208a7ff159d44504df86d38
+  data.tar.gz: 2da040fd6f4c14d1dff37ae0524bea4d12e65510aa888eed55410c6cf3c0453380c8b0b83da22fecab7d51b1d2f763bdb6401e746461d3b9706212e34baaec37

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-07
+
+### Added
+- `Deadline#duration` — exposes the original budget passed to `Deadline.new`.
+- `Deadline#progress` — fraction of the budget consumed, useful for progress bars and adaptive cancellation.
+
 ## [0.3.0] - 2026-04-17
 
 ### Added

data/README.md

@@ -59,6 +59,14 @@ Philiprehberger::TimeoutKit.deadline(10) do |d|
 end
 ```
 
+### Deadline Progress
+
+```ruby
+deadline = Philiprehberger::TimeoutKit::Deadline.new(10)
+sleep 5
+deadline.progress # => 0.5 (approximately)
+```
+
 ### Nested Deadlines
 
 ```ruby
@@ -151,6 +159,8 @@ end
 | `Deadline#check!` | Raise `DeadlineExceeded` if the deadline has passed (respects grace period) |
 | `Deadline#remaining` | Seconds remaining until the primary deadline (negative during grace) |
 | `Deadline#elapsed` | Seconds elapsed since the deadline was created (continues past the budget after expiration) |
+| `Deadline#duration` | The original budget passed to `Deadline.new` (Float) |
+| `Deadline#progress` | Fraction of the budget that has elapsed (`elapsed / duration`); exceeds 1.0 after expiry |
 | `Deadline#expired?` | Whether the primary deadline has passed |
 | `Deadline#name` | The human-readable name for this deadline (nil if not set) |
 | `Deadline#in_grace?` | Whether the deadline is in the grace period |

data/lib/philiprehberger/timeout_kit/deadline.rb

@@ -13,6 +13,11 @@ module Philiprehberger
       # @return [String, nil] the human-readable name for this deadline
       attr_reader :name
 
+      # The original budget passed to {.new} as +seconds+.
+      #
+      # @return [Float] the original deadline duration in seconds
+      attr_reader :duration
+
       # Create a new deadline.
       #
       # @param seconds [Numeric] the number of seconds until the deadline expires
@@ -21,6 +26,7 @@ module Philiprehberger
       # @param on_expire [Proc, nil] optional callback that fires once when expiry is detected
       def initialize(seconds, name: nil, grace: nil, on_expire: nil)
         @started_at = now
+        @duration = seconds.to_f
         @expires_at = @started_at + seconds
         @name = name
         @grace_seconds = grace
@@ -76,6 +82,17 @@ module Philiprehberger
         now - @started_at
       end
 
+      # Fraction of the original budget that has elapsed (0.0..1.0+).
+      # Exceeds 1.0 once the primary deadline has expired (and during grace period).
+      # Returns 1.0 if the original budget is zero.
+      #
+      # @return [Float] elapsed / duration
+      def progress
+        return 1.0 if @duration.zero?
+
+        elapsed / @duration
+      end
+
       # Return the remaining time in the grace period.
       #
       # @return [Float] seconds remaining in grace period (0.0 if no grace period or grace expired)

data/lib/philiprehberger/timeout_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module TimeoutKit
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-timeout_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies: []
 description: A cooperative timeout library providing deadline and timeout patterns
   that avoid Thread.raise, with nested deadline support, grace periods, callbacks,