deckard 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d27aab47bd5883ad518fe7910ae3faf5f7a3c617430bd0668345dacd652252a6
-  data.tar.gz: 8b232443e73afa31f061a082327c5b3c541912f83127f18ba968e99659f0f167
+  metadata.gz: a0545ee7c006b54aaedd28b162ee6eb06647b0812bfbbdcb3b5846a78d6cdd68
+  data.tar.gz: 9cf0a020aaeabaf9d659549b3045fe9ba2b4a758ee40106163a6aead95c7a778
 SHA512:
-  metadata.gz: e851c6424c4c790437c294461f64e2444a34297c67507b3fa53c36cdc3af2008462ee41f12465908f4187bbd8b02b0ea6ea5cfa9c8f3509d31cbc86de21f69f3
-  data.tar.gz: 354bd7706454a95d042b85d2d80166215cfa0cd9c8ae31c5dfee06f3de0d16f51b277505eaec6a992bdd689ff189044ea536a0220bde49a99484603d2fcd585f
+  metadata.gz: 33e82c2fbba3856af1019a61bc1cf181e6f74383824895ab667d76aedd1994a04af5e69534c73f379ba2b64f333748319767290511f97eaefb13fbb75e674b83
+  data.tar.gz: dacd253d2915316b2549f6ea4196354055f0abd4b504b14c9e6980ecab11f83d676a1868e81751c785ee813fd242bd256361daaae475c5078eda6c227364d0aa

data/CHANGELOG.md

@@ -5,7 +5,22 @@ All notable changes to deckard are recorded here. The format follows
 [Semantic Versioning](https://semver.org/). Before 1.0, minor versions may
 change the stream format and the Ruby API.
 
-## [0.2.0] - Unreleased
+## [0.3.0] - Unreleased
+
+### Added
+
+- `natural_keys` inside a `replicate` block: one table of class name to
+  attribute name or names, the short form for a reached class that only
+  needs a natural key. `model "Name" do natural_key ... end` still works
+  for an entry that also names associations or omissions.
+
+### Changed
+
+- A plan gives each class one natural key. Declaring it twice in the same
+  plan is reported by validation as a `ConfigurationError`; before, the
+  later declaration silently replaced the earlier one.
+
+## [0.2.0] - 2026-09-30
 
 ### Changed
 

data/README.md

@@ -92,7 +92,7 @@ gives every order the full plan, and a record two dumps share lands once.
 
 ## Plans
 
-The `replicate` block offers five methods:
+The `replicate` block offers six methods:
 
 ```ruby
 replicate do
@@ -101,17 +101,25 @@ replicate do
   omit_fields :internal_notes    # keep a field out of the stream
   omit_associations :warehouse   # do not traverse this association
 
-  model "LineItem" do            # the same four, for a class the dump reaches
+  natural_keys "Product" => :sku,             # how each reached class is matched
+    "Warehouse" => [:region, :code]
+
+  model "LineItem" do            # the first four, for a class the dump reaches
     associations :adjustments
   end
 end
 ```
 
+Most reached classes need nothing but a natural key, and `natural_keys` says
+that for all of them in one table. A `model` block is for the rest: a
+collection to bring along, a field to leave out. A plan gives each class one
+key, so naming it in both places is a plan problem, not an override.
+
 Classes are named as strings, so the root never forces them to load first,
 and an STI subclass follows the entry for its nearest declared ancestor. Each
 record travels with the natural key its plan gave it, so the destination
 needs no plan of its own. That also means a natural key is repeated in every
-plan whose dumps reach the class: a Customer entry in Order's plan and one in
+plan whose dumps reach the class: a Customer line in Order's plan and one in
 Invoice's, each saying how a customer is matched.
 
 Before dumping, the `deckard` executable eager loads the application so

data/lib/deckard/model_config.rb

@@ -4,10 +4,10 @@ require "active_support/core_ext/string/inflections"
 
 module Deckard
   # A replication plan: a root model's `replicate do ... end` block. The plan
-  # is an entry for the root plus, through `model`, an entry for each class
-  # its dumps reach, all in one table shared by the plan's entries. A class
-  # finds its entry through its ancestors, so an STI subclass follows its
-  # nearest declared ancestor. See docs/traversal.md.
+  # is an entry for the root plus an entry for each class its dumps reach,
+  # declared through `natural_keys` or `model`, all in one table shared by
+  # the plan's entries. A class finds its entry through its ancestors, so an
+  # STI subclass follows its nearest declared ancestor. See docs/traversal.md.
   class ModelConfig
     attr_reader :name, :extra_associations, :natural_key_attributes, :omitted_fields, :omitted_associations
 
@@ -47,11 +47,17 @@ module Deckard
     end
 
     # DSL: attributes identifying an existing destination record to reuse.
-    # Calling it again replaces the key.
+    # Declaring it twice in one plan is a problem, not an override.
     def natural_key(*attributes)
+      @redeclared_natural_key = !@natural_key_attributes.empty?
       @natural_key_attributes = attributes.map(&:to_s)
     end
 
+    # DSL: class name to natural key, for reached classes needing nothing else.
+    def natural_keys(keys)
+      keys.each { |name, attributes| model(name) { natural_key(*attributes) } }
+    end
+
     # DSL: fields to exclude from dumped attributes. Additive across calls.
     def omit_fields(*names)
       @omitted_fields |= names.map(&:to_s)
@@ -104,9 +110,11 @@ module Deckard
         missing = attributes - model.attribute_names
         problems += missing.map { |attribute| "#{model} has no #{attribute.inspect} attribute" }
       end
-      problems + (@natural_key_attributes & @omitted_fields).map do |attribute|
+      problems += (@natural_key_attributes & @omitted_fields).map do |attribute|
         "#{model} names #{attribute.inspect} as both a natural key attribute and an omitted field"
       end
+      problems << "#{model} is given a natural key more than once in the same plan" if @redeclared_natural_key
+      problems
     end
 
     # The plan as data, root entry first: what PlanReport renders.

data/lib/deckard/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deckard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rob Sanheim