plumb 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26a0c552d1280339792c3acf480302056f203a6ac3a1a19a548d977b72bb581f
-  data.tar.gz: 325d6d8e267e107c6a2a7c28dddf696ed8198595fe0bc13af76b53648531dd1a
+  metadata.gz: 6a6433ce0705844548d8c5488e0a454335eecb2dc385ded5e398dabbce66f8f6
+  data.tar.gz: aed47d0aef0f1a1a685ae9e4b164451484b9cd2aa4763f0cfd0293c5bb90ed99
 SHA512:
-  metadata.gz: aff0c3be749f252774c753074d87fe1b6f169a0ef3f118013b54100a3d0482283745b664f90a39c44b9af664dbd5d0d9cda9f63b86867236e178642bb026933d
-  data.tar.gz: 6e8383986cf0bd2ee8e429adb13dd0440bf634536c3db745910fab84a6aac67b7130a6e90e59edca539cc9f22b661937c2c9feb9fa9f854467c086731189b37b
+  metadata.gz: b9a3ef7bb37d3239cca40a7a925bfad585b4490f02e6292310072a7d7d87361f0a39450cec257dbe7e1567234dd4cbc2c05610efbe245a219a2835cc8ecc1830
+  data.tar.gz: f3ea81577b79c024044615d7079acec13d40fc7db7435163301632d70d37dc24bedd23d6720a2d5781476b6b5c8ef308b1e7ee0b0739ded2b1e88953e5b68fb2

data/README.md

@@ -96,7 +96,7 @@ StringToInt.parse('100lol') # fails
 
 ### `#resolve(value) => Result`
 
-`#resolve` takes an input value and returns a `Result::Valid` or `Result::Invalid`
+`#resolve` takes an input value and returns a `Plumb::Result`, which is either valid or invalid (check with `#valid?` / `#invalid?`).
 
 ```ruby
 result = Types::Integer.resolve(10)
@@ -846,14 +846,14 @@ Example: parsing strings with `Date.parse` and turning `Date::Error` exceptions
 ```ruby
 # Accept a string that can be parsed into a Date
 # via Date.parse
-# If Date.parse raises a Date::Error, return a Result::Invalid with
+# If Date.parse raises a Date::Error, return an invalid Result with
 # the exception's message as error message.
 type = Types::String
 	.build(::Date, :parse)
 	.policy(:rescue, ::Date::Error)
 
-type.resolve('2024-02-02') # => Result::Valid with Date object
-type.resolve('2024-') # => Result::Invalid with error message
+type.resolve('2024-02-02') # => valid Result with Date object
+type.resolve('2024-') # => invalid Result with error message
 ```
 
 The guard keeps the type it wraps: the example above is still a `Date` for subtyping,
@@ -1216,9 +1216,9 @@ Plumb::JSONSchemaVisitor.call(Types::Range[0...100], root: false)
 
 ## `Types::SymbolizedHash`
 
-This type turns a hash's keys into symbols by calling `#to_sym` on them, and returning a new Hash.
+This type recursively turns a hash's String keys into symbols, returning a new Hash. Symbol keys and any other keys pass through unchanged, so it accepts any Hash.
 
-`SymbolizedHash` is a `Symbol => Any` map. You can use it as a _transform_.
+You can use it as a _transform_.
 
 ```ruby
 UserHash = Types::Hash[name: String]
@@ -1233,6 +1233,13 @@ type = Types::Hash[name: String, age: Integer].symbolized
 type.parse('name' => 'Joe', 'age' => 20) # {name: 'Joe', age: 20}
 ```
 
+Hash maps support `#symbolized` too. It raises `Plumb::TypeError` if the map's key type can't accept Symbols, since every symbolized key would be rejected.
+
+```ruby
+Types::Hash[Symbol, Integer].symbolized.parse('a' => 1) # {a: 1}
+Types::Hash[String, Integer].symbolized # raises Plumb::TypeError
+```
+
 ##  maps
 
 You can also use Hash syntax to define a hash map with specific types for all keys and values:
@@ -1361,7 +1368,7 @@ TODO: pluggable concurrency engines (Async?)
 
 ### `#stream`
 
-Turn an Array definition into an enumerator that yields each element wrapped in `Result::Valid` or `Result::Invalid`.
+Turn an Array definition into an enumerator that yields each element wrapped in a valid or invalid `Result`.
 
 See [`Types::Stream`](#typesstream) below for more.
 
@@ -1421,7 +1428,7 @@ Row = Types::Tuple[Types::String.present, Types:Lax::Integer]
 Stream = Types::Stream[Row]
 
 data = CSV.new(File.new('./big-file.csv')).each # An Enumerator
-# stream is an Enumerator that yields rows wrapped in[Result::Valid] or [Result::Invalid]
+# stream is an Enumerator that yields rows wrapped in a valid or invalid Result
 stream = Stream.parse(data)
 stream.each.with_index(1) do |result, line|
   if result.valid?
@@ -1816,7 +1823,7 @@ CreateIfJoe = IsJoe >> CreateUser
 Use `#around` in a pipeline definition to add a middleware step that wraps all other steps registered.
 
 ```ruby
-# The #around interface is #call(Step, Result::Valid) => Result::Valid | Result::Invalid
+# The #around interface is #call(Step, Result) => Result
 StepLogger = proc do |step, result|
   Logger.info "Processing step #{step}"
   step.call(result)
@@ -2024,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
@@ -2147,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.
@@ -2170,12 +2179,14 @@ Things to know:
 Every Plumb type exposes the following one-method interface:
 
 ```
-#call(Result::Valid) => Result::Valid | Result::Invalid
+#call(Result) => Result
 ```
 
+The incoming result is always valid (invalid results halt a pipeline before reaching later steps). Return a valid result to pass a value on, or an invalid one to halt.
+
 As long as an object implements this interface, it can be composed into Plumb workflows.
 
-The `Result::Valid` class has helper methods `#valid(value) => Result::Valid` and `#invalid(errors:) => Result::Invalid` to facilitate returning valid or invalid values from your own steps.
+`Plumb::Result` has helper methods `#valid(value) => Result` and `#invalid(value, errors:) => Result` to facilitate returning valid or invalid results from your own steps. Both return a new `Result` and leave the receiver untouched.
 
 ### Compose procs or lambdas directly
 
@@ -2243,7 +2254,7 @@ LoudGreeting = Greeting.default('no greeting').invoke(:upcase)
 
 ### A custom `#call` class
 
-Or write a custom class that responds to `#call(Result::Valid) => Result::Valid | Result::Invalid`
+Or write a custom class that responds to `#call(Result) => Result`
 
 ```ruby
 class Greeting
@@ -2252,8 +2263,8 @@ class Greeting
   end
 
   # The Plumb step interface
-  # @param result [Plumb::Result::Valid]
-  # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
+  # @param result [Plumb::Result] a valid result
+  # @return [Plumb::Result]
   def call(result)
     result.valid("#{@gr} #{result.value}")
   end

data/lib/plumb/and.rb

@@ -29,11 +29,20 @@ module Plumb
       #
       # Conjunction.build, not Intersection.new — `left.output_type` need not preserve
       # values (a record drops undeclared keys, a Static replaces it), and only the
-      # classifier may decide. The `lo.equal?(left)` guard is the fixpoint: a left that
-      # IS its own output type would otherwise recurse forever.
+      # classifier may decide.
+      #
+      # A left that IS its own output type (eg. a recursive type) can't be met without
+      # recursing forever, so fall back to the right alone: every output passed it
+      # unchanged, so it's a sound over-approximation. Unless the right is the Any top,
+      # which would opt the chain out of #>> checks; then stay opaque (self).
       @output_type = if Plumb::Subtyping.value_preserving?(right)
                        lo = left.output_type
-                       lo.equal?(left) ? self : Conjunction.build(lo, right)
+                       if lo.equal?(left)
+                         ro = right.output_type
+                         ro.is_a?(AnyClass) ? self : ro
+                       else
+                         Conjunction.build(lo, right)
+                       end
                      else
                        right.output_type
                      end

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/hash_map.rb

@@ -35,6 +35,15 @@ module Plumb
       super
     end
 
+    # A map whose key and value types both admit Any is the "any Hash" type, so it
+    # claims anything whose base types are all Hashes (eg. `transform(::Hash)`).
+    def supertype_of?(other)
+      return false unless children.all? { |c| Plumb::Subtyping.subtype?(Types::Any, c) }
+
+      bases = Plumb.resolve_base_types(other)
+      bases.any? && bases.all? { |k| k.is_a?(::Class) && k <= ::Hash }
+    end
+
     # A HashMap re-maps each key and value through its key/value types, so it
     # preserves the value only when both do (a coercing key or value would change
     # the hash).
@@ -74,6 +83,19 @@ module Plumb
       FilteredHashMap.new(@key_type, @value_type)
     end
 
+    # Symbolize keys (via Types::SymbolizedHash), then validate against this map.
+    # Only the key type is checked up front: a map whose keys can't be Symbols
+    # (eg. `Hash[String, X]`) would reject every symbolized key.
+    # @see HashClass#symbolized
+    # @raise [Plumb::TypeError] when the key type doesn't accept Symbols.
+    def symbolized
+      unless Plumb::Subtyping.subtype?(Types::Symbol, Plumb::Subtyping.accepted_type(@key_type))
+        raise Plumb::TypeError, "cannot symbolize #{inspect}: its key type doesn't accept Symbols"
+      end
+
+      Types::SymbolizedHash / self
+    end
+
     private def _inspect = "HashMap[#{@key_type.inspect}, #{@value_type.inspect}]"
 
     # Same key/value types as a HashMap (so it inherits #initialize, #children

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/subtyping.rb

@@ -72,8 +72,7 @@ module Plumb
       ub = unwrap_transparent(b)
       return subtype?(ua, ub) unless ua.equal?(a) && ub.equal?(b)
 
-      return true if b.is_a?(AnyClass)  # X <= Top
-      return false if a.is_a?(AnyClass) # Top <= X only when X is Top (handled above)
+      return true if b.is_a?(AnyClass) # X <= Top
 
       # A value-converting type (Function, or any custom type that opts in) is
       # identified for subtyping by what it *produces*, not what it consumes, so we
@@ -108,6 +107,10 @@ module Plumb
       return b.children.all? { |bb| subtype?(a, bb) } if b.is_a?(Intersection) # a <= (b1 ∧ b2)
       return a.children.any? { |aa| subtype?(aa, b) } if a.is_a?(Intersection) # (a1 ∧ a2) <= b
 
+      # Top <= X only when X is Top-equivalent. Checked after the join/meet rules
+      # so a union with a Top branch (`X | Any`) still admits Top.
+      return false if a.is_a?(AnyClass)
+
       # `a` decides via its #subtype_of? leaf; if it can't (it doesn't know about
       # `b`), `b` may claim `a` via #supertype_of? — the mirror hook for
       # supertype-driven relations like Interface duck-typing.

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/types.rb

@@ -196,8 +196,8 @@ module Plumb
     # @example Mixed types preserved
     #   SymbolizedHash.parse({ 'count' => 1, 'active' => true })  # => { count: 1, active: true }
     SymbolizedHash = Hash[
-      # String keys are converted to symbols, existing symbols are preserved
-      (Symbol | String.transform(::Symbol, :to_sym)),
+      # String keys are converted to symbols; any other key passes through unchanged
+      (Symbol | String.transform(::Symbol, :to_sym) | Any),
       # Hash values are recursively symbolized, other types pass through unchanged
       Any.defer { SymbolizedHash } | Any
     ]

data/lib/plumb/version.rb

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

metadata

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