propel_facets 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213ffd21289407fbd5ea496541026dc6b74ab15ac40c5e664b46b8c8566554b8
-  data.tar.gz: 445aa9e0fc962b1ea8e0ae2300d59dc14639fe9b76f27b0f2a80a0bda9c5dce9
+  metadata.gz: e5233eaef1c8dc1acd2c631b9117c5b1a13c8deb1997d97a0e5fb294c7c55081
+  data.tar.gz: 15905b8628b5f2cb805b91ba4e25b36451a23ece1768216f64b0ae4fe964a96e
 SHA512:
-  metadata.gz: 629277208c5fcb8a1c45358d8515619fb45e583557bcc3df5775730bffe0e34ce6e6228344b632a6c0c34d4f77be6c77f3f17c75cc842d7211e7a30243ad959c
-  data.tar.gz: bab90747419b952deb39e0f170785535e9d292a0e9c054c8764e40d3ba9ba9cda7b88b14f1fb2e8cceffeb7ff669ba322a33abaf32ed26a93171df4cf857938d
+  metadata.gz: 57cf3b84754b71e1c18d45ac31690531ec212f49bc2179eda78fc3e791b01f0e6cf7c2dbf38f99e42765c45dfd1a39b071446a461ceb88a206339f2303a7ac82
+  data.tar.gz: 461b058e8e4f91e575d83560029b738f873c8dd85744be9c22e1bfd343a8c07b53cf1035229ea0906125c8710c20995c51e4f3c4ed568b408f047e2ca816b6e7

data/CHANGELOG.md

@@ -14,7 +14,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Metadata inclusion (pagination, counts, etc.)
 - Performance logging and optimization tools
 
-## [0.1.4] - 2025-01-23
+## [0.2.0] - 2025-09-02
+
+### Added
+- **Enhanced facet pattern consistency** - Standardized JSON facet definitions across all models
+  - Support for comprehensive User model facets with authentication fields
+  - Improved association handling in facet rendering with proper include directives
+  - Consistent field inclusion patterns for better API consistency
+
+### Improved
+- **Compatibility updates** - Enhanced integration with PropelAuthentication 0.2.0 and PropelApi 0.2.0
+  - Updated to work with new security-first architecture
+  - Maintained full compatibility with enhanced JSON facet definitions
+  - Support for `PropelAuthenticationConcern` namespace changes
+  - Seamless integration with configurable tenancy requirements
+
+### Fixed
+- **JSON facet rendering** - Enhanced association handling and field inclusion
+  - Proper handling of organization associations in User model facets
+  - Consistent foreign key and association rendering across all model types
+
+## [0.1.4] - 2025-08-15
 
 ### Added
 - **Clean controller generation by default** - PropelFacets controller templates now generate production-ready code

data/better_nesting.md

