activerecord-duplicator 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc6a883e8a354d6b41962cb96eff90d95f083918fee428b0f865d5d254117f5c
-  data.tar.gz: 6b04468f4352d8d82f7a3cee8ccf684d19672d86715c4899313992a65519f362
+  metadata.gz: 4139cd9d1fa3041e02e9c17a2cf97c5f435230955c63b4ed29453b685fb6a985
+  data.tar.gz: 8acef30197ddd818ffc3e957bf7db58821e8ae8b34f848d72fdfd5f1713680f4
 SHA512:
-  metadata.gz: f3ee11352e9d5612730e3a86f3f11d50e9becff4ac25651f1efef18dc9a6207da379e71751af1cf983e1bd880725200ce44c8c6f86da774242144942076996eb
-  data.tar.gz: 90472d33b56c36ab4d3688284cee4f6cacb2d6d3fa1f5cbfc3b44ba8ca5e5f52bcf176da680937d815cc2da0df97c558caee71fb196d03f1f816a2e53ab10f23
+  metadata.gz: 22a435ec6ebc808da2a87bb20a4b19c82188c80ec73db48c39f33868f1729dc80775bae437f0b7e7b6d6dd86ae0e47862a72a3fb34e9e96d0c70ea50b5991bab
+  data.tar.gz: 5a5978f8259fde2473f220e8b2a953d649ae9c5824502ecb9a4c15bbfbbb9af9b2ae6cd5e9ebe89c5d5ea4a5d8c4de29e7c4efabe2058455d0197965f84fae3e

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-06
+
+### Fixed
+
+- `Duplicator#duplicate` now accepts `transaction_options: {}` and forwards
+  it to `Session#run`, which forwards it to `root_record.transaction`. In
+  v0.3.0 this plumbing was only wired at the Session#run layer, so callers
+  using the documented `Duplicator#duplicate` entry point had no way to
+  override the outer transaction options.
+
+## [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)

data/README.md

@@ -71,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,12 +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 = {}
+        # 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
@@ -41,9 +45,7 @@ module ActiveRecord
       # Duplicator-level handler is intentional and does not raise.
       #: (Class) { (HandlerApi, Class, untyped) -> void } -> void
       def on(klass, &block)
-        if @user_handlers.key?(klass)
-          raise DuplicateHandlerError, "handler for #{klass} is already overridden in this session"
-        end
+        raise DuplicateHandlerError, "handler for #{klass} is already overridden in this session" if @user_handlers.key?(klass)
 
         @user_handlers[klass] = block
       end
@@ -59,6 +61,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.
@@ -89,6 +106,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
@@ -97,8 +116,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|
@@ -137,11 +162,17 @@ 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
+      # 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|
@@ -159,6 +190,10 @@ module ActiveRecord
       # 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)

data/lib/active_record/duplicator/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   class Duplicator
-    VERSION = "0.2.0"
+    VERSION = "0.4.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
 
@@ -50,11 +63,15 @@ module ActiveRecord
     # If a block is given it is called with the new Session before duplication
     # starts, letting the caller mark_skip or store_new_id for records that
     # were duplicated elsewhere.
-    #: (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
-    def duplicate(root_record, associations: [], &block)
-      session = Session.new(handlers: @handlers)
+    #
+    # transaction_options is forwarded verbatim to Session#run, which forwards
+    # it to `root_record.transaction`. Default is `{}` (plain
+    # `transaction do ... end`).
+    #: (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) ?{ (Session) -> void } -> ActiveRecord::Base
+    def duplicate(root_record, associations: [], transaction_options: {}, &block)
+      session = Session.new(handlers: @handlers, skipped_classes: @skipped_classes)
       block&.call(session)
-      session.run(root_record, associations:)
+      session.run(root_record, associations:, transaction_options:)
     end
   end
 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,10 +102,16 @@ 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
 
@@ -94,6 +119,10 @@ module ActiveRecord
       # 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
 

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
@@ -39,7 +49,11 @@ module ActiveRecord
     # If a block is given it is called with the new Session before duplication
     # starts, letting the caller mark_skip or store_new_id for records that
     # were duplicated elsewhere.
-    # : (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
-    def duplicate: (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
+    #
+    # transaction_options is forwarded verbatim to Session#run, which forwards
+    # it to `root_record.transaction`. Default is `{}` (plain
+    # `transaction do ... end`).
+    # : (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) ?{ (Session) -> void } -> ActiveRecord::Base
+    def duplicate: (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) ?{ (Session) -> void } -> ActiveRecord::Base
   end
 end

metadata

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