quo 1.0.0.beta1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f72639830288de3776524bb1003fc88aeeee4d1adf83abeb44dd42e48caa0bfb
-  data.tar.gz: f72435e5e5ef3832bcf993362f0b56252bc17edaaedb197455308195c71f6516
+  metadata.gz: f3e56abbd1094d91702a10b327e82b05a28d7fc44e491316c438059de2c0c229
+  data.tar.gz: 7ebdcfb6b774c274ae30e7eaff556dae898be1f2a8478c5ee1544cfde41dcd25
 SHA512:
-  metadata.gz: 64401d860bd1682d6b3d46d06f76eb644c9b3a3b1ad4d945b6d52b778d5deafe386f4588f9a7f381a8c484790711a3e0727f3d84f45469e8d53a787410741741
-  data.tar.gz: 5c148a23cc7ce4006fcac7c5cb9f6c118cbf08b35ea7b623743f48b3d36ae457d5902932a90669c5763e98db5df42b7ec31a470453752473821bc3e65ef7815d
+  metadata.gz: ff1b0856ab186d6adfab0274aac9b94a61a0ece421716726b15c762a097f46d2566bcbe53fb04c589bb6d9eb708d91b65303b5cee419c0ae0cdeab193483089f
+  data.tar.gz: 4befea0da9dcbdb6a71f4e447b871e9f0424738f50908bef479f3fd89a2401a5fc861a7ddf124c36ffbfdec5e871b03a0fd75ffcf2941e861465e0ede1ef0f6e

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022-2025 Stephen Ierodiaconou
+Copyright (c) 2022-2024 Stephen Ierodiaconou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,324 +1,335 @@
-# Quo: Query Objects for ActiveRecord
+# 'Quo' query objects for ActiveRecord
 
-Quo helps you organize database queries into reusable, composable, and testable objects.
+> Note: these docs are for pre-V1 and need updating. I'm working on it!
 
-## Core Features
+Quo query objects can help you abstract ActiveRecord DB queries into reusable and composable objects with a chainable
+interface.
 
-* Wrap around an underlying ActiveRecord relation or array-like collection
-* Supports pagination for ActiveRecord-based queries and collections that respond to `[]`
-* Support composition with the `+` (`compose`) method to merge multiple query objects
-* Allow transforming results with the `transform` method
-* Offer utility methods that operate on the underlying collection (eg `exists?`)
-* Act as a callable with chainable methods like ActiveRecord
-* Provide a clear separation between query definition and execution with enumerable `Results` objects
-* Type-safe properties with optional default values
+The query object can also abstract over any array-like collection meaning that it is possible for example to cache the
+data from a query and reuse it.
 
-## Core Concepts
+The core implementation provides the following functionality:
 
-Query objects encapsulate query logic in dedicated classes, making complex queries more manageable and reusable.
+* wrap around an underlying ActiveRecord or array-like collection
+* optionally provides paging behaviour to ActiveRecord based queries
+* provides a number of utility methods that operate on the underlying collection (eg `exists?`)
+* provides a `+` (`compose`) method which merges two query object instances (see section below for details!)
+* can specify a mapping or transform method to `transform` to perform on results
+* acts as a callable which executes the underlying query with `.first`
+* can return an `Enumerable` of results
 
-Quo provides two main components:
-1. **Query Objects** - Define and configure queries
-2. **Results Objects** - Execute queries and provide access to the results
 
-## Creating Query Objects
+`Quo::Query` subclasses are the builders, they retain configuration of the queries, and prepare the underlying query or data collections. Query objects then return `Quo::Results` which take the built queries and then take action on them, such as to fetch data or to count records.
 
-### Relation-Backed Queries
+## Creating a Quo query object
 
-For queries based on ActiveRecord relations:
+The query object must inherit from `Quo::Query` and provide an implementation for the `query` method.
 
