computed_model 0.1.0 → 0.3.0

data/README.ja.md

@@ -0,0 +1,168 @@
+# ComputedModel
+
+ComputedModelは依存解決アルゴリズムを備えた普遍的なバッチローダーです。
+
+- 依存解決アルゴリズムの恩恵により、抽象化を損なわずに以下の3つを両立させることができます。
+  - ActiveRecord等から読み込んだデータを加工して提供する。
+  - ActiveRecord等からのデータの読み込みを一括で行うことでN+1問題を防ぐ。
+  - 必要なデータだけを読み込む。
+- 複数のデータソースからの読み込みにも対応。
+- データソースに依存しない普遍的な設計。HTTPで取得した情報とActiveRecordから取得した情報の両方を使う、といったこともできます。
+
+[English version](README.md)
+
+## 解決したい問題
+
+モデルが複雑化してくると、単にデータベースから取得した値を返すだけではなく、加工した値を返したくなることがあります。
+
+```ruby
+class User < ApplicationRecord
+  has_one :preference
+  has_one :profile
+
+  def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+ところがこれをそのまま使うと N+1 問題が発生することがあります。
+
+```ruby
+# N+1 問題!
+User.where(id: friend_ids).map(&:display_name)
+```
+
+N+1問題を解決するには、 `#display_name` が何に依存していたかを調べ、それをpreloadしておく必要があります。
+
+```ruby
+User.where(id: friend_ids).preload(:preference, :profile).map(&:display_name)
+#                                  ^^^^^^^^^^^^^^^^^^^^^ display_name の抽象化が漏れてしまう
+```
+
+これではせっかく `#display_name` を抽象化した意味が半減してしまいます。
+
+ComputedModelは依存解決アルゴリズムをバッチローダーに接続することでこの問題を解消します。
+
+```ruby
+class User
+  define_primary_loader :raw_user do ... end
+  define_loader :preference do ... end
+  define_loader :profile do ... end
+
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+## インストール
+
+Gemfileに以下の行を追加:
+
+```ruby
+gem 'computed_model', '~> 0.3.0'
+```
+
+その後、以下を実行:
+
+    $ bundle
+
+または直接インストール:
+
+    $ gem install computed_model
+
+## 動かせるサンプルコード
+
+```ruby
+require 'computed_model'
+
+# この2つを外部から取得したデータとみなす (ActiveRecordやHTTPで取得したリソース)
+RawUser = Struct.new(:id, :name, :title)
+Preference = Struct.new(:user_id, :name_public)
+
+class User
+  include ComputedModel::Model
+
+  attr_reader :id
+  def initialize(raw_user)
+    @id = raw_user.id
+    @raw_user = raw_user
+  end
+
+  def self.list(ids, with:)
+    bulk_load_and_compute(Array(with), ids: ids)
+  end
+
+  define_primary_loader :raw_user do |_subfields, ids:, **|
+    # ActiveRecordの場合:
+    # raw_users = RawUser.where(id: ids).to_a
+    raw_users = [
+      RawUser.new(1, "Tanaka Taro", "Mr. "),
+      RawUser.new(2, "Yamada Hanako", "Dr. "),
+    ].filter { |u| ids.include?(u.id) }
+    raw_users.map { |u| User.new(u) }
+  end
+
+  define_loader :preference, key: -> { id } do |user_ids, _subfields, **|
+    # ActiveRecordの場合:
+    # Preference.where(user_id: user_ids).index_by(&:user_id)
+    {
+      1 => Preference.new(1, true),
+      2 => Preference.new(2, false),
+    }.filter { |k, _v| user_ids.include?(k) }
+  end
+
+  delegate_dependency :name, to: :raw_user
+  delegate_dependency :title, to: :raw_user
+  delegate_dependency :name_public, to: :preference
+
+  dependency :name, :name_public
+  computed def public_name
+    name_public ? name : "Anonymous"
+  end
+
+  dependency :public_name, :title
+  computed def public_name_with_title
+    "#{title}#{public_name}"
+  end
+end
+
+# あらかじめ要求したフィールドにだけアクセス可能
+users = User.list([1, 2], with: [:public_name_with_title])
+users.map(&:public_name_with_title) # => ["Mr. Tanaka Taro", "Dr. Anonymous"]
+users.map(&:public_name) # => error (ForbiddenDependency)
+
+users = User.list([1, 2], with: [:public_name_with_title, :public_name])
+users.map(&:public_name_with_title) # => ["Mr. Tanaka Taro", "Dr. Anonymous"]
+users.map(&:public_name) # => ["Tanaka Taro", "Anonymous"]
+
+# 次のような場合は preference は読み込まれない。
+users = User.list([1, 2], with: [:title])
+users.map(&:title) # => ["Mr. ", "Dr. "]
+```
+
+## 次に読むもの
+
+- [基本概念と機能](CONCEPTS.ja.md)
+
+## License
+
+This library is distributed under MIT license.
+
+Copyright (c) 2020 Masaki Hara
+
+Copyright (c) 2020 Masayuki Izumi
+
+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/wantedly/computed_model.

data/README.md

@@ -1,120 +1,162 @@
 # 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.
+ComputedModel is a universal batch loader which comes with a dependency-resolution algorithm.
 
-It is designed to be universal. It's as easy as pie to pull data from both
-ActiveRecord and remote server (such as ActiveResource).
+- Thanks to the dependency resolution, it allows you to the following trifecta at once, without breaking abstraction.
+  - Process information gathered from datasources (such as ActiveRecord) and return the derived one.
+  - Prevent N+1 problem via batch loading.
+  - Load only necessary data.
+- Can load data from multiple datasources.
+- Designed to be universal and datasource-independent.
+  For example, you can gather data from both HTTP and ActiveRecord and return the derived one.
 
-## Installation
+[日本語版README](README.ja.md)
 
-Add this line to your application's Gemfile:
+## Problems to solve
+
+As models grow, they cannot simply return the database columns as-is.
+Instead, we want to process information obtained from the database and return the derived value.
 
 ```ruby
