bson 4.7.1-java → 4.8.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8c8a8456a3da6e860243257d9bb9feeb63257f21422a15150df244c8013830d
-  data.tar.gz: 9dafda0d9652f1528fbce70db3fa6ab2645275dbb292f3f1bc8171adde2e5b0c
+  metadata.gz: d691529718f7129a9ee438d11e85f2abc13fe81c03a43d48f528a21e05bd9e1b
+  data.tar.gz: 5ab219503040fe8826b1d58bcc51bdad454fa84420609474b6315c18f54a5db0
 SHA512:
-  metadata.gz: ea4a57864469d857227855434271646d2a2c168d927f24fbfd8d7f8a86709744db36d52a52567f25b2b5fa6f2aa83c7d67032b9d2bb5a773d36490dc30eb5a61
-  data.tar.gz: 0bc99ae57ae76c93ccc2b7be6a23804486ec20a9e38bb82c206baf69e8dd13eaeb4a5fe2290d8e8eefcbf552193d48c2a0579cfcd4f939005535f526e6967d73
+  metadata.gz: b00a7c8078bf9d05a94ecb6d4052eb195df77115a6d11568d84db513da65ace9ec15ce91ca403680d1a029f615ac80e41b4e98aee44133c3a4b488d56f6075fc
+  data.tar.gz: 83a6195af39949c91379888f7c97d244b42248824de696248fb958825725a711b6ea414da93b3bac7f581c55999b33c633114e2d057366ea2e1d9c838a1002f4

checksums.yaml.gz.sig

