kweerie 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c4f949ad0ee144a37015f2444ad19721390ee94a59b1fc118599409b6b0f0a
-  data.tar.gz: a8b741b11e8dd572f6fccba9f06becbb75b06f0444e879f43b21f70d164d2ba7
+  metadata.gz: b47a2f9363e6fb03e19af88b8d34ab9d727e45e2ed7f05e95d41d23835f93693
+  data.tar.gz: cb868fa5858008ce6e2ec14188e81c41fb0ad554e85e491b71ebe625d357257e
 SHA512:
-  metadata.gz: 368206d1376231a56d197911245878f8efdf8eb33f86f47135c079f2d3c28b2ac5a70786b7bafaa694b980f6f192ea6ac2d43ffcdb41f77bbd24aee295c7b9c4
-  data.tar.gz: 82c8cb0e9a1171f3a0e90b0db23ebc5f35e2b82401f4db2066b3903db383b8e08f619ab25edefbc0bea4ebab93fde9072d86895bfa864a1f793c4370f5f02f03
+  metadata.gz: 3f9927adf42ec5fed6e65ea6c5a83a3166ea10ccadbe9d802a2d2bb6cc02647365df44865052566a6b255fa8dbb91be74f406a0fc61993982589222b2724724a
+  data.tar.gz: '08acf2f917e887a25e0c22aebd493aa861c1bc0fa827e80983ee577f352d1048efabb2285b152cb1d141ccf8846e34071828f4b77960d0b1b51909fb279fcd85'

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.3
 
 Style/StringLiterals:
   Enabled: true
@@ -11,3 +11,33 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength: 
+  Enabled: false
+
+Metrics/AbcSize: 
+  Enabled: false
+
+Style/MultilineBlockChain: 
+  Enabled: false
+
+Metrics/PerceivedComplexity: 
+  Enabled: false
+
+Metrics/AbcSize: 
+  Enabled: false
+
+Gemspec/RequiredRubyVersion: 
+  Enabled: false
+
+Metrics/BlockLength: 
+  Enabled: false

data/README.md

@@ -47,10 +47,10 @@ Execute your query:
 
 ```ruby
 results = UserSearch.with(
-  name: 'John%',
+  name: 'Eclipsoid%',
   email: '%@example.com'
 )
-# => [{"id"=>9981, "name"=>"John Doe", "email"=>"johndoe@example.com"}]
+# => [{"id"=>109981, "name"=>"Eclipsoid Doe", "email"=>"eclipsoiddoe@example.com"}]
 ```
 
 ### Object Mapping
@@ -65,12 +65,12 @@ end
 
 # Returns array of objects instead of hashes
 users = UserSearch.with(
-  name: 'Claude',
+  name: 'Eclipsoid',
   created_at: '2024-01-01'
 )
 
 user = users.first
-user.name         # => "Claude"
+user.name         # => "Eclipsoid"
 user.created_at   # => 2024-01-01 00:00:00 +0000 (Time object)
 ```
 
@@ -155,13 +155,13 @@ Both methods work with `Kweerie::Base` and `Kweerie::BaseObjects`, returning arr
 class AllUsers < Kweerie::Base
 end
 users = AllUsers.all
-# => [{"id" => 1, "name" => "Claude"}, ...]
+# => [{"id" => 1, "name" => "Eclipsoid"}, ...]
 
 # Returns array of objects
 class AllUsers < Kweerie::BaseObjects
 end
 users = AllUsers.all
-# => [#<AllUsers id=1 name="Claude">, ...]
+# => [#<AllUsers id=1 name="Eclipsoid">, ...]
 ```
 
 ### Automatic Type Casting
@@ -181,7 +181,7 @@ SELECT
 FROM users;
 
 # In your Ruby code
-user = UserSearch.with(name: 'Claude').first
+user = UserSearch.with(name: 'Eclipsoid').first
 
 user.created_at   # => Time object
 user.age          # => Integer
@@ -220,7 +220,7 @@ BaseObjects provide several useful methods:
 
 ```ruby
 # Hash-like access
-user[:name]                    # => "Claude"
+user[:name]                    # => "Eclipsoid"
 user.fetch(:email, 'N/A')      # => Returns 'N/A' if email is nil
 
 # Serialization
@@ -250,13 +250,38 @@ create_table :users do |t|
 end
 
 # In your query
-user = UserSearch.with(name: 'Claude').first
+user = UserSearch.with(name: 'Eclipsoid').first
 
 user.preferred_ordering  # => [1, 3, 2]
 user.tags                 # => ["ruby", "rails"]
 user.scores              # => [98.5, 87.2, 92.0]
 ```
 
