activerecord-duplicator 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bf58194f42894cf69c9ff83e02cd0f9f76fe38565e671e24ebb232221e8fa31
-  data.tar.gz: 1d20e02d28ef2bffcf831654d2b71fe73461d3eee0fa3b11ce5e95a15bac259a
+  metadata.gz: ee612e84f80aefec6371c6e900d058e9934b7b7d095a981e2f52d22291586210
+  data.tar.gz: 2aafb86816d74188a18a82e36c74e1a6c1dcb65b52523c3ee4bafa9db45e1fa3
 SHA512:
-  metadata.gz: ba02707cbdfdf479e2663bfcbf9b7d4012e1b1d43a9a483a041b76debff00d013e8b4f36efd7e81cb8e2e09d30a60b374a87345f625216dad0c75fee6898f1f0
-  data.tar.gz: 6871e902554ea9fc435b17bfa83e978a1034898bae00cf744edb61b191a89dc05bc479d316c6785a172a722f7d87b794114e173b819ed8176ccdffca380bd430
+  metadata.gz: f167f08df7e50cc605ff85d3663f3e51cb1b2a11ea88201bf50726b20721e263b8b9f96fee38ad64e42b97cd895f2217fb1968760bdf085351959632c7fec0d1
+  data.tar.gz: 652d33cc38a670dc0eafad296157d6f56c5fd3e4a435082b1bec45706c9a01624730be36992ebd22ac88f335a70def57aad3234480d77816297f879460462cda

data/CHANGELOG.md

@@ -1,8 +1,55 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-06
+
+### Changed (breaking)
+
+- `Session#run` now takes a `transaction_options: {}` keyword and forwards
+  it verbatim to `root_record.transaction`. The previous hard-coded
+  `requires_new: true, joinable: false` defaults are removed; callers that
+  relied on them must pass those flags explicitly:
+  `session.run(root, transaction_options: { requires_new: true, joinable: false })`.
+
+### Added
+
+- `Duplicator#mark_skip_class(*klasses)` / `Session#mark_skip_class` /
+  `HandlerApi#mark_skip_class` — class-wide shorthand for `mark_skip`.
+  Behaviour is exactly as if every record of the class had been passed
+  to `mark_skip` beforehand: handlers registered for the class still
+  fire, the default `bulk_insert` path becomes a no-op, and
+  `fetch_new_id(klass, old_id: ...)` echoes `old_id` back unchanged.
+  The Duplicator-level registration is inherited by every subsequent
+  `duplicate` run; Session-level additions apply only to the current run.
+
+## [0.2.0] - 2026-07-06
+
 - Drop support for Ruby 3.2 (EOL)
 - Drop support for Rails 7.2; assume ActiveRecord >= 8.0 so `in_batches(cursor:)` is always available
 
+### Removed (breaking)
+
+- STI (Single Table Inheritance) dispatch in `Session#duplicate_records`.
+  Handlers are now looked up by the input Relation's `klass` (or the first
+  element's class for Arrays), with no ancestor walk and no `group_by(&:class)`.
+  If you were relying on registering a handler on a base class and expecting
+  it to fire for subclass records mixed in one Relation, split your input by
+  subclass and register handlers on each concrete class instead.
+
+### Changed (breaking)
+
+- Handlers now receive an `ActiveRecord::Relation` (not an Array) when the
+  input to duplication was a Relation. This lets `api.bulk_insert(klass,
+  records, cursor: [...])` take the `in_batches(cursor:)` path and enables
+  cursor-based keyset pagination for large child sets.
+- Default (handler-less) dispatch of a Relation now uses `find_in_batches`
+  internally, reducing peak memory for large child sets.
+
+### Migration
+
+- Handlers that previously used Array-only methods (`records.reject!`, etc.)
+  on the third argument must convert to Array explicitly:
+  `records = records.to_a`.
+
 ## [0.1.0] - 2026-07-02
 
 - Add `ActiveRecord::Duplicator::AssociationTraversal` — breadth-first traversal of preload-style association specifications

data/README.md

@@ -26,6 +26,17 @@ gem install activerecord-duplicator
 - PostgreSQL (via `pg` gem). The gem relies on `insert_all!` returning inserted
   primary keys.
 
