attr_json 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 72f8c96e1a2f0a885c25f6d606cf22a00b813245
-  data.tar.gz: 6b038484149947ae8458addd45d54eabbcff2447
+  metadata.gz: 1033d8a923d5935a8b18e10612883d6756279089
+  data.tar.gz: 8c8b5faf3c24cc27d1d6e382b44c3a63b180826a
 SHA512:
-  metadata.gz: 893ca2a4eabb9457df9abeaaee9b4ac09a068bdd86eede605c76ded7dc3c1f41a39d80fb2ab1de29091808b35b31af749cbf68163ee59df7a006bd133e0c4c9d
-  data.tar.gz: ea4a9e617dabb6b4d5e5779e302f7fb55722588314740509b81ca9d3af64a98523ed41199219608e627b24c35b3673dc59fafaec57568cc6a431d60bfd25c392
+  metadata.gz: 57dec15a2438c7d5fa8b2460afc3c3fcedef01aad80a78bf9bb1511b9be68bb6b7166acb7dc9b1aa25d5614c8cd7eb688fc55433ed9bce1fdb8eab8d1061e22d
+  data.tar.gz: 76f0397e93f14b3ca5ff38c01bf4da3b6d4ea11080414d60e7da2126ecffc78926e087245fe82cc8d30a5d8bc6ffa41d2092b096ed8bcb2ad91149960610a85d

data/README.md

@@ -1,17 +1,20 @@
 # AttrJson
+[![Build Status](https://travis-ci.org/jrochkind/attr_json.svg?branch=master)](https://travis-ci.org/jrochkind/attr_json)
+[![Gem Version](https://badge.fury.io/rb/attr_json.svg)](https://badge.fury.io/rb/attr_json)
+
 
 ActiveRecord attributes stored serialized in a json column, super smooth. For Rails 5.0, 5.1, or 5.2.
 
 Typed and cast like Active Record. Supporting [nested models](#nested), [dirty tracking](#dirty), some [querying](#querying) (with postgres [jsonb](https://www.postgresql.org/docs/9.5/static/datatype-json.html) contains), and [working smoothy with form builders](#forms).
 
-Use your database as a typed object store via ActiveRecord, in the same models right next to ordinary ActiveRecord column-backed attributes and associations. Your json-serialized `attr_json` attributes use as much of the existing ActiveRecord architecture as we can.
+*Use your database as a typed object store via ActiveRecord, in the same models right next to ordinary ActiveRecord column-backed attributes and associations. Your json-serialized `attr_json` attributes use as much of the existing ActiveRecord architecture as we can.*
 
-[![Build Status](https://travis-ci.org/jrochkind/attr_json.svg?branch=master)](https://travis-ci.org/jrochkind/attr_json)
+[Why might you want or not want this?](#why)
 
 AttrJson is pre-1.0. The functionality that is documented here _is_ already implemented (these docs are real, not vaporware) and seems pretty solid. It may still have backwards-incompat changes before 1.0 release. Review and feedback is very welcome.
 
-Developed for postgres, but most features should work with MySQL json columns too. Has not yet been tested.
-
+Developed for postgres, but most features should work with MySQL json columns too, although
+has not yet been tested with MySQL.
 
 ## Basic Use
 
@@ -67,7 +70,7 @@ save the record and then use the standard Rails `*_before_type_cast` method.
 
 ```ruby
 model.save!
-model.attr_jsons_before_type_cast
+model.json_attributes_before_type_cast
 # => string containing: {"my_integer":12,"int_array":[12],"my_datetime":"2016-01-01T17:45:00.000Z"}
 ```
 
@@ -75,7 +78,7 @@ model.attr_jsons_before_type_cast
 
 While the default is to assume you want to serialize in a column called
 `json_attributes`, no worries, of course you can pick whatever named
-jsonb column you like.
+jsonb column you like, class-wide or per-attribute.
 
 ```ruby
 class OtherModel < ActiveRecord::Base
@@ -92,10 +95,10 @@ class OtherModel < ActiveRecord::Base
 end
 ```
 
-## store key different than attribute name
+## Store key different than attribute name/methods
 
 You can also specify that the serialized JSON key
-should be different than the attribute name with the `store_key` argument.
+should be different than the attribute name/methods, by using the `store_key` argument.
 
 ```ruby
 class MyModel < ActiveRecord::Base
@@ -106,9 +109,9 @@ end
 
 model = MyModel.new
 model.special_string = "foo"
-model.attr_jsons # => {"__my_string"=>"foo"}
+model.json_attributes # => {"__my_string"=>"foo"}
 model.save!
-model.attr_jsons_before_type_cast # => string containing: {"__my_string":"foo"}
+model.json_attributes_before_type_cast # => string containing: {"__my_string":"foo"}
 ```
 
 You can of course combine `array`, `default`, `store_key`, and `container_attribute`
@@ -143,7 +146,7 @@ MyModel.jsonb_contains(int_array: [10, 20]) # it contains both, so still finds i
 MyModel.jsonb_contains(int_array: [10, 1000]) # nope, returns nil, has to contain ALL listed in query for array args
 ```
 
-`jsonb_contains` will handlesany `store_key` you have set -- you should specify
+`jsonb_contains` will handle any `store_key` you have set -- you should specify
 attribute name, it'll actually query on store_key. And properly handles any
 `container_attribute` -- it'll look in the proper jsonb column.
 
@@ -218,6 +221,9 @@ m.attr_jsons_before_type_cast
 
 You can nest AttrJson::Model objects inside each other, as deeply as you like.
 
+There is some support for "polymorphic" attributes that can hetereogenously contain instances of different AttrJson::Model classes, see comment docs at [AttrJson::Type::PolymorphicModel](./lib/attr_json/type/polymorphic_model.rb).
+
+
 ```ruby
 class SomeLabels
   include AttrJson::Model
@@ -279,7 +285,7 @@ other key/values in it too.  String values will need to match exactly.
 
 Use with Rails form builders is supported pretty painlessly. Including with [simple_form](https://github.com/plataformatec/simple_form) and [cocoon](https://github.com/nathanvda/cocoon) (integration-tested in CI).
 
-If you have nested AttrJson::Models you'd like to use in your forms much like Rails associated records: Where you would use Rails `accept_nested_attributes_for`, instead `include AttrJson::NestedAttributes` and use `attr_json_accepts_nested_attributes_for`. Multiple levels of nesting are supported.
+If you have nested AttrJson::Models you'd like to use in your forms much like Rails associated records: Where you would use Rails `accepts_nested_attributes_for`, instead `include AttrJson::NestedAttributes` and use `attr_json_accepts_nested_attributes_for`. Multiple levels of nesting are supported.
 
 To get simple_form to properly detect your attribute types, define your attributes with `rails_attribute: true`.
 
@@ -318,6 +324,7 @@ Change-tracking methods are available off the `attr_json_changes` method.
 More options are available, including merging changes from 'ordinary'
 ActiveRecord attributes in. See docs on [Dirty Tracking](./doc_src/dirty_tracking.md)
 
+<a name="why"></a>
 ## Do you want this?
 
 Why might you want this?
@@ -334,7 +341,8 @@ Why might you want this?
 * A "content management system" type project, where you need complex
   structured data of various types, maybe needs to be vary depending
   on plugins or configuration, or for different article types -- but
-  doesn't need to be very queryable generally.
+  doesn't need to be very queryable generally -- or you have means of querying
+  other than a normalized rdbms schema.
 
 * You want to version your models, which is tricky with associations between models.
   Minimize associations by inlining the complex data into one table row.
@@ -381,8 +389,6 @@ Except for the jsonb_contains stuff using postgres jsonb contains operator, I do
 
 ### Possible future features:
 
-* Polymorphic JSON attributes.
-
 * partial updates for json hashes would be really nice: Using postgres jsonb merge operators to only overwrite what changed. In my initial attempts, AR doesn't make it easy to customize this.
 
 * seamless compatibility with ransack

data/lib/attr_json.rb

@@ -7,6 +7,7 @@ require 'attr_json/record'
 require 'attr_json/model'
 require 'attr_json/nested_attributes'
 require 'attr_json/record/query_scopes'
+require 'attr_json/type/polymorphic_model'
 
 # Dirty not supported on Rails 5.0
 if Gem.loaded_specs["activerecord"].version.release >= Gem::Version.new('5.1')

data/lib/attr_json/type/polymorphic_model.rb

@@ -0,0 +1,171 @@
+module AttrJson
+  module Type
+    # AttrJson::Type::PolymorphicModel can be used to create attr_json attributes
+    # that can hold any of various specified AttrJson::Model models. It is a
+    # _somewhat_ experimental feature.
+    #
+    # "polymorphic" may not be quite the right word, but we use it out of analogy
+    # with ActiveRecord [polymorphic assocications](http://guides.rubyonrails.org/association_basics.html#polymorphic-associations),
+    # which it resembles, as well as ActiveRecord [Single-Table Inheritance](http://guides.rubyonrails.org/association_basics.html#single-table-inheritance).
+    #
+    # Similar to these AR features, a PolymorphicModel-typed attribute will serialize the
+    # _model name_ of a given value in a `type` json hash key, so it can deserialize
+    # to the same correct model class.
+    #
+    # It can be used for single-model attributes, or arrays (which can be hetereogenous),
+    # in either AttrJson::Record or nested AttrJson::Models. If `CD`, `Book`, `Person`,
+    # and `Corporation` are all AttrJson::Model classes:
+    #
+    #      attr_json :favorite, AttrJson::Type::PolymorphicAttribute.new(CD, Book)
+    #      attr_json :authors, AttrJson::Type::PolymorphicAttribute.new(Person, Corporation), array: true
+    #
+    # Currently, you need a specific enumerated list of allowed types, and they all
+    # need to be AttrJson::Model classes. You can't at the moment have an "open" polymorphic
+    # type that can accept any AttrJson::Model.
+    #
+    # You can change the json key that the "type" (class name) for a value is stored to,
+    # when creating the type:
+    #
+    #      attr_json, :author, AttrJson::Type::PolymorphicAttribute.new(Person, Corporation, type_key: "__type__")
+    #
+    # But if you already have existing data in the db, that's gonna be problematic to change on the fly.
+    #
+    # You can set attributes with a hash, but it needs to have an appropriate `type` key
+    # (or other as set by `type_key` arg). If it does not, or you try to set a non-hash
+    # value, you will get a AttrJson::Type::PolymorphicModel::TypeError. (maybe a validation
+    # error would be better? but it's not what it does now.)
+    #
+    # **Note** this
+    # also applies to loading non-compliant data from the database. If you have non-compliant
+    # data in the db, the only way to look at it will be as a serialized json string in top-level
+    # {#json_attributes_before_cast} (or other relevant container attribute.)
+    #
+    # There is no built-in form support for PolymorphicModels, you'll have to work it out.
+    #
+    # ## jsonb_contains support
+    #
+    # There is basic jsonb_contains support, but no sophisticated type-casting like normal, beyond
+    # the polymorphic attribute. But you can do:
+    #
+    #      MyRecord.jsonb_contains(author: { name: "foo"})
+    #      MyRecord.jsonb_contains(author: { name: "foo", type: "Corporation"})
+    #      MyRecord.jsonb_contains(author: Corporation.new(name: "foo"))
+    #
+    class PolymorphicModel < ActiveModel::Type::Value
+      class TypeError < ::TypeError ; end
+
+      attr_reader :type_key, :unrecognized_type, :model_type_lookup
+      def initialize(*args)
+        options = { type_key: "type", unrecognized_type: :raise}.merge(
+          args.extract_options!.assert_valid_keys(:type_key, :unrecognized_type)
+        )
+        @type_key = options[:type_key]
+        @unrecognized_type = options[:unrecognized_type]
+
+        model_types = args
+
+        model_types.collect! do |m|
+          if m.respond_to?(:ancestors) && m.ancestors.include?(AttrJson::Model)
+            m.to_type
+          else
+            m
+          end
+        end
+
+        if bad_arg = model_types.find { |m| !m.is_a? AttrJson::Type::Model }
+          raise ArgumentError, "#{self.class.name} only works with AttrJson::Model / AttrJson::Type::Model, not '#{bad_arg.inspect}'"
+        end
+        if type_key_conflict = model_types.find { |m| m.model.attr_json_registry.has_attribute?(@type_key) }
+          raise ArgumentError, "conflict between type_key '#{@type_key}' and an existing attr_json in #{type_key_conflict.model}"
+        end
+
+        @model_type_lookup = model_types.collect do |type|
+          [type.model.name, type]
+        end.to_h
+      end
+
+      def model_names
+        model_type_lookup.keys
+      end
+
+      def model_types
+        model_type_lookup.values
+      end
+
+      # ActiveModel method, symbol type label
+      def type
+        @type ||= "any_of_#{model_types.collect(&:type).collect(&:to_s).join('_')}".to_sym
+      end
+
+      def cast(v)
+        if v.nil?
+          v
+        elsif model_names.include?(v.class.name)
+          v
+        elsif v.respond_to?(:to_hash)
+          cast_from_hash(v.to_hash)
+        elsif v.respond_to?(:to_h)
+          cast_from_hash(v.to_h)
+        else
+          raise_bad_model_name(v.class, v)
+        end
+      end
+
+      def serialize(v)
+        model_name = v.class.name
+        type = type_for_model_name(model_name)
+
+        raise_bad_model_name(model_name, v) if type.nil?
+
+        type.serialize(v).merge(type_key => model_name)
+      end
+
+      def deserialize(v)
+        cast(v)
+      end
+
+      def type_for_model_name(model_name)
+        model_type_lookup[model_name]
+      end
+
+      # This is used only by our own keypath-chaining query stuff.
+      # For PolymorphicModel type, it does no type casting, just
+      # sticks whatever you gave it in, which needs to be json-compat
+      # values.
+      def value_for_contains_query(key_path_arr, value)
+        hash_arg = {}
+        key_path_arr.each.with_index.inject(hash_arg) do |hash, (n, i)|
+          if i == key_path_arr.length - 1
+            hash[n] = value
+          else
+            hash[n] = {}
+          end
+        end
+        hash_arg
+      end
+
+      protected
+
+      def raise_missing_type_key(value)
+        raise TypeError, "AttrJson::Type::Polymorphic can't cast without '#{type_key}' key: #{value}"
+      end
+
+      def raise_bad_model_name(name, value)
+        raise TypeError, "This AttrJson::Type::PolymorphicType can only include {#{model_names.join(', ')}}, not '#{name}': #{value.inspect}"
+      end
+
+      def cast_from_hash(hash)
+        new_hash = hash.stringify_keys
+        model_name = new_hash.delete(type_key.to_s)
+
+        raise_missing_type_key(hash) if model_name.nil?
+
+        type = type_for_model_name(model_name)
+
+        raise_bad_model_name(model_name, hash) if type.nil?
+
+        type.cast(new_hash)
+      end
+    end
+  end
+end

data/lib/attr_json/version.rb

@@ -1,3 +1,3 @@
 module AttrJson
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: attr_json
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jonathan Rochkind
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-28 00:00:00.000000000 Z
+date: 2018-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -122,6 +122,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- attr_json.gemspec
 - bin/console
 - bin/rake
 - bin/rspec
@@ -129,7 +130,6 @@ files:
 - config.ru
 - doc_src/dirty_tracking.md
 - doc_src/forms.md
-- json_attribute.gemspec
 - lib/attr_json.rb
 - lib/attr_json/attribute_definition.rb
 - lib/attr_json/attribute_definition/registry.rb
@@ -146,6 +146,7 @@ files:
 - lib/attr_json/type/array.rb
 - lib/attr_json/type/container_attribute.rb
 - lib/attr_json/type/model.rb
+- lib/attr_json/type/polymorphic_model.rb
 - lib/attr_json/version.rb
 - playground_models.rb
 homepage: https://github.com/jrochkind/attr_json