+### SQL File Location
+
+By default, Kweerie looks for SQL files adjacent to their Ruby query classes. You can customize this behavior:
+
+```ruby
+# Default behavior - looks for user_search.sql next to this file
+class UserSearch < Kweerie::Base
+end
+
+# Specify absolute path from Rails root
+class UserSearch < Kweerie::Base
+  sql_file_location root: 'db/queries/complex_user_search.sql'
+end
+
+# Specify path relative to the Ruby file
+class UserSearch < Kweerie::Base
+  sql_file_location relative: '../sql/user_search.sql'
+end
+
+# Explicitly use default behavior
+class UserSearch < Kweerie::Base
+  sql_file_location :default
+end
+```
+
 ### Performance Considerations
 
 BaseObjects creates a unique class for each query result set, with the following optimizations:
@@ -312,14 +337,6 @@ end
 - ✅ Configurable connection handling
 - ✅ Parameter validation
 
-### Why Kweerie?
-
-- **SQL Views Overkill**: When a database view is too heavy-handed but you still want to keep SQL separate from Ruby
-- **Version Control**: Keep your SQL under version control alongside your Ruby code
-- **Parameter Safety**: Built-in parameter binding prevents SQL injection
-- **Simple Interface**: Clean, simple API for executing parameterized queries
-- **Rails Integration**: Works seamlessly with Rails and ActiveRecord
-
 ### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
@@ -338,6 +355,9 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## FAQ
 
+**Q: Why does Kweerie exist?**  
+A: PostgreSQL DB views are powerful and (honestly) preferred for what kweerie offers, but they need migrations to change, which isn't always practical when you just need a query. Kweerie provides that flexibility. Plus, SQL is more readable in a single file than when nested in Ruby code. SQL is powerful and doesn’t always need to be hidden behind abstractions.
+
 **Q: Why PostgreSQL only?**  
 A: Kweerie uses PostgreSQL-specific features for parameter binding and result handling. Supporting other databases would require different parameter binding syntax and result handling.
 

data/lib/kweerie/base.rb

@@ -5,37 +5,175 @@ module Kweerie
     class << self
       def inherited(subclass)
         subclass.instance_variable_set(:@bindings, {})
+        subclass.instance_variable_set(:@class_location, caller_locations(1, 1)[0].path)
         super
       end
 
+      # == Parameter Binding
+      #
+      # Binds a parameter to a SQL placeholder. Parameters are required by default and
+      # must be provided when executing the query.
+      #
+      # === Options
+      #
+      # * <tt>:as</tt> - The SQL placeholder (e.g., '$1', '$2') that this parameter maps to
+      #
+      # === Examples
+      #
+      #   class UserSearch < Kweerie::Base
+      #     # Single parameter
+      #     bind :name, as: '$1'
+      #
+      #     # Multiple parameters
+      #     bind :email, as: '$2'
+      #     bind :status, as: '$3'
+      #   end
+      #
+      #   # Using the query
+      #   UserSearch.with(
+      #     name: 'Eclipsoid',
+      #     email: '%@example.com',
+      #     status: 'active'
+      #   )
+      #
+      # === Notes
+      #
+      # * Parameters must be provided in the order they appear in the SQL
+      # * All bound parameters are required
+      # * Use PostgreSQL's COALESCE for optional parameters
+      #
       def bind(param_name, as:)
         @bindings[param_name] = as
       end
 
       attr_reader :bindings
 