-```ruby
-class RecentActiveUsers < Quo::RelationBackedQuery
-  # Define typed properties
-  prop :days_ago, Integer, default: -> { 30 }
-  
-  def query
-    User
-      .where(active: true)
-      .where("created_at > ?", days_ago.days.ago)
-  end
-end
+The `query` method must return either:
 
-# Create and use the query
-query = RecentActiveUsers.new(days_ago: 7)
-results = query.results
+- an `ActiveRecord::Relation`
+- an Enumerable (like a 'collection backed' query) 
+- or another `Quo::Query` instance.
 
-# Work with results
-results.each { |user| puts user.email }
-puts "Found #{results.count} users"
-```
+Remember that the query object should be useful in composition with other query objects. Thus it should not directly 
+specify things that are not directly needed to fetch the right data for the given context. 
 
-### Collection-Backed Queries
+For example the ordering of the results is mostly something that is specified when the query object is used, not as
+part of the query itself (as then it would always enforce the ordering on other queries it was composed with).
 
-For queries based on any Enumerable collection:
+## Passing options to queries
 
-```ruby
-class CachedUsers < Quo::CollectionBackedQuery
-  prop :role, String
-  
-  def collection
-    @cached_users ||= Rails.cache.fetch("all_users", expires_in: 1.hour) do
-      User.all.to_a
-    end.select { |user| user.role == role }
-  end
-end
+If any parameters are need in `query`, these are provided when instantiating the query object using the `options` hash.
 
-# Use the query
-admins = CachedUsers.new(role: "admin").results
-```
+It is also possible to pass special configuration options to the constructor options hash. 
 
-## Quick Queries with Wrap
+Specifically when the underlying collection is a ActiveRecord relation then:
 
-Create query objects without subclassing:
+* `order`: the `order` condition for the relation (eg `:desc`)
+* `includes`: the `includes` condition for the relation (eg `account: {user: :profile}`)
+* `group`: the `group` condition for the relation
+* `page`: the current page number to fetch
+* `page_size`: the number of elements to fetch in the page
 
-```ruby
-# Relation-backed
-users_query = Quo::RelationBackedQuery.wrap(User.active).new
-active_users = users_query.results
+Note that the above options have no bearing on the query if it is backed by an array-like collection and that some
+options can be configured using the following methods.
 
-# Collection-backed
-items_query = Quo::CollectionBackedQuery.wrap([1, 2, 3]).new
-items = items_query.results
-```
+## Configuring queries
 
-## Type-Safe Properties
+Note that it is possible to configure a query using chainable methods similar to ActiveRecord:
 
-Quo uses the `Literal` gem for typed properties:
+* limit
+* order
+* group
+* includes
+* left_outer_joins
+* preload
+* joins
 
-```ruby
-class UsersByState < Quo::RelationBackedQuery
-  prop :state, String
-  prop :minimum_age, Integer, default: -> { 18 }
-  prop :active_only, Boolean, default: -> { true }
+Note that these return a new Quo Query and do not mutate the original instance.
 
-  def query
-    scope = User.where(state: state)
-    scope = scope.where("age >= ?", minimum_age) if minimum_age.present?
-    scope = scope.where(active: true) if active_only
-    scope
-  end
-end
+## Composition of queries (merging or combining them)
 
-query = UsersByState.new(state: "California", minimum_age: 21)
-```
+Quo query objects are composeability. In `ActiveRecord::Relation` this is acheived using `merge`
+and so under the hood `Quo::Query` uses that when composing relations. However since Queries can also abstract over
+array-like collections (ie enumerable and define a `+` method) compose also handles concating them together.
 
-## Fluent API for Building Queries
+Composing can be done with either 
 
-```ruby
-query = UsersByState.new(state: "California")
-  .order(created_at: :desc)
-  .includes(:profile)
-  .limit(10)
-  .where(verified: true)
+- `Quo::Query.compose(left, right)` 
+- or `left.compose(right)` 
+- or more simply with `left + right`
 
-users = query.results
-```
+The composition methods also accept an optional parameter to pass to ActiveRecord relation merges for the `joins`. 
+This allows you to compose together Query objects which return relations which are of different models but still merge 
+them correctly with the appropriate joins. Note with the alias you cant neatly specify optional parameters for joins
+on relations.
 
