jsi 0.7.0 → 0.8.0

data/lib/jsi/base.rb

@@ -1,40 +1,35 @@
 # frozen_string_literal: true
 
 module JSI
-  # JSI::Base is the base class of every JSI instance of a JSON schema.
+  # A JSI::Base instance represents a node in a JSON document (its {#jsi_document}) at a particular
+  # location (its {#jsi_ptr}), described by any number of JSON Schemas (its {#jsi_schemas}).
   #
-  # instances are described by a set of one or more JSON schemas. JSI dynamically creates a subclass of
-  # JSI::Base for each set of JSON schemas which describe an instance that is to be instantiated.
+  # JSI::Base is an abstract base class. The subclasses used to instantiate JSIs are dynamically created as
+  # needed for a given instance.
   #
-  # a JSI instance of such a subclass represents a JSON schema instance described by that set of schemas.
+  # These subclasses are generally intended to be ignored by applications using this library - the purpose
+  # they serve is to include modules relevant to the instance. The modules these classes include are:
   #
-  # this subclass includes the JSI Schema Module of each schema it represents.
-  #
-  # the method {Base#jsi_schemas} is defined to indicate the schemas the class represents.
-  #
-  # the JSI::Base class itself is not intended to be instantiated.
+  # - the {Schema#jsi_schema_module} of each schema which describes the instance
+  # - {Base::HashNode}, {Base::ArrayNode}, or {Base::StringNode} if the instance is
+  #   a hash/object, array, or string
+  # - Modules defining accessor methods for property names described by the schemas
   class Base
     autoload :ArrayNode, 'jsi/base/node'
     autoload :HashNode, 'jsi/base/node'
+    autoload :StringNode, 'jsi/base/node'
+    autoload(:Mutable, 'jsi/base/mutability')
+    autoload(:Immutable, 'jsi/base/mutability')
 
     include Schema::SchemaAncestorNode
-    include Util::Memoize
 
-    # an exception raised when {Base#[]} is invoked on an instance which is not an array or hash
-    class CannotSubscriptError < StandardError
+    # An exception raised when attempting to access a child of a node which cannot have children.
+    # A complex node can have children, a simple node cannot.
+    class SimpleNodeChildError < StandardError
     end
 
     class << self
-      # @private
-      # 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.)
-      def in_schema_classes
-        # #name sets @in_schema_classes
-        name
-        @in_schema_classes
-      end
-
-      # a string indicating a class name if one is defined, as well as the schema module name
+      # A string indicating the schema module name
       # and/or schema URI of each schema the class represents.
       # @return [String]
       def inspect
@@ -42,11 +37,11 @@ module JSI
           super
         else
           schema_names = jsi_class_schemas.map do |schema|
-            mod = schema.jsi_schema_module
-            if mod.name && schema.schema_uri
-              "#{mod.name} (#{schema.schema_uri})"
-            elsif mod.name
-              mod.name
+            mod_name = schema.jsi_schema_module.name_from_ancestor
+            if mod_name && schema.schema_absolute_uri
+              "#{mod_name} <#{schema.schema_absolute_uri}>"
+            elsif mod_name
+              mod_name
             elsif schema.schema_uri
               schema.schema_uri.to_s
             else
@@ -54,61 +49,51 @@ module JSI
             end
           end
 
-          if name && !in_schema_classes
-            if jsi_class_schemas.empty?
-              "#{name} (0 schemas)"
-            else
-              "#{name} (#{schema_names.join(', ')})"
-            end
+          if schema_names.empty?
+            "(JSI Schema Class for 0 schemas#{jsi_class_includes.map { |n| " + #{n}" }})"
           else
-            if schema_names.empty?
-              "(JSI Schema Class for 0 schemas)"
-            else
-              "(JSI Schema Class: #{schema_names.join(', ')})"
-            end
+            -"(JSI Schema Class: #{(schema_names + jsi_class_includes.map(&:name)).join(' + ')})"
           end
         end
       end
 
-      alias_method :to_s, :inspect
-
-      # @private
-      # see {.name}
-      def schema_classes_const_name
-        if respond_to?(:jsi_class_schemas)
-          schema_names = jsi_class_schemas.map do |schema|
-            named_ancestor_schema, tokens = schema.jsi_schema_module.send(:named_ancestor_schema_tokens)
-            if named_ancestor_schema
-              [named_ancestor_schema.jsi_schema_module.name, *tokens].join('_')
-            elsif schema.schema_uri
-              schema.schema_uri.to_s
-            else
-              nil
-            end
-          end
-          if !schema_names.any?(&:nil?) && !schema_names.empty?
-            schema_names.sort.map { |n| 'X' + n.to_s.gsub(/[^\w]/, '_') }.join('')
-          end
-        end
+      def to_s
+        inspect
       end
 
