flexor 0.1.0

data/benchmark/compare.rb

@@ -0,0 +1,173 @@
+require "benchmark/ips"
+require "ostruct"
+require_relative "../lib/flexor"
+
+begin
+  require "hashie"
+  Hashie.logger = Logger.new(File::NULL)
+  HAS_HASHIE = true
+rescue LoadError
+  HAS_HASHIE = false
+  warn "Hashie not installed skipping Mash benchmarks. Install with: gem install hashie"
+end
+
+def hashie_report(bench, label, &block)
+  bench.report(label, &block) if HAS_HASHIE
+end
+
+FLAT_HASH = { name: "alice", age: 30, city: "NYC" }.freeze
+NESTED_HASH = { user: { name: "alice", address: { city: "NYC", zip: "10001" } } }.freeze
+DEEP_HASH = { a: { b: { c: { d: { e: "deep" } } } } }.freeze
+
+puts "Ruby #{RUBY_VERSION} (YJIT: #{defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled? ? "enabled" : "disabled"})"
+puts "Flexor #{Flexor::VERSION}"
+puts "Hashie #{Hashie::VERSION}" if HAS_HASHIE
+puts
+
+# --- 1. Construction ---
+puts "=" * 60
+puts "CONSTRUCTION"
+puts "=" * 60
+
+Benchmark.ips do |x|
+  x.report("Flexor.new (flat)") { Flexor.new(FLAT_HASH) }
+  x.report("Mash.new (flat)")   { Hashie::Mash.new(FLAT_HASH) } if HAS_HASHIE
+  x.report("OpenStruct (flat)") { OpenStruct.new(FLAT_HASH) }
+  x.compare!
+end
+
+puts
+
+Benchmark.ips do |x|
+  x.report("Flexor.new (nested)") { Flexor.new(NESTED_HASH) }
+  x.report("Mash.new (nested)")   { Hashie::Mash.new(NESTED_HASH) } if HAS_HASHIE
+  x.report("OpenStruct (nested)") { OpenStruct.new(NESTED_HASH) }
+  x.compare!
+end
+
+# --- 2. Reading (method access) ---
+puts
+puts "=" * 60
+puts "READING (method access)"
+puts "=" * 60
+
+flexor  = Flexor.new(FLAT_HASH)
+mash    = HAS_HASHIE ? Hashie::Mash.new(FLAT_HASH) : nil
+ostruct = OpenStruct.new(FLAT_HASH)
+
+Benchmark.ips do |x|
+  x.report("Flexor#name")       { flexor.name }
+  x.report("Mash#name")         { mash.name } if HAS_HASHIE
+  x.report("OpenStruct#name")   { ostruct.name }
+  x.compare!
+end
+
+# --- 3. Reading (nested chaining) ---
+puts
+puts "=" * 60
+puts "READING (nested chaining)"
+puts "=" * 60
+
+flexor_nested = Flexor.new(NESTED_HASH)
+mash_nested   = HAS_HASHIE ? Hashie::Mash.new(NESTED_HASH) : nil
+
+Benchmark.ips do |x|
+  x.report("Flexor chain") { flexor_nested.user.address.city }
+  x.report("Mash chain")   { mash_nested.user.address.city } if HAS_HASHIE
+  x.compare!
+end
+
+# --- 4. Writing ---
+puts
+puts "=" * 60
+puts "WRITING (method setter)"
+puts "=" * 60
+
+Benchmark.ips do |x|
+  f = Flexor.new
+  m = HAS_HASHIE ? Hashie::Mash.new : nil
+  o = OpenStruct.new
+
+  x.report("Flexor#name=")       { f.name = "bob" }
+  x.report("Mash#name=")         { m.name = "bob" } if HAS_HASHIE
+  x.report("OpenStruct#name=")   { o.name = "bob" }
+  x.compare!
+end
+
+# --- 5. Writing (hash assignment with vivification) ---
+puts
+puts "=" * 60
+puts "WRITING (hash assignment)"
+puts "=" * 60
+
+Benchmark.ips do |x|
+  x.report("Flexor []= hash") {
+    f = Flexor.new
+    f[:config] = { db: { host: "localhost" } }
+  }
+  hashie_report(x, "Mash []= hash") { Hashie::Mash.new.tap { |m| m[:config] = { db: { host: "localhost" } } } }
+  x.compare!
+end
+
+# --- 6. Deep autovivification ---
+puts
+puts "=" * 60
+puts "AUTOVIVIFICATION (deep write)"
+puts "=" * 60
+
+Benchmark.ips do |x|
+  x.report("Flexor a.b.c.d=") {
+    f = Flexor.new
+    f.a.b.c.d = "deep"
+  }
+  hashie_report(x, "Mash a!.b!.c!.d=") { Hashie::Mash.new.tap { |m| m.a!.b!.c!.d = "deep" } }
+  x.compare!
+end
+
+# --- 7. to_h conversion ---
+puts
+puts "=" * 60
+puts "CONVERSION (to_h)"
+puts "=" * 60
+
+flexor_deep  = Flexor.new(DEEP_HASH)
+mash_deep    = HAS_HASHIE ? Hashie::Mash.new(DEEP_HASH) : nil
+ostruct_flat = OpenStruct.new(FLAT_HASH)
+
+Benchmark.ips do |x|
+  x.report("Flexor#to_h (deep)") { flexor_deep.to_h }
+  x.report("Mash#to_h (deep)")   { mash_deep.to_h } if HAS_HASHIE
+  x.report("OpenStruct#to_h")    { ostruct_flat.to_h }
+  x.compare!
+end
+
+# --- 8. Deep merge ---
+puts
+puts "=" * 60
+puts "DEEP MERGE"
+puts "=" * 60
+
+flexor_base = Flexor.new({ db: { host: "localhost", port: 5432 }, log: "info" })
+mash_base   = HAS_HASHIE ? Hashie::Mash.new({ db: { host: "localhost", port: 5432 }, log: "info" }) : nil
+override    = { db: { port: 3306, name: "mydb" }, log: "debug" }
+
+Benchmark.ips do |x|
+  x.report("Flexor#merge") { flexor_base.merge(override) }
+  x.report("Mash#merge")   { mash_base.merge(override) } if HAS_HASHIE
+  x.compare!
+end
+
+# --- 9. Missing key access ---
+puts
+puts "=" * 60
+puts "MISSING KEY ACCESS"
+puts "=" * 60
+
+flexor_empty = Flexor.new
+mash_empty   = HAS_HASHIE ? Hashie::Mash.new : nil
+
+Benchmark.ips do |x|
+  x.report("Flexor missing") { flexor_empty.nope }
+  x.report("Mash missing")   { mash_empty.nope } if HAS_HASHIE
+  x.compare!
+end

data/benchmark/results-with-caching.txt

@@ -0,0 +1,175 @@
+Ruby 4.0.1 (YJIT: enabled)
+Flexor 0.0.1
+Hashie 5.1.1
+
+============================================================
+CONSTRUCTION
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+   Flexor.new (flat)   163.066k i/100ms
+     Mash.new (flat)    52.640k i/100ms
+   OpenStruct (flat)    13.099k i/100ms
+Calculating -------------------------------------
+   Flexor.new (flat)      1.721M (± 9.6%) i/s  (581.18 ns/i) -      8.642M in   5.094349s
+     Mash.new (flat)    533.781k (± 1.4%) i/s    (1.87 μs/i) -      2.685M in   5.030551s
+   OpenStruct (flat)    124.015k (± 5.2%) i/s    (8.06 μs/i) -    628.752k in   5.086193s
+
+Comparison:
+   Flexor.new (flat):  1720629.7 i/s
+     Mash.new (flat):   533781.0 i/s - 3.22x  slower
+   OpenStruct (flat):   124015.0 i/s - 13.87x  slower
+
+
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+ Flexor.new (nested)    65.146k i/100ms
+   Mash.new (nested)    21.485k i/100ms
+ OpenStruct (nested)    28.870k i/100ms
+Calculating -------------------------------------
+ Flexor.new (nested)    623.855k (± 3.3%) i/s    (1.60 μs/i) -      3.127M in   5.018035s
+   Mash.new (nested)    214.900k (± 1.5%) i/s    (4.65 μs/i) -      1.096M in   5.099994s
+ OpenStruct (nested)    252.759k (± 5.2%) i/s    (3.96 μs/i) -      1.270M in   5.040492s
+
+Comparison:
+ Flexor.new (nested):   623854.6 i/s
+ OpenStruct (nested):   252759.3 i/s - 2.47x  slower
+   Mash.new (nested):   214900.2 i/s - 2.90x  slower
+
+
+============================================================
+READING (method access)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+         Flexor#name   799.709k i/100ms
+           Mash#name   343.414k i/100ms
+     OpenStruct#name     1.220M i/100ms
+Calculating -------------------------------------
+         Flexor#name     10.128M (± 9.4%) i/s   (98.74 ns/i) -     50.382M in   5.024214s
+           Mash#name      3.849M (± 8.8%) i/s  (259.78 ns/i) -     19.231M in   5.036833s
+     OpenStruct#name     17.994M (± 8.7%) i/s   (55.57 ns/i) -     90.310M in   5.059803s
+
+Comparison:
+     OpenStruct#name: 17993847.7 i/s
+         Flexor#name: 10127706.6 i/s - 1.78x  slower
+           Mash#name:  3849448.9 i/s - 4.67x  slower
+
+
+============================================================
+READING (nested chaining)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+        Flexor chain   294.871k i/100ms
+          Mash chain   124.885k i/100ms
+Calculating -------------------------------------
+        Flexor chain      3.695M (± 5.7%) i/s  (270.66 ns/i) -     18.577M in   5.046400s
+          Mash chain      1.428M (± 1.2%) i/s  (700.26 ns/i) -      7.243M in   5.073040s
+
+Comparison:
+        Flexor chain:  3694724.7 i/s
+          Mash chain:  1428036.7 i/s - 2.59x  slower
+
+
+============================================================
+WRITING (method setter)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+        Flexor#name=   575.837k i/100ms
+          Mash#name=    69.733k i/100ms
+    OpenStruct#name=   819.293k i/100ms
+Calculating -------------------------------------
+        Flexor#name=      6.786M (± 3.5%) i/s  (147.36 ns/i) -     33.974M in   5.014192s
+          Mash#name=    715.935k (± 1.2%) i/s    (1.40 μs/i) -      3.626M in   5.065556s
+    OpenStruct#name=      9.487M (±15.0%) i/s  (105.41 ns/i) -     45.880M in   5.005795s
+
+Comparison:
+    OpenStruct#name=:  9487184.9 i/s
+        Flexor#name=:  6785984.8 i/s - 1.40x  slower
+          Mash#name=:   715934.6 i/s - 13.25x  slower
+
+
+============================================================
+WRITING (hash assignment)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+     Flexor []= hash    70.692k i/100ms
+       Mash []= hash    42.105k i/100ms
+Calculating -------------------------------------
+     Flexor []= hash    722.453k (± 1.4%) i/s    (1.38 μs/i) -      3.676M in   5.089203s
+       Mash []= hash    427.759k (± 1.2%) i/s    (2.34 μs/i) -      2.147M in   5.020685s
+
+Comparison:
+     Flexor []= hash:   722453.4 i/s
+       Mash []= hash:   427758.7 i/s - 1.69x  slower
+
+
+============================================================
+AUTOVIVIFICATION (deep write)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+     Flexor a.b.c.d=     7.491k i/100ms
+    Mash a!.b!.c!.d=    26.742k i/100ms
+Calculating -------------------------------------
+     Flexor a.b.c.d=     70.677k (± 5.8%) i/s   (14.15 μs/i) -    359.568k in   5.107327s
+    Mash a!.b!.c!.d=    269.153k (± 1.5%) i/s    (3.72 μs/i) -      1.364M in   5.068281s
+
+Comparison:
+    Mash a!.b!.c!.d=:   269152.7 i/s
+     Flexor a.b.c.d=:    70677.4 i/s - 3.81x  slower
+
+
+============================================================
+CONVERSION (to_h)
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+  Flexor#to_h (deep)    53.044k i/100ms
+    Mash#to_h (deep)     1.113M i/100ms
+     OpenStruct#to_h   583.538k i/100ms
+Calculating -------------------------------------
+  Flexor#to_h (deep)    544.961k (± 1.6%) i/s    (1.83 μs/i) -      2.758M in   5.062731s
+    Mash#to_h (deep)     15.876M (± 1.5%) i/s   (62.99 ns/i) -     80.124M in   5.048076s
+     OpenStruct#to_h      7.316M (± 1.4%) i/s  (136.68 ns/i) -     36.763M in   5.025665s
+
+Comparison:
+    Mash#to_h (deep): 15875729.1 i/s
+     OpenStruct#to_h:  7316392.4 i/s - 2.17x  slower
+  Flexor#to_h (deep):   544960.9 i/s - 29.13x  slower
+
+
+============================================================
+DEEP MERGE
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+        Flexor#merge   141.366k i/100ms
+          Mash#merge    17.957k i/100ms
+Calculating -------------------------------------
+        Flexor#merge      1.520M (± 1.2%) i/s  (657.82 ns/i) -      7.634M in   5.022294s
+          Mash#merge    180.829k (± 0.9%) i/s    (5.53 μs/i) -    915.807k in   5.064952s
+
+Comparison:
+        Flexor#merge:  1520181.4 i/s
+          Mash#merge:   180828.6 i/s - 8.41x  slower
+
+
+============================================================
+MISSING KEY ACCESS
+============================================================
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [aarch64-linux]
+Warming up --------------------------------------
+      Flexor missing   806.094k i/100ms
+        Mash missing   133.262k i/100ms
+Calculating -------------------------------------
+      Flexor missing     10.920M (± 1.4%) i/s   (91.58 ns/i) -     54.814M in   5.020653s
+        Mash missing      1.289M (± 1.2%) i/s  (775.78 ns/i) -      6.530M in   5.066387s
+
+Comparison:
+      Flexor missing: 10919839.7 i/s
+        Mash missing:  1289028.6 i/s - 8.47x  slower
+

