jsi 0.7.0 → 0.8.0

data/lib/jsi/schema_set.rb

@@ -6,14 +6,12 @@ module JSI
   # any schema instance is described by a set of schemas.
   class SchemaSet < ::Set
     class << self
-      # builds a SchemaSet from a mutable Set which is added to by the given block
+      # Builds a SchemaSet, yielding a yielder to be called with each schema of the SchemaSet.
       #
-      # @yield [Set] a Set to which the block may add schemas
+      # @yield [Enumerator::Yielder]
       # @return [SchemaSet]
-      def build
-        mutable_set = Set.new
-        yield mutable_set
-        new(mutable_set)
+      def build(&block)
+        new(Enumerator.new(&block))
       end
 
       # ensures the given param becomes a SchemaSet. returns the param if it is already SchemaSet, otherwise
@@ -51,6 +49,10 @@ module JSI
         ].join("\n"))
       end
 
+      unless enum.is_a?(Enumerable)
+        raise(ArgumentError, "#{SchemaSet} initialized with non-Enumerable: #{enum.pretty_inspect.chomp}")
+      end
+
       super
 
       not_schemas = reject { |s| s.is_a?(Schema) }
@@ -64,36 +66,79 @@ module JSI
       freeze
     end
 
-    # instantiates the given instance as a JSI. its schemas are inplace applicators matched from the schemas
-    # in this SchemaSet which apply to the given instance.
+    # Instantiates a new JSI whose content comes from the given `instance` param.
+    # This SchemaSet indicates the schemas of the JSI - its schemas are inplace
+    # applicators of this set's schemas which apply to the given instance.
+    #
+    # @param instance [Object] the instance to be represented as a JSI
+    # @param uri [#to_str, Addressable::URI] The retrieval URI of the instance.
     #
-    # @param instance [Object] the JSON Schema instance to be represented as a JSI
-    # @param uri [nil, #to_str, Addressable::URI] for an instance document containing schemas, this is
-    #   the URI of the document, whether or not the document is itself a schema.
-    #   in the normal case where the document does not contain any schemas, `uri` has no effect.
-    #   schemas within the document use this uri as the base URI to resolve relative URIs.
-    #   the resulting JSI may be registered with a {SchemaRegistry} (see {JSI.schema_registry}).
-    # @return [JSI::Base subclass] a JSI whose instance is the given instance and whose schemas are inplace
-    #   applicators matched to the instance from the schemas in this set.
+    #   It is rare that this needs to be specified, and only useful for instances which contain schemas.
+    #   See {Schema::MetaSchema#new_schema}'s `uri` param documentation.
+    # @param register [Boolean] Whether schema resources in the instantiated JSI will be registered
+    #   in the schema registry indicated by param `schema_registry`.
+    #   This is only useful when the JSI is a schema or contains schemas.
+    #   The JSI's root will be registered with the `uri` param, if specified, whether or not the
+    #   root is a schema.
+    # @param schema_registry [SchemaRegistry, nil] The registry to use for references to other schemas and,
+    #    depending on `register` and `uri` params, to register this JSI and/or any contained schemas with
+    #    declared URIs.
+    # @param stringify_symbol_keys [Boolean] Whether the instance content will have any Symbol keys of Hashes
+    #   replaced with Strings (recursively through the document).
+    #   Replacement is done on a copy; the given instance is not modified.
+    # @param to_immutable [#call, nil] A proc/callable which takes given instance content
+    #   and results in an immutable (i.e. deeply frozen) object equal to that.
+    #   If the instantiated JSI will be mutable, this is not used.
+    #   Though not recommended, this may be nil with immutable JSIs if the instance content is otherwise
+    #   guaranteed to be immutable, as well as any modified copies of the instance.
+    # @param mutable [Boolean] Whether the instantiated JSI will be mutable.
+    #   The instance content will be transformed with `to_immutable` if the JSI will be immutable.
+    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
+    #   inplace applicators of the schemas in this set.
     def new_jsi(instance,
-        uri: nil
+        uri: nil,
+        register: false,
+        schema_registry: JSI.schema_registry,
+        stringify_symbol_keys: false,
+        to_immutable: DEFAULT_CONTENT_TO_IMMUTABLE,
+        mutable: true
     )
+      instance = Util.deep_stringify_symbol_keys(instance) if stringify_symbol_keys
+
+      instance = to_immutable.call(instance) if !mutable && to_immutable
+
       applied_schemas = inplace_applicator_schemas(instance)
 
