propel_facets 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da6cba3a34b195a31c1b16b7609f418cffd3b4b8ff94f54459a8a8abc2b55155
+  data.tar.gz: 119e220c8e5d0bc8f5a63b651bba57c8766a8cfffeecb5c7848bd079b45a8891
+SHA512:
+  metadata.gz: ed75a71a012e5740455d6aaadcbc9b374c7a0ad22a4cb7108d6036e00b73b6cc506a084bf744d02d857077e6e4541552015b1ed1fca463bea9706b26228a7b8d
+  data.tar.gz: 66d137d4866629b9e392d65abef7d916e66132710a945cbb7c5c8c5bdcd62cbaa7994175dd35f51f17d96136ae4e2d2ea59bf9ef2df5440c6a5c58ecbec26d95

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned Features
+- Caching system integration with Rails caching (Solid Cache support)
+- Automatic association inclusion configuration
+- Field naming conventions (camelCase, kebab-case, etc.)
+- Metadata inclusion (pagination, counts, etc.)
+- Performance logging and optimization tools
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- **Self-extracting generator gem architecture** - Install temporarily, extract code, remove dependency
+- **Rails generator system** with install and unpack commands
+- **Model concern (ModelFacet)** for defining JSON facets with inheritance
+- **Controller concerns** for rendering facets and parameter handling:
+  - `FacetRenderer` - Connect facets to controller actions
+  - `StrongParamsHelper` - Enhanced parameter handling for complex JSON
+- **Complete configuration system** with implemented features only:
+  - JSON root structure configuration (`:data`, `:model`, `:class`, `:none`)
+  - API format selection (`:rest`, `:jsonapi`, `:openapi`, `:graphql`, etc.)
+  - Strict mode for error handling
+  - Default facets and inheritance patterns
+- **Error handling system** with custom error classes
+- **API parameter utilities** for complex JSON structures
+- **Comprehensive documentation** and examples
+- **Path gem installation** support for development workflow
+- **Template system** with customizable generators
+
+### Features
+- **Multiple JSON representations** per model with simple DSL
+- **Facet inheritance** with base facets and extension chains
+- **Field and method selection** for precise API responses
+- **Association rendering** with custom facet selection
+- **Configurable JSON root structures** for different API standards
+- **Rails conventions integration** with standard patterns
+- **Zero runtime dependencies** after code extraction
+
+### Technical Implementation
+- Clean generator architecture following Rails conventions
+- Template-based code generation for easy customization
+- Proper Ruby module structure with namespace isolation
+- Comprehensive test suite for generator functionality
+- Documentation-driven development with extensive examples
+
+### Generator Commands
+- `rails generate propel_facets:install` - Install PropelFacets into application
+- `rails generate propel_facets:unpack` - Extract generator for customization
+- Selective unpacking with `--models-only`, `--controllers-only`, etc.
+
+### Self-Extracting Benefits
+- **No runtime gem dependencies** - all code lives in host application
+- **Full customization control** - modify any generated component
+- **Standard Rails patterns** - follows established conventions
+- **Easy maintenance** - no hidden gem complexity in production 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Propel Facets Generator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,354 @@
+# PropelFacets
+
+A Rails generator that provides a flexible system for defining different JSON representations of ActiveRecord models and automatically connecting them to controller actions.
+
+## Installation
+
+PropelFacets is designed as a **self-extracting generator gem**. You install it temporarily, run the generators to extract the code into your application, then remove the gem dependency.
+
+### Step 1: Add to Gemfile as a Path Gem
+
+```ruby
+# In your Gemfile
+gem 'propel_facets', path: 'propel_facets'
+```
+
+### Step 2: Bundle Install
+
+```bash
+bundle install
+```
+
+### Step 3: Unpack the Generator (Optional)
+
+If you want to customize the generator templates:
+
+```bash
+rails generate propel_facets:unpack
+```
+
+This extracts the generator into `lib/generators/propel_facets/` for customization.
+
+### Step 4: Install PropelFacets
+
+```bash
+rails generate propel_facets:install
+```
+
+This installs the facets system including model and controller concerns, utilities, and configuration.
+
+### Step 5: Remove Gem Dependency (Optional)
+
+After installation, you can remove the gem from your Gemfile. All functionality remains in your application.
+
+## Quick Start
+
+### In Models
+
+Define different JSON representations using facets:
+
+```ruby
+class User < ApplicationRecord
+  # Basic facet with specific fields
+  json_facet :summary, fields: [:id, :name, :email, :created_at]
+  
+  # Extended facet building on another
+  json_facet :details, base: :summary, 
+             fields: [:updated_at], 
+             methods: [:full_name], 
+             include: [:posts]
+             
+  # Association facets
+  json_facet :with_posts, base: :summary, include: [:posts]
+  
+  # Custom method
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+end
+```
+
+### In Controllers
+
+Connect facets to controller actions:
+
+```ruby
+class UsersController < ApplicationController
+  include FacetRenderer
+  include StrongParamsHelper
+  
+  connect_facet :summary, actions: [:index]
+  connect_facet :details, actions: [:show, :update]
+  
+  permitted_params :name, :email, :role
+  
+  def index
+    users = User.all
+    render json: { data: users.map { |user| resource_json(user) } }
+  end
+  
+  def show
+    user = User.find(params[:id])
+    render json: { data: resource_json(user) }
+  end
+end
+```
+
+### Enhanced Parameter Handling
+
+For complex JSON parameters:
+
+```ruby
+class ProductsController < ApplicationController
+  include StrongParamsHelper
+  
+  permitted_params :name, :price, :category
+  permitted_unknown_params :metadata, :settings  # For dynamic JSON structures
+  
+  def create
+    # Handles both strong params and unknown params
+    product = Product.new(resource_params)
+    # ...
+  end
+end
+```
+
+## Features
+
+### Flexible JSON Representations
+- **Multiple facets per model** - Define various JSON views for different contexts
+- **Facet inheritance** - Build complex facets by extending simpler ones
+- **Field selection** - Include specific model attributes
+- **Method inclusion** - Include results of model methods
+- **Association rendering** - Include related models with their own facets
+
+### Controller Integration
+- **Automatic facet-action mapping** - Connect specific facets to controller actions
+- **Resource JSON rendering** - Simple method to render models with appropriate facets
+- **Enhanced parameter handling** - Support for complex JSON structures
+- **Strong parameters extension** - Handles both known and unknown parameters
+
+### Configuration System
+- **JSON root structures** - Configure response format (`:data`, `:model`, `:class`, `:none`)
+- **API format standards** - Support for REST, JSON:API, OpenAPI, GraphQL formats
+- **Strict mode** - Control error handling for missing facets
+- **Default facets** - Set up standard facets across all models
+
+### Rails Integration
+- **ApplicationRecord defaults** - Standard facets available on all models
+- **ActiveStorage support** - Automatic attachment URL handling
+- **Standard Rails patterns** - Follows Rails conventions throughout
+- **Zero dependencies** - No runtime gem dependencies after extraction
+
+## Facet Options
+
+When defining facets, you can use these options:
+
+- **`fields`**: Array of model attributes to include
+- **`methods`**: Array of model methods to call and include
+- **`include`**: Array of associations to include (uses association name as JSON key)
+- **`include_as`**: Hash of associations with custom JSON key names
+- **`base`**: Name of another facet to extend from
+
+```ruby
+class Article < ApplicationRecord
+  # Basic reference facet
+  json_facet :reference, fields: [:id, :title]
+  
+  # Summary extends reference
+  json_facet :summary, base: :reference, fields: [:excerpt, :published_at]
+  
+  # Details with methods and associations
+  json_facet :details, base: :summary,
+             methods: [:word_count, :reading_time],
+             include: [:author],           # Will appear as "author" in JSON
+             include_as: [comments: :feedback]  # Will appear as "feedback" in JSON
+end
+```
+
+## Default Facets
+
+All models inherit these default facets from `ApplicationRecord`:
+
+- **`:reference`** - Basic id and type information
+- **`:included`** - Extends reference facet
+- **`:short`** - General purpose summary view
+- **`:details`** - Comprehensive view with more fields
+
+```ruby
+# These are automatically available on all models:
+User.first.as_json(facet: :reference)  # => { "id": 1, "type": "User" }
+User.first.as_json(facet: :short)      # => More fields based on inheritance
+```
+
+## Configuration
+
+Configure PropelFacets in `config/initializers/propel_facets.rb`:
+
+```ruby
+PropelFacets.configure do |config|
+  # JSON root structure: :data, :model, :class, :none
+  # :data  => { "data": { "id": 1, "name": "John" } }
+  # :model => { "user": { "id": 1, "name": "John" } }
+  # :none  => { "id": 1, "name": "John" }
+  config.root = :data
+  
+  # API format standard: :rest, :jsonapi, :openapi, :graphql
+  config.api_format = :rest
+  
+  # Default facets available on all models
+  config.default_facets = %w[reference included short details]
+  
+  # Error handling: raise errors (true) or show warnings (false)
+  config.strict_mode = false
+  
+  # Default base facet for inheritance chains
+  config.default_base_facet = :reference
+end
+```
+
+## Advanced Usage
+
+### Complex Facet Inheritance
+
+```ruby
+class Product < ApplicationRecord
+  # Base facets
+  json_facet :reference, fields: [:id, :name]
+  json_facet :pricing, fields: [:price, :currency]
+  
+  # Combine multiple facets
+  json_facet :listing, base: :reference, 
+             fields: [:description, :availability],
+             methods: [:formatted_price]
+             
+  # Full details combining multiple concerns
+  json_facet :admin, base: :listing,
+             fields: [:cost, :margin, :created_at],
+             include: [:supplier, :reviews]
+end
+```
+
+### Dynamic Parameter Handling
+
+```ruby
+class ApiController < ApplicationController
+  include StrongParamsHelper
+  
+  # Handle known parameters
+  permitted_params :name, :email, :status
+  
+  # Handle dynamic JSON structures
+  permitted_unknown_params :preferences, :metadata, :custom_fields
+  
+  private
+  
+  def resource_params
+    # Returns both strong params and unknown params merged
+    super
+  end
+end
+```
+
+### Custom JSON Formatting
+
+```ruby
+# Configure different JSON root structures
+PropelFacets.configure do |config|
+  config.root = :none  # Flat JSON structure
+end
+
+# Result:
+User.first.as_json(facet: :summary)
+# => { "id": 1, "name": "John", "email": "john@example.com" }
+
+# vs. with config.root = :data:
+# => { "data": { "id": 1, "name": "John", "email": "john@example.com" } }
+```
+
+## Self-Extracting Architecture
+
+PropelFacets follows a self-extracting pattern that provides:
+
+- **No runtime dependencies** - all code lives in your application
+- **Full control** - modify any component after installation
+- **No black boxes** - transparent, readable Rails code
+- **Easy maintenance** - standard Rails patterns throughout
+
+After installation, you can:
+- Remove the gem from your Gemfile
+- Customize all generated code
+- Maintain and extend functionality independently
+- Modify facet behavior for your specific needs
+
+## Generated Files
+
+After installation, PropelFacets creates:
+
+### Model Support
+- `app/models/concerns/model_facet.rb` - Facet definition DSL for models
+- `app/models/application_record.rb` - Base model with default facets (if needed)
+
+### Controller Support
+- `app/controllers/concerns/facet_renderer.rb` - Controller facet rendering
+- `app/controllers/concerns/strong_params_helper.rb` - Enhanced parameter handling
+
+### Utilities
+- `lib/api_params.rb` - API parameter utility class
+
+### Error Handling
+- `app/errors/application_error.rb` - Base error class
+- `app/errors/missing_facet.rb` - Facet-specific error handling
+
+### Configuration
+- `config/initializers/propel_facets.rb` - PropelFacets configuration
+
+### Documentation
+- `doc/json_facet.md` - Complete usage documentation and examples
+
+## Integration with PropelApi
+
+PropelFacets integrates seamlessly with PropelApi for complete API development:
+
+```ruby
+# Install both systems
+rails generate propel_api:install --adapter=propel_facets
+rails generate propel_facets:install
+
+# Generated API controllers automatically use facets
+class Api::V1::UsersController < Api::V1::ApiController
+  connect_facet :short, actions: [:index]
+  connect_facet :details, actions: [:show, :create, :update]
+  
+  # Facet rendering is automatic
+end
+```
+
+## Development
+
+```bash
+# Run facets tests
+cd propel_facets
+bundle exec rake test
+
+# Test specific functionality
+bundle exec ruby -Ilib:test test/propel_facets_generator_test.rb
+```
+
+## Roadmap
+
+### Planned Features
+- **Caching integration** - Rails caching support for rendered facets
+- **Field naming conventions** - camelCase, kebab-case transformations
+- **Metadata inclusion** - Pagination, counts, timestamps
+- **Performance logging** - Monitor facet rendering performance
+- **Nested depth limits** - Prevent infinite recursion
+- **Type information** - Include model type data in JSON
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT). 

data/lib/generators/propel_facets/README.md

@@ -0,0 +1,130 @@
+# PropelFacets
+
+A Rails generator that provides a flexible system for defining different JSON representations of ActiveRecord models and automatically connecting them to controller actions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'propel_facets'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install propel_facets
+```
+
+## Usage
+
+Generate the PropelFacets system in your Rails application:
+
+```bash
+$ bin/rails generate propel_facets
+```
+
+This will create:
+
+- `app/models/concerns/model_facet.rb` - Model concern for defining facets
+- `app/controllers/concerns/facet_renderer.rb` - Controller concern for rendering facets
+- `app/controllers/concerns/strong_params_helper.rb` - Enhanced parameter handling
+- `lib/api_params.rb` - API parameter utility class
+- `app/errors/application_error.rb` - Base error class
+- `app/errors/missing_facet.rb` - Facet-specific error class
+- `app/models/application_record.rb` - Base model with default facets (if doesn't exist)
+- `doc/json_facet.md` - Complete documentation
+
+## Quick Start
+
+### In Models
+
+Define different JSON representations using facets:
+
+```ruby
+class User < ApplicationRecord
+  # Basic facet with specific fields
+  json_facet :short, fields: [:name, :email, :created_at]
+  
+  # Extended facet building on another
+  json_facet :details, base: :short, 
+             fields: [:updated_at], 
+             methods: [:full_name], 
+             include: [:posts]
+end
+```
+
+### In Controllers
+
+Connect facets to controller actions:
+
+```ruby
+class UsersController < ApplicationController
+  include FacetRenderer
+  include StrongParamsHelper
+  
+  connect_facet :short, actions: [:index]
+  connect_facet :details, actions: [:show]
+  
+  permitted_params :name, :email, :role
+  
+  def index
+    users = User.all
+    render json: { data: users.map { |u| resource_json(u) } }
+  end
+end
+```
+
+### Parameter Handling
+
+For complex JSON parameters:
+
+```ruby
+class ProductsController < ApplicationController
+  include StrongParamsHelper
+  
+  permitted_params :name, :price, :category
+  permitted_unknown_params :metadata, :settings  # For dynamic JSON structures
+end
+```
+
+## Features
+
+- **Flexible JSON representations** with facet inheritance
+- **Automatic controller-action mapping** 
+- **Strong parameters with JSON support** including complex structures
+- **Active Storage attachment handling**
+- **Comprehensive error handling**
+- **Rails-like conventions** and familiar patterns
+
+## Documentation
+
+After installation, see `doc/json_facet.md` for complete documentation including:
+
+- Advanced facet options
+- Parameter handling patterns
+- Error handling
+- Best practices
+
+## Development
+
+To test the generator:
+
+```bash
+$ cd lib/generators/propel_facets
+$ ruby test/propel_facets_generator_test.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT). 

