computed_model 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21e228839945609c0ea57b95c23b1d6d7a2df2e31bdc077c23d04c7dfbe0a52f
-  data.tar.gz: 5f2dcf0e436b2c3bed403f592c8d7619e8b1e33db9e991ac07b5a9a6885cd063
+  metadata.gz: abe05016ded2805bb131703f0ac56757d84b3d341bb79d041184703dd2d61d73
+  data.tar.gz: 81f95364fee17dd9aff3dc37fb1036c679ad59f5006f734cd4b0bcbe79b6a4f7
 SHA512:
-  metadata.gz: 73b4e81cc16de364f6e4a6105038c30e5f2f49e0faa8adb9fdf121558563af41bb4b7ee315b20bd4cd8d5fe49248d4f1a0c7eec41283cadddcba7115e149bdb5
-  data.tar.gz: 69a3808af0eda772fa93bff71d59d442972f0a673bc68485767033f72c60296c40bb7e4c7e095b91096394d0b037dc1f1f90e78c9bf04641cfb61125d4046193
+  metadata.gz: e5cc071ca1645543721eb8ba0c50811930ac00f3ff542b9119b9919c328e3c22a8d127310cd3b8fca04d1ad32122b01a708a7b8210d5afe12d31f7580dbeb023
+  data.tar.gz: 431edf1ed4d6993b75fd67a8367f031e00eb210a57e9c40a87a28b393ecbc0fce54d3a364e80353a440687eabff65bbd7e213830d5b1bdbc7b4e669540f9eaef

data/.github/dependabot.yml

@@ -8,3 +8,11 @@ updates:
   open-pull-requests-limit: 10
   reviewers:
   - qnighy
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "20:00"
+  open-pull-requests-limit: 10
+  reviewers:
+    - qnighy

data/.github/workflows/test.yml

@@ -8,12 +8,17 @@ jobs:
 
     strategy:
       matrix:
-        ruby: ["2.5", "2.6", "2.7"]
+        ruby: ["2.5", "2.6", "2.7", "3.0"]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v2.3.4
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
     - run: bundle install
     - run: bundle exec rake
+    - name: Upload coverage
+      uses: codecov/codecov-action@v1.5.0
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: coverage/coverage.lcov

data/.yardopts

@@ -1 +1,6 @@
 --markup markdown
+-
+README.md
+README.ja.md
+CONCEPTS.md
+CONCEPTS.ja.md

data/CHANGELOG.md

@@ -1,5 +1,112 @@
 ## Unreleased
 
+## 0.3.0
+
+computed_model 0.3 comes with a great number of improvements, and a bunch of breaking changes.
+
+- Breaking changes
+  - `include ComputedModel` is now `include ComputedModel::Model`.
+  - Indirect dependencies are now rejected.
+  - `computed_model_error` was removed.
+  - `dependency` before `define_loader` will be consumed and ignored.
+  - `dependency` before `define_primary_loader` will be an error.
+  - Cyclic dependency is an error even if it is unused.
+  - `nil`, `true`, and `false` in subdeps will be filtered out before passed to a loader.
+  - `ComputedModel.normalized_dependencies` now returns `[true]` instead of `[]` as an empty value.
+  - `include_subdeps` is now `include_subfields`
+- Notable behavioral changes
+  - The order in which fields are loaded is changed.
+  - `ComputedModel::Model` now uses `ActiveSupport::Concern`.
+- Changed
+  - Separate `ComputedModel::Model` from `ComputedModel` https://github.com/wantedly/computed_model/pull/17
+  - Remove `computed_model_error` https://github.com/wantedly/computed_model/pull/18
+  - Improve behavior around dependency-field pairing https://github.com/wantedly/computed_model/pull/20
+  - Implement strict field access https://github.com/wantedly/computed_model/pull/23
+  - Preprocess graph with topological sorting https://github.com/wantedly/computed_model/pull/24
+  - Implement conditional dependencies and subdependency mapping/passthrough https://github.com/wantedly/computed_model/pull/25
+  - Use `ActiveSupport::Concern` https://github.com/wantedly/computed_model/pull/26
+  - Rename subdeps as subfields https://github.com/wantedly/computed_model/pull/31
+- Added
+  - `ComputedModel::Model#verify_dependencies`
+  - Loader dependency https://github.com/wantedly/computed_model/pull/28
+  - Support computed model inheritance https://github.com/wantedly/computed_model/pull/29
+- Refactored
+  - Extract `DepGraph` from `Model` https://github.com/wantedly/computed_model/pull/19
+  - Define loader as a singleton method https://github.com/wantedly/computed_model/pull/21
+  - Refactor `ComputedModel::Plan` https://github.com/wantedly/computed_model/pull/22
+- Misc
+  - Collect coverage https://github.com/wantedly/computed_model/pull/12 https://github.com/wantedly/computed_model/pull/16
+  - Refactor tests https://github.com/wantedly/computed_model/pull/10 https://github.com/wantedly/computed_model/pull/15
+  - Add tests https://github.com/wantedly/computed_model/pull/27
+  - Add documentation https://github.com/wantedly/computed_model/pull/30
+
+See [Migration-0.3.md](Migration-0.3.md) for migration.
+
+### New feature: dynamic dependencies
+
+Previously, subdeps are only useful for loaded fields and primary fields. Now computed fields can make use of subdeps!
+
+```ruby
+
+class User
+  # Delegate subdeps
+  dependency(
+    blog_articles: -> (subdeps) { subdeps }
+  )
+  computed def filtered_blog_articles
+    if current_subfields.normalized[:image].any?
+      # ...
+    end
+    # ...
+  end
+end
+```
+
+See [CONCEPTS.md](CONCEPTS.md) for more usages.
+
+### New feature: loader dependency
+
+You can specify dependency from a loaded field.
+
+```ruby
+class User
+  dependency :raw_user  # dependency of :raw_books
+  define_loader :raw_books, key: -> { id } do |subdeps, **|
+    # ...
+  end
+end
+```
+
+### New feature: computed model inheritance
+
+Now you can reuse computed model definitions via inheritance.
+
+```ruby
+module UserLikeConcern
+  extends ActiveSupport::Concern
+  include ComputedModel::Model
+
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+
+class User
+  include UserLikeConcern
+
+  define_loader :preference, key: -> { id } do ... end
+  define_loader :profile, key: -> { id } do ... end
+end
+
+class Admin
+  include UserLikeConcern
+
+  define_loader :preference, key: -> { id } do ... end
+  define_loader :profile, key: -> { id } do ... end
+end
+```
+
 ## 0.2.2
 
 - [#7](https://github.com/wantedly/computed_model/pull/7) Accept Hash as a `with` parameter

data/CONCEPTS.ja.md

@@ -0,0 +1,324 @@
+# 基本概念と機能
+
+[English version](CONCEPTS.md)
+
+## ラッパークラス
+
+ComputedModelは、ActiveRecordクラスなどに直接includeして使うことを(今のところ)想定していません。
+その場合ラッパークラスを作成し、元のクラスのオブジェクトは主ローダー (後述) として定義するのがよいでしょう。
+
+## フィールド
+
+**フィールド**はComputedModelの管理下にある属性のことで、依存管理の基本単位です。以下の3種類のフィールドがあります。
+
+- computed field (計算フィールド)
+- loaded field (読み込みフィールド)
+- primary field (主フィールド)
+
+### computed field (計算フィールド)
+
+別のフィールドの組み合わせで算出されるフィールドです。各レコードごとに独立に計算されます。
+
+```ruby
+class User
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+### loaded field (読み込みフィールド)
+
+複数レコードに対してまとめて読み込むフィールドです。
+
+```ruby
+class User
+  define_loader :preference, key: -> { id } do |ids, _subfields, **|
+    Preference.where(user_id: ids).index_by(&:user_id)
+  end
+end
+```
+
+### primary field (主フィールド)
+
+loaded fieldの機能に加えて、レコードの検索・列挙機能を担う特別なフィールドです。
+
+たとえば `User` の場合、あるidのユーザーが存在するかどうかはどこかのデータソースに問い合わせる必要があるはずです。
+それがたとえばActiveRecordの `RawUser` クラスである場合、主フィールドは以下のように定義されます。
+
+```ruby
+class User
+  def initialize(raw_user)
+    @raw_user = raw_user
+  end
+
+  define_primary_loader :raw_user do |_subfields, ids:, **|
+    # User#initialize 内で @raw_user をセットする必要がある
+    RawUser.where(id: ids).map { |u| User.new(u) }
+  end
+end
+```
+
+## 計算タイミング
+
+ComputedModelの `bulk_load_and_compute` が呼ばれたタイミングで全ての必要なフィールドが計算されます。
+
+遅延ロードは今のところサポートしていません。
+
+## 依存関係
+
+フィールドには依存関係を宣言することができます。
+ただし、主フィールドは依存関係を持つことができません。 (他のフィールドから主フィールドに依存することはできます。)
+
+```ruby
+class User
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+`computed def` 内や `define_loader` のブロック内では、 `dependency` で宣言したフィールドのみ参照できます。
+間接依存しているフィールドなど、たまたまロードされている場合でもアクセスはブロックされます。
+
+## `bulk_load_and_compute`
+
+ComputedModelの読み込みを行うメソッドが `bulk_load_and_compute` です。
+`bulk_load_and_compute` をそのまま使うのではなく、各モデルでラッパー関数を実装することが推奨されます。
+(これは後述するバッチロード引数の自由度が高く、そのままでは使い間違いが起きやすいからです)
+
+```ruby
+class User
+  # with には [:display_name, :title] のようにフィールド名の配列を指定する
+  def self.list(ids, with:)
+    bulk_load_and_compute(with, ids: ids)
+  end
+
+  def self.get(id, with:)
+    list([id], with: with).first
+  end
+
+  def self.get!(id, with:)
+    get(id, with: with) || (raise User::NotFound)
+  end
+end
+```
+
+単独のレコードを読み込むための専用のメソッドはありません。こちらも `bulk_load_and_compute` のラッパーを実装することで実現してください。
+もし単独のレコードであることを利用した最適化が必要な場合は、 `define_loader` や `define_primary_loader` で分岐を実装するとよいでしょう。
+
+## 下位フィールドセレクタ
+
+下位フィールドセレクタ (subfield selector) または 下位依存 (subdependency) は依存関係につけられる追加の情報です。
+
+実装上はフィールドから依存先フィールドに任意のメッセージを送ることができる仕組みになっていますが、
+名前の通りフィールドにぶら下がっている情報の取得に使うことを想定しています。
+
+```ruby
+class User
+  define_loader :profile, key: -> { id } do |ids, subfields, **|
+    Profile.preload(subfields).where(user_id: ids).index_by(&:user_id)
+  end
+
+  # profileのローダーに [:contact_phones] が渡される
+  dependency profile: :contact_phones
+  computed def contact_phones
+    profile.contact_phones
+  end
+end
+```
+
+計算フィールドでも下位フィールドセレクタを使うことができます。 (「高度な依存関係」で後述)
+
+## バッチロード引数
+
+`bulk_load_and_compute` のキーワード引数は、 `define_primary_loader` や `define_loader` のブロックにそのまま渡されます。
+状況にあわせて色々な使い方が考えられます。
+
+### id以外での検索
+
+複数の検索条件を与えることもできます。
+
+```ruby
+class User
+  def self.list(ids, with:)
+    bulk_load_and_compute(with, ids: ids, emails: nil)
+  end
+
+  def self.list_by_emails(emails, with:)
+    bulk_load_and_compute(with, ids: nil, emails: emails)
+  end
+
+  define_primary_loader :raw_user do |_subfields, ids:, emails:, **|
+    s = User.all
+    s = s.where(id: ids) if ids
+    s = s.where(email: emails) if emails
+    s.map { |u| User.new(u) }
+  end
+end
+```
+
+### カレントユーザー
+
+「今どのユーザーでログインしているか」によって情報の見え方が違う、というような状況を考えます。これはカレントユーザー情報をバッチロード引数に含めることで実現可能です。
+
+```ruby
+class User
+  def initialize(raw_user, current_user_id)
+    @raw_user = raw_user
+    @current_user_id = current_user_id
+  end
+
+  define_primary_loader :raw_user do |_subfields, current_user_id:, ids:, **|
+    # ...
+  end
+
+  define_loader :profile, key: -> { id } do |ids, _subfields, current_user_id:, **|
+    # ...
+  end
+end
+```
+
+## 高度な依存関係
+
+下位フィールドセレクタにprocを指定することで、より高度な制御をすることができます。
+
+### 条件つき依存
+
+受け取った下位フィールドセレクタの内容にもとづいて、条件つき依存関係を定義することができます。
+
+```ruby
+
+class User
+  dependency(
+    :blog_articles,
+    # image 下位フィールドセレクタがあるときのみ image_permissions フィールド を読み込む
+    image_permissions: -> (subfields) { subfields.normalized[:image].any? }
+  )
+  computed def filtered_blog_articles
+    if current_subfields.normalized[:image].any?
+      # ...
+    end
+    # ...
+  end
+end
+```
+
+### 下位フィールドセレクタのパススルー
+
+下位フィールドセレクタを別のフィールドにそのまま流すことができます。
+
+```ruby
+
+class User
+  dependency(
+    blog_articles: -> (subfields) { subfields }
+  )
+  computed def filtered_blog_articles
+    if current_subfields.normalized[:image].any?
+      # ...
+    end
+    # ...
+  end
+end
+```
+
+### 下位フィールドセレクタのマッピング
+
+下位フィールドセレクタを加工して別のフィールドに流すこともできます。
+
+```ruby
+class User
+  dependency(
+    # blog_articles を必ずロードするが、
+    # 特に下位フィールドセレクタが blog_articles キーを持つ場合はそれを blog_articles の下位フィールドセレクタとして流す
+    blog_articles: [true, -> (subfields) { subfields.normalized[:blog_articles] }],
+    # wiki_articles を必ずロードするが、
+    # 特に下位フィールドセレクタが wiki_articles キーを持つ場合はそれを wiki_articles の下位フィールドセレクタとして流す
+    wiki_articles: [true, -> (subfields) { subfields.normalized[:wiki_articles] }]
+  )
+  computed def articles
+    (blog_articles + wiki_articles).sort_by { |article| article.created_at }.reverse
+  end
+end
+```
+
+### 依存関係のフォーマット
+
+`dependency` には0個以上の引数を渡すことができます。
+これらは内部で配列に積まれていき、直後の `computed def` や `define_loader` によって消費されます。
+そのため、以下は同じ意味です。
+
+```ruby
+dependency :profile
+dependency :preference
+computed def display_name; ...; end
+```
+
+```ruby
+dependency :profile, :preference
+computed def display_name; ...; end
+```
+
+渡された配列は `ComputedModel.normalize_dependencies` によってハッシュに正規化されます。これは以下のようなルールになっています。
+
+- Symbolの場合はそのシンボルをキーとするHashとみなす。 (`:foo` → `{ foo: [true] }`)
+- Hashの場合は中の値を以下のように変換する。
+  - 空配列の場合は `[true]` に変換する。 (`{ foo: [] }` → `{ foo: [true] }`)
+  - 配列以外の場合はそれを単独で含む配列に変換する。 (`{ foo: :bar }` → `{ foo: [:bar] }`)
+  - 空以外の配列の場合はそのまま。
+- 配列の場合は個々の要素を上記のルールに従って変換したあと、ハッシュのキーをマージする。ハッシュの値は配列なのでそのまま結合される。
+  - `[:foo, :bar]` → `{ foo: [true], bar: [true] }`
+  - `[{ foo: :foo }, { foo: :bar }]` → `{ foo: [:foo, :bar] }`
+
+このようにして得られたハッシュのキーは依存するフィールド名、値は下位フィールドセレクタとして解釈されます。
+
+下位フィールドセレクタは以下のように解釈します。
+
+- Procなど `#call` を持つオブジェクトがある場合、引数に `subfields` (下位フィールドセレクタの配列) を渡して実行する。
+  - 配列が返ってきた場合はフラットに展開する。 (`{ foo: [-> { [:bar, :baz] }] }` → `{ foo: [:bar, :baz] }`)
+  - それ以外の値が返ってきた場合はその要素で置き換える。 (`{ foo: [-> { :bar }] }` → `{ foo: [:bar] }`)
+- Procの置き換え後、真値 (nilとfalse以外の値) が1つ以上含まれているかを判定する。
+  - 真値がひとつもない場合は、条件つき依存の判定が偽になったとみなし、その依存関係は使わない。
+  - それ以外の場合は依存関係を使う。Procの置き換え後に得られた下位フィールドセレクタはそのまま依存先フィールドに送られる。
+
+そのため下位フィールドセレクタには通常 `true` が含まれています。特別な条件として以下の場合は取り除かれます。
+
+- `define_loader` や `define_primary_loader` のブロックに渡されるときは、下位フィールドセレクタに含まれる `nil`, `false`, `true` は
+  取り除かれます。
+- いくつかの場面では `subfields.normalize` という特別なメソッドが使えることがあります。これは下位フィールドセレクタに含まれる
+  `nil`, `false`, `true` を取り除いたあと、 `ComputedModel.normalize_dependencies` の正規化にかけたハッシュを返します。
+
+## 継承
+
+ComputedModelで部分的にフィールドを定義したクラス (モジュール) を作り、それを継承 (インクルード) したクラスで定義を完成させることができます。
+
+```ruby
+module UserLikeConcern
+  extends ActiveSupport::Concern
+  include ComputedModel::Model
+
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+
+class User
+  include UserLikeConcern
+
+  define_loader :preference, key: -> { id } do ... end
+  define_loader :profile, key: -> { id } do ... end
+end
+
+class Admin
+  include UserLikeConcern
+
+  define_loader :preference, key: -> { id } do ... end
+  define_loader :profile, key: -> { id } do ... end
+end
+```
+
+オーバーライドは正しく動かない可能性があります。 (computed def が内部的にメソッドのリネームを行っているため)