squint 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 861884fea5cb7280a63e0759876ae2aae7a00750
-  data.tar.gz: 6e2a4f8b024b165ef215e3a135063fdb235002f4
+  metadata.gz: df371ee0e87ea3faac9e9fc9a41b348f0ff30424
+  data.tar.gz: d44f014f0e8fa11d00f23bf19a6fa29d4954b035
 SHA512:
-  metadata.gz: c8403702ac72aaef517fb97ef8042f9bb28170cddf4edbe6e11c655993f29301206d2bd7b70bf2c943fb5f6ef7f782141d044acd1f61ad539995575b7d4c238b
-  data.tar.gz: 7f355faa0113834c322e9c13093ff556914bfff0438e809144eedfb0efe729b72cc6174f72fa348281c03ea65739ba5921720ca414029cbccc32bd502afb1fb3
+  metadata.gz: b8459d887335bb272cbd9d0fb8e31f012d2c573e710c3dc2b2a4d6e07057187171c7dbc8e9fbd873cec58741199aae5804861698c9eba2bdfaf5fd6ae6e3f69b
+  data.tar.gz: d000d6ebde399bb8edaead6c27e43aeb78575b81072eb9d0f0aa96e860cfb61bf45d0e169a1830bf6f7428e4c0511cd4798ac1ae900f882a636276d3a35a2345

data/.all-contributorsrc

@@ -0,0 +1,86 @@
+{
+  "projectName": "squint",
+  "projectOwner": "ProctorU",
+  "files": [
+    "readme.md"
+  ],
+  "imageSize": 100,
+  "commit": true,
+  "contributors": [
+    {
+      "login": "chevinbrown",
+      "name": "Kevin Brown",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/864581?v=3",
+      "profile": "https://github.com/chevinbrown",
+      "contributions": [
+        "design",
+        "review"
+      ]
+    },
+    {
+      "login": "king601",
+      "name": "Andrew Fomera",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/1741179?v=3",
+      "profile": "http://andrewfomera.com",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "Jaehdawg",
+      "name": "Matthew Jaeh",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/1785682?v=3",
+      "profile": "https://github.com/Jaehdawg",
+      "contributions": [
+        "design",
+        "review"
+      ]
+    },
+    {
+      "login": "rthbound",
+      "name": "Ryan T. Hosford",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/708692?v=3",
+      "profile": "https://github.com/rthbound",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "licatajustin",
+      "name": "Justin Licata",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/3933204?v=3",
+      "profile": "https://twitter.com/justinlicata",
+      "contributions": [
+        "code",
+        "design",
+        "doc",
+        "review"
+      ]
+    },
+    {
+      "login": "dwilkins",
+      "name": "David H. Wilkins",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/97011?v=3",
+      "profile": "http://conecuh.com",
+      "contributions": [
+        "question",
+        "bug",
+        "code",
+        "design",
+        "doc",
+        "example",
+        "review",
+        "test"
+      ]
+    },
+    {
+      "login": "TheJayWright",
+      "name": "Jay Wright",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/19173815?v=3",
+      "profile": "https://github.com/TheJayWright",
+      "contributions": [
+        "review"
+      ]
+    }
+  ]
+}

data/lib/squint.rb

@@ -3,23 +3,34 @@ require 'active_support/concern'
 # Squint json, jsonb, hstore queries
 module Squint
   extend ActiveSupport::Concern
-  include ::ActiveRecord::QueryMethods
+  if ActiveRecord::VERSION::STRING < '5'
+    include ::ActiveRecord::QueryMethods
+  end
 
   module WhereMethods
-    # Args may be passed to build_where like:
+    # Args may be passed to build/build_where like:
     #  build_where(jsonb_column: {key1: value1})
     #  build_where(jsonb_column: {key1: value1}, jsonb_column: {key2: value2})
     #  build_where(jsonb_column: {key1: value1}, regular_column: value)
     #  build_where(jsonb_column: {key1: value1}, association: {column: value))
-    def build_where(*args)
+    if ActiveRecord::VERSION::STRING > '5'
+      method_name = :build
+    elsif ActiveRecord::VERSION::STRING < '5'
+      method_name = :build_where
+    end
+    send :define_method, method_name do |*args|
+      # For Rails 5, we end up monkey patching WhereClauseFactory for everyone
+      # so need to return super if our methods aren't on the AR class
+      # doesn't hurt for 4.2.x either
+      return super(*args) unless klass.respond_to?(:squint_hash_field_reln)
       save_args = []
       reln = args.inject([]) do |memo, arg|
         if arg.is_a?(Hash)
           arg.keys.each do |key|
             if arg[key].is_a?(Hash) && HASH_DATA_COLUMNS[key]
