jsi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9899a9ae6a661558974001eba14223c9e497849d3bf3d8e3c6ee9fffd4fcc6d
-  data.tar.gz: 8cfcc01a0167bc251235d7376e793e50bdba92e39f706edbb7bd05386a035352
+  metadata.gz: 4f38a4e48bd546b340af428489a4cb5361ddf0d4b322c598cd56a7d6e69e1949
+  data.tar.gz: 4028ff03d8f935fc5b9f328e1adf9f094dab5621183c0d3b2b6152105b672f5d
 SHA512:
-  metadata.gz: e4ed68443ce9a25db4ddeb18c80f4aea51b4dbb819600afc98c30ab6453ddf8dbc7589079cb7e6743802a31cc4ec53bc32b1da6796a10334e8cc2b6182d37cd4
-  data.tar.gz: 64e8c93a243bc54e0226b8020e20b475c151d349d0b2769bf745b0ba6019f31cf6de63c4edaa36baea89da790814654e92c68154c5a63ade881bef4a18fac133
+  metadata.gz: a7bc8a8ac76c4deaf859681f763e031f570cb04a557549e7b77b42055bea61132792347c2037ceed11c824f7968bda55db0ff69a317c425cf9576335ebc17af3
+  data.tar.gz: 04d7f8d2132c20051f9780b92990d1b0b65b6a5f1fda19572b01effbdfbff22b93c8ffa1267bbaca367279fa8547feaa326d9f861763509a799aff0ecf8dc534

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+# v0.2.0
+
+- JSI::PathedNode unifies interfaces of JSI::Base, JSI::JSON::Node
+- JSI::Base does not (generally) wrap a JSI::JSON::Node
+- some method renames to try to better indicate what a method applies to, and unreserve common names
+  - JSI::Base
+    - #instance -> #jsi_instance
+    - #parents -> #parent_jsis, #parent -> #parent_jsi
+  - JSI::Schema
+    - #fully_validate -> #fully_validate_instance
+    - #validate -> #validate_instance
+    - #validate! -> #validate_instance!
+- improvements to methods which use a modified copy - #dup, #update/#merge
+- #deref on PathedNode classes uses a block form
+- JSI::PathedArrayNode, PathedHashNode
+- JSI::JSON::Pointer refactoring and improvement
+- Schema#new_jsi
+- JSI::SimpleWrap
+- more
+
 # v0.1.0
 
 - JSI::JSON::Pointer replaces monkey-patched-in ::JSON::Schema::Pointer

data/README.md

@@ -3,9 +3,11 @@
 [![Build Status](https://travis-ci.org/notEthan/jsi.svg?branch=master)](https://travis-ci.org/notEthan/jsi)
 [![Coverage Status](https://coveralls.io/repos/github/notEthan/jsi/badge.svg)](https://coveralls.io/github/notEthan/jsi)
 
-JSI represents JSON-schemas as ruby classes, and schema instances as instances of those classes.
+JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby classes which are used to instantiate your JSON data. These classes let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
 
-A JSI class aims to be a fairly unobtrusive wrapper around its instance. It adds accessors for known property names, validation methods, and a few other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
+To learn more about JSON Schema see [https://json-schema.org/]().
+
+A JSI class aims to be a fairly unobtrusive wrapper around its instance - "instance" here meaning the JSON data which instantiate the JSON Schema. The instance is usually a Hash or an Array but may be basic types, or in fact any object. A JSI class adds accessors for property names described by its schema, schema validation, and other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
 
 ## Example
 
@@ -37,10 +39,11 @@ This definition gives you not just the Contact class, but classes for the whole
 
 ```ruby
 bill = Contact.new('name' => 'bill', 'phone' => [{'location' => 'home', 'number' => '555'}], 'nickname' => 'big b')
-# => #{<Contact fragment="#">
-# #{<Contact fragment="#">
-#   "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
-#     #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0"> "location" => "home", "number" => "555"}
+
+# => #{<Contact Hash>
+#   "name" => "bill",
+#   "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
+#     #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash> "location" => "home", "number" => "555"}
 #   ],
 #   "nickname" => "big b"
 # }
@@ -75,15 +78,15 @@ bill.validate
 
 ```ruby
 bad = Contact.new('phone' => [{'number' => [5, 5, 5]}])
-# => #{<Contact fragment="#">
-#   "phone" => #[<JSI::SchemaClasses["1f97#/properties/phone"] fragment="#/phone">
-#     #{<JSI::SchemaClasses["1f97#/properties/phone/items"] fragment="#/phone/0">
-#       "number" => #[<JSI::SchemaClasses["1f97#/properties/phone/items/properties/number"] fragment="#/phone/0/number"> 5, 5, 5]
+# => #{<Contact Hash>
+#   "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
+#     #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash>
+#       "number" => #[<JSI::SchemaClasses["23d8#/properties/phone/items/properties/number"] Array> 5, 5, 5]
 #     }
 #   ]
 # }
 bad.phone.fully_validate
-# => ["The property '#/0/number' of type array did not match the following type: string in schema 1f97"]
+# => ["The property '#/0/number' of type array did not match the following type: string in schema 23d8"]
 ```
 
 These validations are done by the [`json-schema` gem](https://github.com/ruby-json-schema/json-schema) - JSI does not do validations on its own.
@@ -101,12 +104,12 @@ There's plenty more JSI has to offer, but this should give you a pretty good ide
 
 ## Terminology and Concepts
 
-- JSI::Base is the base class from which other classes representing JSON-Schemas inherit.
-- a JSI class refers to a class representing a schema, a subclass of JSI::Base.
+- `JSI::Base` is the base class for each JSI class representing a JSON Schema.
+- a "JSI class" is a subclass of `JSI::Base` representing a JSON schema.
 - "instance" is a term that is significantly overloaded in this space, so documentation will attempt to be clear what kind of instance is meant:
-  - a schema instance refers broadly to a data structure that is described by a json-schema.
+  - a schema instance refers broadly to a data structure that is described by a JSON schema.
   - a JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
-- a schema refers to a json-schema. a JSI::Schema represents such a json-schema. a JSI class allows instantiation of such a schema.
+- a schema refers to a JSON schema. a `JSI::Schema` represents such a schema. a JSI class allows instantiation of a schema as a JSI instance.
 
 ## JSI classes
 

data/jsi.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name    = "jsi"
   spec.version = JSI::VERSION
   spec.authors = ["Ethan"]
-  spec.email   = ["ethan@unth"]
+  spec.email   = ["ethan@unth.net"]
 
   spec.summary     = "JSI: JSON-Schema instantiation"
   spec.description = "JSI represents json-schemas as ruby classes and json-schema instances as instances of those classes"

data/lib/jsi.rb

@@ -1,5 +1,6 @@
 require "jsi/version"
 require "pp"
+require "set"
 require "jsi/json-schema-fragments"
 require "jsi/util"
 
@@ -10,6 +11,7 @@ module JSI
   end
 
   autoload :JSON, 'jsi/json'
+  autoload :PathedNode, 'jsi/pathed_node'
   autoload :Typelike, 'jsi/typelike_modules'
   autoload :Hashlike, 'jsi/typelike_modules'
   autoload :Arraylike, 'jsi/typelike_modules'
@@ -17,9 +19,11 @@ module JSI
   autoload :Base, 'jsi/base'
   autoload :BaseArray, 'jsi/base'
   autoload :BaseHash, 'jsi/base'
-  autoload :SchemaClasses, 'jsi/base'
+  autoload :SchemaClasses, 'jsi/schema_classes'
   autoload :JSICoder, 'jsi/jsi_coder'
 
+  autoload :SimpleWrap, 'jsi/simple_wrap'
+
   # @return [Class subclassing JSI::Base] a JSI class which represents the
   #   given schema. instances of the class represent JSON Schema instances
   #   for the given schema.

data/lib/jsi/base.rb

@@ -13,8 +13,11 @@ module JSI
   class Base
     include Memoize
     include Enumerable
+    include PathedNode
 
     class << self
+      # is the constant JSI::SchemaClasses::{self.schema_classes_const_name} defined?
+      # (if so, we will prefer to use something more human-readable than that ugly mess.)
       attr_accessor :in_schema_classes
 
       # @return [String] absolute schema_id of the schema this class represents.
@@ -53,7 +56,7 @@ module JSI
       #   schema_id. only used if the class is not assigned to another constant.
       def schema_classes_const_name
         name = schema.schema_id.gsub(/[^\w]/, '_')
-        name = 'X' + name unless name[/\A[a-zA-Z_]/]
+        name = 'X' + name unless name[/\A[a-zA-Z]/]
         name = name[0].upcase + name[1..-1]
         name
       end
@@ -68,33 +71,85 @@ module JSI
       end
     end
 
-    # initializes this JSI from the given instance. the instance will be
-    # wrapped as a {JSI::JSON::Node JSI::JSON::Node} (unless what you pass is
-    # a Node already).
+    # NOINSTANCE is a magic value passed to #initialize when instantiating a JSI
+    # from a document and JSON Pointer.
+    NOINSTANCE = Object.new.tap { |o| [:inspect, :to_s].each(&(-> (s, m) { o.define_singleton_method(m) { s } }.curry.([JSI::Base.name, 'NOINSTANCE'].join('::')))) }
+
+    # initializes this JSI from the given instance - instance is most commonly
+    # a parsed JSON document consisting of Hash, Array, or sometimes a basic
+    # type, but this is in no way enforced and a JSI may wrap any object.
     #
     # @param instance [Object] the JSON Schema instance being represented
-    # @param ancestor [JSI::Base] for internal use, specifies an ancestor
+    # @param jsi_document [Object] for internal use. the instance may be specified as a
+    #   node in the `jsi_document` param, pointed to by `jsi_ptr`. the param `instance`
+    #   MUST be `NOINSTANCE` to use the jsi_document + jsi_ptr form. `jsi_document` MUST
+    #   NOT be passed if `instance` is anything other than `NOINSTANCE`.
+    # @param jsi_ptr [JSI::JSON::Pointer] for internal use. a JSON pointer specifying
+    #   the path of this instance in the `jsi_document` param. `jsi_ptr` must be passed
+    #   iff `jsi_document` is passed, i.e. when `instance` is `NOINSTANCE`
+    # @param ancestor_jsi [JSI::Base] for internal use, specifies an ancestor_jsi
     #   from which this JSI originated to calculate #parents
-    def initialize(instance, ancestor: nil)
+    def initialize(instance, jsi_document: nil, jsi_ptr: nil, ancestor_jsi: nil)
       unless respond_to?(:schema)
         raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #schema. please use JSI.class_for_schema")
       end
 
-      @ancestor = ancestor || self
-      self.instance = instance
+      if instance.is_a?(JSI::Base)
+        raise(TypeError, "assigning another JSI::Base instance to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      elsif instance.is_a?(JSI::Schema)
+        raise(TypeError, "assigning a schema to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      end
+
+      if instance == NOINSTANCE
+        @jsi_document = jsi_document
+        unless jsi_ptr.is_a?(JSI::JSON::Pointer)
+          raise(TypeError, "jsi_ptr must be a JSI::JSON::Pointer; got: #{jsi_ptr.inspect}")
+        end
+        @jsi_ptr = jsi_ptr
+      else
+        raise(Bug, 'incorrect usage') if jsi_document || jsi_ptr || ancestor_jsi
+        if instance.is_a?(PathedNode)
+          @jsi_document = instance.document_root_node
+          # this can result in the unusual situation where ancestor_jsi is nil, though jsi_ptr is not root.
+          # #document_root_node will then return a JSI::JSON::Pointer instead of a root JSI.
+          @jsi_ptr = instance.node_ptr
+        else
+          @jsi_document = instance
+          @jsi_ptr = JSI::JSON::Pointer.new([])
+        end
+      end
+      if ancestor_jsi
+        if !ancestor_jsi.is_a?(JSI::Base)
+          raise(TypeError, "ancestor_jsi must be a JSI::Base; got: #{ancestor_jsi.inspect}")
+        end
+        if !ancestor_jsi.jsi_ptr.contains?(@jsi_ptr)
+          raise(Bug, "ancestor_jsi ptr #{ancestor_jsi.jsi_ptr.inspect} is not ancestor of #{@jsi_ptr.inspect}")
+        end
+      end
+      @ancestor_jsi = ancestor_jsi
 
-      if @instance.is_a?(JSI::JSON::HashNode)
+      if self.jsi_instance.respond_to?(:to_hash)
         extend BaseHash
-      elsif @instance.is_a?(JSI::JSON::ArrayNode)
+      elsif self.jsi_instance.respond_to?(:to_ary)
         extend BaseArray
       end
     end
 
-    # the instance of the json-schema. this is a JSI::JSON::Node.
-    attr_reader :instance
+    # document containing the instance of this JSI
+    attr_reader :jsi_document
+
+    # JSI::JSON::Pointer pointing to this JSI's instance within the jsi_document
+    attr_reader :jsi_ptr
 
-    # a JSI which is an ancestor of this
-    attr_reader :ancestor
+    # a JSI which is an ancestor_jsi of this
+    attr_reader :ancestor_jsi
+
+    alias_method :node_document, :jsi_document
+    alias_method :node_ptr, :jsi_ptr
+
+    # the instance of the json-schema
+    alias_method :jsi_instance, :node_content
+    alias_method :instance, :node_content
 
     # each is overridden by BaseHash or BaseArray when appropriate. the base
     # #each is not actually implemented, along with all the methods of Enumerable.
@@ -103,37 +158,93 @@ module JSI
     end
 
     # an array of JSI instances above this one in the document. empty if this
-    # JSI is at the root or was instantiated from a source that does not have
-    # a document (e.g. a plain hash or array).
+    # JSI does not have a known ancestor.
     #
     # @return [Array<JSI::Base>]
-    def parents
-      parent = @ancestor
-      (@ancestor.instance.path.size...self.instance.path.size).map do |i|
-        parent.tap do
-          parent = parent[self.instance.path[i]]
+    def parent_jsis
+      ancestor_jsi = @ancestor_jsi || self
+      parent = ancestor_jsi
+
+      (ancestor_jsi.jsi_ptr.reference_tokens.size...self.jsi_ptr.reference_tokens.size).map do |i|
+        current = parent
+        parent = parent[self.jsi_ptr.reference_tokens[i]]
+        if current.is_a?(JSI::Base)
+          current
+        else
+          # sometimes after a deref, we may end up with parents whose schema we do not know.
+          # TODO this is kinda crap; hopefully we can remove it along with deref instantiating
+          # a deref ptr as the same JSI class it is
+          SimpleWrap.new(NOINSTANCE, jsi_document: jsi_document, jsi_ptr: jsi_ptr.take(i), ancestor_jsi: @ancestor_jsi)
         end
       end.reverse
     end
 
-    # the immediate parent of this JSI. nil if no parent(s) are known.
+    # the immediate parent of this JSI. nil if there is no parent.
     #
     # @return [JSI::Base, nil]
-    def parent
-      parents.first
+    def parent_jsi
+      parent_jsis.first
+    end
+
+    # @return [JSI::PathedNode] a pathed node at the root of the document. this is generally a JSI::Base
+    #   but may be a JSI::JSON::Node in unusual circumstances.
+    def document_root_node
+      if @jsi_ptr.root?
+        self
+      elsif @ancestor_jsi
+        @ancestor_jsi.document_root_node
+      elsif instance.is_a?(PathedNode)
+        instance.document_root_node
+      else
+        JSI::JSON::Node.new_doc(@jsi_document)
+      end
     end
 
+    # @return [JSI::PathedNode]
+    def parent_node
+      if @jsi_ptr.root?
+        nil
+      elsif @ancestor_jsi
+        parent_jsis.first.tap do |parent_node|
+          raise(Bug, 'is @ancestor_jsi == self? it should not be') if parent_node.nil?
+          raise(Bug, "parent_node not PathedNode: #{parent_node.pretty_inspect.chomp}") unless parent_node.is_a?(JSI::PathedNode)
+        end
+      elsif instance.is_a?(PathedNode)
+        instance.parent_node
+      else
+        JSI::JSON::Node.new_by_type(@jsi_document, @jsi_ptr.parent)
+      end
+    end
+
+    # @deprecated
+    alias_method :parents, :parent_jsis
+    # @deprecated
+    alias_method :parent, :parent_jsi
+
     # if this JSI is a $ref then the $ref is followed. otherwise this JSI
     # is returned.
     #
+    # @yield [JSI::Base] if a block is given (optional), this will yield a deref'd JSI. if this
+    #   JSI 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::Base, self]
-    def deref
-      derefed = instance.deref
-      if derefed.object_id == instance.object_id
-        self
-      else
-        self.class.new(derefed, ancestor: @ancestor)
+    def deref(&block)
+      node_ptr_deref do |deref_ptr|
+        jsi_from_root = deref_ptr.evaluate(document_root_node)
+        if jsi_from_root.is_a?(JSI::Base)
+          return jsi_from_root.tap(&(block || Util::NOOP))
+        else
+          # TODO I want to get rid of this ... just return jsi_from_root whatever it is
+          # NOTE when I get rid of this, simplify #parent_jsis too
+          if @ancestor_jsi && @ancestor_jsi.jsi_ptr.contains?(deref_ptr)
+            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr, ancestor_jsi: @ancestor_jsi)
+          else
+            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr)
+          end
+          return derefed.tap(&(block || Util::NOOP))
+        end
       end
+      return self
     end
 
     # yields the content of the underlying instance. the block must result in
@@ -144,22 +255,33 @@ module JSI
     #   in a (nondestructively) modified copy of this.
     # @return [JSI::Base subclass the same as self] the modified copy of self
     def modified_copy(&block)
-      modified_instance = instance.modified_copy(&block)
-      self.class.new(modified_instance, ancestor: @ancestor)
+      if @ancestor_jsi
+        raise(Bug, 'bad @ancestor_jsi') if @ancestor_jsi.object_id == self.object_id
+
+        modified_ancestor = @ancestor_jsi.modified_copy do |anc|
+          mod_anc = @jsi_ptr.ptr_relative_to(@ancestor_jsi.jsi_ptr).modified_document_copy(anc, &block)
+          mod_anc
+        end
+        self.class.new(Base::NOINSTANCE, jsi_document: modified_ancestor.jsi_document, jsi_ptr: @jsi_ptr, ancestor_jsi: modified_ancestor)
+      else
+        modified_document = @jsi_ptr.modified_document_copy(@jsi_document, &block)
+        self.class.new(Base::NOINSTANCE, jsi_document: modified_document, jsi_ptr: @jsi_ptr)
+      end
     end
 
+    # @return [String] the fragment representation of a pointer to this JSI's instance within its document
     def fragment
-      instance.fragment
+      @jsi_ptr.fragment
     end
 
     # @return [Array<String>] array of schema validation error messages for this instance
     def fully_validate
-      schema.fully_validate(instance)
+      schema.fully_validate_instance(instance)
     end
 
     # @return [true, false] whether the instance validates against its schema
     def validate
-      schema.validate(instance)
+      schema.validate_instance(instance)
     end
 
     # @return [true] if this method does not raise, it returns true to
@@ -167,7 +289,11 @@ module JSI
     # @raise [::JSON::Schema::ValidationError] raises if the instance has
     #   validation errors
     def validate!
-      schema.validate!(instance)
+      schema.validate_instance!(instance)
+    end
+
+    def dup
+      modified_copy(&:dup)
     end
 
     # @return [String] a string representing this JSI, indicating its class
@@ -194,7 +320,7 @@ module JSI
 
     # @return [String] the instance's object_group_text
     def object_group_text
-      instance.object_group_text
+      instance.respond_to?(:object_group_text) ? instance.object_group_text : instance.class.inspect
     end
 
     # @return [Object] a jsonifiable representation of the instance
@@ -202,35 +328,20 @@ module JSI
       Typelike.as_json(instance, *opt)
     end
 
-    # @return [Object] an opaque fingerprint of this JSI for FingerprintHash
+    # @return [Object] an opaque fingerprint of this JSI for FingerprintHash. JSIs are equal
+    #   if their instances are equal, and if the JSIs are of the same JSI class or subclass.
     def fingerprint
-      {class: self.class, instance: instance}
+      {class: jsi_class, jsi_document: jsi_document, jsi_ptr: jsi_ptr}
     end
     include FingerprintHash
 
     private
 
-    # assigns @instance to the given thing, raising if the thing is not appropriate for a JSI instance
-    # @param thing [Object] a JSON schema instance for this class's schema
-    def instance=(thing)
-      if instance_variable_defined?(:@instance)
-        raise(JSI::Bug, "overwriting instance is not supported")
-      end
-      if thing.is_a?(Base)
-        warn "assigning instance to a Base instance is incorrect. received: #{thing.pretty_inspect.chomp}"
-        @instance = thing.instance
-      elsif thing.is_a?(JSI::JSON::Node)
-        @instance = thing
-      else
-        @instance = JSI::JSON::Node.new_doc(thing)
-      end
-    end
-
-    # assigns a subscript, taking care of memoization and unwrapping a JSI if given.
+    # assigns a subscript, unwrapping a JSI if given.
     # @param subscript [Object] the bit between the [ and ]
     # @param value [JSI::Base, Object] the value to be assigned
     def subscript_assign(subscript, value)
-      clear_memo(:[], subscript)
+      clear_memo(:[])
       if value.is_a?(Base)
         instance[subscript] = value.instance
       else
@@ -245,145 +356,44 @@ module JSI
     end
   end
 
-  # this module is just a namespace for schema classes.
-  module SchemaClasses
-    extend Memoize
-
-    # JSI::SchemaClasses[schema_id] returns a class for the schema with the
-    # given id, the same class as returned from JSI.class_for_schema.
-    #
-    # @param schema_id [String] absolute schema id as returned by {JSI::Schema#schema_id}
-    # @return [Class subclassing JSI::Base] the class for that schema
-    def self.[](schema_id)
-      @classes_by_id[schema_id]
-    end
-    @classes_by_id = {}
-  end
-
-  # see {JSI.class_for_schema}
-  def SchemaClasses.class_for_schema(schema_object)
-    memoize(:class_for_schema, JSI::Schema.from_object(schema_object)) do |schema_|
-      begin
-        begin
-          Class.new(Base).instance_exec(schema_) do |schema|
-            begin
-              include(JSI::SchemaClasses.module_for_schema(schema))
-
-              SchemaClasses.instance_exec(self) { |klass| @classes_by_id[klass.schema_id] = klass }
-
-              self
-            end
-          end
-        end
-      end
-    end
-  end
-
-  # a module for the given schema, with accessor methods for any object
-  # property names the schema identifies. also has class and instance
-  # methods called #schema to access the {JSI::Schema} this module
-  # represents.
-  #
-  # accessor methods are defined on these modules so that methods can be
-  # defined on {JSI.class_for_schema} classes without method redefinition
-  # warnings. additionally, these overriding instance methods can call
-  # `super` to invoke the normal accessor behavior.
-  #
-  # no property names that are the same as existing method names on the JSI
-  # class will be defined. users should use #[] and #[]= to access properties
-  # whose names conflict with existing methods.
-  def SchemaClasses.module_for_schema(schema_object)
-    memoize(:module_for_schema, JSI::Schema.from_object(schema_object)) do |schema_|
-      Module.new.tap do |m|
-        m.instance_exec(schema_) do |schema|
-          define_method(:schema) { schema }
-          define_singleton_method(:schema) { schema }
-          define_singleton_method(:included) do |includer|
-            includer.send(:define_singleton_method, :schema) { schema }
-          end
-
-          define_singleton_method(:schema_id) do
-            schema.schema_id
-          end
-          define_singleton_method(:inspect) do
-            %Q(#<Module for Schema: #{schema_id}>)
-          end
-
-          instance_method_modules = [m, Base, BaseArray, BaseHash]
-          instance_methods = instance_method_modules.map do |mod|
-            mod.instance_methods + mod.private_instance_methods
-          end.inject(Set.new, &:|)
-          accessors_to_define = schema.described_object_property_names.map(&:to_s) - instance_methods.map(&:to_s)
-          accessors_to_define.each do |property_name|
-            define_method(property_name) do
-              if respond_to?(:[])
-                self[property_name]
-              else
-                raise(NoMethodError, "instance does not respond to []; cannot call reader `#{property_name}' for: #{pretty_inspect.chomp}")
-              end
-            end
-            define_method("#{property_name}=") do |value|
-              if respond_to?(:[]=)
-                self[property_name] = value
-              else
-                raise(NoMethodError, "instance does not respond to []=; cannot call writer `#{property_name}=' for: #{pretty_inspect.chomp}")
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-
-  # module extending a {JSI::Base} object when its schema instance is Hash-like (responds to #to_hash)
+  # module extending a {JSI::Base} object when its instance is Hash-like (responds to #to_hash)
   module BaseHash
-    # yields each key and value of this JSI.
-    # each yielded key is the same as a key of the instance, and each yielded
-    # value is the result of self[key] (see #[]).
-    # returns an Enumerator if no block is given.
-    # @yield [Object, Object] each key and value of this JSI hash
-    # @return [self, Enumerator]
-    def each
-      return to_enum(__method__) { instance.size } unless block_given?
-      instance.each_key { |k| yield(k, self[k]) }
-      self
-    end
-
-    # @return [Hash] a hash in which each key is a key of the instance hash and
-    #   each value is the result of self[key] (see #[]).
-    def to_hash
-      inject({}) { |h, (k, v)| h[k] = v; h }
-    end
-
-    include Hashlike
+    include PathedHashNode
 
-    # 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| instance.public_send(method_name, *a, &b) }
-    end
+    alias_method :jsi_instance_hash_pubsend, :node_content_hash_pubsend
 
+    # @param property_name [String, Object] the property name to subscript
     # @return [JSI::Base, Object] the instance's subscript value at the given
     #   key property_name_. if there is a subschema defined for that property
     #   on this JSI's schema, returns the instance's subscript as a JSI
     #   instiation of that subschema.
-    def [](property_name_)
-      memoize(:[], property_name_) do |property_name|
+    def [](property_name)
+      instance_property_key_ = jsi_instance_hash_pubsend(:key?, property_name)
+      if !instance_property_key_
+        deref do |deref_jsi|
+          return deref_jsi[property_name]
+        end
+      end
+      instance_property_value_ = jsi_instance_sub(property_name)
+      memoize(:[], property_name, instance_property_value_, instance_property_key_) do |property_name_, instance_property_value, instance_property_key|
         begin
-          property_schema = schema.subschema_for_property(property_name)
-          property_schema = property_schema && property_schema.match_to_instance(instance[property_name])
+          property_schema = schema.subschema_for_property(property_name_)
+          property_schema = property_schema && property_schema.match_to_instance(instance_property_value)
 
-          if !instance.key?(property_name) && property_schema && property_schema.schema_object.key?('default')
+          if !instance_property_key && property_schema && property_schema.schema_object.key?('default')
             # use the default value
             default = property_schema.schema_object['default']
             if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              class_for_schema(property_schema).new(default, ancestor: @ancestor)
+              # we are using #dup so that we get a modified copy of self, in which we set dup[property_name_]=default.
+              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
+              dup.tap { |o| o[property_name_] = default }[property_name_]
             else
               default
             end
-          elsif property_schema && (instance[property_name].respond_to?(:to_hash) || instance[property_name].respond_to?(:to_ary))
-            class_for_schema(property_schema).new(instance[property_name], ancestor: @ancestor)
+          elsif property_schema && (instance_property_value.respond_to?(:to_hash) || instance_property_value.respond_to?(:to_ary))
+            class_for_schema(property_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[property_name_], ancestor_jsi: @ancestor_jsi || self)
           else
-            instance[property_name]
+            instance_property_value
           end
         end
       end
@@ -398,57 +408,46 @@ module JSI
     def []=(property_name, value)
       subscript_assign(property_name, value)
     end
-  end
 
-  # module extending a {JSI::Base} object when its schema instance is Array-like (responds to #to_ary)
-  module BaseArray
-    # yields each element. each yielded element is the result of self[index]
-    # for each index of the instance (see #[]).
-    # returns an Enumerator if no block is given.
-    # @yield [Object] each element of this JSI array
-    # @return [self, Enumerator]
-    def each
-      return to_enum(__method__) { instance.size } unless block_given?
-      instance.each_index { |i| yield(self[i]) }
-      self
-    end
+    private
 
-    # @return [Array] an array, the same size as the instance, in which the
-    #   element at each index is the result of self[index] (see #[])
-    def to_ary
-      to_a
+    # @param token [String, Object]
+    # @return [Object]
+    def jsi_instance_sub(token)
+      jsi_instance_hash_pubsend(:[], token)
     end
+  end
 
-    include Arraylike
+  # module extending a {JSI::Base} object when its instance is Array-like (responds to #to_ary)
+  module BaseArray
+    include PathedArrayNode
 
-    # 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| instance.public_send(method_name, *a, &b) }
-    end
+    alias_method :jsi_instance_ary_pubsend, :node_content_ary_pubsend
 
-    # @return [Object] returns the instance's subscript value at the given index
-    #   i_. if there is a subschema defined for that index on this JSI's schema,
+    # @param i [Integer] the array index to subscript
+    # @return [JSI::Base, Object] the instance's subscript value at the given index
+    #   i. if there is a subschema defined for that index on this JSI's schema,
     #   returns the instance's subscript as a JSI instiation of that subschema.
-    # @param i_ the array index to subscript
-    def [](i_)
-      memoize(:[], i_) do |i|
+    def [](i)
+      memoize(:[], i, jsi_instance_sub(i), jsi_instance_ary_pubsend(:each_index).to_a.include?(i)) do |i_, instance_idx_value, i_in_range|
         begin
-          index_schema = schema.subschema_for_index(i)
-          index_schema = index_schema && index_schema.match_to_instance(instance[i])
+          index_schema = schema.subschema_for_index(i_)
+          index_schema = index_schema && index_schema.match_to_instance(instance_idx_value)
 
-          if !instance.each_index.to_a.include?(i) && index_schema && index_schema.schema_object.key?('default')
+          if !i_in_range && index_schema && index_schema.schema_object.key?('default')
             # use the default value
             default = index_schema.schema_object['default']
             if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              class_for_schema(index_schema).new(default, ancestor: @ancestor)
+              # we are using #dup so that we get a modified copy of self, in which we set dup[i]=default.
+              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
+              dup.tap { |o| o[i_] = default }[i_]
             else
               default
             end
-          elsif index_schema && (instance[i].respond_to?(:to_hash) || instance[i].respond_to?(:to_ary))
-            class_for_schema(index_schema).new(instance[i], ancestor: @ancestor)
+          elsif index_schema && (instance_idx_value.respond_to?(:to_hash) || instance_idx_value.respond_to?(:to_ary))
+            class_for_schema(index_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[i_], ancestor_jsi: @ancestor_jsi || self)
           else
-            instance[i]
+            instance_idx_value
           end
         end
       end
@@ -461,5 +460,13 @@ module JSI
     def []=(i, value)
       subscript_assign(i, value)
     end
+
+    private
+
+    # @param token [Integer]
+    # @return [Object]
+    def jsi_instance_sub(token)
+      jsi_instance_ary_pubsend(:[], token)
+    end
   end
 end