active_model-relation 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2440274ca803bb2b2d571a3c7753730c66a86a5c8e5ccba873dbd19541e236a3
-  data.tar.gz: cab3d4c534dc3ada120d5660a029cffdd343d5869653f183434cf8fd3793da4b
+  metadata.gz: 317f4bd9c497d254fabc65f125c743badd36fe4f91e41876bd40819f77703e01
+  data.tar.gz: 937df0db69de0e3983531fae564b0cefa8efbb3cc9d9aac499238a601d9e6503
 SHA512:
-  metadata.gz: 12fe2562f8977cb3b2ac5db4f32dce3dd886d9c4d09996e2bf8fbb98e699ac54f6cad071625cc430c4de1615a3089fdf178bdc2d9c738d1f96b2fbe58a185ff7
-  data.tar.gz: 7cf7a6a159a8b5df87c5112644f2dc1118cf5e91b26bdf273c182e8ea4d84768291618ec4c0b47bd3b985217d26331551d9bec5a8f8e5a8c6bc59f69b00f3f7e
+  metadata.gz: f147ee5f25e5b5cd8570dae9d0117c4cbbf015491d8820ae07cf6cca831075d3c9a70f5cc0ec0bf7a15dd522bd691103fa12ee9b6e9b3dcc9a12484ca0761df3
+  data.tar.gz: d61a00b7833c030be0ca14d814f8aeb8e0f23d913e071dd068a09fac050106ca1f3c46cd80b8dea597c21632397fec4d0ccd276cfb7193b29e09b73d1b2ebe68

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-08-30
+- Treat `ActiveModel::RecordNotFound` like `ActiveRecord::RecordNotFound` in `ActionDispatch`
+- Properly type cast values when they are defined as attribute
+- Ensure that there is always at least an empty array of records
+
+## [0.2.0] - 2024-09-16
+
+- Rename `ActiveModel::ModelNotFound` to `ActiveModel::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::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).
@@ -69,3 +268,11 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the ActiveModel::Relation project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/userlist/active_model-relation/blob/main/CODE_OF_CONDUCT.md).
+
+## What is Userlist?
+
+[![Userlist](https://userlist.com/images/external/userlist-logo-github.svg)](https://userlist.com/)
+
+[Userlist](https://userlist.com/) allows you to onboard and engage your SaaS users with targeted behavior-based campaigns using email or in-app messages.
+
+Userlist was started in 2017 as an alternative to bulky enterprise messaging tools. We believe that running SaaS products should be more enjoyable. Learn more [about us](https://userlist.com/about-us/).

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/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+module ActiveModel
+  class Relation
+    class Railtie < Rails::Railtie # :nodoc:
+      config.action_dispatch.rescue_responses.merge!(
+        'ActiveModel::RecordNotFound' => :not_found
+      )
+    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.1'
   end
 end

data/lib/active_model/relation.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require 'active_model'
+require_relative 'relation/railtie' if defined?(Rails::Railtie)
 
 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,9 +30,9 @@ module ActiveModel
 
     delegate :each, :size, :last, to: :records
 
-    def initialize(model, records = [])
+    def initialize(model, records = model.try(:records))
       @model = model
-      @records = records
+      @records = records || []
       @where_clause = WhereClause.new
       @order_clause = OrderClause.new
       @offset_value = nil
@@ -39,15 +40,17 @@ 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 = {})
-      where_clause = self.where_clause + WhereClause.from_hash(attributes)
+      where_clause = self.where_clause + WhereClause.from_hash(type_cast_values(attributes))
 
       records.find(&where_clause)
     end
@@ -59,7 +62,7 @@ module ActiveModel
     def where!(attributes = {}, &)
       return WhereChain.new(spawn) unless attributes.any? || block_given?
 
-      self.where_clause += WhereClause.build(attributes, &)
+      self.where_clause += WhereClause.build(type_cast_values(attributes), &)
       self
     end
 
@@ -178,5 +181,14 @@ module ActiveModel
         relation.limit_value = values[:limit]
       end
     end
+
+    def type_cast_values(attributes)
+      attributes.to_h do |key, value|
+        type = model.try(:type_for_attribute, key)
+        value = type.cast(value) if type
+
+        [key, value]
+      end
+    end
   end
 end

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: active_model-relation
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Benedikt Deicke
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-09 00:00:00.000000000 Z
+date: 2024-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 description: This library allows querying of collections of Ruby objects, with a similar
   interface to ActiveRecord::Relation.
 email:
@@ -43,17 +49,18 @@ files:
 - lib/active_model/relation/model.rb
 - lib/active_model/relation/order_clause.rb
 - lib/active_model/relation/querying.rb
+- lib/active_model/relation/railtie.rb
 - lib/active_model/relation/scoping.rb
 - 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 +80,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: []