pennycress 0.0.1

data/lib/pennycress/integration.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "registry"
+
+module Pennycress
+  # This module integrates Pennycress with a Rails application.
+  module Integration
+    # This module is a concern included on watched models that adds a
+    # post-commit hook to trigger invalidation.
+    module ModelCommitHandler
+      extend ActiveSupport::Concern
+
+      included do
+        after_commit do
+          Integration.handle_commit(self)
+        end
+      end
+    end
+
+    class << self
+      # Respond to a commit on a watched model
+      #
+      # @param record [ActiveRecord::Base] a committed model instance
+      # @return [void]
+      def handle_commit(record)
+        action = commit_action(record)
+
+        model_handlers[record.class].each do |handler|
+          handler.call(record, action)
+        end
+      end
+
+      # Search for value files in the given directories
+      #
+      # The directories should contain Value definitions.  When loaded, these
+      # definitions will be added to the value registry.
+      #
+      # @param directories [Array<String>] absolute directory paths
+      # @return [void]
+      # @raise [ArgumentError] if a path is not a directory
+      def load_values(directories)
+        directories.each do |directory|
+          unless File.directory?(directory)
+            raise ArgumentError, "path is not a directory: #{directory}"
+          end
+
+          Dir
+            .glob(File.join(directory, "**", "*.rb"))
+            .sort
+            .each { |file| load file }
+        end
+      end
+
+      # Add callbacks to all watched models
+      #
+      # @return [void]
+      def watch_models
+        model_handlers.clear
+
+        Registry.current.values.each do |value_class|
+          value_class.config.watches.each do |watch|
+            model_handlers[watch.model_class] << lambda do |record, action|
+              if watch.on.include?(action)
+                value_class.invalidate_model(watch, record)
+              end
+            end
+          end
+        end
+
+        model_handlers.each_key do |model|
+          unless model.include?(ModelCommitHandler)
+            model.include(ModelCommitHandler)
+          end
+        end
+      end
+
+    private
+
+      # @param record [ActiveRecord::Base] a committed model instance
+      # @return [Symbol] the commit action that triggered the callback
+      def commit_action(record)
+        if record.destroyed?
+          :destroy
+        elsif record.previously_new_record?
+          :create
+        else
+          :update
+        end
+      end
+
+      # @return [Hash{Class => Array<Proc>}] a mapping of model classes to invalidation handlers
+      def model_handlers
+        @model_handlers ||= Hash.new do |hash, key|
+          hash[key] = []
+        end
+      end
+    end
+  end
+end

data/lib/pennycress/model_reference.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Pennycress
+  # A model reference is a description of a model that can use either a model
+  # instance or its primary key.
+  class ModelReference
+    # @return [Object] the model's scalar or composite primary key
+    attr_reader :id
+
+    # @return [ActiveRecord::Base] the referenced ActiveRecord model class
+    attr_reader :model_class
+
+    class << self
+      # @param model_class [ActiveRecord::Base] a model class
+      # @param value [Object] a model instance or primary key value
+      # @param label [String] the input label used in error messages
+      # @return [ModelReference]
+      # @raise [ValidationError] if the value is invalid
+      def from(model_class, value, label:)
+        result =
+          if value.is_a?(model_class)
+            from_instance(model_class, value)
+          elsif model_class.composite_primary_key?
+            from_composite_key(model_class, value)
+          else
+            from_scalar_key(model_class, value)
+          end
+
+        raise ValidationError, "#{label} #{result}" if result.is_a?(String)
+
+        result
+      end
+
+    private
+
+      # @param model_class [ActiveRecord::Base]
+      # @param value [Object]
+      # @return [ModelReference, String]
+      def from_composite_key(model_class, value)
+        length = model_class.primary_key.length
+
+        unless value.is_a?(Array)
+          return "must be a #{model_class.name} or an array of #{length} key values"
+        end
+
+        if value.length != length
+          "must have #{length} primary key values, got #{value.length}"
+        elsif value.any? { |item| !scalar_key?(item) }
+          "primary keys must use scalar values"
+        else
+          new(id: value, model_class: model_class)
+        end
+      end
+
+      # @param model_class [ActiveRecord::Base]
+      # @param instance [ActiveRecord::Base]
+      # @return [ModelReference, String]
+      def from_instance(model_class, instance)
+        id =
+          begin
+            instance.id
+          rescue NoMethodError
+            nil
+          end
+
+        if id.nil? || (instance.respond_to?(:new_record?) && instance.new_record?)
+          return "must be persisted"
+        end
+
+        new(id: id, model_class: model_class, record: instance)
+      end
+
+      # @param model_class [ActiveRecord::Base]
+      # @param value [Object]
+      # @return [ModelReference, String]
+      def from_scalar_key(model_class, value)
+        if scalar_key?(value)
+          new(id: value, model_class: model_class)
+        else
+          "must be a #{model_class.name} or a primary key value: #{value.inspect}"
+        end
+      end
+
+      # @param value [Object]
+      # @return [Boolean]
+      def scalar_key?(value)
+        !value.nil? && !value.is_a?(Array) && !value.is_a?(Hash)
+      end
+    end
+
+    # Creates a model reference
+    #
+    # @param id [Object] the model's scalar or composite primary key
+    # @param model_class [Class] the referenced ActiveRecord model class
+    # @param record [ActiveRecord::Base, nil] a loaded record, when one is available
+    def initialize(id:, model_class:, record: nil)
+      @id = id
+      @model_class = model_class
+      @record = record
+    end
+
+    # @return [Array<String>] cache key segments for this reference's ID
+    def cache_key
+      Array(id).map(&:to_s)
+    end
+
+    # @return [ActiveRecord::Base] the referenced model instance
+    def record
+      @record ||= model_class.find(id)
+    end
+  end
+end

