jsi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec49b425e6253b4ff1bf14b1d2218fe1bd5c905194d169faab948820a2e17302
+  data.tar.gz: 56d79d38177b3272ba094e21def5083896a12c8157346909b739927fbe52e542
+SHA512:
+  metadata.gz: cd3d72c29b166c0bb7b1a5970742e5538a79fda1a16359fadb35dd3b6ea65911481f40ab8e4f79ec9da56247f385ee6168ad2aeeaec0f4a6735da7370aba8005
+  data.tar.gz: c476fb40d83d9b98568bc067375ddf2f95953fe886284ab889fed11df51b12bd3c8c079bb6dc7e0dec52fa38175e61eb1d784b83d3b707cc984100670f8a592a

data/.simplecov

@@ -0,0 +1 @@
+SimpleCov.start

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# v0.0.1
+
+- extracted JSI from Scorpio

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ethan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# JSI: JSON-Schema Instantiation
+
+[![Build Status](https://travis-ci.org/notEthan/jsi.svg?branch=master)](https://travis-ci.org/notEthan/jsi)
+[![Coverage Status](https://coveralls.io/repos/github/notEthan/jsi/badge.svg)](https://coveralls.io/github/notEthan/jsi)
+
+JSI represents JSON-schemas as ruby classes, and schema instances as instances of those classes.
+
+A JSI class aims to be a fairly unobtrusive wrapper around its instance. It adds accessors for known property names, validation methods, and a few other nice things. Mostly though, you use a JSI as you would use its underlying data.
+
+## Example
+
+Words are boring, let's code. Here's a schema in yaml:
+
+```yaml
+description: "A Contact"
+type: "object"
+properties:
+  name: {type: "string"}
+  phone:
+    type: "array"
+    items:
+      type: "object"
+      properties:
+        location: {type: "string"}
+        number: {type: "string"}
+```
+
+And here's an instance of that schema with JSI:
+
+```ruby
+Contact = JSI.class_for_schema(YAML.load_file('contact.schema.yml'))
+```
+
+This definition gives you not just the Contact class, but classes for the whole nested structure. So, if we construct an instance like:
+
+```ruby
+bill = Contact.new(name: 'bill', phone: [{location: 'home', number: '555'}], nickname: 'big b')
+# => #{<Contact fragment="#">
+# #{<Contact fragment="#">
+#   "phone" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone"] fragment="#/phone">
+#     #{<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items"] fragment="#/phone/0"> "location" => "home", "number" => "555"}
+#   ],
+#   "nickname" => "big b"
+# }
+```
+
+The nested classes can be seen as `JSI::SchemaClasses[schema_id]` where schema_id is a generated value.
+
+We get accessors for the Contact:
+
+```ruby
+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:
+
+```ruby
+bill.phone.map(&:location)
+# => ["home"]
+```
+
+We also get validations, as you'd expect given that's largely what json-schema exists to do:
+
+```ruby
+bill.validate
+# => true
+```
+
+... and validations on the nested schema instances (#phone here), showing in this example validation failure:
+
+```ruby
+bad = Contact.new(phone: [{number: [5, 5, 5]}])
+# => #{<Contact fragment="#">
+#   "phone" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone"] fragment="#/phone">
+#     #{<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items"] fragment="#/phone/0">
+#       "number" => #[<JSI::SchemaClasses["594126e3-ea3c-5d9a-b5f4-7423a8701f97#/properties/phone/items/properties/number"] fragment="#/phone/0/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-ea3c-5d9a-b5f4-7423a8701f97"]
+```
+
+Since the underlying instance is a ruby hash (json object), we can use it like a hash with #[] or, say, #transform_values:
+
+```ruby
+bill.transform_values(&:size)
+# => {"name" => 4, "phone" => 1, "nickname" => 5}
+bill['nickname']
+# => "big b"
+```
+
+There's plenty more JSI has to offer, but this should give you a pretty good idea of basic usage.
+
+## Terminology
+
+- JSI::Base is the base class from which other classes representing JSON-Schemas inherit.
+- a JSI class refers to a class representing a schema, a subclass of JSI::Base.
+- "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 is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
+- a schema refers to a json-schema. a JSI::Schema represents such a json-schema. a JSI class allow instantiation of such a schema.
+
+## JSI classes
+
+A JSI class (that is, subclass of JSI::Base) is a starting point but obviously you want your own methods, so you reopen the class as you would any other. referring back to the Example section above, here's an example:
+
+```ruby
+class Contact
+  def full_address
+    address.values.join(", ")
+  end
+  def name
+    super + ' esq.'
+  end
+  def name=(name)
+    super(name.chomp(' esq.'))
+  end
+end
+
+bill.name
+# => "bill esq."
+bill.name = 'rob esq.'
+# => "rob esq."
+bill.instance['name']
+# => "rob"
+```
+
+Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers (these accessor methods are defined on an included class instead of the JSI class for this reason). You can also use [] and []=, of course, with the same effect.
+
+## ActiveRecord serialization
+
+A really excellent place to use JSI is when dealing with serialized columns in ActiveRecord.
+
+Let's say you're sticking to json types in the database - you have to do so if you're using json columns, or json serialization, and if you have dealt with arbitrary yaml- or marshal-serialized objects in ruby, you have probably found that approach has its shortcomings when the implementation of your classes changes.
+
+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 SchemaInstanceJSONCoder. The objects in your database are simple json types, and your ruby classes are extensible and have the accessors you get from a JSI class hierarchy. Here's an example:
+
+```ruby
+class User < ActiveRecord::Base
+  serialize :contacts, JSI::SchemaInstanceJSONCoder.new(Contact, array: true)
+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.
+
+## Keying Hashes (JSON Objects)
+
+Unlike Ruby, JSON only supports string keys. JSI converts symbols to strings for its internal hash keys (much like ActiveSupport::HashWithIndifferentAccess). JSI accepts symbols to refer to its string hash keys for instantiation, but does not currently transform symbols to strings everywhere else, e.g. `bill[:name]` is `nil` whereas `bill['name']` is `"bill"`.
+
+## Contributing
+
+Issues and pull requests are welcome on GitHub at https://github.com/notEthan/jsi.
+
+## License
+
+JSI is open source software available under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile.rb

@@ -0,0 +1,9 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/jsi.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "jsi/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "jsi"
+  spec.version = JSI::VERSION
+  spec.authors = ["Ethan"]
+  spec.email   = ["ethan@unth"]
+
+  spec.summary     = "JSI: JSON-Schema instantiation"
+  spec.description = "JSI represents json-schemas as ruby classes and json-schema instances as instances of those classes"
+  spec.homepage    = "https://github.com/notEthan/jsi"
+  spec.license     = "MIT"
+  ignore_files = %w(.gitignore .travis.yml Gemfile test)
+  ignore_files_re = %r{\A(#{ignore_files.map { |f| Regexp.escape(f) }.join('|')})(/|\z)}
+  Dir.chdir(File.expand_path('..', __FILE__)) do
+    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")
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  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", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-around"
+  spec.add_development_dependency "minitest-reporters"
+end

data/lib/jsi.rb

@@ -0,0 +1,28 @@
+require "jsi/version"
+require "pp"
+require "jsi/json-schema-fragments"
+require "jsi/util"
+
+module JSI
+  # generally put in code paths that are not expected to be valid control flow paths.
+  # rather a NotImplementedCorrectlyError. but that's too long.
+  class Bug < NotImplementedError
+  end
+
+  autoload :JSON, 'jsi/json'
+  autoload :Typelike, 'jsi/typelike_modules'
+  autoload :Hashlike, 'jsi/typelike_modules'
+  autoload :Arraylike, 'jsi/typelike_modules'
+  autoload :Schema, 'jsi/schema'
+  autoload :Base, 'jsi/base'
+  autoload :BaseArray, 'jsi/base'
+  autoload :BaseHash, 'jsi/base'
+  autoload :SchemaClasses, 'jsi/base'
+  autoload :ObjectJSONCoder, 'jsi/schema_instance_json_coder'
+  autoload :StructJSONCoder, 'jsi/struct_json_coder'
+  autoload :SchemaInstanceJSONCoder,'jsi/schema_instance_json_coder'
+
+  def self.class_for_schema(*a, &b)
+    SchemaClasses.class_for_schema(*a, &b)
+  end
+end

data/lib/jsi/base.rb

@@ -0,0 +1,325 @@
+require 'json'
+require 'jsi/typelike_modules'
+
+module JSI
+  # base class for representing an instance of an instance described by a schema
+  class Base
+    include Memoize
+    include Enumerable
+
+    class << self
+      def schema_id
+        schema.schema_id
+      end
+
+      def inspect
+        if !respond_to?(:schema)
+          super
+        elsif !name || name =~ /\AJSI::SchemaClasses::/
+          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
+        else
+          %Q(#{name} (#{schema_id}))
+        end
+      end
+      def to_s
+        if !respond_to?(:schema)
+          super
+        elsif !name || name =~ /\AJSI::SchemaClasses::/
+          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
+        else
+          name
+        end
+      end
+
+      def schema_classes_const_name
+        name = schema.schema_id.gsub(/[^\w]/, '_')
+        name = 'X' + name unless name[/\A[a-zA-Z_]/]
+        name = name[0].upcase + name[1..-1]
+        name
+      end
+
+      def name
+        unless super
+          SchemaClasses.const_set(schema_classes_const_name, self)
+        end
+        super
+      end
+    end
+
+    def initialize(instance, origin: nil)
+      unless respond_to?(:schema)
+        raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #schema. please use JSI.class_for_schema")
+      end
+
+      @origin = origin || self
+      self.instance = instance
+
+      if @instance.is_a?(JSI::JSON::HashNode)
+        extend BaseHash
+      elsif @instance.is_a?(JSI::JSON::ArrayNode)
+        extend BaseArray
+      end
+    end
+
+    attr_reader :instance
+
+    # each is overridden by BaseHash or BaseArray when appropriate. the base
+    # #each is not actually implemented, along with all the methods of Enumerable.
+    def each
+      raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{instance.pretty_inspect.chomp}"
+    end
+
+    def parents
+      parent = @origin
+      (@origin.instance.path.size...self.instance.path.size).map do |i|
+        parent.tap do
+          parent = parent[self.instance.path[i]]
+        end
+      end.reverse
+    end
+    def parent
+      parents.first
+    end
+
+    def deref
+      derefed = instance.deref
+      if derefed.object_id == instance.object_id
+        self
+      else
+        self.class.new(derefed, origin: @origin)
+      end
+    end
+
+    def modified_copy(&block)
+      modified_instance = instance.modified_copy(&block)
+      self.class.new(modified_instance, origin: @origin)
+    end
+
+    def fragment
+      instance.fragment
+    end
+
+    def fully_validate
+      schema.fully_validate(instance)
+    end
+    def validate
+      schema.validate(instance)
+    end
+    def validate!
+      schema.validate!(instance)
+    end
+    def inspect
+      "\#<#{self.class.to_s} #{instance.inspect}>"
+    end
+    def pretty_print(q)
+      q.instance_exec(self) do |obj|
+        text "\#<#{obj.class.to_s}"
+        group_sub {
+          nest(2) {
+            breakable ' '
+            pp obj.instance
+          }
+        }
+        breakable ''
+        text '>'
+      end
+    end
+
+    def object_group_text
+      instance.object_group_text
+    end
+
+    def as_json(*opt)
+      Typelike.as_json(instance, *opt)
+    end
+
+    def fingerprint
+      {class: self.class, instance: instance}
+    end
+    include FingerprintHash
+
+    private
+    def instance=(thing)
+      if instance_variable_defined?(:@instance)
+        raise(JSI::Bug, "overwriting instance is not supported")
+      end
+      if thing.is_a?(Base)
+        warn "assigning instance to a Base instance is incorrect. received: #{thing.pretty_inspect.chomp}"
+        @instance = JSI.deep_stringify_symbol_keys(thing.instance)
+      elsif thing.is_a?(JSI::JSON::Node)
+        @instance = JSI.deep_stringify_symbol_keys(thing)
+      else
+        @instance = JSI::JSON::Node.new_by_type(JSI.deep_stringify_symbol_keys(thing), [])
+      end
+    end
+
+    def subscript_assign(subscript, value)
+      clear_memo(:[], subscript)
+      if value.is_a?(Base)
+        instance[subscript] = value.instance
+      else
+        instance[subscript] = value
+      end
+    end
+  end
+
+  # this module is just a namespace for schema classes.
+  module SchemaClasses
+    extend Memoize
+    def self.[](schema_id)
+      @classes_by_id[schema_id]
+    end
+    @classes_by_id = {}
+  end
+
+  def SchemaClasses.class_for_schema(schema_object)
+    if schema_object.is_a?(JSI::Schema)
+      schema__ = schema_object
+    else
+      schema__ = JSI::Schema.new(schema_object)
+    end
+
+    memoize(:class_for_schema, schema__) do |schema_|
+      begin
+        begin
+          Class.new(Base).instance_exec(schema_) do |schema|
+            begin
+              include(JSI.module_for_schema(schema))
+
+              SchemaClasses.instance_exec(self) { |klass| @classes_by_id[klass.schema_id] = klass }
+
+              self
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def self.module_for_schema(schema_object)
+    if schema_object.is_a?(JSI::Schema)
+      schema__ = schema_object
+    else
+      schema__ = JSI::Schema.new(schema_object)
+    end
+
+    memoize(:module_for_schema, schema__) do |schema_|
+      Module.new.tap do |m|
+        m.instance_exec(schema_) do |schema|
+          define_method(:schema) { schema }
+          define_singleton_method(:schema) { schema }
+          define_singleton_method(:included) do |includer|
+            includer.send(:define_singleton_method, :schema) { schema }
+          end
+
+          define_singleton_method(:schema_id) do
+            schema.schema_id
+          end
+          define_singleton_method(:inspect) do
+            %Q(#<Module for Schema: #{schema_id}>)
+          end
+
+          if schema.describes_hash?
+            instance_method_modules = [m, Base, BaseArray, BaseHash]
+            instance_methods = instance_method_modules.map do |mod|
+              mod.instance_methods + mod.private_instance_methods
+            end.inject(Set.new, &:|)
+            accessors_to_define = schema.described_hash_property_names.map(&:to_s) - instance_methods.map(&:to_s)
+            accessors_to_define.each do |property_name|
+              define_method(property_name) do
+                if respond_to?(:[])
+                  self[property_name]
+                else
+                  raise(NoMethodError, "instance does not respond to []; cannot call reader `#{property_name}' for: #{pretty_inspect.chomp}")
+                end
+              end
+              define_method("#{property_name}=") do |value|
+                if respond_to?(:[]=)
+                  self[property_name] = value
+                else
+                  raise(NoMethodError, "instance does not respond to []=; cannot call writer `#{property_name}=' for: #{pretty_inspect.chomp}")
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  module BaseHash
+    # Hash methods
+    def each
+      return to_enum(__method__) { instance.size } unless block_given?
+      instance.each_key { |k| yield(k, self[k]) }
+      self
+    end
+
+    def to_hash
+      inject({}) { |h, (k, v)| h[k] = v; h }
+    end
+
+    include Hashlike
+
+    # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
+    SAFE_KEY_ONLY_METHODS.each do |method_name|
+      define_method(method_name) { |*a, &b| instance.public_send(method_name, *a, &b) }
+    end
+
+    def [](property_name_)
+      memoize(:[], property_name_) do |property_name|
+        begin
+          property_schema = schema.subschema_for_property(property_name)
+          property_schema = property_schema && property_schema.match_to_instance(instance[property_name])
+
+          if property_schema && instance[property_name].is_a?(JSON::Node)
+            JSI.class_for_schema(property_schema).new(instance[property_name], origin: @origin)
+          else
+            instance[property_name]
+          end
+        end
+      end
+    end
+    def []=(property_name, value)
+      subscript_assign(property_name, value)
+    end
+  end
+
+  module BaseArray
+    def each
+      return to_enum(__method__) { instance.size } unless block_given?
+      instance.each_index { |i| yield(self[i]) }
+      self
+    end
+
+    def to_ary
+      to_a
+    end
+
+    include Arraylike
+
+    # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a).
+    # we override these methods from Arraylike
+    SAFE_INDEX_ONLY_METHODS.each do |method_name|
+      define_method(method_name) { |*a, &b| instance.public_send(method_name, *a, &b) }
+    end
+
+    def [](i_)
+      memoize(:[], i_) do |i|
+        begin
+          index_schema = schema.subschema_for_index(i)
+          index_schema = index_schema && index_schema.match_to_instance(instance[i])
+
+          if index_schema && instance[i].is_a?(JSON::Node)
+            JSI.class_for_schema(index_schema).new(instance[i], origin: @origin)
+          else
+            instance[i]
+          end
+        end
+      end
+    end
+    def []=(i, value)
+      subscript_assign(i, value)
+    end
+  end
+end