Redis::Objects::Periodical

Extend Redis::Objects with counters, values, sets, and hashes whose Redis keys are partitioned by period. Use them for page views, active-user counts, rate-limiting data, and other periodical values.

Installation

Ruby 3.3 or newer is required. Ruby 3.3, 3.4, and 4.0 are tested in CI. The support policy follows stable Ruby branches receiving official normal or security maintenance; preview releases are not supported. CI uses the latest patch releases available in each supported series' CircleCI Ruby image. See Ruby's maintenance status.

Ruby 2.7, 3.0, 3.1, and 3.2 are no longer supported. Applications using those versions must upgrade Ruby before upgrading this gem, or remain on the last gem release whose required_ruby_version permits their Ruby version.

Add this line to your application's Gemfile:

gem 'redis-objects-periodical'

Quick start

Configure the Redis connection as described in Redis::Objects, then declare a field:

require 'redis-objects-periodical'

class Homepage
  include Redis::Objects

  daily_counter :pv, expireat: -> { Time.now + 2_678_400 } # about a month

  def id
    1
  end
end

homepage = Homepage.new
# On 2021-04-01:
homepage.pv.increment(3)
homepage.pv.value # => 3

# On 2021-04-02, calling the field accessor selects the new day's key:
homepage.pv.value # => 0
homepage.pv.increment(2)
homepage.pv.range(Date.new(2021, 4, 1), Date.new(2021, 4, 2)) # => [3, 2]

Keys are unique to the model, its ID, field, and period. This daily counter uses homepage:1:pv:2021-04-01. Each field accessor creates a new periodical object; an object retained in a variable keeps its original key across period boundaries. Use an appropriate expiration option to limit retained period keys.

Available periods and types

Combine one of annual, monthly, weekly, daily, hourly, or minutely with one of these field types:

Type	Daily declaration	Single-period result	Multi-period result
Counter	`daily_counter`	Integer, missing as `0`	Array of integers
Value	`daily_value`	Stored value, missing as `nil`	Array of values
Set	`daily_set`	Members, missing as `[]`	Union of members
Hash	`daily_hash_key`	Hash, missing as `{}`	Hash with combined field values

See the usage guide for declarations, key suffixes, weekly year-boundary behavior, date/time arguments, aggregation, expiration, and timezone selection. Rails/ActiveSupport is optional.

Development and maintenance

Contributing: Docker setup, isolated Compose projects, specs, lint, builds, CI, and optional ActiveSupport verification.
Maintaining: dependency updates, auto-merge, coverage configuration, releases, scheduled maintenance, and CircleCI cutover/rollback.
Agent guidance: repository workflow and compatibility constraints.
Changelog: released changes.

Contributing

Bug reports and pull requests are welcome on GitHub. Track unresolved bugs, improvements, and decisions in GitHub Issues. See CONTRIBUTING.md for the development workflow.

License and code of conduct

The gem is available under the MIT License. Everyone interacting with the Redis::Objects::Periodical project is expected to follow the code of conduct.

redis-objects-daily-counter