computed_model 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d4c9e19dfb66454b769cf0cb92e95fb01de3aeace7276953182fcebf82fdcd2
-  data.tar.gz: 836d822953b14420ee7ed6f4dd3d17fba896b41e2caa638eb4fe9e1d59323df5
+  metadata.gz: 5fbb65b996358c1bad2d9f03cde8c2fa0e326341d5ef6964a273370d111bc90f
+  data.tar.gz: 26869abf1e1ddf74b3c94e836d192379fdc1159328b9c260c14a8968b95ec9fd
 SHA512:
-  metadata.gz: e1d34a7a00c560ea97d96927e643d40e02164f94181601e39bcde334cd86f9c5f618c7d6c62556adb5331f2f3f8e61bc015d295f82ee03237d75d4dc8c1d3240
-  data.tar.gz: 556daff44be9ae2408c9e5d11590fecd440d802067071b53563ee6646ca01296bafa01944df8e691bc770f9c7b613a66631cf60cffa5472abb9673b1ef82b95c
+  metadata.gz: bcc03d655e79ef7941b1fc765f9dc56c698aa1afa832c9dac43b409b7a104332a77d9d87ff288146bcb348597af225cc666320eac51d543805cd8d0c39f92a43
+  data.tar.gz: e0677afa15a0c1e0b33ce94e2543b9101a985ef2a9ce852c62e1bf69de54321f3fa825c38332a7e3f22810ac90f0beb8c4900ca8b4d509ed6607872028b5bb98

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Unreleased
 
+## 0.1.1
+
+- Expand docs.
+- Add `ComputedModel#computed_model_error` for load cancellation
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -12,7 +12,7 @@ ActiveRecord and remote server (such as ActiveResource).
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'computed_model'
+gem 'computed_model', '~> 0.1.1'
 ```
 
 And then execute:
@@ -115,6 +115,7 @@ users = User.list([1, 2, 3], with: [:name, :name_with_playing_music, :premium_us
 This library is distributed under MIT license.
 
 Copyright (c) 2020 Masaki Hara
+
 Copyright (c) 2020 Wantedly, Inc.
 
 ## Development
@@ -125,4 +126,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/lib/computed_model.rb

@@ -3,19 +3,71 @@
 require "computed_model/version"
 require 'set'
 
+# A mixin for batch-loadable compound models.
+#
+# @example typical structure of a computed model
+#   class User
+#     include ComputedModel
+#
+#     attr_reader :id
+#     def initialize(id)
+#       @id = id
+#     end
+#
+#     define_loader do ... end
+#
+#     dependency :foo, :bar
+#     computed def something ... end
+#   end
 module ComputedModel
+  # An error raised when you tried to read from a loaded/computed attribute,
+  # but that attribute isn't loaded by the batch loader.
   class NotLoaded < StandardError; end
 
+  # A return value from {ComputedModel::ClassMethods#computing_plan}.
   Plan = Struct.new(:load_order, :subdeps_hash)
 
+  # A set of class methods for {ComputedModel}. Automatically included to the
+  # singleton class when you include {ComputedModel}.
   module ClassMethods
-    # @param deps [Array]
+    # Declares the dependency of a computed attribute. See {#computed} too.
+    #
+    # @param deps [Array<Symbol, Hash{Symbol=>Array}>]
+    #   Dependency description. If a symbol `:foo` is given,
+    #   it's interpreted as `{ foo: [] }`.
+    #   When the same symbol occurs multiple times, the array is concatenated.
+    #   The contents of the array (called "sub-dependency") is treated opaquely
+    #   by the `computed_model` gem. It is up to the user to design the format
+    #   of sub-dependencies.
+    # @return [void]
+    #
+    # @example declaring dependencies
+    #   dependency :user, :user_external_resource
+    #   computed def something
+    #     # Use user and user_external_resource ...
+    #   end
+    #
+    # @example declaring dependencies with sub-dependencies
+    #   dependency user: [:user_names, :premium], user_external_resource: [:received_stars]
+    #   computed def something
+    #     # Use user and user_external_resource ...
+    #   end
     def dependency(*deps)
       @__computed_model_next_dependency ||= []
       @__computed_model_next_dependency.push(*deps)
     end
 
-    # @param meth_name [Symbol]
+    # Declares a computed attribute. See {#dependency} too.
+    #
+    # @param meth_name [Symbol] a method name to promote to a computed attribute.
+    #   Typically used in the form of `computed def ...`.
+    # @return [Symbol] passes through the argument.
+    #
+    # @example define a field which is calculated from loaded models
+    #   dependency :user, :user_external_resource
+    #   computed def something
+    #     # Use user and user_external_resource ...
+    #   end
     def computed(meth_name)
       var_name = :"@#{meth_name}"
       meth_name_orig = :"#{meth_name}_orig"
@@ -43,12 +95,25 @@ module ComputedModel
       meth_name
     end
 
-    # @param methods [Array<Symbol>]
-    # @param to [Symbol]
-    # @param allow_nil [nil, Boolean]
-    # @param prefix [nil, Symbol]
-    # @param include_subdeps [nil, Boolean]
+    # A shorthand for simple computed attributes.
+    #
+    # Use {#computed} for more complex definition.
+    #
+    # @param methods [Array<Symbol>] method names to delegate
+    # @param to [Symbol] which attribute to delegate the methods to.
+    #   This parameter is used for the dependency declaration too.
+    # @param allow_nil [nil, Boolean] If `true`,
+    #   nil receivers are is ignored, and nil is returned instead.
+    # @param prefix [nil, Symbol] A prefix for the delegating method name.
+    # @param include_subdeps [nil, Boolean] If `true`,
+    #   sub-dependencies are also included.
     # @return [void]
+    #
+    # @example delegate name from raw_user
+    #   delegate_dependency :name, to: :raw_user
+    #
+    # @example delegate name from raw_user, but expose as user_name
+    #   delegate_dependency :name, to: :raw_user, prefix: :user
     def delegate_dependency(*methods, to:, allow_nil: nil, prefix: nil, include_subdeps: nil)
       method_prefix = prefix ? "#{prefix_}" : ""
       methods.each do |meth_name|
@@ -71,10 +136,30 @@ module ComputedModel
       end
     end
 
-    # @param meth_name [Symbol]
-    # @yieldparam objects [Array]
-    # @yieldparam options [Hash]
+    # Declares a loaded attribute. See {#dependency} 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.
+    #
+    # The responsibility of loader is to call `foo=` for all the given objects,
+    # or set `computed_model_error` otherwise.
+    #
+    # @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.
+    # @yieldparam options [Hash] A verbatim copy of what is passed to {#bulk_load_and_compute}.
     # @yieldreturn [void]
+    #
+    # @example define a loader for ActiveRecord-based models
+    #   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
     def define_loader(meth_name, &block)
       raise ArgumentError, "No block given" unless block
 
@@ -89,9 +174,15 @@ module ComputedModel
       attr_writer meth_name
     end
 
-    # @param objs [Array]
-    # @param deps [Array]
+    # 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
       plan = computing_plan(deps)
       plan.load_order.each do |dep_name|
         if @__computed_model_dependencies.key?(dep_name)
@@ -103,6 +194,7 @@ module ComputedModel
         else
           raise "No dependency info for #{self}##{dep_name}"
         end
+        objs.reject! { |obj| !obj.computed_model_error.nil? }
       end
     end
 
@@ -168,6 +260,12 @@ module ComputedModel
     normalized
   end
 
+  # An error field to prevent {ComputedModel::ClassMethods#bulk_load_and_compute}
+  # from loading remaining attributes.
+  #
+  # @return [StandardError]
+  attr_accessor :computed_model_error
+
   def self.included(klass)
     super
     klass.extend ClassMethods

data/lib/computed_model/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: computed_model
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Masaki Hara
@@ -70,6 +70,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - README.md