thunderframe 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9c6e4b83f0233fc6d8f91d1e5a5285f16136964d2837753b76dd8a0dc1be928
+  data.tar.gz: c28f8d42fa7db56fd8f7e78b771820ca8e4869d3d3d7e5e3c86acfcdcf03306f
+SHA512:
+  metadata.gz: 61cd9d6e6956b6d873425c6b8e7ede0d8f6338066772396da1a3e328c5369ed44fa9ea964a98cc199bc255712e033aa254f19e85538a46ec950dbdcde6744aae
+  data.tar.gz: cb16f8a545735240c5a947e98d930c3ea9d5726b41bd5007a8434568ca73a9126c08a26df790297aac6f4f3364510e314f333bbfb1c4419345e1b2da75d87546

data/README.md

@@ -0,0 +1,3 @@
+# thunderframe
+
+Declares the shape of a result (`field`, `association`, `condition`) and renders entities into immutable `Data`.

data/lib/thunderframe/association.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ThunderFrame
+  class Association
+    attr_reader :name, :frame, :options
+
+    def initialize(name, frame, options)
+      @name = name
+      @frame = frame
+      @options = options
+    end
+
+    def relation_name
+      final_name = options[:as] || name
+      final_name = options[:eager_loads] if options[:eager_loads].is_a?(String) || options[:eager_loads].is_a?(Symbol)
+
+      final_name.to_sym
+    end
+
+    def render(entity, context)
+      frame.render_hash(value(entity, context), context:)
+    end
+
+    # A callable `from` is not an association name, so it cannot be preloaded by itself: in that case only an
+    # explicit `eager_loads` says what to preload, and without it nothing is preloaded.
+    def preload_key
+      return options[:from] || relation_name unless options[:from].respond_to?(:call)
+
+      relation_name if options[:eager_loads].is_a?(String) || options[:eager_loads].is_a?(Symbol)
+    end
+
+    def prepare_preload
+      @prepare_preload ||= begin
+        below_preloads = frame.prepare_preload
+
+        {}.tap do |hash|
+          hash[preload_key] = below_preloads if preload_key && (below_preloads.any? || options[:eager_loads])
+        end
+      end
+    end
+
+    private
+
+    def value(entity, context)
+      from = options[:from] || name
+      return from.arity == 2 ? from.call(entity, context) : from.call(entity) if from.respond_to?(:call)
+
+      entity.is_a?(Hash) ? entity[from] || entity[from.to_s] : entity.public_send(from)
+    end
+  end
+end

data/lib/thunderframe/condition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ThunderFrame
+  class Condition
+    attr_reader :test, :frame
+
+    def initialize(test, frame)
+      @test = test
+      @frame = frame
+    end
+
+    def applies?(entity)
+      case test
+      when Class then entity.is_a?(test)
+      when Symbol then entity.public_send(test)
+      else test.call(entity)
+      end
+    end
+
+    def prepare_preload
+      @prepare_preload ||= begin
+        below_preloads = frame.prepare_preload
+
+        {}.tap do |hash|
+          hash[test] = below_preloads if below_preloads.any? && test.is_a?(Class)
+        end
+      end
+    end
+  end
+end

data/lib/thunderframe/field.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ThunderFrame
+  class Field
+    attr_reader :name, :codec, :options, :block
+
+    def initialize(name, codec, options, block)
+      @name = name
+      @codec = codec
+      @options = options
+      @block = block
+    end
+
+    def relation_name
+      final_name = options[:as] || name
+      final_name = options[:eager_loads] if options[:eager_loads].is_a?(String) || options[:eager_loads].is_a?(Symbol)
+
+      final_name.to_sym
+    end
+
+    def prepare_preload
+      eager = options[:eager_loads]
+      return {} unless eager
+      return eager if eager.is_a?(Hash)
+
+      { relation_name => {} }
+    end
+
+    def extract(entity, context, label)
+      value = read(entity, context)
+      codec.coerce(value)
+    rescue ArgumentError
+      raise Error, "#{label}: #{name} must be #{codec.name}, got #{value.class} (#{value.inspect})"
+    end
+
+    private
+
+    def read(entity, context)
+      return block.arity == 2 ? block.call(entity, context) : block.call(entity) if block
+
+      source = options[:from] || name
+      return entity.public_send(source) unless entity.is_a?(Hash)
+
+      entity.key?(source) ? entity[source] : entity[source.to_s]
+    end
+  end
+end