-      # a constant name of this class. this is generated from the schema module name or URI of each schema
-      # this class represents. nil if any represented schema has no schema module name or schema URI.
+      # A constant name of this class. This is generated from any schema module name or URI of each schema
+      # this class represents, or random characters.
       #
       # this generated name is not too pretty but can be more helpful than an anonymous class, especially
       # in error messages.
       #
       # @return [String]
       def name
-        unless instance_variable_defined?(:@in_schema_classes)
-          const_name = schema_classes_const_name
-          if super || !const_name || SchemaClasses.const_defined?(const_name)
-            @in_schema_classes = false
+        return super if instance_variable_defined?(:@tried_to_name)
+        @tried_to_name = true
+        return super unless respond_to?(:jsi_class_schemas)
+        alnum = proc { |id| (id % 36**4).to_s(36).rjust(4, '0').upcase }
+        schema_names = jsi_class_schemas.map do |schema|
+          named_ancestor_schema, tokens = schema.jsi_schema_module.send(:named_ancestor_schema_tokens)
+          if named_ancestor_schema
+            [named_ancestor_schema.jsi_schema_module.name, *tokens].join('_')
+          elsif schema.schema_uri
+            schema.schema_uri.to_s
           else
-            SchemaClasses.const_set(const_name, self)
-            @in_schema_classes = true
+            [alnum[schema.jsi_root_node.__id__], *schema.jsi_ptr.tokens].join('_')
           end
         end
+        includes_names = jsi_class_includes.map { |m| m.name.sub(/\AJSI::Base::/, '').gsub(Util::RUBY_REJECT_NAME_RE, '_') }
+        if schema_names.any?
+          parts = schema_names.compact.sort.map { |n| 'X' + n.to_s }
+          parts += includes_names
+          const_name = Util.const_name_from_parts(parts, join: '__')
+          const_name += "__" + alnum[__id__] if SchemaClasses.const_defined?(const_name)
+        else
+          const_name = (['X' + alnum[__id__]] + includes_names).join('__')
+        end
+        # collisions are technically possible though vanishingly unlikely
+        SchemaClasses.const_set(const_name, self) unless SchemaClasses.const_defined?(const_name)
         super
       end
     end
@@ -117,37 +102,46 @@ module JSI
     #
     # this is a private api - users should look elsewhere to instantiate JSIs, in particular:
     #
-    # - {JSI.new_schema} and {Schema::DescribesSchema#new_schema} to instantiate schemas
+    # - {JSI.new_schema} and {Schema::MetaSchema#new_schema} to instantiate schemas
     # - {Schema#new_jsi} to instantiate schema instances
     #
     # @api private
     # @param jsi_document [Object] the document containing the instance
     # @param jsi_ptr [JSI::Ptr] a pointer pointing to the JSI's instance in the document
-    # @param jsi_root_node [JSI::Base] the JSI of the root of the document containing this JSI
     # @param jsi_schema_base_uri [Addressable::URI] see {SchemaSet#new_jsi} param uri
-    # @param jsi_schema_resource_ancestors [Array<JSI::Base<JSI::Schema>>]
+    # @param jsi_schema_resource_ancestors [Array<JSI::Base + JSI::Schema>]
+    # @param jsi_root_node [JSI::Base] the JSI of the root of the document containing this JSI
     def initialize(jsi_document,
         jsi_ptr: Ptr[],
-        jsi_root_node: nil,
+        jsi_indicated_schemas: ,
         jsi_schema_base_uri: nil,
-        jsi_schema_resource_ancestors: Util::EMPTY_ARY
+        jsi_schema_resource_ancestors: Util::EMPTY_ARY,
+        jsi_schema_registry: ,
+        jsi_content_to_immutable: ,
+        jsi_root_node: nil
     )
-      raise(Bug, "no #jsi_schemas") unless respond_to?(:jsi_schemas)
-
-      jsi_initialize_memos
+      #chkbug raise(Bug, "no #jsi_schemas") unless respond_to?(:jsi_schemas)
 
       self.jsi_document = jsi_document
       self.jsi_ptr = jsi_ptr
+      self.jsi_indicated_schemas = jsi_indicated_schemas
+      self.jsi_schema_base_uri = jsi_schema_base_uri
+      self.jsi_schema_resource_ancestors = jsi_schema_resource_ancestors
+      self.jsi_schema_registry = jsi_schema_registry
+      @jsi_content_to_immutable = jsi_content_to_immutable
       if @jsi_ptr.root?
-        raise(Bug, "jsi_root_node specified for root JSI") if jsi_root_node
+        #chkbug raise(Bug, "jsi_root_node specified for root JSI") if jsi_root_node
         @jsi_root_node = self
       else
