namo 0.27.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5649b6afb8e1272273a87286f053376ad42caddec81eed0610a672f26bc7e66a
-  data.tar.gz: 77a5e0c6499c3d600b76753e28c5e600b0dcd6dc0968d93069a56e3b10fc7652
+  metadata.gz: 5e56f3159063720b0e933e9c346ddad824831a51dac7a576da6d0cf841fd28ea
+  data.tar.gz: 8aee98bb89f8c7ab978c0ce459cc90c8259123123c13f5158a3e16dbb93922c7
 SHA512:
-  metadata.gz: 33c03e6c39cee1242a576a8355928b041464c9049a5bbb54900b7654dc36a9dec44741edaf28a8408eb293f4fcf4b702736841e8cf3b3bae7ce43e6684b098f1
-  data.tar.gz: d0ad82d6b415a09ba086a9d6a7b0f06c24d1dfad8bb3eaad72e1a40c878f9a431ccfb093f781836a94d0d4f4ab6bdf8b7917ddb61123012bf1fd0455168e3e05
+  metadata.gz: 16e3d16921ee88ae7d5d76c79227efb035128ac46f17d93fa61c7445434bb1c475c597ff7e2478fe19bbaf8f53b73ed366fee5ed1e514ad99a423a030db0d46c
+  data.tar.gz: 7e0045e6e6a842be576e171c9c31bde901f7ade581e5dce694e853a868f832c358e5eb7329ce9fc14efdc13a20663f4877135895f99328d646bb8717d177a2af

data/CHANGELOG

@@ -1,5 +1,33 @@
 # CHANGELOG
 
