jsi 0.6.0 → 0.8.0

data/lib/jsi/schema_registry.rb

@@ -14,6 +14,7 @@ module JSI
 
     # an exception raised when a URI we are looking for has not been registered
     class ResourceNotFound < StandardError
+      attr_accessor :uri
     end
 
     def initialize
@@ -24,8 +25,8 @@ module JSI
 
     # registers the given resource and/or schema resources it contains in the registry.
     #
-    # each child of the resource (including the resource itself) is registered if it is a schema that
-    # has an absolute URI (generally defined by the '$id' keyword).
+    # each descendent node of the resource (including the resource itself) is registered if it is a schema
+    # that has an absolute URI (generally defined by the '$id' keyword).
     #
     # the given resource itself will be registered, whether or not it is a schema, if it is the root
     # of its document and was instantiated with the option `uri` specified.
@@ -45,12 +46,12 @@ module JSI
       # allow for registration of resources at the root of a document whether or not they are schemas.
       # jsi_schema_base_uri at the root comes from the `uri` parameter to new_jsi / new_schema.
       if resource.jsi_schema_base_uri && resource.jsi_ptr.root?
-        register_single(resource.jsi_schema_base_uri, resource)
+        internal_store(resource.jsi_schema_base_uri, resource)
       end
 
-      resource.jsi_each_child_node do |node|
+      resource.jsi_each_descendent_node do |node|
         if node.is_a?(JSI::Schema) && node.schema_absolute_uri
-          register_single(node.schema_absolute_uri, node)
+          internal_store(node.schema_absolute_uri, node)
         end
       end
 
@@ -72,12 +73,18 @@ module JSI
     #
     # the block would normally load JSON from the filesystem or similar.
     #
-    # @param uri [Addressable::URI]
+    # @param uri [#to_str]
     # @yieldreturn [JSI::Base] a JSI instance containing the resource identified by the given uri
     # @return [void]
     def autoload_uri(uri, &block)
-      uri = Addressable::URI.parse(uri)
-      ensure_uri_absolute(uri)
+      uri = registration_uri(uri)
+      mutating
+      unless block
+        raise(ArgumentError, ["#{SchemaRegistry}#autoload_uri must be invoked with a block", "URI: #{uri}"].join("\n"))
+      end
+      if @autoload_uris.key?(uri)
+        raise(Collision, ["already registered URI for autoload", "URI: #{uri}", "loader: #{@autoload_uris[uri]}"].join("\n"))
+      end
       @autoload_uris[uri] = block
       nil
     end
@@ -86,22 +93,50 @@ module JSI
     # @return [JSI::Base]
     # @raise [JSI::SchemaRegistry::ResourceNotFound]
     def find(uri)
-      uri = Addressable::URI.parse(uri)
-      ensure_uri_absolute(uri)
-      if @autoload_uris.key?(uri) && !@resources.key?(uri)
-        register(@autoload_uris[uri].call)
+      uri = registration_uri(uri)
+      if @autoload_uris.key?(uri)
+        autoloaded = @autoload_uris[uri].call
+        register(autoloaded)
+        @autoload_uris.delete(uri)
       end
-      registered_uris = @resources.keys
-      if !registered_uris.include?(uri)
-        raise(ResourceNotFound, "URI #{uri} is not registered. registered URIs:\n#{registered_uris.join("\n")}")
+      if !@resources.key?(uri)
+        if autoloaded
+          msg = [
+            "URI #{uri} was registered with autoload_uri but the result did not contain a resource with that URI.",
+            "the resource resulting from autoload_uri was:",
+            autoloaded.pretty_inspect.chomp,
+          ]
+        else
+          msg = ["URI #{uri} is not registered. registered URIs:", *(@resources.keys | @autoload_uris.keys)]
+        end
+        raise(ResourceNotFound.new(msg.join("\n")).tap { |e| e.uri = uri })
       end
       @resources[uri]
     end
 