-        raise(Bug, "jsi_root_node is not JSI::Base") if !jsi_root_node.is_a?(JSI::Base)
-        raise(Bug, "jsi_root_node ptr is not root") if !jsi_root_node.jsi_ptr.root?
+        #chkbug raise(Bug, "jsi_root_node is not JSI::Base") if !jsi_root_node.is_a?(JSI::Base)
+        #chkbug raise(Bug, "jsi_root_node ptr is not root") if !jsi_root_node.jsi_ptr.root?
         @jsi_root_node = jsi_root_node
       end
-      self.jsi_schema_base_uri = jsi_schema_base_uri
-      self.jsi_schema_resource_ancestors = jsi_schema_resource_ancestors
+
+      jsi_memomaps_initialize
+      jsi_mutability_initialize
+
+      super()
 
       if jsi_instance.is_a?(JSI::Base)
         raise(TypeError, "a JSI::Base instance must not be another JSI::Base. received: #{jsi_instance.pretty_inspect.chomp}")
@@ -155,7 +149,9 @@ module JSI
     end
 
     # @!method jsi_schemas
-    #   the set of schemas which describe this instance
+    #   The set of schemas that describe this instance.
+    #   These are the applicator schemas that apply to this instance, the result of inplace application
+    #   of our {#jsi_indicated_schemas}.
     #   @return [JSI::SchemaSet]
     # note: defined on subclasses by JSI::SchemaClasses.class_for_schemas
 
@@ -167,38 +163,66 @@ module JSI
     # @return [JSI::Ptr]
     attr_reader :jsi_ptr
 
+    # Comes from the param `to_immutable` of {SchemaSet#new_jsi} (or other `new_jsi` /
+    # `new_schema` / `new_schema_module` method).
+    # Immutable JSIs use this when instantiating a modified copy so its instance is also immutable.
+    # @return [#call, nil]
+    attr_reader(:jsi_content_to_immutable)
+
     # the JSI at the root of this JSI's document
     # @return [JSI::Base]
     attr_reader :jsi_root_node
 
     # the content of this node in our {#jsi_document} at our {#jsi_ptr}. the same as {#jsi_instance}.
     def jsi_node_content
-      content = jsi_ptr.evaluate(jsi_document)
-      content
+      # stub method for doc, overridden by Mutable/Immutable
     end
 
-    # the JSON schema instance this JSI represents - the underlying JSON data used to instantiate this JSI
-    alias_method :jsi_instance, :jsi_node_content
+    # The JSON schema instance this JSI represents - the underlying JSON data used to instantiate this JSI.
+    # The same as {#jsi_node_content} - 'node content' is usually preferable terminology, to avoid
+    # ambiguity in the heavily overloaded term 'instance'.
+    def jsi_instance
+      jsi_node_content
+    end
 
-    # yields a JSI of each node at or below this one in this JSI's document.
+    # the schemas indicated as describing this instance, prior to inplace application.
+    #
+    # this is different from {#jsi_schemas}, which are the inplace applicator schemas
+    # which describe this instance. for most purposes, `#jsi_schemas` is more relevant.
+    #
+    # `jsi_indicated_schemas` does not include inplace applicator schemas, such as the
+    # subschemas of `allOf`, whereas `#jsi_schemas` does.
     #
-    # returns an Enumerator if no block is given.
+    # this does include indicated schemas which do not apply themselves, such as `$ref`
+    # schemas (on json schema drafts up to 7) - these are not included on `#jsi_schemas`.
     #
+    # @return [JSI::SchemaSet]
+    attr_reader :jsi_indicated_schemas
+
+    # yields a JSI of each node at or below this one in this JSI's document.
+    #
+    # @param propertyNames [Boolean] Whether to also yield each object property
+    #   name (Hash key) of any descendent which is a hash/object.
+    #   These are described by `propertyNames` subshemas of that object's schemas.
+    #   They are not actual descendents of this node.
+    #   See {HashNode#jsi_each_propertyName}.
     # @yield [JSI::Base] each descendent node, starting with self
     # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
-    def jsi_each_descendent_node(&block)
-      return to_enum(__method__) unless block
+    def jsi_each_descendent_node(propertyNames: false, &block)
+      return to_enum(__method__, propertyNames: propertyNames) unless block
 
       yield self
-      if respond_to?(:to_hash)
-        each_key do |k|
-          self[k, as_jsi: true].jsi_each_descendent_node(&block)
-        end
-      elsif respond_to?(:to_ary)
-        each_index do |i|
-          self[i, as_jsi: true].jsi_each_descendent_node(&block)
+
+      if propertyNames && is_a?(HashNode)
+        jsi_each_propertyName do |propertyName|
+          propertyName.jsi_each_descendent_node(propertyNames: propertyNames, &block)
         end
       end
+
+      jsi_each_child_token do |token|
+        jsi_child_node(token).jsi_each_descendent_node(propertyNames: propertyNames, &block)
+      end
+
       nil
     end
 