+## Non-goals
+
+### STI dispatch
+
+This gem dispatches based on the class of the input Relation (or the first
+element for Arrays). If your Relation mixes STI subclasses and you need
+per-subclass handlers, split the input into per-subclass Relations before
+passing them in. Ancestor-walking dispatch (register a handler on a base class,
+have it fire for subclass records mixed in one Relation) is intentionally not
+supported; see CHANGELOG for details.
+
 ## Usage
 
 ### Basic duplication
@@ -60,6 +71,32 @@ duplicator.duplicate(old_project, associations: [tasks: :attachments])
 Skipped records get `new_id == old_id` in the internal map, so children that
 reference them are inserted with the original id unchanged.
 
+### Skipping a whole model (`mark_skip_class`)
+
+When every row of a model should be reused by id (a shared lookup table,
+a tenant-wide catalog, an enum-backed table with dozens of entries), skip
+the class itself instead of enumerating rows. `mark_skip_class` exists at
+both scopes and mirrors `on`: register once on the Duplicator to inherit
+across every run, or add it in the Session block for a single run.
+
+```ruby
+duplicator = ActiveRecord::Duplicator.new
+duplicator.mark_skip_class(Tag)           # applies to every subsequent run
+
+duplicator.duplicate(old_post, associations: [:taggings])
+
+duplicator.duplicate(other_post, associations: [:taggings]) do |session|
+  session.mark_skip_class(Currency)       # extra skip, this run only
+end
+```
+
+Behaviour is exactly as if you had passed every row to `mark_skip` up front:
+handlers registered for the class still fire (so custom copy logic keeps
+working), but the default `bulk_insert` path becomes a no-op and any
+`fetch_new_id(klass, old_id: ...)` from a child's foreign-key reassignment
+echoes the old id back unchanged. `mark_skip_class` only differs from
+per-record `mark_skip` in cost: no enumeration is needed to opt each row in.
+
 ### Registering an id from outside (`store_new_id` / `fetch_new_id`)
 
 If you produce a duplicate yourself (for example a model with a uniqueness

data/lib/active_record/duplicator/handler_api.rb

@@ -19,6 +19,11 @@ module ActiveRecord
         @session.mark_skip(...)
       end
 
+      #: (*Class) -> void
+      def mark_skip_class(...)
+        @session.mark_skip_class(...)
+      end
+
       #: (Class, old_id: untyped, new_id: untyped) -> void
       def store_new_id(...)
         @session.store_new_id(...)

data/lib/active_record/duplicator/session.rb

@@ -24,13 +24,16 @@ module ActiveRecord
       # @rbs @record_id_map: Hash[Class, Hash[untyped, untyped]]
       # @rbs @handlers: Hash[Class, Proc]
       # @rbs @user_handlers: Hash[Class, Proc]
+      # @rbs @skipped_classes: Set[Class]
 
-      #: (?handlers: Hash[Class, Proc]) -> void
-      def initialize(handlers: {})
+      #: (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
+      def initialize(handlers: {}, skipped_classes: Set.new)
         @record_id_map = Hash.new { |hash, klass| hash[klass] = {} }
         @handlers = handlers
         @user_handlers = {}
-        @handlers_cache = {}
+        # dup so that Session#mark_skip_class additions never leak back to the
+        # Duplicator-level set shared across every run.
+        @skipped_classes = skipped_classes.dup
       end
 
       # Register a handler that overrides Duplicator#on for the current session
@@ -42,8 +45,6 @@ module ActiveRecord
       # Duplicator-level handler is intentional and does not raise.
       #: (Class) { (HandlerApi, Class, untyped) -> void } -> void
       def on(klass, &block)
-        @handlers_cache.clear
-
         if @user_handlers.key?(klass)
           raise DuplicateHandlerError, "handler for #{klass} is already overridden in this session"
         end
@@ -62,6 +63,21 @@ module ActiveRecord
         end
       end
 
+      # Class-wide equivalent of mark_skip: it is exactly as if every record of
+      # each given class had been passed to mark_skip. Handlers still fire
+      # (matching the mark_skip case where a handler for the class is invoked
+      # with a Relation that happens to contain pre-skipped records); the
+      # default bulk_insert path becomes a no-op, and fetch_new_id echoes the
+      # queried old_id back unchanged.
+      #
+      # Use when the target database is expected to already hold every
+      # referenced row (shared lookup tables, tenant-wide catalogs, etc.), so
+      # per-record mark_skip would only differ from this in cost, not effect.
+      #: (*Class) -> void
+      def mark_skip_class(*klasses)
+        @skipped_classes.merge(klasses)
+      end
+
       # Record a mapping from an old_id to a new_id. Called automatically from
       # bulk_insert; called explicitly by user code (or a handler) when new
       # records are produced outside of the default duplication path.
@@ -92,6 +108,8 @@ module ActiveRecord
       # associations tree or register/skip it explicitly.
       #: (Class, old_id: untyped) -> untyped
       def fetch_new_id(klass, old_id:)
+        return old_id if @skipped_classes.include?(klass)
+
         @record_id_map[klass].fetch(old_id) do
           raise MissingNewIdError, "no new_id registered for #{klass}##{old_id.inspect}"
         end
@@ -100,8 +118,14 @@ module ActiveRecord
       # Bulk-insert copies of the given records into klass, skipping any that
       # are already present in the id map. Handlers can reuse this via HandlerApi
       # to defer a subset of records to the default duplication path.
+      #
+      # When klass has been passed to mark_skip_class the call is a no-op that
+      # never touches the DB: it is equivalent to having pre-registered every
+      # incoming record via mark_skip, only without the per-record enumeration.
       #: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
       def bulk_insert(klass, records, batch_size: DEFAULT_BATCH_SIZE, cursor: nil)
+        return if @skipped_classes.include?(klass)
+
         batches = enumerate_batches(records, batch_size:, cursor:)
 
         batches.each do |batch|
@@ -140,15 +164,21 @@ module ActiveRecord
         attrs
       end
 
-      # Run the duplication inside a new, non-joinable transaction and return
-      # the freshly loaded root record. Normally invoked by Duplicator#duplicate.
-      #: (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
-      def run(root_record, associations: [])
-        root_record.transaction(requires_new: true, joinable: false) do
-          duplicate_records([root_record])
+      # Run the duplication inside a transaction and return the freshly loaded
+      # root record. Normally invoked by Duplicator#duplicate.
+      #
+      # transaction_options is passed through verbatim to
+      # `root_record.transaction`, so callers can request `requires_new: true`
+      # / `joinable: false` / `isolation: :serializable` etc. as fits the
+      # surrounding call site. It defaults to `{}`, i.e. plain
+      # `transaction do ... end` behaviour.
+      #: (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) -> ActiveRecord::Base
+      def run(root_record, associations: [], transaction_options: {})
+        root_record.transaction(**transaction_options) do
+          duplicate_records(root_record.class, [root_record])
 
           AssociationTraversal.new(root_record, associations).each do |relation|
-            duplicate_records(relation)
+            duplicate_records(relation.klass, relation)
           end
 
           new_id = fetch_new_id(root_record.class, old_id: current_id(root_record))
@@ -158,45 +188,30 @@ module ActiveRecord
 
       private
 
-      #: (untyped) -> void
-      def duplicate_records(relation_or_records)
-        # Group by the real class of each record so a handler registered on an
-        # STI subclass fires only for records of that subclass. For non-STI
-        # models every record shares the given `klass`, so a single group is
-        # produced.
-        relation_or_records.group_by(&:class).each do |real_class, records|
-          handler = cache_or_resolve_handler(real_class)
-
-          if handler
-            handler.call(HandlerApi.new(self), real_class, records)
-          else
-            bulk_insert(real_class, records)
-          end
+      # Dispatch to a handler (or the default bulk_insert path) for `klass`.
+      # All records in `relation_or_records` are assumed to be of `klass`; the
+      # caller is responsible for splitting mixed inputs (e.g. STI subclasses)
+      # into per-class Relations and passing the matching class in.
+      #
+      # mark_skip_class does NOT short-circuit here: handlers must still fire
+      # (mirroring the per-record mark_skip case), and the class-wide skip is
+      # applied inside bulk_insert instead.
+      #: (Class, untyped) -> void
+      def duplicate_records(klass, relation_or_records)
+        handler = resolve_handler(klass)
+
+        if handler
+          handler.call(HandlerApi.new(self), klass, relation_or_records)
+        else
+          bulk_insert(klass, relation_or_records)
         end
       end
 
-      #: (Class) -> Proc?
-      def cache_or_resolve_handler(klass)
-        @handlers_cache[klass] = resolve_handler(klass) unless @handlers_cache.key?(klass)
-
-        @handlers_cache[klass]
-      end
-
-      # Look up a handler for `klass` by walking its ancestor chain. Session
-      # -local handlers (Session#on) take precedence over any Duplicator-level
-      # handler, even one registered closer in the ancestor chain: the two
-      # passes below are deliberate, not a refactor opportunity.
+      # Session-local handlers (Session#on) take precedence over any
+      # Duplicator-level handler registered for the exact same class.
       #: (Class) -> Proc?
       def resolve_handler(klass)
-        # rubocop:disable Style/CombinableLoops
-        klass.ancestors.each do |ancestor|
-          return @user_handlers[ancestor] if @user_handlers.key?(ancestor)
-        end
-        klass.ancestors.each do |ancestor|
-          return @handlers[ancestor] if @handlers.key?(ancestor)
-        end
-        # rubocop:enable Style/CombinableLoops
-        nil
+        @user_handlers[klass] || @handlers[klass]
       end
 
       #: (untyped, batch_size: Integer, cursor: untyped) -> untyped

data/lib/active_record/duplicator/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   class Duplicator
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/active_record/duplicator.rb

@@ -19,10 +19,12 @@ module ActiveRecord
   #   end
   class Duplicator
     # @rbs @handlers: Hash[Class, Proc]
+    # @rbs @skipped_classes: Set[Class]
 
     #: () -> void
     def initialize
       @handlers = {}
+      @skipped_classes = Set.new
     end
 
     # Register a custom handler for the given model class. See HandlerApi for
@@ -36,11 +38,22 @@ module ActiveRecord
       @handlers[klass] = block
     end
 
+    # Declare that every record of the given classes must not be duplicated in
+    # any subsequent run. See Session#mark_skip_class for the semantics; the
+    # Duplicator-level registration is applied to every fresh Session as its
+    # baseline, and Session#mark_skip_class can extend it for a single run.
+    # Repeated calls with the same class are idempotent.
+    #: (*Class) -> void
+    def mark_skip_class(*klasses)
+      @skipped_classes.merge(klasses)
+    end
+
     # Prevent further registrations. Also freezes the internal handler map so
     # accidental mutation later fails loudly.
     #: () -> self
     def freeze
       @handlers.freeze
+      @skipped_classes.freeze
       super
     end
 
@@ -52,7 +65,7 @@ module ActiveRecord
     # were duplicated elsewhere.
     #: (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
     def duplicate(root_record, associations: [], &block)
-      session = Session.new(handlers: @handlers)
+      session = Session.new(handlers: @handlers, skipped_classes: @skipped_classes)
       block&.call(session)
       session.run(root_record, associations:)
     end

data/sig/generated/active_record/duplicator/handler_api.rbs

@@ -15,6 +15,9 @@ module ActiveRecord
       # : (*ActiveRecord::Base) -> void
       def mark_skip: (*ActiveRecord::Base) -> void
 
+      # : (*Class) -> void
+      def mark_skip_class: (*Class) -> void
+
       # : (Class, old_id: untyped, new_id: untyped) -> void
       def store_new_id: (Class, old_id: untyped, new_id: untyped) -> void
 

data/sig/generated/active_record/duplicator/session.rbs

@@ -20,14 +20,16 @@ module ActiveRecord
     class Session
       DEFAULT_BATCH_SIZE: ::Integer
 
+      @skipped_classes: Set[Class]
+
       @user_handlers: Hash[Class, Proc]
 
       @handlers: Hash[Class, Proc]
 
       @record_id_map: Hash[Class, Hash[untyped, untyped]]
 
-      # : (?handlers: Hash[Class, Proc]) -> void
-      def initialize: (?handlers: Hash[Class, Proc]) -> void
+      # : (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
+      def initialize: (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
 
       # Register a handler that overrides Duplicator#on for the current session
       # only. Useful when a single duplication run needs a special copy of a
@@ -45,6 +47,19 @@ module ActiveRecord
       # : (*ActiveRecord::Base) -> void
       def mark_skip: (*ActiveRecord::Base) -> void
 
+      # Class-wide equivalent of mark_skip: it is exactly as if every record of
+      # each given class had been passed to mark_skip. Handlers still fire
+      # (matching the mark_skip case where a handler for the class is invoked
+      # with a Relation that happens to contain pre-skipped records); the
+      # default bulk_insert path becomes a no-op, and fetch_new_id echoes the
+      # queried old_id back unchanged.
+      #
+      # Use when the target database is expected to already hold every
+      # referenced row (shared lookup tables, tenant-wide catalogs, etc.), so
+      # per-record mark_skip would only differ from this in cost, not effect.
+      # : (*Class) -> void
+      def mark_skip_class: (*Class) -> void
+
       # Record a mapping from an old_id to a new_id. Called automatically from
       # bulk_insert; called explicitly by user code (or a handler) when new
       # records are produced outside of the default duplication path.
@@ -69,6 +84,10 @@ module ActiveRecord
       # Bulk-insert copies of the given records into klass, skipping any that
       # are already present in the id map. Handlers can reuse this via HandlerApi
       # to defer a subset of records to the default duplication path.
+      #
+      # When klass has been passed to mark_skip_class the call is a no-op that
+      # never touches the DB: it is equivalent to having pre-registered every
+      # incoming record via mark_skip, only without the per-record enumeration.
       # : (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
       def bulk_insert: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
 
@@ -83,23 +102,32 @@ module ActiveRecord
       # : (Class, ActiveRecord::Base) -> Hash[String, untyped]
       def attributes_for: (Class, ActiveRecord::Base) -> Hash[String, untyped]
 
-      # Run the duplication inside a new, non-joinable transaction and return
-      # the freshly loaded root record. Normally invoked by Duplicator#duplicate.
-      # : (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
-      def run: (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
+      # Run the duplication inside a transaction and return the freshly loaded
+      # root record. Normally invoked by Duplicator#duplicate.
+      #
+      # transaction_options is passed through verbatim to
+      # `root_record.transaction`, so callers can request `requires_new: true`
+      # / `joinable: false` / `isolation: :serializable` etc. as fits the
+      # surrounding call site. It defaults to `{}`, i.e. plain
+      # `transaction do ... end` behaviour.
+      # : (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) -> ActiveRecord::Base
+      def run: (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) -> ActiveRecord::Base
 
       private
 
-      # : (untyped) -> void
-      def duplicate_records: (untyped) -> void
-
-      # : (Class) -> Proc?
-      def cache_or_resolve_handler: (Class) -> Proc?
-
-      # Look up a handler for `klass` by walking its ancestor chain. Session
-      # -local handlers (Session#on) take precedence over any Duplicator-level
-      # handler, even one registered closer in the ancestor chain: the two
-      # passes below are deliberate, not a refactor opportunity.
+      # Dispatch to a handler (or the default bulk_insert path) for `klass`.
+      # All records in `relation_or_records` are assumed to be of `klass`; the
+      # caller is responsible for splitting mixed inputs (e.g. STI subclasses)
+      # into per-class Relations and passing the matching class in.
+      #
+      # mark_skip_class does NOT short-circuit here: handlers must still fire
+      # (mirroring the per-record mark_skip case), and the class-wide skip is
+      # applied inside bulk_insert instead.
+      # : (Class, untyped) -> void
+      def duplicate_records: (Class, untyped) -> void
+
+      # Session-local handlers (Session#on) take precedence over any
+      # Duplicator-level handler registered for the exact same class.
       # : (Class) -> Proc?
       def resolve_handler: (Class) -> Proc?
 

data/sig/generated/active_record/duplicator.rbs

@@ -18,6 +18,8 @@ module ActiveRecord
   class Duplicator
     @handlers: Hash[Class, Proc]
 
+    @skipped_classes: Set[Class]
+
     # : () -> void
     def initialize: () -> void
 
@@ -28,6 +30,14 @@ module ActiveRecord
     # : (Class) { (HandlerApi, Class, untyped) -> void } -> void
     def on: (Class) { (HandlerApi, Class, untyped) -> void } -> void
 
+    # Declare that every record of the given classes must not be duplicated in
+    # any subsequent run. See Session#mark_skip_class for the semantics; the
+    # Duplicator-level registration is applied to every fresh Session as its
+    # baseline, and Session#mark_skip_class can extend it for a single run.
+    # Repeated calls with the same class are idempotent.
+    # : (*Class) -> void
+    def mark_skip_class: (*Class) -> void
+
     # Prevent further registrations. Also freezes the internal handler map so
     # accidental mutation later fails loudly.
     # : () -> self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-duplicator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - SmartHR