dry-monads 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 527c622566bcbf2acd219b357314a4b6388f49ef9f4dcfd775298de921629c7b
-  data.tar.gz: 3dc196066bd360620f39a550575a52b4d112849e09484ad76eb565002611950c
+  metadata.gz: 74c983b4b86f5bc73455c3f8987760ae5e11d026f87fbcb4741da18051c60e10
+  data.tar.gz: 42b72b1ab09dab98fe8c5a399d17d882a2fdcdf45971ec70e29868fbb07dfcba
 SHA512:
-  metadata.gz: 5dc4be9b41c1f2349b8078831d0d8980e89095da3b09cbf0084d392ce0966fcf4575d4ffa811deecf894eeb4c16cea1d09d97ebd2ef6458c6e18864f0adc42b6
-  data.tar.gz: 587c40965ce23128508b1978d2e5e2d55aff7d3780f777d6a45fbff58d19165809d8a143871269b6092ef475b4b769fcfa262414693bd9b716435ec45c4b0915
+  metadata.gz: d7afa3e95783b08fb767e1ad0b4be5aa5e3e3bf096e534884783a419acc62ccbc141fbdf641a673b9a2808b6bf27fdfb2ca64dc7e0360adbaff7f587353b3357
+  data.tar.gz: 831f701ceb7e787bab8d4c77f159aeaa1a13c5c387c790e2c50fe78a8c50a9d9d0610893466eb3f06ae73b9cbd31c08fcf45f0a8dc6822d203949abafce23870

data/CHANGELOG.md