@@ -212,21 +236,17 @@ module JSI
     # @return [JSI::Base] modified copy of self containing only the selected nodes
     def jsi_select_descendents_node_first(&block)
       jsi_modified_copy do |instance|
-        if respond_to?(:to_hash)
+        if jsi_array? || jsi_hash?
           res = instance.class.new
-          each_key do |k|
-            v = self[k, as_jsi: true]
+          jsi_each_child_token do |token|
+            v = jsi_child_node(token)
             if yield(v)
-              res[k] = v.jsi_select_descendents_node_first(&block).jsi_node_content
-            end
-          end
-          res
-        elsif respond_to?(:to_ary)
-          res = instance.class.new
-          each_index do |i|
-            e = self[i, as_jsi: true]
-            if yield(e)
-              res << e.jsi_select_descendents_node_first(&block).jsi_node_content
+              res_v = v.jsi_select_descendents_node_first(&block).jsi_node_content
+              if jsi_array?
+                res << res_v
+              else
+                res[token] = res_v
+              end
             end
           end
           res
@@ -236,9 +256,6 @@ module JSI
       end
     end
 
-    # @deprecated after v0.6
-    alias_method :jsi_select_children_node_first, :jsi_select_descendents_node_first
-
     # recursively selects descendent nodes of this JSI, returning a modified copy of self containing only
     # descendent nodes for which the given block had a true-ish result.
     #
@@ -249,21 +266,17 @@ module JSI
     # @return [JSI::Base] modified copy of self containing only the selected nodes
     def jsi_select_descendents_leaf_first(&block)
       jsi_modified_copy do |instance|
-        if respond_to?(:to_hash)
+        if jsi_array? || jsi_hash?
           res = instance.class.new
-          each_key do |k|
-            v = self[k, as_jsi: true].jsi_select_descendents_leaf_first(&block)
+          jsi_each_child_token do |token|
+            v = jsi_child_node(token).jsi_select_descendents_leaf_first(&block)
             if yield(v)
-              res[k] = v.jsi_node_content
-            end
-          end
-          res
-        elsif respond_to?(:to_ary)
-          res = instance.class.new
-          each_index do |i|
-            e = self[i, as_jsi: true].jsi_select_descendents_leaf_first(&block)
-            if yield(e)
-              res << e.jsi_node_content
+              res_v = v.jsi_node_content
+              if jsi_array?
+                res << res_v
+              else
+                res[token] = res_v
+              end
             end
           end
           res
@@ -273,9 +286,6 @@ module JSI
       end
     end
 
-    # @deprecated after v0.6
-    alias_method :jsi_select_children_leaf_first, :jsi_select_descendents_leaf_first
-
     # an array of JSI instances above this one in the document.
     #
     # @return [Array<JSI::Base>]
@@ -284,9 +294,9 @@ module JSI
 
       jsi_ptr.tokens.map do |token|
         parent.tap do
-          parent = parent[token, as_jsi: true]
+          parent = parent.jsi_child_node(token)
         end
-      end.reverse
+      end.reverse!.freeze
     end
 
     # the immediate parent of this JSI. nil if there is no parent.
@@ -305,7 +315,7 @@ module JSI
       ancestors << ancestor
 
       jsi_ptr.tokens.each do |token|
-        ancestor = ancestor[token, as_jsi: true]
+        ancestor = ancestor.jsi_child_node(token)
         ancestors << ancestor
       end
       ancestors.reverse!.freeze
@@ -320,19 +330,140 @@ module JSI
       descendent
     end
 