+    def inspect
+      [
+        "#<#{self.class}",
+        *[['resources', @resources.keys], ['autoload', @autoload_uris.keys]].map do |label, uris|
+          [
+            "  #{label} (#{uris.size})#{uris.empty? ? "" : ":"}",
+            *uris.map do |uri|
+              "    #{uri}"
+            end,
+          ]
+        end.inject([], &:+),
+        '>',
+      ].join("\n").freeze
+    end
+
+    def to_s
+      inspect
+    end
+
     def dup
       self.class.new.tap do |reg|
         @resources.each do |uri, resource|
-          reg.register_single(uri, resource)
+          reg.internal_store(uri, resource)
         end
         @autoload_uris.each do |uri, autoload|
           reg.autoload_uri(uri, &autoload)
@@ -109,13 +144,21 @@ module JSI
       end
     end
 
+    def freeze
+      @resources.freeze
+      @autoload_uris.freeze
+      @resources_mutex = nil
+      super
+    end
+
     protected
     # @param uri [Addressable::URI]
     # @param resource [JSI::Base]
     # @return [void]
-    def register_single(uri, resource)
+    def internal_store(uri, resource)
+      mutating
       @resources_mutex.synchronize do
-        ensure_uri_absolute(uri)
+        uri = registration_uri(uri)
         if @resources.key?(uri)
           if @resources[uri] != resource
             raise(Collision, "URI collision on #{uri}.\nexisting:\n#{@resources[uri].pretty_inspect.chomp}\nnew:\n#{resource.pretty_inspect.chomp}")
@@ -129,13 +172,29 @@ module JSI
 
     private
 
-    def ensure_uri_absolute(uri)
+    # registration URIs are
+    # - absolute
+    #   - without fragment
+    #   - not relative
+    # - normalized
+    # - frozen
+    # @param uri [#to_str]
+    # @return [Addressable::URI]
+    def registration_uri(uri)
+      uri = Util.uri(uri)
       if uri.fragment
         raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access URI with fragment: #{uri}")
       end
       if uri.relative?
         raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access relative URI: #{uri}")
       end
+      uri.normalize.freeze
+    end
+
+    def mutating
+      if frozen?
+        raise(FrozenError, "cannot modify frozen #{self.class}")
+      end
     end
   end
 end

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
@@ -42,12 +40,25 @@ module JSI
     # @yieldreturn [JSI::Schema]
     # @raise [JSI::Schema::NotASchemaError]
     def initialize(enum, &block)
+      if enum.is_a?(Schema)
+        raise(ArgumentError, [
+          "#{SchemaSet} initialized with a #{Schema}",
+          "you probably meant to pass that to #{SchemaSet}[]",
+          "or to wrap that schema in a Set or Array for #{SchemaSet}.new",
+          "given: #{enum.pretty_inspect.chomp}",
+        ].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) }
       if !not_schemas.empty?
         raise(Schema::NotASchemaError, [
-          "JSI::SchemaSet initialized with non-schema objects:",
+          "#{SchemaSet} initialized with non-schema objects:",
           *not_schemas.map { |ns| ns.pretty_inspect.chomp },
         ].join("\n"))
       end
@@ -55,33 +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)
 
-      jsi = JSI::SchemaClasses.class_for_schemas(applied_schemas).new(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))
@@ -89,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)
@@ -102,13 +159,40 @@ module JSI
       nil
     end
 
+    # 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#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))
+    end
+
+    # yields each child applicator schema which applies to the child of
+    # the given instance on the given token.
+    #
+    # @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)
+      return to_enum(__method__, token, instance) unless block
+
+      each do |schema|
+        schema.each_child_applicator_schema(token, instance, &block)
+      end
+
+      nil
+    end
+
     # validates the given instance against our schemas
     #
     # @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
@@ -120,19 +204,21 @@ module JSI
 
     # @return [String]
     def inspect
-      "#{self.class}[#{map(&:inspect).join(", ")}]"
+      -"#{self.class}[#{map(&:inspect).join(", ")}]"
+    end
+
+    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

@@ -1,12 +1,26 @@
 # frozen_string_literal: true
 
 module JSI
-  SimpleWrap = JSI::JSONSchemaOrgDraft06.new_schema_module({
-    "additionalProperties": {"$ref": "#"},
-    "items": {"$ref": "#"}
-  })
+  simple_wrap_implementation = Module.new do
+    def internal_child_applicate_keywords(token, instance)
+      yield self
+    end
+
+    def internal_inplace_applicate_keywords(instance, visited_refs)
+      yield self
+    end
+
+    def internal_validate_keywords(result_builder)
+    end
+  end
+
+  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
   end
+
+  SimpleWrap::Implementation = simple_wrap_implementation
+  SimpleWrap::METASCHEMA = simple_wrap_metaschema
 end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module JSI
+  module Util::Private
+    # like a Struct, but stores all the attributes in one @attributes Hash, instead of individual instance
+    # variables for each attribute.
+    # this tends to be easier to work with and more flexible. keys which are symbols are converted to strings.
+    class AttrStruct
+      class AttrStructError < StandardError
+      end
+
+      class UndefinedAttributeKey < AttrStructError
+      end
+
+      class << self
+        # creates a AttrStruct subclass with the given attribute keys.
+        # @param attribute_keys [Enumerable<String, Symbol>]
+        def subclass(*attribute_keys)
+          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|
+            klass.define_singleton_method(:attribute_keys) { all_attribute_keys }
+
+            attribute_keys.each do |attribute_key|
+              # reader
+              klass.send(:define_method, attribute_key) do
+                @attributes[attribute_key]
+              end
+
+              # writer
+              klass.send(:define_method, "#{attribute_key}=") do |value|
+                @attributes[attribute_key] = value
+              end
+            end
+          end
+        end
+
+        alias_method :[], :subclass
+
+        # the attribute keys defined for this class
+        # @return [Set<String>]
+        def attribute_keys
+          # empty for AttrStruct itself; redefined on each subclass
+          Util::Private::EMPTY_SET
+        end
+
+        # returns a frozen string, given a string or symbol.
+        # returns anything else as-is for the caller to handle.
+        # @api private
+        def convert_key(key)
+          # TODO use Symbol#name when available on supported rubies
+          key.is_a?(Symbol) ? key.to_s.freeze : key.frozen? ? key : key.is_a?(String) ? key.dup.freeze : key
+        end
+      end
+
+      def initialize(attributes = {})
+        unless attributes.respond_to?(:to_hash)
+          raise(TypeError, "expected attributes to be a Hash; got: #{attributes.inspect}")
+        end
+        @attributes = {}
+        attributes.to_hash.each do |k, v|
+          @attributes[self.class.convert_key(k)] = v
+        end
+        bad = @attributes.keys.reject { |k| class_attribute_keys.include?(k) }
+        unless bad.empty?
+          raise UndefinedAttributeKey, "undefined attribute keys: #{bad.map(&:inspect).join(', ')}"
+        end
+      end
+
+      def [](key)
+        @attributes[key.is_a?(Symbol) ? key.to_s : key]
+      end
+
+      def []=(key, value)
+        key = self.class.convert_key(key)
+        unless class_attribute_keys.include?(key)
+          raise UndefinedAttributeKey, "undefined attribute key: #{key.inspect}"
+        end
+        @attributes[key] = value
+      end
+
+      # @return [String]
+      def inspect
+        -"\#<#{self.class.name}#{@attributes.map { |k, v| " #{k}: #{v.inspect}" }.join(',')}>"
+      end
+
+      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(2) {
+            q.breakable(' ') if !@attributes.empty?
+            q.seplist(@attributes, nil, :each_pair) { |k, v|
+              q.group {
+                q.text k
+                q.text ': '
+                q.pp v
+              }
+            }
+        }
+        q.breakable('') if !@attributes.empty?
+        q.text '>'
+      end
+
+      # (see AttrStruct.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}.freeze
+      end
+    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