pennycress 0.0.1

data/lib/pennycress/value.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require_relative "cache"
+require_relative "caching"
+require_relative "configuration"
+require_relative "constraints"
+require_relative "input"
+require_relative "output"
+require_relative "output_reference"
+require_relative "registry"
+require_relative "value_config"
+require_relative "watched_model"
+
+module Pennycress
+  # A value describes a computation performed for each distinct input.  After
+  # the initial value is computed, it is cached and reused until an invalidation
+  # condition is met.
+  class Value
+    include Constraints
+
+    class << self
+      # @param value [Class] the value being defined
+      # @return [void]
+      def inherited(value)
+        super
+        Registry.current.register(value)
+      end
+
+      # @return [ValueConfig] the value's configuration
+      def config
+        @config ||= ValueConfig.new
+      end
+
+      # Evicts cached outputs for the given inputs
+      #
+      # @param inputs [Enumerable<Hash>] a list of keyword arguments for inputs
+      # @return [void]
+      # @raise [ValidationError] if any inputs are invalid
+      def evict_many(inputs)
+        evict = inputs
+          .map { |input| reference(input) }
+          .to_a
+
+        cache.evict_many(evict)
+      end
+
+      # Computes an output value for the given input
+      #
+      # @param inspect_reference [Proc, nil] expose the output reference used for retrieval
+      # @param input [Hash] keyword arguments that should conform to the input schema
+      # @return [Object] the output value
+      # @raise [ValidationError] if the input is invalid
+      def fetch(inspect_reference: nil, **input)
+        ref = reference(input)
+        inspect_reference&.call(ref)
+
+        cache.fetch(ref) do
+          new.send(:fetch, **ref.input)
+        end
+      end
+
+      # Computes an output value for each input in an enumerable
+      #
+      # @param inputs [Enumerable<Hash>] a list of keyword arguments for inputs
+      # @return [Array<Object>] output values
+      # @raise [ValidationError] if any inputs or outputs are invalid
+      def fetch_many(inputs)
+        new.send(:fetch_many, cache, inputs).to_a
+      end
+
+      # Defines the value's input schema
+      #
+      # @param model_ids [Array<Symbol>] model IDs (e.g., `:uploaded_file, :user`)
+      # @return [void]
+      def input(*model_ids)
+        config.input = Input.new(*model_ids)
+      end
+
+      # Invalidate cached outputs for a watched model
+      #
+      # @param watch [WatchedModel] the watch that produced the change
+      # @param model [ActiveRecord::Base] the changed model instance
+      # @return [void]
+      def invalidate_model(watch, model)
+        evict_many(watch.inputs_for(model))
+      end
+
+      # Defines the value's output schema
+      #
+      # @param schema [Class, Hash{Symbol => Class}] a scalar type or shape hash
+      # @return [void]
+      # @raise [ArgumentError] if the schema is invalid
+      def output(schema)
+        config.output = Output.new(schema)
+      end
+
+      # Clears memoized cache bindings
+      #
+      # @return [void]
+      def reset_cache
+        @cache = nil
+      end
+
+      # Defines or returns the value's seeds
+      #
+      # @yieldreturn [Enumerable<Object>] a list of seeds to warm
+      # @return [Enumerable<Object>] the defined seeds, when called without a block
+      def seeds(&block)
+        if block
+          config.seeds = block
+        else
+          class_eval(&config.seeds)
+        end
+      end
+
+      # Registers a watch on a model
+      #
+      # @param id [Symbol] the model ID to watch (e.g., `:discussion`)
+      # @param on [Array<Symbol>] commit actions that trigger invalidation
+      # @yieldparam model [ActiveRecord::Base] the changed model instance
+      # @yieldreturn [Enumerable<Hash>] inputs to refresh
+      # @return [void]
+      def watch(id, on: WatchedModel::ACTIONS, &inputs)
+        config.watches << WatchedModel.new(id, on: on, &inputs)
+      end
+
+      # Warms the cache for each seed
+      #
+      # @return [void]
+      def warm
+        value = new
+        seeds.each { |seed| value.warm_seed(seed) }
+      end
+
+    private
+
+      # @return [Cache] the value's cache
+      def cache
+        @cache ||= Cache.new(Configuration.current.cache)
+      end
+
+      # @return [String] the value's cache namespace
+      def cache_namespace
+        @cache_namespace ||= if name
+          name.split("::").map(&:downcase).join("/")
+        else
+          ""
+        end
+      end
+
+      # Builds an output reference for the given input
+      #
+      # @param input [Hash] keyword arguments that should conform to the input schema
+      # @return [OutputReference] a reference to the cached output
+      # @raise [ValidationError] if the input is invalid
+      def reference(input)
+        validated = config.input.validate(input)
+
+        namespace = Caching.key(
+          Configuration.current.cache_namespace,
+          cache_namespace
+        )
+
+        OutputReference.new(
+          input: validated,
+          namespace: namespace.empty? ? nil : namespace
+        )
+      end
+    end
+
+    # Computes an output value for a valid input
+    #
+    # @return [Object]
+    # @api value
+    def compute(*)
+      require_method(:compute)
+    end
+
+    # Computes output values for each input in an enumerable
+    #
+    # @param inputs [Enumerable<Hash>] a list of valid inputs
+    # @return [Enumerable<Object>] output values
+    # @api value
+    def compute_many(inputs)
+      inputs.map do |input|
+        compute(**input)
+      end
+    end
+
+    # Converts a seed to a list of inputs
+    #
+    # @return [Enumerable<Hash>]
+    # @api value
+    def seed_to_inputs(*)
+      require_method(:seed_to_inputs)
+    end
+
+    # Warms the cache for a seed
+    #
+    # @param seed [Object]
+    # @return [void]
+    def warm_seed(seed)
+      self.class.send(:fetch_many, seed_to_inputs(seed)).each { nil }
+    end
+
+  private
+
+    # Computes an output value for a valid input
+    #
+    # @param input [Hash] a valid input
+    # @return [Object] the output value
+    def fetch(**input)
+      output.validate(compute(**input))
+    end
+
+    # Computes an output value for each input in an enumerable
+    #
+    # @param cache [Cache]
+    # @param inputs [Enumerable<Hash>] inputs to validate and compute
+    # @return [Array<Object>] output values
+    def fetch_many(cache, inputs)
+      refs = inputs
+        .map { |input| self.class.send(:reference, input) }
+        .to_a
+
+      misses = []
+
+      values = cache.fetch_multi(refs) do |ref|
+        misses << ref
+        nil
+      end
+
+      return values if misses.empty?
+
+      inputs = misses.map(&:input)
+      results = compute_many(inputs).to_a
+
+      if results.length != inputs.length
+        raise ValidationError,
+              "compute_many must return one output per input: got #{results.length}, expected #{inputs.length}"
+      end
+
+      computed = results.map do |result|
+        output.validate(result)
+      end
+
+      cache.write_multi(misses.zip(computed).to_h)
+
+      index = 0
+
+      values.map do |value|
+        if value.nil?
+          computed[index].tap { index += 1 }
+        else
+          value
+        end
+      end
+    end
+
+    # @return [Output] the value's output schema
+    def output
+      @output ||= self.class.config.output
+    end
+  end
+end

data/lib/pennycress/value_config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "input"
+require_relative "output"
+require_relative "watched_model"
+
+module Pennycress
+  # A value config holds data describing how a value behaves.
+  class ValueConfig
+    # @!attribute [w] input
+    #   @param value [Input]
+    attr_writer :input
+
+    # @!attribute [w] output
+    #   @param value [Output]
+    attr_writer :output
+
+    # @!attribute [w] seeds
+    #   @param value [Proc]
+    attr_writer :seeds
+
+    # @return [Input] the schema for the value's input
+    # @raise [ValidationError] if a schema is incomplete
+    def input
+      raise ValidationError, "input is not defined" if @input.nil?
+
+      @input
+    end
+
+    # @return [Output] the schema for the value's output
+    # @raise [ValidationError] if a schema is not defined
+    def output
+      raise ValidationError, "output is not defined" if @output.nil?
+
+      @output
+    end
+
+    # @return [Proc] a block that defines the list of seeds
+    def seeds
+      @seeds ||= proc { [] }
+    end
+
+    # @return [Array<WatchedModel>] watches registered for the value
+    def watches
+      @watches ||= []
+    end
+  end
+end

data/lib/pennycress/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pennycress
+  VERSION = "0.0.1"
+end

data/lib/pennycress/warm_seed_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+require_relative "configuration"
+
+module Pennycress
+  # This job warms cached outputs for one value seed.
+  class WarmSeedJob < ActiveJob::Base
+    queue_as { Configuration.current.warming_queue }
+
+    # @param value_class_name [String] the value class to warm
+    # @param seed [Object] the seed to warm
+    # @return [void]
+    def perform(value_class_name, seed)
+      value_class_name.constantize.new.warm_seed(seed)
+    end
+  end
+end