-Available methods include:
-* `where`
-* `order`
-* `limit`
-* `includes`
-* `preload`
-* `left_outer_joins`
-* `joins`
-* `group`
+Note that the compose process creates a new query object instance, which is a instance of a `Quo::ComposedQuery`.
 
-Each method returns a new query instance without modifying the original.
+Consider the following cases:
 
-## Pagination
+1. compose two query objects which return `ActiveRecord::Relation`s
+2. compose two query objects, one of which returns a `ActiveRecord::Relation`, and the other an array-like
+3. compose two query objects which return array-likes
 
-```ruby
-query = UsersByState.new(
-  state: "California",
-  page: 2,
-  page_size: 20
-)
-
-# Get paginated results
-users = query.results
-
-# Navigation
-next_page = query.next_page_query
-prev_page = query.previous_page_query
-```
+In case (1) the compose process uses `ActiveRecords::Relation`'s `merge` method to create another query object
+wrapped around a new 'composed' `ActiveRecords::Relation`.
+
+In case (2) the query object with a `ActiveRecords::Relation` inside is executed, and the result is then concatenated
+to the array-like with `+`
+
+In case (3) the values contained are concatenated with `+`
+
+*Note that*
 
-## Composing Queries
+with `left.compose(right)`, `left` must obviously be an instance of a `Quo::Query`, and `right` can be either a
+query object or and `ActiveRecord::Relation`. However `Quo::Query.compose(left, right)` also accepts
+`ActiveRecord::Relation`s for left.
 
-Combine multiple queries:
+### Examples
 
 ```ruby
-class ActiveUsers < Quo::RelationBackedQuery
+class CompanyToBeApproved < Quo::RelationBackedQuery
   def query
-    User.where(active: true)
+    Registration
+      .left_joins(:approval)
+      .where(approvals: {completed_at: nil})
   end
 end
 
-class PremiumUsers < Quo::RelationBackedQuery
+class CompanyInUsState < Quo::RelationBackedQuery
   def query
-    User.where(subscription_tier: "premium")
+    Registration
+      .joins(company: :address)
+      .where(addresses: {state: options[:state]})
   end
 end
 
-# Compose queries
-active_premium = ActiveUsers.new + PremiumUsers.new
-users = active_premium.results
+query1 = CompanyToBeApproved.new
+query2 = CompanyInUsState.new(state: "California")
+
+# Compose
+composed = query1 + query2 # or Quo::Query.compose(query1, query2) or query1.compose(query2)
+composed.first
+```
+
+This effectively executes:
+
+```ruby
+Registration
+  .left_joins(:approval)
+  .joins(company: :address)
+  .where(approvals: {completed_at: nil})
+  .where(addresses: {state: options[:state]})
 ```
 
-You can compose queries using:
-* `Quo::Query.compose(left, right)`
-* `left.compose(right)`
-* `left + right`
+It is also possible to compose with an `ActiveRecord::Relation`. This can be useful in a Query object itself to help
+build up the `query` relation. For example:
 
-### Composing with Joins
+```ruby
+class RegistrationToBeApproved < Quo::RelationBackedQuery
+  def query
+    done = Registration.where(step: "complete")
+    approved = CompanyToBeApproved.new
+    # Here we use `.compose` utility method to wrap our Relation in a Query and 
+    # then compose with the other Query
+    Quo::Query.compose(done, approved)
+  end
+end
+
+# A Relation can be composed directly to a Quo::Query
+query = RegistrationToBeApproved.new + Registration.where(blocked: false)
+```
+
+Also you can use joins:
 
 ```ruby
-class ProductsQuery < Quo::RelationBackedQuery
+class TagByName < Quo::RelationBackedQuery
   def query
-    Product.where(active: true)
+    Tag.where(name: options[:name])
   end
 end
 
-class CategoriesQuery < Quo::RelationBackedQuery
+class CategoryByName < Quo::RelationBackedQuery
   def query
-    Category.where(featured: true)
+    Category.where(name: options[:name])
   end
 end
 
-# Compose with a join
-products = ProductsQuery.new.compose(CategoriesQuery.new, joins: :category)
+tags = TagByName.new(name: "Intel")
+for_category = CategoryByName.new(name: "CPUs")
+tags.compose(for_category, :category) # perform join on tag association `category`
 
-# Equivalent to:
-# Product.joins(:category)
-#        .where(products: { active: true })
-#        .where(categories: { featured: true })
+# equivalent to Tag.joins(:category).where(name: "Intel").where(categories: {name: "CPUs"})
 ```
 
