kweerie 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b17930ae6088ef2d4fb7f4e20c36479bc8bcc97ae2ed3bd2bfd8d7baed4266b0
-  data.tar.gz: 7100335df50ba93ee28fb811d530cdf2231db2efaed2f149073144a15e389c41
+  metadata.gz: b47a2f9363e6fb03e19af88b8d34ab9d727e45e2ed7f05e95d41d23835f93693
+  data.tar.gz: cb868fa5858008ce6e2ec14188e81c41fb0ad554e85e491b71ebe625d357257e
 SHA512:
-  metadata.gz: 52f8165082fb447dcc9219c968256f867ead4dba70722920928acedae4e150d9608ee3ffd5dd803131d556031f588b3bba7f8f17171d56cca4487ae427dfb6b4
-  data.tar.gz: bdfdf6ecf8cf3495ef4ed157ea3e149d23ff16f5a7ff98a73329dd3f3a1516d80a8a57ddbea1b23dd26df43805a27164a28ba4836550ed9951f7392f07118eb9
+  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,15 +65,105 @@ 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)
 ```
 
+## Querying
+
+Kweerie provides two main ways to execute queries based on whether they have parameters:
+
+### Parameterized Queries
+
+When your query needs parameters, use the `.with` method:
+
+```ruby
+class UsersByDepartment < Kweerie::Base
+  bind :department, as: '$1'
+  bind :active, as: '$2'
+end
+
+# app/queries/users_by_department.sql
+SELECT *
+FROM users
+WHERE department = $1
+  AND active = $2;
+
+# Using the query
+users = UsersByDepartment.with(
+  department: 'Engineering',
+  active: true
+)
+```
+
+### Parameter-free Queries
+
+For queries that don't require any parameters, you can use the more semantically appropriate `.all` method:
+
+```ruby
+class AllUsers < Kweerie::Base
+end
+
+# app/queries/all_users.sql
+SELECT *
+FROM users
+WHERE active = true
+ORDER BY created_at DESC;
+
+# Using the query
+users = AllUsers.all
+```
+
+The `.all` method provides a cleaner interface when you're not binding any parameters. It will raise an error if you try to use it on a query class that has parameter bindings:
+
+```ruby
+# This will raise an ArgumentError
+UsersByDepartment.all  
+# => ArgumentError: Cannot use .all on queries with bindings. Use .with instead.
+```
+
+### Choosing Between .all and .with
+
+- Use `.all` when your SQL query is completely static with no parameters
+- Use `.with` when you need to pass parameters to your query
+- Even for parameterized queries, you can use `.with` without arguments if all parameters are optional
+
+```ruby
+# A query with no parameters
+class RecentUsers < Kweerie::Base
+end
+RecentUsers.all  # ✓ Clean and semantic
+RecentUsers.with # ✓ Works but less semantic
+
+# A query with parameters
+class UsersByStatus < Kweerie::Base
+  bind :status, as: '$1'
+end
+UsersByStatus.all                    # ✗ Raises ArgumentError
+UsersByStatus.with(status: 'active') # ✓ Correct usage
+```
+
+Both methods work with `Kweerie::Base` and `Kweerie::BaseObjects`, returning arrays of hashes or objects respectively:
+
+```ruby
+# Returns array of hashes
+class AllUsers < Kweerie::Base
+end
+users = AllUsers.all
+# => [{"id" => 1, "name" => "Eclipsoid"}, ...]
+
+# Returns array of objects
+class AllUsers < Kweerie::BaseObjects
+end
+users = AllUsers.all
+# => [#<AllUsers id=1 name="Eclipsoid">, ...]
+```
+
 ### Automatic Type Casting
 
 BaseObjects automatically casts common PostgreSQL types to their Ruby equivalents:
@@ -91,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
@@ -130,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
@@ -147,7 +237,7 @@ user.changes                   # => Hash of changes with [old, new] values
 user.original_attributes       # => Original attributes from DB
 ```
 
-## PostgreSQL Array Support
+### PostgreSQL Array Support
 
 BaseObjects handles PostgreSQL arrays by converting them to Ruby arrays with proper type casting:
 
@@ -160,14 +250,39 @@ 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]
 ```
 
-## Performance Considerations
+### 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:
 
@@ -179,7 +294,7 @@ BaseObjects creates a unique class for each query result set, with the following
 
 For queries where you don't need the object interface, use `Kweerie::Base` instead for slightly better performance.
 
-### Rails Generator
+## Rails Generator
 
 If you're using Rails, you can use the generator to create new query files:
 
@@ -193,7 +308,7 @@ rails generate kweerie UserSearch email name
 
 This will create both the Ruby class and SQL file with the appropriate structure.
 
-### Configuration
+## Configuration
 
 By default, Kweerie uses ActiveRecord's connection if available. You can configure this and other options:
 
@@ -222,19 +337,11 @@ 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
+### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
 
-## Contributing
+### Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
@@ -242,12 +349,15 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
-## License
+### License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## 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)
@@ -45,6 +183,12 @@ module Kweerie
         result.to_a
       end
 
+      def all
+        raise ArgumentError, "Cannot use .all on queries with bindings. Use .with instead." if bindings.any?
+
+        with
+      end
+
       private
 
       def validate_params!(params)

data/lib/kweerie/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kweerie
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  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