data/docs/benchmark-results.md

@@ -0,0 +1,64 @@
+# Benchmark: Flexor vs Hashie::Mash vs OpenStruct
+
+Ruby 4.0.1, YJIT enabled, aarch64-linux
+
+Flexor 0.0.1 | Hashie 5.1.1 | OpenStruct (stdlib)
+
+## Results (with lazy method caching)
+
+Flexor caches property accessors via `define_singleton_method`. Getters are cached only when the key already exists in the store — autovivified keys skip the caching cost on first access and cache on the second. Setters cache on first use.
+
+| Operation | Flexor | Mash | OpenStruct | Winner |
+|-----------|--------|------|------------|--------|
+| Construction (flat) | 1.74M i/s | 530K i/s | 124K i/s | **Flexor** 3.3x vs Mash, 14.0x vs OS |
+| Construction (nested) | 660K i/s | 216K i/s | 330K i/s | **Flexor** 3.1x vs Mash |
+| Read (method) | 10.8M i/s | 3.69M i/s | 19.4M i/s | **OpenStruct** 1.8x vs Flexor |
+| Read (nested chain) | 3.76M i/s | 1.43M i/s | — | **Flexor** 2.6x |
+| Write (setter) | 6.59M i/s | 717K i/s | 9.97M i/s | **OpenStruct** 1.5x vs Flexor |
+| Write (hash assign) | 720K i/s | 426K i/s | — | **Flexor** 1.7x |
+| Autovivification | 176K i/s | 270K i/s | — | **Mash** 1.5x |
+| to_h (deep) | 547K i/s | 15.3M i/s | 6.6M i/s | **Mash** 28x vs Flexor |
+| Deep merge | 1.50M i/s | 181K i/s | — | **Flexor** 8.3x |
+| Missing key access | 10.5M i/s | 1.32M i/s | — | **Flexor** 8.0x |
+
+## Method caching evolution
+
+| Operation | No caching | Eager caching | Lazy caching |
+|-----------|-----------|--------------|-------------|
+| Read (method) | 3.76M | 10.1M | **10.8M** |
+| Read (nested chain) | 1.32M | 3.69M | **3.76M** |
+| Write (setter) | 1.27M | 6.79M | **6.59M** |
+| Missing key access | 3.79M | 10.9M | **10.5M** |
+| Autovivification | **291K** | 71K (4x regression) | 176K (2.5x recovered) |
+
+Lazy caching keeps all the read/write speedups (2.7-5.3x faster than no caching) while recovering most of the autovivification regression (from 4x slower to 1.5x slower vs Mash).
+
+## Analysis
+
+### Why Flexor wins construction and merge
+
+Flexor's wrapper design is lighter at construction time. Creating a Flexor means building an autovivifying Hash via `default_proc` and iterating the input — no key conversion, no warning checks, no indifferent access setup. Mash converts every key to a string, checks for method collisions, and sets up its indifferent access layer.
+
+Deep merge is 8.3x faster because Flexor's `merge` does a `dup` + recursive `merge!`, while Mash's merge goes through its full `deep_update` pipeline with key conversion at every level.
+
+### Why Flexor is close to OpenStruct on reads and writes
+
+With method caching, Flexor uses the same strategy as OpenStruct: `define_singleton_method` on first access, direct method call thereafter. The remaining 1.8x gap on reads comes from Flexor's cached method delegating through `self[name]` → `@store[name]` (two method calls) vs OpenStruct's direct `@table[:name]` (one ivar access).
+
+### Why Mash wins to_h
+
+Mash IS a Hash (`Mash < Hash`), so `to_h` is essentially a no-op — it returns itself or a thin copy. Flexor wraps a Hash and must recursively convert every nested Flexor back to a plain Hash, filtering phantom keys along the way. This is the main cost of the wrapper design.
+
+For most use cases this doesn't matter — you call `to_h` at serialization boundaries, not in hot loops.
+
+### How lazy caching works
+
+The key insight: only cache getters when `@store.key?(name)` is true. On first access to an unset key, autovivification creates the key via `default_proc` but no singleton method is defined. On the second access, the key exists, so the method gets cached. Constructor-populated keys cache on first read since they already exist in the store.
+
+This means autovivification chains (`store.a.b.c.d = "deep"`) only pay the `define_singleton_method` cost for the final setter, not the intermediate getters. Short-lived Flexors created during chain construction are never burdened with cached methods.
+
+## Methodology
+
+Benchmarks use `benchmark-ips` which measures iterations per second over a 5-second window with warmup. Each operation is tested in isolation. OpenStruct is excluded from operations it doesn't support (nested chaining, autovivification, merge, missing key handling).
+
+Run: `ruby --yjit benchmark/compare.rb`