-      def sql_path
-        @sql_path ||= begin
-          subclass_file = "#{name.underscore}.sql"
-          possible_paths = Kweerie.configuration.sql_paths.call
-
-          sql_file = possible_paths.map do |path|
-            File.join(root_path, path, subclass_file)
-          end.find { |f| File.exist?(f) }
-
-          unless sql_file
-            raise SQLFileNotFound,
-                  "Could not find SQL file for #{name} in paths: #{possible_paths.join(", ")}"
+      # == SQL File Location
+      #
+      # Specifies the location of the SQL file for this query. By default, Kweerie looks for
+      # an SQL file with the same name as the query class in the same directory.
+      #
+      # === Options
+      #
+      # * <tt>:default</tt> - Use default file naming (class_name.sql in same directory)
+      # * <tt>root: 'path'</tt> - Path relative to Rails.root
+      # * <tt>relative: 'path'</tt> - Path relative to the query class file
+      #
+      # === Examples
+      #
+      #   class UserSearch < Kweerie::Base
+      #     # Default behavior - looks for user_search.sql in same directory
+      #     sql_file_location :default
+      #
+      #     # Use a specific file from Rails root
+      #     sql_file_location root: 'db/queries/complex_user_search.sql'
+      #
+      #     # Use a file relative to this class
+      #     sql_file_location relative: '../sql/user_search.sql'
+      #   end
+      #
+      # === Notes
+      #
+      # * Root paths require Rails to be defined
+      # * Paths should use forward slashes even on Windows
+      # * File extensions should be included in the path
+      # * Relative paths are relative to the query class file location
+      #
+      def sql_file_location(location = :default)
+        @sql_file_location =
+          case location
+          when :default
+            nil
+          when Hash
+            if location.key?(:root)
+              { root: location[:root].to_s }
+            elsif location.key?(:relative)
+              { relative: location[:relative].to_s }
+            else
+              raise ArgumentError,
+                    "Invalid sql_file_location option. Use :default, root: 'path', or relative: 'path'"
+            end
+          else
+            raise ArgumentError,
+                  "Invalid sql_file_location option. Use :default, root: 'path', or relative: 'path'"
           end
+      end
 
-          sql_file
-        end
+      def sql_path
+        @sql_path ||=
+          if @sql_file_location&.key?(:root)
+            raise ConfigurationError, "Root path requires Rails to be defined" unless defined?(Rails)
+
+            path = Rails.root.join(@sql_file_location[:root]).to_s
+            raise SQLFileNotFound, "Could not find SQL file at #{path}" unless File.exist?(path)
+
+            path
+
+          elsif @sql_file_location&.key?(:relative)
+            configured_paths = Kweerie.configuration.sql_paths.call
+            sql_file = configured_paths.map do |path|
+              full_path = File.join(path, @sql_file_location[:relative])
+              full_path if File.exist?(full_path)
+            end.compact.first
+            unless sql_file
+              raise SQLFileNotFound,
+                    "Could not find SQL file #{@sql_file_location[:relative]}"
+            end
+
+            sql_file
+          else # default behavior
+            sql_filename = "#{name.underscore}.sql"
+            configured_paths = Kweerie.configuration.sql_paths.call
+
+            sql_file = configured_paths.map do |path|
+              full_path = File.join(path, sql_filename)
+              full_path if File.exist?(full_path)
+            end.compact.first
+
+            raise SQLFileNotFound, "SQL file not found for #{name}" unless sql_file
+
+            sql_file
+          end
       end
 
       def sql_content
         @sql_content ||= File.read(sql_path)
       end
 
+      # == Execute Query with Parameters
+      #
+      # Executes the SQL query with the provided parameters. All bound parameters must be provided
+      # unless using .all for parameter-free queries.
+      #
+      # === Parameters
+      #
+      # * <tt>params</tt> - Hash of parameter names and values that match the bound parameters
+      #
+      # === Returns
+      #
+      # Array of hashes representing the query results. When using Kweerie::BaseObjects,
+      # returns array of typed objects instead.
+      #
+      # === Examples
+      #
+      #   # With parameters
+      #   UserSearch.with(
+      #     name: 'Eclipsoid',
+      #     email: '%@example.com'
+      #   )
+      #   # => [{"id"=>1, "name"=>"Eclipsoid", "email"=>"eclipsoid@example.com"}]
+      #
+      #   # With type casting (BaseObjects)
+      #   UserSearch.with(created_after: '2024-01-01')
+      #   # => [#<UserSearch id=1 created_at=2024-01-01 00:00:00 +0000>]
+      #
+      # === Notes
+      #
+      # * Raises ArgumentError if required parameters are missing
+      # * Raises ArgumentError if extra parameters are provided
+      # * Returns empty array if no results found
+      # * Parameters are bound safely using pg-ruby's parameter binding
+      #
       def with(params = {})
         validate_params!(params)
         param_values = order_params(params)

data/lib/kweerie/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kweerie
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kweerie
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Toby
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-07 00:00:00.000000000 Z
+date: 2024-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest