flexor 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 823be7501c328a913f46121e7aa40b37fde22d73505f92928087f0d68b9355e2
-  data.tar.gz: 717311911cdb6e059859390ef9b238c1f524ed96d52071563cbc9f56568d119a
+  metadata.gz: 4829c05a12464754b396dce1819af07f73ab4be5701bd1386bf75b17d25cf20d
+  data.tar.gz: c160abc174ce641f4b9f08fd5cdff829f64980b63282059d1181a88e8ee4aecd
 SHA512:
-  metadata.gz: 9abb50d29119d0cb6deb40e8a14dc1bed3cf860fc65eb599adb1fc8f740374fc664440dc55cc5b3868b1cbe93e44d262ea338ab544f0fc590d587d1d738ab047
-  data.tar.gz: 531b16d783d2f49bf68edd73a27b47a7565f17f6a465b12b64f9d9542e4d781b9b4dfdacf345b941bad847e36afdee523b8666f42d09cb6ef0dc9f4de393a9c4
+  metadata.gz: 7f9bcadb983ea41a9420a1bac2b4c537b24ad86ab8d515dfd9de01d3fd6c4feddab1d52a8e2afe9e82f1dfb40b233772bc30c80a243ef1543a39258413486596
+  data.tar.gz: '0858ff2f829320da4c0eefe619e5269063d649ea659d7d2c6c2b75cd3ed5adaacec74117689a6a73e104fe980c8a42f567d49706893ff3b347d6fc84436ccb4c'

data/.rubocop.yml

@@ -13,10 +13,9 @@ plugins:
   - rubocop-claude
   - rubocop-performance
   - rubocop-rspec
-  - rubocop-md
-  - rubocop-rake
 
 AllCops:
+  NewCops: enable
   TargetRubyVersion: 3.4
 
 # ===========================================================================
@@ -172,9 +171,6 @@ Style/RedundantReturn:
 # ===========================================================================
 # Overrides from rubocop-performance — disable chain-hostile cops
 # ===========================================================================
-Performance:
-  Exclude:
-    - "spec/**/*"
 
 # ChainArrayAllocation flags idiomatic pipelines for microsecond gains.
 # If we need real throughput we parallelize, not uglify.
@@ -233,12 +229,19 @@ Metrics/BlockLength:
     - heredoc
     - method_call
   AllowedMethods:
+    - command
     - describe
     - context
     - shared_examples
     - shared_examples_for
     - shared_context
 
+# Shared test contexts legitimately define many helpers (stdin, stdout,
+# stderr, env, cli, exit_status, output). These are a single fixture,
+# not independent concerns.
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
 # Anonymous forwarding (*, **, &) breaks TruffleRuby, JRuby, and
 # Ruby < 3.2. Named args are explicit and portable.
 #
@@ -379,16 +382,31 @@ RSpec/LeadingSubject:
 RSpec/ExpectChange:
   EnforcedStyle: block
 
-RSpec/NamedSubject:
+# Disabled because OpenStruct is used for testing
+Style/OpenStructUse:
   Enabled: false
 
-# PROJECT SPECIFIC:
-#
-# Behavior is very intricate here and warrants separation
-RSpec/SpecFilePathFormat:
+RSpec/NamedSubject:
   Enabled: false
 
+# Would rather be as thorough as possible here as this is inherently a "not normally safe" library
 RSpec/NestedGroups:
-  Enabled: false
+  Max: 4
+
 RSpec/MultipleExpectations:
-  Max: 3
+  Max: 2
+
+# Prefer the explicit &block rather than &
+Naming/BlockForwarding:
+  Enabled: false
+
+# has_key? is a standard Ruby Hash method. Renaming it would break the
+# public interface contract that Flexor quacks like a Hash.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - is_a?
+    - has_key?
+
+# This has bugs and is causing specs to fail when autocorrected
+Performance/RedundantMerge:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Rules
+
+1. DO NOT edit .rubocop.yml or add inline rubocop exemptions without explicit permission
+2. DO NOT run any git command that will rewrite history without explicit permission
+3. PREFER method & class extraction over comments
+4. Making new files, classes, modules, and methods IS NOT overengineering
+5. BEFORE writing code, identify which domain concept owns the behavior. Each class and module should have a single responsibility. If the new behavior doesn't fit an existing class's responsibility, create a new one — don't expand the scope of what's already there.
+6. DO NOT name classes with suffixes like "-er" or "-or" unless using a canonical pattern name (e.g., Parser, Router, Controller)
+7. ALWAYS write specs first. The workflow is: identify the domain concept (rule 5), write specs describing its behavior, then implement. No implementation without a failing spec.
+
+## Project
+
+Flexor is a Ruby gem providing a Hash-like data store with autovivifying nested access, nil-safe chaining, and seamless conversion between hashes and method-style access. Requires Ruby >= 3.4.
+
+## Commands
+
+- `rake spec` — run all tests
+- `bundle exec rspec spec/flexor/flexor_reading_spec.rb` — run a single spec file
+- `bundle exec rspec spec/flexor/flexor_reading_spec.rb:15` — run a single example by line
+- `rake rubocop` — run linter
+- `bundle exec rubocop -a` — autocorrect safe offenses
+- `rake` — run both specs and rubocop (default task)
+- `rake benchmark` — run performance benchmarks (uses YJIT)
+- `rake rdoc` — generate documentation
+- `rake version:current` — show current version
+- `rake version:bump` — bump patch version
+- `bin/console` — IRB session with Flexor loaded
+
+## Architecture
+
+Plugin-based architecture following the Sequel/Roda pattern. `Flexor` class body is a minimal plugin dispatcher. All behavior lives in plugins under `Flexor::Plugins`.
+
+**Plugin dispatcher** (`lib/flexor.rb`):
+- `Flexor.plugin(mod)` — includes `mod::StoreMethods`, extends `mod::ClassMethods`
+- `Flexor.register_plugin(:name, mod)` — symbol registration for lazy loading
+- Lifecycle hooks: `before_load` (dependencies), `after_load` (initialization)
+- Plugins compose via Ruby's method lookup chain — each calls `super`
+
+**Plugins:**
+- **`Plugins::Core`** (`lib/flexor/plugins/core.rb`) — all base store behavior: autovivifying `@store`, method-style access via `method_missing`, hash delegation, serialization (Marshal/YAML), vivification
+- **`Plugins::FlexKeys`** (`lib/flexor/plugins/flex_keys.rb`) — overrides `[]`, `[]=`, `delete`, `key?`, `set_raw`, `deconstruct_keys`, `read_via_method` to resolve camelCase/snake_case alternates before calling `super`
+
+**Utilities:**
+- **`CaseConversion`** (`lib/flexor/case_conversion.rb`) — pure `module_function` utilities: `camelize`, `underscore`, `case_counterpart`
+
+Key internals:
+- `@store` is the backing Hash with an autovivifying default block
+- `@root` flag distinguishes top-level instances from auto-created children (affects `inspect` and `nil?` behavior)
+- `method_missing` handles dynamic getter/setter; once accessed, singleton methods are cached for performance (`cache_getter`/`cache_setter`)
+- `nil?` returns `true` when `@store` is empty (non-root nodes appear nil-like until written to)
+- Adding a new feature means adding a new file in `lib/flexor/plugins/` — no existing files modified
+
+## Style Conventions (from .rubocop.yml)
+
+- Double quotes always (`Style/StringLiterals`)
+- No frozen_string_literal comments
+- Trailing commas in multiline literals/arguments
+- Pipeline-style chaining encouraged (multiline block chains allowed)
+- Block length max 8 (keeps blocks small, push logic into pipelines)
+- Dot-aligned chaining (`Layout/MultilineMethodCallIndentation: aligned`)
+- Consistent 2-space argument indentation (not aligned to first arg)
+- Explicit `begin/rescue/end` preferred over implicit method-body rescue
+- All classes require rdoc documentation (`Style/Documentation`)
+- RSpec: `expect { }.to change { }` block style, nested groups max 4, multiple expectations max 2
+
+## Tests
+
+Specs are organized by concern in `spec/flexor/` (reading, writing, merge, serialization, freeze, etc.). The top-level `spec/flexor_spec.rb` only checks the version. RSpec runs with `--format documentation` and monkey patching disabled.

data/Rakefile

@@ -1,8 +1,10 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
+require "gempilot/version_task"
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
+Gempilot::VersionTask.new
 
 task default: [:spec, :rubocop]

data/issues.rec

@@ -0,0 +1,169 @@
+%rec: Issue
+%key: Id
+%typedef: Status_t enum open in_progress closed
+%typedef: text_t regexp /.*/
+%type: Id uuid
+%type: Title line
+%type: Description text_t
+%type: Updated date
+%type: Status Status_t
+%auto: Id Updated
+
+Id: 710B6B1A-5EE5-4899-BB12-E41B44DAC090
+Updated: Tue, 17 Mar 2026 10:15:19 -0400
+Title: Add constant F that is set equal to Flexor
+Description: As Flexor is built to maximize ergonomics, it would be ideal to have a shorter way to call it. In lib, there should be f.rb, where F = Flexor as the only line. It could be called like:
++ puts F[json_string].people.first.first_name
++ 
+Status: closed
+
+Id: E4B0F842-0EFD-4FA9-9841-0984A905C67B
+Updated: Tue, 17 Mar 2026 12:45:02 -0400
+Title: Address rubocop offenses
+Description: Currently 30 violations as I write this
+Status: closed
+
+Id: 573035C3-BEDE-4C1F-9F88-3FBD4E870973
+Updated: Tue, 17 Mar 2026 14:40:13 -0400
+Title: Auto resolve fields against ones following a different style/casing
+Description: It would be useful to have the ability for flexor to auto-resolve or infer fields, like:
++ 1. key `fooBar` is on data, user types `foo_bar`. Flexor returns value of `fooBar`
++ 2. Vice-versa of 1
++ 
++ Note that the behavior would be optional/opt-in
+Status: closed
+
+Id: 115686E8-6961-4B6C-9B2F-EB4DABD8A900
+Updated: Tue, 17 Mar 2026 15:00:34 -0400
+Title: Using F "alias" requires "require 'f'", which is undesirable
+Description: The requirement of requiring 'f' for usage of "F" is undesirable as it pollutes global namespace, and is not intuitive for users that install flexor as the name of the gem. That alias should be loaded automatically when user does `require 'flexor'`.
+Status: closed
+
+Id: 19A6A0B1-D762-45D3-95E9-32545E230126
+Updated: Mon, 30 Mar 2026 12:00:29 -0400
+Title: Add plugin to "compile" keys into real methods
+Description: Currently Flexor when used with IRB lacks good autocompletion. It would be beneficial to precompile the keys into methods such that they can be completed. There are also potential performance benefits to doing this. ActiveSupport::Configurable does something similar:
+Status: open
+
+Id: 1FC0E609-B57F-45C3-9305-EB47601B259E
+Updated: Mon, 30 Mar 2026 12:01:05 -0400
+Title: ActiveSupport::Configurable example (tied to previous ticket):
+Description: 4 │ module ActiveSupport
++    5 │   # = Active Support \Configurable
++    6 │   # Configurable provides a <tt>config</tt> method to store and retrieve
++    7 │   # configuration options as an OrderedOptions.
++    8 │   module Configurable
++    9 │     extend ActiveSupport::Concern
++   10 │     class Configuration < ActiveSupport::InheritableOptions
++   11 │       def compile_methods\\\\\\\\\\\\!
++   12 │         self.class.compile_methods\\\\\\\\\\\\!(keys)
++   13 │       end
++   14 │       # Compiles reader methods so we don't have to go through method_missing.
++   15 │       def self.compile_methods\\\\\\\\\\\\!(keys)
++   16 │         keys.reject { |m| method_defined?(m) }.each do |key|
++   17 │           class_eval <<-RUBY, __FILE__, __LINE__ + 1
++   18 │             def #{key}; _get(#{key.inspect}); end
++   19 │           RUBY
++   20 │         end
++   21 │       end
++   22 │     end
+Status: open
+
+Id: 3B49DC55-C580-42C7-AB0D-08F0CB899B2D
+Updated: Sat, 11 Apr 2026 13:30:31 -0400
+Title: Create plugin to allow for the "?" method suffix
+Description: For example, when doing something like
++ ```ruby
++ object = Flexor[mandatory: true]
++ 
++ # CURRENT BEHAVIOR:
++ #
++ object.mandatory
++ # => true
++ #
++ object.mandatory?
++ # => nil
++ #
++ 
++ # DESIRED BEHAVIOR:
++ #
++ object.mandatory
++ # => true
++ #
++ object.mandatory?
++ # => true
++ #
++ ```
+Status: open
+
+Id: B0673B2E-A2A2-4FBE-BBF9-F41FA1CA3169
+Updated: Tue, 17 Mar 2026 10:15:19 -0400
+Title: Add constant F that is set equal to Flexor
+Description: As Flexor is built to maximize ergonomics, it would be ideal to have a shorter way to call it. In lib, there should be f.rb, where F = Flexor as the only line. It could be called like:
++ puts F[json_string].people.first.first_name
++ 
+Status: closed
+
+Id: 9938B05E-15F6-402B-AF42-7046D5B5F671
+Updated: Tue, 17 Mar 2026 12:45:02 -0400
+Title: Address rubocop offenses
+Description: Currently 30 violations as I write this
+Status: closed
+
+Id: 4BAD9D04-F360-4859-8454-B40CB80F0F85
+Updated: Tue, 17 Mar 2026 14:40:13 -0400
+Title: Auto resolve fields against ones following a different style/casing
+Description: It would be useful to have the ability for flexor to auto-resolve or infer fields, like:
++ 1. key `fooBar` is on data, user types `foo_bar`. Flexor returns value of `fooBar`
++ 2. Vice-versa of 1
++ 
++ Note that the behavior would be optional/opt-in
+Status: closed
+
+Id: B85383C2-5142-464F-81CF-7938445411E1
+Updated: Tue, 17 Mar 2026 15:00:34 -0400
+Title: Using F "alias" requires "require 'f'", which is undesirable
+Description: The requirement of requiring 'f' for usage of "F" is undesirable as it pollutes global namespace, and is not intuitive for users that install flexor as the name of the gem. That alias should be loaded automatically when user does `require 'flexor'`.
+Status: closed
+
+Id: 67833956-1397-4820-887B-60EE975CDF46
+Updated: Sat, 21 Mar 2026 22:38:19 -0400
+Title: Perform spike around IRB autocompletions
+Description: IRB autocompletions are incredibly useful, but flexor only exposes its own internal methods, rather than the fields for autocompletions. Some thoughts:
++ 1. Method caching is already (or was) built into flexor - if methods get defined, IRB can cache them
++ 2. Alternatively but more robustly, flexor could dynamically generate RBS types for the RBS type infer completor.
++ 3. Either which way, the plugin system allows us to isolate this behvior and only trigger it when IRB is active
+Status: open
+
+Id: 3ED3C15C-4051-11F1-9F71-FE6CB9572C2F
+Updated: Fri, 24 Apr 2026 22:48:31 -0400
+Title: Conflicting nil behavior between ||=, implicit nil, and ".nil?"
+Description: #Write a spec/test for the following example:
++ ```ruby
++ context 'when flexor has no key set' do
++   describe 'setting via ||=' do
++     it 'sets the attribute' do
++       f = Flexor.new
++       f[:foo] ||= :bar
++       expect(f.foo).to eq(:bar)
++     end
++   end
++ 
++   describe 'setting via implicit nil OR' do
++     it 'correctly sets the attribute' do
++       f = Flexor.new
++       f[:foo] || f[:foo] = :bar
++       expect(f.foo).to eq(:bar)
++     end
++   end
++ 
++   describe 'setting via nil? OR' do
++     it 'correctly sets the attribute' do
++       f = Flexor.new
++       f[:foo].nil? || f[:foo] = :bar
++       expect(f.foo).to eq(:bar)
++     end
++   end
++ end
++ ```
+Status: open

