computed_model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d4c9e19dfb66454b769cf0cb92e95fb01de3aeace7276953182fcebf82fdcd2
+  data.tar.gz: 836d822953b14420ee7ed6f4dd3d17fba896b41e2caa638eb4fe9e1d59323df5
+SHA512:
+  metadata.gz: e1d34a7a00c560ea97d96927e643d40e02164f94181601e39bcde334cd86f9c5f618c7d6c62556adb5331f2f3f8e61bc015d295f82ee03237d75d4dc8c1d3240
+  data.tar.gz: 556daff44be9ae2408c9e5d11590fecd440d802067071b53563ee6646ca01296bafa01944df8e691bc770f9c7b613a66631cf60cffa5472abb9673b1ef82b95c

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+/Gemfile.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+- 2.7
+- 2.6
+- 2.5
+before_install: gem install bundler -v 2.1.4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Unreleased
+
+## 0.1.0
+
+Initial release.

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in computed_model.gemspec
+gemspec

data/README.md

@@ -0,0 +1,128 @@
+# ComputedModel
+
+ComputedModel is a helper for building a read-only model (sometimes called a view)
+from multiple sources of models.
+It comes with batch loading and dependency resolution for better performance.
+
+It is designed to be universal. It's as easy as pie to pull data from both
+ActiveRecord and remote server (such as ActiveResource).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'computed_model'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install computed_model
+
+## Usage
+
+Include `ComputedModel` in your model class. You may also need an `attr_reader` for the primary key.
+
+```ruby
+class User
+  attr_reader :id
+
+  include ComputedModel
+
+  def initialize(id)
+    @id = id
+  end
+end
+```
+
+They your model class will be able to define the two kinds of special attributes:
+
+- **Loaded attributes** for external data. You define batch loading strategies for loaded attributes.
+- **Computed attributes** for data derived from loaded attributes or other computed attributes.
+  You define a usual `def` with special dependency annotations.
+
+## Loaded attributes
+
+Use `ComputedModel::ClassMethods#define_loader` to define loaded attributes.
+
+```ruby
+# Example: pulling data from ActiveRecord
+define_loader :raw_user do |users, subdeps, **options|
+  user_ids = users.map(&:id)
+  raw_users = RawUser.where(id: user_ids).preload(subdeps).index_by(&:id)
+  users.each do |user|
+    # Even if it doesn't exist, you must explicitly assign nil to the field.
+    user.raw_user = raw_users[user.id]
+  end
+end
+```
+
+The first argument to the block is an array of the model instances.
+The loader's job is to assign something to the corresponding field of each instance.
+
+The second argument to the block is called a "sub-dependency".
+The value of `subdeps` is an array, but further details are up to you
+(it's just a verbatim copy of what you pass to `ComputedModel::ClassMethods#dependency`).
+It's customary to take something ActiveRecord's `preload` accepts.
+
+The keyword arguments are also a verbatim copy of what you pass to `ComputedModel::ClassMethods#bulk_load_and_compute`.
+
+## Computed attributes
+
+Use `ComputedModel::ClassMethods#computed` and `#dependency` to define computed attributes.
+
+```ruby
+dependency raw_user: [:name], user_music_info: [:latest]
+computed def name_with_playing_music
+  if user_music_info.latest&.playing?
+    "#{user.name} (Now playing: #{user_music_info.latest.name})"
+  else
+    user.name
+  end
+end
+```
+
+## Batch loading
+
+Once you defined loaded and computed attributes, you can batch-load them using `ComputedModel::ClassMethods#bulk_load_and_compute`.
+
+Typically you need to create a wrapper for the batch loader like:
+
+```ruby
+def self.list(ids, with:)
+  # Create placeholder objects.
+  objs = ids.map { |id| User.new(id) }
+  # Batch-load attributes into the objects.
+  bulk_load_and_compute(objs, Array(with) + [:raw_user])
+  # Reject objects without primary model.
+  objs.reject! { |u| u.raw_user.nil? }
+  objs
+end
+```
+
+They you can retrieve users with only a specified attributes in a batch:
+
+```ruby
+users = User.list([1, 2, 3], with: [:name, :name_with_playing_music, :premium_user])
+```
+
+## License
+
+This library is distributed under MIT license.
+
+Copyright (c) 2020 Masaki Hara
+Copyright (c) 2020 Wantedly, Inc.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/qnighy/computed_model.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "computed_model"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/computed_model.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "computed_model/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "computed_model"
+  spec.version       = ComputedModel::VERSION
+  spec.authors       = ["Masaki Hara", "Wantedly, Inc."]
+  spec.email         = ["ackie.h.gmai@gmail.com", "dev@wantedly.com"]
+
+  spec.summary       = %q{Batch loader with dependency resolution and computed fields}
+  spec.description   = <<~DSC
+    ComputedModel is a helper for building a read-only model (sometimes called a view)
+    from multiple sources of models.
+    It comes with batch loading and dependency resolution for better performance.
+
+    It is designed to be universal. It's as easy as pie to pull data from both
+    ActiveRecord and remote server (such as ActiveResource).
+  DSC
+  spec.homepage      = "https://github.com/wantedly/computed_model"
+  spec.licenses      = ['MIT']
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/wantedly/computed_model"
+  spec.metadata["changelog_uri"] = "https://github.com/wantedly/computed_model/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/computed_model.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "computed_model/version"
+require 'set'
+
+module ComputedModel
+  class NotLoaded < StandardError; end
+
+  Plan = Struct.new(:load_order, :subdeps_hash)
+
+  module ClassMethods
+    # @param deps [Array]
+    def dependency(*deps)
+      @__computed_model_next_dependency ||= []
+      @__computed_model_next_dependency.push(*deps)
+    end
+
+    # @param meth_name [Symbol]
+    def computed(meth_name)
+      var_name = :"@#{meth_name}"
+      meth_name_orig = :"#{meth_name}_orig"
+      compute_meth_name = :"compute_#{meth_name}"
+
+      @__computed_model_dependencies[meth_name] = ComputedModel.normalize_dependencies(@__computed_model_next_dependency)
+      remove_instance_variable(:@__computed_model_next_dependency)
+
+      alias_method meth_name_orig, meth_name
+      define_method(meth_name) do
+        raise NotLoaded, "the field #{meth_name} is not loaded" unless instance_variable_defined?(var_name)
+        instance_variable_get(var_name)
+      end
+      define_method(compute_meth_name) do
+        instance_variable_set(var_name, send(meth_name_orig))
+      end
+      if public_method_defined?(meth_name_orig)
+        public meth_name
+      elsif protected_method_defined?(meth_name_orig)
+        protected meth_name
+      elsif private_method_defined?(meth_name_orig)
+        private meth_name
+      end
+
+      meth_name
+    end
+
+    # @param methods [Array<Symbol>]
+    # @param to [Symbol]
+    # @param allow_nil [nil, Boolean]
+    # @param prefix [nil, Symbol]
+    # @param include_subdeps [nil, Boolean]
+    # @return [void]
+    def delegate_dependency(*methods, to:, allow_nil: nil, prefix: nil, include_subdeps: nil)
+      method_prefix = prefix ? "#{prefix_}" : ""
+      methods.each do |meth_name|
+        pmeth_name = :"#{method_prefix}#{meth_name}"
+        if include_subdeps
+          dependency to=>meth_name
+        else
+          dependency to
+        end
+        if allow_nil
+          define_method(pmeth_name) do
+            send(to)&.public_send(meth_name)
+          end
+        else
+          define_method(pmeth_name) do
+            send(to).public_send(meth_name)
+          end
+        end
+        computed pmeth_name
+      end
+    end
+
+    # @param meth_name [Symbol]
+    # @yieldparam objects [Array]
+    # @yieldparam options [Hash]
+    # @yieldreturn [void]
+    def define_loader(meth_name, &block)
+      raise ArgumentError, "No block given" unless block
+
+      var_name = :"@#{meth_name}"
+
+      @__computed_model_loaders[meth_name] = block
+
+      define_method(meth_name) do
+        raise NotLoaded, "the field #{meth_name} is not loaded" unless instance_variable_defined?(var_name)
+        instance_variable_get(var_name)
+      end
+      attr_writer meth_name
+    end
+
+    # @param objs [Array]
+    # @param deps [Array]
+    def bulk_load_and_compute(objs, deps, **options)
+      plan = computing_plan(deps)
+      plan.load_order.each do |dep_name|
+        if @__computed_model_dependencies.key?(dep_name)
+          objs.each do |obj|
+            obj.send(:"compute_#{dep_name}")
+          end
+        elsif @__computed_model_loaders.key?(dep_name)
+          @__computed_model_loaders[dep_name].call(objs, plan.subdeps_hash[dep_name], **options)
+        else
+          raise "No dependency info for #{self}##{dep_name}"
+        end
+      end
+    end
+
+    # @param deps [Array]
+    # @return [Plan]
+    def computing_plan(deps)
+      normalized = ComputedModel.normalize_dependencies(deps)
+      load_order = []
+      subdeps_hash = {}
+      visiting = Set[]
+      visited = Set[]
+      normalized.each do |dep_name, dep_subdeps|
+        computing_plan_dfs(dep_name, dep_subdeps, load_order, subdeps_hash, visiting, visited)
+      end
+
+      Plan.new(load_order, subdeps_hash)
+    end
+
+    # @param meth_name [Symbol]
+    # @param meth_subdeps [Array]
+    # @param load_order [Array<Symbol>]
+    # @param subdeps_hash [Hash{Symbol=>Array}]
+    # @param visiting [Set<Symbol>]
+    # @param visited [Set<Symbol>]
+    private def computing_plan_dfs(meth_name, meth_subdeps, load_order, subdeps_hash, visiting, visited)
+      (subdeps_hash[meth_name] ||= []).push(*meth_subdeps)
+      return if visited.include?(meth_name)
+      raise "Cyclic dependency for #{self}##{meth_name}" if visiting.include?(meth_name)
+      visiting.add(meth_name)
+
+      if @__computed_model_dependencies.key?(meth_name)
+        @__computed_model_dependencies[meth_name].each do |dep_name, dep_subdeps|
+          computing_plan_dfs(dep_name, dep_subdeps, load_order, subdeps_hash, visiting, visited)
+        end
+      elsif @__computed_model_loaders.key?(meth_name)
+      else
+        raise "No dependency info for #{self}##{meth_name}"
+      end
+
+      load_order << meth_name
+      visiting.delete(meth_name)
+      visited.add(meth_name)
+    end
+  end
+
+  # @param deps [Array<Symbol, Hash>]
+  # @return [Hash{Symbol=>Array}]
+  def self.normalize_dependencies(deps)
+    normalized = {}
+    deps.each do |elem|
+      case elem
+      when Symbol
+        normalized[elem] ||= []
+      when Hash
+        elem.each do |k, v|
+          v = [v] if v.is_a?(Hash)
+          normalized[k] ||= []
+          normalized[k].push(*Array(v))
+        end
+      else; raise "Invalid dependency: #{elem.inspect}"
+      end
+    end
+    normalized
+  end
+
+  def self.included(klass)
+    super
+    klass.extend ClassMethods
+    klass.instance_variable_set(:@__computed_model_dependencies, {})
+    klass.instance_variable_set(:@__computed_model_loaders, {})
+  end
+end

data/lib/computed_model/version.rb

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

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: computed_model
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Masaki Hara
+- Wantedly, Inc.
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  ComputedModel is a helper for building a read-only model (sometimes called a view)
+  from multiple sources of models.
+  It comes with batch loading and dependency resolution for better performance.
+
+  It is designed to be universal. It's as easy as pie to pull data from both
+  ActiveRecord and remote server (such as ActiveResource).
+email:
+- ackie.h.gmai@gmail.com
+- dev@wantedly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- computed_model.gemspec
+- lib/computed_model.rb
+- lib/computed_model/version.rb
+homepage: https://github.com/wantedly/computed_model
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wantedly/computed_model
+  source_code_uri: https://github.com/wantedly/computed_model
+  changelog_uri: https://github.com/wantedly/computed_model/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Batch loader with dependency resolution and computed fields
+test_files: []