data/lib/pennycress/models.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/core_ext/string/inflections"
+
+require_relative "errors"
+
+module Pennycress
+  # This module contains helpers for working with references to ActiveRecord
+  # models that follow Rails naming conventions like `:uploaded_file`.
+  module Models
+    # Resolves a model ID to a class
+    #
+    # @param id [Symbol] a model ID (e.g., `:uploaded_file`)
+    # @return [ActiveRecord::Base] the model class
+    # @raise [ValidationError] if the model ID cannot be resolved
+    # @raise [ValidationError] if the resolved class is not a model
+    def self.resolve(id)
+      begin
+        model = id.to_s.classify.constantize
+      rescue NameError => e
+        raise ValidationError, "unknown model #{id.inspect}", cause: e
+      end
+
+      unless model < ActiveRecord::Base
+        raise ValidationError, "#{model.name} is not an ActiveRecord model"
+      end
+
+      model
+    end
+  end
+end

data/lib/pennycress/output.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "schema"
+
+module Pennycress
+  # An output describes the type or shape of a value's computed result.
+  class Output
+    # Creates a description of a value's output
+    #
+    # @param schema [Class, Hash{Symbol => Class}] a scalar type or shape hash
+    # @raise [ArgumentError] if the schema is invalid
+    def initialize(schema)
+      if schema.is_a?(Class)
+        @type = schema
+      elsif schema.is_a?(Hash)
+        @shape = schema
+      else
+        raise ArgumentError, "output must be a type or a shape hash"
+      end
+    end
+
+    # Validates a computed result against the output's schema
+    #
+    # @param value [Object] a computed result
+    # @return [Object] a value that conforms to the schema
+    # @raise [ValidationError] if the value is invalid
+    def validate(value)
+      if @type
+        Schema.validate_type(@type, value)
+      else
+        Schema.validate_shape(@shape, value)
+      end
+    end
+  end
+end

data/lib/pennycress/output_reference.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "caching"
+require_relative "model_reference"
+
+module Pennycress
+  # An output reference identifies a cached output for a computed value produced
+  # from a single input.
+  class OutputReference
+    # Creates an output reference
+    #
+    # @param input [Hash] a validated input
+    # @param namespace [String, nil] a namespace that contains the value's outputs
+    def initialize(input:, namespace: nil)
+      @raw_input = input
+      @namespace = namespace
+    end
+
+    # @return [String] the cache key for this reference
+    def cache_key
+      @cache_key ||= Caching.key(@namespace, *input_key_segments)
+    end
+
+    # @return [Hash] the input in a form suitable for computing an output value
+    def input
+      @input ||= @raw_input.transform_values do |value|
+        value.is_a?(ModelReference) ? value.record : value
+      end
+    end
+
+  private
+
+    # @return [Array<String>] segments in the cache key for the input
+    def input_key_segments
+      @raw_input.keys.sort.flat_map do |key|
+        value = @raw_input[key]
+        next [] unless value
+
+        value.cache_key.map(&:downcase)
+      end
+    end
+  end
+end

