stairwell 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7846f146e7d718b2c1dacaaf795e2093c3f24a5a4ee520a2821c6a3bb23d2ca2
-  data.tar.gz: 3b39deebbb1db67dd063953d92899b4cc4b94a96fda740a0c6b2173ef28e7c24
+  metadata.gz: e963ad4c2388946d0baae50090e6f3e9913e49dcdd896cdd18403861d72b9a40
+  data.tar.gz: 29cb2a589732e6e4b0b43115da878d8b4463eb59a1ad46726d01595bc0f56f19
 SHA512:
-  metadata.gz: 1e678fe8b202b64ba0d2abbd1771983fc2a72c9a757478c6cfac163af7985b68f8e2d47458a01715b81c756153f6858963cb6d3d59ed9223d089ff6fdebeb01e
-  data.tar.gz: 7fe23548a55c4ea1eb3f10d1ab8eb375699f7849e084af9346eee041fef19c5129558952b662d4814adbb0439f5e5af17bce02f27884f58fc0e8c3adf01dc483
+  metadata.gz: 0d21bd2ad1fc8a8b04de7da744dae787a474a33fbb42146a4b77d218d5ee493c25ed930da39b23a4ce45a67448920924e5d2a4006ba62978422caf3c43156395
+  data.tar.gz: 229bc47578fea9e530d10291d79d94bcd042222e767f5627b45e4b7867af09e76958a34b9d4208b6763c1d89fcea5399317ad6c4047c547e2bae11e62361f61c

data/Gemfile.lock

@@ -1,18 +1,52 @@
 PATH
   remote: .
   specs:
-    stairwell (0.1.1)
+    stairwell (0.3.0)
+      activerecord (>= 4.2.11)
+      sqlite3
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activemodel (7.1.1)
+      activesupport (= 7.1.1)
+    activerecord (7.1.1)
+      activemodel (= 7.1.1)
+      activesupport (= 7.1.1)
+      timeout (>= 0.4.0)
+    activesupport (7.1.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.1.1)
+    bigdecimal (3.1.4)
     coderay (1.1.3)
+    concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
+    drb (2.1.1)
+      ruby2_keywords
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
     method_source (1.0.0)
-    minitest (5.14.1)
+    mini_portile2 (2.8.5)
+    minitest (5.20.0)
+    mutex_m (0.1.2)
     pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     rake (12.3.3)
+    ruby2_keywords (0.0.5)
+    sqlite3 (1.6.7)
+      mini_portile2 (~> 2.8.0)
+    timeout (0.4.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -18,9 +18,15 @@ Or install it yourself as:
 
     $ gem install stairwell
 
+## Why?
+Although ActiveRecord serves as an excellent tool for the majority of database queries, certain scenarios call for more customized queries.
+This project was initially conceived to help transition a development team and their project from PHP to Ruby. This PHP project had thousands of complex SQL queries, thus the necessity of making SQL a first-class citizen in the ruby project enabled a smoother transition.
+So, why not Arel? Arel is a powerful tool, but it's worth noting that it is considered a private API and is likely to remain so for the forseeable future.
+Does this approach make queries less composable? Yes, if you are used to chaining your arel queries and AR scopes then you're probably not going to use this. However, it provides an interface that enables you to leverage SQL securely in your Ruby projects without the need to reinvent the wheel.
+
 ## Usage
 
-Define a class in your app that inherits from `Stairwell::Query`. We're going to assume you are in a rails app, but this will work in any ruby app, ActiveRecord is not a dependency here.
+Define a class in your app that inherits from `Stairwell::Query`. We're going to assume you are in a rails app, but this will work in any ruby app, although ActiveRecord is a dependency of this gem.
 In rails you could create a directory called `app/queries` for instance.
 
 Define your `validate_type`, which will be the arguments you send in, and their type. For instance, if your query looks like this: `SELECT * FROM users WHERE name = :name`, and name is a `String`, your `validate_type` will look like this `validate_type :name, :string`, and you'll pass in a hash of your binds like this: `{ name: "<name value>" }`
@@ -34,6 +40,7 @@ class UsersSql < Stairwell::Query
   validate_type :gpa, :float
   validate_type :date_joined, :sql_date
   validate_type :created_at, :sql_date_time
+  validate_type :favorite_numbers, [:integer]
 
   query <<-SQL
     SELECT
@@ -45,6 +52,7 @@ class UsersSql < Stairwell::Query
       AND gpa = :gpa
       AND date_joined = :date_joined
       AND created_at >= :created_at
+      AND favorite_numbers IN (:favorite_numbers)
     ;
   SQL
 end
@@ -55,9 +63,10 @@ binds = {
   name: "First",
   age: 99,
   active: true,
-  gpa: 4.2
+  gpa: 4.2,
   date_joined: "2008-08-28",
   created_at: "2008-08-28 23:41:18",
+  favorite_numbers: [4, 7, 100]
 }
 
 # and call the following:
@@ -66,23 +75,33 @@ UsersSql.sql(binds)
 
 # You will receive the following result:
 
-"SELECT * FROM users WHERE name = 'First' age = 99 active = TRUE date_joined = '2008-08-28' created_at = '2008-08-28 23:41:18' gpa = 4.2;"
+"SELECT * FROM users WHERE name = 'First' AND age = 99 AND active = TRUE AND date_joined = '2008-08-28' AND created_at >= '2008-08-28 23:41:18' AND gpa = 4.2 AND favorite_numbers IN (4, 7, 100) ;"
 ```
 
 Binds passed in are validated against the validate_type, so if you have a validate_type you must include that value in your binds hash.
 They types of the binds are validated too.
 The names binds in your sql are also validated.
-Strings are quoted. Dates are quoted. Datetime is quoted.
-
-Tested in both Mysql and Postgres.
+All types are quoted using ActiveRecord quoting, which will be different depending on your database type (Mysql, postgres etc.)
+
+## Supported Types
+
+| Type         | Values Accepted      | Info                                                                                                 |
+|--------------|----------------------|------------------------------------------------------------------------------------------------------|
+| :boolean     | TrueClass/FalseClass | Not fully supported since many databases require 'IS TRUE' or 'IS FALSE'                             |
+| :column_name | String               | for quoting a column name                                                                            |
+| :date_time   | String               | only taking the actual string for now                                                                |
+| :date        | String               | only taking the actual string for now                                                                |
+| :float       | Float                |                                                                                                      |
+| [<type>]     | Array                | will quote any type provided in the array [:integer]                                                 |
+| :integer     | Integer              |                                                                                                      |
+| :null        | NilClass             | nil/NULL values are not completely supported since many databases require 'IS NULL' or 'IS NOT NULL' |
+| :string      | String               |                                                                                                      |
+| :table_name  | String               | for quoting a table name                                                                             |
 
 ## Known issues
 
-* nil/NULL values are not currently supported. Just use `IS NULL` or `IS NOT NULL` in your query for the time being.
+* nil/NULL values are not completely supported, since many databases require `IS NULL`, or `IS NOT NULL`, you can use the null_type here, but it will only accept `nil`, and it will possibly not support what you're trying to do. YMMV.
 * Date/Datetime are not validated for their format, it is expected that you will pass the correct format.
-* Datetime in postgres is not currently working for equality, only for `>` or `<` or `>=` or `<=`
-* Column/table quoting is not currently available.
-* `IN` statements with arrays support is forthcoming.
 
 
 ## Development

data/lib/stairwell/bind_transformer.rb

@@ -1,7 +1,7 @@
 module Stairwell
   class BindTransformer
 
-    attr_accessor :sql, :bind_hash, :depleting_bind_hash
+    attr_accessor :sql, :bind_hash, :depleting_bind_hash, :converted_sql
 
     def initialize(sql, bind_hash)
       @sql = sql
@@ -18,26 +18,29 @@ module Stairwell
     # with quoted values to ensure safety.
     # Note: $2 is The match for the first, second, etc. parenthesized groups in the last regex
     def transform
-      converted_sql = sql.gsub(/(:?):([a-zA-Z]\w*)/) do |_|
+      convert_sql
+      validate_bind_hash
+      converted_sql
+    end
+
+    def convert_sql
+      @converted_sql ||= sql.gsub(/(:?):([a-zA-Z]\w*)/) do |_|
         replace = $2.to_sym
         validate_sql(replace)
-        bind_hash[replace].sql_quote
+        bind_hash[replace].quote
       end
-
-      validate_bind_hash
-      converted_sql
     end
 
     private
 
       def validate_sql(attr)
-        raise SqlBindMismatch, ":#{attr} in your query is missing from your bind hash: #{bind_hash}" unless bind_hash[attr]
+        raise SqlBindMismatch, ":#{attr} in your query is missing from your args" unless bind_hash[attr]
 
         depleting_bind_hash.delete(attr)
       end
 
       def validate_bind_hash
-        raise SqlBindMismatch, "#{depleting_bind_hash} in your bind hash is missing from your query: #{sql}" unless depleting_bind_hash.empty?
+        raise SqlBindMismatch, ":#{depleting_bind_hash.keys.join(', ')} in your bind hash is missing from your query: #{sql}" unless depleting_bind_hash.empty?
       end
 
   end

data/lib/stairwell/query.rb

@@ -1,3 +1,15 @@
+require "stairwell/bind_transformer"
+require "stairwell/types/boolean_type"
+require "stairwell/types/column_name_type"
+require "stairwell/types/date_time_type"
+require "stairwell/types/date_type"
+require "stairwell/types/float_type"
+require "stairwell/types/integer_type"
+require "stairwell/types/in_type"
+require "stairwell/types/string_type"
+require "stairwell/types/null_type"
+require "stairwell/types/table_name_type"
+
 module Stairwell
   class Query
 
@@ -26,10 +38,15 @@ module Stairwell
 
           bind_hash.each do |bind_name, bind_value|
             type = all_validations[bind_name]
-            type = type.first if type.is_a?(Array)
-            valid = TypeValidator.send(type, bind_value)
+            if type.is_a?(Array)
+              type = type.first
+              type_object = Types::InType.new(bind_value, type)
+            end
+            type_object ||= Object.const_get(TYPE_CLASSES[type]).new(bind_value)
+
+            raise InvalidBindType.new("#{bind_name} is not #{all_validations[bind_name]}") unless type_object.valid?
 
-            raise InvalidBindType.new("#{bind_name} is not #{all_validations[bind_name]}") unless valid
+            bind_hash[bind_name] = type_object
           end
         end
 

data/lib/stairwell/types/base_type.rb

@@ -0,0 +1,17 @@
+module Stairwell::Types
+  class BaseType
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def quote
+      connection.quote(value)
+    end
+
+    def connection
+      @connection ||= ActiveRecord::Base.connection
+    end
+  end
+end

data/lib/stairwell/types/boolean_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class BooleanType < BaseType
+    def valid?
+      value.is_a?(TrueClass) || value.is_a?(FalseClass)
+    end
+  end
+end

data/lib/stairwell/types/column_name_type.rb

@@ -0,0 +1,13 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class ColumnNameType < BaseType
+    def valid?
+      value.is_a?(String)
+    end
+
+    def quote
+      connection.quote_column_name(value)
+    end
+  end
+end

data/lib/stairwell/types/date_time_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class DateTimeType < BaseType
+    def valid?
+      value.is_a?(String)
+    end
+  end
+end

data/lib/stairwell/types/date_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class DateType < BaseType
+    def valid?
+      value.is_a?(String)
+    end
+  end
+end

data/lib/stairwell/types/float_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class FloatType < BaseType
+    def valid?
+      value.is_a?(Float)
+    end
+  end
+end

data/lib/stairwell/types/in_type.rb

@@ -0,0 +1,28 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class InType
+    attr_reader :value, :type
+
+    def initialize(value, type)
+      @value = value
+      @type = type
+    end
+
+    def quote
+      contained_values.map(&:quote).join(", ")
+    end
+
+    def valid?
+      value.is_a?(Array) && contained_values.all?(&:valid?)
+    end
+
+    private
+
+      def contained_values
+        value.map do |contained|
+          Object.const_get(Stairwell::TYPE_CLASSES[type]).new(contained)
+        end
+      end
+  end
+end

data/lib/stairwell/types/integer_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class IntegerType < BaseType
+    def valid?
+      value.is_a?(Integer)
+    end
+  end
+end

data/lib/stairwell/types/null_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class NullType < BaseType
+    def valid?
+      value.is_a?(NilClass)
+    end
+  end
+end

data/lib/stairwell/types/string_type.rb

@@ -0,0 +1,9 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class StringType < BaseType
+    def valid?
+      value.is_a?(String)
+    end
+  end
+end

data/lib/stairwell/types/table_name_type.rb

@@ -0,0 +1,13 @@
+require "stairwell/types/base_type"
+
+module Stairwell::Types
+  class TableNameType < BaseType
+    def valid?
+      value.is_a?(String)
+    end
+
+    def quote
+      connection.quote_table_name(value)
+    end
+  end
+end

data/lib/stairwell/version.rb

@@ -1,3 +1,3 @@
 module Stairwell
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/stairwell.rb

@@ -1,14 +1,31 @@
+require "active_record"
 require "date"
-require "stairwell/bind_transformer"
 require "stairwell/query"
-require "stairwell/type_validator"
 require "stairwell/version"
-require "stairwell/core_extensions/core"
-require "stairwell/core_extensions/types"
 
 module Stairwell
   class Error < StandardError; end
   class InvalidBindType < StandardError; end
   class InvalidBindCount < StandardError; end
   class SqlBindMismatch < StandardError; end
+
+  TYPE_CLASSES = {
+    string: "Stairwell::Types::StringType",
+    integer: "Stairwell::Types::IntegerType",
+    boolean: "Stairwell::Types::BooleanType",
+    float: "Stairwell::Types::FloatType",
+    date: "Stairwell::Types::DateType",
+    date_time: "Stairwell::Types::DateTimeType",
+    null: "Stairwell::Types::NullType",
+    column_name: "Stairwell::Types::ColumnNameType",
+    table_name: "Stairwell::Types::TableNameType"
+  }.freeze
+
+  # for development and testing
+  unless defined?(Rails)
+    ActiveRecord::Base.establish_connection(
+      adapter: 'sqlite3',
+      database: 'test.db'
+    )
+  end
 end

data/stairwell.gemspec

@@ -25,4 +25,11 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activerecord', '>= 4.2.11'
+
+  # for development and testing
+  unless defined?(Rails)
+    spec.add_dependency 'sqlite3'
+  end
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: stairwell
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - tobyond
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-21 00:00:00.000000000 Z
-dependencies: []
+date: 2023-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.11
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Sanitize and quote raw SQL for rails and any project in ruby
 email:
 executables: []
@@ -27,12 +55,21 @@ files:
 - bin/setup
 - lib/stairwell.rb
 - lib/stairwell/bind_transformer.rb
-- lib/stairwell/core_extensions/core.rb
-- lib/stairwell/core_extensions/types.rb
 - lib/stairwell/query.rb
-- lib/stairwell/type_validator.rb
+- lib/stairwell/types/base_type.rb
+- lib/stairwell/types/boolean_type.rb
+- lib/stairwell/types/column_name_type.rb
+- lib/stairwell/types/date_time_type.rb
+- lib/stairwell/types/date_type.rb
+- lib/stairwell/types/float_type.rb
+- lib/stairwell/types/in_type.rb
+- lib/stairwell/types/integer_type.rb
+- lib/stairwell/types/null_type.rb
+- lib/stairwell/types/string_type.rb
+- lib/stairwell/types/table_name_type.rb
 - lib/stairwell/version.rb
 - stairwell.gemspec
+- test.db
 homepage: https://github.com/tobyond/stairwell
 licenses:
 - MIT
@@ -54,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: stairwell for sql

data/lib/stairwell/core_extensions/core.rb

@@ -1,77 +0,0 @@
-class String
-  def squish!
-    gsub!(/[[:space:]]+/, " ")
-    strip!
-    self
-  end
-
-  def underscore
-    self.gsub(/::/, '/').
-      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-      gsub(/([a-z\d])([A-Z])/,'\1_\2').
-      tr("-", "_").
-      downcase
-  end
-
-  def sql_quote
-    "'#{self.gsub('\\', '\&\&').gsub("'", "''")}'"
-  end
-end
-
-class TrueClass
-  def sql_quote
-    "TRUE"
-  end
-end
-
-class FalseClass
-  def sql_quote
-    "FALSE"
-  end
-end
-
-class NilClass
-  def sql_quote
-    "IS NULL"
-  end
-end
-
-class Integer
-  def sql_quote
-    self
-  end
-end
-
-class Float
-  def sql_quote
-    self
-  end
-end
-
-class Array
-  def sql_quote
-    map(&:sql_quote).join(", ")
-  end
-end
-
-class Date
-  def self.parsable?(string)
-    begin
-      parse(string)
-      true
-    rescue ArgumentError
-      false
-    end
-  end
-end
-
-class DateTime
-  def self.parsable?(string)
-    begin
-      parse(string)
-      true
-    rescue ArgumentError
-      false
-    end
-  end
-end

data/lib/stairwell/core_extensions/types.rb

@@ -1,7 +0,0 @@
-module Boolean; end
-class TrueClass; include Boolean; end
-class FalseClass; include Boolean; end
-
-module SqlDate; end
-module SqlDateTime; end
-class String; include SqlDate; include SqlDateTime; end

data/lib/stairwell/type_validator.rb

@@ -1,25 +0,0 @@
-require "stairwell/core_extensions/core"
-require "stairwell/core_extensions/types"
-
-module Stairwell
-  class TypeValidator
-
-    class << self
-      TYPES = [
-        String,
-        Boolean,
-        Integer,
-        Float,
-        SqlDate,
-        SqlDateTime
-      ].freeze
-
-      TYPES.each do |type|
-        define_method(type.to_s.underscore.to_sym) do |arg|
-          return arg.is_a?(type) unless arg.is_a?(Array)
-          arg.all? { |element| element.is_a?(type) }
-        end
-      end
-    end
-  end
-end