-## Transforming Results
+Collection backed queries can also be composed (see below sections for more details).
 
-```ruby
-query = UsersByState.new(state: "California")
-  .transform { |user| UserPresenter.new(user) }
+### Quo::ComposedQuery
 
-# Results are automatically transformed
-presenters = query.results.to_a # Array of UserPresenter objects
+The new instance of `Quo::ComposedQuery` from a compose process, retains references to the original entities that were
+composed. These are then used to create a more useful output from `to_s`, so that it is easier to understand what the
+merged query is actually made up of:
+
+```ruby
+q = FooQuery.new + BarQuery.new
+puts q
+# > "Quo::ComposedQuery[FooQuery, BarQuery]"
 ```
 
-## Custom Association Preloading
+## Query Objects & Pagination
 
-```ruby
-class UsersWithOrders < Quo::RelationBackedQuery
-  include Quo::Preloadable
-  
-  def query
-    User.all
-  end
+Specify extra options to enable pagination:
 
-  def preload_associations(collection)
-    # Custom preloading logic
-    ActiveRecord::Associations::Preloader.new(
-      records: collection,
-      associations: [:profile, :orders]
-    ).call
-    
-    collection
-  end
-end
-```
+* `page`: the current page number to fetch
+* `page_size`: the number of elements to fetch in the page
 
-## Testing Helpers
+### `Quo::CollectionBackedQuery` & `Quo::CollectionBackedQuery` objects
 
-### Minitest
+`Quo::CollectionBackedQuery` is a subclass of `Quo::Query` which can be used to create query objects which are backed 
+by a collection (ie an enumerable such as an Array). This is useful for encapsulating data that doesn't come from an 
+ActiveRecord query or queries that execute immediately. Subclass this and override `collection` to return the data you 
+want to encapsulate.
 
 ```ruby
-class UserQueryTest < ActiveSupport::TestCase
-  include Quo::Minitest::Helpers
-
-  test "filters users by state" do
-    users = [User.new(name: "Alice"), User.new(name: "Bob")]
-    
-    fake_query(UsersByState, results: users) do
-      result = UsersByState.new(state: "California").results.to_a
-      assert_equal users, result
-    end
+class MyCollectionBackedQuery < Quo::CollectionBackedQuery
+  def collection
+    [1, 2, 3]
   end
 end
+q = MyCollectionBackedQuery.new
+q.collection? # is it a collection under the hood? Yes it is!
+q.count # '3'
 ```
 
-### RSpec
+Sometimes it is useful to create similar Queries without needing to create a explicit subclass of your own. For this
+use `Quo::CollectionBackedQuery`:
 
 ```ruby
-RSpec.describe UsersByState do
-  include Quo::RSpec::Helpers
-
-  it "filters users by state" do
-    users = [User.new(name: "Alice"), User.new(name: "Bob")]
-    
-    fake_query(UsersByState, results: users) do
-      result = UsersByState.new(state: "California").results.to_a
-      expect(result).to eq(users)
-    end
-  end
-end
+q = Quo::CollectionBackedQuery.wrap([1, 2, 3])
+q.collection? # true
+q.count # '3'
 ```
 
-## Project Organization
+`Quo::CollectionBackedQuery` also uses `total_count` option value as the specified 'total count', useful when the data is
+actually just a page of the data and not the total count.
 
-Suggested directory structure:
+Example of an CollectionBackedQuery used to wrap a page of enumerable data:
 
+```ruby
+Quo::CollectionBackedQuery.wrap(my_data, total_count: 100, page: current_page)
 ```
-app/
-  queries/
-    application_query.rb
-    users/
-      active_users_query.rb
-      by_state_query.rb
-    products/
-      featured_products_query.rb
-```
 
