jsi 0.0.4 → 0.4.0

data/lib/jsi/base/to_rb.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSI
   class Base
     class << self

data/lib/jsi/jsi_coder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module JSI
+  # this is an ActiveRecord serialization coder intended to serialize between
+  # JSON-compatible objects on the database side, and a JSI instance loaded on
+  # the model attribute.
+  #
+  # on its own this coder is useful with a JSON database column. in order to
+  # serialize further to a string of JSON, or to YAML, the gem `arms` allows
+  # coders to be chained together. for example, for a table `foos` and a column
+  # `preferences_json` which is an actual json column, and `preferences_txt`
+  # which is a string:
+  #
+  #     Preferences = JSI.class_for_schema(preferences_json_schema)
+  #     class Foo < ActiveRecord::Base
+  #       # as a single serializer, loads a Preferences instance from a json column
+  #       serialize 'preferences_json', JSI::JSICoder.new(Preferences)
+  #
+  #       # for a text column, arms_serialize will go from JSI to JSON-compatible
+  #       # objects to a string. the symbol `:jsi` is a shortcut for JSI::JSICoder.
+  #       arms_serialize 'preferences_txt', [:jsi, Preferences], :json
+  #     end
+  #
+  # the column data may be either a single instance of the schema class
+  # (represented as one json object) or an array of them (represented as a json
+  # array of json objects), indicated by the keyword argument `array`.
+  class JSICoder
+    # @param schema [JSI::Schema, JSI::SchemaModule, Class < JSI::Base] a schema, a JSI schema class, or
+    #   a JSI schema module. #load will instantiate column data using the JSI schema represented.
+    # @param array [Boolean] whether the dumped data represent one instance of the schema,
+    #   or an array of them. note that it may be preferable to simply use an array schema.
+    def initialize(schema, array: false)
+      unless schema.respond_to?(:new_jsi)
+        raise(ArgumentError, "not a JSI schema, class, or module: #{schema.inspect}")
+      end
+      @schema = schema
+      @array = array
+    end
+
+    # loads the database column to JSI instances of our schema
+    #
+    # @param data [Object, Array, nil] the dumped schema instance(s) of the JSI(s)
+    # @return [JSI::Base, Array<JSI::Base>, nil] the JSI or JSIs containing the schema
+    #   instance(s), or nil if data is nil
+    def load(data)
+      return nil if data.nil?
+      object = if @array
+        unless data.respond_to?(:to_ary)
+          raise TypeError, "expected array-like column data; got: #{data.class}: #{data.inspect}"
+        end
+        data.map { |el| load_object(el) }
+      else
+        load_object(data)
+      end
+      object
+    end
+
+    # @param object [JSI::Base, Array<JSI::Base>, nil] the JSI or array of JSIs containing
+    #   the schema instance(s)
+    # @return [Object, Array, nil] the schema instance(s) of the JSI(s), or nil if object is nil
+    def dump(object)
+      return nil if object.nil?
+      jsonifiable = begin
+        if @array
+          unless object.respond_to?(:to_ary)
+            raise(TypeError, "expected array-like attribute; got: #{object.class}: #{object.inspect}")
+          end
+          object.map do |el|
+            dump_object(el)
+          end
+        else
+          dump_object(object)
+        end
+      end
+      jsonifiable
+    end
+
+    private
+    # @param data [Object]
+    # @return [JSI::Base]
+    def load_object(data)
+      @schema.new_jsi(data)
+    end
+
+    # @param object [JSI::Base, Object]
+    # @return [Object]
+    def dump_object(object)
+      JSI::Typelike.as_json(object)
+    end
+  end
+end

data/lib/jsi/json-schema-fragments.rb

@@ -1,141 +1,9 @@
+# frozen_string_literal: true
+
 require "json-schema"
 
 # apply the changes from https://github.com/ruby-json-schema/json-schema/pull/382 
 
