philiprehberger-state_bag

Thread-local state bag for implicit context propagation

Requirements

• Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-state_bag"

Or install directly:

gem install philiprehberger-state_bag

Usage

require "philiprehberger/state_bag"

Philiprehberger::StateBag.set(:user_id, 42)
Philiprehberger::StateBag.get(:user_id)
# => 42

Default Values

Philiprehberger::StateBag.get(:missing, 'fallback')
# => "fallback"

Scoped Overrides

Philiprehberger::StateBag.set(:locale, 'en')

Philiprehberger::StateBag.with(locale: 'de') do
  Philiprehberger::StateBag.get(:locale)
  # => "de"
end

Philiprehberger::StateBag.get(:locale)
# => "en"

Fetch and Delete

require "philiprehberger/state_bag"

Philiprehberger::StateBag.set(:user, "Alice")
Philiprehberger::StateBag.fetch(:user)             # => "Alice"
Philiprehberger::StateBag.fetch(:missing, "default") # => "default"
Philiprehberger::StateBag.fetch(:missing) { |k| "no #{k}" } # => "no missing"

Philiprehberger::StateBag.delete(:user)  # => "Alice"
Philiprehberger::StateBag.key?(:user)    # => false

Inspection

Philiprehberger::StateBag.set(:a, 1)
Philiprehberger::StateBag.key?(:a)   # => true
Philiprehberger::StateBag.size       # => 1
Philiprehberger::StateBag.empty?     # => false
Philiprehberger::StateBag.keys       # => [:a]
Philiprehberger::StateBag.values     # => [1]
Philiprehberger::StateBag.to_h       # => {:a=>1}
Philiprehberger::StateBag.clear

Deep access

Philiprehberger::StateBag.set(:request, { id: "abc", user: { email: "x@y.com" } })
Philiprehberger::StateBag.dig(:request, :user, :email) # => "x@y.com"
Philiprehberger::StateBag.dig(:request, :missing)      # => nil

Bulk Operations

Philiprehberger::StateBag.merge(user_id: 42, locale: 'en', request_id: 'req-1')
# => {:user_id=>42, :locale=>"en", :request_id=>"req-1"}

Philiprehberger::StateBag.slice(:user_id, :locale)
# => {:user_id=>42, :locale=>"en"}

Philiprehberger::StateBag.each { |k, v| puts "#{k}=#{v}" }

Philiprehberger::StateBag.replace(user_id: 99)
Philiprehberger::StateBag.to_h
# => {:user_id=>99}

Update

Atomically read-modify-write a single key. The block receives the current value (or nil if the key is missing) and its return value is stored back.

Philiprehberger::StateBag.set(:counter, 0)
Philiprehberger::StateBag.update(:counter) { |v| v + 1 }
Philiprehberger::StateBag.get(:counter) # => 1

Philiprehberger::StateBag.update(:visited) { |v| (v || []) + ['/home'] }
Philiprehberger::StateBag.get(:visited)  # => ["/home"]

Snapshot & Restore

Philiprehberger::StateBag.set(:user_id, 42)
Philiprehberger::StateBag.set(:locale, 'en')

snapshot = Philiprehberger::StateBag.snapshot
# => {:user_id=>42, :locale=>"en"} (frozen)

Philiprehberger::StateBag.set(:user_id, 99)
Philiprehberger::StateBag.restore(snapshot)
Philiprehberger::StateBag.get(:user_id)
# => 42

API

Method	Description
.set(key, val)	Store a value in the thread-local state bag
.get(key, default = nil)	Retrieve a value or return the default
.with(**overrides, &block)	Execute block with temporary state, restoring after
.fetch(key, default = UNSET, &block)	Retrieve a value; raises KeyError if missing with no default/block
.dig(*keys)	Dig into nested hash-valued entries; returns nil on any miss
.delete(key)	Remove a key and return its value
.clear	Remove all entries from the state bag
.to_h	Return a snapshot of the current state
.key?(key)	Check if a key exists in the state bag
.size	Number of entries in the state bag
.empty?	True if the state bag has no entries
.keys	Array of all keys in the state bag
.values	Array of all values in the state bag
.merge(**entries)	Bulk-set multiple keys; returns a snapshot
.replace(hash)	Replace the entire state with the given hash; returns a snapshot
.slice(*keys)	Return a hash containing only the given keys
.each(&block)	Iterate key-value pairs; returns an Enumerator without a block
.update(key, &block)	Atomic read-modify-write; yields current value (or nil), stores block result
.snapshot	Return a frozen copy of the current state
.restore(snapshot)	Replace the state with a copy of the given snapshot; raises ArgumentError for non-Hash

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT