plumb 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c32b91fda7581018e0febe58953ab0256b9850d9848cfe9ba468ef81d6003e3
-  data.tar.gz: 340f1681daffc709e724254a9ee031f1fd0bc12c2cdd80e53f47ce1384e5827c
+  metadata.gz: 6a6433ce0705844548d8c5488e0a454335eecb2dc385ded5e398dabbce66f8f6
+  data.tar.gz: aed47d0aef0f1a1a685ae9e4b164451484b9cd2aa4763f0cfd0293c5bb90ed99
 SHA512:
-  metadata.gz: e6e3c5d2bbaeeae28946cbaef50bf65edc9d98815d0546e8d62a69a0097dc889448e8edc68863f44ff922f5a808fbdb1266cc8fde6569bcde52c713c80856df7
-  data.tar.gz: ea269dc275559ccb3fb61c94311707881cc11151cbbb433daafb4040218748d33e5461b84be951d73bdc4b5c02ec5ef5622498ea0ac23efa77efcc110411670f
+  metadata.gz: b9a3ef7bb37d3239cca40a7a925bfad585b4490f02e6292310072a7d7d87361f0a39450cec257dbe7e1567234dd4cbc2c05610efbe245a219a2835cc8ecc1830
+  data.tar.gz: f3ea81577b79c024044615d7079acec13d40fc7db7435163301632d70d37dc24bedd23d6720a2d5781476b6b5c8ef308b1e7ee0b0739ded2b1e88953e5b68fb2

data/README.md

@@ -2031,14 +2031,16 @@ Composing a codec with a type rewrites the type deeply, in either direction:
 Person = Types::Hash[name: Types::String, dates: DateRange]
 
 JSONPerson = JSONCodec >> Person # decode: JSON structures -> Person
-JSONPerson.parse({ name: 'Joe', dates: { from: '2024-01-01', to: '2024-02-01' } })
+JSONPerson.parse({ 'name' => 'Joe', 'dates' => { 'from' => '2024-01-01', 'to' => '2024-02-01' } })
 # => { name: 'Joe', dates: Date(2024-01-01)..Date(2024-02-01) }
 
 EncodedPerson = Person >> JSONCodec # encode: Person -> JSON structures
 EncodedPerson.parse({ name: 'Joe', dates: Date.new(2024, 1, 1)..Date.new(2024, 2, 1) })
-# => { name: 'Joe', dates: { from: '2024-01-01', to: '2024-02-01' } }
+# => { 'name' => 'Joe', 'dates' => { 'from' => '2024-01-01', 'to' => '2024-02-01' } }
 ```
 
+Hash keys are rewritten like values: a Symbol key travels as whatever the codec encodes a Symbol to (a String, for both built-in codecs). Decoding reads `'name'` and emits `:name` — still accepting `:name` itself, with the wire key winning if both are present — and encoding emits `'name'`. `Types::Hash[Types::Symbol, V]` map keys rewrite the same way. A codec with no Symbol encoder leaves keys alone.
+
 `Codec.for(type)` returns both directions as a `[decoding, encoding]` pair:
 
 ```ruby
@@ -2154,10 +2156,10 @@ Config = Types::Hash[
 ]
 
 decoder, encoder = Plumb::Codec::Forms.for(Config)
-decoder.parse({ host: 'http://example.com', port: '80', active: '1', starts_on: '' })
+decoder.parse({ 'host' => 'http://example.com', 'port' => '80', 'active' => '1', 'starts_on' => '' })
 # => { host: URI(...), port: 80, active: true, starts_on: nil }
 encoder.parse({ host: URI.parse('http://example.com'), port: 80, active: true, starts_on: nil })
-# => { host: 'http://example.com', port: '80', active: 'true', starts_on: '' }
+# => { 'host' => 'http://example.com', 'port' => '80', 'active' => 'true', 'starts_on' => '' }
 ```
 
 `Codec::Forms` replaces the old one-way `Types::Forms` namespace. The input types are strict — actual integers or booleans are *not* accepted on decode, since form data is always strings; apply the codec at the boundary and write schemas in output types.

data/lib/plumb/attributes.rb

@@ -193,6 +193,13 @@ module Plumb
 
     def prepare_attributes(attrs) = attrs
 
+    # @see ._build_validated
+    def _assign_validated(attrs)
+      @errors = {}
+      @attributes = prepare_attributes(attrs)
+      freeze
+    end
+
     module ClassMethods
       def _set_pipeline(pl)
         @_pipeline = pl
@@ -249,6 +256,19 @@ module Plumb
 
       MUST_BE_HASH = ['Must be a Hash of attributes'].freeze
 
+      # An instance from attributes already validated against this struct's schema —
+      # a codec decoder's output — without validating again, which would re-run
+      # converting fields on converted values. Skips #initialize; #prepare_attributes
+      # still runs. Override it when building needs more. A struct with pipeline
+      # steps (see .step) is built by #new, as the steps expect.
+      # @param attrs [Hash] validated, and owned by the new instance
+      # @return [Plumb::Attributes]
+      def _build_validated(attrs)
+        return new(attrs) unless _pipeline.is_a?(AnyClass)
+
+        allocate.tap { |instance| instance.send(:_assign_validated, attrs) }
+      end
+
       # The Plumb::Callable interface
       # @param result [Plumb::Result]
       # @return [Plumb::Result]

data/lib/plumb/codec.rb

@@ -276,6 +276,7 @@ module Plumb
         @match_memo = {}.compare_by_identity
         @noop_memo = {}.compare_by_identity
         @bridge_memo = {}.compare_by_identity
+        @key_memo = {}
         @input_stack = []
         @root = nil
       end
@@ -428,8 +429,9 @@ module Plumb
 
       # A struct (Types::Data / Plumb::Attributes) is a Hash schema plus a
       # constructor. Decoding, the rewritten schema turns input fields into
-      # output values and the class itself builds the instance (Function's
-      # output stage CALLS it). Encoding, the class validates/constructs the
+      # output values and the step builds the instance from them without
+      # validating again (the output stage then passes the instance through).
+      # Encoding, the class validates/constructs the
       # instance, `#attributes` exposes the output values (shallow — nested
       # structs stay instances and are handled by their own rewritten nodes,
       # unlike the deep #to_h), and the encode-rewritten schema turns them
@@ -442,7 +444,13 @@ module Plumb
           # constructs by itself.
           return original if schema.equal?(struct._schema)
 
-          Function.new(schema, struct, Plumb::NOOP)
+          # The rewritten schema has validated and converted every field, so the
+          # instance is built without running the struct's own schema again.
+          build = lambda do |result|
+            instance = struct._build_validated(result.value)
+            instance.valid? ? result.valid(instance) : result.invalid(instance, errors: instance.errors.to_h)
+          end
+          Function.new(schema, struct, build, identity: [:struct_decode, struct])
         else
           # The lambda is fresh per call, so name what the step IS as its identity —
           # otherwise `(Person >> Codec) == (Person >> Codec)` is false while the
@@ -543,9 +551,31 @@ module Plumb
       def visit_hash(type, path)
         return noop_or_fail(type, path) if type._schema.empty? # the bare "any Hash" — a leaf
 
-        NodeMapper.map_record(type) do |field, key|
-          visit(field, path + [key.literal? ? key.to_s : key.inspect])
+        changed = false
+        schema = type._schema.each_with_object({}) do |(key, field), acc|
+          mapped = visit(field, path + [key.literal? ? key.to_s : key.inspect])
+          wkey = wire_key(key)
+          changed ||= !mapped.equal?(field) || !wkey.equal?(key)
+          acc[wkey] = mapped
         end
+        changed ? type.class.new(schema:) : type
+      end
+
+      # A Symbol key is a value like any other, so its wire name is what the codec
+      # encodes a Symbol to — fixed, so computed here. The key is ALIASED: decoding
+      # reads the wire name and emits the Symbol, encoding the reverse (see
+      # Key#aliased?). A codec with no Symbol encoder leaves keys alone.
+      def wire_key(key)
+        name = key.to_key
+        wire = wire_name(name) if key.literal? && name.is_a?(::Symbol)
+        return key if wire.nil? || wire == name
+
+        to, from = @direction == :decode ? [name, wire] : [wire, name]
+        Key.new(to, optional: key.optional?, from:)
+      end
+
+      def wire_name(sym)
+        @key_memo.fetch(sym) { @key_memo[sym] = encoder_for(Types::Symbol, BLANK_ARRAY)&.encode(sym) }
       end
 
       # DECODE rewrites the schema a filter FILTERS and rebuilds the filter around it,
@@ -574,20 +604,39 @@ module Plumb
         members.zip(type.children).all? { |v, m| v.equal?(m) } ? type : type.of(*members)
       end
 
-      # Keys are left untouched — key normalization (eg. string keys from the
-      # input) is a separate concern (see Types::SymbolizedHash / #symbolized).
       def visit_hash_map(type, path)
         key_type, value_type = type.children
+        k = visit_map_key(key_type, path)
         v = visit(value_type, path + ['{}'])
         # type.class (not HashMap) to preserve FilteredHashMap's leniency.
-        v.equal?(value_type) ? type : type.class.new(key_type, v)
+        k.equal?(key_type) && v.equal?(value_type) ? type : type.class.new(k, v)
+      end
+
+      # Keys rewrite like values, with two differences. A key type the codec
+      # can't rewrite stays as it is: maps were keyed by raw input before codecs
+      # rewrote keys at all. And decoding still accepts the decoded form, as
+      # an aliased literal key does (see #wire_key).
+      def visit_map_key(key_type, path)
+        k = visit(key_type, path + ['<key>'])
+        return k if k.equal?(key_type) || @direction == :encode
+
+        Disjunction.build(k, key_type)
+      rescue Plumb::TypeError
+        key_type
       end
 
       # A tagged union of Hash variants discriminated by a key: rewrite each
       # variant schema (all HashClasses); the tag key's literal value is a
       # native pass-through, so the discriminator survives.
       def visit_tagged_hash(type, path)
-        NodeMapper.map_children(type) { |variant| visit(variant, path) }
+        base = type.hash_type
+        # The bare Hash base is a leaf this codec may not cover; it rewrites to itself anyway.
+        base = visit(base, path) unless base._schema.empty?
+        variants = type.children.map { |variant| visit(variant, path) }
+        key = wire_key(type.key)
+        unchanged = base.equal?(type.hash_type) && key.equal?(type.key) &&
+                    variants.each_with_index.all? { |v, i| v.equal?(type.children[i]) }
+        unchanged ? type : type.class.new(base, key, variants)
       end
 
       # Rewriting can collapse two branches onto the SAME node — encoding a

data/lib/plumb/deferred.rb

@@ -10,6 +10,10 @@ module Plumb
       @lock = Mutex.new
       @definition = definition
       @cached_type = nil
+      # Separate from @lock: materializing the accepted type reaches back here while
+      # its own #type holds @lock.
+      @accepted_lock = Mutex.new
+      @accepted_type = nil
       # freeze
     end
 
@@ -22,6 +26,16 @@ module Plumb
       type.call(result)
     end
 
+    # What the materialized type accepts, as another Deferred, so a forward reference
+    # isn't resolved early. Memoized, so a self-reference in the body maps back to it
+    # and the recursion closes. Without it a Deferred accepts ITSELF, so a codec's
+    # recursive encode rewrite is checked against its own encoded form, and rejected.
+    def accepted_type
+      @accepted_lock.synchronize do
+        @accepted_type ||= Deferred.new(-> { Plumb::Subtyping.accepted_type(type) }).tap { |d| d.accepts_itself! }
+      end
+    end
+
     def type
       @lock.synchronize do
         @cached_type ||= @definition.call
@@ -35,5 +49,12 @@ module Plumb
         @cached_type
       end
     end
+
+    protected
+
+    # What an accepted type accepts is itself.
+    def accepts_itself!
+      @accepted_type = self
+    end
   end
 end

data/lib/plumb/disjunction.rb

@@ -23,14 +23,30 @@ module Plumb
 
     attr_reader :children
 
+    # Leaf branches under this node, counting through nested disjunctions:
+    # `a | b | c` is `(a | b) | c`, with 3.
+    attr_reader :branch_count
+
     # Identical for both nodes, which differ only in how types flow.
     def initialize(left, right)
       @left = Composable.wrap(left)
       @right = Composable.wrap(right)
       @children = [@left, @right].freeze
+      @branch_count = [@left, @right].sum { |c| c.is_a?(Disjunction) ? c.branch_count : 1 }
+      if @branch_count >= ClassDispatch::MIN_BRANCHES
+        @dispatch = ClassDispatch.new(self)
+        # Per instance, so a short union keeps the plain #call.
+        extend Dispatched
+      end
       freeze
     end
 
+    # #dup keeps ivars but not singleton modules (TypeRegistry dups types to rename them).
+    def initialize_copy(source)
+      super
+      extend Dispatched if @dispatch
+    end
+
     # (A | B).input_type == A.input_type | B.input_type — shared by both nodes.
     #
     # A Union cannot shortcut this to `self` the way it can #output_type, because a
@@ -52,6 +68,23 @@ module Plumb
       l.equal?(@left) && r.equal?(@right) ? self : Disjunction.build(l, r)
     end
 
+    # What either branch accepts. Not #input_type: that leaves a container branch as
+    # is, so `Array[Date] | Nil` composed with its encode rewrite checks an
+    # `Array[Date]` against the rewrite's String output, and rejects.
+    def accepted_type
+      l = branch_accepted(@left)
+      r = branch_accepted(@right)
+      l.equal?(@left) && r.equal?(@right) ? self : Disjunction.build(l, r)
+    end
+
+    # A branch whose input is unknown (a bare pattern matcher) opts out of the
+    # composition check, as it does on its own (see Subtyping.check_composable!).
+    private def branch_accepted(branch)
+      return Types::Any if Plumb::Subtyping.resolved_input(branch).is_a?(AnyClass)
+
+      Plumb::Subtyping.accepted_type(branch)
+    end
+
     # Rebuild around new branches, RECLASSIFYING by what they are.
     # @see Conjunction#with_children for why this must not preserve the class.
     def with_children(children) = Disjunction.build(children[0], children[1])
@@ -108,5 +141,88 @@ module Plumb
       right.is_a?(::Array) ? merged.concat(right) : merged.push(right)
       merged
     end
+
+    # #call for a union of ClassDispatch::MIN_BRANCHES or more. It first tries only the
+    # branches that could accept the value's class: same result, as the skipped ones
+    # would have failed. If those fail too, the plain #call runs to collect every
+    # branch's errors, as without dispatch.
+    module Dispatched
+      def call(result)
+        candidates = @dispatch.candidates(result.value.class)
+        return super unless candidates
+
+        original = result.value
+        i = 0
+        while i < candidates.size
+          r = candidates[i].call(i.zero? ? result : result.reset(original))
+          return r if r.valid?
+
+          i += 1
+        end
+        super(result.reset(original))
+      end
+    end
+
+    # Per input class, the leaf branches that could accept a value of that class, in
+    # order. A branch's classes are its Subtyping.stable_domain: known only when what it
+    # accepts and what it produces share base types, so a converting branch (a
+    # Function, a struct, a codec's rewrite) is always a candidate.
+    #
+    # Only Class domains are used, not Modules: an object can gain a module through
+    # #extend, which its #class doesn't show.
+    #
+    # Built lazily, on first use: resolving branch domains when the union is built would
+    # materialize `defer`red forward references.
+    class ClassDispatch
+      MIN_BRANCHES = 3
+      # Beyond this many distinct classes, candidates are recomputed instead of cached.
+      MAX_CLASSES = 64
+      # Cached for a class whose candidates are all the branches: nothing to skip.
+      ALL = :all
+
+      def initialize(node)
+        @node = node
+        @lock = Mutex.new
+        # Replaced, never mutated, so reads need no lock.
+        @table = {}.freeze
+        @branches = nil
+      end
+
+      # @param klass [Class] the input value's class
+      # @return [Array<Composable>, nil] candidate branches in order, or nil when none
+      #   can be skipped
+      def candidates(klass)
+        found = @table[klass] || store(klass, compute(klass))
+        found.equal?(ALL) ? nil : found
+      end
+
+      private
+
+      def compute(klass)
+        list = branches.filter_map { |branch, domain| branch if domain.nil? || domain.any? { |d| klass <= d } }
+        list.size == branches.size ? ALL : list.freeze
+      end
+
+      def store(klass, list)
+        @lock.synchronize { @table = @table.merge(klass => list).freeze if @table.size < MAX_CLASSES }
+        list
+      end
+
+      # [[branch, classes or nil], ...]
+      def branches
+        @branches || @lock.synchronize do
+          @branches ||= leaves(@node).map { |branch| [branch, domain(branch)] }.freeze
+        end
+      end
+
+      def leaves(node)
+        node.children.flat_map { |c| c.is_a?(Disjunction) ? leaves(c) : [c] }
+      end
+
+      def domain(branch)
+        classes = Plumb::Subtyping.stable_domain(branch)
+        classes if classes&.all? { |c| c.is_a?(::Class) }
+      end
+    end
   end
 end

data/lib/plumb/hash_class.rb

@@ -25,6 +25,8 @@ module Plumb
       # leftover input keys. `_schema` stays the source of truth for ==/subtyping.
       @literal_fields = @_schema.select { |k, _| k.literal? }
       @matcher_fields = @_schema.reject { |k, _| k.literal? }
+      # [from, to] names of aliased keys (see Key#aliased?), renamed by #unalias.
+      @aliases = @literal_fields.each_key.filter_map { |k| [k.from_key, k.to_key] if k.aliased? }.freeze
       # The `_` catch-all's value type, if present (there is at most one).
       @catch_all_type = @_schema.find { |k, _| k.catch_all? }&.last
       freeze
@@ -161,7 +163,7 @@ module Plumb
         return result.invalid!(errors: 'must be a Hash') unless result.value.is_a?(::Hash)
         return result unless _schema.any?
 
-        input = result.value
+        input = @aliases.empty? ? result.value : unalias(result.value)
         # Reuse the incoming cursor as the per-field scratch (see #call): `input`
         # is captured above and `result` is only flipped at the end, so fields
         # reset it in place with no scratch allocation.
@@ -208,7 +210,7 @@ module Plumb
       return result.invalid!(errors: NOT_A_HASH) unless result.value.is_a?(::Hash)
       return result unless _schema.any?
 
-      input = result.value
+      input = @aliases.empty? ? result.value : unalias(result.value)
       errors = nil # Do not allocate errors unless needed
       output = {}
 
@@ -270,7 +272,8 @@ module Plumb
       # a key's optionality are different types, so compare that too.
       _schema.all? do |key, value|
         other_key, other_value = other._schema.find { |k, _| k.eql?(key) }
-        other_key && key.optional? == other_key.optional? && value == other_value
+        other_key && key.optional? == other_key.optional? && key.from_key == other_key.from_key &&
+          value == other_value
       end
     end
 
@@ -300,7 +303,7 @@ module Plumb
     # type-check (the front-end/back-end coercion pattern).
     def accepted_type
       relaxed = _schema.each_with_object({}) do |(key, field), h|
-        h[key] = Plumb::Subtyping.accepted_type(field)
+        h[key.accepted] = Plumb::Subtyping.accepted_type(field)
       end
       self.class.new(schema: relaxed)
     end
@@ -407,12 +410,20 @@ module Plumb
     # catch-all) are already optional, so they pass through unchanged.
     def relaxed_to_optional
       relaxed = _schema.each_with_object({}) do |(key, type), h|
-        new_key = key.literal? ? Key.new(key.to_key, optional: true) : key
+        new_key = key.literal? ? key.with_optional(true) : key
         h[new_key] = type
       end
       self.class.new(schema: relaxed)
     end
 
