typical_situation 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59384fee031d1440a474689f99be97760aedc645343e4febf4d1356ed05ee801
-  data.tar.gz: '08b482a57e976dbe1ac86604648a4f237346c09db88c672483dfae604d566cf1'
+  metadata.gz: 48bf00bdaee8edb5e3fbf54b68ca577960068cae3dac7804ca56169d738c834c
+  data.tar.gz: e11a3d08dd5991937bb08b2b3a731d8bd67f91b19658c25239bef18e60e4f921
 SHA512:
-  metadata.gz: dbcec21abd36a2da29b901bb2ffcb0468b6cf4170b4e974bef1cd640d174813c557fa8a87bddcda23e92c5709ea5c89c4fa39de7968f62ea08d5db6ac99a01a3
-  data.tar.gz: d12f5d0e3d6408a7060d46704e8dbe47cc516119fd7ae360e863bd3d00592def5e0ce99ac2bd2e6b491575284022469299689fef943368831003da8235c0a5a3
+  metadata.gz: 584cecff5e2be5ac3201983c4a2e0fbe1ec69cf5cd7cc18c91aa2d267bb73a8680194137774889fe9cd546c3f3dc55ee35bcef53ff643e8b5ff54eb741a7e6fe
+  data.tar.gz: e31342f32bc78ce7aecf165ce64c51fb38f1fd3d8031ffeec891f38b972945fc0da002227a919afc7942ca61179fe3de4e4dbf4fe3f82af77cc9a014b7ed1b14

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,17 @@ 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. `prepare_resources` - search or filter transforms
+4. `apply_sorting` - default sorting from `default_sorting_attribute`
+5. `paginate_resources` - pagination adapter hook
+
+**Scoped Collections** - Restrict the base collection based on user permissions, tenancy, or other security boundaries:
 
 ```ruby
 def scoped_resource
@@ -121,6 +133,16 @@ def scoped_resource
 end
 ```
 
+**Search and Filtering** - Apply request-driven filters after scoping and before sorting/pagination:
+
+```ruby
+def prepare_resources(resources)
+  resources = resources.where(status: params[:status]) if params[:status].present?
+  resources = resources.where("title ILIKE ?", "%#{params[:q]}%") if params[:q].present?
+  resources
+end
+```
+
 **Custom Lookup** - Use different attributes for finding resources:
 
 ```ruby
@@ -439,6 +461,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/engine.rb

@@ -1,4 +1,4 @@
-require 'rails/engine'
+require "rails/engine"
 
 module TypicalSituation
   class Engine < Rails::Engine

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
@@ -29,11 +31,11 @@ module TypicalSituation
     end
 
     def get_resource
-      if (@resource = find_resource(params[:id]))
+      if (@resource = find_resource(id_param))
         set_single_instance
         @resource
       else
-        raise ActiveRecord::RecordNotFound, "Could not find #{model_class}( id:#{params[:id].inspect} )"
+        raise ActiveRecord::RecordNotFound, "Could not find #{model_class}( id:#{id_param.inspect} )"
       end
     end
 
@@ -41,12 +43,29 @@ module TypicalSituation
       !@resource.errors.empty?
     end
 
+    # Collection pipeline lifecycle:
+    #   collection         - base relation (user-defined, required)
+    #   scoped_resource    - wraps/scopes the collection (visibility, tenancy, PHI)
+    #   prepare_resources  - standardized additional transforms (search, filter)
+    #   apply_sorting      - applies ORDER BY
+    #   paginate_resources - applies pagination
+    #
+    # Override +prepare_resources+ in host controllers to add search/filter
+    # behavior without touching sorting or pagination hooks.
     def get_resources
-      @resources = paginate_resources(apply_sorting(scoped_resource))
+      resources = scoped_resource
+      resources = prepare_resources(resources)
+      resources = apply_sorting(resources)
+      resources = paginate_resources(resources)
+      @resources = resources
       set_collection_instance
       @resources
     end
 
+    def prepare_resources(resources)
+      resources
+    end
+
     def new_resource
       @resource = collection.build
     end
@@ -93,16 +112,8 @@ 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)
+    def id_param
+      params[:id]
     end
 
     private
@@ -111,5 +122,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.2"
+  VERSION = "1.1.0"
 end

data/lib/typical_situation.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'typical_situation/engine'
-require 'typical_situation/identity'
-require 'typical_situation/permissions'
-require 'typical_situation/flash_messages'
-require 'typical_situation/actions'
-require 'typical_situation/operations'
-require 'typical_situation/responses'
+require "typical_situation/engine"
+require "typical_situation/identity"
+require "typical_situation/permissions"
+require "typical_situation/flash_messages"
+require "typical_situation/actions"
+require "typical_situation/operations"
+require "typical_situation/responses"
 
 module TypicalSituation
   class Error < StandardError; end
@@ -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.2
+  version: 1.1.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:
   - - ">="