+      if uri
+        unless uri.respond_to?(:to_str)
+          raise(TypeError, "uri must be string or Addressable::URI; got: #{uri.inspect}")
+        end
+        uri = Util.uri(uri)
+        unless uri.absolute? && !uri.fragment
+          raise(ArgumentError, "uri must be an absolute URI with no fragment; got: #{uri.inspect}")
+        end
+      end
+
       jsi_class = JSI::SchemaClasses.class_for_schemas(applied_schemas,
         includes: SchemaClasses.includes_for(instance),
+        mutable: mutable,
       )
       jsi = jsi_class.new(instance,
+        jsi_indicated_schemas: self,
         jsi_schema_base_uri: uri,
+        jsi_schema_registry: schema_registry,
+        jsi_content_to_immutable: to_immutable,
       )
 
+      schema_registry.register(jsi) if register && schema_registry
+
       jsi
     end
 
     # a set of inplace applicator schemas of each schema in this set which apply to the given instance.
-    # (see {Schema::Application::InplaceApplication#inplace_applicator_schemas})
+    # (see {Schema#inplace_applicator_schemas})
     #
-    # @param instance (see Schema::Application::InplaceApplication#inplace_applicator_schemas)
+    # @param instance (see Schema#inplace_applicator_schemas)
     # @return [JSI::SchemaSet]
     def inplace_applicator_schemas(instance)
       SchemaSet.new(each_inplace_applicator_schema(instance))
@@ -101,7 +146,7 @@ module JSI
 
     # yields each inplace applicator schema which applies to the given instance.
     #
-    # @param instance (see Schema::Application::InplaceApplication#inplace_applicator_schemas)
+    # @param instance (see Schema#inplace_applicator_schemas)
     # @yield [JSI::Schema]
     # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
     def each_inplace_applicator_schema(instance, &block)
@@ -116,9 +161,9 @@ module JSI
 
     # a set of child applicator subschemas of each schema in this set which apply to the child
     # of the given instance on the given token.
-    # (see {Schema::Application::ChildApplication#child_applicator_schemas})
+    # (see {Schema#child_applicator_schemas})
     #
-    # @param instance (see Schema::Application::ChildApplication#child_applicator_schemas)
+    # @param instance (see Schema#child_applicator_schemas)
     # @return [JSI::SchemaSet]
     def child_applicator_schemas(token, instance)
       SchemaSet.new(each_child_applicator_schema(token, instance))
@@ -127,7 +172,7 @@ module JSI
     # yields each child applicator schema which applies to the child of
     # the given instance on the given token.
     #
-    # @param (see Schema::Application::ChildApplication#child_applicator_schemas)
+    # @param (see Schema#child_applicator_schemas)
     # @yield [JSI::Schema]
     # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
     def each_child_applicator_schema(token, instance, &block)
@@ -145,8 +190,9 @@ module JSI
     # @param instance [Object] the instance to validate against our schemas
     # @return [JSI::Validation::Result]
     def instance_validate(instance)
-      results = map { |schema| schema.instance_validate(instance) }
-      results.inject(Validation::FullResult.new, &:merge).freeze
+      inject(Validation::FullResult.new) do |result, schema|
+        result.merge(schema.instance_validate(instance))
+      end.freeze
     end
 
     # whether the given instance is valid against our schemas
@@ -158,21 +204,21 @@ module JSI
 
     # @return [String]
     def inspect
-      "#{self.class}[#{map(&:inspect).join(", ")}]"
+      -"#{self.class}[#{map(&:inspect).join(", ")}]"
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
 
     def pretty_print(q)
       q.text self.class.to_s
       q.text '['