data/lib/f.rb

@@ -0,0 +1 @@
+F = Flexor

data/lib/flexor/case_conversion.rb

@@ -0,0 +1,43 @@
+class Flexor
+  ##
+  # Pure-function utilities for converting between camelCase and snake_case.
+  # Used by the FlexKeys plugin to compute alternate key forms.
+  module CaseConversion
+    CAMEL_BOUNDARY = /(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/
+    UNDERSCORE_SEGMENT = %r{(?:_|(/))([a-z\d]*)}
+
+    module_function
+
+    def camelize(term)
+      string = term.to_s.dup
+      return string if string.empty?
+
+      string.gsub!(UNDERSCORE_SEGMENT) do
+        "#{Regexp.last_match(1) && "::"}#{Regexp.last_match(2).capitalize}"
+      end
+      return string if string.empty?
+
+      string[0] = string[0].downcase
+      string
+    end
+
+    def underscore(camel_cased_word)
+      return camel_cased_word.to_s.dup unless /[A-Z-]/.match?(camel_cased_word)
+
+      word = camel_cased_word.to_s.dup
+      word.gsub!(CAMEL_BOUNDARY, "_")
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    def case_counterpart(key)
+      str = key.to_s
+      if str.include?("_")
+        camelize(str).to_sym
+      elsif str.match?(/[A-Z]/)
+        underscore(str).to_sym
+      end
+    end
+  end
+end

data/lib/flexor/hash_delegation.rb

@@ -25,6 +25,9 @@ class Flexor
     def key?(key)
       @store.key?(key)
     end
-    alias has_key? key?
+
+    def has_key?(key)
+      key?(key)
+    end
   end
 end

data/lib/flexor/method_dispatch.rb

@@ -0,0 +1,49 @@
+class Flexor
+  ##
+  # Handles dynamic getter/setter dispatch via method_missing and
+  # caches singleton methods for repeated access.
+  module MethodDispatch
+    def respond_to_missing?(_name, _include_private = false)
+      true
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      return super if block
+
+      case [name, args]
+      in /^[^=]+=$/, [arg] then write_via_method(name, arg)
+      in _, [] then read_via_method(name)
+      else super
+      end
+    end
+
+    def write_via_method(name, arg)
+      key = name.to_s.chomp("=").to_sym
+      cache_setter(name, key)
+      self[key] = arg
+    end
+
+    def read_via_method(name)
+      cache_getter(name) if !frozen? && @store.key?(name)
+      self[name]
+    end
+
+    def cache_setter(name, key)
+      define_singleton_method(name) do |val = nil, &blk|
+        raise NoMethodError, "undefined method '#{name}' for #{inspect}" if blk
+
+        self[key] = val
+      end
+    end
+
+    def cache_getter(name)
+      define_singleton_method(name) do |*a, &blk|
+        raise NoMethodError, "undefined method '#{name}' for #{inspect}" if blk || !a.empty?
+
+        self[name]
+      end
+    end
+  end
+end

data/lib/flexor/plugins/core.rb

@@ -0,0 +1,153 @@
+class Flexor
+  module Plugins
+    ##
+    # Core plugin providing all fundamental Flexor behavior.
+    # Bundles Vivification, HashDelegation, Serialization, and
+    # MethodDispatch along with every instance and class method
+    # that ships with a default Flexor install.
+    module Core
+      ##
+      # Instance methods for the core Flexor data store.
+      module StoreMethods
+        include Flexor::Vivification
+        include Flexor::HashDelegation
+        include Flexor::Serialization
+        include Flexor::MethodDispatch
+
+        def initialize(hash = {}, root: true)
+          raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+          @root  = root
+          @store = vivify(hash)
+        end
+
+        def initialize_copy(original)
+          super
+          @store = @store.dup
+        end
+
+        def [](key)
+          @store[key]
+        end
+
+        def []=(key, value)
+          @store[key] = vivify_value(value)
+        end
+
+        def set_raw(key, value)
+          @store[key] = value
+        end
+
+        def delete(key)
+          @store.delete(key)
+        end
+
+        def clear
+          @store.clear
+          self
+        end
+
+        def to_ary
+          nil
+        end
+
+        def freeze
+          @store.freeze
+          super
+        end
+
+        def to_h
+          @store.each_with_object({}) do |(key, value), hash|
+            result = recurse_to_h(value)
+            hash[key] = result unless value.is_a?(Flexor) && result.nil?
+          end
+        end
+
+        def to_json(...)
+          require "json"
+          to_h.to_json(...)
+        end
+
+        def to_s
+          return "" if nil?
+
+          @store.to_s
+        end
+
+        def inspect
+          return @store.inspect if @root
+          return nil.inspect if @store.empty?
+
+          @store.inspect
+        end
+
+        def deconstruct
+          @store.values
+        end
+
+        def deconstruct_keys(keys)
+          return @store if keys.nil?
+
+          @store.slice(*keys)
+        end
+
+        def nil?
+          @store.empty?
+        end
+
+        def merge!(other)
+          other = other.to_h if other.is_a?(Flexor)
+          other.each do |key, value|
+            if value.is_a?(Hash) && self[key].is_a?(Flexor) && !self[key].nil?
+              self[key].merge!(value)
+            else
+              self[key] = value
+            end
+          end
+          self
+        end
+
+        def merge(other)
+          dup.merge!(other)
+        end
+
+        def ==(other)
+          case other
+          in nil then nil?
+          in Flexor then to_h == other.to_h
+          in Hash then to_h == other
+          else super
+          end
+        end
+
+        def ===(other)
+          other.nil? ? nil? : super
+        end
+      end
+
+      ##
+      # Class-level methods for the core Flexor data store.
+      module ClassMethods
+        def [](input = {})
+          case input
+          when String then from_json(input)
+          when Hash then new(input)
+          else raise ArgumentError, "expected a String or Hash, got #{input.class}"
+          end
+        end
+
+        def from_json(json)
+          require "json"
+          JSON.parse(json, symbolize_names: true)
+              .then { new it }
+        end
+
+        def ===(other)
+          other.is_a?(self)
+        end
+      end
+
+      Flexor.register_plugin(:core, self)
+    end
+  end
+end

data/lib/flexor/plugins/flex_keys.rb

@@ -0,0 +1,61 @@
+class Flexor
+  module Plugins
+    ##
+    # CamelCase/snake_case key resolution plugin. Overrides key-accepting
+    # methods to check for an alternate-case match when the exact key is
+    # not found. Composes via +super+ with Core (or any plugin below it).
+    module FlexKeys
+      ##
+      # Instance methods that resolve symbol keys to their alternate-case
+      # counterpart before delegating to the underlying store.
+      module StoreMethods
+        def [](key)
+          super(resolve_flex_key(key))
+        end
+
+        def []=(key, value)
+          super(resolve_flex_key(key), value)
+        end
+
+        def set_raw(key, value)
+          super(resolve_flex_key(key), value)
+        end
+
+        def delete(key)
+          super(resolve_flex_key(key))
+        end
+
+        def key?(key)
+          super(resolve_flex_key(key))
+        end
+
+        def deconstruct_keys(keys)
+          return super if keys.nil?
+
+          keys.each_with_object({}) do |key, hash|
+            resolved = resolve_flex_key(key)
+            hash[key] = @store[resolved] if @store.key?(resolved)
+          end
+        end
+
+        private
+
+        def resolve_flex_key(key)
+          return key if @store.key?(key)
+          return key unless key.is_a?(Symbol)
+
+          alt = CaseConversion.case_counterpart(key)
+          alt && @store.key?(alt) ? alt : key
+        end
+
+        def read_via_method(name)
+          resolved = resolve_flex_key(name)
+          cache_getter(name) if !frozen? && @store.key?(resolved)
+          self[name]
+        end
+      end
+
+      Flexor.register_plugin(:flex_keys, self)
+    end
+  end
+end

data/lib/flexor/plugins/symbolize_keys.rb

@@ -0,0 +1,35 @@
+class Flexor
+  module Plugins
+    ##
+    # Normalizes string keys to symbols at ingestion and access time.
+    # Ensures that data arriving with string keys (from JSON, YAML, or
+    # plain Ruby hashes) is accessible via method and symbol-bracket
+    # access without manual conversion.
+    module SymbolizeKeys
+      ##
+      # Instance methods that convert string keys to symbols on
+      # ingestion (+vivify+, +[]=+) and read (+[]+).
+      module StoreMethods
+        def [](key)
+          super(symbolize_key(key))
+        end
+
+        def []=(key, value)
+          super(symbolize_key(key), value)
+        end
+
+        private
+
+        def symbolize_key(key)
+          key.is_a?(String) ? key.to_sym : key
+        end
+
+        def vivify(hash)
+          super(hash.transform_keys { |k| symbolize_key(k) })
+        end
+      end
+
+      Flexor.register_plugin(:symbolize_keys, self)
+    end
+  end
+end

data/lib/flexor/plugins.rb

@@ -0,0 +1,38 @@
+class Flexor
+  ##
+  # Namespace for Flexor plugins. Each plugin is a module containing
+  # optional +StoreMethods+ and +ClassMethods+ submodules.
+  module Plugins
+    ##
+    # Class-level methods for registering and loading plugins.
+    # Extended onto Flexor to provide +.plugin+ and +.register_plugin+.
+    module Dispatcher
+      def register_plugin(symbol, mod)
+        Flexor.plugin_registry[symbol] = mod
+      end
+
+      def plugin(mod, ...)
+        mod = resolve_plugin(mod)
+        mod.before_load(self, ...) if mod.respond_to?(:before_load)
+
+        include(mod::StoreMethods) if defined?(mod::StoreMethods)
+        extend(mod::ClassMethods)  if defined?(mod::ClassMethods)
+
+        mod.after_load(self, ...) if mod.respond_to?(:after_load)
+        nil
+      end
+
+      def plugin_registry
+        @plugin_registry ||= {}
+      end
+
+      private
+
+      def resolve_plugin(mod)
+        return mod unless mod.is_a?(Symbol)
+
+        Flexor.plugin_registry.fetch(mod)
+      end
+    end
+  end
+end

data/lib/flexor/version.rb

@@ -1,3 +1,3 @@
 class Flexor
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.2".freeze
 end

data/lib/flexor.rb

@@ -1,7 +1,10 @@
 require_relative "flexor/version"
+require_relative "flexor/plugins"
 require_relative "flexor/hash_delegation"
 require_relative "flexor/serialization"
 require_relative "flexor/vivification"
+require_relative "flexor/method_dispatch"
+require_relative "flexor/case_conversion"
 
 ##
 # A Hash-like data store with autovivifying nested access, nil-safe
@@ -10,178 +13,15 @@ require_relative "flexor/vivification"
 class Flexor
   class Error < StandardError; end
 
-  include HashDelegation
-  include Serialization
-  include Vivification
-
-  def self.[](input = {})
-    case input
-    when String then from_json(input)
-    when Hash then new(input)
-    else raise ArgumentError, "expected a String or Hash, got #{input.class}"
-    end
-  end
-
-  def self.from_json(json)
-    require "json"
-    JSON.parse(json, symbolize_names: true)
-        .then { new it }
-  end
-
-  def self.===(other)
-    other.is_a?(self)
-  end
-
-  def initialize(hash = {}, root: true)
-    raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
-
-    @root  = root
-    @store = vivify(hash)
-  end
-
-  def initialize_copy(original)
-    super
-    @store = @store.dup
-  end
-
-  def [](key)
-    @store[key]
-  end
-
-  def []=(key, value)
-    @store[key] = vivify_value(value)
-  end
-
-  def set_raw(key, value)
-    @store[key] = value
-  end
-
-  def delete(key)
-    @store.delete(key)
-  end
-
-  def clear
-    @store.clear
-    self
-  end
-
-  def to_ary
-    nil
-  end
-
-  def freeze
-    @store.freeze
-    super
-  end
-
-  def to_h
-    @store.each_with_object({}) do |(key, value), hash|
-      result = recurse_to_h(value)
-      hash[key] = result unless value.is_a?(Flexor) && result.nil?
-    end
-  end
-
-  def to_json(...)
-    require "json"
-    to_h.to_json(...)
-  end
-
-  def to_s
-    return "" if nil?
-
-    @store.to_s
-  end
-
-  def inspect
-    return @store.inspect if @root
-    return nil.inspect if @store.empty?
-
-    @store.inspect
-  end
-
-  def deconstruct
-    @store.values
-  end
-
-  def deconstruct_keys(keys)
-    return @store if keys.nil?
-
-    @store.slice(*keys)
-  end
-
-  def nil?
-    @store.empty?
-  end
-
-  def merge!(other)
-    other = other.to_h if other.is_a?(Flexor)
-    other.each do |key, value|
-      if value.is_a?(Hash) && self[key].is_a?(Flexor) && !self[key].nil?
-        self[key].merge!(value)
-      else
-        self[key] = value
-      end
-    end
-    self
-  end
-
-  def merge(other)
-    dup.merge!(other)
-  end
-
-  def ==(other)
-    case other
-    in nil then nil?
-    in Flexor then to_h == other.to_h
-    in Hash then to_h == other
-    else super
-    end
-  end
-
-  def ===(other)
-    other.nil? ? nil? : super
-  end
-
-  def respond_to_missing?(_name, _include_private = false)
-    true
-  end
-
-  private
-
-  def method_missing(name, *args, &block)
-    return super if block
-
-    case [name, args]
-    in /^[^=]+=$/, [arg] then write_via_method(name, arg)
-    in _, [] then read_via_method(name)
-    else super
-    end
-  end
-
-  def write_via_method(name, arg)
-    key = name.to_s.chomp("=").to_sym
-    cache_setter(name, key)
-    self[key] = arg
-  end
-
-  def read_via_method(name)
-    cache_getter(name) if !frozen? && @store.key?(name)
-    self[name]
-  end
-
-  def cache_setter(name, key)
-    define_singleton_method(name) do |val = nil, &blk|
-      raise NoMethodError, "undefined method '#{name}' for #{inspect}" if blk
+  extend Plugins::Dispatcher
+end
 
-      self[key] = val
-    end
-  end
+require_relative "flexor/plugins/core"
+require_relative "flexor/plugins/symbolize_keys"
+require_relative "flexor/plugins/flex_keys"
 
-  def cache_getter(name)
-    define_singleton_method(name) do |*a, &blk|
-      raise NoMethodError, "undefined method '#{name}' for #{inspect}" if blk || !a.empty?
+Flexor.plugin(:core)
+Flexor.plugin(:flex_keys)
+Flexor.plugin(:symbolize_keys)
 
-      self[name]
-    end
-  end
-end
+require_relative "f"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flexor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - David Gillis
@@ -21,6 +21,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -29,14 +30,21 @@ files:
 - docs/benchmark-results.md
 - docs/original_specification.yaml
 - docs/specification.yaml
+- issues.rec
+- lib/f.rb
 - lib/flexor.rb
+- lib/flexor/case_conversion.rb
 - lib/flexor/hash_delegation.rb
+- lib/flexor/method_dispatch.rb
+- lib/flexor/plugins.rb
+- lib/flexor/plugins/core.rb
+- lib/flexor/plugins/flex_keys.rb
+- lib/flexor/plugins/symbolize_keys.rb
 - lib/flexor/serialization.rb
 - lib/flexor/version.rb
 - lib/flexor/vivification.rb
 - rakelib/benchmark.rake
 - rakelib/rdoc.rake
-- rakelib/version.rake
 homepage: https://github.com/gillisd/flexor
 licenses:
 - MIT
@@ -58,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.9
 specification_version: 4
 summary: A Hash-like data store that does what you tell it to do
 test_files: []

data/rakelib/version.rake

@@ -1,72 +0,0 @@
-VERSION_PATTERN = /VERSION\s*=\s*"(\d+\.\d+\.\d+)"/
-
-# Encapsulates version file manipulation logic for rake tasks.
-module VersionBumper
-  module_function
-
-  def version_path
-    File.expand_path("../lib/flexor/version.rb", __dir__)
-  end
-
-  def print_current
-    require_relative "../lib/flexor/version"
-    puts "Current version: #{Flexor::VERSION}"
-  end
-
-  def bump
-    File.open(version_path, File::RDWR, 0o644) do |f|
-      f.flock(File::LOCK_EX)
-      old_version, new_version, new_source = compute_bump(f.read)
-      f.rewind
-      f.write(new_source)
-      f.truncate(f.pos)
-      puts "Version bumped from #{old_version} to #{new_version}"
-    end
-  end
-
-  def compute_bump(source)
-    match = source.match(VERSION_PATTERN)
-    abort "Could not find VERSION in #{version_path}" unless match
-
-    old_version = match[1]
-    parts = old_version.split(".").map(&:to_i)
-    parts[-1] += 1
-    new_version = parts.join(".")
-    new_source = source.sub(/VERSION\s*=\s*"#{Regexp.escape(old_version)}"/, "VERSION = \"#{new_version}\"")
-    [old_version, new_version, new_source]
-  end
-
-  def commit
-    require_relative "../lib/flexor/version"
-    system("git", "add", version_path) || abort("git add failed")
-    system("git", "commit", "-m", "Bump version to #{Flexor::VERSION}") || abort("git commit failed")
-    puts "Version change committed."
-  end
-
-  def revert
-    last_message = `git log -1 --pretty=%B`.strip
-    abort "Last commit does not appear to be a version bump." unless last_message.start_with?("Bump version to ")
-
-    system("git", "revert", "HEAD", "--no-edit") || abort("git revert failed")
-    puts "Version bump reverted."
-  end
-end
-
-namespace :version do
-  desc "Display the current version"
-  task(:current) { VersionBumper.print_current }
-
-  desc "Bump the patch version"
-  task(:bump) { VersionBumper.bump }
-
-  desc "Commit the version change"
-  task(:commit) { VersionBumper.commit }
-
-  desc "Revert the last version bump commit"
-  task(:revert) { VersionBumper.revert }
-end
-
-namespace :release do
-  desc "Bump version, commit, and release"
-  task full: ["version:bump", "version:commit", :release]
-end