typical_situation 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48bf00bdaee8edb5e3fbf54b68ca577960068cae3dac7804ca56169d738c834c
-  data.tar.gz: e11a3d08dd5991937bb08b2b3a731d8bd67f91b19658c25239bef18e60e4f921
+  metadata.gz: 1784b34111a7c2de6a6f429d431d5fc36e00ec033f5e43c1618fc8a198ff534c
+  data.tar.gz: 4c40c7fab53aacffff4d30dbe5578fae9019e798384c086b36e4566bdb46baee
 SHA512:
-  metadata.gz: 584cecff5e2be5ac3201983c4a2e0fbe1ec69cf5cd7cc18c91aa2d267bb73a8680194137774889fe9cd546c3f3dc55ee35bcef53ff643e8b5ff54eb741a7e6fe
-  data.tar.gz: e31342f32bc78ce7aecf165ce64c51fb38f1fd3d8031ffeec891f38b972945fc0da002227a919afc7942ca61179fe3de4e4dbf4fe3f82af77cc9a014b7ed1b14
+  metadata.gz: e88563fb73ebb702a0b673920e1e85b925799a9287b3336fec394dc8a52952234e296576d7c39a05e015e95611185a1607e7cb0feb005af6a1406caef15b488b
+  data.tar.gz: 1a663cdf260368f6ab83b7fadd99128a62cbae89ba67b2d50881232a0f388cc319ae4b5d3b6c4029e47145710be28c344e2608bae30cd2203fcaf5ccb6c95fe8

data/README.md

@@ -30,7 +30,7 @@ Add to your **Gemfile**:
 
 ### Define your model and methods
 
-Basic usage is to declare the `typical_situation`, and then two required helper methods. Everything else is handled automatically.
+Basic usage is to declare `typical_situation` and define the required `collection` helper. Member lookup uses the model's configured single-column primary key within the security-scoped collection. Missing identifiers return `nil` from the lookup and produce a 404 response.
 
 ```rb
 class PostsController < ApplicationController
@@ -45,11 +45,6 @@ class PostsController < ApplicationController
   def collection
     current_user.posts
   end
-
-  # Find a model instance by ID.
-  def find_in_collection(id)
-    collection.find_by_id(id)
-  end
 end
 ```
 
