namo 0.13.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 480baeb4c1da195bc5e9800df21267467dd784a4ef6b4fc41cd1997925c36432
-  data.tar.gz: d1794682a82a35578e87734569808b61171ceb95f2d0548e761b42052ea5223b
+  metadata.gz: 78880ca991afa35b970cc09625c4ca632db3a3ff69e7b4c69fda2fa3b536bd08
+  data.tar.gz: b85bfe8ef28cf45880e8ebda997d209e7a4f6d545710bad52ec4f6e5c790e30f
 SHA512:
-  metadata.gz: 203c4416d177b726d3f8bec5bebf5225f9bb28cbf2ca3fbae1365f8f0d4062ce95018233e4342ec29b33f2bf753849acc512f1ff017f0925eec629caece73781
-  data.tar.gz: a9ca4f20b7319825652588fe780e59601744447c38cddbfe0d2ce2c624200d249ce1ff43113a5d543737ab5789890392a48ff2fcf3dca52c3d5f25c999838bee
+  metadata.gz: c61419caff79be760cc24d3cd67eb008107061a65041853bd5108e51c70bf0fb100e50c899241b2ae45de59d92c9f7bcd6173eb2af279543c9057c186c3ec4ba
+  data.tar.gz: 5b9fe7311512c5a59f6528d70a82724f35323769267a804784d14a83351da08cb62000feb6f676e396ecd45c79397413f754cb09c599e5204f28212e95caa872

data/CHANGELOG

@@ -1,6 +1,37 @@
 CHANGELOG
 _________
 
+20260608
+0.14.0: + blocks on the composition operators (*, **) for custom match refinement.
+
+1. ~ lib/namo.rb: Namo#* takes an optional block. Without a block, behaviour is unchanged.
+   With a block, the right rows matched on the shared data dimensions are passed as a Namo
+   (candidates, carrying other's formulae) alongside the left Row (carrying self's
+   formulae); the block returns a Namo of the rows to pair, each merged into the left row.
+   An empty returned Namo drops the left row (inner-join semantics). Result formulae are
+   other.formulae.merge(@formulae) as before — the block does not affect result formulae.
+   The shared-dimension precondition still applies with a block present.
+2. ~ lib/namo.rb: Namo#** takes an optional block, same contract, with candidates being all
+   of other's rows (no shared-dimension pre-filter). The disjoint-dimensions precondition
+   still applies with a block present.
+3. ~ test/namo_test.rb: + "with a block" context under #* (single-match one-row return, empty-return
+   drop, multi-row return, selection on other's derived dimension, reference to self's
+   derived dimension, result-formulae parity with no-block, derived-not-stored-but-resolves,
+   subclass type, preconditions still raise) and under #** (selector filtering one-to-many,
+   empty-return drop, full-candidates reproduces no-block, selection on other's derived
+   dimension, result-formulae parity, disjoint precondition still raises, subclass type).
+   Existing no-block #* and #** tests unchanged and green.
+4. ~ README.md: + block subsections under Composition and Cartesian product, with the
+   price/quarterly matching and orders/tiers worked examples and the (row, candidates) ->
+   Namo contract.
+5. ~ ROADMAP.md: Promote 0.14.0 to shipped (composition blocks only); Current state -> 0.14.0;
+   Summary folds in composition blocks; next phase -> 0.15.0. + the governing principle
+   (a block form is warranted iff the operation gives consideration to a dimension in
+   isolation), tied to the orthogonality/efficiency rationale for why set-operator/`/`
+   blocks were not added. The now-redundant upcoming 0.14.0 section removed.
+6. ~ COMPARISON.md: "Conditional join with block" -> shipped (0.14.0).
+7. ~ Namo::VERSION: /0.13.2/0.14.0/
+
 20260608
 0.13.2: Narrow the planned 0.14.0 block-form scope to the composition operators and document the rationale.
 

data/README.md

@@ -355,6 +355,36 @@ Inner-join semantics: unmatched rows from either side are dropped. Output dimens
 
 The two Namos must have at least one shared data dimension. No overlap raises an `ArgumentError` — the asymmetry with `**` is deliberate, and falling through to a Cartesian product would silently turn a logic error into a large pile of nonsense rows. Formulae merge from both sides; the left-hand side wins on conflict.
 