@@ -0,0 +1,166 @@
+# Feature Implementation Guide: Per-Association Facet Specification in json_facet includes
+
+## Current State
+The `json_facet` system currently supports including associations, but all included associations use the same facet determined by the `include_as` parameter:
+
+```ruby
+# Current syntax - all associations use :included facet
+json_facet :details, 
+  fields: [:id, :name], 
+  include: [:organization, :user, :comments], 
+  include_as: :included
+```
+
+## Desired Feature
+Enable specifying different facets for different associations within a single json_facet definition:
+
+```ruby
+# Proposed syntax - each association can specify its own facet
+json_facet :details,
+  fields: [:id, :name],
+  include: {
+    organization: :short,      # Use organization's :short facet
+    user: :included,          # Use user's :included facet  
+    comments: :minimal        # Use comment's :minimal facet
+  }
+```
+
+## Implementation Approach
+
+### 1. Modify `json_facet` method (line 74-85)
+- Detect when `include` is a Hash vs Array
+- Parse Hash format to extract association → facet mappings
+- Maintain backward compatibility with Array format
+
+### 2. Update `facet_serializable_options` method (line 154-161)
+Current code:
+```ruby
+include = actual[:include].reduce({}) do |memo, current|
+  memo.update(current => { facet: include_as })  # Same facet for all
+end
+```
+
+New logic needed:
+```ruby
+include = actual[:include].reduce({}) do |memo, current|
+  if current.is_a?(Hash)
+    # Handle { association: :facet_name } format
+    current.each do |assoc, facet|
+      memo.update(assoc => { facet: facet })
+    end
+  else
+    # Backward compatibility: use include_as for array format
+    memo.update(current => { facet: include_as })
+  end
+  memo
+end
+```
+
+### 3. Mixed Syntax Support
+Support combining both syntaxes in one facet:
+```ruby
+json_facet :details,
+  include: [:tags, { organization: :short, user: :minimal }],
+  include_as: :included  # Default for array items
+```
+
+### 4. Validation & Error Handling
+- Validate that specified facets exist on target models
+- Provide meaningful error messages for missing facets
+- Handle edge cases (nil facets, invalid association names)
+
+## Example Usage Patterns
+
+### Basic Usage
+```ruby
+class Product < ApplicationRecord
+  json_facet :api_response,
+    fields: [:id, :name, :price],
+    include: {
+      category: :short,        # Just id, name  
+      reviews: :summary,       # rating, comment excerpt
+      seller: :public         # name, avatar, rating
+    }
+end
+```
+
+### Mixed with Array Syntax
+```ruby
+class BlogPost < ApplicationRecord  
+  json_facet :feed_item,
+    fields: [:id, :title, :excerpt],
+    include: [
+      :tags,                   # Use default :included facet
+      { author: :author_card } # Use custom :author_card facet
+    ],
+    include_as: :included      # Default for array items
+end
+```
+
+### Nested Facet Chains
+```ruby
+class User < ApplicationRecord
+  json_facet :profile,
+    fields: [:id, :username],
+    include: {
+      organization: :public,   # Organization uses its :public facet
+      posts: :feed_summary     # Posts use their :feed_summary facet  
+    }
+end
+
+class Organization < ApplicationRecord
+  json_facet :public,
+    fields: [:id, :name, :logo],
+    include: { industry: :basic }  # Nested includes work too
+end
+```
+
+## Backward Compatibility Requirements
+- Existing `include: [:association]` syntax must continue working
+- Current `include_as: :facet` behavior must remain unchanged for array includes
+- No breaking changes to existing APIs
+
+## Test Cases to Implement
+
+### 1. Basic Hash Syntax
+```ruby
+test "should support hash syntax for per-association facets" do
+  # Test that each association uses its specified facet
+end
+```
+
+### 2. Backward Compatibility
+```ruby
+test "should maintain array syntax compatibility" do
+  # Ensure existing code continues working
+end
+```
+
+### 3. Mixed Syntax
+```ruby 
+test "should support mixed array and hash syntax" do
+  # Test combining both syntaxes in one facet
+end
+```
+
+### 4. Error Handling
+```ruby
+test "should handle missing facets gracefully" do
+  # Test behavior when specified facet doesn't exist
+end
+```
+
+### 5. Deep Nesting
+```ruby
+test "should support nested facet chains" do
+  # Test that included objects can have their own includes
+end
+```
+
+## Implementation Priority
+1. **Phase 1**: Basic Hash syntax support
+2. **Phase 2**: Mixed Array/Hash syntax  
+3. **Phase 3**: Advanced validation and error handling
+4. **Phase 4**: Performance optimization for complex nested includes
+
+This feature would provide much more granular control over JSON serialization while maintaining the elegant declarative syntax that makes json_facet powerful.

data/lib/generators/propel_facets/templates/models/application_record.rb

@@ -10,4 +10,10 @@ class ApplicationRecord < ActiveRecord::Base
   json_facet :included, base: :reference
   json_facet :short, base: :included, include_as: :reference
   json_facet :details, base: :short, include_as: :included
+
+  # Organization scoping for multi-tenancy
+  scope :for_organization, ->(organization_id) {
+    return none if organization_id.blank?
+    where(organization_id: organization_id)
+  }
 end 

data/lib/propel_facets.rb

@@ -1,3 +1,3 @@
 module PropelFacets
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: propel_facets
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Propel Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 2025-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,6 +43,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- better_nesting.md
 - lib/generators/propel_facets/README.md
 - lib/generators/propel_facets/USAGE
 - lib/generators/propel_facets/install_generator.rb