-# json-schema/pointer.rb
-require 'addressable/uri'
-
-module JSON
-  class Schema
-    # a JSON Pointer, as described by RFC 6901 https://tools.ietf.org/html/rfc6901
-    class Pointer
-      class Error < JSON::Schema::SchemaError
-      end
-      class PointerSyntaxError < Error
-      end
-      class ReferenceError < Error
-      end
-
-      # parse a fragment to an array of reference tokens
-      #
-      # #/foo/bar
-      #
-      # => ['foo', 'bar']
-      #
-      # #/foo%20bar
-      #
-      # => ['foo bar']
-      def self.parse_fragment(fragment)
-        fragment = Addressable::URI.unescape(fragment)
-        match = fragment.match(/\A#/)
-        if match
-          parse_pointer(match.post_match)
-        else
-          raise(PointerSyntaxError, "Invalid fragment syntax in #{fragment.inspect}: fragment must begin with #")
-        end
-      end
-
-      # parse a pointer to an array of reference tokens
-      #
-      # /foo
-      #
-      # => ['foo']
-      #
-      # /foo~0bar/baz~1qux
-      #
-      # => ['foo~bar', 'baz/qux']
-      def self.parse_pointer(pointer_string)
-        tokens = pointer_string.split('/', -1).map! do |piece|
-          piece.gsub('~1', '/').gsub('~0', '~')
-        end
-        if tokens[0] == ''
-          tokens[1..-1]
-        elsif tokens.empty?
-          tokens
-        else
-          raise(PointerSyntaxError, "Invalid pointer syntax in #{pointer_string.inspect}: pointer must begin with /")
-        end
-      end
-
-      # initializes a JSON::Schema::Pointer from the given representation.
-      #
-      # type may be one of:
-      #
-      # - :fragment - the representation is a fragment containing a pointer (starting with #)
-      # - :pointer - the representation is a pointer (starting with /)
-      # - :reference_tokens - the representation is an array of tokens referencing a path in a document
-      def initialize(type, representation)
-        @type = type
-        if type == :reference_tokens
-          reference_tokens = representation
-        elsif type == :fragment
-          reference_tokens = self.class.parse_fragment(representation)
-        elsif type == :pointer
-          reference_tokens = self.class.parse_pointer(representation)
-        else
-          raise ArgumentError, "invalid initialization type: #{type.inspect} with representation #{representation.inspect}"
-        end
-        @reference_tokens = reference_tokens.map(&:freeze).freeze
-      end
-
-      attr_reader :reference_tokens
-
-      # takes a root json document and evaluates this pointer through the document, returning the value
-      # pointed to by this pointer.
-      def evaluate(document)
-        res = reference_tokens.inject(document) do |value, token|
-          if value.respond_to?(:to_ary)
-            if token.is_a?(String) && token =~ /\A\d|[1-9]\d+\z/
-              token = token.to_i
-            end
-            unless token.is_a?(Integer)
-              raise(ReferenceError, "Invalid resolution for #{to_s}: #{token.inspect} is not an integer and cannot be resolved in array #{value.inspect}")
-            end
-            unless (0...(value.respond_to?(:size) ? value : value.to_ary).size).include?(token)
-              raise(ReferenceError, "Invalid resolution for #{to_s}: #{token.inspect} is not a valid index of #{value.inspect}")
-            end
-            (value.respond_to?(:[]) ? value : value.to_ary)[token]
-          elsif value.respond_to?(:to_hash)
-            unless (value.respond_to?(:key?) ? value : value.to_hash).key?(token)
-              raise(ReferenceError, "Invalid resolution for #{to_s}: #{token.inspect} is not a valid key of #{value.inspect}")
-            end
-            (value.respond_to?(:[]) ? value : value.to_hash)[token]
-          else
-            raise(ReferenceError, "Invalid resolution for #{to_s}: #{token.inspect} cannot be resolved in #{value.inspect}")
-          end
-        end
-        res
-      end
-
-      # the pointer string representation of this Pointer
-      def pointer
-        reference_tokens.map { |t| '/' + t.to_s.gsub('~', '~0').gsub('/', '~1') }.join('')
-      end
-
-      # the fragment string representation of this Pointer
-      def fragment
-        '#' + Addressable::URI.escape(pointer)
-      end
-
-      def to_s
-        "#<#{self.class.inspect} #{@type} = #{representation_s}>"
-      end
-
-      private
-
-      def representation_s
-        if @type == :fragment
-          fragment
-        elsif @type == :pointer
-          pointer
-        else
-          reference_tokens.inspect
-        end
-      end
-    end
-  end
-end
-
 # json-schema/validator.rb
 
 module JSON
@@ -177,7 +45,7 @@ module JSON
     def schema_from_fragment(base_schema, fragment)
       schema_uri = base_schema.uri
 
-      pointer = JSON::Schema::Pointer.new(:fragment, fragment)
+      pointer = JSI::JSON::Pointer.from_fragment(fragment)
 
       base_schema = JSON::Schema.new(pointer.evaluate(base_schema.schema), schema_uri, @options[:version])
 

data/lib/jsi/json.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module JSI
   module JSON
     autoload :Node, 'jsi/json/node'
     autoload :ArrayNode, 'jsi/json/node'
     autoload :HashNode, 'jsi/json/node'
+    autoload :Pointer, 'jsi/json/pointer'
   end
 end

data/lib/jsi/json/node.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSI
   module JSON
     # JSI::JSON::Node is an abstraction of a node within a JSON document.
@@ -22,51 +24,45 @@ module JSI
     # return a copy of the document with the content of the node modified.
     # the original node's document and content are untouched.
     class Node
-      def self.new_doc(document)
-        new_by_type(document, [])
+      include Enumerable
+      include PathedNode
+
+      def self.new_doc(node_document)
+        new_by_type(node_document, JSI::JSON::Pointer.new([]))
       end
 
-      # if the content of the document at the given path is Hash-like, returns
+      # if the content of the document at the given pointer is Hash-like, returns
       # a HashNode; if Array-like, returns ArrayNode. otherwise returns a
       # regular Node, although Nodes are for the most part instantiated from
       # Hash or Array-like content.
-      def self.new_by_type(document, path)
-        node = Node.new(document, path)
-        content = node.content
+      def self.new_by_type(node_document, node_ptr)
+        content = node_ptr.evaluate(node_document)
         if content.respond_to?(:to_hash)
-          HashNode.new(document, path)
+          HashNode.new(node_document, node_ptr)
         elsif content.respond_to?(:to_ary)
-          ArrayNode.new(document, path)
+          ArrayNode.new(node_document, node_ptr)
         else
-          node
+          Node.new(node_document, node_ptr)
         end
       end
 
-      # a Node represents the content of a document at a given path.
-      def initialize(document, path)
-        unless path.respond_to?(:to_ary)
-          raise(ArgumentError, "path must be an array. got: #{path.pretty_inspect.chomp} (#{path.class})")
+      # a Node represents the content of a document at a given pointer.
+      def initialize(node_document, node_ptr)
+        unless node_ptr.is_a?(JSI::JSON::Pointer)
+          raise(TypeError, "node_ptr must be a JSI::JSON::Pointer. got: #{node_ptr.pretty_inspect.chomp} (#{node_ptr.class})")
         end
-        if document.is_a?(JSI::JSON::Node)
-          raise(TypeError, "document of a Node should not be another JSI::JSON::Node: #{document.inspect}")
+        if node_document.is_a?(JSI::JSON::Node)
+          raise(TypeError, "node_document of a Node should not be another JSI::JSON::Node: #{node_document.inspect}")
         end
-        @document = document
-        @path = path.to_ary.dup.freeze
-        @pointer = ::JSON::Schema::Pointer.new(:reference_tokens, path)
+        @node_document = node_document
+        @node_ptr = node_ptr
       end
 
-      # the path of this Node within its document
-      attr_reader :path
-      # the document containing this Node at is path
-      attr_reader :document
-      # ::JSON::Schema::Pointer representing the path to this node within its document
-      attr_reader :pointer
+      # the document containing this Node at our pointer
+      attr_reader :node_document
 
-      # the raw content of this Node from the underlying document at this Node's path.
-      def content
-        content = pointer.evaluate(document)
-        content
-      end
+      # JSI::JSON::Pointer pointing to this node within its document
+      attr_reader :node_ptr
 
       # returns content at the given subscript - call this the subcontent.
       #
@@ -78,12 +74,8 @@ module JSI
       # if this node's content is a $ref - that is, a hash with a $ref attribute - and the subscript is
       # not a key of the hash, then the $ref is followed before returning the subcontent.
       def [](subscript)
-        node = self
-        content = node.content
-        if content.respond_to?(:to_hash) && !(content.respond_to?(:key?) ? content : content.to_hash).key?(subscript)
-          node = node.deref
-          content = node.content
-        end
+        ptr = self.node_ptr
+        content = self.node_content
         unless content.respond_to?(:[])
           if content.respond_to?(:to_hash)
             content = content.to_hash
@@ -99,9 +91,9 @@ module JSI
           raise(e.class, e.message + "\nsubscripting with #{subscript.pretty_inspect.chomp} (#{subscript.class}) from #{content.class.inspect}. content is: #{content.pretty_inspect.chomp}", e.backtrace)
         end
         if subcontent.respond_to?(:to_hash)
-          HashNode.new(node.document, node.path + [subscript])
+          HashNode.new(node_document, ptr[subscript])
         elsif subcontent.respond_to?(:to_ary)
-          ArrayNode.new(node.document, node.path + [subscript])
+          ArrayNode.new(node_document, ptr[subscript])
         else
           subcontent
         end
@@ -110,9 +102,9 @@ module JSI
       # assigns the given subscript of the content to the given value. the document is modified in place.
       def []=(subscript, value)
         if value.is_a?(Node)
-          content[subscript] = value.content
+          node_content[subscript] = value.node_content
         else
-          content[subscript] = value
+          node_content[subscript] = value
         end
       end
 
@@ -120,209 +112,92 @@ module JSI
       # does not have a $ref, or if what its $ref cannot be found, this node is returned.
       #
       # currently only $refs pointing within the same document are followed.
-      def deref
-        content = self.content
-
-        if content.respond_to?(:to_hash)
-          ref = (content.respond_to?(:[]) ? content : content.to_hash)['$ref']
-        end
-        return self unless ref.is_a?(String)
-
-        if ref[/\A#/]
-          return self.class.new_by_type(document, ::JSON::Schema::Pointer.parse_fragment(ref)).deref
-        end
-
-        # HAX for how google does refs and ids
-        if document_node['schemas'].respond_to?(:to_hash)
-          if document_node['schemas'][ref]
-            return document_node['schemas'][ref]
-          end
-          _, deref_by_id = document_node['schemas'].detect { |_k, schema| schema['id'] == ref }
-          if deref_by_id
-            return deref_by_id
-          end
+      #
+      # @yield [Node] if a block is given (optional), this will yield a deref'd node. if this
+      #   node is not a $ref object, the block is not called. if we are a $ref which cannot be followed
+      #   (e.g. a $ref to an external document, which is not yet supported), the block is not called.
+      # @return [JSI::JSON::Node] dereferenced node, or this node
+      def deref(&block)
+        node_ptr_deref do |deref_ptr|
+          return Node.new_by_type(node_document, deref_ptr).tap(&(block || Util::NOOP))
         end
-
-        #raise(NotImplementedError, "cannot dereference #{ref}") # TODO
         return self
       end
 
       # a Node at the root of the document
-      def document_node
-        Node.new_doc(document)
+      def document_root_node
+        Node.new_doc(node_document)
       end
 
-      # the parent of this node. if this node is the document root (its path is empty), raises
-      # ::JSON::Schema::Pointer::ReferenceError.
+      # the parent of this node. if this node is the document root, raises
+      # JSI::JSON::Pointer::ReferenceError.
       def parent_node
-        if path.empty?
-          raise(::JSON::Schema::Pointer::ReferenceError, "cannot access parent of root node: #{pretty_inspect.chomp}")
-        else
-          Node.new_by_type(document, path[0...-1])
-        end
-      end
-
-      # the pointer path to this node within the document, per RFC 6901 https://tools.ietf.org/html/rfc6901
-      def pointer_path
-        pointer.pointer
-      end
-
-      # the pointer fragment to this node within the document, per RFC 6901 https://tools.ietf.org/html/rfc6901
-      def fragment
-        pointer.fragment
+        Node.new_by_type(node_document, node_ptr.parent)
       end
 
       # returns a jsonifiable representation of this node's content
       def as_json(*opt)
-        Typelike.as_json(content, *opt)
+        Typelike.as_json(node_content, *opt)
       end
 
       # takes a block. the block is yielded the content of this node. the block MUST return a modified
       # copy of that content (and NOT modify the object it is given).
-      def modified_copy
-        # we need to preserve the rest of the document, but modify the content at our path.
-        #
-        # this is actually a bit tricky. we can't modify the original document, obviously.
-        # we could do a deep copy, but that's expensive. instead, we make a copy of each array
-        # or hash in the path above this node. this node's content is modified by the caller, and
-        # that is recursively merged up to the document root. the recursion is done with a
-        # y combinator, for no other reason than that was a fun way to implement it.
-        modified_document = JSI::Util.ycomb do |rec|
-          proc do |subdocument, subpath|
-            if subpath == []
-              yield(subdocument)
-            else
-              car = subpath[0]
-              cdr = subpath[1..-1]
-              if subdocument.respond_to?(:to_hash)
-                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_hash)[car]
-                car_object = rec.call(subdocument_car, cdr)
-                if car_object.object_id == subdocument_car.object_id
-                  subdocument
-                else
-                  (subdocument.respond_to?(:merge) ? subdocument : subdocument.to_hash).merge({car => car_object})
-                end
-              elsif subdocument.respond_to?(:to_ary)
-                if car.is_a?(String) && car =~ /\A\d+\z/
-                  car = car.to_i
-                end
-                unless car.is_a?(Integer)
-                  raise(TypeError, "bad subscript #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for array: #{subdocument.pretty_inspect.chomp}")
-                end
-                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_ary)[car]
-                car_object = rec.call(subdocument_car, cdr)
-                if car_object.object_id == subdocument_car.object_id
-                  subdocument
-                else
-                  (subdocument.respond_to?(:[]=) ? subdocument : subdocument.to_ary).dup.tap do |arr|
-                    arr[car] = car_object
-                  end
-                end
-              else
-                raise(TypeError, "bad subscript: #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for content: #{subdocument.pretty_inspect.chomp}")
-              end
-            end
-          end
-        end.call(document, path)
-        Node.new_by_type(modified_document, path)
+      def modified_copy(&block)
+        Node.new_by_type(node_ptr.modified_document_copy(node_document, &block), node_ptr)
+      end
+
+      def dup
+        modified_copy(&:dup)
       end
 
       # meta-information about the object, outside the content. used by #inspect / #pretty_print
