active_model-relation 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2440274ca803bb2b2d571a3c7753730c66a86a5c8e5ccba873dbd19541e236a3
-  data.tar.gz: cab3d4c534dc3ada120d5660a029cffdd343d5869653f183434cf8fd3793da4b
+  metadata.gz: f0321b5b92acdc5dd26dae064782f042c36201d3f5f3a956497d0719e774aaee
+  data.tar.gz: f46553ea8591a73af03326c41c3ada13454f7ae9f508382bfeef1788bdbb178c
 SHA512:
-  metadata.gz: 12fe2562f8977cb3b2ac5db4f32dce3dd886d9c4d09996e2bf8fbb98e699ac54f6cad071625cc430c4de1615a3089fdf178bdc2d9c738d1f96b2fbe58a185ff7
-  data.tar.gz: 7cf7a6a159a8b5df87c5112644f2dc1118cf5e91b26bdf273c182e8ea4d84768291618ec4c0b47bd3b985217d26331551d9bec5a8f8e5a8c6bc59f69b00f3f7e
+  metadata.gz: ab15a40f58b9a295841a8740a9b4465c4a872db3d64a1d9e03b69ff6c018b5716af356cf65d64ed8b2e8d8037ee601f8eac4e5d9d33a911257a1f2db7e447152
+  data.tar.gz: 4f2fad7e6ed5b5f365aec277d438fb9d22c6bdce031adf3b42d22e36ee5c297eaee14d655f1c8c6fcdfda5746655838f51d4454261d146d654bc73e874e52db1

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-08-30
+## [0.2.0] - 2024-09-16
+
+- Rename `ActiveModel::Relation::ModelNotFound` to `ActiveModel::Relation::RecordNotFound`
+- Allow creating a `ActiveModel::Relation` without passing a collection
+- Don't require a `.records` class method on model classes
+- Allow passing a block to `ActiveModel::Relation#find`
+
+## [0.1.0] - 2024-09-09
 
 - Initial release

data/README.md

@@ -1,6 +1,6 @@
 # ActiveModel::Relation
 
-This library allows querying of collections of Ruby objects, with a similar interfaces to `ActiveRecord::Relation`.
+Query a collection of ActiveModel objects like an ActiveRecord::Relation.
 
 ## Installation
 
@@ -14,6 +14,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+### Initialization
+
 Create a new relation by passing the model class and a collection:
 
 ```ruby
@@ -25,16 +27,144 @@ relation = ActiveModel::Relation.new(Project, [
 ])
 ```
 
-Afterwards you can use it (almost) like an `ActiveRecord::Relation`.
+As an alternative, it's also possible to create a collection for a model without explicitly passing a collection.
+In this case, the library will attempt to call `Project.records` to get the default collection. If the method doesn't exist or returns `nil`, the collection will default to an empty array.
+
+```ruby
+class Project
+  def self.records
+    [
+      Project.new(id: 1, state: 'draft', priority: 1),
+      Project.new(id: 2, state: 'running', priority: 2),
+      Project.new(id: 3, state: 'completed', priority: 3),
+      Project.new(id: 4, state: 'completed', priority: 1)
+    ]
+  end
+end
+
+relation = ActiveModel::Relation.new(Project)
+```
+
+### Querying
+
+An `ActiveModel::Relation` can be queried almost exactly like an `ActiveRecord::Relation`.
+
+#### `#find`
+
+You can look up a record by it's primary key, using the `find` method. If no record is found, it will raise a `ActiveModel::Relation::RecordNotFound` error.
+
+```ruby
+project = relation.find(1)
+```
+
+By default, `ActiveModel::Relation` will assume `:id` as the primary key. You can customize this behavior by setting a `primary_key` on the model class.
+
+```ruby
+class Project
+  def self.primary_key = :identifier
+end
+```
+
+When passed a block, the `find` method will behave like `Enumerable#find`.
+
+```ruby
+project = relation.find { |p| p.id == 1 }
+```
+
+#### `#find_by`
+
+To look up a record based on a set of arbitary attributes, you can use `find_by`. It accepts the same arguments as `#where` and will return the first matching record.
+
+```ruby
+project = relation.find_by(state: 'draft')
+```
+
+#### `#where`
+
+To filter a relation, you can use `where` and pass a set of attributes and the expected values. This method will return a new `ActiveModel::Relation` that only returns the matching records, so it's possible to chain multiple calls. The filtering will only happen when actually accessing records.
 
 ```ruby
 relation.where(state: 'completed')
-relation.offset(3)
-relation.limit(2)
-relation.order(priority: :asc, state: :desc)
 ```
 
-You can also write named filter methods on the model class, after including `ActiveModel::Relation::Model`.
+The following two lines will return the same filtered results:
+
+```ruby
+relation.where(state: 'completed', priority: 1)
+relation.where(state: 'completed').where(priority: 1)
+```
+
+To allow for more advanced filtering, `#where` allows filtering using a block. This works similar to `Enumerable#select`, but will return a new `ActiveModel::Relation` instead of an already filtered array.
+
+```ruby
+relation.where { |p| p.state == 'completed' && p.priority == 1 }
+```
+
+#### `#where.not`
+
+Similar to `#where`, the `#where.not` chain allows you to filter a relation. It will also return a new `ActiveModel::Relation` with that returns only the matching records.
+
+```ruby
+relation.where.not(state: 'draft')
+```
+
+To allow for more advanced filtering, `#where.not` allows filtering using a block. This works similar to `Enumerable#reject`, but will return a new `ActiveModel::Relation` instead of an already filtered array.
+
+```ruby
+relation.where.not { |p| p.state == 'draft' && p.priority == 1 }
+```
+
+### Sorting
+
+It is possible to sort an `ActiveModel::Relation` by a given set of attribute names. Sorting will be applied after filtering, but before limits and offsets.
+
+#### `#order`
+
+To sort by a single attribute in ascending order, you can just pass the attribute name to the `order` method.
+
+```ruby
+relation.order(:priority)
+```
+
+To specify the sort direction, you can pass a hash with the attribute name as key and either `:asc`, or `:desc` as value.
+
+```ruby
+relation.order(priorty: :desc)
+```
+
+To order by multiple attributes, you can pass them in the order of specificity you want.
+
+```ruby
+relation.order(:state, :priority)
+```
+
+For multiple attributes, it's also possible to specify the direction.
+
+```ruby
+relation.order(state: :desc, priority: :asc)
+```
+
+### Limiting and offsets
+
+#### `#limit`
+
+To limit the amount of records returned in the collection, you can call `limit` on the relation. It will return a new `ActiveModel::Relation` that only returns the given limit of records, allowing you to chain multiple other calls. The limit will only be applied when actually accessing the records later on.
+
+```ruby
+relation.limit(10)
+```
+
+#### `#offset`
+
+To skip a certain number of records in the collection, you can use `offset` on the relation. It will return a new `ActiveModel::Relation` that skips the given number of records at the beginning. The offset will only be applied when actually accessing the records later on.
+
+```ruby
+relation.offset(20)
+```
+
+### Scopes
+
+After including `ActiveModel::Relation::Model`, the library also supports calling class methods defined on the model class as part of the relation.
 
 ```ruby
 class Project
@@ -52,6 +182,71 @@ class Project
 end
 ```
 
