jsonb_accessor 1.3.7-java

data/README.md

@@ -0,0 +1,355 @@
+# JSONb Accessor
+
+Created by &nbsp;&nbsp;&nbsp; [<img src="https://raw.githubusercontent.com/madeintandem/jsonb_accessor/master/tandem-logo.png" alt="Tandem Logo" />](https://www.madeintandem.com/)
+
+[![Gem Version](https://badge.fury.io/rb/jsonb_accessor.svg)](http://badge.fury.io/rb/jsonb_accessor) &nbsp;&nbsp;&nbsp;![CI](https://github.com/madeintandem/jsonb_accessor/actions/workflows/ci.yml/badge.svg) <img src="https://raw.githubusercontent.com/madeintandem/jsonb_accessor/master/json-bee.png" alt="JSONb Accessor Logo" align="right" />
+
+Adds typed `jsonb` backed fields as first class citizens to your `ActiveRecord` models. This gem is similar in spirit to [HstoreAccessor](https://github.com/madeintandem/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.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Scopes](#scopes)
+- [Single-Table Inheritance](#single-table-inheritance)
+- [Dependencies](#dependencies)
+- [Validations](#validations)
+- [Upgrading](#upgrading)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "jsonb_accessor"
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+First we must create a model which has a `jsonb` column available to store data into it:
+
+```ruby
+class CreateProducts < ActiveRecord::Migration
+  def change
+    create_table :products do |t|
+      t.jsonb :data
+    end
+  end
+end
+```
+
+We can then declare the `jsonb` fields we wish to expose via the accessor:
+
+```ruby
+class Product < ActiveRecord::Base
+  jsonb_accessor :data,
+    title: :string,
+    external_id: :integer,
+    reviewed_at: :datetime
+end
+```
+
+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
+```
+
+The `default` option works pretty much as you would expect in practice; if no values are set for the attributes, a hash of the specified default values is saved to the jsonb column.
+
+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 like the json column with `_where` suffix, in our case `data_where`.
+
+```ruby
+Product.all.data_where(name: "Granite Towel", price: 17)
+```
+
+Similarly, it will also add a `data_where_not` `scope` to `Product`.
+
+```ruby
+Product.all.data_where_not(name: "Plasma Fork")
+```
+
+For number fields you can query using `<` or `>`or use plain english if that's what you prefer.
+
+```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 })
+```
+
+If you want to search for records within a certain time, date, or number range, just pass in the range (Note: this is just shorthand for the above mentioned `before`/`after`/`less_than`/`less_than_or_equal_to`/`greater_than_or_equal_to`/etc options).
+
+```ruby
+Product.all.data_where(price: 10..20)
+Product.all.data_where(price: 10...20)
+Product.all.data_where(reviewed_at: Time.current..3.days.from_now)
+```
+
+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_where_not`
+
+Just the opposite of `jsonb_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).
+
+```ruby
+Product.all.jsonb_where_not(:data, reviewed_at: { before: Time.current }, p: { greater_than: 5 })
+```
+
+### `<jsonb_attribute>_order`
+
+Orders your query according to values in the Jsonb Accessor fields similar to ActiveRecord's `order`.
+
+```ruby
+Product.all.data_order(:price)
+Product.all.data_order(:price, :reviewed_at)
+Product.all.data_order(:price, reviewed_at: :desc)
+```
+
+It will convert your given keys into store keys if necessary.
+
+### `jsonb_order`
+
+Allows you to order by a Jsonb Accessor field.
+
+```ruby
+Product.all.jsonb_order(:data, :price, :asc)
+Product.all.jsonb_order(:data, :price, :desc)
+```
+
+### `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_excludes`
+
+Returns all records that exclude the given JSON paths. Pretty much the opposite of `jsonb_contains`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).
+
+```ruby
+Product.all.jsonb_excludes(:data, title: "foo")
+Product.all.jsonb_excludes(:data, reviewed_at: 10.minutes.ago, p: 12) # Using the store key
+```
+
+### `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_number_where_not`
+
+Returns all records that do not match the given criteria. It's the opposite of `jsonb_number_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).
+
+```ruby
+Product.all.jsonb_number_where_not(:data, :price_in_cents, :greater_than, 300)
+```
+
+### `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.
+
+### `jsonb_time_where_not`
+
+Returns all records that match the given criteria. The opposite of `jsonb_time_where`. Note that this will automatically exclude all records that contain `null` in their jsonb column (the `data` column, in the example below).
+
+```ruby
+Product.all.jsonb_time_where_not(:data, :reviewed_at, :before, 2.days.ago)
+```
+
+## Single-Table Inheritance
+
+One of the big issues with `ActiveRecord` single-table inheritance (STI)
+is sparse columns. Essentially, as sub-types of the original table
+diverge further from their parent more columns are left empty in a given
+table. Postgres' `jsonb` type provides part of the solution in that
+the values in an `jsonb` column does not impose a structure - different
+rows can have different values.
+
+We set up our table with an `jsonb` field:
+
+```ruby
+# db/migration/<timestamp>_create_players.rb
+class CreateVehicles < ActiveRecord::Migration
+  def change
+    create_table :vehicles do |t|
+      t.string :make
+      t.string :model
+      t.integer :model_year
+      t.string :type
+      t.jsonb :data
+    end
+  end
+end
+```
+
+And for our models:
+
+```ruby
+# app/models/vehicle.rb
+class Vehicle < ActiveRecord::Base
+end
+
+# app/models/vehicles/automobile.rb
+class Automobile < Vehicle
+  jsonb_accessor :data,
+    axle_count: :integer,
+    weight: :float
+end
+
+# app/models/vehicles/airplane.rb
+class Airplane < Vehicle
+  jsonb_accessor :data,
+    engine_type: :string,
+    safety_rating: :integer
+end
+```
+
+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 conceived by Joe Hirn in [this blog
+post](https://madeintandem.com/blog/2013-3-single-table-inheritance-hstore-lovely-combination/).
+
+## Validations
+
+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
+- Postgres >= 9.4 (in order to use the [jsonb column type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)).
+
+## Upgrading
+
+See the [upgrade guide](UPGRADE_GUIDE.md).
+
+## Development
+
+### On your local machine
+
+After checking out the repo, run `bin/setup` to install dependencies (make sure postgres is running first).
+
+Run `bin/console` for an interactive prompt that will allow you to experiment.
+
+`rake` will run Rubocop and the specs.
+
+### With Docker
+
+```
+# setup
+docker-compose build
+docker-compose run ruby rake db:migrate
+# run test suite
+docker-compose run ruby rake spec
+```
+
+## Contributing
+
+1. [Fork it](https://github.com/madeintandem/jsonb_accessor/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Add tests and changes (run the tests with `rake`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "active_record"
+require "erb"
+
+RSpec::Core::RakeTask.new
+RuboCop::RakeTask.new
+
+# rubocop:disable Style/MixinUsage
+include ActiveRecord::Tasks
+# rubocop:enable Style/MixinUsage
+
+root = File.expand_path __dir__
+db_dir = File.join(root, "db")
+DatabaseTasks.root = root
+DatabaseTasks.db_dir = db_dir
+DatabaseTasks.database_configuration = YAML.safe_load(ERB.new(File.read(File.join(db_dir, "config.yml"))).result, aliases: true)
+DatabaseTasks.migrations_paths = [File.join(db_dir, "migrate")]
+DatabaseTasks.env = "test"
+
+task :environment do
+  ActiveRecord::Base.configurations = DatabaseTasks.database_configuration
+  ActiveRecord::Base.establish_connection DatabaseTasks.env.to_sym
+end
+
+load "active_record/railties/databases.rake"
+
+task(default: %i[rubocop spec])

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/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "jsonb_accessor"
+require "rspec"
+require File.expand_path("../spec/spec_helper.rb", __dir__)
+
+dbconfig = YAML.safe_load(ERB.new(File.read(File.join("db", "config.yml"))).result, aliases: true)
+ActiveRecord::Base.establish_connection(dbconfig["development"])
+
+# rubocop:disable Lint/UselessAssignment
+x = Product.new
+# rubocop:enable Lint/UselessAssignment
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle
+
+rake db:create
+rake db:migrate

data/db/config.yml

@@ -0,0 +1,8 @@
+default: &default
+  adapter: postgresql
+  database: jsonb_accessor
+  host: <%= ENV.fetch("DATABASE_HOST") { "127.0.0.1" } %>
+  user: postgres
+
+test:
+  <<: *default

data/db/migrate/20150407031737_set_up_testing_db.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class SetUpTestingDb < ActiveRecord::Migration[5.0]
+  def change
+    create_table :products do |t|
+      t.jsonb :options
+      t.jsonb :data
+
+      t.string :string_type
+      t.integer :integer_type
+      t.integer :product_category_id
+      t.boolean :boolean_type
+      t.float :float_type
+      t.time :time_type
+      t.date :date_type
+      t.datetime :datetime_type
+      t.decimal :decimal_type
+    end
+
+    create_table :product_categories do |t|
+      t.jsonb :options
+    end
+  end
+end

data/db/schema.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# Note that this schema.rb definition is the authoritative source for your
+# database schema. If you need to create the application database on another
+# system, you should be using db:schema:load, not running all the migrations
+# from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# you'll amass, the slower it'll run and the greater likelihood for issues).
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema.define(version: 20_150_407_031_737) do
+  # These are extensions that must be enabled in order to support this database
+  enable_extension "plpgsql"
+
+  create_table "product_categories", id: :serial, force: :cascade do |t|
+    t.jsonb "options"
+  end
+
+  create_table "products", id: :serial, force: :cascade do |t|
+    t.jsonb "options"
+    t.jsonb "data"
+    t.string "string_type"
+    t.integer "integer_type"
+    t.integer "product_category_id"
+    t.boolean "boolean_type"
+    t.float "float_type"
+    t.time "time_type"
+    t.date "date_type"
+    t.datetime "datetime_type"
+    t.decimal "decimal_type"
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,29 @@
+version: '3'
+
+services:
+  ruby:
+    environment:
+      - DATABASE_HOST=postgres
+    build:
+      args:
+        - RUBY_VERSION=${RUBY_VERSION:-2.7.2}
+      context: .
+    volumes:
+      - '.:/usr/src/app'
+    depends_on:
+      - postgres
+
+
+  postgres:
+    image: postgres:12
+    environment:
+      - POSTGRES_HOST_AUTH_METHOD=trust
+      - POSTGRES_DB=jsonb_accessor
+      - PGDATA=/var/lib/postgresql/data/pgdata
+    volumes:                                                                                    
+      - pg_data:/var/lib/postgresql/data/pgdata
+    ports:
+      - 5432:5432
+
+volumes:                                                                                        
+  pg_data:

data/gemfiles/activerecord_5.0.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 5.0.0"
+
+gemspec path: "../"

data/gemfiles/activerecord_5.1.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 5.1.3"
+
+gemspec path: "../"

data/gemfiles/activerecord_5.2.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 5.2.8"
+
+gemspec path: "../"

data/gemfiles/activerecord_6.0.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 6.0.6"
+
+gemspec path: "../"

data/gemfiles/activerecord_6.1.0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 6.1"
+
+gemspec path: "../"

data/gemfiles/activerecord_7.0.1.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 7.0.1"
+
+gemspec path: "../"

data/jsonb_accessor.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "jsonb_accessor/version"
+
+is_java = RUBY_PLATFORM == "java"
+
+Gem::Specification.new do |spec|
+  spec.name                  = "jsonb_accessor"
+  spec.version               = JsonbAccessor::VERSION
+  spec.authors               = ["Michael Crismali", "Joe Hirn", "Jason Haruska"]
+  spec.email                 = ["michael@crismali.com", "joe@devmynd.com", "jason@haruska.com"]
+  spec.platform              = "java" if is_java
+
+  spec.summary               = "Adds typed jsonb backed fields to your ActiveRecord models."
+  spec.description           = "Adds typed jsonb backed fields to your ActiveRecord models."
+  spec.homepage              = "https://github.com/devmynd/jsonb_accessor"
+  spec.license               = "MIT"
+  spec.required_ruby_version = ">= 2"
+
+  spec.files                 = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(/png\z/) }
+  spec.bindir                = "exe"
+  spec.executables           = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths         = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 5.0"
+  spec.add_dependency "activesupport", ">= 5.0"
+  if is_java
+    spec.add_dependency "activerecord-jdbcpostgresql-adapter", ">= 50.0"
+  else
+    spec.add_dependency "pg", ">= 0.18.1"
+  end
+
+  spec.add_development_dependency "appraisal", "~> 2.2.0"
+  spec.add_development_dependency "awesome_print"
+  spec.add_development_dependency "database_cleaner", "~> 1.6.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-doc"
+  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency "psych", "~> 3"
+  spec.add_development_dependency "rake", ">= 12.3.3"
+  spec.add_development_dependency "rspec", "~> 3.6.0"
+  spec.add_development_dependency "rubocop", "~> 1"
+end