jsonb_accessor 1.0.0.beta → 1.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c764a056e39fc6979212aac29a31384cb694a38b
-  data.tar.gz: 495df5a38ac759f3b07d718f818bddfbcb9449ec
+  metadata.gz: e5a63babf736e4f8208d2aef0238f2f2ec82fc7b
+  data.tar.gz: 72f1ef3b5c23839cd7fac5c016b3f5ab228b9ba6
 SHA512:
-  metadata.gz: 8716e5c48b3122677518e20230d3d70c59b42eb9434ed4ebe8992f4ef9b797a4b9e2b2566960ed34a3a6cbf77baa785f0fe0853f9bf40198d9214360ced4bf8f
-  data.tar.gz: 90389c14a8b8aa3b27da14301897e5ee836c713456ed562421ef989d6b3c88407d211ff22cc79fd76be318735660bb9129e4ce6ccd9bd7b17bbe7444f346b2b8
+  metadata.gz: 82287481f107b50bb00aa74a2e750010db9a0961110107604538ed976500bfec54fab7b5ee0f9ef4f013b3bb742e5c44d8dcfb2c5371a3286807c580705686ad
+  data.tar.gz: 71eab6fd8aa74450a93858d1d1970af547a13a5e9da49e43cdff6f55d0c78b5c164ef00f7ce36532ec2ce1caeeb3cff05dc0a1624f1c1c002623ee697e2782b2

data/README.md

