pennycress 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 481d0ac59ec75712e97bd7ddf0bd6a3dc712e616056d544ca015bfd84fd439f1
+  data.tar.gz: 102c76801dbfb8b2ae6cc11a83acee5405ef8f8277d8d51037f225999dcec2e4
+SHA512:
+  metadata.gz: c2e852b9413643f112c51425b593e550fac26130865b526c96982621b185d031586c14e4a5f42bf92442ae25c0dcd0a8628209d15df5afd9a4f8ab2a6278c529
+  data.tar.gz: 2a7243f6ed832c3ff8434db21e4723070529007ce26c6445b7be86d3f5f9b22b748e377cc72ac676dc9118765ba17e491c6435dd05676c4dde5b49e14da4f932

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Justin Locsei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,333 @@
+<p align="center">
+  <img src="./assets/logo.svg" width="600" alt="Pennycress">
+</p>
+
+<br>
+
+<p align="center">
+  Pennycress is a Rails gem that allows you to describe expensive, model-based computations as Ruby classes.  You define a list of input models, a way to transform those models into a cached output value, and any model changes that should invalidate it.  Values can also provide a plan for warming the cache, enabling distributed, batch-focused precomputation.  By capturing the full lifecycle of a cached value in Ruby, Pennycress offers a lightweight alternative to materialized views that lets you fix hot read paths without recreating them in SQL.
+</p>
+
+---
+
+[![Verify](https://github.com/justinlocsei/pennycress/actions/workflows/verify.yml/badge.svg)](https://github.com/justinlocsei/pennycress/actions/workflows/verify.yml)
+[![Gem Version](https://img.shields.io/gem/v/pennycress.svg)](https://rubygems.org/gems/pennycress)
+[![License](https://img.shields.io/github/license/justinlocsei/pennycress.svg)](https://github.com/justinlocsei/pennycress/blob/main/LICENSE)
+
+<!-- <toc> -->
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Rails Integration](#rails-integration)
+- [How Values Work](#how-values-work)
+  - [Inputs](#inputs)
+  - [Outputs](#outputs)
+  - [Fetching a Value](#fetching-a-value)
+  - [Fetching Multiple Values](#fetching-multiple-values)
+- [Cache Invalidation](#cache-invalidation)
+  - [Producing Invalidation Inputs](#producing-invalidation-inputs)
+  - [Specifying Invalidation Triggers](#specifying-invalidation-triggers)
+  - [Handling Destroyed Records](#handling-destroyed-records)
+- [Cache Warming](#cache-warming)
+  - [Warming the Cache](#warming-the-cache)
+- [Batch Computation](#batch-computation)
+- [Configuring Pennycress](#configuring-pennycress)
+- [Why the Name?](#why-the-name)
+<!-- </toc> -->
+
+## Installation
+
+Add Pennycress to your application's `Gemfile`:
+
+```ruby
+gem "pennycress"
+```
+
+Then install it:
+
+```sh
+bundle install
+```
+
+## Quick Start
+
+Create the following file at `app/values/account_order_total.rb`:
+
+```ruby
+class AccountOrderTotal < Pennycress::Value
+  # Derive the order total from the Account model
+  input :account
+
+  # Compute and cache a numeric order total
+  output Integer
+
+  # Evict the cached value for a changed account
+  watch :account do |account|
+    [{ account: account }]
+  end
+
+  # Evict the cached value for the account associated with a changed order
+  watch :order do |order|
+    [{ account: order.account_id }]
+  end
+
+  # Run a cache-warming job for every active organization
+  seeds { Organization.active.ids }
+
+  # Use a model method to calculate the order total
+  #
+  # In this example, we're assuming that this is an expensive call that triggers
+  # lots of reads.  Maybe it's legacy code that hasn't been touched in ten years.
+  def compute(account:)
+    account.calculate_completed_order_total
+  end
+
+  # Warm the cache for each account in an organization
+  #
+  # This runs in the context of a background job.  Each value emitted by `seeds`
+  # enqueues one background job, so allowing multiple warming jobs to run at
+  # once can rapidly populate cached values.
+  def seed_to_inputs(organization_id)
+    Organization
+      .find(organization_id)
+      .active_accounts
+      .map { |account| { account: account } }
+  end
+end
+```
+
+Any application code that needs the order total for an account can request it by passing an `Account` instance:
+
+```ruby
+AccountOrderTotal.fetch(account: account)
+```
+
+## Rails Integration
+
+Any class that subclasses `Pennycress::Value` and lives under `app/values` is loaded automatically when your Rails app boots or reloads.  Values can be placed in nested directories, allowing for paths like `app/values/billing/account_order_total.rb`.
+
+All discovered values have [invalidation handlers](#cache-invalidation) registered and are made available for [cache warming](#cache-warming).  To use a different location for your value definitions, see [Configuring Pennycress](#configuring-pennycress) for details.
+
+## How Values Work
+
+A Pennycress `Value` describes the transformation of a set of model inputs into an output with a stable cache key.  The smallest useful value specifies its input, output, and a `#compute` method that can delegate to the application's existing logic:
+
+```ruby
+class AccountOrderTotal < Pennycress::Value
+  input :account
+  output Integer
+
+  def compute(account:)
+    account.calculate_completed_order_total
+  end
+end
+```
+
+The `input` and `output` declarations act as both documentation and validation.  If a caller provides an invalid account input, or `#compute` returns a non-numeric value, `Pennycress::ValidationError` is raised.
+
+### Inputs
+
+The `input` declaration accepts one or more model identifiers:
+
+```ruby
+input :account
+input :account, :organization
+```
+
+A model identifier follows Rails naming conventions, with `:account` resolving to `Account` and `:uploaded_file` mapping to `UploadedFile`.  The resolved class must be a database-backed model that inherits from `ActiveRecord::Base`.
+
+### Outputs
+
+The `output` declaration describes the type of data a value produces from its model inputs, which can be either a Ruby class or a hash with multiple typed fields:
+
+```ruby
+output Integer
+output count: Integer, labels: Array
+```
+
+A hash output validates the type of each key's value and raises an error when unknown or missing keys are detected.  Pennycress performs shallow validation of each field against its declared type, so deep validation of an array's items or child hashes should be handled by the caller of `.fetch`.
+
+### Fetching a Value
+
+Application code requests a computed value by calling `.fetch`.  This validates the model inputs, computes the value in the case of a cache miss, and verifies the type of the resulting output.
+
+When requesting a computed value, callers can provide either a persisted model instance or its primary key:
+
+```ruby
+AccountOrderTotal.fetch(account: account)
+AccountOrderTotal.fetch(account: 1)
+```
+
+Pennycress uses the primary key when constructing the cache key, so these forms are equivalent.  On a cache hit, passing a primary key does not load the model from the database.  Composite primary keys are supported by passing their key values as an array.
+
+### Fetching Multiple Values
+
+When application code needs a computed value for several models, it should use `.fetch_many`:
+
+```ruby
+totals = AccountOrderTotal.fetch_many([
+  { account: alfa },
+  { account: bravo },
+  { account: charlie }
+])
+```
+
+The returned values match the order of the inputs, with the second item in `totals` containing the value computed for account `bravo`.  Cached outputs are reused, and only misses are computed.
+
+By default, Pennycress calls `#compute` once for each miss.  Values can override `#compute_many` to replace those calls with a more efficient batch calculation, which is explored in depth in [Batch Computation](#batch-computation).
+
+## Cache Invalidation
+
+Pennycress enables fine-grained invalidation in response to committed changes to Active Record models.  A value declares invalidation rules using `watch`, which specifies a model and logic to run when an instance of that model changes:
+
+```ruby
+class AccountOrderTotal < Pennycress::Value
+  watch :account do |account|
+    [{ account: account }]
+  end
+end
+```
+
+The symbol passed to `watch` resolves to an Active Record class using Rails naming conventions.  When a matching model is created, updated, or destroyed, Pennycress calls the block with the changed record and evicts the cached output for every input returned by the block.  With an input's value removed from the cache, the next call to `.fetch` will calculate it with the latest model data.
+
+### Producing Invalidation Inputs
+
+A watch block returns an enumerable of inputs for the value.  It may return one input, several inputs, or an empty array when a change does not affect the value.  Inputs follow the same rules used for the values passed to `.fetch`, supporting either model instances or IDs:
+
+```ruby
+watch :account { |account| [{ account: account }] }
+watch :order { |order| [{ account: order.account_id }] }
+```
+
+Inputs can be any valid `Enumerable`, rather than just a concrete `Array`.  If your list of inputs may be large, you can use a lazy or custom `Enumerator` to reduce memory usage during invalidation.
+
+### Specifying Invalidation Triggers
+
+By default, a watch responds to `:create`, `:update`, and `:destroy` commits.  If you would like to only respond to a subset of those events, use `on:` to narrow the actions that trigger invalidation:
+
+```ruby
+watch :order, on: %i[create update] do |order|
+  [{ account: order.account_id }]
+end
+```
+
+If a value should only be invalidated when specific fields change, the watch block can inspect Active Record's saved-change information and return an empty list of inputs for unrelated changes:
+
+```ruby
+watch :account, on: [:update] do |account|
+  account.saved_change_to_billing_status? ? [{ account: account }] : []
+end
+```
+
+### Handling Destroyed Records
+
+Destroy invalidations run after the destroy transaction is committed.  The record's in-memory attributes, including its primary and foreign keys, are generally still available, but the row will no longer exists in the database.
+
+These conditions can result in errors when trying to fetch associated records.  For watches that respond to a `:destroy` commit, derive inputs from attributes retained on the destroyed instance:
+
+```ruby
+watch :order, on: %i[create update destroy] do |order|
+  [{ account: order.account_id }]
+end
+```
+
+If a watch cannot handle destroyed records using the same logic as created or updated ones, you can define separate invalidation handlers for each action:
+
+```ruby
+watch :order, on: %i[create update] do |order|
+  [{ account: order.account.id }]
+end
+
+watch :order, on: [:destroy] do |order|
+  [{ account: order.account_id }]
+end
+```
+
+## Cache Warming
+
+Pennycress values can define seeds that divide the work of cache warming into discrete background jobs.  Each seed returned from the `seeds` block creates an Active Job that passes its seed to `.seed_to_inputs`, and the resulting inputs are fetched through the normal cache pipeline.
+
+```ruby
+class AccountOrderTotal < Pennycress::Value
+  input :account
+  output Integer
+
+  seeds { Organization.active.ids }
+
+  def seed_to_inputs(organization_id)
+    Organization
+      .find(organization_id)
+      .active_accounts
+      .map { |account| { account: account } }
+  end
+
+  def compute(account:)
+    account.calculate_completed_order_total
+  end
+end
+```
+
+Seeds can be any value that can be safely serialized in the context of an Active Job.  When possible, prefer primitive values like numbers and strings.
+
+Seeding is a performance optimization to eagerly populate the cache for values that are known to put pressure on the database.  A value can define as narrow or wide a set of inputs for warming as are appropriate to the computed value.
+
+### Warming the Cache
+
+All registered `Value` classes that define seeds can be warmed via the `pennycress:warm_cache` Rake task, making it a natural fit for post-deployment tasks.  If you prefer to start cache warming through Ruby code, you can call `Pennycress.warm_cache`.
+
+Both operations will block while they enqueue Active Jobs for each warming seed.  This should be a fast operation, since the computation of each value is performed in the background jobs, and the only synchronous work is the calculation of seeds.
+
+Warming jobs will be added to the default queue without any further configuration.  If you wish to use a named queue to limit concurrent jobs, you can use the `warming_queue` option detailed in [Configuring Pennycress](#configuring-pennycress).
+
+## Batch Computation
+
+The default `#compute_many` implementation calls `#compute` for each input that resulted in a cache miss.  If a value can be calculated more efficiently in bulk, define a custom `compute_many` implementation:
+
+```ruby
+class AccountOrderTotal < Pennycress::Value
+  input :account
+  output Integer
+
+  def compute(account:)
+    account.calculate_completed_order_total
+  end
+
+  def compute_many(inputs)
+    ids = inputs.map do |input|
+      input[:account].id
+    end
+
+    by_id = Account.calculate_completed_order_totals_for_ids(ids)
+
+    ids.map do |id|
+      by_id.fetch(id)
+    end
+  end
+end
+```
+
+This example uses a theoretical method that efficiently calculates order totals for multiple accounts and exposes the totals in a hash keyed by account ID.  By fetching these values once and mapping them to the ordered inputs, `compute_many` avoids N+1 issues when calculating multiple account totals.
+
+## Configuring Pennycress
+
+While Pennycress comes with sane defaults, you can customize its integration with your Rails app using an initializer.  The available settings and their default values are shown below:
+
+```ruby
+# config/initializers/pennycress.rb
+Pennycress.configure do |config|
+  # The ActiveSupport::Cache::Store instance used for all cache operations
+  config.cache = Rails.cache
+
+  # The prefix used for the cache key of all Pennycress values
+  config.cache_namespace = "pennycress"
+
+  # The directories in which values can be defined
+  config.directories = ["app/values"]
+
+  # The queue to which warming jobs are added
+  config.warming_queue = :default
+end
+```
+
+## Why the Name?
+
+In [floristry](https://www.instagram.com/justinlocsei/), pennycress is a filler flower with lots of tiny leaves.  Fine, granular foliage feels appropriate for a library that offers fine-grained cache invalidation.

data/lib/pennycress/cache.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pennycress
+  # A cache is a thin wrapper around an ActiveSupport cache store that uses
+  # specialized output references for all cache operations.
+  class Cache
+    WRITE_OPTIONS = { skip_nil: true }.freeze
+    private_constant :WRITE_OPTIONS
+
+    # Creates a cache
+    #
+    # @param store [ActiveSupport::Cache::Store] the backing cache store
+    def initialize(store)
+      @store = store
+    end
+
+    # Evicts a cached value
+    #
+    # @param reference [OutputReference]
+    # @return [void]
+    def evict(reference)
+      @store.delete(reference.cache_key)
+    end
+
+    # Evicts cached values
+    #
+    # @param references [Array<OutputReference>]
+    # @return [void]
+    def evict_many(references)
+      @store.delete_multi(references.map(&:cache_key))
+    end
+
+    # Reads a cached value, computing and storing it when absent
+    #
+    # @param reference [OutputReference]
+    # @yieldparam reference [OutputReference] a reference that was not cached
+    # @yieldreturn [Object] the value to cache in the case of a cache miss
+    # @return [Object] the cached or computed value
+    def fetch(reference, &)
+      @store.fetch(reference.cache_key, **WRITE_OPTIONS, &)
+    end
+
+    # Reads a set of cached values, computing and storing misses
+    #
+    # @param references [Array<OutputReference>]
+    # @yieldparam reference [OutputReference] a reference that was not cached
+    # @yieldreturn [Object] the value to cache for the reference
+    # @return [Array<Object>] cached or computed values in reference order
+    def fetch_multi(references)
+      keys = references.map(&:cache_key)
+      refs_by_key = keys.zip(references).to_h
+
+      cached = @store.fetch_multi(*keys, **WRITE_OPTIONS) do |key|
+        yield refs_by_key.fetch(key)
+      end
+
+      keys.map { |key| cached.fetch(key) }
+    end
+
+    # Writes a value to the cache
+    #
+    # @param reference [OutputReference]
+    # @param value [Object] the value to cache
+    # @return [void]
+    def write(reference, value)
+      @store.write(reference.cache_key, value, **WRITE_OPTIONS)
+    end
+
+    # Writes multiple values to the cache
+    #
+    # @param entries [Hash{OutputReference => Object}]
+    # @return [void]
+    def write_multi(entries)
+      @store.write_multi(
+        entries.transform_keys(&:cache_key),
+        **WRITE_OPTIONS
+      )
+    end
+  end
+end

data/lib/pennycress/caching.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pennycress
+  # This module defines helpers for building cache keys.
+  module Caching
+    # Builds a cache key from segments
+    #
+    # @param segments [Array<Object>]
+    # @return [String]
+    def self.key(*segments)
+      segments
+        .compact
+        .map(&:to_s)
+        .reject(&:empty?)
+        .join("/")
+    end
+  end
+end

data/lib/pennycress/configuration.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_support/cache/null_store"
+
+module Pennycress
+  # The configuration stores all global settings for Pennycress.
+  class Configuration
+    class << self
+      # Builds a new configuration
+      #
+      # @yieldparam config [Configuration] the configuration to customize
+      # @return [Configuration] the built configuration
+      def build
+        config = new
+        yield config
+        config
+      end
+
+      # @return [Configuration] the current configuration
+      def current
+        @current ||= new
+      end
+
+      # Expands relative paths against a root
+      #
+      # @param root [Pathname, String] the root for relative paths
+      # @param paths [Array<String>] paths to expand
+      # @return [Array<String>] absolute paths
+      def expand_paths(root, paths)
+        paths.map do |path|
+          File.absolute_path?(path) ? path : File.join(root, path)
+        end
+      end
+
+      # Builds a modified copy of the current configuration
+      #
+      # @yieldparam config [Configuration] a copy of the current configuration
+      # @return [Configuration] the modified configuration
+      def modify
+        config = current.dup
+        yield config
+        config
+      end
+
+      # Runs a block with a temporary configuration
+      #
+      # @param config [Configuration] the configuration to use
+      # @yield run a block in which the given configuration is the current one
+      # @return [Object] the block's return value
+      def override(config)
+        previous = @current
+        @current = config
+
+        yield
+      ensure
+        @current = previous
+      end
+    end
+
+    # @!attribute [w] cache
+    #   @param value [ActiveSupport::Cache::Store]
+    attr_writer :cache
+
+    # @!attribute [rw] cache_namespace
+    #   @return [String] a global prefix for cache keys
+    attr_accessor :cache_namespace
+
+    # @!attribute [rw] directories
+    #   @return [Array<String>] absolute paths to directories containing value classes
+    attr_accessor :directories
+
+    # @!attribute [rw] warming_queue
+    #   @return [Symbol] the queue for the warming job
+    attr_accessor :warming_queue
+
+    # Creates a configuration
+    def initialize
+      @cache_namespace = "pennycress"
+      @directories = []
+      @warming_queue = :default
+    end
+
+    # @return [ActiveSupport::Cache::Store] the cache store to use
+    def cache
+      @cache ||= ActiveSupport::Cache::NullStore.new
+    end
+
+  protected
+
+    # @param original [Configuration] the configuration to copy
+    def initialize_copy(original)
+      @cache = original.instance_variable_get(:@cache)
+      @cache_namespace = original.cache_namespace.dup
+      @directories = original.directories.dup
+      @warming_queue = original.warming_queue
+    end
+  end
+end

data/lib/pennycress/constraints.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pennycress
+  # This module provides a collection of helpers for enforcing constraints on
+  # user-facing classes.
+  module Constraints
+    # Raises an error stating that the named method is required
+    #
+    # @param name [Symbol] the name of the method
+    # @raise [NotImplementedError]
+    def require_method(name)
+      raise NotImplementedError, "#{self.class} must implement ##{name}"
+    end
+  end
+end

data/lib/pennycress/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Pennycress
+  class Error < StandardError; end
+  class ValidationError < Error; end
+end

data/lib/pennycress/input.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "model_reference"
+require_relative "models"
+require_relative "schema"
+
+module Pennycress
+  # An input describes a value's model inputs.
+  class Input
+    # @return [Array<Symbol>] the IDs of the models used by the value
+    attr_reader :model_ids
+
+    # Creates an input schema for a value
+    #
+    # @param model_ids [Array<Symbol>] model IDs (e.g., `:uploaded_file, :user`)
+    # @raise [ArgumentError] if model IDs are missing or invalid
+    def initialize(*model_ids)
+      raise ArgumentError, "model IDs are required" if model_ids.empty?
+      raise ArgumentError, "model IDs must be symbols" unless model_ids.all?(Symbol)
+
+      @model_ids = model_ids.uniq.sort
+    end
+
+    # Validates an input against the schema
+    #
+    # @param input [Object] user-provided input
+    # @return [Hash] an input that conforms to the schema
+    # @raise [ValidationError] if the input is invalid
+    def validate(input)
+      Schema.validate_shape(schema, input) do |key, value|
+        ModelReference.from(schema[key], value, label: key.to_s)
+      end
+    end
+
+  private
+
+    # @return [Hash{Symbol => Class}] a mapping of IDs to model classes
+    def schema
+      @schema ||= model_ids.to_h do |id|
+        [id, Pennycress::Models.resolve(id)]
+      end
+    end
+  end
+end