@@ -108,6 +103,7 @@ The library is split into modules:
 - [operations](https://github.com/mars/typical_situation/blob/master/lib/typical_situation/operations.rb) - loading, changing, & persisting the model
 - [permissions](https://github.com/mars/typical_situation/blob/master/lib/typical_situation/permissions.rb) - handling authorization to records and actions
 - [responses](https://github.com/mars/typical_situation/blob/master/lib/typical_situation/responses.rb) - HTTP responses & redirects
+- [serialization](lib/typical_situation/serialization.rb) - resource representation and JSON root wrapping
 
 #### Common Customization Hooks
 
@@ -117,11 +113,12 @@ 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
+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:
+**Scoped Collections** - Restrict the base collection based on user permissions, tenancy, or other security boundaries. This scope applies to index and member lookup for show, edit, update, and destroy. Filtering, sorting, and pagination remain index-only. New/create use `collection`, so read-visibility conditions do not become creation defaults:
 
 ```ruby
 def scoped_resource
@@ -136,21 +133,31 @@ end
 **Search and Filtering** - Apply request-driven filters after scoping and before sorting/pagination:
 
 ```ruby
-def prepare_resources(resources)
+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
-def find_resource(param)
-  collection.find_by!(slug: param)
+def find_in_collection(resources, slug)
+  resources.find_by(slug: slug)
 end
 ```
 
+The lookup receives `scoped_resource`; query that relation rather than `collection` to preserve security boundaries. Overriding `find_resource` replaces the security-aware lookup entirely.
+
 **Custom Redirects** - Control where users go after actions:
 
 ```ruby
@@ -323,7 +330,9 @@ end
 
 #### Serialization
 
-Under the hood `TypicalSituation` calls `to_json` on your `ActiveRecord` models. This isn't always the optimal way to serialize resources, though, and so `TypicalSituation` offers a simple means of overriding the base Serialization --- either on an individual controller, or for your entire application.
+`TypicalSituation` calls `as_json(root: false)` by default. Override `serializable_resource` to return an unrooted Ruby `Hash` for a member or an `Array` of resource data for a collection. Rails encodes the response once; returning an encoded JSON string raises `TypeError`.
+
+`include_root?` controls wrapping with `model_type` for members and `plural_model_type` for collections. Error responses merge model errors under `errors`, independently of the custom serializer.
 
 ##### Alba
 
@@ -343,16 +352,12 @@ class MockApplePiesController < ApplicationController
   private
 
   def serializable_resource(resource)
-    MockApplePieResource.new(resource).serialize
+    MockApplePieResource.new(resource).to_h
   end
 
   def collection
     current_user.mock_apple_pies
   end
-
-  def find_in_collection(id)
-    collection.find_by_id(id)
-  end
 end
 ```
 
@@ -364,15 +369,19 @@ class MockApplePieIndexSerializer < ActiveModel::Serializer
 end
 
 module TypicalSituation
-  module Operations
+  module Serialization
     def serializable_resource(resource)
       if action_name == "index"
         ActiveModelSerializers::SerializableResource.new(
           resource,
-          each_serializer: MockApplePieIndexSerializer
-        )
+          each_serializer: MockApplePieIndexSerializer,
+          adapter: :attributes
+        ).as_json
       else
-        ActiveModelSerializers::SerializableResource.new(resource)
+        ActiveModelSerializers::SerializableResource.new(
+          resource,
+          adapter: :attributes
+        ).as_json
       end
     end
   end
@@ -392,11 +401,22 @@ class MockApplePiesController < ApplicationController
   include TypicalSituation
 
   def serializable_resource(resource)
-    MockApplePieSerializer.new(resource).serializable_hash
+    MockApplePieSerializer.new(resource).serializable_hash.fetch(:data)
   end
 end
 ```
 
+## Migrating Controller Hooks
+
+These hook changes are breaking:
+
+- Remove redundant `find_in_collection(id)` overrides, or change them to `find_in_collection(resources, id)` and query the supplied scoped relation.
+- `update_resource(resource, attrs)` must return a success boolean. `create_resource` and `destroy_resource` still return resources; success is determined by `persisted?` and `destroyed?`, respectively. Callback aborts return 422 even when no validation errors were added.
+- Overrides of `respond_as_created`, `respond_as_changed`, and `respond_as_gone` must accept the required `success:` keyword and pass it to `super` when delegating.
+- HTML creation uses `created_so_redirect` and `after_resource_created_path`; updates continue using `changed_so_redirect` and `after_resource_updated_path`.
+- Serialization methods now live in `TypicalSituation::Serialization`, not `Operations`. Return Ruby data from `serializable_resource`, not JSON strings or serializer objects. Overrides of `serialize_resource` should accept `errors: false` instead of an options hash.
+- Failed operations preserve model errors or add `typical_situation.errors.operation_failed` when none exist. Failed HTML destruction sets the error flash; JSON failures do not set flash messages.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/config/locales/typical_situation.en.yml

@@ -1,5 +1,7 @@
 en:
   typical_situation:
+    errors:
+      operation_failed: "Operation could not be completed"
     flash:
       create:
         success: "%{resource} was successfully created"

data/lib/typical_situation/actions.rb

@@ -35,8 +35,12 @@ module TypicalSituation
       get_resource
       raise TypicalSituation::ActionForbidden unless authorized?(:update, @resource)
 
-      update_resource(@resource, update_params)
-      respond_as_changed
+      success = normalize_operation_result(
+        @resource,
+        success: update_resource(@resource, update_params)
+      )
+
+      respond_as_changed(success: success)
     end
 
     def destroy
@@ -44,14 +48,26 @@ module TypicalSituation
       raise TypicalSituation::ActionForbidden unless authorized?(:destroy, @resource)
 
       destroy_resource(@resource)
-      respond_as_gone
+
+      success = normalize_operation_result(
+        @resource,
+        success: @resource.destroyed?
+      )
+
+      respond_as_gone(success: success)
     end
 
     def create
       raise TypicalSituation::ActionForbidden unless authorized?(:create)
 
       @resource = create_resource(create_params)
-      respond_as_created
+
+      success = normalize_operation_result(
+        @resource,
+        success: @resource.persisted?
+      )
+
+      respond_as_created(success: success)
     end
   end
 end

data/lib/typical_situation/identity.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module TypicalSituation
-  # These Identity methods must be defined for each implementation.
+  # Model identity, collection, and request configuration.
   module Identity
     protected
 
@@ -43,9 +43,9 @@ module TypicalSituation
       raise(NotImplementedError, "#collection must be defined in the TypicalSituation implementation.")
     end
 
-    # Find a model instance by ID.
-    def find_in_collection(_id)
-      raise(NotImplementedError, "#find_in_collection must be defined in the TypicalSituation implementation.")
+    # Find a model instance by its configured primary key.
+    def find_in_collection(resources, identifier)
+      resources.find_by(resources.primary_key => identifier)
     end
 
     def include_root?

data/lib/typical_situation/operations.rb

@@ -11,7 +11,7 @@ module TypicalSituation
     end
 
     def find_resource(param)
-      find_in_collection(param)
+      find_in_collection(scoped_resource, param)
     end
 
     def default_sorting_attribute
@@ -46,22 +46,28 @@ module TypicalSituation
     # 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_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 +prepare_resources+ in host controllers to add search/filter
-    # behavior without touching sorting or pagination hooks.
+    # Override +apply_filtering+ to add search/filter behavior.
+    # Override +prepare_resources+ to mutate or decorate the final record set.
     def get_resources
       resources = scoped_resource
-      resources = prepare_resources(resources)
+      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
@@ -80,7 +86,6 @@ module TypicalSituation
 
     def destroy_resource(resource)
       resource.destroy
-      collection.reload if resource.errors.empty?
       resource
     end
 
@@ -96,28 +101,23 @@ module TypicalSituation
       @model_class ||= model_type.to_s.camelize.constantize
     end
 
-    def serialize_resource(resource, options = {})
-      serializable_resource(resource).to_json(options.merge(root: include_root?))
-    end
-
-    def serialize_resources(resources)
-      if include_root?
-        return {plural_model_type => serializable_resource(resources)}
-      end
-
-      serializable_resource(resources).to_json(root: false)
-    end
-
-    def serializable_resource(resource)
-      resource
-    end
-
     def id_param
       params[:id]
     end
 
     private
 
+    def normalize_operation_result(resource, success:)
+      if !success && resource.errors.empty?
+        resource.errors.add(
+          :base,
+          I18n.t("typical_situation.errors.operation_failed")
+        )
+      end
+
+      success
+    end
+
     def apply_sorting(resources)
       return resources unless default_sorting_attribute
       resources.order(default_sorting_attribute => default_sorting_direction)

data/lib/typical_situation/responses.rb

@@ -39,42 +39,40 @@ module TypicalSituation
       end
     end
 
-    def respond_as_changed
-      if has_errors?
-        respond_as_error
-      else
-        respond_to do |format|
-          yield(format) if block_given?
-
-          format.html do
-            set_success_flash(:update)
-            set_single_instance
-            changed_so_redirect || render
-          end
-          format.json do
-            render json: serialize_resource(@resource)
-          end
+    def respond_as_changed(success:)
+      return respond_as_failure(:update) unless success
+
+      respond_to do |format|
+        yield(format) if block_given?
+
+        format.html do
+          set_success_flash(:update)
+          set_single_instance
+          changed_so_redirect || render
+        end
+
+        format.json do
+          render json: serialize_resource(@resource)
         end
       end
     end
 
-    def respond_as_created
-      if has_errors?
-        respond_as_error
-      else
-        respond_to do |format|
-          yield(format) if block_given?
-
-          format.html do
-            set_success_flash(:create)
-            set_single_instance
-            changed_so_redirect || render
-          end
-          format.json do
-            render json: serialize_resource(@resource),
-              location: location_url,
-              status: :created
-          end
+    def respond_as_created(success:)
+      return respond_as_failure(:create) unless success
+
+      respond_to do |format|
+        yield(format) if block_given?
+
+        format.html do
+          set_success_flash(:create)
+          set_single_instance
+          created_so_redirect || render
+        end
+
+        format.json do
+          render json: serialize_resource(@resource),
+            location: location_url,
+            status: :created
         end
       end
     end
@@ -89,27 +87,25 @@ module TypicalSituation
             status: :unprocessable_entity
         end
         format.json do
-          render json: serialize_resource(@resource, methods: [:errors]),
+          render json: serialize_resource(@resource, errors: true),
             status: :unprocessable_entity
         end
       end
     end
 
-    def respond_as_gone
-      if has_errors?
-        set_error_flash
-        respond_as_error
-      else
-        respond_to do |format|
-          yield(format) if block_given?
-
-          format.html do
-            set_single_instance
-            gone_so_redirect || render
-          end
-          format.json do
-            head :no_content
-          end
+    def respond_as_gone(success:)
+      return respond_as_failure(:destroy) unless success
+
+      respond_to do |format|
+        yield(format) if block_given?
+
+        format.html do
+          set_single_instance
+          gone_so_redirect || render
+        end
+
+        format.json do
+          head :no_content
         end
       end
     end
@@ -135,17 +131,22 @@ module TypicalSituation
     end
 
     def after_resource_created_path(resource)
-      {action: :show, id: resource.id}
+      {action: :show, id: resource.to_param}
     end
 
     def after_resource_updated_path(resource)
-      {action: :show, id: resource.id}
+      {action: :show, id: resource.to_param}
     end
 
     def after_resource_destroyed_path(_resource)
       {action: :index}
     end
 
+    def created_so_redirect
+      redirect_to after_resource_created_path(@resource)
+      true
+    end
+
     # HTML response when @resource saved or updated.
     def changed_so_redirect
       redirect_to after_resource_updated_path(@resource)
@@ -154,10 +155,16 @@ module TypicalSituation
 
     # HTML response when @resource deleted.
     def gone_so_redirect
-      set_error_flash if has_errors?
-      set_success_flash(:destroy) unless has_errors?
+      set_success_flash(:destroy)
       redirect_to after_resource_destroyed_path(@resource)
       true
     end
+
+    private
+
+    def respond_as_failure(action)
+      set_error_flash if action == :destroy && request.format.html?
+      respond_as_error
+    end
   end
 end

data/lib/typical_situation/serialization.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TypicalSituation
+  module Serialization
+    protected
+
+    def serialize_resource(resource, errors: false)
+      data = serialization_data(resource, Hash)
+      data = data.merge("errors" => resource.errors.as_json) if errors
+
+      include_root? ? {model_type => data} : data
+    end
+
+    def serialize_resources(resources)
+      data = serialization_data(resources, Array)
+
+      include_root? ? {plural_model_type => data} : data
+    end
+
+    def serializable_resource(resource)
+      resource.as_json(root: false)
+    end
+
+    private
+
+    def serialization_data(resource, expected_type)
+      data = serializable_resource(resource)
+
+      unless data.is_a?(expected_type)
+        raise TypeError,
+          "serializable_resource must return #{expected_type}, got #{data.class}"
+      end
+
+      data
+    end
+  end
+end

data/lib/typical_situation/version.rb

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

data/lib/typical_situation.rb

@@ -7,19 +7,28 @@ require "typical_situation/flash_messages"
 require "typical_situation/actions"
 require "typical_situation/operations"
 require "typical_situation/responses"
+require "typical_situation/serialization"
 
 module TypicalSituation
   class Error < StandardError; end
   class ActionForbidden < Error; end
 
+  ACTION_NAMES = Actions.public_instance_methods(false).map(&:to_s).freeze
+
   include Identity
   include Permissions
   include FlashMessages
   include Operations
   include Responses
+  include Serialization
 
   def self.included(base)
     add_rescues(base)
+
+    base.class_attribute :typical_action_names,
+      instance_accessor: false,
+      default: ACTION_NAMES
+
     base.extend(ClassMethods)
   end
 
@@ -37,20 +46,23 @@ module TypicalSituation
     #     :post
     #   end
     def typical_situation(model_type_symbol, only: nil)
-      define_method :model_type do
-        model_type_symbol
+      actions = only.nil? ? ACTION_NAMES : Array(only).map(&:to_s)
+      unknown = actions - ACTION_NAMES
+
+      if unknown.any?
+        raise ArgumentError, "Unknown actions: #{unknown.join(", ")}"
       end
+
+      self.typical_action_names = actions.freeze
+
+      define_method(:model_type) { model_type_symbol }
       protected :model_type
 
-      if only
-        only.each do |action|
-          if TypicalSituation::Actions.method_defined?(action)
-            define_method(action, TypicalSituation::Actions.instance_method(action))
-          end
-        end
-      else
-        include TypicalSituation::Actions
-      end
+      include TypicalSituation::Actions
+    end
+
+    def action_methods
+      super - (ACTION_NAMES - typical_action_names)
     end
 
     def typical_rest(model_type_symbol)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typical_situation
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Mars Hall
@@ -213,6 +213,7 @@ files:
 - lib/typical_situation/operations.rb
 - lib/typical_situation/permissions.rb
 - lib/typical_situation/responses.rb
+- lib/typical_situation/serialization.rb
 - lib/typical_situation/version.rb
 homepage: https://github.com/apsislabs/typical_situation
 licenses: []