kweerie 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b17930ae6088ef2d4fb7f4e20c36479bc8bcc97ae2ed3bd2bfd8d7baed4266b0
-  data.tar.gz: 7100335df50ba93ee28fb811d530cdf2231db2efaed2f149073144a15e389c41
+  metadata.gz: d8c4f949ad0ee144a37015f2444ad19721390ee94a59b1fc118599409b6b0f0a
+  data.tar.gz: a8b741b11e8dd572f6fccba9f06becbb75b06f0444e879f43b21f70d164d2ba7
 SHA512:
-  metadata.gz: 52f8165082fb447dcc9219c968256f867ead4dba70722920928acedae4e150d9608ee3ffd5dd803131d556031f588b3bba7f8f17171d56cca4487ae427dfb6b4
-  data.tar.gz: bdfdf6ecf8cf3495ef4ed157ea3e149d23ff16f5a7ff98a73329dd3f3a1516d80a8a57ddbea1b23dd26df43805a27164a28ba4836550ed9951f7392f07118eb9
+  metadata.gz: 368206d1376231a56d197911245878f8efdf8eb33f86f47135c079f2d3c28b2ac5a70786b7bafaa694b980f6f192ea6ac2d43ffcdb41f77bbd24aee295c7b9c4
+  data.tar.gz: 82c8cb0e9a1171f3a0e90b0db23ebc5f35e2b82401f4db2066b3903db383b8e08f619ab25edefbc0bea4ebab93fde9072d86895bfa864a1f793c4370f5f02f03

data/README.md

@@ -74,6 +74,96 @@ user.name         # => "Claude"
 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" => "Claude"}, ...]
+
+# Returns array of objects
+class AllUsers < Kweerie::BaseObjects
+end
+users = AllUsers.all
+# => [#<AllUsers id=1 name="Claude">, ...]
+```
+
 ### Automatic Type Casting
 
 BaseObjects automatically casts common PostgreSQL types to their Ruby equivalents:
@@ -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:
 
@@ -167,7 +257,7 @@ user.tags                 # => ["ruby", "rails"]
 user.scores              # => [98.5, 87.2, 92.0]
 ```
 
-## Performance Considerations
+### Performance Considerations
 
 BaseObjects creates a unique class for each query result set, with the following optimizations:
 
@@ -179,7 +269,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 +283,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,7 +312,7 @@ end
 - ✅ Configurable connection handling
 - ✅ Parameter validation
 
-## Why Kweerie?
+### 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
@@ -230,11 +320,11 @@ end
 - **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,7 +332,7 @@ 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).
 

data/lib/kweerie/base.rb

@@ -45,6 +45,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.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kweerie
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Toby