data/lib/thunderframe/frame.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module ThunderFrame
+  class Frame
+    attr_reader :associations, :conditions
+
+    def initialize(const_name, owner:, parent: nil, &block)
+      @const_name = const_name
+      @owner = owner
+      @parent = parent
+      @fields = []
+      @associations = []
+      @conditions = []
+      instance_exec(&block) if block
+    end
+
+    def fields(*names)
+      return @fields if names.empty?
+
+      names.each { |name| field(name) }
+    end
+
+    def field(name, type = String, **options, &block)
+      check_name!(name)
+      @fields << Field.new(name.to_sym, ThunderFoundation::Types.fetch(type), options, block)
+    end
+
+    def association(name, **options, &block)
+      check_name!(name)
+      @associations << Association.new(name.to_sym, nested(name, &block), options)
+    end
+
+    def condition(test, &block)
+      @conditions << Condition.new(test, nested("Condition#{@conditions.size + 1}", &block))
+    end
+
+    def members
+      fields.map(&:name) + associations.map(&:name) + conditions.flat_map { |condition| condition.frame.members }
+    end
+
+    # A Hash responds to each, but it is an entity and not a collection of entities; a Struct too.
+    def render_hash(entity, context: nil, skip_preload: false)
+      return if entity.nil?
+      return render_many_hash(entity, context:, skip_preload:) if collection?(entity)
+
+      hash = {}
+      fields.each { |field| hash[field.name] = field.extract(entity, context, label) }
+      associations.each { |association| hash[association.name] = association.render(entity, context) }
+      conditions.each { |condition| hash.merge!(condition.frame.render_hash(entity, context:)) if condition.applies?(entity) }
+      hash
+    end
+
+    # render_hash for a Hash that must have exactly the declared shape: a key the frame does not declare, or a declared
+    # field or association left out, raises Error. Associations are checked the same way, item by item when they hold
+    # a list. A field or association declared with `optional: true`, and the fields of a condition, may be left out.
+    def render_hash!(entity, context: nil)
+      return if entity.nil?
+      return entity.map { |item| render_hash!(item, context:) } if entity.is_a?(Array)
+      raise Error, "#{label} must be a Hash, got #{entity.class}" unless entity.is_a?(Hash)
+
+      keys = entity.keys.map(&:to_sym)
+      declared = fields + associations
+      required = declared.reject { |member| member.options[:optional] }.map(&:name)
+      allowed = declared.map(&:name) + conditions.flat_map { |condition| condition.frame.members }
+      unknown = keys - allowed
+      missing = required - keys
+
+      errors = []
+      errors << "unknown #{unknown.join(', ')}" if unknown.any?
+      errors << "missing #{missing.join(', ')}" if missing.any?
+      raise Error, "#{label}: #{errors.join('; ')}" if errors.any?
+
+      hash = {}
+      fields.each { |field| hash[field.name] = field.extract(entity, context, label) }
+      associations.each do |association|
+        value = entity.key?(association.name) ? entity[association.name] : entity[association.name.to_s]
+        hash[association.name] = association.frame.render_hash!(value, context:)
+      end
+      conditions.each { |condition| hash.merge!(condition.frame.render_hash(entity, context:)) if condition.applies?(entity) }
+      hash
+    end
+
+    # Only records of ActiveRecord are preloaded; a collection of anything else is rendered as it is.
+    def render_many_hash(enumerable, context: nil, skip_preload: false)
+      records = enumerable.to_a
+      Preloader.call(records, prepare_preload) if !skip_preload && defined?(::ActiveRecord::Base) && records.first.is_a?(::ActiveRecord::Base)
+
+      records.map { |entity| render_hash(entity, context:, skip_preload: true) }
+    end
+
+    def render_json(entity, root: :data)
+      { root => render_hash(entity) }.to_json
+    end
+
+    alias render render_json
+
+    def prepare_preload
+      @prepare_preload ||= begin
+        hash = associations.each_with_object({}) { |association, acc| acc.deep_merge!(association.prepare_preload) }
+        hash = fields.each_with_object(hash) { |field, acc| acc.deep_merge!(field.prepare_preload) }
+        conditions.each_with_object(hash) { |condition, acc| acc.deep_merge!(condition.prepare_preload) }
+      end
+    end
+
+    def label
+      @parent ? "#{@parent.label}.#{@const_name.to_s.underscore}" : "#{@owner.name}::#{@const_name}"
+    end
+
+    private
+
+    def nested(name, &block)
+      Frame.new(name, owner: @owner, parent: self, &block)
+    end
+
+    def check_name!(name)
+      raise Error, "#{label}: #{name} declared twice" if members.include?(name.to_sym)
+    end
+
+    def collection?(entity)
+      entity.is_a?(Enumerable) && !entity.is_a?(Hash) && !entity.is_a?(Struct)
+    end
+  end
+end

