plumb 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 104313a59a2f9187f582058b8f0f3c6dce43763079518d68fde511aef6112400
-  data.tar.gz: 4fc765c09d840145ebf5777cfd4e326f3705db5cfda8ee5324c5f6f4f81e0070
+  metadata.gz: 13814b82e58449726341c0a26a398fee38818f852fe09f19ba7754a99b7c54ce
+  data.tar.gz: 2205b2bc5f48b19b417afe8403cdbd7afbcac3689307b6ba69237ad094718815
 SHA512:
-  metadata.gz: 2ca83f0ed1b4fbb2a83e11ff05bded28ed99550de9bfbec2d20d79943d886209c6b4cabeb2055857e24e60748642f0f7b541dcf5dc433107073772b085c5025a
-  data.tar.gz: 9d7b79dc0509f481730331bd3e65a1b85378d3609279b6c575ec8d77d8e786ccbe33b8dd54b0abfa826df06454793b235c1f8086a581c9a143359899cebb0318
+  metadata.gz: 604b2d74cf5a78578471d5e6cf523f956025ea95c2e9b17dec7337cca41de10dc2254bc66b69ea2255ee18059b885ef6bb5bd64ea32a34a763cf095168c80022
+  data.tar.gz: 50e065d933d9c3a00ff04a0e3e2375997d43039fc8d5c3ba6c7c1a6dc9455bda9d056bfefb11e81b4c75f0a26c01919d7f18c5b0da6aefa33c1f668ddabbaa29

data/.rubocop.yml

@@ -1,5 +1,11 @@
 AllCops:
-  TargetRubyVersion: 3.2.2
+  TargetRubyVersion: 3.4
+inherit_from:
+  - ~/.rubocop.yml
+Style/StringLiterals:
+  Enabled: true
+Style/Documentation:
+  Enabled: false
 Style/CaseEquality:
   Enabled: false
 Style/LambdaCall:

data/README.md

@@ -2,9 +2,9 @@
 
 **This library is work in progress!**
 
-Composable data validation, coercion and processing in Ruby. Takes over from https://github.com/ismasan/parametric
+Composable data validation, coercion and processing in Ruby. Takes over from [https://github.com/ismasan/parametric](https://github.com/ismasan/parametric)
 
-This library takes ideas from the excellent https://dry-rb.org ecosystem, with some of the features offered by Dry-Types, Dry-Schema, Dry-Struct. However, I'm aiming at a subset of the functionality with a (hopefully) smaller API surface and fewer concepts, focusing on lessons learned after using Parametric in production for many years.
+This library takes ideas from the excellent [https://dry-rb.org](https://dry-rb.org) ecosystem, with some of the features offered by Dry-Types, Dry-Schema, Dry-Struct. However, I'm aiming at a subset of the functionality with a (hopefully) smaller API surface and fewer concepts, focusing on lessons learned after using Parametric in production for many years.
 
 If you're after raw performance and versatility I strongly recommend you use the Dry gems.
 
@@ -135,7 +135,7 @@ joe = User.parse({ name: 'Joe', email: 'joe@email.com', age: 20}) # returns vali
 Users.parse([joe]) # returns valid array of user hashes
 ```
 
-More about [Types::Hash](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps), [data structs](#typesdata) and [streams](#typesstream), and it's possible to create your own composite types.
+More about [Types::Hash](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#maps), [data structs](#typesdata) and [streams](#typesstream), and it's possible to create your own composite types.
 
 ### Type composition
 
@@ -329,26 +329,26 @@ type.resolve(['a', 'a', 'b']) # Valid
 type.resolve(['a', 'x', 'b']) # Failure
 ```
 
-### `#with`
+### `#where`
 
-The `#with` helper matches attributes of the object with values, using `#===`.
+The `#where` helper matches attributes of the object with values, using `#===`.
 
 ```ruby
-LimitedArray = Types::Array[String].with(size: 10)
-LimitedString = Types::String.with(size: 10)
-LimitedSet = Types::Any[Set].with(size: 10)
+LimitedArray = Types::Array[String].where(size: 10)
+LimitedString = Types::String.where(size: 10)
+LimitedSet = Types::Any[Set].where(size: 10)
 ```
 
 The size is matched via `#===`, so ranges also work.
 
 ```ruby
-Password = Types::String.with(bytesize: 10..20)
+Password = Types::String.where(bytesize: 10..20)
 ```
 
 The helper accepts multiple attribute/value pairs
 
 ```ruby
-JoeBloggs = Types::Any[User].with(first_name: 'Joe', last_name: 'Bloggs')
+JoeBloggs = Types::Any[User].where(first_name: 'Joe', last_name: 'Bloggs')
 ```
 
 #### `#transform`
@@ -1039,7 +1039,7 @@ end
 
 ### Types::Data
 
-`Types::Data` provides a superclass to define **inmutable** structs or value objects with typed / coercible attributes.
+`Types::Data` provides a superclass to define **immutable** structs or value objects with typed / coercible attributes.
 
 #### `[]` Syntax
 
@@ -1816,3 +1816,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/ismasa
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Created by [Ismael Celis](https://ismaelcelis.com)

data/Rakefile

@@ -2,6 +2,8 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'docco/tasks'
+
 
 RSpec::Core::RakeTask.new(:spec)
 

data/docs/styles.css

@@ -0,0 +1,540 @@
+/* Reset and Base Styles */
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+:root {
+    --primary-color: #2563eb;
+    --primary-dark: #1e40af;
+    --secondary-color: #64748b;
+    --bg-color: #f8fafc;
+    --sidebar-bg: #1e293b;
+    --sidebar-text: #cbd5e1;
+    --sidebar-hover: #334155;
+    --content-bg: #ffffff;
+    --text-color: #1e293b;
+    --text-light: #64748b;
+    --border-color: #e2e8f0;
+    --code-bg: #f1f5f9;
+    --code-border: #cbd5e1;
+    --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+}
+
+html {
+    scroll-behavior: smooth;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+    line-height: 1.6;
+    color: var(--text-color);
+    background-color: var(--bg-color);
+    padding-top: 60px;
+}
+
+/* Top Menu Bar */
+.top-menu {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 60px;
+    background-color: var(--content-bg);
+    border-bottom: 1px solid var(--border-color);
+    box-shadow: var(--shadow);
+    z-index: 1000;
+}
+
+.top-menu-content {
+    max-width: 100%;
+    height: 100%;
+    padding: 0 2rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+
+.top-menu-brand {
+    display: flex;
+    align-items: baseline;
+    gap: 0.75rem;
+}
+
+.brand-name {
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--text-color);
+}
+
+.brand-tagline {
+    font-size: 0.875rem;
+    color: var(--text-light);
+    font-weight: 400;
+}
+
+.top-menu .github-link {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 1rem;
+    background-color: var(--text-color);
+    color: #ffffff;
+    border-radius: 6px;
+    text-decoration: none;
+    font-weight: 600;
+    font-size: 0.875rem;
+    transition: all 0.2s ease;
+}
+
+.top-menu .github-link:hover {
+    background-color: #000000;
+    text-decoration: none;
+}
+
+.top-menu .github-link svg {
+    width: 20px;
+    height: 20px;
+}
+
+/* Layout */
+.container {
+    display: flex;
+    min-height: calc(100vh - 60px);
+}
+
+/* Sidebar */
+.sidebar {
+    width: 280px;
+    background-color: var(--sidebar-bg);
+    color: var(--sidebar-text);
+    padding: 2rem 0;
+    position: fixed;
+    top: 60px;
+    height: calc(100vh - 60px);
+    overflow-y: auto;
+    box-shadow: var(--shadow-lg);
+}
+
+.sidebar::-webkit-scrollbar {
+    width: 8px;
+}
+
+.sidebar::-webkit-scrollbar-track {
+    background: var(--sidebar-bg);
+}
+
+.sidebar::-webkit-scrollbar-thumb {
+    background: var(--sidebar-hover);
+    border-radius: 4px;
+}
+
+.logo {
+    padding: 0 1.5rem 1.5rem;
+    border-bottom: 1px solid var(--sidebar-hover);
+    margin-bottom: 1.5rem;
+}
+
+.logo h2 {
+    font-size: 1.75rem;
+    color: #ffffff;
+    margin-bottom: 0.25rem;
+    font-weight: 700;
+}
+
+.logo .tagline {
+    font-size: 0.875rem;
+    color: var(--sidebar-text);
+    font-weight: 400;
+}
+
+.nav-menu {
+    list-style: none;
+    padding-left: 0;
+}
+
+.nav-menu li {
+    margin: 0;
+}
+
+.nav-menu a {
+    display: block;
+    padding: 0.625rem 1.5rem;
+    color: var(--sidebar-text);
+    text-decoration: none;
+    transition: all 0.2s ease;
+    font-size: 0.9375rem;
+}
+
+.nav-menu li:not(.nav-submenu) > a {
+    font-weight: 600;
+    margin-top: 0.5rem;
+}
+
+.nav-submenu a {
+    padding-left: 2.5rem;
+    font-size: 0.875rem;
+    color: var(--sidebar-text);
+    opacity: 0.9;
+}
+
+.nav-menu a:hover {
+    background-color: var(--sidebar-hover);
+    color: #ffffff;
+}
+
+.nav-menu a.active {
+    background-color: var(--primary-color);
+    color: #ffffff;
+    border-left: 3px solid #ffffff;
+    padding-left: calc(1.5rem - 3px);
+}
+
+.nav-submenu a.active {
+    padding-left: calc(2.5rem - 3px);
+}
+
+/* Accordion Menus */
+.nav-accordion {
+    position: relative;
+}
+
+.accordion-toggle {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    cursor: pointer;
+}
+
+.accordion-icon {
+    font-size: 0.75rem;
+    transition: transform 0.2s ease;
+    margin-left: 0.5rem;
+}
+
+.nav-accordion.expanded .accordion-icon {
+    transform: rotate(-180deg);
+}
+
+.accordion-content {
+    list-style: none;
+    padding-left: 0;
+    max-height: 0;
+    overflow: hidden;
+    transition: max-height 0.3s ease;
+}
+
+.nav-accordion.expanded .accordion-content {
+    max-height: 500px;
+}
+
+.nav-h4 a {
+    padding-left: 3.5rem;
+    font-size: 0.8125rem;
+    color: var(--sidebar-text);
+    opacity: 0.85;
+}
+
+.nav-h4 a.active {
+    padding-left: calc(3.5rem - 3px);
+}
+
+/* Main Content */
+.content {
+    flex: 1;
+    margin-left: 280px;
+    padding: 3rem;
+    max-width: 1200px;
+    width: 79vw;
+}
+
+/* Page Header */
+.page-header {
+    margin-bottom: 3rem;
+    padding-bottom: 2rem;
+    border-bottom: 2px solid var(--border-color);
+}
+
+.page-header h1 {
+    font-size: 3rem;
+    font-weight: 800;
+    color: var(--text-color);
+    margin-bottom: 0.5rem;
+    letter-spacing: -0.025em;
+}
+
+.page-header .subtitle {
+    font-size: 1.25rem;
+    color: var(--text-light);
+    font-weight: 400;
+}
+
+/* Sections */
+.section {
+    margin-bottom: 4rem;
+}
+
+.section h2 {
+    font-size: 2rem;
+    font-weight: 700;
+    color: var(--text-color);
+    margin-bottom: 1.5rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 2px solid var(--primary-color);
+}
+
+.subsection {
+    margin-bottom: 2.5rem;
+    background-color: var(--content-bg);
+    padding: 2rem;
+    border-radius: 8px;
+    box-shadow: var(--shadow);
+}
+
+.subsection h3 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    color: var(--text-color);
+    margin-bottom: 1rem;
+}
+
+.subsection h4 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--text-color);
+    margin: 1.5rem 0 1rem;
+}
+
+/* Typography */
+p {
+    margin-bottom: 1rem;
+    line-height: 1.75;
+}
+
+a {
+    color: var(--primary-color);
+    text-decoration: none;
+}
+
+a:hover {
+    color: var(--primary-dark);
+    text-decoration: underline;
+}
+
+strong {
+    font-weight: 600;
+    color: var(--text-color);
+}
+
+/* Lists */
+ul, ol {
+    margin-bottom: 1rem;
+    padding-left: 1.5rem;
+}
+
+li {
+    margin-bottom: 0.5rem;
+}
+
+.feature-list {
+    list-style: none;
+    padding-left: 0;
+}
+
+.feature-list li {
+    padding-left: 1.5rem;
+    position: relative;
+    margin-bottom: 0.75rem;
+}
+
+.feature-list li::before {
+    content: "→";
+    position: absolute;
+    left: 0;
+    color: var(--primary-color);
+    font-weight: bold;
+}
+
+/* Code Blocks */
+code {
+    font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+    font-size: 0.875em;
+    background-color: var(--code-bg);
+    padding: 0.2em 0.4em;
+    border-radius: 3px;
+    border: 1px solid var(--code-border);
+}
+
+pre {
+    margin: 1.5rem 0;
+    padding: 0;
+    overflow-x: auto;
+    border-radius: 6px;
+    box-shadow: var(--shadow);
+    background-color: #282c34;
+}
+
+pre code {
+    display: block;
+    padding: 1.25rem;
+    background-color: transparent;
+    color: inherit;
+    border: none;
+    border-radius: 6px;
+    line-height: 1.6;
+    overflow-x: auto;
+}
+
+pre code::-webkit-scrollbar {
+    height: 8px;
+}
+
+pre code::-webkit-scrollbar-track {
+    background: var(--sidebar-hover);
+    border-radius: 4px;
+}
+
+pre code::-webkit-scrollbar-thumb {
+    background: var(--sidebar-text);
+    border-radius: 4px;
+}
+
+/* Images */
+.image-container {
+    margin: 2rem 0;
+    text-align: center;
+}
+
+.image-container img {
+    max-width: 100%;
+    height: auto;
+}
+
+.image-container .caption {
+    margin-top: 0.75rem;
+    font-size: 0.875rem;
+    color: var(--text-light);
+    font-style: italic;
+}
+
+@media (max-width: 1248px) {
+  .content p img {
+    width: 64vw;
+    height: auto;
+  }
+}
+
+/* Responsive Design */
+@media (max-width: 1024px) {
+    .sidebar {
+        width: 240px;
+    }
+
+    .content {
+      width: 76vw;
+        margin-left: 240px;
+        padding: 2rem;
+    }
+}
+
+@media (max-width: 768px) {
+    /* Stack sidebar and content vertically on handhelds */
+    .container {
+        flex-direction: column;
+    }
+    .top-menu-content {
+        padding: 0 1rem;
+    }
+
+    .brand-tagline {
+        display: none;
+    }
+
+    .top-menu .github-link span {
+        display: none;
+    }
+
+    .top-menu .github-link {
+        padding: 0.5rem;
+    }
+
+    .sidebar {
+      display:none;
+    }
+
+    .content {
+        margin-left: 0;
+        width: 100vw;
+        padding: 1.5rem;
+    }
+
+    .content p img {
+      width: 78vw;
+      height: auto;
+    }
+    .page-header h1 {
+        font-size: 2rem;
+    }
+
+    .page-header .subtitle {
+        font-size: 1rem;
+    }
+
+    .section h2 {
+        font-size: 1.5rem;
+    }
+
+    .subsection {
+        padding: 1.5rem;
+    }
+
+    .subsection h3 {
+        font-size: 1.25rem;
+    }
+
+    pre code {
+        padding: 1rem;
+        font-size: 0.8125rem;
+    }
+}
+
+/* Smooth Scrolling and Anchor Offset */
+section {
+    scroll-margin-top: 5rem;
+}
+
+article {
+    scroll-margin-top: 5rem;
+}
+
+/* Print Styles */
+@media print {
+    .top-menu {
+        display: none;
+    }
+
+    body {
+        padding-top: 0;
+    }
+
+    .sidebar {
+        display: none;
+    }
+
+    .content {
+        margin-left: 0;
+        max-width: 100%;
+    }
+
+    .subsection {
+        box-shadow: none;
+        border: 1px solid var(--border-color);
+    }
+
+    pre code {
+        background-color: var(--code-bg);
+        color: var(--text-color);
+    }
+}

