computed_model 0.1.0 → 0.3.0

data/CONCEPTS.md

@@ -0,0 +1,330 @@
+# Basic concepts and features
+
+[日本語版](CONCEPTS.ja.md)
+
+## Wrapping classes
+
+We don't (yet) support directly including `ComputedModel::Model` into ActiveRecord classes or similar ones.
+In that case, we recommend creating a wrapper class and reference the original class via the primary loader
+(described later).
+
+## Fields
+
+**Field** are certain attributes managed by ComputedModel. It's a unit of dependency resolution and
+there are three kinds of fields:
+
+- computed fields
+- loaded fields
+- primary fields
+
+### computed fields
+
+A computed field is a field in which it's value is derived from other fields.
+It's calculated independently per record.
+
+```ruby
+class User
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+### loaded fields
+
+A loaded field is a field in which we obtain values in batches.
+
+```ruby
+class User
+  define_loader :preference, key: -> { id } do |ids, _subfields, **|
+    Preference.where(user_id: ids).index_by(&:user_id)
+  end
+end
+```
+
+### primary fields
+
+A primary field is responsible in searching/enumerating the whole records,
+in addition to the usual responsibility of loaded fields.
+
+Consider a hypothetical `User` class for example. In this case you might want to inquiry somewhere (a data source)
+whether a user with a certain id exists.
+
+If it were a hypothetical ActiveRecord class `RawUser`, the primary field would be defined as follows:
+
+```ruby
+class User
+  def initialize(raw_user)
+    @raw_user = raw_user
+  end
+
+  define_primary_loader :raw_user do |_subfields, ids:, **|
+    # You need to set @raw_user in User#initialize.
+    RawUser.where(id: ids).map { |u| User.new(u) }
+  end
+end
+```
+
+## When computation is done
+
+All necessary fields are computed eagerly when ComputedModel's `bulk_load_and_compute` is called.
+
+It doesn't (yet) provide lazy loading functionality.
+
+## Dependency
+
+You can declare dependencies on a field.
+As an exception, the primary field cannot have a dependency (but it can have dependents, of course).
+
+```ruby
+class User
+  dependency :preference, :profile
+  computed def display_name
+    "#{preference.title} #{profile.name}"
+  end
+end
+```
+
+In `computed def` or `define_loader`, among all fields, you can only read values of explicitly declared dependencies.
+You cannot read other fields even if it happens to be present (such as indirect dependencies).
+
+## `bulk_load_and_compute`
+
+`bulk_load_and_compute` is the very method you need to load ComputedModel records.
+We recommend wrapping the method in each model class.
+This is mostly because there is a lot of freedom in the format of the batch-loading parameters (described later)
+and it will likely cause mistakes if used directly.
+
+```ruby
+class User
+  # You can specify an array of fields like [:display_name, :title] in the `with` parameter.
+  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
+```
+
+There is no such method as load a single record. You can easily implement it by wrapping `bulk_load_and_compute`.
+If you want a certain optimization for single-record cases, you may want to write conditionals in `define_loader` or `define_primary_loader`.
+
+## Subfield selectors
+
+Subfield selectors (or subdependencies) are additional information attached to a dependency.
+
+Implementation-wise they're just arbitrary messages sent from a field to its dependency.
+Nonetheless we expect them to be used to request "subfields" as the name suggests.
+
+```ruby
+class User
+  define_loader :profile, key: -> { id } do |ids, subfields, **|
+    Profile.preload(subfields).where(user_id: ids).index_by(&:user_id)
+  end
+
+  # [:contact_phones] will be passed to the loader of `profile`.
+  dependency profile: :contact_phones
+  computed def contact_phones
+    profile.contact_phones
+  end
+end
+```
+
+You can also receive subfield selectors in a computed field. See the "Dynamic dependencies" section later.
+
+## Batch-loading parameters
+
+The keyword parameters given to `bulk_load_and_compute` is passed through to the blocks of `define_primary_loader` or `define_loader`.
+You can use it for various purposes, some of which we present below:
+
+### Searching records by conditions other than id
+
+You can pass multiple different search conditions through the keyword parameters.
+
+```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
+```
+
+### Current user
+
+Consider a situation where we want to present different information depending on whom the user is logging in as.
+You can implement it by including the current user in the keyword parameters.
+
+```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
+```
+
+## Dynamic dependencies
+
+You can configure dynamic dependencies by specifying Procs as subfield selectors.
+
+### Conditional dependencies
+
+Dependencies which are conditionally enabled based on incoming subfield selectors:
+
+```ruby
+
+class User
+  dependency(
+    :blog_articles,
+    # Load image_permissions only when it receives `image` subfield selector.
+    image_permissions: -> (subfields) { subfields.normalized[:image].any? }
+  )
+  computed def filtered_blog_articles
+    if current_subfields.normalized[:image].any?
+      # ...
+    end
+    # ...
+  end
+end
+```
+
+### Subfield selectors passthrough
+
+Passing through incoming subfield selectors to another field:
+
+```ruby
+
+class User
+  dependency(
+    blog_articles: -> (subfields) { subfields }
+  )
+  computed def filtered_blog_articles
+    if current_subfields.normalized[:image].any?
+      # ...
+    end
+    # ...
+  end
+end
+```
+
+### Subfield selectors mapping
+
+Processing incoming subfield selectors and pass the result as outgoing subfield selectors to another field:
+
+```ruby
+class User
+  dependency(
+    # Always load blog_articles, but
+    # if the incoming subfield selectors contain `blog_articles`, pass them down to the dependency.
+    blog_articles: [true, -> (subfields) { subfields.normalized[:blog_articles] }],
+    # Always load wiki_articles, but
+    # if the incoming subfield selectors contain `wiki_articles`, pass them down to the dependency.
+    wiki_articles: [true, -> (subfields) { subfields.normalized[:wiki_articles] }]
+  )
+  computed def articles
+    (blog_articles + wiki_articles).sort_by { |article| article.created_at }.reverse
+  end
+end
+```
+
+### Detailed dependency format
+
+You can pass 0 or more arguments to `dependency`.
+They're pushed into an internal array and will be consumed by the next `computed def` or `define_loader`.
+So they have the same meaning:
+
+```ruby
+dependency :profile
+dependency :preference
+computed def display_name; ...; end
+```
+
+```ruby
+dependency :profile, :preference
+computed def display_name; ...; end
+```
+
+The resulting array will be normalized as a hash by `ComputedModel.normalize_dependencies`. The rules are:
+
+- If it's a Symbol, convert it to a singleton hash containing the key. (`:foo` → `{ foo: [true] }`)
+- If it's a Hash, convert the values as follows:
+  - If the value is an empty array, replace it with `[true]`. (`{ foo: [] }` → `{ foo: [true] }`)
+  - If the value is not an array, convert it to the singleton array. (`{ foo: :bar }` → `{ foo: [:bar] }`)
+  - If the value is a non-empty array, keep it as-is.
+- If it's an Array, convert each element following the rules above and merge the keys of the hashes. Hash values are always arrays and will be simply concatenated.
+  - `[:foo, :bar]` → `{ foo: [true], bar: [true] }`
+  - `[{ foo: :foo }, { foo: :bar }]` → `{ foo: [:foo, :bar] }`
+
+We interpret the resulting hash as a dictionary from a field name (dependency names) and it's subfield selectors.
+
+Each subfield selector is interpreted as below:
+
+- If it contains `#call`able objects (such as Proc), call them with `subfields` (incoming subfield selectors) as their argument.
+  - Expand the result if it's an Array. (`{ foo: [-> { [:bar, :baz] }] }` → `{ foo: [:bar, :baz] }`)
+  - Otherwise push the result. (`{ foo: [-> { :bar }] }` → `{ foo: [:bar] }`)
+- After Proc substitution, check if it contains any truthy value (value other than `nil` or `false`).
+  - If no truthy value is found, we don't use the dependency as the condition is not met.
+  - Otherwise (if truthy value is found), use the dependency. Subfield selectors (after substitution) are sent to the dependency as-is.
+
+For that reason, in most cases subfield selectors contain `true`. As a special case we remove them in the following cases:
+
+- We'll remove `nil`, `false`, `true` from the subfield selectors before passed to a `define_loader` or `define_primary_loader` block.
+- In certain cases you can use `subfields.normalize` to get a hash from the subfield selectors array. This is basically `ComputedModel.normalize_dependencies` but `nil`, `false`, `true` will be removed as part of preprocessing.
+
+## Inheritance
+
+You can also define partial ComputedModel class/module. You can then inherit/include it in a different class and complete the definition.
+
+```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
+```
+
+Note that in certain cases overriding might work incorrectly (because `computed def` internally renames the given method)

data/Migration-0.3.md

@@ -0,0 +1,343 @@
+# v0.3.0 migration guide
+
+computed_model 0.3.0 comes with a number of breaking changes.
+This guide will help you upgrade the library,
+but please test your program before deploying to production.
+
+## Major breaking: `ComputedModel` is now `ComputedModel::Model`
+
+https://github.com/wantedly/computed_model/pull/17
+
+Before:
+
+```ruby
+class User
+  include ComputedModel
+end
+```
+
+After:
+
+```ruby
+class User
+  include ComputedModel::Model
+end
+```
+
+
+## Major breaking: Indirect dependencies are now rejected
+
+computed_model 0.3 checks if the requested field is a direct dependency.
+If not, it raises `ComputedModel::ForbiddenDependency`.
+
+https://github.com/wantedly/computed_model/pull/23
+
+### Case 1
+
+This will mostly affect the following "indirect dependency" case:
+
+Before:
+
+```ruby
+class User
+  dependency :bar
+  computed def foo
+    baz  # Accepted in computed_model 0.2
+    # ...
+  end
+
+  dependency :baz
+  computed def bar
+    # ...
+  end
+end
+```
+
+After:
+
+```ruby
+class User
+  dependency :bar, :baz  # Specify dependencies correctly
+  computed def foo
+    baz
+    # ...
+  end
+
+  dependency :baz
+  computed def bar
+    # ...
+  end
+end
+```
+
+### Case 2
+
+Before:
+
+```ruby
+class User
+  dependency :bar
+  computed def foo
+    # ...
+  end
+end
+
+users = User.bulk_load_and_compute([:foo], ...)
+users[0].bar  # Accepted in computed_model 0.2
+```
+
+After:
+
+```ruby
+class User
+  dependency :bar
+  computed def foo
+    # ...
+  end
+end
+
+users = User.bulk_load_and_compute([:foo, :bar], ...)  # Specify dependencies correctly
+users[0].bar
+```
+
+### Other cases
+
+Previously, it sometimes happens to work depending on the order in which fields are loaded.
+
+```ruby
+class User
+  # No dependency between foo and bar
+
+  dependency :raw_user
+  computed def foo
+    # ...
+  end
+
+  dependency :raw_user
+  computed def bar
+    foo
+    # ...
+  end
+end
+```
+
+It was already fragile in computed_model 0.2.
+However, in computed_model 0.3,
+it always leads to `ComputedModel::ForbiddenDependency`.
+
+
+## Major breaking: `subdeps` are now called `subfields`
+
+https://github.com/wantedly/computed_model/pull/31
+
+Before:
+
+```ruby
+class User
+  delegate_dependency :name, to: :raw_user, include_subdeps: true
+end
+```
+
+After:
+
+```ruby
+class User
+  delegate_dependency :name, to: :raw_user, include_subfields: true
+end
+```
+
+We also recommend renaming block parameters named `subdeps` as `subfields`,
+although not strictly necessary.
+
+
+## Minor breaking: `computed_model_error` has been removed
+
+It was useful in computed_model 0.1 but no longer needed in computed_model 0.2.
+
+https://github.com/wantedly/computed_model/pull/18
+
+```ruby
+# No longer possible
+self.computed_model_error = User::NotFound.new
+```
+
+## Minor breaking: Behavior of `dependency` not directly followed by `computed def` has been changed.
+
+It doesn't effect you if all `dependency` declarations are followed by `computed def`.
+
+```ruby
+# Keeps working
+dependency :foo
+computed def bar
+end
+```
+
+Otherwise `dependency` might be consumed by the next `define_loader` or `define_primary_loader`.
+
+https://github.com/wantedly/computed_model/pull/20
+
+Before:
+
+```ruby
+dependency :foo  # dependency of bar in computed_model 0.2
+
+define_loader :quux, key: -> { id } do
+  # ...
+end
+
+computed def bar
+  # ...
+end
+```
+
+After:
+
+```ruby
+# This would be interpreted as a dependency of quux
+# dependency :foo
+
+define_loader :quux, key: -> { id } do
+  # ...
+end
+
+dependency :foo  # Place it here
+computed def bar
+  # ...
+end
+```
+
+Additionally, `dependency` before `define_primary_loader` will be an error.
+
+## Minor breaking: Cyclic dependency is an error even if it is unused
+
+https://github.com/wantedly/computed_model/pull/24
+
+Before:
+
+```ruby
+class User
+
+  # Cyclic dependency is allowed as long as it's unused
+
+  dependency :bar
+  computed def foo
+  end
+
+  dependency :foo
+  computed def bar
+  end
+end
+
+users = User.bulk_load_and_compute([], ...)  # Neither :foo nor :bar is used
+```
+
+After:
+
+```ruby
+class User
+  # Remove cyclic dependency altogether
+end
+
+users = User.bulk_load_and_compute([], ...)  # Neither :foo nor :bar is used
+```
+
+## Minor breaking: `nil`, `true`, `false` and `Proc` in subdeps are treated differently
+
+They now have special meaning, so you should avoid using them as a normal subdependency.
+
+https://github.com/wantedly/computed_model/pull/25
+
+### `nil` and `false`
+
+They are constantly false condition in conditional dependency. Unless otherwise enabled, the dependency won't be used.
+
+Before:
+
+```ruby
+dependency foo: [nil, false]  # foo will be used
+computed def bar
+end
+```
+
+After:
+
+```ruby
+# dependency foo: [nil, false]  # foo won't be used
+dependency foo: [:nil, :false]  # Use other values instead
+computed def bar
+end
+```
+
+### `true`
+
+They are constantly true condition in conditional dependency. It's filtered out before passed to a loader or a primary loader.
+
+Before:
+
+```ruby
+dependency foo: [true]  # true is given to "define_loader :foo do ... end"
+computed def bar
+end
+```
+
+After:
+
+```ruby
+# dependency foo: [true]  # true is ignored
+dependency foo: [:true]  # Use other values instead
+computed def bar
+end
+```
+
+### Proc
+
+Callable objects (objects implementing `#call`), including instances of `Proc`, is interpreted as a dynamic dependency.
+
+Before:
+
+```ruby
+dependency foo: -> { raise "foo" }  # Passed to foo as-is
+computed def bar
+end
+```
+
+After:
+
+```ruby
+# dependency foo: -> { raise "foo" }  # Dynamic dependency. Called during dependency resolution.
+dependency foo: { callback: -> { raise "foo" } }  # Wrap it in something
+computed def bar
+end
+```
+
+
+## Behavioral change: The order in which fields are loaded is changed
+
+https://github.com/wantedly/computed_model/pull/24
+
+Independent fields may be loaded in an arbitrary order. But implementation-wise, this is to some degree predictable.
+
+computed_model 0.3 uses different dependency resolution algorithm and may produce different orders.
+As a result, if your model is accidentally order-dependent, it may break with computed_model 0.3.
+
+
+## Behavioral change: `ComputedModel::Model` now uses `ActiveSupport::Concern`
+
+It won't affect you if you simply did `include ComputedModel::Model` (previously `include ComputedModel`) and nothing more.
+Be cautious if you have a more complex inheritance/inclusion graph than that.
+
+
+## Recommendation: `#verify_dependencies`
+
+`#verify_dependencies` allows you to check the graph in the initialization process, rather than just before loading records.
+We recommend doing this at the end of the class definition.
+
+```ruby
+class User
+  define_loader ...
+
+  computed def ... end
+
+  verify_dependencies  # HERE
+end
+```