@@ -4,13 +4,20 @@
 
 Adds typed `jsonb` backed fields as first class citizens to your `ActiveRecord` models. This gem is similar in spirit to [HstoreAccessor](https://github.com/devmynd/hstore_accessor), but the `jsonb` column in PostgreSQL has a few distinct advantages, mostly around nested documents and support for collections.
 
+It also adds generic scopes for querying `jsonb` columns.
+
+## 1.0 Beta
+
+This README reflects the 1.0 beta. Method names and interfaces may still change.
+
 ## Table of Contents
 
 * [Installation](#installation)
 * [Usage](#usage)
-* [Validations](#validations)
+* [Scopes](#scopes)
 * [Single-Table Inheritance](#single-table-inheritance)
 * [Dependencies](#dependencies)
+* [Validations](#validations)
 * [Development](#development)
 * [Contributing](#contributing)
 
@@ -31,10 +38,10 @@ And then execute:
 First we must create a model which has a `jsonb` column available to store data into it:
 
 ```ruby
-class CreateProductsTable < ActiveRecord::Migration
+class CreateProducts < ActiveRecord::Migration
   def change
     create_table :products do |t|
-      t.jsonb :options
+      t.jsonb :data
     end
   end
 end
@@ -44,19 +51,141 @@ We can then declare the `jsonb` fields we wish to expose via the accessor:
 
 ```ruby
 class Product < ActiveRecord::Base
-  jsonb_accessor(
-    :options,
+  jsonb_accessor :data,
     title: :string,
-    id_value: :value,
     external_id: :integer,
     reviewed_at: :datetime
-  )
 end
 ```
 
-## Validations
+Any type the [`attribute` API](http://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html#method-i-attribute) supports. You can also implement your own type by following the example in the `attribute` documentation.
+
+To pass through options like `default` and `array` to the `attribute` API, just put them in an array.
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    title: [:string, default: "Untitled"],
+    previous_titles: [:string, array: true, default: []]
+end
+```
+
+You can also pass in a `store_key` option.
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data, title: [:string, store_key: :t]
+end
+```
+
+This allows you to use `title` for your getters and setters, but use `t` as the key in the `jsonb` column.
+
+```ruby
+product = Product.new(title: "Foo")
+product.title #=> "Foo"
+product.data #=> { "t" => "Foo" }
+```
+
+## Scopes
+
+Jsonb Accessor provides several scopes to make it easier to query `jsonb` columns. `jsonb_contains`, `jsonb_number_where`, `jsonb_time_where`, and `jsonb_where` are available on all `ActiveRecord::Base` subclasses and don't require that you make use of the `jsonb_accessor` declaration.
+
+If a class does have a `jsonb_accessor` declaration, then we define one custom scope. So, let's say we have a class that looks like this:
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    name: :string,
+    price: [:integer, store_key: :p],
+    price_in_cents: :integer,
+    reviewed_at: :datetime
+end
+```
+
+Jsonb Accessor will add a `scope` to `Product` called `data_where`.
+
+```ruby
+Product.all.data_where(name: "Granite Towel", price: 17)
+```
+
+For number fields you can query using `<` or `>`or use plain english if that's what you prefer.
 
-Because this gem promotes attributes nested into the JSON column to first level attributes, most validations should just work. We still have to add some testing and support around this feature but feel free to try and leave us feedback if they're not working as expected.
+```ruby
+Product.all.data_where(price: { <: 15 })
+Product.all.data_where(price: { <=: 15 })
+Product.all.data_where(price: { less_than: 15 })
+Product.all.data_where(price: { less_than_or_equal_to: 15 })
+
+Product.all.data_where(price: { >: 15 })
+Product.all.data_where(price: { >=: 15 })
+Product.all.data_where(price: { greater_than: 15 })
+Product.all.data_where(price: { greater_than_or_equal_to: 15 })
+
+Product.all.data_where(price: { greater_than: 15, less_than: 30 })
+```
+
+For time related fields you can query using `before` and `after`.
+
+```ruby
+Product.all.data_where(reviewed_at: { before: Time.current.beginning_of_week, after: 4.weeks.ago })
+```
+
+This scope is a convenient wrapper around the `jsonb_where` `scope` that saves you from having to convert the given keys to the store keys and from specifying the column.
+
+### `jsonb_where`
+
+Works just like the [`scope` above](#scopes) except that it does not convert the given keys to store keys and you must specify the column name. For example:
+
+```ruby
+Product.all.jsonb_where(:data, reviewed_at: { before: Time.current }, p: { greater_than: 5 })
+
+# instead of
+
+Product.all.data_where(reviewed_at: { before: Time.current }, price: { greater_than: 5 })
+```
+This scope makes use of the `jsonb_contains`, `jsonb_number_where`, and `jsonb_time_where` `scope`s.
+
+### `jsonb_contains`
+
+Returns all records that contain the given JSON paths.
+
+```ruby
+Product.all.jsonb_contains(:data, title: "foo")
+Product.all.jsonb_contains(:data, reviewed_at: 10.minutes.ago, p: 12) # Using the store key
+```
+
+**Note:** Under the hood, `jsonb_contains` uses the [`@>` operator in Postgres](https://www.postgresql.org/docs/9.5/static/functions-json.html) so when you include an array query, the stored array and the array used for the query do not need to match exactly. For example, when queried with `[1, 2]`, records that have arrays of `[2, 1, 3]` will be returned.
+
+### `jsonb_number_where`
+
+Returns all records that match the given criteria.
+
+```ruby
+Product.all.jsonb_number_where(:data, :price_in_cents, :greater_than, 300)
+```
+
+It supports:
+
+* `>`
+* `>=`
+* `greater_than`
+* `greater_than_or_equal_to`
+* `<`
+* `<=`
+* `less_than`
+* `less_than_or_equal_to`
+
+and it is indifferent to strings/symbols.
+
+### `jsonb_time_where`
+
+Returns all records that match the given criteria.
+
+```ruby
+Product.all.jsonb_time_where(:data, :reviewed_at, :before, 2.days.ago)
+```
+
+It supports `before` and `after` and is indifferent to strings/symbols.
 
 ## Single-Table Inheritance
 
@@ -70,8 +199,8 @@ rows can have different values.
 We set up our table with an `jsonb` field:
 
 ```ruby
-# db/migration/<timestamp>_create_players_table.rb
-class CreateVehiclesTable < ActiveRecord::Migration
+# db/migration/<timestamp>_create_players.rb
+class CreateVehicles < ActiveRecord::Migration
   def change
     create_table :vehicles do |t|
       t.string :make
@@ -110,44 +239,16 @@ From here any attributes specific to any sub-class can be stored in the
 `jsonb` column avoiding sparse data.  Indices can also be created on
 individual fields in an `jsonb` column.
 
-This approach was originally concieved by Joe Hirn in [this blog
+This approach was originally conceived by Joe Hirn in [this blog
 post](http://www.devmynd.com/blog/2013-3-single-table-inheritance-hstore-lovely-combination).
 
-## Scopes
-
-JsonbAccessor currently supports several scopes. Let's say we have a class that looks like this:
-
-```ruby
-class Product < ActiveRecord::Base
-  jsonb_accessor :data,
-    approved: :boolean,
-    name: :string,
-    price: :integer,
-    previous_prices: :integer_array,
-    reviewed_at: :date_time
-end
-```
-
-### General Scopes
-
-#### `<jsonb_field>_contains`
-
-**Description:** returns all records that contain matching attributes in the specified `jsonb` field.
-
-```ruby
-product_1 = Product.create!(name: "foo", approved: true, reviewed_at: 3.days.ago)
-product_2 = Product.create!(name: "bar", approved: true)
-product_3 = Product.create!(name: "foo", approved: false)
-
-Product.data_contains(name: "foo", approved: true) # => [product_1]
-```
+## Validations
 
-**Note:** when including an array attribute, the stored array and the array used for the query do not need to match exactly. For example, when queried with `[1, 2]`, records that have arrays of `[2, 1, 3]` will be returned.
+Because this gem promotes attributes nested into the JSON column to first level attributes, most validations should just work. Please leave us feedback if they're not working as expected.
 
 ## Dependencies
 
-- ActiveRecord 5.0
-- Ruby >= 2.2.2
+- ActiveRecord >= 5.0
 - Postgres >= 9.4 (in order to use the [jsonb column type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)).
 
 ## Development

data/UPGRADE_GUIDE.md

@@ -0,0 +1,67 @@
+# Upgrading from 0.X.X to 1.0.0
+
+## Jsonb Accessor declaration
+
+In 0.X.X you would write:
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    :count, # doesn't specify a type
+    title: :string,
+    external_id: :integer,
+    reviewed_at: :date_time, # snake cased
+    previous_rankings: :integer_array, # `:type_array` key
+    external_rankings: :array # plain array
+end
+```
+
+In 1.0.0 you would write:
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    count: :value, # all fields must specify a type
+    title: :string,
+    external_id: :integer,
+    reviewed_at: :datetime, # `:date_time` is now `:datetime`
+    previous_rankings: [:integer, array: true], # now just the type followed by `array: true`
+    external_rankings: [:value, array: true] # now the value type is specified as well as `array: true`
+end
+```
+
+There are several important differences. All fields must now specify a type, `:date_time` is now `:datetime`, and arrays are specified using a type and `array: true` instead of `type_array`.
+
+Also, in order to use the `value` type you need to register it:
+
+```ruby
+# in an initializer
+ActiveRecord::Type.register(:value, ActiveRecord::Type::Value)
+```
+
+### Deeply nested objects
+
+In 0.X.X you could write:
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    ranking_info: {
+      original_rank: :integer,
+      current_rank: :integer,
+      metadata: {
+        ranked_on: :date
+      }
+    }
+end
+```
+
+Which would allow you to use getter and setter methods at any point in the structure.
+
+```ruby
+Product.new(ranking_info: { original_rank: 3, current_rank: 5, metadata: { ranked_on: Date.today } })
+product.ranking_info.original_rank # 3
+product.ranking_info.metadata.ranked_on # Date.today
+```
+
+1.0.0 does not support this syntax. If you need these sort of methods, you can create your own type `class` and register it with `ActiveRecord::Type`. [Here's an example](http://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html#method-i-attribute).

data/gemfiles/activerecord_5.0.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../
   specs:
-    jsonb_accessor (1.0.0.beta)
+    jsonb_accessor (1.0.0.beta.1)
       activerecord (>= 5.0.0)
       pg (>= 0.18.1)
 

data/lib/jsonb_accessor/query_builder.rb

@@ -46,12 +46,12 @@ module JsonbAccessor
       scope(:jsonb_contains,
         -> (column_name, attributes) { where("#{table_name}.#{column_name} @> (?)::jsonb", attributes.to_json) })
 
-      scope(:jsonb_number_query, lambda do |column_name, field_name, given_operator, value|
+      scope(:jsonb_number_where, lambda do |column_name, field_name, given_operator, value|
         operator = JsonbAccessor::NUMBER_OPERATORS_MAP.fetch(given_operator.to_s)
         where("(#{table_name}.#{column_name} ->> ?)::float #{operator} ?", field_name, value)
       end)
 
-      scope(:jsonb_time_query, lambda do |column_name, field_name, given_operator, value|
+      scope(:jsonb_time_where, lambda do |column_name, field_name, given_operator, value|
         operator = JsonbAccessor::TIME_OPERATORS_MAP.fetch(given_operator.to_s)
         where("(#{table_name}.#{column_name} ->> ?)::timestamp #{operator} ?", field_name, value)
       end)
@@ -63,9 +63,9 @@ module JsonbAccessor
         attributes.each do |name, value|
           case value
           when IS_NUMBER_QUERY_ARGUMENTS
-            value.each { |operator, query_value| query = query.jsonb_number_query(column_name, name, operator, query_value) }
+            value.each { |operator, query_value| query = query.jsonb_number_where(column_name, name, operator, query_value) }
           when IS_TIME_QUERY_ARGUMENTS
-            value.each { |operator, query_value| query = query.jsonb_time_query(column_name, name, operator, query_value) }
+            value.each { |operator, query_value| query = query.jsonb_time_where(column_name, name, operator, query_value) }
           else
             contains_attributes[name] = value
           end

data/lib/jsonb_accessor/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module JsonbAccessor
-  VERSION = "1.0.0.beta"
+  VERSION = "1.0.0.beta.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonb_accessor
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta
+  version: 1.0.0.beta.1
 platform: ruby
 authors:
 - Michael Crismali
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-18 00:00:00.000000000 Z
+date: 2016-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -228,6 +228,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- UPGRADE_GUIDE.md
 - bin/console
 - bin/setup
 - db/config.yml