+      # @return [Array<String>]
       def object_group_text
-        "fragment=#{fragment.inspect}" + (content.respond_to?(:object_group_text) ? ' ' + content.object_group_text : '')
+        [
+          self.class.inspect,
+          node_ptr.uri.to_s,
+        ] + (node_content.respond_to?(:object_group_text) ? node_content.object_group_text : [])
       end
 
       # a string representing this node
       def inspect
-        "\#<#{self.class.inspect} #{object_group_text} #{content.inspect}>"
+        "\#<#{object_group_text.join(' ')} #{node_content.inspect}>"
       end
 
       # pretty-prints a representation this node to the given printer
       def pretty_print(q)
-        q.instance_exec(self) do |obj|
-          text "\#<#{obj.class.inspect} #{obj.object_group_text}"
-          group_sub {
-            nest(2) {
-              breakable ' '
-              pp obj.content
-            }
+        q.text '#<'
+        q.text object_group_text.join(' ')
+        q.group_sub {
+          q.nest(2) {
+            q.breakable ' '
+            q.pp node_content
           }
-          breakable ''
-          text '>'
-        end
+        }
+        q.breakable ''
+        q.text '>'
       end
 
       # fingerprint for equality (see FingerprintHash). two nodes are equal if they are both nodes
       # (regardless of type, e.g. one may be a Node and the other may be a HashNode) within equal
-      # documents at equal paths. note that this means two nodes with the same content may not be
+      # documents at equal pointers. note that this means two nodes with the same content may not be
       # considered equal.
-      def fingerprint
-        {is_node: self.is_a?(JSI::JSON::Node), document: document, path: path}
+      def jsi_fingerprint
+        {class: JSI::JSON::Node, node_document: node_document, node_ptr: node_ptr}
       end
-      include FingerprintHash
+      include Util::FingerprintHash
     end
 
     # a JSI::JSON::Node whose content is Array-like (responds to #to_ary)
     # and includes Array methods from Arraylike
     class ArrayNode < Node
-      # iterates over each element in the same manner as Array#each
-      def each
-        return to_enum(__method__) { (content.respond_to?(:size) ? content : content.to_ary).size } unless block_given?
-        (content.respond_to?(:each_index) ? content : content.to_ary).each_index { |i| yield self[i] }
-        self
-      end
-
-      # the content of this ArrayNode, as an Array
-      def to_ary
-        to_a
-      end
-
-      include Enumerable
-      include Arraylike
-
-      # returns a jsonifiable representation of this node's content
-      def as_json(*opt) # needs redefined after including Enumerable
-        Typelike.as_json(content, *opt)
-      end
-
-      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a).
-      # we override these methods from Arraylike
-      SAFE_INDEX_ONLY_METHODS.each do |method_name|
-        define_method(method_name) { |*a, &b| (content.respond_to?(method_name) ? content : content.to_ary).public_send(method_name, *a, &b) }
-      end
+      include PathedArrayNode
     end
 
     # a JSI::JSON::Node whose content is Hash-like (responds to #to_hash)
     # and includes Hash methods from Hashlike
     class HashNode < Node
-      # iterates over each element in the same manner as Array#each
-      def each(&block)
-        return to_enum(__method__) { content.respond_to?(:size) ? content.size : content.to_ary.size } unless block_given?
-        if block.arity > 1
-          (content.respond_to?(:each_key) ? content : content.to_hash).each_key { |k| yield k, self[k] }
-        else
-          (content.respond_to?(:each_key) ? content : content.to_hash).each_key { |k| yield [k, self[k]] }
-        end
-        self
-      end
-
-      # the content of this HashNode, as a Hash
-      def to_hash
-        inject({}) { |h, (k, v)| h[k] = v; h }
-      end
-
-      include Enumerable
-      include Hashlike
-
-      # returns a jsonifiable representation of this node's content
-      def as_json(*opt) # needs redefined after including Enumerable
-        Typelike.as_json(content, *opt)
-      end
-
-      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
-      SAFE_KEY_ONLY_METHODS.each do |method_name|
-        define_method(method_name) { |*a, &b| (content.respond_to?(method_name) ? content : content.to_hash).public_send(method_name, *a, &b) }
-      end
+      include PathedHashNode
     end
   end
 end