-gem 'computed_model'
+class User < ApplicationRecord
+  has_one :preference
+  has_one :profile
+
+  def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
 ```
 
-And then execute:
+However, it can lead to N+1 without care.
 
-    $ bundle
+```ruby
+# N+1 problem!
+User.where(id: friend_ids).map(&:display_name)
+```
 
-Or install it yourself as:
+To solve the N+1 problem, we need to enumerate dependencies of `#display_name` and preload them.
 
-    $ gem install computed_model
+```ruby
+User.where(id: friend_ids).preload(:preference, :profile).map(&:display_name)
+#                                  ^^^^^^^^^^^^^^^^^^^^^ breaks abstraction of display_name
+```
 
-## Usage
+This partially defeats the purpose of `#display_name`'s abstraction.
 
-Include `ComputedModel` in your model class. You may also need an `attr_reader` for the primary key.
+Computed solves the problem by connection the dependency-resolution to the batch loader.
 
 ```ruby
 class User
-  attr_reader :id
+  define_primary_loader :raw_user do ... end
+  define_loader :preference do ... end
+  define_loader :profile do ... end
 
-  include ComputedModel
-
-  def initialize(id)
-    @id = id
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
   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
+## Installation
 
-Use `ComputedModel::ClassMethods#define_loader` to define loaded attributes.
+Add this line to your application's Gemfile:
 
 ```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
+gem 'computed_model', '~> 0.3.0'
 ```
 
-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.
+And then execute:
 
-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.
+    $ bundle
 
-The keyword arguments are also a verbatim copy of what you pass to `ComputedModel::ClassMethods#bulk_load_and_compute`.
+Or install it yourself as:
 
-## Computed attributes
+    $ gem install computed_model
 
-Use `ComputedModel::ClassMethods#computed` and `#dependency` to define computed attributes.
+## Working example
 
 ```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
+require 'computed_model'
+
+# Consider them external sources (ActiveRecord or resources obtained via HTTP)
+RawUser = Struct.new(:id, :name, :title)
+Preference = Struct.new(:user_id, :name_public)
+
+class User
+  include ComputedModel::Model
+
+  attr_reader :id
+  def initialize(raw_user)
+    @id = raw_user.id
+    @raw_user = raw_user
+  end
+
+  def self.list(ids, with:)
+    bulk_load_and_compute(Array(with), ids: ids)
+  end
+
+  define_primary_loader :raw_user do |_subfields, ids:, **|
+    # In ActiveRecord:
+    # raw_users = RawUser.where(id: ids).to_a
+    raw_users = [
+      RawUser.new(1, "Tanaka Taro", "Mr. "),
+      RawUser.new(2, "Yamada Hanako", "Dr. "),
+    ].filter { |u| ids.include?(u.id) }
+    raw_users.map { |u| User.new(u) }
   end
-end
-```
 