data/lib/generators/propel_facets/USAGE

@@ -0,0 +1,68 @@
+Description:
+    PropelFacets is a self-extracting generator gem that provides a flexible system for 
+    defining different JSON representations of your ActiveRecord models and automatically 
+    connecting them to controller actions.
+
+Installation:
+    1. Add to Gemfile: gem 'propel_facets', path: 'lib/propel_facets'
+    2. Run: bundle install
+    3. Optionally unpack: bin/rails generate propel_facets:unpack
+    4. Install: bin/rails generate propel_facets:install
+    5. Optionally remove gem from Gemfile (functionality remains)
+
+Example:
+    bin/rails generate propel_facets:install
+
+    This will create:
+        config/initializers/propel_facets.rb     - Configuration file
+        app/models/concerns/model_facet.rb       - Model concern for defining facets
+        app/controllers/concerns/facet_renderer.rb   - Controller concern for rendering facets
+        app/controllers/concerns/strong_params_helper.rb - Enhanced parameter handling
+        lib/api_params.rb                        - API parameter utility class
+        app/errors/application_error.rb          - Base error class
+        app/errors/missing_facet.rb              - Facet-specific error class
+        doc/json_facet.md                        - Complete documentation
+        app/models/application_record.rb         - Base model with default facets (if doesn't exist)
+
+Unpack Generator:
+    bin/rails generate propel_facets:unpack     # Extract generator for customization
+    bin/rails generate propel_facets:unpack --templates-only    # Only templates
+    bin/rails generate propel_facets:unpack --models-only       # Only model templates
+    bin/rails generate propel_facets:unpack --controllers-only  # Only controller templates
+    bin/rails generate propel_facets:unpack --errors-only       # Only error templates
+    bin/rails generate propel_facets:unpack --lib-only          # Only lib templates
+    bin/rails generate propel_facets:unpack --docs-only         # Only documentation
+
+Quick Start Usage:
+    In models, define facets for different JSON representations:
+        class User < ApplicationRecord
+          json_facet :summary, fields: [:id, :name, :email]
+          json_facet :details, base: :summary, fields: [:created_at], methods: [:full_name]
+        end
+
+    In controllers, connect facets to actions:
+        class UsersController < ApplicationController
+        include FacetRenderer
+          include StrongParamsHelper
+          
+          connect_facet :summary, actions: [:index]
+        connect_facet :details, actions: [:show]
+
+        permitted_params :name, :email, :role
+        end
+
+Configuration:
+    Configure in config/initializers/propel_facets.rb:
+        PropelFacets.configure do |config|
+          config.root = :data              # JSON root structure
+          config.api_format = :rest        # API format standard
+          config.strict_mode = false       # Error handling mode
+        end
+
+Self-Extracting Architecture:
+    PropelFacets is designed to be installed temporarily, extract its functionality 
+    into your application, then be removed. This ensures:
+    - No runtime gem dependencies
+    - Full control over all generated code
+    - Easy customization of all components
+    - Standard Rails patterns throughout