data/examples/concurrent_downloads.rb

@@ -54,7 +54,7 @@ module Types
       image = result.value
       path = path_for(image.url)
       File.open(path, 'wb') { |f| f.write(image.io.read) }
-      result.valid image.with(url: path, io: File.new(path))
+      result.valid image.where(url: path, io: File.new(path))
     end
 
     def path_for(url)

data/examples/csv_stream.rb

@@ -22,7 +22,7 @@ module Types
               .transform(::Enumerator, &:each)
 
   # Turn a string file path into a CSV stream
-  # ex. csv_enum = StrinToCSV.parse('./files/data.csv') #=> Enumerator
+  # ex. csv_enum = StringToCSV.parse('./files/data.csv') #=> Enumerator
   StringToCSV = OpenFile >> FileToCSV
 end
 

data/lib/plumb/composable.rb

@@ -311,16 +311,22 @@ module Plumb
 
     # Check attributes of an object against values, using #===
     # @example
-    #   type = Types::Array.with(size: 1..10)
-    #   type = Types::String.with(bytesize: 1..10)
+    #   type = Types::Array.where(size: 1..10)
+    #   type = Types::String.where(bytesize: 1..10)
     #
     # @param attrs [Hash]
-    def with(attrs)
+    def where(attrs)
       attrs.reduce(self) do |t, (name, value)|
         t >> AttributeValueMatch.new(t, name, value)
       end
     end
 
+    # @deprecated User {#where} instead
+    def with(...)
+      warn 'Composable#with() is deprecated. Use #where() instead. #with is reserved to make copies of Data structs'
+      where(...)
+    end
+
     # Register a policy for this step.
     # Mode 1.a: #policy(:name, arg) a single policy with an argument
     # Mode 1.b: #policy(:name) a single policy without an argument

data/lib/plumb/json_schema_visitor.rb

@@ -61,6 +61,13 @@ module Plumb
       props
     end
 
+    # Trying to visit the deferred could go into infinite recursion
+    # if a type is deferring to itself
+    # Not clear what deferred types would mean for JSON Schema anyway.
+    on(:deferred) do |node, props|
+      props
+    end
+
     on(:hash) do |node, props|
       props.merge(
         TYPE => 'object',

data/lib/plumb/pipeline.rb

@@ -41,9 +41,8 @@ module Plumb
       @type = type
       @children = [type].freeze
       @around_blocks = self.class.around_blocks.dup
-      return unless block_given?
 
-      configure(&setup)
+      configure(&setup) if block_given?
       freeze if freeze_after
     end
 

data/lib/plumb/schema.rb

@@ -178,8 +178,8 @@ module Plumb
         self
       end
 
-      def with(...)
-        @_type = @_type.with(...)
+      def where(...)
+        @_type = @_type.where(...)
         self
       end
 

data/lib/plumb/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - Ismael Celis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -38,7 +37,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Data validation and transformation library.
+description: Data structures, validation, coercion and processing toolkit for Ruby
 email:
 - ismaelct@gmail.com
 executables: []
@@ -54,6 +53,7 @@ files:
 - bench/compare_parametric_struct.rb
 - bench/parametric_schema.rb
 - bench/plumb_hash.rb
+- docs/styles.css
 - examples/command_objects.rb
 - examples/concurrent_downloads.rb
 - examples/csv_stream.rb
@@ -97,11 +97,11 @@ files:
 - lib/plumb/value_class.rb
 - lib/plumb/version.rb
 - lib/plumb/visitor_handlers.rb
-homepage: https://github.com/ismasan/plumb
+homepage: https://ismasan.github.io/plumb
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  source_code_uri: https://github.com/ismasan/plumb
 rdoc_options: []
 require_paths:
 - lib
@@ -116,8 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Data validation and transformation library.
 test_files: []