data/lib/pennycress/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "configuration"
+require_relative "integration"
+require_relative "registry"
+
+module Pennycress
+  # This Railtie integrates Pennycress with Rails.
+  class Railtie < ::Rails::Railtie
+    DEFAULT_DIRECTORIES = ["app/values"].freeze
+    private_constant :DEFAULT_DIRECTORIES
+
+    config.to_prepare do
+      Registry.current.reset
+      Integration.load_values(Configuration.current.directories)
+      Integration.watch_models
+    end
+
+    initializer "pennycress.setup", before: :load_config_initializers do
+      Configuration.current.cache = Rails.cache
+    end
+
+    initializer "pennycress.expand_directories", after: :load_config_initializers do
+      configuration = Configuration.current
+
+      configuration.directories = Configuration.expand_paths(
+        Rails.root,
+        configuration.directories.empty? ? DEFAULT_DIRECTORIES : configuration.directories
+      )
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/pennycress.rake", __dir__)
+    end
+  end
+end

data/lib/pennycress/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Pennycress
+  # A registry tracks value classes registered at load time.
+  class Registry
+    class << self
+      # @return [Registry] the current registry
+      def current
+        @current ||= new
+      end
+
+      # Runs a block with a temporary registry
+      #
+      # @param registry [Registry] the registry to use
+      # @yield run a block in which the given registry is the current one
+      # @return [Object] the block's return value
+      def override(registry)
+        previous = @current
+        @current = registry
+
+        yield
+      ensure
+        @current = previous
+      end
+    end
+
+    # Creates a registry
+    def initialize
+      @values = []
+    end
+
+    # @param value [Value] a value class
+    # @return [void]
+    def register(value)
+      @values << value
+    end
+
+    # Clears registered value classes
+    #
+    # @return [void]
+    def reset
+      @values = []
+    end
+
+    # @return [Array<Value>] registered value classes
+    def values
+      @values
+    end
+  end
+end

data/lib/pennycress/schema.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Pennycress
+  # This module provides a collection of helpers for validating user-provided
+  # values against type and shape constraints.
+  module Schema
+    class << self
+      # Ensures that a value conforms to a given shape
+      #
+      # When a block is given, it is called for each shaped field with the key
+      # and value.  The block may return a normalized value or raise
+      # {ValidationError} for an invalid field.
+      #
+      # @param shape [Hash{Symbol => Class}] the shape to validate against
+      # @param value [Object] the value to validate
+      # @yieldparam key [Symbol] a shaped field key
+      # @yieldparam item [Object] the field value
+      # @yieldreturn [Object] a normalized field value
+      # @return [Hash] the input value, or normalized values when a block is given
+      # @raise [ValidationError] if the value is invalid
+      def validate_shape(shape, value)
+        unless value.is_a?(Hash)
+          raise ValidationError, "value is not a hash: #{value.inspect}"
+        end
+
+        errors = shape.keys.filter_map do |key|
+          "missing key: #{key}" unless value.key?(key)
+        end
+
+        normalized = {}
+
+        errors += value.filter_map do |key, item|
+          if shape.key?(key)
+            if block_given?
+              begin
+                normalized[key] = yield(key, item)
+                nil
+              rescue ValidationError => e
+                e.message
+              end
+            else
+              check_type(shape[key], item, label: key.to_s)
+            end
+          else
+            "unknown key: #{key}"
+          end
+        end
+
+        unless errors.empty?
+          raise ValidationError, errors.sort.join("\n")
+        end
+
+        block_given? ? normalized : value
+      end
+
+      # Ensures that a value is an instance of a type
+      #
+      # @param type [Class] the type to validate against
+      # @param value [Object] the value to validate
+      # @param label [String] a custom label for the value
+      # @return [Object] an instance of the type
+      # @raise [ValidationError] if the value is invalid
+      def validate_type(type, value, label: "value")
+        error = check_type(type, value, label: label)
+
+        raise ValidationError, error if error
+
+        value
+      end
+
+    private
+
+      # Produces an error message if a value is not a given type
+      #
+      # @param type [Class] the type to validate against
+      # @param value [Object] the value to validate
+      # @param label [String] a custom label for the value
+      # @return [String, nil] an error message if the value is not a given type
+      def check_type(type, value, label:)
+        return if value.is_a?(type)
+
+        "#{label} is not an instance of #{type.name}: #{value.inspect}"
+      end
+    end
+  end
+end