@@ -1,2 +1 @@
-b)�GPk�M�����EV�_s�Q��MD<�����@A|�zYs6��
>g|e-2N����5_�&Q��M��k!��L�Y�Ȕ����ntvI}UWc.#��ONG'�����-/�y���
q
��l�5Z{�G���;��S��g���1�"�Uڋ!�Ƒ��/� z
-S^�T�J/N�����}~!�*Ȏ<�����"�Aq�:K�iF�b1���� ��%\TCW�5xڊ����KFsW��M�*��4P��;KK
+��n�QH@�y|d����E�5�.�
!�<ҙ(
L�����1����+R8lD|襣��2m$�E�

data/README.md

@@ -1,4 +1,8 @@
-BSON [![Build Status](https://secure.travis-ci.org/mongodb/bson-ruby.png?branch=master&.png)](http://travis-ci.org/mongodb/bson-ruby)  [![Code Climate](https://codeclimate.com/github/mongodb/bson-ruby.png)](https://codeclimate.com/github/mongodb/bson-ruby) [![Coverage Status](https://coveralls.io/repos/mongodb/bson-ruby/badge.png?branch=master)](https://coveralls.io/r/mongodb/bson-ruby?branch=master) [![Inline docs](http://inch-ci.org/github/mongodb/bson-ruby.svg?branch=master)](http://inch-ci.org/github/mongodb/bson-ruby)
+BSON [![Build Status](https://secure.travis-ci.org/mongodb/bson-ruby.svg?branch=master)](http://travis-ci.org/mongodb/bson-ruby)
+[![Build status Windows](https://ci.appveyor.com/api/projects/status/p5aqko7umsx351nm?svg=true)](https://ci.appveyor.com/project/p-mongo/bson-ruby/branch/master)
+[![Code Climate](https://codeclimate.com/github/mongodb/bson-ruby.svg)](https://codeclimate.com/github/mongodb/bson-ruby)
+[![Coverage Status](https://coveralls.io/repos/mongodb/bson-ruby/badge.svg?branch=master)](https://coveralls.io/r/mongodb/bson-ruby?branch=master)
+[![Inline docs](http://inch-ci.org/github/mongodb/bson-ruby.svg?branch=master)](http://inch-ci.org/github/mongodb/bson-ruby)
 ====
 
 An implementation of the BSON specification in Ruby.

data/lib/bson.rb

@@ -57,6 +57,7 @@ module BSON
 end
 
 require "bson/config"
+require "bson/error"
 require "bson/registry"
 require "bson/specialized"
 require "bson/json"
@@ -70,8 +71,10 @@ require "bson/code"
 require "bson/code_with_scope"
 require "bson/date"
 require "bson/date_time"
+require "bson/db_pointer"
 require "bson/decimal128"
 require "bson/document"
+require "bson/ext_json"
 require "bson/false_class"
 require "bson/float"
 require "bson/hash"

data/lib/bson/array.rb

@@ -85,26 +85,44 @@ module BSON
       map { |value| value.to_bson_normalized_value }
     end
 
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # This method recursively invokes +as_extended_json+ with the provided
+    # options on each array element.
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Array ] This array converted to extended json representation.
+    def as_extended_json(**options)
+      map do |item|
+        item.as_extended_json(**options)
+      end
+    end
+
     module ClassMethods
 
       # Deserialize the array from BSON.
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Array ] The decoded array.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         if buffer.respond_to?(:get_array)
-          buffer.get_array
+          buffer.get_array(**options)
         else
           array = new
           buffer.get_int32 # throw away the length
           while (type = buffer.get_byte) != NULL_BYTE
             buffer.get_cstring
-            array << BSON::Registry.get(type).from_bson(buffer)
+            array << BSON::Registry.get(type).from_bson(buffer, **options)
           end
           array
         end

data/lib/bson/binary.rb

@@ -31,6 +31,12 @@ module BSON
 
     # The mappings of subtypes to their single byte identifiers.
     #
+    # @note subtype 6 (ciphertext) is used for the Client-Side Encryption
+    #   feature. Data represented by this subtype is often encrypted, but
+    #   may also be plaintext. All instances of this subtype necessary for
+    #   Client-Side Encryption will be created internally by the Ruby driver.
+    #   An application should not create new BSON::Binary objects of this subtype.
+    #
     # @since 2.0.0
     SUBTYPES = {
       :generic => 0.chr,
@@ -39,6 +45,7 @@ module BSON
       :uuid_old => 3.chr,
       :uuid => 4.chr,
       :md5 => 5.chr,
+      :ciphertext => 6.chr,
       :user => 128.chr
     }.freeze
 
@@ -94,8 +101,31 @@ module BSON
     # @return [ Hash ] The binary as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
-      { "$binary" => Base64.encode64(data), "$type" => type }
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      subtype = SUBTYPES[type].each_byte.map { |c| c.to_s(16) }.join
+      if subtype.length == 1
+        subtype = "0#{subtype}"
+      end
+
+      value = Base64.encode64(data).strip
+
+      if options[:mode] == :legacy
+        { "$binary" => value, "$type" => subtype }
+      else
+        { "$binary" => {'base64' => value, "subType" => subtype }}
+      end
     end
 
     # Instantiate the new binary object.
@@ -228,14 +258,22 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ Binary ] The decoded binary data.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       length = buffer.get_int32
-      type = TYPES[buffer.get_byte]
+      type_byte = buffer.get_byte
+      type = TYPES[type_byte]
+      if type.nil?
+        raise Error::UnsupportedBinarySubtype,
+          "BSON data contains unsupported binary subtype #{'0x%02x' % type_byte.ord}"
+      end
+
       length = buffer.get_int32 if type == :old
       data = buffer.get_bytes(length)
       new(data, type)

data/lib/bson/boolean.rb

@@ -31,12 +31,14 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded boolean.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       buffer.get_byte == TrueClass::TRUE_BYTE
     end
 

data/lib/bson/code.rb

@@ -55,7 +55,19 @@ module BSON
     # @return [ Hash ] The code as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { "$code" => javascript }
     end
 
@@ -89,12 +101,14 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded code.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       new(buffer.get_string)
     end
 

data/lib/bson/code_with_scope.rb

@@ -59,8 +59,20 @@ module BSON
     # @return [ Hash ] The code with scope as a JSON hash.
     #
     # @since 2.0.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
-      { "$code" => javascript, "$scope" => scope }
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      { "$code" => javascript, "$scope" => scope.as_extended_json(**options) }
     end
 
     # Instantiate the new code with scope.
@@ -99,14 +111,16 @@ module BSON
     #
     # @param [ ByteBuffer ] buffer The byte buffer.
     #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
     # @return [ TrueClass, FalseClass ] The decoded code with scope.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def self.from_bson(buffer)
+    def self.from_bson(buffer, **options)
       buffer.get_int32 # Throw away the total length.
-      new(buffer.get_string, ::Hash.from_bson(buffer))
+      new(buffer.get_string, ::Hash.from_bson(buffer, **options))
     end
 
     # Register this type when the module is loaded.

data/lib/bson/db_pointer.rb

@@ -0,0 +1,104 @@
+# Copyright (C) 2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module BSON
+
+  # Injects behaviour for encoding and decoding DBPointer values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  class DbPointer
+    include JSON
+
+    # A DBPointer is type 0x0C in the BSON spec.
+    BSON_TYPE = 0x0C.chr.force_encoding(BINARY).freeze
+
+    # Create a new DBPointer object.
+    #
+    # @param [ String ] ref The database collection name.
+    # @param [ BSON::ObjectId ] id The DBPointer id.
+    def initialize(ref, id)
+      @ref = ref
+      @id = id
+    end
+
+    # Return the collection name.
+    #
+    # @return [ String ] The database collection name.
+    attr_reader :ref
+
+    # Return the DbPointer's id.
+    #
+    # @return [ BSON::ObjectId ] The id of the DbPointer instance
+    attr_reader :id
+
+    # Determine if this DBPointer object is equal to another object.
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true | false ] If the objects are equal
+    def ==(other)
+      return false unless other.is_a?(DbPointer)
+      ref == other.ref && id == other.id
+    end
+
+    # Get the DBPointer as JSON hash data
+    #
+    # @return [ Hash ] The DBPointer as a JSON hash.
+    #
+    # @deprecated Use as_extended_json instead.
+    def as_json(*args)
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option options [ true | false ] :relaxed Whether to produce relaxed
+    #   extended JSON representation.
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
+      {'$dbPointer' => { "$ref" => ref, '$id' => id.as_extended_json }}
+    end
+
+    # Encode the DBPointer.
+    #
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+    #
+    # @see http://bsonspec.org/#/specification
+    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+      buffer.put_string(ref)
+      id.to_bson(buffer, validating_keys)
+      buffer
+    end
+
+    # Deserialize a DBPointer from BSON.
+    #
+    # @param [ ByteBuffer ] buffer The byte buffer.
+    # @param [ Hash ] options
+    #
+    # @option options [ nil | :bson ] :mode Decoding mode to use.
+    #
+    # @return [ BSON::DbPointer ] The decoded DBPointer.
+    #
+    # @see http://bsonspec.org/#/specification
+    def self.from_bson(buffer, **options)
+      new(buffer.get_string, ObjectId.from_bson(buffer, **options))
+    end
+
+    # Register this type when the module is loaded.
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/decimal128.rb

@@ -63,7 +63,19 @@ module BSON
     # @return [ Hash ] The number as a JSON hash.
     #
     # @since 4.2.0
+    # @deprecated Use as_extended_json instead.
     def as_json(*args)
+      as_extended_json
+    end
+
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).
+    #
+    # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+    #   (default is canonical extended JSON)
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**options)
       { EXTENDED_JSON_KEY => to_s }
     end
 
@@ -197,10 +209,12 @@ module BSON
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ BSON::Decimal128 ] The decimal object.
       #
       # @since 4.2.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         from_bits(*buffer.get_decimal128_bytes.unpack('Q<*'))
       end
 

data/lib/bson/error.rb

@@ -0,0 +1,17 @@
+module BSON
+  # Base exception class for all BSON-related errors.
+  #
+  # @note Many existing exceptions raised by bson-ruby do not derive from
+  #   this base class. This will change in the next major version (5.0).
+  class Error < StandardError
+
+    # Exception raised when Extended JSON parsing fails.
+    class ExtJSONParseError < Error
+    end
+
+    # Exception raised when decoding BSON and the data contains an
+    # unsupported binary subtype.
+    class UnsupportedBinarySubtype < Error
+    end
+  end
+end

data/lib/bson/ext_json.rb

@@ -0,0 +1,374 @@
+# Copyright (C) 2019 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'json'
+
+module BSON
+
+  # This module contains methods for parsing Extended JSON 2.0.
+  # https://github.com/mongodb/specifications/blob/master/source/extended-json.rst
+  module ExtJSON
+
+    # Parses JSON in a string into a Ruby object tree.
+    #
+    # There are two strategies that this method can follow. If the canonical
+    # strategy is used which is the default, this method returns BSON types
+    # as much as possible. This allows the resulting object tree to be
+    # serialized back to extended JSON or to BSON while preserving the types.
+    # The relaxed strategy, enabled by passing {emit_relaxed: true} option,
+    # returns native Ruby types as much as possible which makes the resulting
+    # object tree easier to work with but may lose type information.
+    #
+    # Please note the following aspects of this method when emitting relaxed
+    # object trees:
+    #
+    # 1. $numberInt and $numberLong inputs produce Integer instances.
+    # 2. $regularExpression inputs produce BSON Regexp instances. This may
+    #    change in a future version of bson-ruby to produce Ruby Regexp
+    #    instances, potentially depending on regular expression options.
+    # 3. $numberDecimal inputs produce BSON Decimal128 instances. This may
+    #    change in a future version of bson-ruby to produce Ruby BigDecimal
+    #    instances instead.
+    #
+    # This method accepts canonical extended JSON, relaxed extended JSON and
+    # JSON without type information as well as a mix of the above.
+    #
+    # @note This method uses Ruby standard library's JSON.parse method to
+    # perform JSON parsing. As the JSON.parse method accepts inputs other
+    # than hashes, so does this method and therefore this method can return
+    # objects of any type.
+    #
+    # @param [ String ] str The string to parse.
+    #
+    # @option options [ nil | :bson ] :mode Which types to emit
+    #
+    # @return [ Object ] Parsed object tree.
+    module_function def parse(str, **options)
+      parse_obj(::JSON.parse(str), **options)
+    end
+
+    # Transforms a Ruby object tree containing extended JSON type hashes
+    # into a Ruby object tree with said hashes replaced by BSON or Ruby native
+    # types.
+    #
+    # @example Convert extended JSON type hashes:
+    #   BSON::ExtJSON.parse_obj('foo' => {'$numberLong' => '42'})
+    #   => {"foo"=>#<BSON::Int64:0x000055e55f4d40f0 @value=42>}
+    #
+    # @example Convert a non-hash value:
+    #   BSON::ExtJSON.parse_obj('$numberLong' => '42')
+    #   => #<BSON::Int64:0x000055e55f4e6ed0 @value=42>
+    #
+    # There are two strategies that this method can follow. If the canonical
+    # strategy is used which is the default, this method returns BSON types
+    # as much as possible. This allows the resulting object tree to be
+    # serialized back to extended JSON or to BSON while preserving the types.
+    # The relaxed strategy, enabled by passing {emit_relaxed: true} option,
+    # returns native Ruby types as much as possible which makes the resulting
+    # object tree easier to work with but may lose type information.
+    #
+    # Please note the following aspects of this method when emitting relaxed
+    # object trees:
+    #
+    # 1. $numberInt and $numberLong inputs produce Integer instances.
+    # 2. $regularExpression inputs produce BSON Regexp instances. This may
+    #    change in a future version of bson-ruby to produce Ruby Regexp
+    #    instances, potentially depending on regular expression options.
+    # 3. $numberDecimal inputs produce BSON Decimal128 instances. This may
+    #    change in a future version of bson-ruby to produce Ruby BigDecimal
+    #    instances instead.
+    #
+    # This method accepts object trees resulting from parsing canonical
+    # extended JSON, relaxed extended JSON and JSON without type information
+    # as well as a mix of the above.
+    #
+    # @note This method accepts any types as input, not just Hash instances.
+    # Consequently, it can return values of any type.
+    #
+    # @param [ Object ] value The object tree to convert.
+    #
+    # @option options [ nil | :bson ] :mode Which types to emit
+    #
+    # @return [ Object ] Converted object tree.
+    module_function def parse_obj(value, **options)
+      # TODO implement :ruby and :ruby! modes
+      unless [nil, :bson].include?(options[:mode])
+        raise ArgumentError, "Invalid value for :mode option: #{options[:mode].inspect}"
+      end
+
+      case value
+      when String, TrueClass, FalseClass, NilClass, Numeric
+        value
+      when Hash
+        parse_hash(value, **options)
+      when Array
+        value.map do |item|
+          parse_obj(item, **options)
+        end
+      else
+        raise Error::ExtJSONParseError, "Unknown value type: #{value}"
+      end
+    end
+
+    private
+
+    RESERVED_KEYS = %w(
+      $oid $symbol $numberInt $numberLong $numberDouble $numberDecimal
+      $binary $code $scope $timestamp $regularExpression $dbPointer
+      $date $minKey $maxKey $undefined
+    ).freeze
+
+    RESERVED_KEYS_HASH = Hash[RESERVED_KEYS.map do |key|
+      [key, true]
+    end].freeze
+
+    module_function def parse_hash(hash, **options)
+      if hash.empty?
+        return {}
+      end
+
+      if hash.key?('$ref')
+        # Legacy dbref handling.
+        # Note that according to extended json spec, only hash values (but
+        # not the top-level BSON document itself) may be of type "dbref".
+        # This code applies to both hash values and the hash overall; however,
+        # since we do not have DBRef as a distinct type, applying the below
+        # logic to top level hashes doesn't cause harm.
+        hash = hash.dup
+        ref = hash.delete('$ref')
+        # $ref can be a string value or an ObjectId
+        unless ref.is_a?(String)
+          raise Error::ExtJSONParseError, "Invalid $ref value: #{ref}"
+        end
+        # $id, if present, can be anything
+        id = hash.delete('$id')
+        if id.is_a?(Hash)
+          id = parse_hash(id)
+        end
+        # Preserve $id value as it was, do not convert either to ObjectId
+        # or to a string. But if the value was in {'$oid' => ...} format,
+        # the value is converted to an ObjectId instance so that
+        # serialization to BSON later on works correctly.
+        out = {'$ref' => ref, '$id' => id}
+        if hash.key?('$db')
+          # $db must always be a string, if provided
+          db = hash.delete('$db')
+          unless db.is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $db value: #{db}"
+          end
+          out['$db'] = db
+        end
+        return out.update(hash)
+      end
+
+      if hash.length == 1
+        key, value = hash.first
+        return case key
+        when '$oid'
+          ObjectId.from_string(value)
+        when '$symbol'
+          Symbol::Raw.new(value)
+        when '$numberInt'
+          unless value.is_a?(String)
+            raise Error::ExtJSONParseError, "$numberInt value is of an incorrect type: #{value}"
+          end
+          value.to_i
+        when '$numberLong'
+          unless value.is_a?(String)
+            raise Error::ExtJSONParseError, "$numberLong value is of an incorrect type: #{value}"
+          end
+          value = value.to_i
+          if options[:mode] != :bson
+            value
+          else
+            Int64.new(value)
+          end
+        when '$numberDouble'
+          # This handles string to double conversion as well as inf/-inf/nan
+          unless value.is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $numberDouble value: #{value}"
+          end
+          BigDecimal(value).to_f
+        when '$numberDecimal'
+          # TODO consider returning BigDecimal here instead of Decimal128
+          Decimal128.new(value)
+        when '$binary'
+          unless value.is_a?(Hash)
+            raise Error::ExtJSONParseError, "Invalid $binary value: #{value}"
+          end
+          unless value.keys.sort == %w(base64 subType)
+            raise Error::ExtJSONParseError, "Invalid $binary value: #{value}"
+          end
+          encoded_value = value['base64']
+          unless encoded_value.is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid base64 value in $binary: #{value}"
+          end
+          subtype = value['subType']
+          unless subtype.is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid subType value in $binary: #{value}"
+          end
+          create_binary(encoded_value, subtype)
+        when '$code'
+          unless value.is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $code value: #{value}"
+          end
+          Code.new(value)
+        when '$timestamp'
+          unless value.keys.sort == %w(i t)
+            raise Error::ExtJSONParseError, "Invalid $timestamp value: #{value}"
+          end
+          t = value['t']
+          unless t.is_a?(Integer)
+            raise Error::ExtJSONParseError, "Invalid t value: #{value}"
+          end
+          i = value['i']
+          unless i.is_a?(Integer)
+            raise Error::ExtJSONParseError, "Invalid i value: #{value}"
+          end
+          Timestamp.new(t, i)
+        when '$regularExpression'
+          unless value.keys.sort == %w(options pattern)
+            raise Error::ExtJSONParseError, "Invalid $regularExpression value: #{value}"
+          end
+          # TODO consider returning Ruby regular expression object here
+          create_regexp(value['pattern'], value['options'])
+        when '$dbPointer'
+          unless value.keys.sort == %w($id $ref)
+            raise Error::ExtJSONParseError, "Invalid $dbPointer value: #{value}"
+          end
+          DbPointer.new(value['$ref'], parse_hash(value['$id']))
+        when '$date'
+          case value
+          when String
+            ::Time.parse(value)
+          when Hash
+            unless value.keys.sort == %w($numberLong)
+              raise Error::ExtJSONParseError, "Invalid value for $date: #{value}"
+            end
+            ::Time.at(value.values.first.to_i.to_f / 1000)
+          else
+            raise Error::ExtJSONParseError, "Invalid value for $date: #{value}"
+          end
+        when '$minKey'
+          unless value == 1
+            raise Error::ExtJSONParseError, "Invalid $minKey value: #{value}"
+          end
+          MinKey.new
+        when '$maxKey'
+          unless value == 1
+            raise Error::ExtJSONParseError, "Invalid $maxKey value: #{value}"
+          end
+          MaxKey.new
+        when '$undefined'
+          unless value == true
+            raise Error::ExtJSONParseError, "Invalid $undefined value: #{value}"
+          end
+          Undefined.new
+        else
+          map_hash(hash, **options)
+        end
+      end
+
+      if hash.length == 2
+        sorted_keys = hash.keys.sort
+        first_key = sorted_keys.first
+        last_key = sorted_keys.last
+
+        if first_key == '$code'
+          unless sorted_keys == %w($code $scope)
+            raise Error::ExtJSONParseError, "Invalid $code value: #{hash}"
+          end
+          unless hash['$code'].is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $code value: #{value}"
+          end
+
+          return CodeWithScope.new(hash['$code'], map_hash(hash['$scope']))
+        end
+
+        if first_key == '$binary'
+          unless sorted_keys == %w($binary $type)
+            raise Error::ExtJSONParseError, "Invalid $binary value: #{hash}"
+          end
+          unless hash['$binary'].is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $binary value: #{value}"
+          end
+          unless hash['$type'].is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $binary subtype: #{hash['$type']}"
+          end
+
+          return create_binary(hash['$binary'], hash['$type'])
+        end
+
+        if last_key == '$regex'
+          unless sorted_keys == %w($options $regex)
+            raise Error::ExtJSONParseError, "Invalid $regex value: #{hash}"
+          end
+
+          if hash['$regex'].is_a?(Hash)
+            return {
+              '$regex' => parse_hash(hash['$regex']),
+              '$options' => hash['$options']
+            }
+          end
+
+          unless hash['$regex'].is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $regex pattern: #{hash['$regex']}"
+          end
+          unless hash['$options'].is_a?(String)
+            raise Error::ExtJSONParseError, "Invalid $regex options: #{hash['$options']}"
+          end
+
+          return create_regexp(hash['$regex'], hash['$options'])
+        end
+
+        verify_no_reserved_keys(hash, **options)
+      end
+
+      verify_no_reserved_keys(hash, **options)
+    end
+
+    module_function def verify_no_reserved_keys(hash, **options)
+      if hash.length > RESERVED_KEYS.length
+        if RESERVED_KEYS.any? { |key| hash.key?(key) }
+          raise Error::ExtJSONParseError, "Hash uses reserved keys but does not match a known type: #{hash}"
+        end
+      else
+        if hash.keys.any? { |key| RESERVED_KEYS_HASH.key?(key) }
+          raise Error::ExtJSONParseError, "Hash uses reserved keys but does not match a known type: #{hash}"
+        end
+      end
+      map_hash(hash, **options)
+    end
+
+    module_function def map_hash(hash, **options)
+      ::Hash[hash.map do |key, value|
+        [key, parse_obj(value, **options)]
+      end]
+    end
+
+    module_function def create_binary(encoded_value, encoded_subtype)
+      subtype = encoded_subtype.hex
+      type = Binary::TYPES[subtype.chr]
+      unless type
+        # Requires https://jira.mongodb.org/browse/RUBY-2056
+        raise NotImplementedError, "Binary subtype #{encoded_subtype} is not currently supported"
+      end
+      Binary.new(Base64.decode64(encoded_value), type)
+    end
+
+    module_function def create_regexp(pattern, options)
+      Regexp::Raw.new(pattern, options)
+    end
+  end
+end