-      q.group_sub {
-        q.nest(2) {
+      q.group(2) {
           q.breakable('')
           q.seplist(self, nil, :each) { |e|
             q.pp e
           }
-        }
       }
       q.breakable ''
       q.text ']'

data/lib/jsi/simple_wrap.rb

@@ -2,11 +2,6 @@
 
 module JSI
   simple_wrap_implementation = Module.new do
-    include Schema
-    include Schema::Application::ChildApplication
-    include Schema::Application::InplaceApplication
-    include Schema::Validation::Core
-
     def internal_child_applicate_keywords(token, instance)
       yield self
     end
@@ -19,8 +14,8 @@ module JSI
     end
   end
 
-  simple_wrap_metaschema = MetaschemaNode.new(nil, schema_implementation_modules: [simple_wrap_implementation])
-  SimpleWrap = simple_wrap_metaschema.new_schema_module({})
+  simple_wrap_metaschema = JSI.new_metaschema(nil, schema_implementation_modules: [simple_wrap_implementation])
+  SimpleWrap = simple_wrap_metaschema.new_schema_module(Util::EMPTY_HASH)
 
   # SimpleWrap is a JSI schema module which recursively wraps nested structures
   module SimpleWrap

data/lib/jsi/util/private/attr_struct.rb

@@ -16,12 +16,18 @@ module JSI
         # creates a AttrStruct subclass with the given attribute keys.
         # @param attribute_keys [Enumerable<String, Symbol>]
         def subclass(*attribute_keys)
-          bad = attribute_keys.reject { |key| key.respond_to?(:to_str) || key.is_a?(Symbol) }
-          unless bad.empty?
-            raise ArgumentError, "attribute keys must be String or Symbol; got keys: #{bad.map(&:inspect).join(', ')}"
+          bad_type = attribute_keys.reject { |key| key.respond_to?(:to_str) || key.is_a?(Symbol) }
+          unless bad_type.empty?
+            raise(ArgumentError, "attribute keys must be String or Symbol; got keys: #{bad_type.map(&:inspect).join(', ')}")
           end
+
           attribute_keys = attribute_keys.map { |key| convert_key(key) }
 
+          bad_name = attribute_keys.reject { |key| Util::Private.ok_ruby_method_name?(key) }
+          unless bad_name.empty?
+            raise(ArgumentError, "attribute keys must be valid ruby method names; got keys: #{bad_name.map(&:inspect).join(', ')}")
+          end
+
           all_attribute_keys = (self.attribute_keys + attribute_keys).freeze
 
           Class.new(self).tap do |klass|
@@ -67,7 +73,7 @@ module JSI
         attributes.to_hash.each do |k, v|
           @attributes[self.class.convert_key(k)] = v
         end
-        bad = @attributes.keys.reject { |k| attribute_keys.include?(k) }
+        bad = @attributes.keys.reject { |k| class_attribute_keys.include?(k) }
         unless bad.empty?
           raise UndefinedAttributeKey, "undefined attribute keys: #{bad.map(&:inspect).join(', ')}"
         end
@@ -79,7 +85,7 @@ module JSI
 
       def []=(key, value)
         key = self.class.convert_key(key)
-        unless attribute_keys.include?(key)
+        unless class_attribute_keys.include?(key)
           raise UndefinedAttributeKey, "undefined attribute key: #{key.inspect}"
         end
         @attributes[key] = value
@@ -87,19 +93,20 @@ module JSI
 
       # @return [String]
       def inspect
-        "\#<#{self.class.name}#{@attributes.empty? ? '' : ' '}#{@attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+        -"\#<#{self.class.name}#{@attributes.map { |k, v| " #{k}: #{v.inspect}" }.join(',')}>"
       end
 
-      alias_method :to_s, :inspect
+      def to_s
+        inspect
+      end
 
       # pretty-prints a representation of self to the given printer
       # @return [void]
       def pretty_print(q)
         q.text '#<'
         q.text self.class.name
-        q.group_sub {
-          q.nest(2) {
-            q.breakable(@attributes.empty? ? '' : ' ')
+        q.group(2) {
+            q.breakable(' ') if !@attributes.empty?
             q.seplist(@attributes, nil, :each_pair) { |k, v|
               q.group {
                 q.text k
@@ -107,20 +114,27 @@ module JSI
                 q.pp v
               }
             }
-          }
         }
-        q.breakable ''
+        q.breakable('') if !@attributes.empty?
         q.text '>'
       end
 
       # (see AttrStruct.attribute_keys)
-      def attribute_keys
+      def class_attribute_keys
         self.class.attribute_keys
       end
 
+      def freeze
+        @attributes.freeze
+        super
+      end
+
       include FingerprintHash
+
+      # see {Util::Private::FingerprintHash}
+      # @api private
       def jsi_fingerprint
-        {class: self.class, attributes: @attributes}
+        {class: self.class, attributes: @attributes}.freeze
       end
     end
   end

data/lib/jsi/util/private/memo_map.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module JSI
+  module Util::Private
+    class MemoMap
+      def initialize(key_by: nil, &block)
+        @key_by = key_by
+        @block = block || raise(ArgumentError, "no block given")
+
+        # each result has its own mutex to update its memoized value thread-safely
+        @result_mutexes = {}
+        # another mutex to thread-safely initialize each result mutex
+        @result_mutexes_mutex = Mutex.new
+
+        @results = {}
+      end
+
+      def key_for(inputs)
+        if @key_by
+          @key_by.call(**inputs)
+        else
+          inputs
+        end
+      end
+    end
+
+    class MemoMap::Mutable < MemoMap
+      Result = AttrStruct[*%w(
+        value
+        inputs
+        inputs_hash
+      )]
+
+      class Result
+      end
+
+      def [](**inputs)
+        key = key_for(inputs)
+
+        result_mutex = @result_mutexes_mutex.synchronize do
+          @result_mutexes[key] ||= Mutex.new
+        end
+
+        result_mutex.synchronize do
+          inputs_hash = inputs.hash
+          if @results.key?(key) && inputs_hash == @results[key].inputs_hash && inputs == @results[key].inputs
+            @results[key].value
+          else
+            value = @block.call(**inputs)
+            @results[key] = Result.new(value: value, inputs: inputs, inputs_hash: inputs_hash)
+            value
+          end
+        end
+      end
+    end
+
+    class MemoMap::Immutable < MemoMap
+      def [](**inputs)
+        key = key_for(inputs)
+
+        result_mutex = @result_mutexes_mutex.synchronize do
+          @result_mutexes[key] ||= Mutex.new
+        end
+
+        result_mutex.synchronize do
+          if @results.key?(key)
+            @results[key]
+          else
+            @results[key] = @block.call(**inputs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsi/util/private.rb

@@ -6,11 +6,18 @@ module JSI
   # @api private
   module Util::Private
     autoload :AttrStruct, 'jsi/util/private/attr_struct'
+    autoload :MemoMap, 'jsi/util/private/memo_map'
+
+    extend self
 
     EMPTY_ARY = [].freeze
 
+    EMPTY_HASH = {}.freeze
+
     EMPTY_SET = Set[].freeze
 
+    CLASSES_ALWAYS_FROZEN = Set[TrueClass, FalseClass, NilClass, Integer, Float, BigDecimal, Rational, Symbol].freeze
+
     # is a hash as the last argument passed to keyword params? (false in ruby 3; true before - generates
     # a warning in 2.7 but no way to make 2.7 behave like 3 so the warning is useless)
     #
@@ -33,18 +40,63 @@ module JSI
       end
     end
 
+    # we won't use #to_json on classes where it is defined by
+    # JSON::Ext::Generator::GeneratorMethods / JSON::Pure::Generator::GeneratorMethods
+    # this is a bit of a kluge and disregards any singleton class to_json, but it will do.
+    USE_TO_JSON_METHOD = Hash.new do |h, klass|
+      h[klass] = klass.method_defined?(:to_json) &&
+        klass.instance_method(:to_json).owner.name !~ /\AJSON:.*:GeneratorMethods\b/
+    end
+
+    RUBY_REJECT_NAME_CODEPOINTS = [
+      0..31, # C0 control chars
+      %q( !"#$%&'()*+,-./:;<=>?@[\\]^`{|}~).each_codepoint, # printable special chars (note: "_" not included)
+      127..159, # C1 control chars
+    ].inject(Set[], &:merge).freeze
+
+    RUBY_REJECT_NAME_RE = Regexp.new('[' + Regexp.escape(RUBY_REJECT_NAME_CODEPOINTS.to_a.pack('U*')) + ']+').freeze
+
     # is the given name ok to use as a ruby method name?
     def ok_ruby_method_name?(name)
       # must be a string
       return false unless name.respond_to?(:to_str)
       # must not begin with a digit
       return false if name =~ /\A[0-9]/
-      # must not contain characters special to ruby syntax
-      return false if name =~ /[\\\s\#;\.,\(\)\[\]\{\}'"`%\+\-\/\*\^\|&=<>\?:!@\$~]/
+      # must not contain special or control characters
+      return false if name =~ RUBY_REJECT_NAME_RE
 
       return true
     end
 
+    def const_name_from_parts(parts, join: '')
+      parts = parts.map do |part|
+        part = part.dup
+        part[/\A[^a-zA-Z]*/] = ''
+        part[0] = part[0].upcase if part[0]
+        part.gsub!(RUBY_REJECT_NAME_RE, '_')
+        part
+      end
+      if !parts.all?(&:empty?)
+        parts.reject(&:empty?).join(join).freeze
+      else
+        nil
+      end
+    end
+
+    # string or URI → frozen URI
+    # @return [Addressable::URI]
+    def uri(uri)
+      if uri.is_a?(Addressable::URI)
+        if uri.frozen?
+          uri
+        else
+          uri.dup.freeze
+        end
+      else
+        Addressable::URI.parse(uri).freeze
+      end
+    end
+
     # this is the Y-combinator, which allows anonymous recursive functions. for a simple example,
     # to define a recursive function to return the length of an array:
     #
@@ -89,10 +141,13 @@ module JSI
       nil
     end
 
+    # Defines equality methods and #hash (for Hash / Set), based on a method #jsi_fingerprint
+    # implemented by the includer. #jsi_fingerprint is to include the class and any properties
+    # of the instance which constitute its identity.
     module FingerprintHash
       # overrides BasicObject#==
       def ==(other)
-        __id__ == other.__id__ || (other.respond_to?(:jsi_fingerprint) && other.jsi_fingerprint == jsi_fingerprint)
+        __id__ == other.__id__ || (other.is_a?(FingerprintHash) && jsi_fingerprint == other.jsi_fingerprint)
       end
 
       alias_method :eql?, :==
@@ -103,102 +158,28 @@ module JSI
       end
     end
 
-    class MemoMap
-      Result = AttrStruct[*%w(
-        value
-        inputs
-        inputs_hash
-      )]
-
-      class Result
-      end
-
-      def initialize(key_by: nil, &block)
-        @key_by = key_by
-        @block = block
+    module FingerprintHash::Immutable
+      include FingerprintHash
 
-        # each result has its own mutex to update its memoized value thread-safely
-        @result_mutexes = {}
-        # another mutex to thread-safely initialize each result mutex
-        @result_mutexes_mutex = Mutex.new
-
-        @results = {}
-      end
-
-      def [](**inputs)
-        if @key_by
-          key = @key_by.call(**inputs)
-        else
-          key = inputs
-        end
-        result_mutex = @result_mutexes_mutex.synchronize do
-          @result_mutexes[key] ||= Mutex.new
-        end
-
-        result_mutex.synchronize do
-          inputs_hash = inputs.hash
-          if @results.key?(key) && inputs_hash == @results[key].inputs_hash && inputs == @results[key].inputs
-            @results[key].value
-          else
-            value = @block.call(**inputs)
-            @results[key] = Result.new(value: value, inputs: inputs, inputs_hash: inputs_hash)
-            value
-          end
-        end
-      end
-    end
-
-    module Memoize
-      def self.extended(object)
-        object.send(:jsi_initialize_memos)
-      end
-
-      private
-
-      def jsi_initialize_memos
-        @jsi_memomaps_mutex = Mutex.new
-        @jsi_memomaps = {}
-      end
-
-      # @return [Util::MemoMap]
-      def jsi_memomap(name, **options, &block)
-        raise(Bug, 'must jsi_initialize_memos') unless @jsi_memomaps
-        unless @jsi_memomaps.key?(name)
-          @jsi_memomaps_mutex.synchronize do
-            # note: this ||= appears redundant with `unless @jsi_memomaps.key?(name)`,
-            # but that check is not thread safe. this check is.
-            @jsi_memomaps[name] ||= Util::MemoMap.new(**options, &block)
-          end
-        end
-        @jsi_memomaps[name]
-      end
-
-      def jsi_memoize(name, **inputs, &block)
-        jsi_memomap(name, &block)[**inputs]
+      def ==(other)
+        return true if __id__ == other.__id__
+        return false unless other.is_a?(FingerprintHash)
+        # FingerprintHash::Immutable#hash being memoized, comparing that is basically free.
+        # not done with FingerprintHash, its #hash can be expensive.
+        return false if other.is_a?(FingerprintHash::Immutable) && hash != other.hash
+        jsi_fingerprint == other.jsi_fingerprint
       end
-    end
 
-    module Virtual
-      class InstantiationError < StandardError
-      end
+      alias_method :eql?, :==
 
-      # this virtual class is not intended to be instantiated except by its subclasses, which override #initialize
-      def initialize
-        # :nocov:
-        raise(InstantiationError, "cannot instantiate virtual class #{self.class}")
-        # :nocov:
+      def hash
+        @jsi_fingerprint_hash ||= jsi_fingerprint.hash
       end
 
-      # virtual_method is used to indicate that the method calling it must be implemented on the (non-virtual) subclass
-      def virtual_method
-        # :nocov:
-        raise(Bug, "class #{self.class} must implement #{caller_locations.first.label}")
-        # :nocov:
+      def freeze
+        hash
+        super
       end
     end
-
-    public
-
-    extend self
   end
 end