data/lib/pennycress/warming.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require_relative "warm_seed_job"
+
+module Pennycress
+  # This module orchestrates cache warming for registered value classes.
+  module Warming
+    # Warms cached outputs for each registered value seed
+    #
+    # @param async [Boolean] whether to warm the cache via jobs or synchronous operations
+    # @return [void]
+    # @raise [ArgumentError] if a value class has no name
+    def self.warm_cache(async: true)
+      method = async ? :perform_later : :perform_now
+
+      Registry.current.values.each do |value_class|
+        value_class.seeds.each do |seed|
+          name = value_class.name
+
+          unless name
+            raise ArgumentError, "value class must have a name"
+          end
+
+          WarmSeedJob.send(method, name, seed)
+        end
+      end
+    end
+  end
+end

data/lib/pennycress/watched_model.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "models"
+
+module Pennycress
+  # A watched model describes a model observed by a value.  When the model
+  # changes, a value has the chance to selectively invalidate itself by deriving
+  # inputs from the changed model.
+  class WatchedModel
+    # Commit actions a watch can respond to
+    ACTIONS = %i[create destroy update].freeze
+
+    # @return [Symbol] the ID of the watched model
+    attr_reader :id
+
+    # @return [Proc] a block that maps a model to inputs
+    attr_reader :inputs
+
+    # @return [Array<Symbol>] commit actions that trigger invalidation
+    attr_reader :on
+
+    # Creates a watched model
+    #
+    # @param id [Symbol] the ID of the model to watch
+    # @param on [Array<Symbol>] commit actions that trigger invalidation
+    # @yieldparam model [ActiveRecord::Base] the changed model instance
+    # @yieldreturn [Enumerable<Hash>] inputs to refresh
+    # @raise [ArgumentError] if the commit actions are invalid
+    def initialize(id, on: ACTIONS, &inputs)
+      @id = id
+      @inputs = inputs
+      @on = validate_actions(on)
+    end
+
+    # Produces invalidation inputs for a given model
+    #
+    # @param model [ActiveRecord::Base] a changed model instance
+    # @return [Enumerable<Hash>] invalidation inputs
+    def inputs_for(model)
+      inputs.call(model)
+    end
+
+    # @return [Class] the watched ActiveRecord model class
+    def model_class
+      @model_class ||= Models.resolve(id)
+    end
+
+  private
+
+    # Validates commit actions
+    #
+    # @param actions [Array<Symbol>]
+    # @return [Array<Symbol>] valid commit actions
+    def validate_actions(actions)
+      if actions.empty?
+        raise ArgumentError, "commit actions cannot be empty"
+      end
+
+      unknown = actions - ACTIONS
+
+      unless unknown.empty?
+        raise ArgumentError, "unsupported commit actions: #{unknown.map(&:inspect).join(', ')}"
+      end
+
+      actions.uniq.sort
+    end
+  end
+end

data/lib/pennycress.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "pennycress/configuration"
+require_relative "pennycress/value"
+require_relative "pennycress/version"
+require_relative "pennycress/warming"
+
+require_relative "pennycress/railtie" if defined?(Rails::Railtie)
+
+# Pennycress allows Rails apps to precompute and cache expensive logic, with
+# fine-grained invalidation and support for targeted cache warming.
+module Pennycress
+  class << self
+    # Configures Pennycress
+    #
+    # @yieldparam config [Configuration] the current configuration
+    # @return [void]
+    def configure
+      yield Configuration.current
+    end
+
+    # Warms cached outputs for each registered value seed
+    #
+    # @param async [Boolean] whether to warm the cache via jobs or synchronous operations
+    # @return [void]
+    def warm_cache(async: true)
+      Warming.warm_cache(async: async)
+    end
+  end
+end

data/lib/tasks/pennycress.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :pennycress do
+  desc "Warm the cache for all values that define seeds"
+  task warm_cache: :environment do
+    Pennycress.warm_cache
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: pennycress
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Justin Locsei
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: Pennycress allows Rails apps to precompute and cache expensive logic,
+  with fine-grained invalidation and support for targeted cache warming.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/pennycress.rb
+- lib/pennycress/cache.rb
+- lib/pennycress/caching.rb
+- lib/pennycress/configuration.rb
+- lib/pennycress/constraints.rb
+- lib/pennycress/errors.rb
+- lib/pennycress/input.rb
+- lib/pennycress/integration.rb
+- lib/pennycress/model_reference.rb
+- lib/pennycress/models.rb
+- lib/pennycress/output.rb
+- lib/pennycress/output_reference.rb
+- lib/pennycress/railtie.rb
+- lib/pennycress/registry.rb
+- lib/pennycress/schema.rb
+- lib/pennycress/value.rb
+- lib/pennycress/value_config.rb
+- lib/pennycress/version.rb
+- lib/pennycress/warm_seed_job.rb
+- lib/pennycress/warming.rb
+- lib/pennycress/watched_model.rb
+- lib/tasks/pennycress.rake
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Memoized domain values for Rails
+test_files: []