+    # A shorthand alias for {#jsi_descendent_node}.
+    #
+    # Note that, though more convenient to type, using an operator whose meaning may not be intuitive
+    # to a reader could impair readability of code.
+    #
+    # examples:
+    #
+    #     my_jsi / ['foo', 'bar']
+    #     my_jsi / %w(foo bar)
+    #     my_schema / JSI::Ptr['additionalProperties']
+    #     my_schema / %w(properties foo items additionalProperties)
+    #
+    # @param (see #jsi_descendent_node)
+    # @return (see #jsi_descendent_node)
+    def /(ptr)
+      jsi_descendent_node(ptr)
+    end
+
+    # yields each token (array index or hash key) identifying a child node.
+    # yields nothing if this node is not complex or has no children.
+    #
+    # @yield [String, Integer] each child token
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def jsi_each_child_token
+      # note: overridden by Base::HashNode, Base::ArrayNode
+      return to_enum(__method__) { 0 } unless block_given?
+      nil
+    end
+
+    # Does the given token identify a child of this node?
+    #
+    # In other words, is the given token an array index or hash key of the instance?
+    #
+    # Always false if this is not a complex node.
+    #
+    # @param token [String, Integer]
+    # @return [Boolean]
+    def jsi_child_token_in_range?(token)
+      # note: overridden by Base::HashNode, Base::ArrayNode
+      false
+    end
+
+    # The child of the {#jsi_node_content} identified by the given token,
+    # or `nil` if the token does not identify an existing child.
+    #
+    # In other words, the element of the instance array at the given index,
+    # or the value of the instance hash/object for the given key.
+    #
+    # @return [Object, nil]
+    # @raise [SimpleNodeChildError] if this node is not complex (its instance is not array or hash)
+    def jsi_node_content_child(token)
+      # note: overridden by Base::HashNode, Base::ArrayNode
+      jsi_simple_node_child_error(token)
+    end
+
+    # A child JSI node, or the child of our {#jsi_instance}, identified by the given token.
+    # The token must identify an existing child; behavior if the child does not exist is undefined.
+    #
+    # @param token (see Base#[])
+    # @param as_jsi (see Base#[])
+    # @return [JSI::Base, Object]
+    def jsi_child(token, as_jsi: )
+      child_content = jsi_node_content_child(token)
+
+      child_indicated_schemas = @child_indicated_schemas_map[token: token, content: jsi_node_content]
+      child_applied_schemas = @child_applied_schemas_map[token: token, child_indicated_schemas: child_indicated_schemas, child_content: child_content]
+
+      jsi_child_as_jsi(child_content, child_applied_schemas, as_jsi) do
+        @child_node_map[
+          token: token,
+          child_indicated_schemas: child_indicated_schemas,
+          child_applied_schemas: child_applied_schemas,
+          includes: SchemaClasses.includes_for(child_content),
+        ]
+      end
+    end
+    private :jsi_child # internals for #[] but idk, could be public
+
+    # @param token (see Base#[])
+    # @return [JSI::Base]
+    protected def jsi_child_node(token)
+      jsi_child(token, as_jsi: true)
+    end
+
+    # A default value for a child of this node identified by the given token, if schemas describing
+    # that child define a default value.
+    #
+    # If no schema describes a default value for the child (or in the unusual case that multiple
+    # schemas define different defaults), the result is `nil`.
+    #
+    # See also the `use_default` param of {Base#[]}.
+    #
+    # @param token (see Base#[])
+    # @param as_jsi (see Base#[])
+    # @return [JSI::Base, nil]
+    def jsi_default_child(token, as_jsi: )
+      child_content = jsi_node_content_child(token)
+
+      child_indicated_schemas = @child_indicated_schemas_map[token: token, content: jsi_node_content]
+      child_applied_schemas = @child_applied_schemas_map[token: token, child_indicated_schemas: child_indicated_schemas, child_content: child_content]
+
+      defaults = Set.new
+      child_applied_schemas.each do |child_schema|
+        if child_schema.keyword?('default')
+          defaults << child_schema.jsi_node_content['default']
+        end
+      end
+
+      if defaults.size == 1
+        # use the default value
+        jsi_child_as_jsi(defaults.first, child_applied_schemas, as_jsi) do
+          jsi_modified_copy do |i|
+            i.dup.tap { |i_dup| i_dup[token] = defaults.first }
+          end.jsi_child_node(token)
+        end
+      else
+        child_content
+      end
+    end
+    private :jsi_default_child # internals for #[] but idk, could be public
+
     # subscripts to return a child value identified by the given token.
     #
     # @param token [String, Integer, Object] an array index or hash key (JSON object property name)
     #   of the instance identifying the child value
-    # @param as_jsi [:auto, true, false] whether to return the result value as a JSI. one of:
+    # @param as_jsi [:auto, true, false] (default is `:auto`)
+    #   Whether to return the child as a JSI. One of:
     #
-    #   - :auto (default): by default a JSI will be returned when either:
+    #   - `:auto`: By default a JSI will be returned when either:
     #
     #     - the result is a complex value (responds to #to_ary or #to_hash)
     #     - the result is a schema (including true/false schemas)
     #
-    #     a plain value is returned when no schemas are known to describe the instance, or when the value is a
-    #     simple type (anything unresponsive to #to_ary / #to_hash).
+    #     The plain content is returned when it is a simple type.
     #
     #   - true: the result value will always be returned as a JSI. the {#jsi_schemas} of the result may be
     #     empty if no schemas describe the instance.
@@ -342,8 +473,9 @@ module JSI
     #   is not a hash key or array index of the instance and no default value applies.
     #   (one exception is when this JSI's instance is a Hash with a default or default_proc, which has
     #   unspecified behavior.)
-    # @param use_default [true, false] whether to return a schema default value when the token is not in
-    #   range. if the token is not an array index or hash key of the instance, and one schema for the child
+    # @param use_default [true, false] (default is `false`)
+    #   Whether to return a schema default value when the token refers to a child that is not in the document.
+    #   If the token is not an array index or hash key of the instance, and one schema for the child
     #   instance specifies a default value, that default is returned.
     #
     #   if the result with the default value is a JSI (per the `as_jsi` param), that JSI is not a child of
@@ -354,52 +486,23 @@ module JSI
     #   defaults are specified across those schemas), nil is returned.
     #   (one exception is when this JSI's instance is a Hash with a default or default_proc, which has
     #   unspecified behavior.)
-    # @return [JSI::Base, Object] the child value identified by the subscript token
-    def [](token, as_jsi: :auto, use_default: true)
-      if respond_to?(:to_hash)
-        token_in_range = jsi_node_content_hash_pubsend(:key?, token)
-        value = jsi_node_content_hash_pubsend(:[], token)
-      elsif respond_to?(:to_ary)
-        token_in_range = jsi_node_content_ary_pubsend(:each_index).include?(token)
-        value = jsi_node_content_ary_pubsend(:[], token)
-      else
-        raise(CannotSubscriptError, "cannot subscript (using token: #{token.inspect}) from instance: #{jsi_instance.pretty_inspect.chomp}")
-      end
-
-      begin
-        subinstance_schemas = jsi_subinstance_schemas_memos[token: token, instance: jsi_node_content, subinstance: value]
+    # @return [JSI::Base, Object, nil] the child value identified by the subscript token
+    def [](token, as_jsi: jsi_child_as_jsi_default, use_default: jsi_child_use_default_default)
+      # note: overridden by Base::HashNode, Base::ArrayNode
+      jsi_simple_node_child_error(token)
+    end
 
-        if token_in_range
-          jsi_subinstance_as_jsi(value, subinstance_schemas, as_jsi) do
-            jsi_subinstance_memos[
-              token: token,
-              subinstance_schemas: subinstance_schemas,
-              includes: SchemaClasses.includes_for(value),
-            ]
-          end
-        else
-          if use_default
-            defaults = Set.new
-            subinstance_schemas.each do |subinstance_schema|
-              if subinstance_schema.keyword?('default')
-                defaults << subinstance_schema.jsi_node_content['default']
-              end
-            end
-          end
+    # The default value for the param `as_jsi` of {#[]}, controlling whether a child is returned as a JSI instance.
+    # @return [:auto, true, false] a valid value of the `as_jsi` param of {#[]}
+    def jsi_child_as_jsi_default
+      :auto
+    end
 
-          if use_default && defaults.size == 1
-            # use the default value
-            # we are using #dup so that we get a modified copy of self, in which we set dup[token]=default.
-            dup.tap { |o| o[token] = defaults.first }[token, as_jsi: as_jsi]
-          else
-            # I kind of want to just return nil here. the preferred mechanism for
-            # a JSI's default value should be its schema. but returning nil ignores
-            # any value returned by Hash#default/#default_proc. there's no compelling
-            # reason not to support both, so I'll return that.
-            value
-          end
-        end
-      end
+    # The default value for the param `use_default` of {#[]}, controlling whether a schema default value is
+    # returned when a token refers to a child that is not in the document.
+    # @return [true, false] a valid value of the `use_default` param of {#[]}
+    def jsi_child_use_default_default
+      false
     end
 
     # assigns the subscript of the instance identified by the given token to the given value.
@@ -408,8 +511,8 @@ module JSI
     # @param token [String, Integer, Object] token identifying the subscript to assign
     # @param value [JSI::Base, Object] the value to be assigned
     def []=(token, value)
-      unless respond_to?(:to_hash) || respond_to?(:to_ary)
-        raise(CannotSubscriptError, "cannot assign subscript (using token: #{token.inspect}) to instance: #{jsi_instance.pretty_inspect.chomp}")
+      unless jsi_array? || jsi_hash?
+        jsi_simple_node_child_error(token)
       end
       if value.is_a?(Base)
         self[token] = value.jsi_instance
@@ -424,6 +527,26 @@ module JSI
       Util.ensure_module_set(jsi_schemas.map(&:jsi_schema_module))
     end
 
+    # Is this JSI described by the given schema (or schema module)?
+    #
+    # @param schema [Schema, SchemaModule]
+    # @return [Boolean]
+    def described_by?(schema)
+      if schema.is_a?(Schema)
+        jsi_schemas.include?(schema)
+      elsif schema.is_a?(SchemaModule)
+        jsi_schema_modules.include?(schema)
+      else
+        raise(TypeError, "expected a Schema or Schema Module; got: #{schema.pretty_inspect.chomp}")
+      end
+    end
+
+    # Is this a JSI Schema?
+    # @return [Boolean]
+    def jsi_is_schema?
+      false
+    end
+
     # yields the content of this JSI's instance. the block must result in
     # a modified copy of the yielded instance (not modified in place, which would alter this JSI
     # as well) which will be used to instantiate and return a new JSI with the modified content.
