philiprehberger-timeout_kit 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a8adc873e824dbd74917d235e838e7471d7e8d5171dced00b3c551d6cd122c7
-  data.tar.gz: c32d783deeb26085d274dd7e802f0127848ad14292d25bb90edc72f8dbe1112b
+  metadata.gz: 9dfc9b63782aba549dbc26a8ee6d86dda684966ecdad05feef37e76c76b711ef
+  data.tar.gz: 701cb726e36b5fc249ba29e4f21b4c870e4a1f26239b67661ec6e749798876c2
 SHA512:
-  metadata.gz: 41d90f277f055add991dede2a122ba767b109cc1d112526ef4aab0a217b935ad16df0e38ddf78ec78b9cc54de7e4d5c8b542b2b93d6f7c95908ed0deb3c7804a
-  data.tar.gz: 39b256c071b1b339f37b02bb13c07ed76fe486b78006961178c6d6e56d0046c1f04dab90d102b0fd14aa3cfb5b6a343f239c92e654de13fa9ce79658e1c56f64
+  metadata.gz: 97067f5fb32a46696cc861eacdf1f4f986b4031694affc5a7ee905666cfd240e05323beebd32819c6b5b7cdc220b1f91b29c88e68208a7ff159d44504df86d38
+  data.tar.gz: 2da040fd6f4c14d1dff37ae0524bea4d12e65510aa888eed55410c6cf3c0453380c8b0b83da22fecab7d51b1d2f763bdb6401e746461d3b9706212e34baaec37

data/CHANGELOG.md

@@ -7,6 +7,17 @@ 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
+- `Deadline#elapsed` returns seconds since the deadline was created (complement to `#remaining`)
+
 ## [0.2.1] - 2026-03-31
 
 ### Changed

data/README.md

@@ -49,6 +49,24 @@ Philiprehberger::TimeoutKit.deadline(10) do |d|
 end
 ```
 
+### Measuring elapsed time
+
+```ruby
+Philiprehberger::TimeoutKit.deadline(10) do |d|
+  do_work
+  puts "Work took #{d.elapsed}s so far"
+  # elapsed continues to grow past the budget even after expiration
+end
+```
+
+### Deadline Progress
+
+```ruby
+deadline = Philiprehberger::TimeoutKit::Deadline.new(10)
+sleep 5
+deadline.progress # => 0.5 (approximately)
+```
+
 ### Nested Deadlines
 
 ```ruby
@@ -140,6 +158,9 @@ end
 | `.current_deadline` | Return the current active deadline or nil |
 | `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
@@ -20,7 +25,9 @@ module Philiprehberger
       # @param grace [Numeric, nil] optional grace period in seconds after the primary deadline
       # @param on_expire [Proc, nil] optional callback that fires once when expiry is detected
       def initialize(seconds, name: nil, grace: nil, on_expire: nil)
-        @expires_at = now + seconds
+        @started_at = now
+        @duration = seconds.to_f
+        @expires_at = @started_at + seconds
         @name = name
         @grace_seconds = grace
         @grace_expires_at = @grace_seconds ? @expires_at + @grace_seconds : nil
@@ -65,6 +72,27 @@ module Philiprehberger
         end
       end
 
+      # Return the number of seconds elapsed since the deadline was created.
+      # This is a pure wall-clock reading from the monotonic clock and continues
+      # to increase past the original budget after expiration. Independent of
+      # {#expired?} and {#in_grace?}.
+      #
+      # @return [Float] seconds elapsed since creation
+      def elapsed
+        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.2.1'
+    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.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 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,
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/timeout_kit.rb
 - lib/philiprehberger/timeout_kit/deadline.rb
 - lib/philiprehberger/timeout_kit/version.rb
-homepage: https://github.com/philiprehberger/rb-timeout-kit
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-timeout_kit
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-timeout-kit
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-timeout_kit
   source_code_uri: https://github.com/philiprehberger/rb-timeout-kit
   changelog_uri: https://github.com/philiprehberger/rb-timeout-kit/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-timeout-kit/issues