+#### Conditional join
+
+`*` takes an optional block that decides which matched rows to pair with each left row. Without a block, every shared-dimension match pairs, as above. With one, the block is handed the current left row and the right rows already matched on the shared dimensions, and returns the subset to pair — the refinement plain `*` can't express, because it pairs every match.
+
+The canonical case is matching each daily price to a single quarterly report — the most recent one dated on or before it. Plain `*` pairs *every* matching quarter; the block narrows that to the one the matching rule picks.
+
+```ruby
+prices = Namo.new([
+  {symbol: 'BHP', date: '2025-02-15', close: 42.5},
+  {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+])
+
+quarterly = Namo.new([
+  {symbol: 'BHP', quarter_end: '2024-12-31', eps: 1.0},
+  {symbol: 'BHP', quarter_end: '2025-03-31', eps: 1.2}
+])
+
+prices.*(quarterly) do |row, candidates|
+  candidates[quarter_end: ->(qe){qe <= row[:date]}].sort_by{|f| f[:quarter_end]}.last(1)
+end
+# => #<Namo [
+#   {symbol: 'BHP', date: '2025-02-15', close: 42.5, quarter_end: '2024-12-31', eps: 1.0},
+#   {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+# ]>
+```
+
+`row` is the `Row` for the current left row, carrying self's formulae, so `row[:date]` and any self formula resolve inside the block. `candidates` is a Namo of the shared-dimension matches, carrying other's formulae, so the block can select on other's derived dimensions too. The block returns a Namo of the rows to pair: one row for the single-match rule above, though it may return zero, one, or many — it's a selector, not a reducer. An empty returned Namo pairs nothing, so that left row is dropped, preserving inner-join semantics. The block can also be passed as a named proc, `prices.*(quarterly, &most_recent_quarter)`.
+
+The block changes only which rows pair. Formulae carry through exactly as in the no-block form — other's merged under self's, self winning on conflict — and the rows the block returns contribute data only.
+
 ### Cartesian product
 
 `**` is the Cartesian product. Every row from the left paired with every row from the right:
@@ -378,6 +408,35 @@ The two Namos must have **no** shared data dimensions — the precondition is th
 
 The visual relationship is intentional: `*` is the filtered version, `**` is the explosive version — more sigil, more output.
 
+#### Conditional product
+
+`**` takes an optional block on the same contract. Where `*`'s block receives the rows pre-matched on the shared dimensions, `**`'s receives *all* of other's rows — there are no shared dimensions to match on — and returns the subset to pair with each left row.
+
+This expresses a conditional product: pair each order with only the shipping tiers that can carry it.
+
+```ruby
+orders = Namo.new([
+  {order: 'A', weight: 5},
+  {order: 'B', weight: 15}
+])
+
+tiers = Namo.new([
+  {tier: 'light', max_weight: 10},
+  {tier: 'heavy', max_weight: 20}
+])
+
+orders.**(tiers) do |row, candidates|
+  candidates[max_weight: ->(w){w >= row[:weight]}]
+end
+# => #<Namo [
+#   {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+#   {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+#   {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+# ]>
+```
+
+The contract matches `*`'s: `row` carries self's formulae, `candidates` carries other's, the block returns a Namo of rows to pair, and an empty return drops the left row. A block that returns its `candidates` unchanged reproduces the no-block product exactly — `**` is its own block form with the identity selector, just as `*` is `**` with the shared-dimension match applied first.
+
 ### Decomposition
 
 `/` removes from the left Namo the dimensions that are also in the right, then dedupes the projected rows. It's the inverse of `*` and `**`:

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.13.2'
+  VERSION = '0.14.0'
 end

data/lib/namo.rb

@@ -115,28 +115,35 @@ class Namo
     self.class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
   end
 
-  def *(other)
+  def *(other, &block)
     raise_unless_namo(other)
     raise_unless_shared_data_dimensions(other)
     shared = data_dimensions & other.data_dimensions
     combined_data = []
     @data.each do |left_row|
-      other.data.each do |right_row|
-        if shared.all?{|dim| left_row[dim] == right_row[dim]}
-          combined_data << left_row.merge(right_row)
-        end
+      matched = other.data.select{|right_row| shared.all?{|dim| left_row[dim] == right_row[dim]}}
+      if block
+        candidates = other.class.new(matched, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        matched.each{|right_row| combined_data << left_row.merge(right_row)}
       end
     end
     self.class.new(combined_data, formulae: other.formulae.merge(@formulae))
   end
 
-  def **(other)
+  def **(other, &block)
     raise_unless_namo(other)
     raise_unless_disjoint_data_dimensions(other)
     combined_data = []
     @data.each do |left_row|
-      other.data.each do |right_row|
-        combined_data << left_row.merge(right_row)
+      if block
+        candidates = other.class.new(other.data, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        other.data.each{|right_row| combined_data << left_row.merge(right_row)}
       end
     end
     self.class.new(combined_data, formulae: other.formulae.merge(@formulae))

data/test/namo_test.rb

@@ -1450,6 +1450,126 @@ describe Namo do
       b = Namo.new([{symbol: 'BHP', pe: 14.5}])
       _((a * b).class).must_equal subclass
     end
+
+    context "with a block" do
+      let(:prices) do
+        Namo.new([
+          {symbol: 'BHP', date: '2025-02-15', close: 42.5},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+        ])
+      end
+
+      let(:quarterly) do
+        Namo.new([
+          {symbol: 'BHP', quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', quarter_end: '2025-03-31', eps: 1.2}
+        ])
+      end
+
+      let(:most_recent_quarter) do
+        proc do |row, candidates|
+          candidates[quarter_end: ->(qe){qe <= row[:date]}].sort_by{|f| f[:quarter_end]}.last(1)
+        end
+      end
+
+      it "pairs each left row with the single match the block returns" do
+        result = prices.*(quarterly, &most_recent_quarter)
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-02-15', close: 42.5, quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "drops a left row whose block returns an empty Namo" do
+        early = Namo.new([
+          {symbol: 'BHP', date: '2024-06-01', close: 40.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+        ])
+        result = early.*(quarterly, &most_recent_quarter)
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "pairs each row when the block returns a multi-row Namo (selector, not reducer)" do
+        left = Namo.new([{symbol: 'BHP', date: '2025-05-20', close: 44.0}])
+        result = left.*(quarterly){|row, candidates| candidates}
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "selects on a derived dimension of other inside the block" do
+        prices = Namo.new([
+          {symbol: 'BHP', close: 42.5},
+          {symbol: 'RIO', close: 118.3}
+        ])
+        funds = Namo.new([
+          {symbol: 'BHP', price: 42.5, eps: 3.0},
+          {symbol: 'RIO', price: 118.3, eps: 13.0}
+        ])
+        funds[:pe] = proc{|f| f[:price] / f[:eps]}
+        result = prices.*(funds){|row, candidates| candidates[pe: ->(v){v && v < 10}]}
+        _(result.values(:symbol)).must_equal ['RIO']
+        _(result.values(:close)).must_equal [118.3]
+      end
+
+      it "resolves a derived dimension of self referenced in the block" do
+        dated = Namo.new([{symbol: 'BHP', date: '2025-05-20', close: 44.0}])
+        dated[:cutoff] = proc{|r| r[:date]}
+        result = dated.*(quarterly){|row, candidates| candidates[quarter_end: ->(qe){qe <= row[:cutoff]}].sort_by{|f| f[:quarter_end]}.last(1)}
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "produces the same result formulae as the no-block form" do
+        ohlcv = Namo.new([
+          {symbol: 'BHP', close: 42.5},
+          {symbol: 'RIO', close: 118.3}
+        ])
+        fundamentals = Namo.new([
+          {symbol: 'BHP', pe: 14.5},
+          {symbol: 'RIO', pe: 9.2}
+        ])
+        ohlcv[:label] = proc{|r| "#{r[:symbol]}-self"}
+        fundamentals[:flag] = proc{|r| "pe=#{r[:pe]}"}
+        blocked = ohlcv.*(fundamentals){|row, candidates| candidates}
+        plain = ohlcv * fundamentals
+        _(blocked.derived_dimensions).must_equal plain.derived_dimensions
+        _(blocked.values(:label)).must_equal plain.values(:label)
+        _(blocked.values(:flag)).must_equal plain.values(:flag)
+      end
+
+      it "leaves other's derived dimension unstored but resolvable on the result" do
+        prices = Namo.new([{symbol: 'BHP', close: 42.5}])
+        funds = Namo.new([{symbol: 'BHP', price: 42.5, eps: 3.0}])
+        funds[:pe] = proc{|f| f[:price] / f[:eps]}
+        result = prices.*(funds){|row, candidates| candidates}
+        _(result.data_dimensions).wont_include :pe
+        _(result.derived_dimensions).must_include :pe
+        _(result.values(:pe)).must_equal [42.5 / 3.0]
+      end
+
+      it "returns an instance of self's class" do
+        subclass = Class.new(Namo)
+        a = subclass.new([{symbol: 'BHP', close: 42.5}])
+        b = Namo.new([{symbol: 'BHP', pe: 14.5}])
+        result = a.*(b){|row, candidates| candidates}
+        _(result.class).must_equal subclass
+      end
+
+      it "still raises ArgumentError on no shared dimensions" do
+        a = Namo.new([{symbol: 'BHP'}])
+        b = Namo.new([{quarter: 'Q1'}])
+        _ { a.*(b){|row, candidates| candidates} }.must_raise ArgumentError
+      end
+
+      it "still raises TypeError on a non-Namo operand" do
+        _ { ohlcv.*([{symbol: 'BHP'}]){|row, candidates| candidates} }.must_raise TypeError
+      end
+    end
   end
 
   describe "#**" do
@@ -1529,6 +1649,90 @@ describe Namo do
       b = Namo.new([{quarter: 'Q1'}])
       _((a ** b).class).must_equal subclass
     end
+
+    context "with a block" do
+      let(:orders) do
+        Namo.new([
+          {order: 'A', weight: 5},
+          {order: 'B', weight: 15}
+        ])
+      end
+
+      let(:tiers) do
+        Namo.new([
+          {tier: 'light', max_weight: 10},
+          {tier: 'heavy', max_weight: 20}
+        ])
+      end
+
+      it "filters pairings by the selector block (one-to-many)" do
+        result = orders.**(tiers){|row, candidates| candidates[max_weight: ->(w){w >= row[:weight]}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "drops a left row whose block returns an empty Namo" do
+        with_unservable = Namo.new([
+          {order: 'C', weight: 50},
+          {order: 'A', weight: 5}
+        ])
+        result = with_unservable.**(tiers){|row, candidates| candidates[max_weight: ->(w){w >= row[:weight]}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "reproduces the no-block product when the block returns all candidates" do
+        blocked = products.**(quarters){|row, candidates| candidates}
+        plain = products ** quarters
+        _(blocked.to_a).must_equal plain.to_a
+      end
+
+      it "selects on a derived dimension of other inside the block" do
+        weighted_tiers = Namo.new([
+          {tier: 'light', max_weight: 10},
+          {tier: 'heavy', max_weight: 20}
+        ])
+        weighted_tiers[:premium] = proc{|t| t[:max_weight] > 15}
+        result = orders.**(weighted_tiers){|row, candidates| candidates[premium: ->(v){v}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "produces the same result formulae as the no-block form" do
+        products[:plabel] = proc{|r| "p=#{r[:product]}"}
+        quarters[:qlabel] = proc{|r| "q=#{r[:quarter]}"}
+        blocked = products.**(quarters){|row, candidates| candidates}
+        plain = products ** quarters
+        _(blocked.derived_dimensions).must_equal plain.derived_dimensions
+        _(blocked.values(:plabel)).must_equal plain.values(:plabel)
+        _(blocked.values(:qlabel)).must_equal plain.values(:qlabel)
+      end
+
+      it "returns an instance of self's class" do
+        subclass = Class.new(Namo)
+        a = subclass.new([{product: 'Widget'}])
+        b = Namo.new([{quarter: 'Q1'}])
+        result = a.**(b){|row, candidates| candidates}
+        _(result.class).must_equal subclass
+      end
+
+      it "still raises ArgumentError when a dimension is shared" do
+        a = Namo.new([{symbol: 'BHP', close: 42.5}])
+        b = Namo.new([{symbol: 'RIO', pe: 14.5}])
+        _ { a.**(b){|row, candidates| candidates} }.must_raise ArgumentError
+      end
+
+      it "still raises TypeError on a non-Namo operand" do
+        _ { products.**([{quarter: 'Q1'}]){|row, candidates| candidates} }.must_raise TypeError
+      end
+    end
   end
 
   describe "#/" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.14.0
 platform: ruby
 authors:
 - thoran