-## Batch loading
+  define_loader :preference, key: -> { id } do |user_ids, _subfields, **|
+    # In ActiveRecord:
+    # Preference.where(user_id: user_ids).index_by(&:user_id)
+    {
+      1 => Preference.new(1, true),
+      2 => Preference.new(2, false),
+    }.filter { |k, _v| user_ids.include?(k) }
+  end
 
-Once you defined loaded and computed attributes, you can batch-load them using `ComputedModel::ClassMethods#bulk_load_and_compute`.
+  delegate_dependency :name, to: :raw_user
+  delegate_dependency :title, to: :raw_user
+  delegate_dependency :name_public, to: :preference
 
-Typically you need to create a wrapper for the batch loader like:
+  dependency :name, :name_public
+  computed def public_name
+    name_public ? name : "Anonymous"
+  end
 
-```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
+  dependency :public_name, :title
+  computed def public_name_with_title
+    "#{title}#{public_name}"
+  end
 end
-```
 
-They you can retrieve users with only a specified attributes in a batch:
+# You can only access the field you requested ahead of time
+users = User.list([1, 2], with: [:public_name_with_title])
+users.map(&:public_name_with_title) # => ["Mr. Tanaka Taro", "Dr. Anonymous"]
+users.map(&:public_name) # => error (ForbiddenDependency)
 
-```ruby
-users = User.list([1, 2, 3], with: [:name, :name_with_playing_music, :premium_user])
+users = User.list([1, 2], with: [:public_name_with_title, :public_name])
+users.map(&:public_name_with_title) # => ["Mr. Tanaka Taro", "Dr. Anonymous"]
+users.map(&:public_name) # => ["Tanaka Taro", "Anonymous"]
+
+# In this case, preference will not be loaded.
+users = User.list([1, 2], with: [:title])
+users.map(&:title) # => ["Mr. ", "Dr. "]
 ```
 
+## Next read
+
+- [Basic concepts and features](CONCEPTS.md)
+
 ## License
 
 This library is distributed under MIT license.
 
 Copyright (c) 2020 Masaki Hara
+
+Copyright (c) 2020 Masayuki Izumi
+
 Copyright (c) 2020 Wantedly, Inc.
 
 ## Development
@@ -125,4 +167,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/qnighy/computed_model.
+Bug reports and pull requests are welcome on GitHub at https://github.com/wantedly/computed_model.

data/Rakefile

@@ -4,3 +4,17 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+namespace :db do
+  namespace :schema do
+    task :dump do
+      $LOAD_PATH.push(File.join(__dir__, 'spec'))
+      require 'active_record'
+      require 'support/db/connection'
+      require 'support/db/schema'
+      File.open(File.join(__dir__, 'spec/support/db/schema.rb'), 'w:utf-8') do |file|
+        ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection, file)
+      end
+    end
+  end
+end

data/computed_model.gemspec

@@ -7,8 +7,8 @@ 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.authors       = ["Masaki Hara", "Masayuki Izumi", "Wantedly, Inc."]
+  spec.email         = ["ackie.h.gmai@gmail.com", "m@izum.in", "dev@wantedly.com"]
 
   spec.summary       = %q{Batch loader with dependency resolution and computed fields}
   spec.description   = <<~DSC
@@ -35,7 +35,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  # For ActiveSupport::Concern
+  spec.add_development_dependency "activesupport"
+
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "activerecord", "~> 6.1"
+  spec.add_development_dependency "sqlite3", "~> 1.4"
+  spec.add_development_dependency "factory_bot", "~> 6.1"
+  spec.add_development_dependency "simplecov", "~> 0.21.2"
+  spec.add_development_dependency "simplecov-lcov", "~> 0.8.0"
 end