computed_model 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fbb65b996358c1bad2d9f03cde8c2fa0e326341d5ef6964a273370d111bc90f
-  data.tar.gz: 26869abf1e1ddf74b3c94e836d192379fdc1159328b9c260c14a8968b95ec9fd
+  metadata.gz: 827856e649d8af3b892979456fb1acbcfc9ab746934713422903e68342872371
+  data.tar.gz: 68b14dcca2f7e31880ac54b26e0f3c92bfeebf90ca9387be741f158d7fbeb5ee
 SHA512:
-  metadata.gz: bcc03d655e79ef7941b1fc765f9dc56c698aa1afa832c9dac43b409b7a104332a77d9d87ff288146bcb348597af225cc666320eac51d543805cd8d0c39f92a43
-  data.tar.gz: e0677afa15a0c1e0b33ce94e2543b9101a985ef2a9ce852c62e1bf69de54321f3fa825c38332a7e3f22810ac90f0beb8c4900ca8b4d509ed6607872028b5bb98
+  metadata.gz: 7a5ea72e1d06f357866dfde5a453591d43bad5a9ebd178cad88db09e351fc6ae3830d380514ee00ce582f45cb80339980e90c363298b910bfb2d2ccf3765008f
+  data.tar.gz: b2a953f74000b6b40f76ae43920e516c39c24856a2c29d89f63ee8253878c1c0ba847342b7915f134de6df3caa620f520f076951e10fed445726f793098153de

data/CHANGELOG.md

@@ -1,4 +1,7 @@
 ## Unreleased
+- **BREAKING CHANGE** Make define_loader more concise interface like GraphQL's DataLoader.
+- Introduce primary loader through `#define_primary_loader`.
+- **BREAKING CHANGE** Change `#bulk_load_and_compute` signature to support primary loader.
 
 ## 0.1.1
 

data/README.md

@@ -42,25 +42,54 @@ 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.
+  - Among them, there is a special **primary model** for listing up the models from certain criteria.
 - **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.
+Use `ComputedModel::ClassMethods#define_primary_loader`
+or `ComputedModel::ClassMethods#define_loader` to define loaded attributes.
 
 ```ruby
+# Create a User instance
+def initialize(raw_user)
+  @id = raw_user.id
+  @raw_user = raw_user
+end
+
 # 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
+define_primary_loader :raw_user do |subdeps, ids:, **options|
+  RawUser.where(id: ids).preload(subdeps).map { |raw_user| User.new(raw_user) }
+end
+
+# Example: pulling auxiliary data from ActiveRecord
+define_loader :user_aux_data, key: -> { id } do |user_ids, subdeps, **options|
+  UserAuxData.where(user_id: user_ids).preload(subdeps).group_by(&:id)
 end
 ```
 
+### `define_primary_loader`
+
+At most one primary loader can be defined on a model class.
+
+The primary loader's job is to list up models from user-defined criteria, along with
+requested data loaded to the primary attribute.
+
+Search criteria can be passed as a keyword argument to `bulk_load_and_compute`
+and it will be passed to the loader as-is.
+
+Most typically you receive `ids`, an array of integers, and use it like
+`.where(id: ids)`. Instead you may want to accept a non-primary-key criterion
+such as `group_ids` and `.where(group_id: group_ids)`.
+
+The loader must return an array of instances of the model being defined.
+Each instance must have the primary attribute assigned at that time.
+In the example above, the block for `define_primary_loader :raw_user`
+must return an array of `User`s, each of which already have `@raw_user`.
+
+### `define_loader`
+
 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.
 
