typical_situation 1.0.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25d81edd5ff28eb30b117722caf4e497c1c795d598d53ac92af1b007306454d9
-  data.tar.gz: 7ebc26384625a9cc513a6c1cd0308ad9339d812694469b1a3114191ee2449bd9
+  metadata.gz: 1806328a0281819fd09cedb96002dd5e038f56a2b292c608b8e1920bd3e7cf25
+  data.tar.gz: fb92828cdf08f013652d379c96e52177b1f6005184b24ac6ea9e9273b4d94383
 SHA512:
-  metadata.gz: 8ed5141d2a0ef301ef1a5b2e07df10c988584c70e9fdcb319499f655b5fba03e19dff789cafd0fb1370bcc2125d916a63711ea51df602cf8fedf2fd853b958cf
-  data.tar.gz: f34b42196b747b3ba706d61b72afbbe6eee59d31dfab64e933836a5f9e25f9715ff129dd12aac1eccf975413ee51eb14df4f66ed368a131881d30d777c4ac2a5
+  metadata.gz: 4d997a83448cd809e5c884c67fb55cd5be7fe1cf2869b6b177e884300c06cd63b65fce54c85f594b68f239bee417b629e9e9335480ed049c6f05d02d0ad2592f
+  data.tar.gz: c4b44e7839dfdcdc8d896354748e154e12c270bfc1c93be8f9167b65f774d24f970ebdc69dc493890bd0f47c582d8075a14d8622963647d69b0c0e55c7bf8c54

data/README.md

@@ -8,15 +8,17 @@ A Ruby mixin (module) providing the seven standard resource actions & responses
 
 Tested in:
 
-- Rails 7.0
-- Rails 7.1  
+- Rails 7.2
 - Rails 8.0
+- Rails 8.1
 
 Against Ruby versions:
 
+- 3.1
 - 3.2
 - 3.3
 - 3.4
+- 4.0
 
 Add to your **Gemfile**:
 
@@ -109,7 +111,18 @@ The library is split into modules:
 
 #### Common Customization Hooks
 
-**Scoped Collections** - Filter the collection based on user permissions or other criteria:
+Most customization hooks are intended to be overridden as `private` or `protected` controller methods so they do not become public controller actions.
+
+For index actions, resources move through this pipeline:
+
+1. `collection` - base relation from the host controller
+2. `scoped_resource` - visibility/tenant/security scoping
+3. `apply_filtering` - request-driven search and filter transforms
+4. `apply_sorting` - default sorting from `default_sorting_attribute`
+5. `paginate_resources` - pagination adapter hook
+6. `prepare_resources` - post-process the loaded records
+
+**Scoped Collections** - Restrict the base collection based on user permissions, tenancy, or other security boundaries:
 
 ```ruby
 def scoped_resource
@@ -121,6 +134,24 @@ def scoped_resource
 end
 ```
 
+**Search and Filtering** - Apply request-driven filters after scoping and before sorting/pagination:
+
+```ruby
+def apply_filtering(resources)
+  resources = resources.where(status: params[:status]) if params[:status].present?
+  resources = resources.where("title ILIKE ?", "%#{params[:q]}%") if params[:q].present?
+  resources
+end
+```
+
+**Post-processing** - Mutate or decorate the final paginated record set (e.g. compute a derived attribute on every record):
+
+```ruby
+def prepare_resources(resources)
+  resources.each { |post| post.current_user_liked = liked_post_ids.include?(post.id) }
+end
+```
+
 **Custom Lookup** - Use different attributes for finding resources:
 
 ```ruby
@@ -439,6 +470,19 @@ Start an interactive console to experiment with the gem:
 bundle exec irb -r typical_situation
 ```
 
+### Releasing
+
+Create a release from `main`:
+
+```sh
+bin/release {major|minor|patch|pre}
+git push --follow-tags
+```
+
+The release script validates the repository, bumps the version, creates a git tag.
+
+Publishing to RubyGems and creating a GitHub Release are handled automatically by GitHub Actions.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/apsislabs/typical_situation.

data/lib/typical_situation/identity.rb

