strict_lazy 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e9db46fd9beb35a23ac710e80c9ae7fddebdc576e399bcc4c249bc22a8acb7b
-  data.tar.gz: 3eb3eb6e31b616914a06accca417608e62919d20b0ec8768f12d538fd0874479
+  metadata.gz: e52f77c57f79c210c07cb64b06b8a156078ac6a39a4326e75c2a57bc4e686c18
+  data.tar.gz: 7921a8cabbe73770a442cd449ab26d0c9b4259b7e08ec7cfc52e621cd37ba304
 SHA512:
-  metadata.gz: 34d9415e1488ca61c7a8476cf372fd14e52aba5c6e67b33a863a15d9ee05386dc406b143648ef0278427938d9eb6d61c2e7691cecadf4487aa6b62d3febd0a91
-  data.tar.gz: d808ab15745e130af97ad8ba0dca0c5189e8e274fdb0a5455dda2cd64378f172faf77c99b5548080e82f17b92d15e1d4fa359520d8ed36c6d2e062a0a02f6986
+  metadata.gz: d7e11f8f5d3da3ab4c6c479b0716b4d71d501b2f66496ca66284594df6a1a2cfefdba36ff23b5fc00fac11365a37eb6701b165df195e876e7f5d3676d9e4bc1c
+  data.tar.gz: 6041ef114555d858c0cd3078e0847f20f726c58120c6ad1aebd2b2e9d62637922ce9b09bbc1a67d7c2854f37d8c826732bbab3d1dd8e6fbb02176b97543d1fae

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-16
+
+### Added
+
+- Nested preload: `StrictLazy.preload` now accepts a Rails-style spec, so lazy
+  values on associated records can be prepared in one call —
+  `StrictLazy.preload(posts, :comments_count, comments: [:reply_count, { replies: :shout }])`.
+  Associations are batch-loaded to avoid N+1; nesting is arbitrarily deep.
+
+### Changed
+
+- `StrictLazy.preload` groups records by STI base class, so a mixed-class array
+  (STI subtrees, or children gathered across associations) resolves each loader
+  once per declaring class. Single-model calls are unchanged.
+
 ## [0.3.0] - 2026-06-14
 
 ### Added

data/README.md

@@ -73,6 +73,32 @@ StrictLazy.preload(@posts)            # all declared loaders
 <img src="<%= post.lazy.avatar %>">
 ```
 
+## Nested preload
+
+To prepare lazy values on associated records, pass a Hash to `preload`. The keys
+are associations to traverse; the values are the spec to apply to the associated
+records (a reader, a Hash, or an array mixing both — the same grammar as the
+top level). This mirrors ActiveRecord's `preload` spec.
+
+```ruby
+# comments and replies each declare their own lazy_load readers
+StrictLazy.preload(@posts,
+  :comments_count,                              # reader on @posts
+  comments: [:reply_count, { replies: :shout }] # reader on comments + nested
+)
+```
+
+- Plain symbols apply to the current level; Hash keys descend into associations.
+- A Hash-only call (`StrictLazy.preload(@posts, comments: :reply_count)`)
+  prepares nothing on `@posts` itself — only the children.
+- Associations are batch-loaded to avoid N+1. If the records aren't
+  ActiveRecord-backed (e.g. unsaved), preload the association yourself first.
+- Records may mix classes (STI subtrees, children gathered across associations);
+  they are grouped by STI base class so each resolver runs once per class.
+- This traverses **associations** only. Chaining a lazy reader into another lazy
+  preload (lazy→lazy) is out of scope — collect those records yourself and call
+  `preload` again.
+
 ## Eager vs lazy (`sync:`)
 
 - `sync: false` (default): resolution is deferred to the first `.lazy` read, then
@@ -173,6 +199,18 @@ A static value (`default: 0`) is written as-is.
   name or a `?` predicate — the read-only `.lazy` namespace rejects setter (`=`),
   bang (`!`), and operator reader names at declaration time.
 
+## Agent skill
+
+This repo ships an [agent skill](skills/strict-lazy/) (`SKILL.md`, plus a
+Japanese `SKILL-ja.md`) that teaches coding agents when and how to apply
+`strict_lazy`. Install it into your project with the GitHub CLI:
+
+```sh
+gh skill install aki77/strict_lazy
+```
+
+> `gh skill` is currently a GitHub CLI preview feature.
+
 ## Non-Rails usage
 
 Works without Rails: `include StrictLazy`, declare with `lazy_load`, call

data/lib/strict_lazy/preloader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # Drives +StrictLazy.preload+: interprets the Rails-style spec, prepares each
+  # level's readers (grouped by STI base class), and traverses associations to
+  # descend into nested records. One instance handles a single level of records;
+  # nested levels are handled by recursing into fresh instances.
+  class Preloader
+    # Prepare +spec+ on +records+. See +StrictLazy.preload+ for the spec grammar.
+    def self.call(records, spec)
+      records = Array(records)
+      return records if records.empty?
+
+      new(records).call(spec)
+      records
+    end
+
+    def initialize(records)
+      @records = records
+    end
+
+    def call(spec)
+      hashes, readers = spec.partition { |element| element.is_a?(Hash) }
+
+      preload_here(readers) if prepare_this_level?(spec, readers)
+
+      hashes.flat_map(&:to_a).each do |association, sub_spec|
+        children = traverse(association)
+        # Array.wrap (not Kernel#Array) so a Hash sub-spec stays a single element
+        # ([hash]) instead of being split into key/value pairs.
+        self.class.call(children, Array.wrap(sub_spec))
+      end
+    end
+
+    private
+
+    # An empty spec means "all loaders" (the historical no-args behavior); a
+    # Hash-only spec prepares nothing here and only descends into children.
+    def prepare_this_level?(spec, readers)
+      spec.empty? || readers.any?
+    end
+
+    # Prepare +readers+ on this level, grouping by STI base class so each loader's
+    # resolver runs once per declaring class with the correct dispatch receiver.
+    def preload_here(readers)
+      @records.group_by { |record| base_model_for(record) }.each do |model, group|
+        loaders_for(model, readers).each do |loader|
+          batch = Batch.new(model, group, loader)
+          group.each { |record| record.instance_variable_set(loader.batch_ivar, batch) }
+          batch.resolve! if loader.sync?
+        end
+      end
+    end
+
+    # The STI base class (the class the loaders are declared on) for a record,
+    # falling back to its class when +base_class+ is unavailable.
+    def base_model_for(record)
+      klass = record.class
+      klass.respond_to?(:base_class) ? klass.base_class : klass
+    end
+
+    # Follow an association across every record and return the flattened
+    # children. belongs_to/has_one (singular or nil) and has_many are unified via
+    # Array.wrap. When the records are ActiveRecord-backed, the association is
+    # batch-preloaded first to avoid N+1; otherwise we rely on the caller having
+    # already preloaded it.
+    def traverse(association)
+      # Reflection lives on the base class and is uniform across the group, so
+      # inspecting the first record is enough here (unlike preload_here, which
+      # must group every record by class to dispatch resolvers correctly).
+      klass = base_model_for(@records.first)
+      unless klass.respond_to?(:reflect_on_association) && klass.reflect_on_association(association)
+        raise ArgumentError, "StrictLazy.preload: #{klass}##{association} is not an association"
+      end
+
+      preload_association(association)
+      # Array.wrap turns nil/singular/has_many into a flat element list; an absent
+      # singular association yields [], so no compact is needed.
+      @records.flat_map { |record| Array.wrap(record.public_send(association)) }
+    end
+
+    # Batch-preload an ActiveRecord association to avoid N+1. No-op (degrading to
+    # the caller's own preloading) when the Preloader is unavailable.
+    def preload_association(association)
+      return unless defined?(ActiveRecord::Associations::Preloader)
+
+      ActiveRecord::Associations::Preloader.new(records: @records, associations: association).call
+    end
+
+    def loaders_for(model, readers)
+      all = model.lazy_loaders
+      readers.empty? ? all.values : readers.map { |r| all.fetch(r) }
+    end
+  end
+end

data/lib/strict_lazy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StrictLazy
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/strict_lazy.rb

@@ -4,12 +4,14 @@ require "active_support"
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/module/attribute_accessors_per_thread"
+require "active_support/core_ext/array/wrap"
 
 require_relative "strict_lazy/version"
 require_relative "strict_lazy/errors"
 require_relative "strict_lazy/loader"
 require_relative "strict_lazy/batch"
 require_relative "strict_lazy/facade"
+require_relative "strict_lazy/preloader"
 
 # strict_lazy applies the spirit of Rails' +strict_loading+ to computed values.
 # Include it in a model, declare values with +lazy_load+, prepare them in the
@@ -130,27 +132,29 @@ module StrictLazy
   end
   private_class_method :validate_violation!
 
-  # Prepare lazy values for a group of records. With no readers, prepares every
-  # declared loader. +sync: true+ loaders resolve immediately; others on first read.
-  def self.preload(records, *readers)
-    records = Array(records)
-    return records if records.empty?
-
-    model = records.first.class
-    loaders_for(model, readers).each do |loader|
-      batch = Batch.new(model, records, loader)
-      records.each { |record| record.instance_variable_set(loader.batch_ivar, batch) }
-      batch.resolve! if loader.sync?
-    end
-
-    records
-  end
-
-  def self.loaders_for(model, readers)
-    all = model.lazy_loaders
-    readers.empty? ? all.values : readers.map { |r| all.fetch(r) }
+  # Prepare lazy values for a group of records.
+  #
+  # The +spec+ is a Rails-style list (mirroring ActiveRecord's +preload+): each
+  # element is either a reader name (Symbol) prepared on the given records, or a
+  # Hash whose keys are associations to traverse and whose values are the spec to
+  # apply recursively to the associated records. A Hash value may itself be a
+  # Symbol, a Hash, or an array mixing both — so a single level can prepare its
+  # own readers and descend into nested associations at once:
+  #
+  #   StrictLazy.preload(posts,
+  #     :comments_count,                              # reader on posts
+  #     comments: [:score, { replies: :like_count }] # reader on comments + nested
+  #   )
+  #
+  # With no spec at all, every declared loader on the records is prepared.
+  # +sync: true+ loaders resolve immediately; others on first read.
+  #
+  # Records may mix classes (e.g. STI subtrees, or children gathered across
+  # associations): they are grouped by their STI base class so each loader's
+  # resolver runs once per declaring class.
+  def self.preload(records, *spec)
+    Preloader.call(records, spec)
   end
-  private_class_method :loaders_for
 end
 
 require_relative "strict_lazy/railtie" if defined?(Rails::Railtie)

data/skills/strict-lazy/references/api-ja.md

@@ -87,18 +87,29 @@ lazy_load :slug, default: ->(record) { "p-#{record.id}" } do ... end   # レコ
 ## `StrictLazy.preload`
 
 ```ruby
