jsi 0.4.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c370e01587ddef37138ffb1aacc4cd6240de94c0bbd9d61e96cafcb6ba829d
-  data.tar.gz: 9e26e8e2e8d78a05018302beff7190f33e0243d4f6899f5c3f1d046ccaaa3869
+  metadata.gz: '0659cc34b129717ffb69089f1d3a25ba3c3ec5364d49a6c0cc93dd5979ac7638'
+  data.tar.gz: 5b0298a9843a61e6f5693d46dd6d86021d53767638e1f3f84e23fff4b167276e
 SHA512:
-  metadata.gz: 75c5220df82e30b9332fba96d10463ee07cc52ff60cf8dc44963dd70c2472d279180659ab782098b5bcc9066dd000e07f60b1e7fa616215bfe6e6bfa11eddcb4
-  data.tar.gz: 848ac231235bebf262502fb7966265ab6c5e477bd6bb4acab038793dd5727a357f70482a3092e161cecc76eff4b126d4cdd7841965747fc2429ee76b5121128c
+  metadata.gz: 8b68dcbb479756b8fa58a43f7a8e83accda02a8b0aa87617dabb6623a4b1a8aa05f94cb03de601cf7bf88c943ce62e42963b533ef125729847159e3b775f32c2
+  data.tar.gz: 49997a70900b9d250e4888bcf3e5470e68b116c3a558651db9e5551f73027ea4abd18b0585d23f5201b15e8d80f1d72b46488d1870ac530d40368c7577d3b048

data/.yardopts

@@ -1 +1 @@
---main README.md --markup=markdown {lib}/**/*.rb
+--main README.md --markup=markdown --no-private {lib}/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+# v0.7.0
+
+- JSI::Base instances include Array/Hash-like modules on subclasses rather than extending each instance; are only Enumerable when appropriate instead of always
+- PathedHashNode -> Base::HashNode, PathedArrayNode -> Base::ArrayNode, PathedNode merged with Base
+- change application of conditional schemas to instances which do not validate, always apply them
+- fix nomenclature: child is immediately below parent; descendent is anywhere at/below an ancestor
+  - deprecate previous misnamed methods
+- Base#jsi_descendent_node, Base#jsi_ancestor_nodes
+- add Schema#describes_schema!, deprecate Schema#jsi_schema_instance_modules
+- Schema#keyword?
+- Base#jmespath_search
+- MetaschemaNode keeps its jsi_root_node (reducing an enormous number of unnecessary instantiations of MetaschemaNode)
+- /metaschema_instance_modules/schema_implementation_modules/
+- separate JSI::Util (public) and JSI::Util::Private
+- support ruby 3
+- Schema.default_metaschema is nil unless set by the application
+- deprecate JSI::Typelike module, merged with Util; Arraylike -> Util::Arraylike, Hashlike -> Util::Hashlike
+
+# v0.6.0
+
+- initial validation; remove gem `json-schema` dependency
+- initial schema issue collection
+- JSI.new_schema / new_schema_module
+- JSI::SchemaSet
+- JSI::SchemaRegistry
+- JSI::Schema::Ref
+- Base#jsi_each_child_node, jsi_select_children_node_first, jsi_select_children_leaf_first
+- JSI::JSON::Pointer → JSI::Ptr
+- deprecate JSI.class_for_schemas
+- remove test/development files from gem
+- remove JSI::JSON::Node
+- as always too much more to list
+
 # v0.4.0
 
 - a JSI::Base has multiple jsi_schemas https://github.com/notEthan/jsi/pull/88

data/LICENSE.md

