familia 2.8.0 → 2.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6cb1ccd59d4290c1d75b70e114945180fc5dbb03aaeb405d841c250cd504179
-  data.tar.gz: c2bd7946e7e024c8322d0bf48bea39c22cd61c7690589007f9ab32e6f12e614d
+  metadata.gz: d24c3b38092f1192f8e250553e8ef4d51b05c1bb00c48dfd7f6520d3a48a9a0e
+  data.tar.gz: 1dd0a2aa47682736209f116adf378eb4a0eccafffd7c151b02a8ef4573e52551
 SHA512:
-  metadata.gz: 54d3c3020c53fe01de9baf6af78fbcc1ffbea72a671b6e6269c08c9c5eaab786bb267514aa64212ff8ec854e0363cfb1c1de9b9c66674e57cb067ed419a8944b
-  data.tar.gz: d8b8ecd85ed1273c64ae75cab7559dee0ddb92fe5d552b60690c3a66ee9df93b3829aa32deef5438677ad9fb8d9acebb0bdbf071f3bccdb63161c4a772b1c021
+  metadata.gz: 10d69edb30370c7dba83b387f53429878fded6bf736e04fbefec4c228baf375806eeefa6c1d44c45c296e5d79b82345d1bc9cfbb0992ee18fc4c204dac250e10
+  data.tar.gz: 9b52e601ae93d44a6db8b0f995828ae45d55872377a471658a8d63210607c56f70958e372654ac20a13b07344e9b9da0afcdaaa50203f0796326d5d08e93bf6b

data/CHANGELOG.rst

@@ -7,6 +7,111 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.9.1:
+
+2.9.1 — 2026-05-18
+==================
+
+Added
+-----
+
+- ``SortedSet#update`` (aliased ``merge!``) for bulk member insertion. A sorted
+  set is ``member => score`` -- the same pair shape as ``HashKey``'s
+  ``field => value`` -- so it follows the established ``HashKey#update``/``merge!``
+  convention (a single Hash argument) rather than the variadic splat used by the
+  value-only ``UnsortedSet``/``ListKey``. Pass ``{member => score}`` to issue one
+  ``ZADD`` instead of one round-trip per member. Validates the argument is a Hash
+  and that every score is ``Numeric`` (a missing/``nil`` score raises a clear
+  ``ArgumentError`` instead of a low-level client error -- unlike single-value
+  ``#add``, the bulk path does not default a missing score to ``Familia.now``).
+  Cascades expiration, and is a no-op returning ``0`` for empty input. The
+  single-value ``SortedSet#add`` (and its array-as-single-member contract) is
+  unchanged. PR #269
+
+Changed
+-------
+
+- Bulk-write optimization for multi-value collection mutations. ``UnsortedSet#add``,
+  ``ListKey#push``, and ``ListKey#unshift`` previously issued one Redis command per
+  element (a loop of ``SADD``/``RPUSH``/``LPUSH`` calls), making large populations
+  slow even when pipelined. They now serialize all values and issue a single bulk
+  ``SADD``/``RPUSH``/``LPUSH`` command. Element ordering, ``nil`` compaction, nested
+  array flattening, return values, dirty-write warnings, and expiration cascading
+  are unchanged; empty calls remain no-ops. PR #269
+
+AI Assistance
+-------------
+
+- AI investigated all collection ``DataType`` classes for the same per-element
+  loop anti-pattern, identified the three affected methods, verified
+  behavior-preservation (ordering, edge cases, chainability) at the Redis wire
+  level, and confirmed zero regressions against the existing test suites. The
+  ``SortedSet#update`` API shape was chosen by priority order: existing Familia
+  conventions first (the ``HashKey#update``/``merge!`` precedent for keyed
+  collections), then the upstream redis-rb bulk ``ZADD`` form, then Ruby
+  ``Hash#merge!`` semantics as confirmation.
+
+.. _changelog-2.9.0:
+
+2.9.0 — 2026-05-17
+==================
+
+Added
+-----
+
+- Batch iteration primitives for DataTypes via ``Enumerable`` integration:
+
+  - All DataTypes (``SortedSet``, ``HashKey``, ``UnsortedSet``, ``ListKey``) now
+    ``include Enumerable``, providing ``each_slice``, ``lazy``, ``map``, ``reduce``,
+    ``find``, and other stdlib methods.
+
+  - **SortedSet#each(since:, until:)**: Cursor-based iteration with optional
+    timestamp bounds. Uses ZRANGEBYSCORE when bounds provided (inclusive),
+    ZSCAN otherwise. Accepts Time objects or numeric scores.
+
+  - **HashKey#each(matching:)**: Cursor-based iteration via HSCAN with optional
+    glob pattern filter on field names.
+
+  - **UnsortedSet#each(matching:)**: Cursor-based iteration via SSCAN with optional
+    glob pattern filter using Redis SSCAN MATCH on raw values.
+
+  - **ListKey#each(batch_size:)**: Memory-efficient LRANGE pagination for large lists.
+
+- ``DataType#each_record(batch_size:, write_size:, **filters)`` yields loaded
+  Horreum records (not raw IDs) via ``load_multi``. Ghost instances (expired keys
+  still in ``instances``) are automatically filtered. The ``write_size:`` parameter
+  controls pipelining depth (``nil`` for serial execution).
+
+- ``Familia::BatchResult`` value type for aggregating batch operation results:
+
+  - ``BatchResult.collect(enumerable, strict: false) { |record| ... }`` iterates
+    any Enumerable, tracking ``scanned``, ``modified`` (truthy returns), ``errors``
+    (array of ``{id:, error:}``), and ``duration_ms``.
+
+  - Per-record exception isolation: errors are captured and iteration continues.
+
+  - ``strict: true`` re-raises collected errors after iteration completes.
+
+Changed
+-------
+
+- Renamed batch field-update methods for clarity:
+
+  - ``batch_update`` is now ``multi_field_update``
+  - ``batch_fast_write`` is now ``multi_field_fast_write``
+
+  Old names removed without deprecation shim (breaking change).
+
+- Moved ``MultiResult`` into Familia namespace as ``Familia::MultiResult``.
+  Old top-level constant removed without backwards-compat alias (breaking change).
+
+AI Assistance
+-------------
+
+- Implementation and test coverage developed with parallel Claude Code agents:
+  one for production code (DataType iteration, BatchResult, renames), one for
+  Tryouts test suite (228 new tests across 8 files). PR #264.
+
 .. _changelog-2.8.0:
 
 2.8.0 — 2026-05-15

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    familia (2.8.0)
+    familia (2.9.1)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
       json_schemer (~> 2.0)
       logger (~> 1.7)
       oj (~> 3.16)
-      redis (>= 4.8.1, < 6.0)
+      redis (>= 5.0, < 6.0)
       stringio (~> 3.1.1)
       uri-valkey (~> 1.4)
 

data/docs/guides/datatype-collections.md

@@ -0,0 +1,159 @@
+# docs/guides/datatype-collections.md
+---
+
+# DataType - Collection classes
+
+UnsortedSet, Sorted Set, List, and Hash data types all include the `Collection` module. This guide covers two performance-sensitive concerns: writing many elements efficiently (a single bulk command instead of one round-trip per element), and iterating large collections efficiently via `each` and `each_record`.
+
+## Bulk writes — single round-trip mutations
+
+Collection mutations are **immediate** — every call hits Valkey/Redis right away, unlike scalar `field` setters which are deferred until `save`. Each call also runs `warn_if_dirty!` and cascades expiration. (See the write-model notes in `CLAUDE.md` for the deferred-vs-immediate split.)
+
+Multi-element adds issue **one** command for the whole batch, not one per element. Populating a large collection is therefore a single round-trip even without an explicit pipeline.
+
+The argument shape follows the collection's structure, and is consistent across the codebase:
+
+- **Value-only** collections (`UnsortedSet`, `ListKey`) take a **variadic splat**; arguments are flattened and `nil`-compacted.
+- **Keyed/pair** collections (`HashKey` is `field => value`, `SortedSet` is `member => score`) take a **single Hash** via `update` (aliased `merge!`), raising `ArgumentError` on a non-Hash.
+
+| Type | Bulk method | Call shape | Redis command |
+|---|---|---|---|
+| `UnsortedSet` | `add(*values)` | `tags.add(:a, :b, :c)` | one `SADD` |
+| `ListKey` | `push(*values)` / `unshift(*values)` | `log.push(1, 2, 3)` | one `RPUSH` / `LPUSH` |
+| `HashKey` | `update(hash)` / `merge!` | `cfg.update(a: 1, b: 2)` | one `HMSET` |
+| `SortedSet` | `update(hash)` / `merge!` | `board.update("alice" => 1000, "bob" => 850)` | one `ZADD` |
+
+```ruby
+tags.add(:ruby, :redis, :valkey)              # 1 SADD, returns self
+log.push("a", "b", "c")                        # 1 RPUSH → [a, b, c]
+board.update("alice" => 1000, "bob" => 850)    # 1 ZADD, returns new-member count (2)
+board.merge!("alice" => 1200)                  # 1 ZADD, score updated → returns 0
+```
+
+Behavior notes:
+
+- **Ordering**: `push` preserves argument order; `unshift` prepends each element in turn, so `unshift(a, b, c)` leaves the list head as `c, b, a` (Redis `LPUSH` semantics — unchanged from the prior per-element implementation). Sets are unordered; sorted sets order by score.
+- **Empty input is a no-op**: `add()` / `push()` / `update({})` issue no command. Set/list adds return `self`; `SortedSet#update` returns `0`.
+- **`SortedSet#add(val, score, …)` is unchanged and not bulk** — it takes a single member plus score and the conditional ZADD options (`nx:`, `xx:`, `gt:`, `lt:`, `ch:`). An Array passed as `val` is stored as one JSON-encoded member, not exploded into many. Use `update`/`merge!` for bulk insertion.
+
+The iteration methods `each` and `each_record` efficiently handle large collections by paginating through Valkey/Redis data structures, but they serve different purposes and yield different results. Here's how the two iterate, using `ModelClass.instances` (a `SortedSet` with `reference: true`) as the running example.
+
+## `each` — yields **members** (identifiers, raw strings)
+
+`each` is implemented per type. For the `instances` SortedSet, it pages through the ZSET with either `ZRANGEBYSCORE` (when `since:`/`until:` are given) or `ZSCAN` (unbounded), yielding one deserialized member at a time.
+
+```mermaid
+flowchart TD
+  Caller["ModelClass.instances.each { |id| ... }"] --> EachImpl["SortedSet#each"]
+  EachImpl --> Decide{since/until?}
+  Decide -- yes --> ZRBS["ZRANGEBYSCORE key min max LIMIT 0 batch_size WITHSCORES"]
+  Decide -- no --> ZSCAN["ZSCAN key cursor COUNT batch_size"]
+  ZRBS --> Page["Page of raw members"]
+  ZSCAN --> Page
+  Page --> Yield["yield deserialize_value(member)"]
+  Yield --> More{more pages?}
+  More -- yes --> Decide
+  More -- no --> Done["return self"]
+```
+
+Per-type variations:
+- `ListKey#each` — paginates with `LRANGE start stop` (no SCAN equivalent)
+- `UnsortedSet#each` / `HashKey#each` — `SSCAN` / `HSCAN`, optional `matching:` glob
+- `SortedSet#each` — `ZRANGEBYSCORE` (bounded) or `ZSCAN` (unbounded)
+
+You get **identifiers only**. No record loading. One Redis round-trip per page.
+
+## `each_record` — yields **loaded Horreum records**
+
+`each_record` is defined once in `CollectionBase` and delegates to `each` to collect identifiers, then batches them into `record_class.load_multi` (pipelined `HGETALL`s), filters ghosts, and yields the live records.
+
+```mermaid
+flowchart TD
+  Caller["ModelClass.instances.each_record { |rec| ... }"] --> ER["each_record(batch_size, pipeline, **filters)"]
+  ER --> Validate{"pipeline <= batch_size?"}
+  Validate -- no --> Raise["raise ArgumentError"]
+  Validate -- yes --> CallEach["each(**filters) do |member|"]
+  CallEach --> Extract["id = member.is_a?(Array) ? member.first : member"]
+  Extract --> Buffer["buffer << id"]
+  Buffer --> Full{"buffer.size >= batch_size?"}
+  Full -- no --> CallEach
+  Full -- yes --> Load["record_class.load_multi(ids)  -- pipelined HGETALLs"]
+  Load --> Compact["live = records.compact  -- drop ghosts"]
+  Compact --> Mode{pipeline?}
+  Mode -- nil --> Serial["live.each { |r| block.call(r) }"]
+  Mode -- positive --> Pipe["live.each_slice(pipeline) do |group|<br/>record_class.pipelined { group.each &block }<br/>end"]
+  Serial --> Clear["buffer.clear; resume each"]
+  Pipe --> Clear
+  Clear --> CallEach
+  CallEach -. each exhausted .-> Flush["process_batch(buffer) if any remain"]
+  Flush --> Return["return self"]
+```
+
+### Concrete timeline for `User.instances.each_record(batch_size: 100, pipeline: 25) { |u| u.touch! }`
+
+```
+SortedSet#each (ZSCAN page 1, 100 ids)
+   ├─ buffer fills to 100
+   ├─ load_multi(ids)        → 1 pipeline of 100 HGETALLs
+   ├─ compact ghosts          → e.g. 97 live records
+   ├─ slice(25):
+   │     pipelined { 25 × u.touch! }   ← 1 Redis pipeline
+   │     pipelined { 25 × u.touch! }   ← 1 Redis pipeline
+   │     pipelined { 25 × u.touch! }   ← 1 Redis pipeline
+   │     pipelined { 22 × u.touch! }   ← 1 Redis pipeline
+   └─ buffer.clear
+SortedSet#each (ZSCAN page 2, 100 ids)
+   └─ … repeat …
+SortedSet#each exhausted
+   └─ flush any remaining buffered ids the same way
+```
+
+## Key differences
+
+| Aspect | `each` | `each_record` |
+|---|---|---|
+| Yields | raw identifier (or `[field, value]` for `HashKey`) | loaded Horreum instance |
+| Redis ops per yield | 0 extra (already paged) | amortized `HGETALL` via `load_multi` batch |
+| Requires `reference: true` + `:class` | no | yes (raises `Familia::Problem` otherwise) |
+| Ghost handling | yields the dangling id | `compact` drops them silently |
+| Write pipelining | not built-in | `pipeline:` groups block-body writes into `pipelined` blocks |
+| Filters | type-specific (`since:`, `matching:`, …) | forwarded to underlying `each` |
+
+So `each_record` is a thin orchestration layer: it leans on the type's own `each` for read pagination, then layers (1) batched record hydration and (2) optional write pipelining on top.
+
+## Choosing a `pipeline` mode
+
+`each_record` has two dispatch modes, controlled by `pipeline:`. The parameter answers a single question: **may the dispatch loop wrap your block in a `pipelined { }`?**
+
+| Value | Dispatch | Use when the block… |
+|---|---|---|
+| `nil` (default) | Each record runs in its own connection context, no pipeline wrapper | …reads, OR calls `save` / `commit_fields` / `transaction` / anything with its own internal MULTI |
+| positive integer | Groups of `pipeline` records run inside `record_class.pipelined { ... }` | …only issues fast writers (`record.field!`) that tolerate being queued |
+
+Note: `pipeline: 0` raises `ArgumentError`. Use `pipeline: nil` to disable pipelining.
+
+The read-only case and the serial-write case collapse into the same mode because both require **immediate** execution with real return values. Wrapping `save` in an outer `pipelined` would either return `Redis::Future` objects or raise `ConflictingContextError` when `save`'s internal transaction tries to open.
+
+### The three idiomatic patterns
+
+```ruby
+# 1. Read-only iteration — the default (pipeline: nil) is correct
+User.instances.each_record do |user|
+  puts "#{user.email} #{user.last_login}"
+end
+
+# 2. Serial writes — the default (pipeline: nil) is required for save / commit_fields / transaction
+User.instances.each_record do |user|
+  user.score = recompute(user)
+  user.save
+end
+
+# 3. Pipelined fast writers — opt-in optimization
+User.instances.each_record(pipeline: 50) do |user|
+  user.last_seen_at! Familia.now   # single HSET, safe to queue in pipeline
+end
+```
+
+### Pipelining footgun
+
+If you enable pipelining and your block reads from a related collection (e.g. `user.sessions.size`), that read is queued into the pipeline and returns a `Redis::Future` rather than a value. Omit the `pipeline:` parameter (or explicitly pass `pipeline: nil`) whenever the block needs real return values from Redis.

data/docs/migrating/v2.9.0.md

@@ -0,0 +1,125 @@
+# Migrating to Familia 2.9.0
+
+This version introduces batch iteration primitives for DataTypes, enabling efficient enumeration over large Redis collections. It also includes breaking changes to method names for clarity.
+
+## Breaking Changes
+
+### Method Renames
+
+The multi-field update methods have been renamed to better reflect their purpose:
+
+```ruby
+# Before (2.8.x)
+user.batch_update(name: "Alice", email: "alice@example.com")
+user.batch_fast_write(name: "Alice", email: "alice@example.com")
+
+# After (2.9.0)
+user.multi_field_update(name: "Alice", email: "alice@example.com")
+user.multi_field_fast_write(name: "Alice", email: "alice@example.com")
+```
+
+**Migration**: Find and replace `batch_update` with `multi_field_update` and `batch_fast_write` with `multi_field_fast_write`.
+
+### MultiResult Namespace
+
+`MultiResult` has moved into the Familia namespace:
+
+```ruby
+# Before (2.8.x)
+result.is_a?(MultiResult)
+
+# After (2.9.0)
+result.is_a?(Familia::MultiResult)
+```
+
+**Migration**: Replace bare `MultiResult` references with `Familia::MultiResult`.
+
+## New Features
+
+### Enumerable Integration
+
+All collection DataTypes now include Ruby's `Enumerable` module, providing `each_slice`, `lazy`, `map`, `reduce`, `find`, and other stdlib methods:
+
+```ruby
+# Lazy iteration with transformation
+Org.instances.lazy.map { |id| id.upcase }.take(10).to_a
+
+# Batch processing with each_slice
+User.instances.each_slice(100) do |batch|
+  batch.each { |id| process(id) }
+end
+```
+
+### Filtered Iteration
+
+Each DataType now supports type-specific filters on `each`:
+
+```ruby
+# SortedSet: filter by score (timestamp) bounds
+Org.instances.each(since: 24.hours.ago, until: Time.now) do |id|
+  puts id
+end
+
+# HashKey: filter by field name pattern
+user.profile.each(matching: "pref_*") do |field, value|
+  puts "#{field}: #{value}"
+end
+
+# UnsortedSet: filter by member pattern
+user.tags.each(matching: "admin*") do |tag|
+  puts tag
+end
+```
+
+### each_record for Loading Horreum Instances
+
+`each_record` yields fully-loaded Horreum records instead of raw IDs:
+
+```ruby
+# Load records in batches of 100
+Org.instances.each_record(batch_size: 100) do |org|
+  org.tidy!  # org is a loaded Horreum instance
+end
+
+# Control pipelining depth separately from fetch batch size
+Org.instances.each_record(batch_size: 500, pipeline: 50) do |org|
+  org.status!("active")
+end
+
+# Serial execution (no pipelining) — this is the default
+Org.instances.each_record(batch_size: 100) do |org|
+  org.complex_operation
+end
+```
+
+Ghost instances (keys that expired but remain in the `instances` sorted set) are automatically filtered and never reach the block.
+
+### BatchResult for Aggregated Operations
+
+`Familia::BatchResult` aggregates results from batch operations with per-record error isolation:
+
+```ruby
+result = Familia::BatchResult.collect(
+  Org.instances.each_record(batch_size: 100, since: 24.hours.ago)
+) do |org|
+  org.tidy!
+end
+
+result.scanned     # Total records yielded to block
+result.modified    # Count of truthy block returns
+result.errors      # Array of {id:, error:} for failed records
+result.duration_ms # Total execution time
+
+# Re-raise errors after completion
+result = Familia::BatchResult.collect(enum, strict: true) { |r| r.process! }
+```
+
+## Concurrent Mutation Behavior
+
+When iterating with `each` or `each_record`, be aware of Redis cursor semantics:
+
+- Items present from iteration start to end are guaranteed to be returned
+- Items added or removed mid-iteration may or may not appear
+- Blocks should be idempotent to handle potential duplicates
+
+This is inherent to ZSCAN/HSCAN/SSCAN and is documented, not a bug.

data/familia.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'json_schemer', '~> 2.0'
   spec.add_dependency 'logger', '~> 1.7'
   spec.add_dependency 'oj', '~> 3.16'
-  spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
+  spec.add_dependency 'redis', '>= 5.0', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'
 

data/lib/familia/batch_result.rb

@@ -0,0 +1,158 @@
+# lib/familia/batch_result.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  # Represents the result of a batch iteration operation.
+  #
+  # BatchResult tracks statistics and errors when processing multiple records
+  # via methods like `each_record`. It provides aggregated metrics for the
+  # entire batch run, distinct from MultiResult which wraps a single
+  # MULTI/EXEC or pipeline operation.
+  #
+  # @attr_reader scanned [Integer] Total number of items iterated
+  # @attr_reader modified [Integer] Count of items where block returned truthy
+  # @attr_reader errors [Array<Hash>] Per-item errors as [{id:, error:}, ...]
+  # @attr_reader duration_ms [Float] Total elapsed time in milliseconds
+  #
+  # @example Using BatchResult.collect
+  #   result = BatchResult.collect(User.instances) do |user|
+  #     user.deactivate!
+  #   end
+  #   puts "Processed #{result.scanned}, modified #{result.modified}"
+  #   puts "Errors: #{result.errors.size}" if result.errors?
+  #
+  # @example With strict mode
+  #   # Re-raises first error after completing iteration
+  #   BatchResult.collect(items, strict: true) { |item| item.process! }
+  #
+  class BatchResult
+    attr_reader :scanned, :modified, :errors, :duration_ms
+
+    # Creates a new BatchResult instance.
+    #
+    # @param scanned [Integer] Total items processed
+    # @param modified [Integer] Items where block returned truthy
+    # @param errors [Array<Hash>] Array of error hashes with :id and :error keys
+    # @param duration_ms [Float] Elapsed time in milliseconds
+    def initialize(scanned:, modified:, errors:, duration_ms:)
+      @scanned = scanned
+      @modified = modified
+      @errors = errors
+      @duration_ms = duration_ms
+    end
+
+    # Iterates over an enumerable, collecting statistics and errors.
+    #
+    # This is the primary factory method for creating BatchResult instances.
+    # It tracks how many items were processed, how many returned truthy values,
+    # and captures any exceptions that occur during iteration.
+    #
+    # @param enumerable [Enumerable] The collection to iterate
+    # @param strict [Boolean] When true, re-raises the first captured error
+    #   after iteration completes. Default: false.
+    # @yield [item] Each item from the enumerable
+    # @yieldreturn [Object] Truthy return values increment the modified count
+    # @return [BatchResult] Aggregated result of the batch operation
+    #
+    # @example Basic usage
+    #   result = BatchResult.collect(records) { |r| r.update!(status: 'done') }
+    #
+    # @example Strict mode re-raises errors
+    #   begin
+    #     BatchResult.collect(records, strict: true) { |r| r.validate! }
+    #   rescue => e
+    #     puts "Batch failed: #{e.message}"
+    #   end
+    #
+    def self.collect(enumerable, strict: false)
+      scanned = 0
+      modified = 0
+      errors = []
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      enumerable.each do |*args|
+        scanned += 1
+        begin
+          result = yield(*args)
+          modified += 1 if result
+        rescue StandardError => e
+          # Extract identifier if possible
+          identifier = extract_identifier(args.length == 1 ? args[0] : args)
+          errors << { id: identifier, error: e }
+        end
+      end
+
+      duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000
+
+      batch_result = new(
+        scanned: scanned,
+        modified: modified,
+        errors: errors,
+        duration_ms: duration_ms
+      )
+
+      # In strict mode, re-raise the first error after completing iteration
+      raise errors.first[:error] if strict && errors.any?
+
+      batch_result
+    end
+
+    # Checks if any errors occurred during the batch.
+    #
+    # @return [Boolean] true if at least one error was captured
+    def errors?
+      !errors.empty?
+    end
+
+    # Checks if the batch completed without errors.
+    #
+    # @return [Boolean] true if no errors occurred
+    def successful?
+      errors.empty?
+    end
+    alias success? successful?
+
+    # Returns the count of items that were scanned but not modified.
+    #
+    # @return [Integer] Number of items where block returned falsy
+    def skipped
+      scanned - modified - errors.size
+    end
+
+    # Returns a hash representation of the result.
+    #
+    # @return [Hash] Result data including all metrics
+    def to_h
+      {
+        scanned: scanned,
+        modified: modified,
+        skipped: skipped,
+        errors: errors.size,
+        duration_ms: duration_ms.round(2),
+        successful: successful?
+      }
+    end
+
+    # Returns a human-readable summary.
+    #
+    # @return [String] Summary of the batch operation
+    def to_s
+      "BatchResult: scanned=#{scanned} modified=#{modified} errors=#{errors.size} duration=#{duration_ms.round(2)}ms"
+    end
+
+    # @private
+    def self.extract_identifier(item)
+      if item.respond_to?(:identifier)
+        item.identifier
+      elsif item.respond_to?(:id)
+        item.id
+      else
+        item.to_s[0, 50]
+      end
+    rescue StandardError
+      nil
+    end
+    private_class_method :extract_identifier
+  end
+end