-Base classes:
+If a loaded query is `compose`d with other Query objects then it will be seen as an array-like, and concatenated to whatever 
+results are returned from the other queries. An loaded or eager query will force all other queries to be eager loaded.
+
+### Composition
+
+Examples of composition of eager loaded queries
 
 ```ruby
-# app/queries/application_query.rb
-class ApplicationQuery < Quo::RelationBackedQuery
-  # Common functionality
+class CachedTags < Quo::RelationBackedQuery
+  def query
+    @tags ||= Tag.where(active: true).to_a
+  end
 end
 
-# app/queries/application_collection_query.rb
-class ApplicationCollectionQuery < Quo::CollectionBackedQuery
-  # Common functionality
-end
+composed = CachedTags.new(active: false) + [1, 2]
+composed.last
+# => 2
+composed.first
+# => #<Tag id: ...>
+
+Quo::CollectionBackedQuery.new([3, 4]).compose(Quo::CollectionBackedQuery.new([1, 2])).last
+# => 2
+Quo::Query.compose([1, 2], [3, 4]).last
+# => 4
 ```
 
-## Installation
+## Transforming results
+
+Sometimes you want to specify a block to execute on each result for any method that returns results, such as `first`,
+`last` and `each`.
 
-Add to your Gemfile:
+This can be specified using the `transform(&block)` instance method. For example:
 
 ```ruby
-gem "quo"
+TagsQuery.new(
+  active: [true, false],
+  page: 1,
+  page_size: 30,
+).transform { |tag| TagPresenter.new(tag) }
+ .first
+# => #<TagPresenter ...>
 ```
 
-Then execute:
+## Tests & stubbing
 
-```
-$ bundle install
-```
+Tests for Query objects themselves should exercise the actual underlying query. But in other code stubbing the query
+maybe desirable.
+
+The spec helper method `stub_query(query_class, {results: ..., with: ...})` can do this for you.
 
-## Configuration
+It stubs `.new` on the Query object and returns instances of `CollectionBackedQuery` instead with the given `results`. 
+The `with` option is passed to the Query object on initialisation and used when setting up the method stub on the 
+query class.
+
+For example:
 
 ```ruby
-# config/initializers/quo.rb
-Quo.default_page_size = 25
-Quo.max_page_size = 100
-Quo.relation_backed_query_base_class = "ApplicationQuery"
-Quo.collection_backed_query_base_class = "ApplicationCollectionQuery"
+stub_query(TagQuery, with: {name: "Something"}, results: [t1, t2])
+expect(TagQuery.new(name: "Something").first).to eql t1
 ```
 
-## Requirements
+*Note that*
+
+This returns an instance of CollectionBackedQuery, so will not work for cases were the actual type of the query instance is
+important or where you are doing a composition of queries backed by relations!
+
+If `compose` will be used then `Quo::Query.compose` needs to be stubbed. Something might be possible to make this
+nicer in future.
+
+## Other reading
+
+See:
+* [Includes vs preload vs eager_load](http://blog.scoutapp.com/articles/2017/01/24/activerecord-includes-vs-joins-vs-preload-vs-eager_load-when-and-where)
+* [Objects on Rails](http://objectsonrails.com/#sec-14)
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add quo
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install quo
+
+## Usage
 
-- Ruby 3.1+
-- Rails 7.0+
+TODO: Write usage instructions here
 
 ## Development
 
@@ -332,7 +343,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/steveg
 
 ## Inspired by `rectify`
 
-This implementation is inspired by the `Rectify` gem: https://github.com/andypike/rectify. Thanks to Andy Pike for the inspiration.
+Note this implementation is inspired by the `Rectify` gem; https://github.com/andypike/rectify. Thanks to Andy Pike for the inspiration.
 
 ## License
 

data/lib/quo/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Quo
-  VERSION = "1.0.0.beta1"
+  VERSION = "1.0.0.beta2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Stephen Ierodiaconou