@@ -2,7 +2,7 @@ Copright © [Ethan](https://github.com/notEthan/) <ethan.jsi@unth.net>
 
 [<img align="right" src="https://github.com/notEthan/jsi/raw/master/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
-JSI is Open Source Software licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
+JSI is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 
 GNU Affero General Public License
 =================================

data/README.md

@@ -1,19 +1,24 @@
 # JSI: JSON Schema Instantiation
 
-[![Build Status](https://travis-ci.org/notEthan/jsi.svg?branch=master)](https://travis-ci.org/notEthan/jsi)
+![Test CI Status](https://github.com/notEthan/jsi/actions/workflows/test.yml/badge.svg?branch=stable)
 [![Coverage Status](https://coveralls.io/repos/github/notEthan/jsi/badge.svg)](https://coveralls.io/github/notEthan/jsi)
 
 JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby modules and classes which are used to instantiate your JSON data. These modules let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
 
-To learn more about JSON Schema see [https://json-schema.org/]().
+To learn more about JSON Schema see [https://json-schema.org/](https://json-schema.org/).
 
-A JSI class aims to be a fairly unobtrusive wrapper around its instance - "instance" here meaning the JSON data, usually a Hash or Array, which instantiate the JSON Schema. JSI schema modules and classes add 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`.
+JSI marries object-oriented programming with JSON Schemas by associating a module with each schema, and extending every instance described by a schema with that module. When an application adds methods to a schema module, those methods can be used on its instances.
+
+A JSI instance aims to offer a fairly unobtrusive wrapper around its JSON data, which is usually a Hash (JSON Object) or Array described by one or more JSON Schemas. JSI instances have accessors for property names described by schemas, 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`.
+
+Note: The canonical location of this README is on [RubyDoc](http://rubydoc.info/gems/jsi/). When viewed on [Github](https://github.com/notEthan/jsi/), it may be inconsistent with the latest released gem, and Yardoc links will not work.
 
 ## Example
 
 Words are boring, let's code. Here's a schema in yaml:
 
 ```yaml
+$schema: "http://json-schema.org/draft-07/schema"
 description: "A Contact"
 type: "object"
 properties:
@@ -28,11 +33,11 @@ properties:
         number: {type: "string"}
 ```
 
-Using that schema, we instantiate a JSI::Schema to represent it:
+We pass that to {JSI.new_schema} which will instantiate a JSI Schema which represents it:
 
 ```ruby
-# this would usually use a YAML.load/JSON.parse/whatever; it's inlined for copypastability.
-contact_schema = JSI::Schema.new({"description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
+# this would usually load YAML or JSON; the schema object is inlined for copypastability.
+contact_schema = JSI.new_schema({"$schema" => "http://json-schema.org/draft-07/schema", "description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
 ```
 
 We name the module that JSI will use when instantiating a contact. Named modules are better to work with, and JSI will indicate the names of schema modules in its `#inspect` output.
@@ -41,6 +46,8 @@ We name the module that JSI will use when instantiating a contact. Named modules
 Contact = contact_schema.jsi_schema_module
 ```
 
+Note: it is more concise to instantiate the schema module with the shortcut {JSI.new_schema_module}, i.e. `Contact = JSI.new_schema_module(...)`. This example includes the intermediate step to help show all that is happening.
+
 To instantiate the schema, we need some JSON data (expressed here as YAML)
 
 ```yaml
@@ -54,12 +61,12 @@ nickname: big b
 So, if we construct an instance like:
 
 ```ruby
-# this would usually use a YAML.load/JSON.parse/whatever; it's inlined for copypastability.
+# this would usually load YAML or JSON; the schema instance is inlined for copypastability.
 bill = Contact.new_jsi({"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}], "nickname" => "big b"})
 # => #{<JSI (Contact)>
 #   "name" => "bill",
-#   "phone" => #[<JSI>
-#     #{<JSI>
+#   "phone" => #[<JSI (Contact.properties["phone"])>
+#     #{<JSI (Contact.properties["phone"].items)>
 #       "location" => "home",
 #       "number" => "555"
 #     }
@@ -68,7 +75,7 @@ bill = Contact.new_jsi({"name" => "bill", "phone" => [{"location" => "home", "nu
 # }
 ```
 
-Note that the keys are strings. JSI, being designed with JSON in mind, is geared toward string keys. Symbol keys will not match to schema properties, and so act the same as any other key not recognized from the schema.
+Note that the hash keys are strings. JSI, being designed with JSON in mind, is geared toward string keys.
 
 We get accessors for the Contact:
 
@@ -77,7 +84,7 @@ bill.name
 # => "bill"
 ```
 
-but also nested accessors - #phone is an instance of its array-type schema, and each phone item is an instance of another object-type schema with location and number accessors:
+but also nested accessors - `#phone` is an instance of its array-type schema, and each phone item is an instance of another object-type schema with `#location` and `#number` accessors:
 
 ```ruby
 bill.phone.map(&:location)
@@ -87,34 +94,43 @@ bill.phone.map(&:location)
 We also get validations, as you'd expect given that's largely what json-schema exists to do:
 
 ```ruby
-bill.validate
+bill.jsi_valid?
 # => true
 ```
 
-... and validations on the nested schema instances (#phone here), showing in this example validation failure:
+... and validations on the nested schema instances (`#phone` here), showing in this example validation failure on /phone/0/number:
 
 ```ruby
 bad = Contact.new_jsi({'phone' => [{'number' => [5, 5, 5]}]})
 # => #{<JSI (Contact)>
-#   "phone" => #[<JSI>
-#     #{<JSI>
-#       "number" => #[<JSI> 5, 5, 5]
+#   "phone" => #[<JSI (Contact.properties["phone"])>
+#     #{<JSI (Contact.properties["phone"].items)>
+#       "number" => #[<JSI (Contact.properties["phone"].items.properties["number"])> 5, 5, 5]
 #     }
 #   ]
 # }
-bad.phone.fully_validate
-# => ["The property '#/0/number' of type array did not match the following type: string in schema 594126e3"]
+bad.phone.jsi_validate
+# => #<JSI::Validation::FullResult
+#  @validation_errors=
+#   #<Set: {#<JSI::Validation::Error
+#      message: "instance type does not match `type` value",
+#      keyword: "type",
+#      schema: #{<JSI (JSI::JSONSchemaOrgDraft07) Schema> "type" => "string"},
+#      instance_ptr: JSI::Ptr["phone", 0, "number"],
+#      instance_document: {"phone"=>[{"number"=>[5, 5, 5]}]}
+#   >,
+#  ...
+# >
 ```
 
-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.
-
 Since the underlying instance is a ruby hash (json object), we can use it like a hash with `#[]` or, say, `#transform_values`:
 
 ```ruby
-# note that #size here is actually referring to multiple different methods; for name and nickname
-# it is String#size but for phone it is Array#size.
+# note that #size here is actually referring to multiple different methods;
+# for name and nickname it is String#size but for phone it is Array#size.
 bill.transform_values(&:size)
 # => {"name" => 4, "phone" => 1, "nickname" => 5}
+
 bill['nickname']
 # => "big b"
 ```
@@ -123,13 +139,24 @@ 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 for each JSI class representing a JSON Schema.
-- a "JSI class" is a subclass of `JSI::Base` representing a JSON schema.
-- a "JSI schema module" is a module representing a schema, included on a JSI class.
+- `JSI::Base` is the base class for each JSI schema class representing instances of JSON Schemas.
+- a "JSI Schema" is a JSON Schema, instantiated as (usually) a JSI::Base described by a metaschema (see the sections on Metaschemas below). a JSI Schema is an instance of the module `JSI::Schema`.
+- a "JSI Schema Module" is a module which represents one schema, dynamically created by that Schema. Instances of that schema are extended with its JSI schema module. applications may reopen these modules to add functionality to JSI instances described by a given schema.
+- a "JSI schema class" is a subclass of `JSI::Base` representing one or more JSON schemas. Instances of such a class are described by all of the represented schemas. A JSI schema class includes the JSI schema module of each represented 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 JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method `#jsi_instance` which contains the underlying data.
-- a schema refers to a JSON schema. `JSI::Schema` is a module which extends schemas. A schema is usually a `JSI::Base` instance, and that schema JSI's schema is a metaschema (see the sections on Metaschemas below).
+  - a JSI instance (or just "a JSI") is a ruby object instantiating a JSI schema class (subclass of `JSI::Base`). This wraps the content of the schema instance (see `JSI::Base#jsi_instance`), and ties it to the schemas which describe the instance (`JSI::Base#jsi_schemas`).
+- "schema" refers to either a parsed JSON schema (generally a ruby Hash) or a JSI schema.
+
+## Supported specification versions
+
+JSI supports these JSON Schema specification versions:
+
+| Version | `$schema` URI                             | JSI Schema Module |
+| ---     | ---                                       | ---               |
+| Draft 4 | `http://json-schema.org/draft-04/schema#` | {JSI::JSONSchemaOrgDraft04} |
+| Draft 6 | `http://json-schema.org/draft-06/schema#` | {JSI::JSONSchemaOrgDraft06} |
+| Draft 7 | `http://json-schema.org/draft-07/schema#` | {JSI::JSONSchemaOrgDraft07} |
 
 ## JSI and Object Oriented Programming
 
@@ -148,23 +175,34 @@ module Contact
   end
 end
 
+bill.phone_numbers
+# => ["555"]
+
 bill.name
 # => "bill esq."
 bill.name = 'rob esq.'
 # => "rob esq."
 bill['name']
 # => "rob"
-bill.phone_numbers
-# => ["555"]
 ```
 
-Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers. You can alternatively use `[]` and `[]=` with the same effect.
+`#phone_numbers` is a new method returning each number in the `phone` array - pretty straightforward.
+
+For `#name` and `#name=`, we're overriding existing accessor methods. note the use of `super` - this invokes the accessor methods defined by JSI which these override. You could alternatively use `self['name']` and `self['name']=` in these methods, with the same effect as `super`.
 
-You can also add methods to a subschema using the same method `#jsi_schema_module` which we used to define the `Contact` module above.
+Working with subschemas is just about as easy as with root schemas.
+
+You can subscript or use property accessors on a JSI schema module to refer to the schema modules of its subschemas, e.g.:
 
 ```ruby
-phone_schema = Contact.schema.properties['phone'].items
-phone_schema.jsi_schema_module.module_eval do
+Contact.properties['phone'].items
+# => Contact.properties["phone"].items (JSI Schema Module)
+```
+
+Opening a subschema module with [`module_exec`](https://ruby-doc.org/core/Module.html#method-i-module_exec), you can add methods to instances of the subschema.
+
+```ruby
+Contact.properties['phone'].items.module_exec do
   def number_with_dashes
     number.split(//).join('-')
   end
@@ -173,10 +211,24 @@ bill.phone.first.number_with_dashes
 # => "5-5-5"
 ```
 
-If you want to name the module, this works:
+A recommended convention for naming subschemas is to define them in the namespace of the module of their
+parent schema. The module can then be opened to add methods to the subschema's module.
 
 ```ruby
-ContactPhone = Contact.schema.properties['phone'].items.jsi_schema_module
+module Contact
+  Phone = properties['phone'].items
+  module Phone
+    def number_with_dashes
+      number.split(//).join('-')
+    end
+  end
+end
+```
+
+However, that is only a convention, and a flat namespace works fine too.
+
+```ruby
+ContactPhone = Contact.properties['phone'].items
 module ContactPhone
   def number_with_dashes
     number.split(//).join('-')
@@ -184,15 +236,35 @@ module ContactPhone
 end
 ```
 
-Either syntax is slightly cumbersome and a better syntax is in the works.
+### A note on Classes
+
+The classes used to instantiate JSIs are dynamically generated subclasses of JSI::Base which include the JSI Schema Module of each schema describing the given instance. These are mostly intended to be ignored: applications aren't expected to instantiate these directly (rather, `#new_jsi` on a Schema or Schema Module is intended), and they are not intended for subclassing or method definition (applications should instead define methods on a schema's {JSI::Schema#jsi_schema_module}).
+
+## Registration
+
+In order for references across documents (generally from a `$ref` schema keyword) to resolve, JSI provides a registry which associates URIs with schemas (or resources containing schemas). This registry is accessible on {JSI.schema_registry} and is a {JSI::SchemaRegistry}.
+
+Schemas instantiated with `.new_schema`, and their subschemas, are automatically registered with `JSI.schema_registry` if they identify an absolute URI.
+
+Schemas can automatically be lazily loaded by registering a block which instantiates them with {JSI::SchemaRegistry#autoload_uri} (see its documentation).
+
+## Validation
+
+JSI implements all required features, and many optional features, for validation according to supported JSON Schema specifications. To validate instances, see methods {JSI::Base#jsi_validate}, {JSI::Base#jsi_valid?}, {JSI::Schema#instance_validate}, {JSI::Schema#instance_valid?}.
+
+The following optional features are not completely supported:
+
+- The `format` keyword does not perform any validation.
+- Regular expressions are interpreted by Ruby's Regexp class, whereas JSON Schema recommends interpreting these as ECMA 262 regular expressions. Certain expressions behave differently, particularly `^` and `$`.
+- Keywords `contentMediaType` and `contentEncoding` do not perform validation.
 
 ## Metaschemas
 
 A metaschema is a schema which describes schemas. Likewise, a schema is an instance of a metaschema.
 
-In JSI, a schema is generally a JSI::Base instance whose schema is a metaschema.
+In JSI, a schema is generally a JSI::Base instance whose schemas include a metaschema.
 
-A self-descriptive metaschema - most commonly one of the JSON schema draft metaschemas - is an object whose schema is itself. This is instantiated in JSI as a JSI::MetaschemaNode (not a JSI::Base).
+A self-descriptive metaschema - most commonly one of the JSON schema draft metaschemas - is an object whose schemas include itself. This is instantiated in JSI as a JSI::MetaschemaNode, a special subclass of JSI::Base.
 
 ## ActiveRecord serialization
 
@@ -202,7 +274,7 @@ Let's say you're sticking to JSON types in the database - you have to do so if y
 
 But if your database contains JSON, then your deserialized objects in ruby are likewise Hash / Array / basic types. You have to use subscripts instead of accessors, and you don't have any way to add methods to your data types.
 
-JSI gives you the best of both with JSICoder. This coder dumps objects which are simple JSON types, and loads instances of a specified JSI schema. Here's an example:
+JSI gives you the best of both with {JSI::JSICoder}. This coder dumps objects which are simple JSON types, and loads instances of a specified JSON Schema. Here's an example, supposing a `users` table with a JSON column `contact_info` to be instantiated using the `Contact` schema module defined in the Example section above:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -210,13 +282,13 @@ class User < ActiveRecord::Base
 end
 ```
 
-Now `user.contacts` will return an array of Contact instances, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
+Now `user.contact_info` will be instantiated as a `Contact` JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
 
 See the gem [`arms`](https://github.com/notEthan/arms) if you wish to serialize the dumped JSON-compatible objects further as text.
 
 ## Keying Hashes (JSON Objects)
 
-Unlike Ruby, JSON only supports string keys. It is recommended to use strings as hash keys for all JSI instances, but JSI does not enforce this, nor does it do any key conversion. It should be possible to use ActiveSupport::HashWithIndifferentAccess as the instance of a JSI in order to gain the benefits that offers over a plain hash. This is not tested behavior, but JSI should behave correctly with any instance that responds to #to_hash.
+Unlike Ruby, JSON only supports string keys. It is recommended to use strings as hash keys for all JSI instances, but JSI does not enforce this, nor does it do any key conversion. You may also use [ActiveSupport::HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html) as the instance of a JSI in order to gain the benefits that offers over a plain hash. Note that activesupport is not a dependency of jsi and would be required separately for this.
 
 ## Contributing
 
@@ -224,7 +296,7 @@ Issues and pull requests are welcome on GitHub at https://github.com/notEthan/js
 
 ## License
 
-[<img align="right" src="https://github.com/notEthan/jsi/raw/master/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
+[<img align="right" src="https://github.com/notEthan/jsi/raw/v0.3.0/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
 JSI is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 

data/jsi.gemspec

@@ -1,4 +1,4 @@
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "jsi/version"
 
@@ -12,17 +12,19 @@ Gem::Specification.new do |spec|
   spec.description = "JSI offers an Object-Oriented representation for JSON data using JSON Schemas"
   spec.homepage    = "https://github.com/notEthan/jsi"
   spec.license     = "AGPL-3.0"
-  ignore_files     = %w(.gitignore .travis.yml Gemfile test)
-  ignore_files_re  = %r{\A(#{ignore_files.map { |f| Regexp.escape(f) }.join('|')})(/|\z)}
-  spec.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(ignore_files_re) }
-  spec.test_files   = `git ls-files -z test`.split("\x0")
+
+  spec.files = [
+    'LICENSE.md',
+    'CHANGELOG.md',
+    'README.md',
+    'readme.rb',
+    '.yardopts',
+    'jsi.gemspec',
+    *Dir['lib/**/*'],
+    *Dir['\\{resources\\}/schemas/**/*'],
+  ].reject { |f| File.lstat(f).ftype == 'directory' }
+
   spec.require_paths = ["lib"]
 
-  # we are monkey patching json-schema with a fix that has not been merged in a timely fashion.
-  spec.add_dependency "json-schema", "~> 2.8"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "minitest-around"
-  spec.add_development_dependency "minitest-reporters"
-  spec.add_development_dependency "scorpio"
+  spec.add_dependency "addressable", '~> 2.3'
 end

data/lib/jsi/base/node.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module JSI
+  module Base::Enumerable
+    include ::Enumerable
+
+    # an Array containing each item in this JSI.
+    #
+    # @param kw keyword arguments are passed to {Base#[]} - see its keyword params
+    # @return [Array]
+    def to_a(**kw)
+      # TODO remove eventually (keyword argument compatibility)
+      # discard when all supported ruby versions Enumerable#to_a delegate keywords to #each (3.0.1 breaks; 2.7.x warns)
+      # https://bugs.ruby-lang.org/issues/18289
+      ary = []
+      each(**kw) do |e|
+        ary << e
+      end
+      ary
+    end
+
+    alias_method :entries, :to_a
+
+    # a jsonifiable representation of the node content
+    # @return [Object]
+    def as_json(*opt)
+      # include Enumerable (above) means, if ActiveSupport is loaded, its undesirable #as_json is included
+      # https://github.com/rails/rails/blob/v7.0.0/activesupport/lib/active_support/core_ext/object/json.rb#L139-L143
+      # although Base#as_json does clobber activesupport's, I want as_json defined correctly on the module too.
+      Typelike.as_json(jsi_node_content, *opt)
+    end
+  end
+
+  # module extending a {JSI::Base} object when its instance (its {Base#jsi_node_content})
+  # is a Hash (or responds to `#to_hash`)
+  module Base::HashNode
+    include Base::Enumerable
+
+    # yields each hash key and value of this node.
+    #
+    # each yielded key is a key of the instance hash, and each yielded value is the result of {Base#[]}.
+    #
+    # returns an Enumerator if no block is given.
+    #
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @yield [Object, Object] each key and value of this hash node
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(**kw, &block)
+      return to_enum(__method__, **kw) { jsi_node_content_hash_pubsend(:size) } unless block
+      if block.arity > 1
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield k, self[k, **kw] }
+      else
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield [k, self[k, **kw]] }
+      end
+      self
+    end
+
+    # a hash in which each key is a key of the instance hash and each value is the result of {Base#[]}
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @return [Hash]
+    def to_hash(**kw)
+      {}.tap { |h| jsi_node_content_hash_pubsend(:each_key) { |k| h[k] = self[k, **kw] } }
+    end
+
+    include Util::Hashlike
+
+    if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_hash
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_hash
+      def jsi_node_content_hash_pubsend(method_name, *a, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, &b)
+        else
+          jsi_node_content.to_hash.public_send(method_name, *a, &b)
+        end
+      end
+    else
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_hash
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param kw keyword arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_hash
+      def jsi_node_content_hash_pubsend(method_name, *a, **kw, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, **kw, &b)
+        else
+          jsi_node_content.to_hash.public_send(method_name, *a, **kw, &b)
+        end
+      end
+    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|
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_node_content_hash_pubsend(method_name, *a, &b)
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_node_content_hash_pubsend(method_name, *a, **kw, &b)
+        end
+      end
+    end
+  end
+
+  # module extending a {JSI::Base} object when its instance (its {Base#jsi_node_content})
+  # is an Array (or responds to `#to_ary`)
+  module Base::ArrayNode
+    include Base::Enumerable
+
+    # yields each array element of this node.
+    #
+    # each yielded element is the result of {Base#[]} for each index of the instance array.
+    #
+    # returns an Enumerator if no block is given.
+    #
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @yield [Object] each element of this array node
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(**kw, &block)
+      return to_enum(__method__, **kw) { jsi_node_content_ary_pubsend(:size) } unless block
+      jsi_node_content_ary_pubsend(:each_index) { |i| yield(self[i, **kw]) }
+      self
+    end
+
+    # an array, the same size as the instance array, in which the element at each index is the
+    # result of {Base#[]}.
+    # @param kw keyword arguments are passed to {Base#[]}
+    # @return [Array]
+    def to_ary(**kw)
+      to_a(**kw)
+    end
+
+    include Util::Arraylike
+
+    if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_ary
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_ary
+      def jsi_node_content_ary_pubsend(method_name, *a, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, &b)
+        else
+          jsi_node_content.to_ary.public_send(method_name, *a, &b)
+        end
+      end
+    else
+      # invokes the method with the given name on the jsi_node_content (if defined) or its #to_ary
+      # @param method_name [String, Symbol]
+      # @param a positional arguments are passed to the invocation of method_name
+      # @param kw keyword arguments are passed to the invocation of method_name
+      # @param b block is passed to the invocation of method_name
+      # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_ary
+      def jsi_node_content_ary_pubsend(method_name, *a, **kw, &b)
+        if jsi_node_content.respond_to?(method_name)
+          jsi_node_content.public_send(method_name, *a, **kw, &b)
+        else
+          jsi_node_content.to_ary.public_send(method_name, *a, **kw, &b)
+        end
+      end
+    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|
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_node_content_ary_pubsend(method_name, *a, &b)
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_node_content_ary_pubsend(method_name, *a, **kw, &b)
+        end
+      end
+    end
+  end
+end