-              memo << hash_field_reln(key => arg[key])
+              memo << klass.squint_hash_field_reln(key => arg[key])
             else
-              memo += super(key => arg[key])
+              save_args << {  key => arg[key] }
             end
           end
         elsif arg.present?
@@ -27,15 +38,51 @@ module Squint
         end
         memo
       end
+      if ActiveRecord::VERSION::STRING > '5'
+        reln = ActiveRecord::Relation::WhereClause.new(reln, [])
+        save_args << [] if save_args.size == 1
+      end
       reln += super(*save_args) unless save_args.empty?
       reln
     end
+  end
+
+  included do |base|
+    if ActiveRecord::VERSION::STRING < '5'
+      ar_reln_module = base::ActiveRecord_Relation
+      ar_association_module = base::ActiveRecord_AssociationRelation
+    elsif ActiveRecord::VERSION::STRING > '5.1'
+      # ActiveRecord_Relation is now a private_constant in 5.1.x
+      ar_reln_module = base.relation_delegate_class(ActiveRecord::Relation)::WhereClauseFactory
+      ar_association_module = nil
+    elsif ActiveRecord::VERSION::STRING > '5.0'
+      ar_reln_module = base::ActiveRecord_Relation::WhereClauseFactory
+      ar_association_module = nil
+      # ar_association_module = base::ActiveRecord_AssociationRelation
+    end
+
+    # put together a list of columns in this model
+    # that are hstore, json, or jsonb and will benefit from
+    # searchability
+    HASH_DATA_COLUMNS = base.columns_hash.keys.map do |col_name|
+      if %w[hstore json jsonb].include?(base.columns_hash[col_name].sql_type)
+        [col_name.to_sym, base.columns_hash[col_name].sql_type]
+      end
+    end.compact.to_h
 
-    # hash_field_reln
+    ar_reln_module.class_eval do
+      prepend WhereMethods
+    end
+
+    ar_association_module.try(:class_eval) do
+      prepend WhereMethods
+    end
+
+    # squint_hash_field_reln
     # return an Arel object with the appropriate query
     # Strings want to be a SQL Literal, other things can be
     # passed in bare to the eq or in operator
-    def hash_field_reln(*args)
+    def self.squint_hash_field_reln(*args)
       temp_attr = args[0]
       contains_nil = false
       column_type = HASH_DATA_COLUMNS[args[0].keys.first]
@@ -100,109 +147,84 @@ module Squint
       # specified as a query value
       if check_attr_missing
         reln = if column_type == 'hstore'.freeze
-                 hstore_element_missing(column_name_segments, reln)
+                 squint_hstore_element_missing(column_name_segments, reln)
                else
-                 jsonb_element_missing(column_name_segments, reln)
+                 squint_jsonb_element_missing(column_name_segments, reln)
                end
       end
       reln
     end
-  end
-
-  included do |base|
-    ar_reln_module = base::ActiveRecord_Relation
-    ar_association_module = base::ActiveRecord_AssociationRelation
 
-    # put together a list of columns in this model
-    # that are hstore, json, or jsonb and will benefit from
-    # searchability
-    HASH_DATA_COLUMNS = base.columns_hash.keys.map do |col_name|
-      if %w[hstore json jsonb].include?(base.columns_hash[col_name].sql_type)
-        [col_name.to_sym, base.columns_hash[col_name].sql_type]
+    def self.squint_storext_default?(temp_attr, attribute_sym)
+      return false unless respond_to?(:storext_definitions)
+      if storext_definitions.keys.include?(attribute_sym) &&
+         !(storext_definitions[attribute_sym][:opts] &&
+           storext_definitions[attribute_sym][:opts][:default]).nil? &&
+         [temp_attr].compact.map(&:to_s).
+           flatten.
+           include?(storext_definitions[attribute_sym][:opts][:default].to_s)
+        true
       end
-    end.compact.to_h
-
-    ar_reln_module.class_eval do
-      prepend WhereMethods
     end
 
-    ar_association_module.class_eval do
-      prepend WhereMethods
+    def self.squint_hstore_element_exists(element, attribute_hash_column, value)
+      Arel::Nodes::Equality.new(
+        Arel::Nodes::NamedFunction.new(
+          "exist",
+          [arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
+           Arel::Nodes::SqlLiteral.new(element)]
+        ), value
+      )
     end
 
-    def self.jsonb_element_missing(column_name_segments, reln)
+    def self.squint_hstore_element_missing(column_name_segments, reln)
       element = column_name_segments.pop
       attribute_hash_column = column_name_segments.join('->'.freeze)
       # Query generated is equals default or attribute present is null or equals false