+Given the example above, you can now create relations like you're used to from `ActiveRecord::Relation`.
+
+```ruby
+projects = Project.all
+completed_projects = all_projects.completed
+important_projects = all_projects.where(priority: 1)
+```
+
+### Spawning
+
+It's possilbe to create new versions of a `ActiveModel::Relation` that only includes certain aspects of the `ActiveModel::Relation` it is based on. It's currently possible to customize the following aspects: `:where`, `:limit`, `:offset`.
+
+#### `#except`
+
+To create a new `ActiveModel::Relation` without certain aspects, you can use `except` and pass a list of aspects, you'd like to exclude from the newly created instance. The following example will create a new `ActiveModel::Relation` without any previously defined limit or offset.
+
+```ruby
+relation.except(:limit, :offset)
+```
+#### `#only`
+
+Similar to `except`, the `only` method will return a new instance of the `ActiveModel::Relation` it is based on but with only the passed list of aspects applied to it.
+
+```ruby
+relation.only(:where)
+```
+
+### Extending relations
+
+#### `#extending`
+
+In order to add additional methods to a relation, you can use `extending`. You can either pass a list of modules that will be included in this particular instance, or a block defining additional methods.
+
+```ruby
+module Pagination
+  def page_size = 25
+
+  def page(page)
+    limit(page_size).offset(page.to_i * page_size)
+  end
+
+  def total_count
+    except(:limit, :offset).count
+  end
+end
+
+relation.extending(Pagination)
+```
+
+The following example is equivalent to the example above:
+
+```ruby
+relation.extending do
+  def page_size = 25
+
+  def page(page)
+    limit(page_size).offset(page.to_i * page_size)
+  end
+
+  def total_count
+    except(:limit, :offset).count
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -62,6 +257,10 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/userlist/active_model-relation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/userlist/active_model-relation/blob/main/CODE_OF_CONDUCT.md).
 
+## Acknowledgements
+
+This library is _heavily_ inspired by [`ActiveRecord::Relation`](https://github.com/rails/rails/blob/main/activerecord/lib/active_record/relation.rb) and uses similar patterns and implementations in various parts.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/active_model/relation/order_clause.rb

@@ -10,20 +10,16 @@ module ActiveModel
           @name = name
         end
 
-        def call(_, _)
-          0
-        end
-      end
-
-      class Ascending < OrderExpression
         def call(record, other)
           record.public_send(name) <=> other.public_send(name)
         end
       end
 
+      class Ascending < OrderExpression; end
+
       class Descending < OrderExpression
         def call(record, other)
-          other.public_send(name) <=> record.public_send(name)
+          super(other, record)
         end
       end
 

data/lib/active_model/relation/querying.rb

@@ -9,11 +9,7 @@ module ActiveModel
         delegate :where, :find, :find_by, :offset, :limit, :first, :last, to: :all
 
         def all
-          current_scope || ActiveModel::Relation.new(self, records)
-        end
-
-        def records
-          raise NotImplementedError
+          current_scope || ActiveModel::Relation.new(self)
         end
       end
     end

data/lib/active_model/relation/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveModel
   class Relation
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/lib/active_model/relation.rb

@@ -3,7 +3,7 @@
 require 'active_model'
 
 module ActiveModel
-  class ModelNotFound < StandardError
+  class RecordNotFound < StandardError
     def initialize(message = nil, model = nil, primary_key = nil, id = nil) # rubocop:disable Metrics/ParameterLists
       @primary_key = primary_key
       @model = model
@@ -29,7 +29,7 @@ module ActiveModel
 
     delegate :each, :size, :last, to: :records
 
-    def initialize(model, records = [])
+    def initialize(model, records = model.try(:records) || [])
       @model = model
       @records = records
       @where_clause = WhereClause.new
@@ -39,11 +39,13 @@ module ActiveModel
       @extending_values = []
     end
 
-    def find(id)
+    def find(id = nil, &)
+      return records.find(id, &) if block_given?
+
       primary_key = model.try(:primary_key) || :id
 
       find_by(primary_key => id) ||
-        raise(ModelNotFound.new("Couldn't find #{model} with '#{primary_key}'=#{id}", model, primary_key, id))
+        raise(RecordNotFound.new("Couldn't find #{model} with '#{primary_key}'=#{id}", model, primary_key, id))
     end
 
     def find_by(attributes = {})

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_model-relation
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Benedikt Deicke
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-09 00:00:00.000000000 Z
+date: 2024-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -47,13 +47,13 @@ files:
 - lib/active_model/relation/version.rb
 - lib/active_model/relation/where_chain.rb
 - lib/active_model/relation/where_clause.rb
-homepage: https://github.com/benedikt/active_model-relation/
+homepage: https://github.com/userlist/active_model-relation/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/benedikt/active_model-relation/
-  source_code_uri: https://github.com/benedikt/active_model-relation/
-  changelog_uri: https://github.com/benedikt/active_model-relation/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/userlist/active_model-relation/
+  source_code_uri: https://github.com/userlist/active_model-relation/
+  changelog_uri: https://github.com/userlist/active_model-relation/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -73,5 +73,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
-summary: Query collection of ActiveModel objects like an ActiveRecord::Relation
+summary: Query collections of ActiveModel objects like an ActiveRecord::Relation
 test_files: []