+    # A copy of `input` with aliased keys under their own names. The alias wins
+    # when both are present; either way the key's own name is still accepted.
+    def unalias(input)
+      input = input.dup
+      @aliases.each { |from, to| input[to] = input.delete(from) if input.key?(from) }
+      input
+    end
+
     def _inspect
       %(Hash[#{_schema.map { |(k, v)| [k.inspect, v.inspect].join(': ') }.join(', ')}])
     end

data/lib/plumb/key.rb

@@ -22,9 +22,11 @@ module Plumb
       key.is_a?(Key) ? key : new(key, symbolize:)
     end
 
-    attr_reader :to_key, :to_sym, :node_name, :matcher
+    attr_reader :to_key, :to_sym, :node_name, :matcher, :from_key
 
-    def initialize(key, optional: false, symbolize: false)
+    # @param from [Symbol, String, nil] a literal key's INPUT name, when it differs
+    #   from the name it is emitted under (see #aliased?).
+    def initialize(key, optional: false, symbolize: false, from: nil)
       @node_name = :key
       if key.is_a?(::Symbol) || key.is_a?(::String)
         key_type = symbolize ? Symbol : key.class
@@ -35,6 +37,8 @@ module Plumb
         @optional = !match[:qmark].nil? ? true : optional
         @matcher = @to_key
         @literal = true
+        @from_key = from.nil? ? @to_key : from
+        @aliased = @from_key != @to_key
       else
         # A type/matcher key. It matches other keys structurally, so it has no
         # concrete #to_key and never imposes a required key.
@@ -43,6 +47,8 @@ module Plumb
         @to_sym = nil
         @optional = true
         @literal = false
+        @from_key = nil
+        @aliased = false
       end
       freeze
     end
@@ -50,6 +56,19 @@ module Plumb
     # A concrete Symbol/String key (exact lookup) vs a type/matcher key.
     def literal? = @literal
 
+    # Read from the input under a different name than it is emitted under — how a
+    # Codec maps a wire key (`'name'`) to a schema key (`:name`) and back. An aliased
+    # key still accepts its own name as a fallback.
+    def aliased? = @aliased
+
+    # This key as a consumer sees it: named by what it reads.
+    def accepted = aliased? ? Key.new(@from_key, optional: @optional) : self
+
+    # This key with a different optionality, keeping its alias.
+    def with_optional(optional)
+      optional == @optional ? self : Key.new(@to_key, optional:, from: @from_key)
+    end
+
     # The `_` catch-all: a matcher key over the Any top, so it matches every key.
     def catch_all? = !@literal && @matcher.is_a?(AnyClass)
 
@@ -82,7 +101,7 @@ module Plumb
 
     def inspect
       if @literal
-        "#{@to_key}#{'?' if @optional}"
+        "#{"#{@from_key.inspect}->" if aliased?}#{@to_key}#{'?' if @optional}"
       elsif catch_all?
         '_'
       else

data/lib/plumb/tagged_hash.rb

@@ -63,18 +63,21 @@ module Plumb
     def accepted_type
       relaxed = @children.map do |child|
         schema = child._schema.each_with_object({}) do |(k, field), h|
-          h[k] = k.eql?(@key) ? field : Plumb::Subtyping.accepted_type(field)
+          h[k.accepted] = k.eql?(@key) ? field : Plumb::Subtyping.accepted_type(field)
         end
         child.class.new(schema:)
       end
-      self.class.new(@hash_type, @key, relaxed)
+      self.class.new(Plumb::Subtyping.accepted_type(@hash_type), @key.accepted, relaxed)
     end
 
     def call(result)
       result = @hash_type.call(result)
       return result unless result.valid?
 
-      child = @index[result.value[@key.to_sym]]
+      input = result.value
+      # An aliased key (a codec's wire name) falls back to its own name.
+      tag_key = @key.aliased? && input.key?(@key.from_key) ? @key.from_key : @key.to_sym
+      child = @index[input[tag_key]]
       return result.invalid!(errors: "expected :#{@key.to_sym} to be one of #{@index.keys.join(', ')}") unless child
 
       child.call(result)

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Ismael Celis