@@ -94,13 +123,7 @@ 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
+  bulk_load_and_compute(Array(with), ids: ids)
 end
 ```
 
@@ -116,6 +139,8 @@ This library is distributed under MIT license.
 
 Copyright (c) 2020 Masaki Hara
 
+Copyright (c) 2020 Masayuki Izumi
+
 Copyright (c) 2020 Wantedly, Inc.
 
 ## Development

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

data/lib/computed_model.rb

@@ -27,6 +27,11 @@ module ComputedModel
   # A return value from {ComputedModel::ClassMethods#computing_plan}.
   Plan = Struct.new(:load_order, :subdeps_hash)
 
+  # An object for storing procs for loaded attributes.
+  Loader = Struct.new(:key_proc, :load_proc)
+
+  private_constant :Loader
+
   # A set of class methods for {ComputedModel}. Automatically included to the
   # singleton class when you include {ComputedModel}.
   module ClassMethods
@@ -136,7 +141,7 @@ module ComputedModel
       end
     end
 
-    # Declares a loaded attribute. See {#dependency} too.
+    # Declares a loaded attribute. See {#dependency} and {#define_primary_loader} too.
     #
     # `define_loader :foo do ... end` generates a reader `foo` and a writer `foo=`.
     # The writer is only meant to be used in the loader.
@@ -145,9 +150,45 @@ module ComputedModel
     # or set `computed_model_error` otherwise.
     #
     # @param meth_name [Symbol] the name of the loaded attribute.
+    # @param key [Proc] The proc to collect keys.
+    # @return [void]
+    # @yield [keys, subdeps, **options]
+    # @yieldparam objects [Array] The ids of the loaded attributes.
+    # @yieldparam subdeps [Hash] sub-dependencies
+    # @yieldparam options [Hash] A verbatim copy of what is passed to {#bulk_load_and_compute}.
+    # @yieldreturn [Hash]
+    #
+    # @example define a loader for ActiveRecord-based models
+    #   define_loader :user_aux_data, key: -> { id } do |user_ids, subdeps, **options|
+    #     UserAuxData.where(user_id: user_ids).preload(subdeps).group_by(&:id)
+    #   end
+    def define_loader(meth_name, key:, &block)
+      raise ArgumentError, "No block given" unless block
+
+      var_name = :"@#{meth_name}"
+
+      @__computed_model_loaders[meth_name] = Loader.new(key, 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
+
+    # Declares a primary attribute. See {#define_loader} and {#dependency} too.
+    #
+    # `define_primary_loader :foo do ... end` generates a reader `foo` and
+    # a writer `foo=`.
+    # The writer is only meant to be used in the loader.
+    #
+    # The responsibility of the primary loader is to list up all the relevant
+    # primary models, and initialize instances of the subclass of ComputedModel
+    # with `@foo` set to the primary model which is just being found.
+    #
+    # @param meth_name [Symbol] the name of the loaded attribute.
     # @return [void]
-    # @yield [objects, **options]
-    # @yieldparam objects [Array] The objects to preload the attribute into.
+    # @yield [**options]
     # @yieldparam options [Hash] A verbatim copy of what is passed to {#bulk_load_and_compute}.
     # @yieldreturn [void]
     #
@@ -160,12 +201,14 @@ module ComputedModel
     #       user.raw_user = raw_users[user.id]
     #     end
     #   end
-    def define_loader(meth_name, &block)
+    def define_primary_loader(meth_name, &block)
       raise ArgumentError, "No block given" unless block
+      raise ArgumentError, "Primary loader has already been defined" if @__computed_model_primary_attribute
 
       var_name = :"@#{meth_name}"
 
-      @__computed_model_loaders[meth_name] = block
+      @__computed_model_primary_loader = block
+      @__computed_model_primary_attribute = meth_name
 
       define_method(meth_name) do
         raise NotLoaded, "the field #{meth_name} is not loaded" unless instance_variable_defined?(var_name)
@@ -176,26 +219,44 @@ module ComputedModel
 
     # The core routine for batch-loading.
     #
-    # @param objs [Array] The objects to preload attributes into.
     # @param deps [Array<Symbol, Hash{Symbol=>Array}>] A set of dependencies.
     # @param options [Hash] An arbitrary hash to pass to loaders
     #   defined by {#define_loader}.
-    # @return [void]
-    def bulk_load_and_compute(objs, deps, **options)
-      objs = objs.dup
+    # @return [Array<Object>] The array of the requested models.
+    #   Based on what the primary loader returns.
+    def bulk_load_and_compute(deps, **options)
+      unless @__computed_model_primary_attribute
+        raise ArgumentError, "No primary loader defined"
+      end
+
+      objs = orig_objs = nil
       plan = computing_plan(deps)
       plan.load_order.each do |dep_name|
-        if @__computed_model_dependencies.key?(dep_name)
+        if @__computed_model_primary_attribute == dep_name
+          orig_objs = @__computed_model_primary_loader.call(plan.subdeps_hash[dep_name], **options)
+          objs = orig_objs.dup
+        elsif @__computed_model_dependencies.key?(dep_name)
+          raise "Bug: objs is nil" if objs.nil?
+
           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)
+          raise "Bug: objs is nil" if objs.nil?
+
+          l = @__computed_model_loaders[dep_name]
+          keys = objs.map { |o| o.instance_exec(&(l.key_proc)) }
+          subobj_by_key = l.load_proc.call(keys, plan.subdeps_hash[dep_name], **options)
+          objs.zip(keys) do |obj, key|
+            obj.send(:"#{dep_name}=", subobj_by_key[key])
+          end
         else
           raise "No dependency info for #{self}##{dep_name}"
         end
         objs.reject! { |obj| !obj.computed_model_error.nil? }
       end
+
+      orig_objs
     end
 
     # @param deps [Array]
@@ -206,6 +267,12 @@ module ComputedModel
       subdeps_hash = {}
       visiting = Set[]
       visited = Set[]
+      if @__computed_model_primary_attribute
+        load_order << @__computed_model_primary_attribute
+        visiting.add @__computed_model_primary_attribute
+        visited.add @__computed_model_primary_attribute
+        subdeps_hash[@__computed_model_primary_attribute] ||= []
+      end
       normalized.each do |dep_name, dep_subdeps|
         computing_plan_dfs(dep_name, dep_subdeps, load_order, subdeps_hash, visiting, visited)
       end
@@ -271,5 +338,7 @@ module ComputedModel
     klass.extend ClassMethods
     klass.instance_variable_set(:@__computed_model_dependencies, {})
     klass.instance_variable_set(:@__computed_model_loaders, {})
+    klass.instance_variable_set(:@__computed_model_primary_loader, nil)
+    klass.instance_variable_set(:@__computed_model_primary_attribute, nil)
   end
 end

data/lib/computed_model/version.rb

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

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: computed_model
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Masaki Hara
+- Masayuki Izumi
 - Wantedly, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-16 00:00:00.000000000 Z
+date: 2020-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,6 +63,7 @@ description: |
   ActiveRecord and remote server (such as ActiveResource).
 email:
 - ackie.h.gmai@gmail.com
+- m@izum.in
 - dev@wantedly.com
 executables: []
 extensions: []