attr_json 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 72f8c96e1a2f0a885c25f6d606cf22a00b813245
+  data.tar.gz: 6b038484149947ae8458addd45d54eabbcff2447
+SHA512:
+  metadata.gz: 893ca2a4eabb9457df9abeaaee9b4ac09a068bdd86eede605c76ded7dc3c1f41a39d80fb2ab1de29091808b35b31af749cbf68163ee59df7a006bd133e0c4c9d
+  data.tar.gz: ea4a9e617dabb6b4d5e5779e302f7fb55722588314740509b81ca9d3af64a98523ed41199219608e627b24c35b3673dc59fafaec57568cc6a431d60bfd25c392

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/internal/tmp/cache
+/tmp/
+.byebug_history

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,17 @@
+#
+dist: trusty
+sudo: false
+addons:
+  postgresql: '9.4'
+  chrome: stable
+language: ruby
+cache: bundler
+rvm:
+  - 2.4
+  - 2.5.0
+env:
+  - RAILS_GEM="~> 5.0.0" PG_GEM="~> 0.18"
+  - RAILS_GEM="~> 5.1.0"
+  - RAILS_GEM=">= 5.2.0.rc2,< 5.3.0"
+before_install:
+  - gem install bundler -v 1.14.6

data/.yardopts

@@ -0,0 +1 @@
+- doc_src/**/*.md --plugin activesupport-concern --markup=markdown

data/Gemfile

@@ -0,0 +1,42 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in attr_json.gemspec
+gemspec
+
+# for our integration test in a real rails env, we add em in development too,
+# so we can bring up the app or a console in development to play with it.
+group :test, :development do
+  gem 'combustion', '~> 0.9.0'
+  # all of rails is NOT a dependency, just activerecord.
+  # But we use it for integration testing with combustion. Hmm, a bit annoying
+  # that now our other tests can't be sure they're depending, this might not
+  # be the way to do it.
+  gem "rails", ENV["RAILS_GEM"] && ENV["RAILS_GEM"].split(",")
+
+  # Rails 5.0 won't work with pg 1.0, but that isn't actually in it's gemspec.
+  # So we specify a compatible PG_GEM spec when testing with rails 5.
+  ENV['PG_GEM'] ||= ">= 0.18.1"
+  gem "pg", ENV['PG_GEM']
+
+  gem "rspec-rails", "~> 3.7"
+  gem "simple_form", ">= 4.0"
+  gem 'cocoon', ">= 1.2"
+  gem 'jquery-rails'
+  gem 'capybara', "~> 3.0"
+  gem "chromedriver-helper"
+  gem "selenium-webdriver"
+  # rails 5.1+ includes it by default, but rails 5.0 needs it:
+  gem 'rails-ujs', require: false
+end
+
+if ENV['RAILS_GEM']
+  gem "activerecord", ENV['RAILS_GEM'].split(",")
+
+  # This shouldn't really be needed, but seems to maybe be a bundler bug,
+  # this makes standalone_migrations dependencies resolve properly even when our
+  # RAILS_REQ is for 5.2.0.rc2. If in the future you delete this and everything
+  # still passes, feel free to remove.
+  gem "railties", ENV['RAILS_GEM'].split(",")
+end
+
+gem "byebug"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Jonathan Rochkind
+
+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,426 @@
+# AttrJson
+
+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.
+
+[![Build Status](https://travis-ci.org/jrochkind/attr_json.svg?branch=master)](https://travis-ci.org/jrochkind/attr_json)
+
+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.
+
+
+## Basic Use
+
+```ruby
+# migration
+class CreatMyModels < ActiveRecord::Migration[5.0]
+  def change
+    create_table :my_models do |t|
+      t.jsonb :json_attributes
+    end
+
+    # If you plan to do any querying with jsonb_contains below..
+    add_index :my_models, :json_attributes, using: :gin
+  end
+end
+
+class MyModel < ActiveRecord::Base
+   include AttrJson::Record
+
+   # use any ActiveModel::Type types: string, integer, decimal (BigDecimal),
+   # float, datetime, boolean.
+   attr_json :my_string, :string
+   attr_json :my_integer, :integer
+   attr_json :my_datetime, :datetime
+
+   # You can have an _array_ of those things too.
+   attr_json :int_array, :integer, array: true
+
+   #and/or defaults
+   attr_json :int_with_default, :integer, default: 100
+end
+```
+
+These attributes have type-casting behavior very much like ordinary ActiveRecord values.
+
+```ruby
+model = MyModel.new
+model.my_integer = "12"
+model.my_integer # => 12
+model.int_array = "12"
+model.int_array # => [12]
+model.my_datetime = "2016-01-01 17:45"
+model.my_datetime # => a Time object representing that, just like AR would cast
+```
+
+You can use ordinary ActiveRecord validation methods with `attr_json` attributes.
+
+All the `attr_json` attributes are serialized to json as keys in a hash, in a database jsonb/json column. By default, in a column `json_attributes`.
+If you look at `model.json_attributes`, you'll see values already cast to their ruby representations.
+
+But one way to see something like what it's really like in the db is to
+save the record and then use the standard Rails `*_before_type_cast` method.
+
+```ruby
+model.save!
+model.attr_jsons_before_type_cast
+# => string containing: {"my_integer":12,"int_array":[12],"my_datetime":"2016-01-01T17:45:00.000Z"}
+```
+
+## Specifying db column to use
+
+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.
+
+```ruby
+class OtherModel < ActiveRecord::Base
+  include AttrJson::Record
+
+  # as a default for the model
+  self.default_json_container_attribute = :some_other_column_name
+
+  # now this is going to serialize to column 'some_other_column_name'
+  attr_json :my_int, :integer
+
+  # Or on a per-attribute basis
+  attr_json :my_int, :integer, container_attribute: "yet_another_column_name"
+end
+```
+
+## store key different than attribute name
+
+You can also specify that the serialized JSON key
+should be different than the attribute name with the `store_key` argument.
+
+```ruby
+class MyModel < ActiveRecord::Base
+  include AttrJson::Record
+
+  attr_json :special_string, :string, store_key: "__my_string"
+end
+
+model = MyModel.new
+model.special_string = "foo"
+model.attr_jsons # => {"__my_string"=>"foo"}
+model.save!
+model.attr_jsons_before_type_cast # => string containing: {"__my_string":"foo"}
+```
+
+You can of course combine `array`, `default`, `store_key`, and `container_attribute`
+params however you like, with whatever types you like: symbols resolvable
+with `ActiveModel::Type.lookup`, or any [ActiveModel::Type::Value](https://apidock.com/rails/ActiveRecord/Attributes/ClassMethods/attribute) subclass, built-in or custom.
+
+<a name="querying"></a>
+## Querying
+
+There is some built-in support for querying using [postgres jsonb containment](https://www.postgresql.org/docs/9.5/static/functions-json.html)
+(`@>`) operator. (or see [here](https://blog.hasura.io/the-unofficial-guide-to-jsonb-operators-in-postgres-part-1-7ad830485ddf) or [here](https://hackernoon.com/how-to-query-jsonb-beginner-sheet-cheat-4da3aa5082a3)). For now you need to additionally `include AttrJson::Record::QueryScopes`
+to get this behavior.
+
+```ruby
+model = MyModel.create(my_string: "foo", my_integer: 100)
+
+MyModel.jsonb_contains(my_string: "foo", my_integer: 100).to_sql
+# SELECT "products".* FROM "products" WHERE (products.json_attributes @> ('{"my_string":"foo","my_integer":100}')::jsonb)
+MyModel.jsonb_contains(my_string: "foo", my_integer: 100).first
+# Implemented with scopes, this is an ordinary relation, you can
+# combine it with whatever, just like ordinary `where`.
+
+# typecasts much like ActiveRecord on query too:
+MyModel.jsonb_contains(my_string: "foo", my_integer: "100")
+# no problem
+
+# works for arrays too
+model = MyModel.create(int_array: [10, 20, 30])
+MyModel.jsonb_contains(int_array: 10) # finds it
+MyModel.jsonb_contains(int_array: [10]) # still finds it
+MyModel.jsonb_contains(int_array: [10, 20]) # it contains both, so still finds it
+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
+attribute name, it'll actually query on store_key. And properly handles any
+`container_attribute` -- it'll look in the proper jsonb column.
+
+Anything you can do with `jsonb_contains` should be handled
+by a [postgres `USING GIN` index](https://www.postgresql.org/docs/9.5/static/datatype-json.html#JSON-INDEXING)
+(I think! can anyone help confirm/deny?). To be sure, I recommend you
+investigate: Check out `to_sql` on any query to see what jsonb SQL it generates,
+and explore if you have the indexes you need.
+
+<a name="nested"></a>
+## Nested models -- Structured/compound data
+
+The `AttrJson::Model` mix-in lets you make ActiveModel::Model objects that can be round-trip serialized to a json hash, and they can be used as types for your top-level AttrJson::Record.
+`AttrJson::Model`s can contain other AJ::Models, singly or as arrays, nested as many levels as you like.
+
+That is, you can serialize complex object-oriented graphs of models into a single
+jsonb column, and get them back as they went in.
+
+`AttrJson::Model` has an identical `attr_json` api to
+`AttrJson::Record`, with the exception that `container_attribute` is not supported.
+
+```ruby
+class LangAndValue
+  include AttrJson::Model
+
+  attr_json :lang, :string, default: "en"
+  attr_json :value, :string
+
+  # Validations work fine, and will post up to parent record
+  validates :lang, inclusion_in: I18n.config.available_locales.collect(&:to_s)
+end
+
+class MyModel < ActiveRecord::Base
+  include AttrJson::Record
+  include AttrJson::Record::QueryScopes
+
+  attr_json :lang_and_value, LangAndValue.to_type
+
+  # YES, you can even have an array of them
+  attr_json :lang_and_value_array, LangAndValue.to_type, array: true
+end
+
+# Set with a model object, in initializer or writer
+m = MyModel.new(lang_and_value: LangAndValue.new(lang: "fr", value: "S'il vous plaît"))
+m.lang_and_value = LangAndValue.new(lang: "es", value: "hola")
+m.lang_and_value
+# => #<LangAndValue:0x007fb64f12bb70 @attributes={"lang"=>"es", "value"=>"hola"}>
+m.save!
+m.attr_jsons_before_type_cast
+# => string containing: {"lang_and_value":{"lang":"es","value":"hola"}}
+
+# Or with a hash, no problem.
+
+m = MyModel.new(lang_and_value: { lang: 'fr', value: "S'il vous plaît"})
+m.lang_and_value = { lang: 'en', value: "Hey there" }
+m.save!
+m.attr_jsons_before_type_cast
+# => string containing: {"lang_and_value":{"lang":"en","value":"Hey there"}}
+found = MyModel.find(m.id)
+m.lang_and_value
+# => #<LangAndValue:0x007fb64eb78e58 @attributes={"lang"=>"en", "value"=>"Hey there"}>
+
+# Arrays too, yup
+
+m = MyModel.new(lang_and_value_array: [{ lang: 'fr', value: "S'il vous plaît"}, { lang: 'en', value: "Hey there" }])
+m.lang_and_value_array
+# => [#<LangAndValue:0x007f89b4f08f30 @attributes={"lang"=>"fr", "value"=>"S'il vous plaît"}>, #<LangAndValue:0x007f89b4f086e8 @attributes={"lang"=>"en", "value"=>"Hey there"}>]
+m.save!
+m.attr_jsons_before_type_cast
+# => string containing: {"lang_and_value_array":[{"lang":"fr","value":"S'il vous plaît"},{"lang":"en","value":"Hey there"}]}
+```
+
+You can nest AttrJson::Model objects inside each other, as deeply as you like.
+
+```ruby
+class SomeLabels
+  include AttrJson::Model
+
+  attr_json :hello, LangAndValue.to_type, array: true
+  attr_json :goodbye, LangAndValue.to_type, array: true
+end
+class MyModel < ActiveRecord::Base
+  include AttrJson::Record
+  include AttrJson::Record::QueryScopes
+
+  attr_json :my_labels, SomeLabels.to_type
+end
+
+m = MyModel.new
+m.my_labels = {}
+m.my_labels
+# => #<SomeLabels:0x007fed2a3b1a18>
+m.my_labels.hello = [{lang: 'en', value: 'hello'}, {lang: 'es', value: 'hola'}]
+m.my_labels
+# => #<SomeLabels:0x007fed2a3b1a18 @attributes={"hello"=>[#<LangAndValue:0x007fed2a0eafc8 @attributes={"lang"=>"en", "value"=>"hello"}>, #<LangAndValue:0x007fed2a0bb4d0 @attributes={"lang"=>"es", "value"=>"hola"}>]}>
+m.my_labels.hello.find { |l| l.lang == "en" }.value = "Howdy"
+m.save!
+m.attr_jsons
+# => {"my_labels"=>#<SomeLabels:0x007fed2a714e80 @attributes={"hello"=>[#<LangAndValue:0x007fed2a714cf0 @attributes={"lang"=>"en", "value"=>"Howdy"}>, #<LangAndValue:0x007fed2a714ac0 @attributes={"lang"=>"es", "value"=>"hola"}>]}>}
+m.attr_jsons_before_type_cast
+# => string containing: {"my_labels":{"hello":[{"lang":"en","value":"Howdy"},{"lang":"es","value":"hola"}]}}
+```
+
+**GUESS WHAT?** You can **QUERY** nested structures with `jsonb_contains`,
+using a dot-keypath notation, even through arrays as in this case. Your specific
+defined `attr_json` types determine the query and type-casting.
+
+```ruby
+MyModel.jsonb_contains("my_labels.hello.lang" => "en").to_sql
+# => SELECT "products".* FROM "products" WHERE (products.json_attributes @> ('{"my_labels":{"hello":[{"lang":"en"}]}}')::jsonb)
+MyModel.jsonb_contains("my_labels.hello.lang" => "en").first
+
+
+# also can give hashes, at any level, or models themselves. They will
+# be cast. Trying to make everything super consistent with no surprises.
+
+MyModel.jsonb_contains("my_labels.hello" => LangAndValue.new(lang: 'en')).to_sql
+# => SELECT "products".* FROM "products" WHERE (products.json_attributes @> ('{"my_labels":{"hello":[{"lang":"en"}]}}')::jsonb)
+
+MyModel.jsonb_contains("my_labels.hello" => {"lang" => "en"}).to_sql
+# => SELECT "products".* FROM "products" WHERE (products.json_attributes @> ('{"my_labels":{"hello":[{"lang":"en"}]}}')::jsonb)
+
+```
+
+Remember, we're using a postgres containment (`@>`) operator, so queries
+always mean 'contains' -- the previous query needs a `my_labels.hello`
+which is a hash that includes the key/value, `lang: en`, it can have
+other key/values in it too.  String values will need to match exactly.
+
+
+<a name="forms"></a>
+## Forms and Form Builders
+
+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.
+
+To get simple_form to properly detect your attribute types, define your attributes with `rails_attribute: true`.
+
+For more info, see doc page on [Use with Forms and Form Builders](doc_src/forms.md).
+
+<a name="dirty"></a>
+## Dirty tracking
+
+Full change-tracking, ActiveRecord::Attributes::Dirty-style, is available in
+Rails 5.1+ on `attr_json`s on your ActiveRecord classes that include
+`AttrJson::Record`, by including `AttrJson::Record::Dirty`.
+Change-tracking methods are available off the `attr_json_changes` method.
+
+    class MyModel < ActiveRecord::Base
+       include AttrJson::Record
+       include AttrJson::Record::Dirty
+
+       attr_json :str, :string
+    end
+
+    model = MyModel.new
+    model.str = "old"
+    model.save
+    model.str = "new"
+
+    # All and only "new" style dirty tracking methods (Raisl 5.1+)
+    # are available:
+
+    model.attr_json_changes.saved_changes
+    model.attr_json_changes.changes_to_save
+    model.attr_json_changes.saved_change_to_str?
+    model.attr_json_changes.saved_change_to_str
+    model.attr_json_changes.will_save_change_to_str?
+    # etc
+
+More options are available, including merging changes from 'ordinary'
+ActiveRecord attributes in. See docs on [Dirty Tracking](./doc_src/dirty_tracking.md)
+
+## Do you want this?
+
+Why might you want this?
+
+* You have complicated data, which you want to access in object-oriented
+  fashion, but want to avoid very complicated normalized rdbms schema --
+  and are willing to trade the powerful complex querying support normalized rdbms
+  schema gives you.
+
+* Single-Table Inheritance, with sub-classes that have non-shared
+  data fields. You rather not make all those columns, some of which will then also appear
+  to inapplicable sub-classes.
+
+* 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.
+
+* You want to version your models, which is tricky with associations between models.
+  Minimize associations by inlining the complex data into one table row.
+
+* Generally, we're turning postgres into a _simple_ object-oriented
+  document store. That can be mixed with an rdbms. The very same
+  row in a table in your db can have document-oriented json data _and_ foreign keys
+  and real rdbms associations to other rows. And it all just
+  feels like ActiveRecord, mostly.
+
+Why might you _not_ want this?
+
+* An rdbms and SQL is a wonderful thing, if you need sophisticated
+  querying and reporting with reasonable performance, complex data
+  in a single jsonb probably isn't gonna be the best.
+
+* This is pretty well-designed code that _mostly_ only uses
+  fairly stable and public Rails API, but there is still some
+  risk of tying your boat to it, it's not Rails itself, and there is
+  some risk it won't keep up with Rails in the future.
+
+
+## Note on Optimistic Locking
+
+When you save a record with any changes to any attr_jsons, it will
+overwrite the _whole json structure_ in the relevant column for that row.
+Unlike ordinary AR attributes where updates just touch changed attributes.
+
+Becuase of this, you probably want to seriously consider using ActiveRecord
+[Optimistic Locking](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html)
+to prevent overwriting other updates from processes.
+
+## State of Code, and To Be Done
+
+This is a pre-1.0 work in progress. But the functionality that is here seems pretty solid.
+
+Backwards incompatible changes are possible before 1.0. Once I tag something 1.0, I'm pretty serious about minimizing backwards incompats.
+
+I do not yet use this myself in production, and may not for a while. I generally am reluctant to release something as 1.0 with implied suitable for production when I'm not yet using it in production myself, but may with enough feedback. A couple others are already using in production.
+
+Feedback of any kind of _very welcome_, please feel free to use the issue tracker.
+
+Except for the jsonb_contains stuff using postgres jsonb contains operator, I don't believe any postgres-specific features are used. It ought to work with MySQL, testing and feedback welcome. (Or a PR to test on MySQL?).  My own interest is postgres.
+
+### 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
+
+* Should we give AttrJson::Model a before_serialize hook that you might
+  want to use similar to AR before_save?  Should AttrJson::Models
+  raise on trying to serialize an invalid model?
+
+* There are limits to what you can do with just jsonb_contains
+  queries. We could support operations like `>`, `<`, `<>`
+  as [jsonb_accessor](https://github.com/devmynd/jsonb_accessor),
+  even accross keypaths. (At present, you could use a
+  before_savee to denormalize/renormalize copy your data into
+  ordinary AR columns/associations for searching. Or perhaps a postgres ts_vector for text searching. Needs to be worked out.)
+
+* We could/should probably support `jsonb_order` clauses, even
+  accross key paths, like jsonb_accessor.
+
+* Could we make these attributes work in ordinary AR where, same
+  as they do in jsonb_contains? Maybe.
+
+## Acknowledements and Prior Art
+
+* The excellent work [Sean Griffin](https://twitter.com/sgrif) did on ActiveModel::Type
+  really lays the groundwork and makes this possible. Plus many other Rails developers.
+  Rails has a reputation for being composed of messy or poorly designed code, but
+  it's some really nice design in Rails that allows us to do some pretty powerful
+  stuff here, in surprisingly few lines of code.
+
+* The existing [jsonb_accessor](https://github.com/devmynd/jsonb_accessor) was
+  an inspiration, and provided some good examples of how to do some things
+  with AR and ActiveModel::Types. I [started out trying to figure out](https://github.com/devmynd/jsonb_accessor/issues/69#issuecomment-294081059)
+  how to fit in nested hashes to jsonb_accessor... but ended up pretty much rewriting it entirely,
+  to lean on object-oriented polymorphism and ActiveModel::Type a lot heavier and have
+  the API and internals I wanted/imagined.
+
+* Took a look at existing [active_model_attributes](https://github.com/Azdaroth/active_model_attributes) too.
+
+* Didn't actually notice existing [json_attributes](https://github.com/joel/json_attributes)
+  until I was well on my way here. I think it's not updated for Rails5 or type-aware,
+  haven't looked at it too much.