@@ -435,30 +558,58 @@ module JSI
     #   in a nondestructively modified copy of this.
     # @return [JSI::Base subclass] the modified copy of self
     def jsi_modified_copy(&block)
-      if @jsi_ptr.root?
         modified_document = @jsi_ptr.modified_document_copy(@jsi_document, &block)
-        jsi_schemas.new_jsi(modified_document,
-          uri: jsi_schema_base_uri,
+        modified_jsi_root_node = @jsi_root_node.jsi_indicated_schemas.new_jsi(modified_document,
+          uri: @jsi_root_node.jsi_schema_base_uri,
+          register: false, # default is already false but this is a place to be explicit
+          schema_registry: jsi_schema_registry,
+          mutable: jsi_mutable?,
+          to_immutable: jsi_content_to_immutable,
         )
-      else
-        modified_jsi_root_node = @jsi_root_node.jsi_modified_copy do |root|
-          @jsi_ptr.modified_document_copy(root, &block)
-        end
         modified_jsi_root_node.jsi_descendent_node(@jsi_ptr)
-      end
+    end
+
+    # Is the instance an array?
+    #
+    # An array is typically an instance of the Array class but may be an object that supports
+    # [implicit conversion](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html)
+    # with a `#to_ary` method.
+    #
+    # @return [Boolean]
+    def jsi_array?
+      # note: overridden by Base::ArrayNode
+      false
+    end
+
+    # Is the instance a ruby Hash (JSON object)?
+    #
+    # This is typically an instance of the Hash class but may be an object that supports
+    # [implicit conversion](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html)
+    # with a `#to_hash` method.
+    #
+    # @return [Boolean]
+    def jsi_hash?
+      # note: overridden by Base::HashNode
+      false
+    end
+
+    # Is this JSI mutable?
+    # @return [Boolean]
+    def jsi_mutable?
+      # note: overridden by Base::Mutable / Immutable
     end
 
     # validates this JSI's instance against its schemas
     #
     # @return [JSI::Validation::FullResult]
     def jsi_validate
-      jsi_schemas.instance_validate(self)
+      jsi_indicated_schemas.instance_validate(self)
     end
 
     # whether this JSI's instance is valid against all of its schemas
     # @return [Boolean]
     def jsi_valid?
-      jsi_schemas.instance_valid?(self)
+      jsi_indicated_schemas.instance_valid?(self)
     end
 
     # queries this JSI using the [JMESPath Ruby](https://rubygems.org/gems/jmespath) gem.
@@ -485,21 +636,21 @@ module JSI
     # a string representing this JSI, indicating any named schemas and inspecting its instance
     # @return [String]
     def inspect
-      "\#<#{jsi_object_group_text.join(' ')} #{jsi_instance.inspect}>"
+      -"\#<#{jsi_object_group_text.join(' ')} #{jsi_instance.inspect}>"
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
 
     # pretty-prints a representation of this JSI to the given printer
     # @return [void]
     def pretty_print(q)
       q.text '#<'
       q.text jsi_object_group_text.join(' ')
-      q.group_sub {
-        q.nest(2) {
+      q.group(2) {
           q.breakable ' '
           q.pp jsi_instance
-        }
       }
       q.breakable ''
       q.text '>'
@@ -512,82 +663,115 @@ module JSI
       if schema_names.empty?
         class_txt = "JSI"
       else
-        class_txt = "JSI (#{schema_names.join(', ')})"
+        class_txt = -"JSI (#{schema_names.join(', ')})"
       end
 
       if (is_a?(ArrayNode) || is_a?(HashNode)) && ![Array, Hash].include?(jsi_node_content.class)
         if jsi_node_content.respond_to?(:jsi_object_group_text)
           content_txt = jsi_node_content.jsi_object_group_text
         else
-          content_txt = [jsi_node_content.class.to_s]
+          content_txt = jsi_node_content.class.to_s
         end
       else
-        content_txt = []
+        content_txt = nil
       end
 
       [
         class_txt,
-        is_a?(Metaschema) ? "Metaschema" : is_a?(Schema) ? "Schema" : nil,
+        is_a?(Schema::MetaSchema) ? "Meta-Schema" : is_a?(Schema) ? "Schema" : nil,
         *content_txt,
-      ].compact
+      ].compact.freeze
     end
 
-    # a jsonifiable representation of the instance
-    # @return [Object]
-    def as_json(*opt)
-      Util.as_json(jsi_instance, *opt)
+    # A structure coerced to JSONifiable types from the instance content.
+    # Calls {Util.as_json} with the instance and any given options.
+    def as_json(options = {})
+      Util.as_json(jsi_instance, **options)
     end
 
-    # an opaque fingerprint of this JSI for {Util::FingerprintHash}.
+    # A JSON encoded string of the instance content.
+    # Calls {Util.to_json} with the instance and any given options.
+    # @return [String]
+    def to_json(options = {})
+      Util.to_json(jsi_instance, **options)
+    end
+
+    # see {Util::Private::FingerprintHash}
+    # @api private
     def jsi_fingerprint
       {
-        class: jsi_class,
+        class: JSI::Base,
+        jsi_schemas: jsi_schemas,
         jsi_document: jsi_document,
         jsi_ptr: jsi_ptr,
         # for instances in documents with schemas:
         jsi_resource_ancestor_uri: jsi_resource_ancestor_uri,
-        # only defined for JSI::Schema instances:
-        jsi_schema_instance_modules: is_a?(Schema) ? jsi_schema_instance_modules : nil,
-      }
+        # different registries mean references may resolve to different resources so must not be equal
+        jsi_schema_registry: jsi_schema_registry,
+      }.freeze
     end