@@ -3,6 +3,8 @@
 module TypicalSituation
   # These Identity methods must be defined for each implementation.
   module Identity
+    protected
+
     # Symbolized, underscored version of the model (class) to use.
     def model_type
       raise(NotImplementedError, "#model_type must be defined in the TypicalSituation implementation.")

data/lib/typical_situation/operations.rb

@@ -4,6 +4,8 @@ module TypicalSituation
   # Model operations.
   # Assume that we're working w/ an ActiveRecord association collection.
   module Operations
+    protected
+
     def scoped_resource
       collection
     end
@@ -41,12 +43,35 @@ module TypicalSituation
       !@resource.errors.empty?
     end
 
+    # Collection pipeline lifecycle:
+    #   collection         - base relation (user-defined, required)
+    #   scoped_resource    - wraps/scopes the collection (visibility, tenancy, PHI)
+    #   apply_filtering    - applies search/filter params
+    #   apply_sorting      - applies ORDER BY
+    #   paginate_resources - applies pagination
+    #   prepare_resources  - post-processes the loaded records (e.g. set a computed attribute)
+    #
+    # Override +apply_filtering+ to add search/filter behavior.
+    # Override +prepare_resources+ to mutate or decorate the final record set.
     def get_resources
-      @resources = paginate_resources(apply_sorting(scoped_resource))
+      resources = scoped_resource
+      resources = apply_filtering(resources)
+      resources = apply_sorting(resources)
+      resources = paginate_resources(resources)
+      resources = prepare_resources(resources)
+      @resources = resources
       set_collection_instance
       @resources
     end
 
+    def apply_filtering(resources)
+      resources
+    end
+
+    def prepare_resources(resources)
+      resources
+    end
+
     def new_resource
       @resource = collection.build
     end
@@ -93,20 +118,6 @@ module TypicalSituation
       resource
     end
 
-    # Set the singular instance variable named after the model. Modules are delimited with "_".
-    # Example: a MockApplePie resource is set to ivar @mock_apple_pie.
-    def set_single_instance
-      instance_variable_set(:"@#{model_type.to_s.gsub("/", "__")}", @resource)
-    end
-
-    # Set the plural instance variable named after the model. Modules are delimited with "_".
-    # Example: a MockApplePie resource collection is set to ivar @mock_apple_pies.
-    def set_collection_instance
-      instance_variable_set(:"@#{model_type.to_s.gsub("/", "__").pluralize}", @resources)
-    end
-
-    protected
-
     def id_param
       params[:id]
     end
@@ -117,5 +128,15 @@ module TypicalSituation
       return resources unless default_sorting_attribute
       resources.order(default_sorting_attribute => default_sorting_direction)
     end
+
+    # Sets the singular ivar named after the model (modules delimited with "__").
+    def set_single_instance
+      instance_variable_set(:"@#{model_type.to_s.gsub("/", "__")}", @resource)
+    end
+
+    # Sets the plural ivar named after the model (modules delimited with "__").
+    def set_collection_instance
+      instance_variable_set(:"@#{model_type.to_s.gsub("/", "__").pluralize}", @resources)
+    end
   end
 end

data/lib/typical_situation/permissions.rb

@@ -2,6 +2,8 @@
 
 module TypicalSituation
   module Permissions
+    protected
+
     def authorized?(_action, _resource = nil)
       true
     end

data/lib/typical_situation/responses.rb

@@ -3,6 +3,8 @@
 module TypicalSituation
   # Rails MIME responses.
   module Responses
+    protected
+
     # Return the collection as HTML or JSON
     #
     def respond_with_resources

data/lib/typical_situation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypicalSituation
-  VERSION = "1.0.3"
+  VERSION = "1.2.0"
 end

data/lib/typical_situation.rb

@@ -40,6 +40,7 @@ module TypicalSituation
       define_method :model_type do
         model_type_symbol
       end
+      protected :model_type
 
       if only
         only.each do |action|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typical_situation
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.2.0
 platform: ruby
 authors:
 - Mars Hall
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -53,7 +53,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.2.0
 - !ruby/object:Gem::Dependency
-  name: byebug
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -210,7 +224,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="