+## 20260715
+
+0.29.0: Per access indexed materialisation.
+
+Materialise each column once per top-level access, collapsing an O(n²) parent-scanning formula to O(n), with no value retained across accesses.
+
+1. ~ Namo#values: wrap the body in a private materialising scope.
+2. ~ Namo#values_for: memoise its column build into @materialised[dim] ||= (the data/derived branch that was its body).
+3. + Namo#materialising (a per-access scope that sets @materialised, yields, and clears it in an ensure; a nested values call reuses the open scope rather than starting another). A formula that scans its parent asks for the same column once per row it visits; the scope materialises that column once and reuses it for the rest of the access, then discards it — so every access still recomputes from current state and nothing can go stale. Enumerable is untouched: iteration paths (each/select/map/group_by) do not yet open the scope.
+4. ~ test/namo_test.rb: + an "access-scoped materialisation" describe — a referenced column materialises once per access, not once per referencing row; nothing is retained across accesses (a later access recomputes from current state); the scope clears on a raising materialisation, leaving later accesses working.
+5. ~ README.md: ~ the cross-row liveness note — "with no caching" becomes "with no caching across accesses", the within-access materialisation being a loop-invariant hoist, not a cache.
+6. ~ ROADMAP.md: + the 0.29.0 entry; current-state bumped to 0.29.0; the 1.x pure-live passages refined from "no memoisation anywhere" to the invariant "no derived value outlives the access that produced it"; the Live-data-and-cache-invalidation open question gains the access-scoped resolution; + forward notes on streaming performance vs incremental maintenance (a commercial-tier candidate) and on formula opacity as the shared wall behind ===, dependency-aware projection, serialisation, and incremental streaming.
+7. ~ docs/: regenerate the print-ready PDFs.
+8. ~ Namo::VERSION: /0.28.0/0.29.0/
+
+## 20260713
+
+0.28.0: ~ Namo::Collection#detail/#as_detail: Accept the by label positionally or by keyword.
+
+Accept the by label positionally or by keyword (positional winning), per the constructor precedent — resolving the detail/as_detail calling-convention asymmetry.
+
+1. ~ Namo::Collection#detail(positional_by = nil, by: :member), #as_detail(positional_by = nil, by: :member): resolve by = positional_by || by, mirroring the constructor's @data = positional_data || data; positional wins. summary/as_summary unchanged — dimension stays their positional, by: the keyword modifier.
+2. ~ test/Namo/Collection_test.rb: + detail and as_detail each take the by label positionally or by keyword, positional winning over a conflicting keyword.
+3. ~ README.md: ~ the view-methods note — detail/as_detail take the label positionally or by keyword (the constructor's shape); replaces the "carries no dimension, so positional" rationale.
+4. ~ ROADMAP.md: + the 0.28.0 entry (twin asymmetry, constructor precedent, primary-dual/modifier-keyword scope); current-state bumped to 0.28.0; a forward-reference on the 0.18.0 note superseding its positional rationale.
+5. ~ docs/: regenerate the print-ready PDFs.
+6. ~ Namo::VERSION: /0.27.0/0.28.0/
+
 ## 20260710
 
 0.27.0: ~ Namo::Collection#summary/#as_summary: + an optional block for a per-member reduction beyond a single named reducer.

data/README.md

@@ -688,7 +688,7 @@ prices.values(:sma)
 # => [10.0, 15.0, 20.0]
 ```
 
-`namo` is the Namo that yielded the row, live — so the window always reflects the current state of the object you ask through. A filtered Namo's rows window over the filtered rows; an operator result's rows window over the result. Appending a row changes every cross-row value on the next access, with no caching.
+`namo` is the Namo that yielded the row, live — so the window always reflects the current state of the object you ask through. A filtered Namo's rows window over the filtered rows; an operator result's rows window over the result. Appending a row changes every cross-row value on the next access, with no caching across accesses.
 
 One-arity formulae are unchanged, and the two forms mix freely — a one-arity formula can reference a two-arity one, and a two-arity formula can reference a one-arity one, by name.
 
@@ -1075,7 +1075,7 @@ Detail is the lazy view because a Collection's rows simply *are* its members' ro
 The views come in a non-mutating pair and a mutating pair:
 
 - `summary(dimension = nil, by:, reducer:, &block)` and `detail(by:)` are **non-mutating** — each returns a fresh `Namo` derived from the members, leaving the Collection untouched. Use these when you want a view to keep: assign the result to a variable and operate on it independently.
-- `as_summary(dimension = nil, by:, reducer:, &block)` and `as_detail(by)` are **mutating** — each sets the Collection's data to the chosen view and returns `self`, for a fluent step. (`as_detail` carries no `dimension`, so its label argument is positional: `as_detail(:assembly)`.)
+- `as_summary(dimension = nil, by:, reducer:, &block)` and `as_detail(by = :member)` are **mutating** — each sets the Collection's data to the chosen view and returns `self`, for a fluent step. (`detail` and `as_detail` take the origin label either positionally or by the `by:` keyword, positional winning — the same shape the constructor gives `data` — so `as_detail(:assembly)` and `as_detail(by: :assembly)` are one call. `summary`/`as_summary` keep `by:` a keyword beside their `dimension` positional.)
 
 ```ruby
 gt.summary(:cost, reducer: :mean)          # a fresh Namo; gt is unchanged

data/lib/Namo/Collection.rb

@@ -34,7 +34,8 @@ class Namo
       Namo.new(rows)
     end
 
-    def detail(by: :member)
+    def detail(positional_by = nil, by: :member)
+      by = positional_by || by
       rows = @members.flat_map do |member|
         member.data.map{|row| row.key?(by) ? row : row.merge(by => member.name)}
       end
@@ -46,8 +47,9 @@ class Namo
       self
     end
 
-    def as_detail(by = :member)
-      @data = detail(by: by).data
+    def as_detail(positional_by = nil, by: :member)
+      by = positional_by || by
+      @data = detail(by).data
       self
     end
 

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.27.0'
+  VERSION = '0.29.0'
 end

data/lib/namo.rb

@@ -30,12 +30,14 @@ class Namo
   end
 
   def values(*dims)
-    if dims.empty?
-      materialisable_dimensions.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
-    elsif dims.length == 1
-      values_for(dims.first)
-    else
-      dims.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+    materialising do
+      if dims.empty?
+        materialisable_dimensions.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+      elsif dims.length == 1
+        values_for(dims.first)
+      else
+        dims.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+      end
     end
   end
 
@@ -290,14 +292,26 @@ class Namo
     end
   end
 
-  def values_for(dim)
-    if data_dimensions.include?(dim)
-      @data.map{|row_data| row_data[dim]}
-    else
-      @data.map{|row_data| Row.new(row_data, @formulae, self)[dim]}
+  def materialising
+    return yield if @materialised
+    @materialised = {}
+    begin
+      yield
+    ensure
+      @materialised = nil
     end
   end
 
+  def values_for(dim)
+    @materialised[dim] ||= (
+      if data_dimensions.include?(dim)
+        @data.map{|row_data| row_data[dim]}
+      else
+        @data.map{|row_data| Row.new(row_data, @formulae, self)[dim]}
+      end
+    )
+  end
+
   def materialisable_dimensions
     dimensions.reject{|dim| requires_arguments?(dim)}
   end

data/test/Namo/Collection_test.rb

@@ -245,6 +245,12 @@ describe Namo::Collection do
       collection.detail(by: :assembly)
       _(collection.dimensions).wont_include :assembly
     end
+
+    it "takes the by label positionally or by keyword, positional winning" do
+      _(collection.detail(:assembly).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+      _(collection.detail(by: :assembly).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+      _(collection.detail(:assembly, by: :ignored).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+    end
   end
 
   describe "live recomputation (no memoisation in 1.x)" do
@@ -285,6 +291,14 @@ describe Namo::Collection do
       _(collection.values(:assembly)).must_equal [:powertrain, :chassis, :body]
       _(collection.values(:count)).must_equal [2, 1, 1]
     end
+
+    it "as_detail takes the by label positionally or by keyword, positional winning" do
+      positional = Namo::Collection.new.tap{|c| c << [powertrain, chassis]}.as_detail(:assembly)
+      keyword    = Namo::Collection.new.tap{|c| c << [powertrain, chassis]}.as_detail(by: :assembly)
+      _(positional.values(:assembly)).must_equal [:powertrain, :powertrain, :chassis]
+      _(keyword.values(:assembly)).must_equal positional.values(:assembly)
+      _(Namo::Collection.new.tap{|c| c << powertrain}.as_detail(:assembly, by: :ignored).values(:assembly)).must_equal [:powertrain, :powertrain]
+    end
   end
 
   describe "as_* view lifetime (rebuild-on-<<: persists until the next <<)" do

data/test/namo_test.rb

@@ -287,6 +287,44 @@ describe Namo do
     end
   end
 
+  describe "access-scoped materialisation" do
+    it "materialises a referenced column once per access, not once per referencing row" do
+      calls = Hash.new(0)
+      namo = Namo.new([{n: 1}, {n: 2}, {n: 3}])
+      namo[:base] = proc{|row| calls[:base] += 1; row[:n] * 10}
+      namo[:sum_base] = proc{|row, namo| namo.values(:base).sum}
+      _(namo.values(:sum_base)).must_equal [60, 60, 60]
+      _(calls[:base]).must_equal 3
+    end
+
+    it "retains nothing across accesses — a later access recomputes from current state" do
+      namo = Namo.new([{n: 1}, {n: 2}])
+      namo[:total] = proc{|row, namo| namo.values(:n).sum}
+      _(namo.values(:total)).must_equal [3, 3]
+      namo.data << {n: 4}
+      _(namo.values(:total)).must_equal [7, 7, 7]
+    end
+
+    it "clears the access scope when materialisation raises, leaving later accesses working" do
+      namo = Namo.new([{n: 1}])
+      namo[:boom] = proc{|row| raise 'materialisation blew up'}
+      _(->{namo.values(:boom)}).must_raise RuntimeError
+      namo[:ok] = proc{|row| row[:n]}
+      _(namo.values(:ok)).must_equal [1]
+    end
+
+    it "keeps one scope when a formula's nested values call runs during a multi-dimension access" do
+      calls = 0
+      namo = Namo.new([{x: 1}, {x: 2}, {x: 3}])
+      namo[:base] = proc{|row| calls += 1; row[:x] * 2}
+      namo[:agg] = proc{|row, namo| namo.values(:base).first}
+      # :agg's formula calls values(:base) mid-materialisation; that nested call must
+      # reuse the open scope, not reset it, so the :x column that follows still builds.
+      _(namo.values(:agg, :x)).must_equal(agg: [2, 2, 2], x: [1, 2, 3])
+      _(calls).must_equal 3
+    end
+  end
+
   describe "#to_h" do
     it "returns the full values Hash" do
       _(sales.to_h).must_equal sales.values

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.29.0
 platform: ruby
 authors:
 - thoran
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []