attr_json 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+require "rubygems"
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task(default: [:spec])

data/bin/console

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+# combustion defaults to RAILS_ENV=test, we don't want to here.
+ENV['RAILS_ENV'] ||= "development"
+
+require "bundler/setup"
+require "attr_json"
+require 'yaml'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "rspec"
+require File.expand_path("../../spec/spec_helper.rb", __FILE__)
+
+require_relative '../playground_models.rb'
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here
+
+rake db:create
+rake db:migrate

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+
+Bundler.require :default, :test
+
+Combustion.initialize! :all
+run Combustion::Application

data/doc_src/dirty_tracking.md

@@ -0,0 +1,155 @@
+# Dirty Tracking Support in AttrJson
+
+In ordinary ActiveRecord, there is dirty/change-tracking support for attributes,
+that lets you see what changes currently exist in the model compared to what
+was fetched from the db, as well as what changed on the most recent save operation.
+
+```ruby
+model = SomeModel.new
+model.str_value = "some value"
+model.changes_to_save
+  # => { 'str_value' => 'some_value'}
+model.will_save_change_to_str_value?
+  # => true
+model.save
+model.saved_changes
+  # => { 'str_value' => 'some_value'}
+model.str_value_before_last_save
+  # => nil
+# and more
+```
+
+You may be used to an older style of AR change-tracking methods,
+involving `changes` and `previous_changes`. These older-style methods were
+deprecated in Rails 5.1 and removed in Rails 5.2.  It's a bit confusing and not
+fully documented in AR, see more at
+[these](https://www.levups.com/en/blog/2017/undocumented-dirty-attributes-activerecord-changes-rails51.html)
+blog [posts](https://www.ombulabs.com/blog/rails/upgrades/active-record-5-1-api-changes.html),
+and the initial [AR pull request](https://github.com/rails/rails/pull/25337).
+
+AttrJson supports all of these new-style dirty-tracking methods, only
+in Rails 5.1+. (*Sorry, our dirty tracking support does not work with Rails 5.0,
+or old-style dirty API in Rails 5.1. Only new-style API in Rails 5.1+*). I wasn't
+able to find a good way to get changes in the default Rails dirty tracking methods,
+so instead **they are available off a separate `attr_json_changes` method**,
+which also allows customization of if host record changes are also included.
+
+To include the AttrJson dirty-tracking features, include the
+`AttrJson::Record::Dirty` module in your active record model already including
+`AttrJson::Record`:
+
+```ruby
+class MyEmbeddedModel
+  include AttrJson::Model
+
+  attr_json :str, :string
+end
+
+class MyModel < ActiveRecord::Base
+  include AttrJson::Record
+  include AttrJson::Record::Dirty
+
+  attr_json :str, :string
+  attr_json :str_array, :string, array: true
+  attr_json :array_of_models, MyEmbeddedModel.to_type, array: true
+end
+```
+
+Now dirty changes are available off a `attr_json_changes` method.
+The full suite of (new, Rails 5.1+) ActiveRecord dirty methods are supported,
+both ones that take the attribute-name as an argument, and synthetic attribute-specific
+methods. All top-level `attr_json`s are supported, including those that
+include arrays and/or complex/nested/compound models.
+
+```ruby
+model = MyModel.new
+model.str = "some value"
+model.attr_json_changes.will_save_change_to_str? #=> true
+model.str_array = ["original1", "original2"]
+model.array_of_models = [MyEmbeddedModel.new(str: "value")]
+model.save
+
+model.attr_json_changes.saved_changes
+  # => {"str"=>[nil, "some value"], "str_array"=>[nil, ["original1", "original2"]], "array_of_models"=>[nil, [#<MyEmbeddedModel:0x00007fb285d12330 @attributes={"str"=>"value"}, @validation_context=nil, @errors=#<ActiveModel::Errors:0x00007fb285d00400 @base=#<MyEmbeddedModel:0x00007fb285d12330 ...>, @messages={}, @details={}>>]]
+
+model.str_array << "new1"
+
+model.attr_json_changes.will_save_change_to_str_array? # => true
+model.attr_json_changes.str_array_change_to_be_saved
+  # => [["original1", "original2"], ["original1", "original2", "new1"]]
+```
+
+## Cast representation vs Json representation
+
+If you ask to see changes, you are going to see the changes reported as _cast_ values,
+not _json_ values. For instance, you'll see your actual `AttrJson::Model`
+objects instead of the hashes they serialize to, and ruby DateTime objects instead
+of the ISO 8601 strings they serialize to.
+
+If you'd like to see the the JSON-compat data structures instead, just tag
+on the `as_json` modifier. For simple strings and ints and similar primitives,
+it won't make a difference, for some types it will:
+
+```ruby
+model.attr_json_changes.changes_to_save
+#=> {
+#  json_str: [nil, "some value"]
+#  embedded_model: [nil, #<TestModel:0x00007fee25a04bf8 @attributes={"str"=>"foo"}>]
+#  json_date: [nil, {{ruby Date object}}]
+# }
+
+model.attr_json_changes.as_json.changes_to_save
+#=> {
+#  json_str: [nil, "some_value"]
+#  embedded_model: [nil, {'str' => 'foo'}]
+#  json_date: [nil, "2018-03-23"]
+# }
+
+```
+
+All existing values are serialized every time you call this, since they are stored
+in cast form internally. So there _could_ be perf implications, but generally it is looking fine.
+
+## Merge in ordinary AR attribute dirty tracking
+
+Now you have one place to track 'ordinary' AR attribute "dirtyness"
+(`model.some_attribute_will_change?`), and another place to track attr_json
+dirty-ness (`my_model.attr_json_changes.some_json_attr_will_change?`).
+
+You may wish you could have one place that tracked both, so your calling code
+doesn't need to care if a given attribute is jsonb-backed or ordinary-column, and
+is resilient if an attribute switches from one to another.
+
+While we couldn't get this on the built-in dirty attributes, you *can* optionally
+tell the `attr_json_changes` to include 'ordinary' changes from model too,
+all in one place, by adding on the method `merged`.
+
+```ruby
+model.attr_json_changes.merged.ordinary_attribute_will_change?
+model.attr_json_changes.merged.attr_json_will_change?
+model.attr_json_changes.merged.attr_json_will_change?
+model.attr_json_changes.merged.changes_to_save
+# => includes a hash with keys that are both ordinary AR attributes
+#    and attr_jsons, as applicable for changes.
+```
+
+This will ordinarily include your json container attributes (eg `attr_jsons`)
+too, as they will show up in ordinary AR dirty tracking since they are just AR
+columns.
+
+If you'd like to exclude these from the merged dirty tracking, pretend the json
+container attributes don't exist and just focus on the individual `attr_json`s,
+we got you covered:
+
+```ruby
+model.attr_json_changes.merged(containers: false).attr_jsons_will_change?
+  # => always returns `nil`, the 'real' `attr_jsons` attribute is dead to us.
+```
+
+## Combine both of these modifiers at once no problem
+
+```ruby
+model.attr_json_changes.as_json.merged.saved_changes
+model.attr_json_changes.as_json.merged(containers: false).saved_changes
+model.attr_json_changes.merged(containers: true).as_json.saved_changes
+```

data/doc_src/forms.md

@@ -0,0 +1,124 @@
+# Use with Forms and Form builders
+
+We've tried to make your attr_jsons just as easy to work with Rails form builders as ordinary attributes, including treating nested/compound models as if they were Rails associations in forms.
+
+It's worked out pretty well. This is one of the more complex parts of our attr_json code, making it work with all the Rails weirdness on nested params, multi-param attributes (generally used for dates), etc. So if a bug is gonna happen somewhere, it's probably here. But at the moment it looks pretty solid and stable.
+
+We even integration test with [simple_form](https://github.com/plataformatec/simple_form) and [cocoon](https://github.com/nathanvda/cocoon) (see below, some custom config may be required).
+You can look at our [stub app used for integration tests](../spec/internal) as an example if you like.
+
+## Standard Rails form builder
+
+### Simple attributes
+
+    attr_json :some_string, :string
+    attr_json :some_datetime, :datetime
+
+Use with form builder just as you would anything else.
+
+    f.text_field :some_string
+    f.datetimme_field :some_datetime
+
+It _will_ work with the weird rails multi-param setting used for date fields.
+
+Don't forget you gotta handle strong params same as you would for any ordinary attribute.
+
+### Arrays of simple attributes
+
+    attr_json :string_array, :string, array: true
+
+The ActionView+ActiveRecord architecture isn't really setup for an array of "primitives", but you can make it work:
+
+    <% f.object.string_array.each do |str| %>
+      <%= f.text_field(:string_array, value: str, multiple: true) %>
+    <% end %>
+
+That will display, submit and update fine, although when you try to handle reporting validation errors, you'll probably only be able to report on the array, not the specific element.
+
+You may want to [use SimpleForm and create a custom input](https://github.com/plataformatec/simple_form#custom-inputs) to handle arrays of primitives in the way you want. Or you may want to consider an array of AttrJson::Model value types instead -- you can have a model with only one attribute! It can be handled more conventionally, see below.
+
+### Embedded/Nested AttrJson::Model attributes
+
+With ordinary rails associations handled in the ordinary Rails way, you use [accepts_nested_attributes_for](http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html) for associations (to-one or to-many).
+
+You can handle a single or array AttrJson::Model attr_json similarly, but you have to:
+
+* include AttrJson::NestedAttributes in your model, and then
+* use our own similar `attr_json_accepts_nested_attributes_for` instead.  It _always_ has `allow_destroy`, and some of the other `accepts_nested_attributes_for` options also don't apply, see method for full options.
+
+```ruby
+class Event
+  include AttrJson::Model
+
+  attr_json :name
+  attr_json :datetime
+end
+class MyRecord < ActiveRecord::Base
+  include AttrJson::Record
+  include AttrJson::NestedAttributes
+
+  attr_json :one_event, Event.to_type
+  attr_json :many_events, Event.to_type, array: true
+
+  attr_json_accepts_nested_attributes_for :one_event, :many_events
+end
+
+# In a form template...
+<%= form_for(record) do |f| %>
+  <%= f.fields_for :one_event do |one_event_f| %>
+    <%= one_event_f.text_field :name %>
+    <%= one_event_f.datetime_field :datetime %>
+  <% end %>
+
+  <%= f.fields_for :many_events do |one_event_f| %>
+    <%= one_event_f.text_field :name %>
+    <%= one_event_f.datetime_field :datetime %>
+  <% end %>
+<% end %>
+```
+
+It should just work as you are expecting! You have to handle strong params as normal for when dealing with Rails associations, which can be tricky, but it's just the same here.
+
+Note that the `AttrJsons::NestedAttributes` module also adds convenient rails-style `build_` methods for you.  In the case above, you get a `build_one_event` and `build_many_event` (note singularization, cause that's how Rails does) method, which you can use much like Rails' `build_to_one_association` or `to_many_assocication.build` methods. You can turn off creation of the build methods by passing `define_build_method: false` to `attr_json_accepts_nested_attributes_for`.
+
+### Nested multi-level/compound embedded models
+
+A model inside a model inside a model?  Some single and some array? No problem, should just work.
+
+Remember to add `include AttrJson::NestedAttributes` to all your AttrJson::Models (or at least non-terminal ones). Remember that Rails strong params have to be dealt with and are confusing here, but you deal with them the same way you would multi-nested associations on a rails form.
+
+## Simple Form
+
+One of the nice parts about [simple_form](https://github.com/plataformatec/simple_form) is how you can just give it `f.input`, and it figures out the right input for you.
+
+AttrJson by default, on an ActiveRecord::Base, doesn't register it's `attr_jsons` in the right way for simple_form to reflect and figure out their types. However, you can ask it to with `rails_attribute: true`.
+
+```ruby
+class SomeRecord < ActiveRecord::Base
+  include AttrJson::Record
+
+  attr_json :my_date, :date, rails_attribute: true
+end
+```
+
+This will use the [ActiveRecord::Base.attribute](http://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html) method to register the attribute and type, and SimpleForm will now be able to automatically look up attribute type just as you expect. (Q: Should we make this default on?)
+
+You don't need to do this in your nested AttrJson::Model classes, SimpleForm will already be able to reflect on their attribute types just fine as is.
+
+## Cocoon
+
+[Cocoon](https://github.com/nathanvda/cocoon) is one easy way to implement js-powered add- and remove-field functionality for to-many associations nested on a form with Rails.
+
+It _almost_ "just works" with nested/compound AttrJson::Model attributes, used with rails `fields_for` form builder as above. But Cocoon is looking for some ActiveRecord-specific methods that don't exist in our AttrJson::Models -- although it doesn't actually matter what these methods return, Cocoon works with our architecture either way.
+
+Include the `AttrJson::Model::CocoonCompat` module in your **AttrJson::Model** classes to get these methods so Cocoon will work.
+
+We have an integration test running a real rails app ensuring both simple_form and cocoon continue to work.
+
+## Reform?
+
+If you would rather use [Reform](https://github.com/trailblazer/reform) than the standard Rails architecture(s) (which are somewhat tangled and weird for nested associations), I _believe_ it should Just Work (tm). Use it how you would with AR associations, and it should work for our nested AttrJson::Models too.
+
+You shouldn't have to use the `AttrJson::NestedAttributes` module anywhere. You will have to do a lot more work yourself, as the nature of reform.
+
+I have not tested or experimented extensively with reform+attr_json myself, feedback welcome.

data/json_attribute.gemspec

@@ -0,0 +1,50 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'attr_json/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "attr_json"
+  spec.version       = AttrJson::VERSION
+  spec.authors       = ["Jonathan Rochkind"]
+  spec.email         = ["jonathan@dnil.net"]
+
+  spec.summary       = %q{ActiveRecord attributes stored serialized in a json column, super smooth.}
+  spec.description   = %q{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,
+dirty tracking, some querying (with postgres jsonb contains), and working smoothy with form builders.
+
+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.}
+  spec.homepage      = "https://github.com/jrochkind/attr_json"
+  spec.license       = "MIT"
+  spec.metadata      = {
+    "homepage_uri"      => "https://github.com/jrochkind/attr_json",
+    "source_code_uri"   => "https://github.com/jrochkind/attr_json"
+  }
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against " \
+  #     "public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activerecord", ">= 5.0.0", "< 5.3"
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", ">= 10.0"
+  spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "database_cleaner", "~> 1.5"
+  spec.add_development_dependency "yard-activesupport-concern"
+end