@@ -21,6 +21,52 @@ and this project adheres to [Break Versioning](https://www.taoensso.com/break-ve
 
 [Unreleased]: https://github.com/dry-rb/dry-monads/compare/v1.10.0...main
 
+## [1.11.0] - 2026-09-11
+
+### Added
+
+- New `:json` extension, which builds a `JSON::Coder` that reads and writes monads. It needs the json gem 2.15.0 or later. (@timriley in #209)
+
+  ```ruby
+  Dry::Monads.load_extensions(:json)
+
+  coder = Dry::Monads.json_coder
+  coder.dump(Some(3)) # => %({"json_class":"Dry::Monads::Maybe::Some","value":3})
+  coder.load(%({"json_class":"Dry::Monads::Maybe::Some","value":3})) # => Some(3)
+  ```
+
+  Give `json_coder` an `as_json:` and an `on_load:` callback to handle your own types in the same coder. Both run after the monad callbacks, and your types and monads can nest inside each other:
+
+  ```ruby
+  coder = Dry::Monads.json_coder(
+    as_json: ->(object, *) {
+      object.is_a?(Time) ? {"json_class" => "Time", "value" => object.iso8601} : object
+    },
+    on_load: ->(value) {
+      value.is_a?(Hash) && value["json_class"] == "Time" ? Time.iso8601(value["value"]) : value
+    }
+  )
+  ```
+
+### Removed
+
+- **Breaking**: removed `json/add/dry/monads/maybe`. The json gem 3.0 removed the whole `json/add` mechanism, so monads can no longer hook into `JSON.dump` and `JSON.load` globally. Use the new `:json` extension instead. (@timriley in #209)
+
+  ```ruby
+  # before
+  require "json/add/dry/monads/maybe"
+  JSON.unsafe_load(JSON.dump(data))
+
+  # after
+  Dry::Monads.load_extensions(:json)
+  coder = Dry::Monads.json_coder
+  coder.load(coder.dump(data))
+  ```
+
+  The JSON serialization format is the same as before, so JSON written by the old serializer still loads. One behavior differs: `JSON::Coder` will always raise a `JSON::GeneratorError` when it sees an object with no JSON counterpart raises, instead of falling back to `to_s`.
+
+[1.11.0]: https://github.com/dry-rb/dry-monads/compare/v1.10.0...v1.11.0
+
 ## [1.10.0] - 2026-04-24
 
 ### Added

data/dry-monads.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.metadata["bug_tracker_uri"]   = "https://github.com/dry-rb/dry-monads/issues"
   spec.metadata["funding_uri"]       = "https://github.com/sponsors/hanami"
 
-  spec.required_ruby_version = ">= 3.1.0"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
   spec.add_runtime_dependency "dry-core", "~> 1.1"

data/lib/dry/monads/extensions/json.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Require json 2.15, the first version with everything this extension needs:
+#
+# - json 2.10 has `JSON::Coder`, but ignores the `on_load:` option
+# - json 2.11 through 2.14 never pass the hash key flag to the `as_json` callback
+#
+# Both of these gaps are silent and may lead to incorrect serialization, so refuse to load instead.
+if Gem::Version.new(::JSON::VERSION) < Gem::Version.new("2.15.0")
+  raise "The Dry Monads :json extension needs json 2.15.0 or later, but json #{::JSON::VERSION} is loaded"
+end
+
+module Dry
+  module Monads
+    # Reads and writes monads as JSON via `JSON::Coder`.
+    #
+    # This replaces the old `json/add/dry/monads/maybe` file, no longer working from json 3.0, which
+    # removed the whole `json/add` mechanism, so monads can no longer serialize via `JSON.dump` and
+    # `JSON.load` globally. A coder does the same job locally, without patching anything.
+    #
+    # The wire format remains unchanged, so JSON written by older versions still loads.
+    #
+    # @example
+    #   Dry::Monads.load_extensions(:json)
+    #
+    #   coder = Dry::Monads.json_coder
+    #   coder.dump(Some(3)) # => %({"json_class":"Dry::Monads::Maybe::Some","value":3})
+    #   coder.load(%({"json_class":"Dry::Monads::Maybe::Some","value":3})) # => Some(3)
+    #
+    # @api public
+    module JSONCoder
+      # Key used to tag a serialized monad.
+      JSON_CLASS_KEY = "json_class"
+
+      # Called for every object the generator cannot write natively.
+      #
+      # The second argument is `true` when the object is a hash key and `false` everywhere else. We
+      # do not use it, because a monad never appears as a key, but it must be accepted.
+      #
+      # @api private
+      AS_JSON = lambda { |object, *|
+        case object
+        when Maybe
+          {JSON_CLASS_KEY => object.class.name, "value" => object.none? ? nil : object.value!}
+        else
+          object
+        end
+      }
+
+      # Called for every value the parser produces, innermost first.
+      #
+      # @api private
+      ON_LOAD = lambda { |value|
+        next value unless value.is_a?(::Hash) && value.key?(JSON_CLASS_KEY)
+
+        case value[JSON_CLASS_KEY]
+        when Maybe::Some.name then Maybe::Some.new(value["value"])
+        when Maybe::None.name then Maybe::None.instance
+        else value
+        end
+      }
+    end
+
+    # Returns a coder that reads and writes monads. Unknown objects raise `JSON::GeneratorError`.
+    #
+    # A `JSON::Coder` is frozen on creation, so you cannot add monad support to an existing coder.
+    # Build your coder here instead: provide `as_json:` to write your own types, and `on_load:` to
+    # read them back. Both will run after the monad callbacks, and both see every value, so pass
+    # through anything you do not recognize.
+    #
+    # @example a coder that reads and writes monads and times
+    #   coder = Dry::Monads.json_coder(
+    #     as_json: ->(object, *) {
+    #       object.is_a?(Time) ? {"json_class" => "Time", "value" => object.iso8601} : object
+    #     },
+    #     on_load: ->(value) {
+    #       if value.is_a?(Hash) && value["json_class"] == "Time"
+    #         Time.iso8601(value["value"])
+    #       else
+    #         value
+    #       end
+    #     }
+    #   )
+    #
+    #   coder.dump(Some(Time.utc(2026)))
+    #   # => %({"json_class":"Dry::Monads::Maybe::Some","value":{"json_class":"Time","value":"2026-01-01T00:00:00Z"}})
+    #
+    # Monads nest inside your types and the other way around, because the generator and the
+    # parser walk the whole document and call both callbacks at every step.
+    #
+    # `as_json:` takes a second argument, which is `true` when the object is a hash key, and `false`
+    # everywhere else. Use it if you write a type that can be a key, because for a key you must
+    # return a String or a Symbol. Anything else raises `JSON::GeneratorError`:
+    #
+    #   as_json: ->(object, as_key) {
+    #     next object unless object.is_a?(Time)
+    #     as_key ? object.iso8601 : {"json_class" => "Time", "value" => object.iso8601}
+    #   }
+    #
+    # Even if you don't need this argument, your lambda must accept it (as in `->(object, *)`), or
+    # you will see an `ArgumentError` on the first dump.
+    #
+    # @param as_json [#call, nil] runs on every object the generator cannot write natively, after
+    #   the monad callback
+    # @param on_load [#call, nil] runs on every parsed value, after the monad callback
+    # @param options [Hash] passed on to `JSON::Coder.new`
+    # @return [JSON::Coder]
+    #
+    # @api public
+    def self.json_coder(as_json: nil, on_load: nil, **options, &block)
+      # `JSON::Coder.new` takes its `as_json` callback as a block. We've opted to make it an keyword
+      # argument for consistency alongside `on_load:`.
+      #
+      # A user familiar with `JSON::Coder` may provide a block, so raise an error just in case.
+      raise ArgumentError, "pass the as_json callback as `as_json:`, not as a block" if block
+
+      ::JSON::Coder.new(
+        on_load: on_load ? JSONCoder::ON_LOAD >> on_load : JSONCoder::ON_LOAD,
+        **options
+      ) do |object, as_key|
+        json = JSONCoder::AS_JSON.call(object, as_key)
+        as_json ? as_json.call(json, as_key) : json
+      end
+    end
+  end
+end

data/lib/dry/monads/extensions.rb

@@ -13,3 +13,7 @@ end
 Dry::Monads.register_extension(:pretty_print) do
   require "dry/monads/extensions/pretty_print"
 end
+
+Dry::Monads.register_extension(:json) do
+  require "dry/monads/extensions/json"
+end

data/lib/dry/monads/maybe.rb

@@ -142,9 +142,9 @@ module Dry
         def maybe(...) = Maybe.coerce(bind(...))
 
         # Accepts a block and runs it against the wrapped value.
-        # If the block returns a trurhy value the result is self,
+        # If the block returns a truthy value the result is self,
         # otherwise None. If no block is given, the value serves
-        # and its result.
+        # as its result.
         #
         # @param with [#call] positional block
         # @param block [Proc] block

data/lib/dry/monads/validated.rb

@@ -46,7 +46,7 @@ module Dry
       def bind(...)
         # See https://typelevel.org/cats/datatypes/validated.html for details on why
         raise NotImplementedError,
-              "Validated is not a monad because it would violate the monad laws"
+          "Validated is not a monad because it would violate the monad laws"
       end
 
       # Valid result

data/lib/dry/monads/version.rb

@@ -3,6 +3,6 @@
 module Dry
   module Monads
     # Gem version
-    VERSION = "1.10.0"
+    VERSION = "1.11.0"
   end
 end

data/lib/dry/monads.rb

@@ -23,7 +23,6 @@ module Dry
         loader.ignore(
           "#{root}/dry-monads.rb",
           "#{root}/dry/monads/{all,constants,errors,registry,version}.rb",
-          "#{root}/json/**/*.rb",
           "#{root}/dry/monads/extensions.rb",
           "#{root}/dry/monads/extensions/**/*.rb"
         )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-monads
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Hanakai team
@@ -132,6 +132,7 @@ files:
 - lib/dry/monads/do/mixin.rb
 - lib/dry/monads/errors.rb
 - lib/dry/monads/extensions.rb
+- lib/dry/monads/extensions/json.rb
 - lib/dry/monads/extensions/pretty_print.rb
 - lib/dry/monads/extensions/rspec.rb
 - lib/dry/monads/extensions/super_diff.rb
@@ -149,7 +150,6 @@ files:
 - lib/dry/monads/unit.rb
 - lib/dry/monads/validated.rb
 - lib/dry/monads/version.rb
-- lib/json/add/dry/monads/maybe.rb
 homepage: https://dry-rb.org/gems/dry-monads
 licenses:
 - MIT
@@ -165,7 +165,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/json/add/dry/monads/maybe.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: false
-
-require "json" unless defined?(JSON::JSON_LOADED) && JSON::JSON_LOADED
-
-require "dry/monads"
-
-# Inspired by standard library implementation
-# for Time serialization/deserialization see (json/lib/json/add/time.rb)
-#
-module Dry
-  module Monads
-    class Maybe
-      # Deserializes JSON string by using Dry::Monads::Maybe#lift method
-      def self.json_create(serialized)
-        coerce(serialized.fetch("value"))
-      end
-
-      # Returns a hash, that will be turned into a JSON object and represent this
-      # object.
-      def as_json(*, **)
-        {
-          JSON.create_id => self.class.name,
-          value: none? ? nil : @value
-        }
-      end
-
-      # Stores class name (Dry::Monads::Maybe::Some or Dry::Monads::Maybe::None)
-      # with the monad value as JSON string
-      def to_json(...) = as_json.to_json(...)
-    end
-  end
-end