-      #    * Is null happens when the the whole column is null
+      #    * Is null happens the the column is null
       #    * equals false is when the column has jsonb data, but the key doesn't exist
       # ("posts"."storext_attributes"->>'is_awesome' = 'false' OR
-      #   (("posts"."storext_attributes" ? 'is_awesome') IS NULL OR
-      #    ("posts"."storext_attributes" ? 'is_awesome') = FALSE)
+      #   (exists("posts"."storext_attributes", 'is_awesome') IS NULL OR
+      #    exists("posts"."storext_attributes", 'is_awesome') = FALSE)
       # )
       Arel::Nodes::Grouping.new(
         reln.or(
           Arel::Nodes::Grouping.new(
-            Arel::Nodes::Equality.new(
-              Arel::Nodes::Grouping.new(
-                Arel::Nodes::InfixOperation.new(
-                  Arel::Nodes::SqlLiteral.new('?'),
-                  arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
-                  Arel::Nodes::SqlLiteral.new(element)
-                )
-              ), nil
-            ).or(
-              Arel::Nodes::Equality.new(
-                Arel::Nodes::Grouping.new(
-                  Arel::Nodes::InfixOperation.new(
-                    Arel::Nodes::SqlLiteral.new('?'),
-                    arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
-                    Arel::Nodes::SqlLiteral.new(element)
-                  )
-                ), Arel::Nodes::False.new
-              )
-            )
+            squint_hstore_element_exists(element, attribute_hash_column, Arel::Nodes::False.new)
+          ).or(
+            squint_hstore_element_exists(element, attribute_hash_column, nil)
           )
         )
       )
     end
 
-    def self.squint_storext_default?(temp_attr, attribute_sym)
-      return false unless respond_to?(:storext_definitions)
-      if storext_definitions.keys.include?(attribute_sym) &&
-         !storext_definitions[attribute_sym].dig(:opts, :default).nil? &&
-         [temp_attr].compact.map(&:to_s).
-           flatten.
-           include?(storext_definitions[attribute_sym][:opts][:default].to_s)
-        true
-      end
+    def self.squint_jsonb_element_equality(element, attribute_hash_column, value)
+      Arel::Nodes::Equality.new(
+        Arel::Nodes::Grouping.new(
+          Arel::Nodes::InfixOperation.new(
+            Arel::Nodes::SqlLiteral.new('?'),
+            arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
+            Arel::Nodes::SqlLiteral.new(element)
+          )
+        ), value
+      )
     end
 
-    def self.hstore_element_missing(column_name_segments, reln)
+    def self.squint_jsonb_element_missing(column_name_segments, reln)
       element = column_name_segments.pop
       attribute_hash_column = column_name_segments.join('->'.freeze)
       # Query generated is equals default or attribute present is null or equals false
-      #    * Is null happens the the column is null
+      #    * Is null happens when the the whole column is null
       #    * equals false is when the column has jsonb data, but the key doesn't exist
       # ("posts"."storext_attributes"->>'is_awesome' = 'false' OR
-      #   (exists("posts"."storext_attributes", 'is_awesome') IS NULL OR
-      #    exists("posts"."storext_attributes", 'is_awesome') = FALSE)
+      #   (("posts"."storext_attributes" ? 'is_awesome') IS NULL OR
+      #    ("posts"."storext_attributes" ? 'is_awesome') = FALSE)
       # )
       Arel::Nodes::Grouping.new(
         reln.or(
           Arel::Nodes::Grouping.new(
-            Arel::Nodes::NamedFunction.new(
-              "exist",
-              [arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
-               Arel::Nodes::SqlLiteral.new(element)]
-            ).eq(Arel::Nodes::False.new)
-          ).or(
-            Arel::Nodes::Equality.new(
-              Arel::Nodes::NamedFunction.new(
-                "exist",
-                [arel_table[Arel::Nodes::SqlLiteral.new(attribute_hash_column)],
-                 Arel::Nodes::SqlLiteral.new(element)]
-              ), nil
+            squint_jsonb_element_equality(element, attribute_hash_column, nil).or(
+              squint_jsonb_element_equality(element, attribute_hash_column, Arel::Nodes::False.new)
             )
           )
         )

data/lib/squint/version.rb

@@ -1,3 +1,3 @@
 module Squint
-  VERSION = "0.0.3".freeze
+  VERSION = "1.0.0".freeze
 end

data/readme.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <a href="https://twitter.com/ProctorUEng">
+    <img src="https://s3-us-west-2.amazonaws.com/dev-team-resources/squint-wordmark.svg" width=198 height=72>
+  </a>
+
+  <p align="center">
+    Search PostgreSQL <code>jsonb</code> and <code>hstore</code> columns.
+  </p>
+</p>
+
+<br>
+
+> Full database searching inside columns containing semi-structured data like `json`,
+`jsonb` and `hstore`. <strong>Compatible with the awesome
+<a href="https://github.com/G5/storext">storext</a> gem</strong>.
+
+## Table of contents
+
+- [Status](#status)
+- [Quick start](#quick-start)
+- [Performance](#performance)
+- [Storext attributes](#storext-attributes)
+- [Developing](#developing)
+- [Contributors](#contributors)
+- [Credits](#credits)
+
+## Status
+[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors)
+[![CircleCI](https://circleci.com/gh/ProctorU/squint.svg?style=svg)](https://circleci.com/gh/ProctorU/squint)
+
+## Quick Start
+
+Add to your Gemfile:
+
+```ruby
+gem 'squint'
+```
+
+Include it in your models:
+
+```ruby
+class Post < ActiveRecord::Base
+  include Squint
+  # ...
+end
+```
+
+Assuming a table with the following structure:
+```
+                                           Table "public.posts"
+       Column              |            Type             |                     Modifiers
+---------------------------+-----------------------------+----------------------------------------------------
+ id                        | integer                     | not null default nextval('posts_id_seq'::regclass)
+ title                     | character varying           |
+ body                      | character varying           |
+ request_info              | jsonb                       |
+ properties                | hstore                      |
+ storext_jsonb_attributes  | jsonb                       |
+ storext_hstore_attributes | jsonb                       |
+ created_at                | timestamp without time zone | not null
+ updated_at                | timestamp without time zone | not null
+Indexes:
+    "posts_pkey" PRIMARY KEY, btree (id)
+```
+
+In your code use queries like:
+```ruby
+Post.where(properties: { referer: 'http://example.com/one' } )
+# SELECT "posts".* FROM "posts" WHERE "posts"."properties"->'referer' = 'http://example.com/one'
+
+Post.where(properties: { referer: nil } )
+# SELECT "posts".* FROM "posts" WHERE "posts"."properties"->'referer' IS NULL
+
+Post.where(properties: { referer: ['http://example.com/one',nil] } )
+# SELECT "posts".* FROM "posts" WHERE ("posts"."properties"->'referer' = 'http://example.com/one'
+#                                   OR "posts"."properties"->'referer' IS NULL)
+
+Post.where(request_info: { referer: ['http://example.com/one',nil] } )
+# SELECT "posts".* FROM "posts" WHERE ("posts"."request_info"->>'referer' = 'http://example.com/one'
+#                                   OR "posts"."request_info"->>'referer' IS NULL)
+```
+
+Squint only operates on json, jsonb and hstore columns.   ActiveRecord
+will throw a StatementInvalid exception like always if the column type is unsupported by
+Squint.
+
+```ruby
+Post.where(title: { not_there: "any value will do" } )
+```
+
+```
+ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR:  missing FROM-clause entry for table "title"
+LINE 1: SELECT COUNT(*) FROM "posts" WHERE "title"."not_there" = 'an...
+                                           ^
+: SELECT COUNT(*) FROM "posts" WHERE "title"."not_there" = 'any value will do'
+```
+
+## Performance
+To get the most performance out searching jsonb/hstore attributes, add a GIN (preferred) or
+GIST index to those columns.   Find out more
+[here](https://www.postgresql.org/docs/9.5/static/textsearch-indexes.html)
+
+TL;DR:
+
+SQL: 'CREATE INDEX name ON table USING GIN (column);'
+
+Rails Migration: `add_index(:table, :column_name, using: 'gin')`
+
+
+## Storext attributes
+Assuming the database schema above and a model like so:
+```ruby
+class Post < ActiveRecord::Base
+  include Storext.model
+  include Squint
+
+  store_attribute :storext_jsonb_attributes, :zip_code, String, default: '90210'
+  store_attribute :storext_jsonb_attributes, :friend_count, Integer, default: 0
+end
+```
+
+Example using StoreXT with a default value:
+```ruby
+Post.where(storext_jsonb_attributes: { zip_code: '90210' } )
+# -- jsonb
+# SELECT "posts".* FROM "posts" WHERE ("posts"."storext_jsonb_attributes"->>'zip_code' = '90210' OR
+#                                     (("posts"."storext_jsonb_attributes" ? 'zip_code') IS NULL OR
+#                                      ("posts"."storext_jsonb_attributes" ? 'zip_code') = FALSE))
+# -- hstore
+# SELECT "posts".* FROM "posts" WHERE ("posts"."storext_hstore_attributes"->'zip_code' = '90210' OR
+#                                     ((exist("posts"."storext_hstore_attributes", 'zip_code') = FALSE) OR
+#                                       exist("posts"."storext_hstore_attributes", 'zip_code') IS NULL))
+#
+#
+```
+If (as in the example above) the default value for the StoreXT attribute is specified, then extra
+checks for missing column ( `("posts"."storext_jsonb_attributes" ? 'zip_code') IS NULL` ) or
+missing key ( `("posts"."storext_jsonb_attributes" ? 'zip_code') = FALSE)` ) are added
+
+When non-default storext values are specified, these extra checks won't be added.
+
+The Postgres SQL for jsonb and hstore is different.   No support for checking for missing `json`
+columns exists, so don't use those with StoreXT + Squint
+
+## Developing
+
+1. Thank you!
+1. Clone the repository
+1. `bundle`
+1. `bundle exec rake --rakefile test/dummy/Rakefile db:setup` # create the db for tests
+1. `bundle exec rake`   # run the tests
+1. make your changes in a thoughtfully named branch
+1. ensure good test coverage
+1. submit a Pull Request
+
+## Contributors
+
+Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+| [<img src="https://avatars2.githubusercontent.com/u/864581?v=3" width="100px;"/><br /><sub>Kevin Brown</sub>](https://github.com/chevinbrown)<br />[🎨](#design-chevinbrown "Design") [👀](#review-chevinbrown "Reviewed Pull Requests") | [<img src="https://avatars2.githubusercontent.com/u/1741179?v=3" width="100px;"/><br /><sub>Andrew Fomera</sub>](http://andrewfomera.com)<br />[👀](#review-king601 "Reviewed Pull Requests") | [<img src="https://avatars2.githubusercontent.com/u/1785682?v=3" width="100px;"/><br /><sub>Matthew Jaeh</sub>](https://github.com/Jaehdawg)<br />[🎨](#design-Jaehdawg "Design") [👀](#review-Jaehdawg "Reviewed Pull Requests") | [<img src="https://avatars2.githubusercontent.com/u/708692?v=3" width="100px;"/><br /><sub>Ryan T. Hosford</sub>](https://github.com/rthbound)<br />[💻](https://github.com/ProctorU/squint/commits?author=rthbound "Code") | [<img src="https://avatars0.githubusercontent.com/u/3933204?v=3" width="100px;"/><br /><sub>Justin Licata</sub>](https://twitter.com/justinlicata)<br />[💻](https://github.com/ProctorU/squint/commits?author=licatajustin "Code") [🎨](#design-licatajustin "Design") [📖](https://github.com/ProctorU/squint/commits?author=licatajustin "Documentation") [👀](#review-licatajustin "Reviewed Pull Requests") | [<img src="https://avatars2.githubusercontent.com/u/97011?v=3" width="100px;"/><br /><sub>David H. Wilkins</sub>](http://conecuh.com)<br />[💬](#question-dwilkins "Answering Questions") [🐛](https://github.com/ProctorU/squint/issues?q=author%3Adwilkins "Bug reports") [💻](https://github.com/ProctorU/squint/commits?author=dwilkins "Code") [🎨](#design-dwilkins "Design") [📖](https://github.com/ProctorU/squint/commits?author=dwilkins "Documentation") [💡](#example-dwilkins "Examples") [👀](#review-dwilkins "Reviewed Pull Requests") [⚠️](https://github.com/ProctorU/squint/commits?author=dwilkins "Tests") | [<img src="https://avatars3.githubusercontent.com/u/19173815?v=3" width="100px;"/><br /><sub>Jay Wright</sub>](https://github.com/TheJayWright)<br />[👀](#review-TheJayWright "Reviewed Pull Requests") |
+| :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
+
+## Credits
+
+Squint is maintained and funded by [ProctorU](https://twitter.com/ProctorUEng).
+
+<br>
+
+<p align="center">
+  <a href="https://twitter.com/ProctorUEng">
+    <img src="https://s3-us-west-2.amazonaws.com/dev-team-resources/procki-eyes.svg" width=108 height=72>
+  </a>
+
+  <h3 align="center">
+    <a href="https://twitter.com/ProctorUEng">ProctorU Engineering & Design</a>
+  </h3>
+
+  <p align="center">
+    A simple online proctoring service that allows you to take exams or certification tests at home.
+  </p>
+</p>