-StrictLazy.preload(records, *readers)
+StrictLazy.preload(records, *spec)
 ```
 
 - `records` — レコード配列 (単体も `Array()` でラップされる)。`ActiveRecord::Relation` もそのまま渡せる（内部の `Array()` が評価するので `.to_a` 不要）。空なら何もしない。
-- `readers` 省略時は **宣言済みの全ローダー** を準備。指定すると一部だけ。
+- `spec` — Rails 流のリスト（ActiveRecord の `preload` と同じ流儀）。各要素は次のいずれか:
+  - **reader 名** (Symbol) — `records` に対して準備、または
+  - **Hash** — キーは辿る関連、値はその関連先レコードに（再帰的に）適用する spec。Hash の値は Symbol・Hash・両者を混在した配列のいずれも可。
+- `spec` が **完全に空** のときは `records` に **宣言済みの全ローダー** を準備。Hash だけの spec（例 `preload(posts, comments: :reply_count)`）は `records` 自身には **何も準備せず**、子だけを準備する。
 - 各ローダーについて `Batch` を作り、全レコードの `@_batch_<reader>` にセット。
   `sync: true` のものはここで即 `resolve!`。
-- モデルは `records.first.class` から決まる。**同一モデルのレコード群** を渡す前提。
+- レコードは **STI ベースクラス**（`class.base_class`）でグループ化され、各ローダーのリゾルバは宣言クラスごとに1回走る。混在クラスの配列（STI サブツリーや、関連を跨いで集めた子）も正しく扱える。
+- 関連を辿る際は `ActiveRecord::Associations::Preloader` で一括ロードして N+1 を回避する。AR でないレコードはこれをスキップ（自分で関連を先に preload しておくこと）。関連でない名前を辿ろうとすると `ArgumentError`。
+
+```ruby
+# posts の reader + comments の reader + comments.replies の reader
+StrictLazy.preload(@posts, :comments_count, comments: [:reply_count, { replies: :shout }])
+```
 
 注意: 同じローダーを **重複するグループに2回 preload** すると、その分リゾルバが複数回走る。
 ビューで読むコレクションを1回でカバーするように呼ぶ。
 
+対象外: lazy reader の結果をさらに lazy preload に繋ぐ（lazy→lazy）ケースは非対応。`preload` が辿るのは **関連** のみ。`lazy_load` がレコードを返しそれをさらに preload したい場合は、自分でそれらを集めて再度 `preload` を呼ぶ。
+
 ### Relation をそのまま渡してよい理由
 
 `preload` は各レコードオブジェクトに `@_batch_<reader>` ivar を書き込むため、preload するレコードとビューで読むレコードは **同一オブジェクト** である必要がある。`Relation` はこれを満たす:

data/skills/strict-lazy/references/api.md

@@ -79,16 +79,27 @@ Passing a mutable value directly like `default: []` shares the same object acros
 ## `StrictLazy.preload`
 
 ```ruby