data/lib/thunderframe/preloader.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Ported from the Framer of tcard_backend (lib/framer/preloader.rb). Preloads the associations of ActiveRecord
+# records, reusing records already loaded instead of querying them again.
+module ThunderFrame
+  class Preloader
+    def self.call(records, association)
+      new.call(records, association)
+    end
+
+    def initialize
+      @available_records = []
+      @cached_record_ids = Hash.new { |h, k| h[k] = Set.new }
+    end
+
+    def call(records, association)
+      records = records.to_a if records.respond_to?(:to_a) && !records.is_a?(Array)
+      return [] if records.empty?
+
+      case association
+      when Symbol, String
+        result = ActiveRecord::Associations::Preloader.new(
+          records:, associations: association, available_records: @available_records
+        ).call
+        cache_preloaded_records(result)
+        result
+      when Hash
+        association.each do |key, value|
+          preloader_result = call(records, key)
+
+          handle_preloader_result(preloader_result, value)
+        end
+      when Array
+        association.each do |value|
+          call(records, value)
+        end
+      end
+    end
+
+    private
+
+    def all_records_from(result)
+      seen = Set.new
+      records = []
+
+      result.records_by_owner.each_value do |owner_records|
+        owner_records.each do |record|
+          next unless seen.add?(record.object_id)
+
+          records << record
+        end
+      end
+
+      return records if records.any?
+
+      result.send(:owners).each do |owner|
+        assoc = owner.association(result.send(:reflection).name)
+        next unless assoc.loaded?
+
+        target = assoc.target
+        targets = target.is_a?(Array) ? target : [target].compact
+        targets.each do |record|
+          next unless seen.add?(record.object_id)
+
+          records << record
+        end
+      end
+
+      records
+    end
+
+    def cache_preloaded_records(preloader_result)
+      preloader_result.each do |result|
+        all_records_from(result).each do |record|
+          key = record.class.base_class.name
+          next if @cached_record_ids[key].include?(record.id)
+
+          @cached_record_ids[key] << record.id
+          @available_records << record
+        end
+      end
+    end
+
+    def resolve_class_key(preloader_result, key)
+      indexed_result = preloader_result.index_by(&:klass)
+
+      return all_records_from(indexed_result[key]) if indexed_result[key]
+
+      parent_result = indexed_result.find { |klass, _| key < klass }&.last
+      return unless parent_result
+
+      all_records_from(parent_result).select { |r| r.is_a?(key) }
+    end
+
+    def handle_preloader_result(preloader_result, association)
+      return unless preloader_result.any?
+
+      case association
+      when Hash
+        association.each do |key, value|
+          if key.is_a?(Class)
+            records = resolve_class_key(preloader_result, key)
+            call(records, value) if records&.any?
+          else
+            preloader_result.each do |result|
+              sub_result = call(all_records_from(result), key)
+
+              handle_preloader_result(sub_result, value) if sub_result&.any?
+            end
+          end
+        end
+      when Array
+        association.each do |value|
+          case value
+          when Hash
+            handle_preloader_result(preloader_result, value)
+          else
+            preloader_result.each do |result|
+              call(all_records_from(result), value)
+            end
+          end
+        end
+      else
+        preloader_result.each do |result|
+          call(all_records_from(result), association)
+        end
+      end
+    end
+  end
+end

data/lib/thunderframe/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ThunderFrame
+  VERSION = '0.2.0'
+end

data/lib/thunderframe.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/hash/deep_merge'
+require 'json'
+require 'thunderfoundation'
+
+require_relative 'thunderframe/version'
+
+module ThunderFrame
+  class Error < StandardError; end
+end
+
+require_relative 'thunderframe/field'
+require_relative 'thunderframe/association'
+require_relative 'thunderframe/condition'
+require_relative 'thunderframe/preloader'
+require_relative 'thunderframe/frame'

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: thunderframe
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Albert Alef
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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'
+- !ruby/object:Gem::Dependency
+  name: thunderfoundation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/thunderframe.rb
+- lib/thunderframe/association.rb
+- lib/thunderframe/condition.rb
+- lib/thunderframe/field.rb
+- lib/thunderframe/frame.rb
+- lib/thunderframe/preloader.rb
+- lib/thunderframe/version.rb
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Declares the shape of a result and renders entities into immutable Data
+test_files: []