-    include Util::FingerprintHash
 
     private
 
-    def jsi_subinstance_schemas_memos
-      jsi_memomap(:subinstance_schemas, key_by: -> (i) { i[:token] }) do |token: , instance: , subinstance: |
-        jsi_schemas.child_applicator_schemas(token, instance).inplace_applicator_schemas(subinstance)
-      end
+    def jsi_memomaps_initialize
+      @child_indicated_schemas_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_indicated_schemas_compute))
+      @child_applied_schemas_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_applied_schemas_compute))
+      @child_node_map = jsi_memomap(key_by: proc { |i| i[:token] }, &method(:jsi_child_node_compute))
     end
 
-    def jsi_subinstance_memos
-      jsi_memomap(:subinstance, key_by: -> (i) { i[:token] }) do |token: , subinstance_schemas: , includes: |
-        jsi_class = JSI::SchemaClasses.class_for_schemas(subinstance_schemas, includes: includes)
+    def jsi_indicated_schemas=(jsi_indicated_schemas)
+      #chkbug raise(Bug) unless jsi_indicated_schemas.is_a?(SchemaSet)
+      @jsi_indicated_schemas = jsi_indicated_schemas
+    end
+
+    def jsi_child_node_compute(token: , child_indicated_schemas: , child_applied_schemas: , includes: )
+        jsi_class = JSI::SchemaClasses.class_for_schemas(child_applied_schemas,
+          includes: includes,
+          mutable: jsi_mutable?,
+        )
         jsi_class.new(@jsi_document,
           jsi_ptr: @jsi_ptr[token],
-          jsi_root_node: @jsi_root_node,
+          jsi_indicated_schemas: child_indicated_schemas,
           jsi_schema_base_uri: jsi_resource_ancestor_uri,
           jsi_schema_resource_ancestors: is_a?(Schema) ? jsi_subschema_resource_ancestors : jsi_schema_resource_ancestors,
+          jsi_schema_registry: jsi_schema_registry,
+          jsi_content_to_immutable: @jsi_content_to_immutable,
+          jsi_root_node: @jsi_root_node,
         )
-      end
     end
 
-    def jsi_subinstance_as_jsi(value, subinstance_schemas, as_jsi)
+    def jsi_child_indicated_schemas_compute(token: , content: )
+      jsi_schemas.child_applicator_schemas(token, content)
+    end
+
+    def jsi_child_applied_schemas_compute(token: , child_indicated_schemas: , child_content: )
+      child_indicated_schemas.inplace_applicator_schemas(child_content)
+    end
+
+    def jsi_child_as_jsi(child_content, child_schemas, as_jsi)
       if [true, false].include?(as_jsi)
-        value_as_jsi = as_jsi
+        child_as_jsi = as_jsi
       elsif as_jsi == :auto
-        complex_value = value.respond_to?(:to_hash) || value.respond_to?(:to_ary)
-        schema_value = subinstance_schemas.any?(&:describes_schema?)
-        value_as_jsi = complex_value || schema_value
+        child_is_complex = child_content.respond_to?(:to_hash) || child_content.respond_to?(:to_ary)
+        child_is_schema = child_schemas.any?(&:describes_schema?)
+        child_as_jsi = child_is_complex || child_is_schema
       else
         raise(ArgumentError, "as_jsi must be one of: :auto, true, false")
       end
 
-      if value_as_jsi
+      if child_as_jsi
         yield
       else
-        value
+        child_content
       end
     end
+
+    def jsi_simple_node_child_error(token)
+      raise(SimpleNodeChildError, [
+        "cannot access a child of this JSI node because this node is not complex",
+        "using token: #{token.inspect}",
+        "instance: #{jsi_instance.pretty_inspect.chomp}",
+      ].join("\n"))
+    end
   end
 end