-StrictLazy.preload(records, *readers)
+StrictLazy.preload(records, *spec)
 ```
 
 - `records` — array of records (single records are wrapped with `Array()`). An `ActiveRecord::Relation` can also be passed directly — the internal `Array()` evaluates it (no `.to_a` needed). Does nothing if empty.
-- When `readers` is omitted, **all declared loaders** are prepared. Specify to prepare only a subset.
+- `spec` — a Rails-style list (mirrors ActiveRecord's `preload`). Each element is either:
+  - a **reader name** (Symbol) — prepared on `records`, or
+  - a **Hash** — keys are associations to traverse, values are the spec applied to the associated records (recursively). A Hash value may be a Symbol, a Hash, or an array mixing both.
+- When `spec` is **entirely empty**, **all declared loaders** on `records` are prepared. A Hash-only spec (e.g. `preload(posts, comments: :reply_count)`) prepares **nothing** on `records` itself — only the children.
 - Creates a `Batch` for each loader and sets it on `@_batch_<reader>` for all records. Loaders with `sync: true` are immediately `resolve!`'d here.
-- The model is determined from `records.first.class`. Assumes a **group of records of the same model**.
+- Records are grouped by **STI base class** (`class.base_class`), so each loader's resolver runs once per declaring class. A mixed-class array (STI subtrees, or children gathered across associations) is handled correctly.
+- Associations are batch-loaded via `ActiveRecord::Associations::Preloader` to avoid N+1 while traversing. Non-AR records skip this (preload the association yourself first). Traversing a name that isn't an association raises `ArgumentError`.
+
+```ruby
+# reader on posts + reader on comments + reader on comments.replies
+StrictLazy.preload(@posts, :comments_count, comments: [:reply_count, { replies: :shout }])
+```
 
 Note: **preloading the same loader for overlapping groups twice** causes the resolver to run multiple times. Call it once to cover the collection you read in the view.
 
+Out of scope: chaining a lazy reader's result into another lazy preload (lazy→lazy). `preload` traverses **associations** only. If a `lazy_load` returns records you want to preload further, collect them yourself and call `preload` again.
+
 ### Why passing a `Relation` directly works
 
 `preload` writes the `@_batch_<reader>` ivar onto each record object, so the records you preload and the records you read in the view must be the **same objects**. A `Relation` satisfies this:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_lazy
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - aki77
@@ -44,6 +44,7 @@ files:
 - lib/strict_lazy/errors.rb
 - lib/strict_lazy/facade.rb
 - lib/strict_lazy/loader.rb
+- lib/strict_lazy/preloader.rb
 - lib/strict_lazy/railtie.rb
 - lib/strict_lazy/version.rb
 - sig/strict_lazy.rbs