jpie 0.3.1 → 0.4.1

data/README.md

@@ -10,11 +10,14 @@ JPie is a modern, lightweight Rails library for developing JSON:API compliant se
 ✨ **Modern Rails DSL** - Clean, intuitive syntax following Rails conventions  
 🔧 **Method Overrides** - Define custom attribute methods directly on resource classes  
 🎯 **Smart Inference** - Automatic model and resource class detection  
+⚡ **Powerful Generators** - Scaffold resources with relationships, meta attributes, and automatic inference  
 📊 **Polymorphic Support** - Full support for complex polymorphic associations  
 🔄 **STI Ready** - Single Table Inheritance works out of the box  
+🔗 **Through Associations** - Full support for Rails `:through` associations  
 ⚡ **Performance Optimized** - Efficient serialization with intelligent deduplication  
 🛡️ **Authorization Ready** - Built-in scoping support for security  
 📋 **JSON:API Compliant** - Full specification compliance with sorting, includes, and meta  
+🚨 **Robust Error Handling** - Smart inheritance-aware error handling with full customization options
 
 ## Installation
 
@@ -24,9 +27,9 @@ Add JPie to your Rails application:
 bundle add jpie
 ```
 
-## Quick Start - Default Implementation
+## Quick Start
 
-JPie works out of the box with minimal configuration. Here's a complete example of the default implementation:
+JPie works out of the box with minimal configuration:
 
 ### 1. Create Your Model
 
@@ -34,6 +37,9 @@ JPie works out of the box with minimal configuration. Here's a complete example
 class User < ActiveRecord::Base
   validates :name, presence: true
   validates :email, presence: true, uniqueness: true
+  
+  has_many :posts, dependent: :destroy
+  has_one :profile, dependent: :destroy
 end
 ```
 
@@ -42,6 +48,10 @@ end
 ```ruby
 class UserResource < JPie::Resource
   attributes :name, :email
+  meta_attributes :created_at, :updated_at
+  
+  has_many :posts
+  has_one :profile
 end
 ```
 
@@ -61,971 +71,296 @@ Rails.application.routes.draw do
 end
 ```
 
-That's it! You now have a fully functional JSON:API compliant server.
-
-## Modern DSL Examples
-
-JPie provides a clean, modern DSL that follows Rails conventions:
-
-### Resource Definition
-
-```ruby
-class UserResource < JPie::Resource
-  # Attributes (multiple syntaxes supported)
-  attributes :name, :email, :created_at
-  attribute :full_name
-  
-  # Meta attributes
-  meta :account_status, :last_login
-  # or: meta_attributes :account_status, :last_login
-  
-  # Relationships
-  has_many :posts
-  has_one :profile
-  
-  # Custom sorting
-  sortable :popularity do |query, direction|
-    query.order(likes_count: direction)
-  end
-  # or: sortable_by :popularity do |query, direction|
-  
-  # Custom attribute methods
-  private
-  
-  def full_name
-    "#{object.first_name} #{object.last_name}"
-  end
-  
-  def account_status
-    object.active? ? 'active' : 'inactive'
-  end
-end
-```
-
-### Controller Definition
-
-```ruby
-class UsersController < ApplicationController
-  include JPie::Controller
-  
-  # Explicit resource (optional - auto-inferred by default)
-  resource UserResource
-  # or: jsonapi_resource UserResource
-  
-  # Override methods as needed
-  def index
-    users = current_user.admin? ? User.all : User.active
-    render_jsonapi(users)
-  end
-  
-  def create
-    user = User.new(deserialize_params)
-    user.created_by = current_user
-    user.save!
-    
-    render_jsonapi(user, status: :created)
-  end
-end
-```
-
-## Suported JSON:API features
+That's it! You now have a fully functional JSON:API compliant server with automatic CRUD operations, sorting, includes, and validation.
 
-### Sorting
-All defined attributes are automatically sortable:
+## 📚 Comprehensive Examples
 
-```http
-GET /users?sort=name
-HTTP/1.1 200 OK
-Content-Type: application/vnd.api+json
-{
-  "data": [
-    {
-      "id": "1",
-      "type": "users", 
-      "attributes": {
-        "name": "Alice Anderson",
-        "email": "alice@example.com"
-      }
-    },
-    {
-      "id": "2", 
-      "type": "users",
-      "attributes": {
-        "name": "Bob Brown",
-        "email": "bob@example.com"
-      }
-    },
-    {
-      "id": "3",
-      "type": "users", 
-      "attributes": {
-        "name": "Carol Clark",
-        "email": "carol@example.com"
-      }
-    }
-  ]
-}
-```
+JPie includes a complete set of examples demonstrating all features:
 
-Or by name in reverse order by name:
+- **[🚀 Basic Usage](https://github.com/emilkampp/jpie/blob/main/examples/basic_usage.rb)** - Fundamental setup and configuration
+- **[🔗 Through Associations](https://github.com/emilkampp/jpie/blob/main/examples/through_associations.rb)** - Many-to-many relationships with `:through`
+- **[🎨 Custom Attributes & Meta](https://github.com/emilkampp/jpie/blob/main/examples/custom_attributes_and_meta.rb)** - Custom computed attributes and meta data
+- **[🔄 Polymorphic Associations](https://github.com/emilkampp/jpie/blob/main/examples/polymorphic_associations.rb)** - Complex polymorphic relationships
+- **[🏗️ Single Table Inheritance](https://github.com/emilkampp/jpie/blob/main/examples/single_table_inheritance.rb)** - STI models and resources
+- **[📊 Custom Sorting](https://github.com/emilkampp/jpie/blob/main/examples/custom_sorting.rb)** - Advanced sorting with complex algorithms
+- **[⚠️ Error Handling](https://github.com/emilkampp/jpie/blob/main/examples/error_handling.rb)** - Comprehensive error handling strategies
 
-```http
-GET /users?sort=-name
-HTTP/1.1 200 OK
-Content-Type: application/vnd.api+json
-{
-  "data": [
-    {
-      "id": "3",
-      "type": "users",
-      "attributes": {
-        "name": "Carol Clark", 
-        "email": "carol@example.com"
-      }
-    },
-    {
-      "id": "2",
-      "type": "users",
-      "attributes": {
-        "name": "Bob Brown",
-        "email": "bob@example.com"
-      }
-    },
-    {
-      "id": "1",
-      "type": "users",
-      "attributes": {
-        "name": "Alice Anderson",
-        "email": "alice@example.com"
-      }
-    }
-  ]
-}
-```
+Each example is self-contained with models, resources, controllers, and sample API requests/responses. **[📋 View all examples →](https://github.com/emilkampp/jpie/blob/main/examples/)**
 
-## Customization and Overrides
+## Generators
 
-Once you have the basic implementation working, you can customize JPie's behavior as needed:
+JPie includes a resource generator for quickly creating new resource classes:
 
-### Resource Class Inference Override
+### Basic Usage
 
-JPie automatically infers the resource class from your controller name, but you can override this:
+```bash
+# Generate a basic resource with semantic syntax
+rails generate jpie:resource User attribute:name attribute:email meta:created_at
 
-```ruby
-# Automatic inference (default behavior)
-class UsersController < ApplicationController
-  include JPie::Controller
-  # Automatically uses UserResource
-end
+# Shorthand for relationships
+rails generate jpie:resource Post attribute:title attribute:content has_many:comments has_one:author
 
-# Explicit resource specification (override)
-class UsersController < ApplicationController
-  include JPie::Controller
-  resource UserResource  # Use a different resource class (modern syntax)
-  # or: jsonapi_resource UserResource  # (backward compatible syntax)
-end
+# Mix explicit categorization with auto-detection
+rails generate jpie:resource User attribute:name email created_at updated_at
 ```
 
-### Model Specification Override
-
-JPie automatically infers the model from your resource class name, but you can override this:
-
+**Generated file:**
 ```ruby
-# Automatic inference (default behavior)
-class UserResource < JPie::Resource
-  attributes :name, :email
-  # Automatically uses User model
-end
-
-# Explicit model specification (override)
 class UserResource < JPie::Resource
-  model CustomUser  # Use a different model class
   attributes :name, :email
-end
-```
-
-### Controller Method Overrides
-
-You can override any of the automatic CRUD methods:
-
-```ruby
-class UsersController < ApplicationController
-  include JPie::Controller
-  
-  # Override index to add filtering
-  def index
-    users = User.where(active: true)
-    render_jsonapi(users)
-  end
-  
-  # Override create to add custom logic
-  def create
-    attributes = deserialize_params
-    user = User.new(attributes)
-    user.created_by = current_user
-    user.save!
-    
-    render_jsonapi(user, status: :created)
-  end
+  meta_attributes :created_at, :updated_at
   
-  # show, update, destroy still use the automatic implementations
+  has_many :comments
+  has_one :author
 end
 ```
 
-### Custom Attributes
-
-Add computed or transformed attributes to your resources using either blocks or method overrides:
-
-#### Using Blocks (Original Approach)
-
-```ruby
-class UserResource < JPie::Resource
-  attribute :display_name do
-    "#{object.first_name} #{object.last_name}"
-  end
-
-  attribute :admin_notes do
-    if context[:current_user]&.admin?
-      object.admin_notes
-    else
-      nil
-    end
-  end
-end
-```
+### Semantic Field Syntax
 
-#### Using Method Overrides (New Approach)
+| Syntax | Purpose | Example |
+|--------|---------|---------|
+| `attribute:field` | Regular JSON:API attribute | `attribute:name` |
+| `meta:field` | JSON:API meta attribute | `meta:created_at` |
+| `has_many:resource` | JSON:API relationship | `has_many:posts` |
+| `has_one:resource` | JSON:API relationship | `has_one:profile` |
 
-You can now define custom methods directly on your resource class instead of using blocks:
+### Generator Options
 
-```ruby
-class UserResource < JPie::Resource
-  attributes :name, :email
-  attribute :full_name
-  attribute :display_name
-  meta_attribute :user_stats
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--model=NAME` | Specify model class | `--model=Person` |
+| `--skip-model` | Skip explicit model declaration | `--skip-model` |
 
-  private
+## Core Features
 
-  def full_name
-    "#{object.first_name} #{object.last_name}"
-  end
+### JSON:API Compliance
 
-  def display_name
-    if context[:admin]
-      "#{full_name} [ADMIN VIEW] - #{object.email}"
-    else
-      full_name
-    end
-  end
+JPie automatically handles all JSON:API specification requirements:
 
-  def user_stats
-    {
-      name_length: object.name.length,
-      email_domain: object.email.split('@').last,
-      account_status: object.active? ? 'active' : 'inactive'
-    }
-  end
-end
+#### Sorting
+```http
+GET /users?sort=name,-created_at
 ```
 
-**Key Benefits of Method Overrides:**
-- **Cleaner syntax** - No need for blocks
-- **Better IDE support** - Full method definitions with proper syntax highlighting
-- **Easier testing** - Methods can be tested individually
-- **Private methods supported** - Use private methods for internal logic
-- **Access to object and context** - Full access to `object` and `context` like blocks
-
-**Method Precedence:**
-1. **Blocks** (highest priority) - `attribute :name do ... end`
-2. **Options blocks** - `attribute :name, block: proc { ... }`
-3. **Custom methods** - `def name; ...; end`
-4. **Model attributes** (lowest priority) - Direct model attribute lookup
-
-### Meta attributes
-
-JPie supports adding meta data to your JSON:API resources in two ways: using the `meta_attributes` macro or by defining a custom `meta` method.
+#### Includes
+```http
+GET /posts?include=author,comments,comments.author
+```
 
-#### Using meta_attributes Macro
+#### Validation
+- Request structure validation for POST/PATCH operations
+- Include parameter validation  
+- Sort parameter validation with clear error messages
 
-It's easy to add meta attributes:
+### Modern DSL
 
 ```ruby
 class UserResource < JPie::Resource
-  meta_attributes :created_at, :updated_at
-  meta_attributes :last_login_at
+  # Multiple attributes at once
+  attributes :name, :email, :created_at
+  
+  # Meta attributes (for additional data)
+  meta :account_status, :last_login
+  
+  # Relationships for includes
+  has_many :posts
+  has_one :profile
+  
+  # Custom sorting
+  sortable :popularity do |query, direction|
+    query.order(likes_count: direction)
+  end
+  
+  # Custom attribute methods (modern approach)
+  private
+  
+  def account_status
+    object.active? ? 'active' : 'inactive'
+  end
 end
 ```
 
-#### Using Custom meta Method
+### Through Associations
 
-For more complex meta data, you can define a `meta` method that returns a hash:
+JPie seamlessly supports Rails `:through` associations:
 
 ```ruby
-class UserResource < JPie::Resource
-  attributes :name, :email
-  meta_attributes :created_at, :updated_at
-
-  def meta
-    super.merge(
-      full_name: "#{object.first_name} #{object.last_name}",
-      user_role: context[:current_user]&.role || 'guest',
-      account_status: object.active? ? 'active' : 'inactive',
-      last_seen: object.last_login_at&.iso8601
-    )
-  end
+class CarResource < JPie::Resource
+  attributes :make, :model, :year
+  
+  # JPie handles the through association automatically
+  has_many :drivers, through: :car_drivers
 end
 ```
 
-The `meta` method has access to:
-- `super` - returns the hash from `meta_attributes` 
-- `object` - the underlying model instance
-- `context` - any context passed during resource initialization
-
-**Example JSON:API Response with Custom Meta:**
-
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "users",
-    "attributes": {
-      "name": "John Doe",
-      "email": "john@example.com"
-    },
-    "meta": {
-      "created_at": "2024-01-01T12:00:00Z",
-      "updated_at": "2024-01-15T14:30:00Z",
-      "full_name": "John Doe",
-      "user_role": "admin",
-      "account_status": "active",
-      "last_seen": "2024-01-15T14:00:00Z"
-    }
-  }
-}
-```
+The join table is completely hidden from the API response, providing a clean interface.
 
-#### Meta Method Inheritance
+### Custom Attributes
 
-Meta methods work seamlessly with inheritance:
+Define custom computed attributes using method overrides:
 
 ```ruby
-class BaseResource < JPie::Resource
-  meta_attributes :created_at, :updated_at
-
-  def meta
-    super.merge(
-      resource_version: '1.0',
-      timestamp: Time.current.iso8601
-    )
-  end
-end
-
-class UserResource < BaseResource
-  attributes :name, :email
-  meta_attributes :last_login_at
-
-  def meta
-    super.merge(
-      user_specific_data: calculate_user_metrics
-    )
-  end
-
+class UserResource < JPie::Resource
+  attributes :first_name, :last_name
+  attribute :full_name
+  
   private
-
-  def calculate_user_metrics
-    {
-      post_count: object.posts.count,
-      comment_count: object.comments.count
-    }
+  
+  def full_name
+    "#{object.first_name} #{object.last_name}"
   end
 end
 ```
 
-### Custom Sorting
+### Authorization & Context
 
-Override the default sorting behavior with custom logic:
+Pass context for authorization-aware responses:
 
 ```ruby
-class PostResource < JPie::Resource
-  attributes :title, :content
+class UsersController < ApplicationController
+  include JPie::Controller
   
-  sortable_by :popularity do |query, direction|
-    if direction == :asc
-      query.order(:likes_count, :comments_count)
-    else
-      query.order(likes_count: :desc, comments_count: :desc)
-    end
+  def show
+    user = User.find(params[:id])
+    render_jsonapi(user, context: { current_user: current_user })
   end
 end
 ```
 
-### Polymorphic Associations
+## Error Handling
 
-JPie supports polymorphic associations seamlessly. Here's a complete example with comments that can belong to multiple types of commentable resources:
+JPie provides robust error handling with full customization options:
 
-#### Models with Polymorphic Associations
+### Default Error Handling
 
-```ruby
-# Comment model with belongs_to polymorphic association
-class Comment < ActiveRecord::Base
-  belongs_to :commentable, polymorphic: true
-  belongs_to :author, class_name: 'User'
-  
-  validates :content, presence: true
-end
+JPie automatically handles common errors:
 
-# Post model with has_many polymorphic association
-class Post < ActiveRecord::Base
-  has_many :comments, as: :commentable, dependent: :destroy
-  belongs_to :author, class_name: 'User'
-  
-  validates :title, :content, presence: true
-end
+| Error Type | HTTP Status | Description |
+|------------|-------------|-------------|
+| `JPie::Errors::Error` | Varies | Base JPie errors with custom status |
+| `ActiveRecord::RecordNotFound` | 404 | Missing records |
+| `ActiveRecord::RecordInvalid` | 422 | Validation failures |
 
-# Article model with has_many polymorphic association  
-class Article < ActiveRecord::Base
-  has_many :comments, as: :commentable, dependent: :destroy
-  belongs_to :author, class_name: 'User'
-  
-  validates :title, :body, presence: true
-end
-```
+### Customization Options
 
-#### Resources for Polymorphic Associations
+#### Override Specific Handlers
 
 ```ruby
-# Comment resource with belongs_to polymorphic relationship
-class CommentResource < JPie::Resource
-  attributes :content, :created_at
-  
-  # Polymorphic belongs_to relationship
-  relationship :commentable do
-    # Dynamically determine the resource class based on the commentable type
-    case object.commentable_type
-    when 'Post'
-      PostResource.new(object.commentable, context)
-    when 'Article'
-      ArticleResource.new(object.commentable, context)
-    else
-      nil
-    end
-  end
-  
-  relationship :author do
-    UserResource.new(object.author, context) if object.author
-  end
-end
-
-# Post resource with has_many polymorphic relationship
-class PostResource < JPie::Resource
-  attributes :title, :content, :published_at
-  
-  # Has_many polymorphic relationship
-  relationship :comments do
-    object.comments.map { |comment| CommentResource.new(comment, context) }
-  end
-  
-  relationship :author do
-    UserResource.new(object.author, context) if object.author
-  end
-end
-
-# Article resource with has_many polymorphic relationship
-class ArticleResource < JPie::Resource
-  attributes :title, :body, :published_at
-  
-  # Has_many polymorphic relationship
-  relationship :comments do
-    object.comments.map { |comment| CommentResource.new(comment, context) }
-  end
+class ApplicationController < ActionController::Base
+  # Define your handlers first
+  rescue_from ActiveRecord::RecordNotFound, with: :my_not_found_handler
   
-  relationship :author do
-    UserResource.new(object.author, context) if object.author
-  end
+  include JPie::Controller
+  # JPie will detect existing handler and won't override it
 end
 ```
 
-#### Controllers for Polymorphic Resources
+#### Extend JPie Handlers
 
 ```ruby
-class CommentsController < ApplicationController
+class ApplicationController < ActionController::Base
   include JPie::Controller
   
-  # Override create to handle polymorphic assignment
-  def create
-    attributes = deserialize_params
-    commentable = find_commentable
-    
-    comment = commentable.comments.build(attributes)
-    comment.author = current_user
-    comment.save!
-    
-    render_jsonapi_resource(comment, status: :created)
-  end
-  
   private
   
-  def find_commentable
-    # Extract commentable info from request path or parameters
-    if params[:post_id]
-      Post.find(params[:post_id])
-    elsif params[:article_id]
-      Article.find(params[:article_id])
-    else
-      raise ArgumentError, "Commentable not specified"
-    end
+  def render_jpie_validation_error(error)
+    # Add custom logging
+    Rails.logger.error "Validation failed: #{error.message}"
+    
+    # Call the original method or implement your own
+    super
   end
 end
-
-class PostsController < ApplicationController
-  include JPie::Controller
-  # Uses default CRUD operations with polymorphic comments included
-end
-
-class ArticlesController < ApplicationController
-  include JPie::Controller
-  # Uses default CRUD operations with polymorphic comments included
-end
 ```
 
-#### Routes for Polymorphic Resources
+#### Disable All JPie Error Handlers
 
 ```ruby
-Rails.application.routes.draw do
-  resources :posts do
-    resources :comments, only: [:index, :create]
-  end
+class ApplicationController < ActionController::Base
+  include JPie::Controller
   
-  resources :articles do
-    resources :comments, only: [:index, :create]
-  end
+  disable_jpie_error_handlers
   
-  resources :comments, only: [:show, :update, :destroy]
-end
-```
-
-#### Example JSON:API Responses
-
-**GET /posts/1?include=comments,comments.author**
-
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "posts",
-    "attributes": {
-      "title": "My First Post",
-      "content": "This is the content of my first post.",
-      "published_at": "2024-01-15T10:30:00Z"
-    },
-    "relationships": {
-      "comments": {
-        "data": [
-          { "id": "1", "type": "comments" },
-          { "id": "2", "type": "comments" }
-        ]
-      }
-    }
-  },
-  "included": [
-    {
-      "id": "1",
-      "type": "comments",
-      "attributes": {
-        "content": "Great post!",
-        "created_at": "2024-01-15T11:00:00Z"
-      },
-      "relationships": {
-        "commentable": {
-          "data": { "id": "1", "type": "posts" }
-        },
-        "author": {
-          "data": { "id": "5", "type": "users" }
-        }
-      }
-    },
-    {
-      "id": "2", 
-      "type": "comments",
-      "attributes": {
-        "content": "Thanks for sharing!",
-        "created_at": "2024-01-15T12:00:00Z"
-      },
-      "relationships": {
-        "commentable": {
-          "data": { "id": "1", "type": "posts" }
-        },
-        "author": {
-          "data": { "id": "6", "type": "users" }
-        }
-      }
-    }
-  ]
-}
-```
-
-### Single Table Inheritance (STI)
-
-JPie provides comprehensive support for Rails Single Table Inheritance (STI) models. STI allows multiple models to share a single database table with a "type" column to differentiate between them.
-
-#### STI Models
-
-```ruby
-# Base model
-class Vehicle < ActiveRecord::Base
-  validates :name, presence: true
-  validates :brand, presence: true
-  validates :year, presence: true
-end
-
-# STI subclasses
-class Car < Vehicle
-  validates :engine_size, presence: true
-end
-
-class Truck < Vehicle
-  validates :cargo_capacity, presence: true
-end
-```
-
-#### STI Resources
-
-JPie automatically handles STI type inference and resource inheritance:
-
-```ruby
-# Base resource
-class VehicleResource < JPie::Resource
-  attributes :name, :brand, :year
-  meta_attributes :created_at, :updated_at
-end
-
-# STI resources inherit from base resource
-class CarResource < VehicleResource
-  attributes :engine_size  # Car-specific attribute
+  # Define your own handlers
+  rescue_from StandardError, with: :handle_standard_error
 end
-
-class TruckResource < VehicleResource
-  attributes :cargo_capacity  # Truck-specific attribute
-end
-```
-
-#### STI Type Inference
-
-JPie automatically infers the correct JSON:API type from the STI model class:
-
-```ruby
-car = Car.create!(name: 'Civic', brand: 'Honda', year: 2020, engine_size: 1500)
-car_resource = CarResource.new(car)
-
-car_resource.type  # => "cars" (automatically inferred from Car model)
-```
-
-#### STI Serialization
-
-Each STI model serializes with its specific type and attributes:
-
-```ruby
-# Car serialization
-car_serializer = JPie::Serializer.new(CarResource)
-result = car_serializer.serialize(car)
-
-# Result:
-{
-  "data": {
-    "id": "1",
-    "type": "cars",  # STI type
-    "attributes": {
-      "name": "Civic",
-      "brand": "Honda", 
-      "year": 2020,
-      "engine_size": 1500  # Car-specific attribute
-    }
-  }
-}
-
-# Truck serialization  
-truck_serializer = JPie::Serializer.new(TruckResource)
-result = truck_serializer.serialize(truck)
-
-# Result:
-{
-  "data": {
-    "id": "2", 
-    "type": "trucks",  # STI type
-    "attributes": {
-      "name": "F-150",
-      "brand": "Ford",
-      "year": 2021,
-      "cargo_capacity": 1000  # Truck-specific attribute
-    }
-  }
-}
 ```
 
-#### STI Controllers
-
-Controllers work seamlessly with STI models:
+### Custom JPie Errors
 
 ```ruby
-class CarsController < ApplicationController
-  include JPie::Controller
-  # Automatically uses CarResource and Car model
-end
-
-class TrucksController < ApplicationController
-  include JPie::Controller  
-  # Automatically uses TruckResource and Truck model
-end
-
-class VehiclesController < ApplicationController
-  include JPie::Controller
-  # Uses VehicleResource and returns all vehicles (cars, trucks, etc.)
+class CustomBusinessError < JPie::Errors::Error
+  def initialize(detail: 'Business logic error')
+    super(status: 422, title: 'Business Error', detail: detail)
+  end
 end
-```
-
-#### STI Scoping
-
-Each STI resource automatically scopes to its specific type:
-
-```ruby
-CarResource.scope      # Returns only Car records
-TruckResource.scope    # Returns only Truck records  
-VehicleResource.scope  # Returns all Vehicle records (including STI subclasses)
-```
-
-#### STI in Polymorphic Relationships
 
-JPie's serializer automatically determines the correct resource class for STI models in polymorphic relationships:
-
-```ruby
-# If a polymorphic relationship returns STI objects,
-# JPie will automatically use the correct resource class
-# (CarResource for Car objects, TruckResource for Truck objects, etc.)
+# Use in controllers
+raise CustomBusinessError.new(detail: 'Custom validation failed')
 ```
 
-#### Complete STI Example
+## Advanced Features
 
-Here's a complete example showing STI in action with HTTP requests and responses:
+### Polymorphic Associations
 
-**1. Database Setup**
+JPie supports polymorphic associations for complex data relationships:
 
 ```ruby
-# Migration
-class CreateVehicles < ActiveRecord::Migration[7.0]
-  def change
-    create_table :vehicles do |t|
-      t.string :type, null: false  # STI discriminator column
-      t.string :name, null: false
-      t.string :brand, null: false
-      t.integer :year, null: false
-      t.integer :engine_size       # Car-specific
-      t.integer :cargo_capacity    # Truck-specific
-      t.timestamps
-    end
-    
-    add_index :vehicles, :type
+class CommentResource < JPie::Resource
+  attributes :content
+  has_one :author
+  
+  # Polymorphic commentable (posts, articles, videos, etc.)
+  private
+  
+  def author
+    object.author
   end
 end
 ```
 
-**2. Models**
-
-```ruby
-class Vehicle < ApplicationRecord
-  validates :name, :brand, :year, presence: true
-end
-
-class Car < Vehicle
-  validates :engine_size, presence: true
-end
+### Single Table Inheritance
 
-class Truck < Vehicle  
-  validates :cargo_capacity, presence: true
-end
-```
-
-**3. Resources**
+JPie automatically handles STI models:
 
 ```ruby
+# Base resource
 class VehicleResource < JPie::Resource
   attributes :name, :brand, :year
-  meta_attributes :created_at, :updated_at
 end
 
+# STI resources inherit automatically
 class CarResource < VehicleResource
-  attributes :engine_size
-end
-
-class TruckResource < VehicleResource
-  attributes :cargo_capacity
+  attributes :engine_size, :doors  # Car-specific attributes
 end
 ```
 
-**4. Controllers**
-
-```ruby
-class VehiclesController < ApplicationController
-  include JPie::Controller
-  # Returns all vehicles (cars, trucks, etc.)
-end
-
-class CarsController < ApplicationController
-  include JPie::Controller
-  # Returns only cars with car-specific attributes
-end
+STI types are automatically inferred in JSON:API responses.
 
-class TrucksController < ApplicationController
-  include JPie::Controller
-  # Returns only trucks with truck-specific attributes
-end
-```
-
-**5. Routes**
-
-```ruby
-Rails.application.routes.draw do
-  resources :vehicles, only: [:index, :show]
-  resources :cars
-  resources :trucks
-end
-```
-
-**6. Example HTTP Requests and Responses**
-
-**GET /cars/1**
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "cars",
-    "attributes": {
-      "name": "Model 3",
-      "brand": "Tesla", 
-      "year": 2023,
-      "engine_size": 0
-    },
-    "meta": {
-      "created_at": "2024-01-15T10:00:00Z",
-      "updated_at": "2024-01-15T10:00:00Z"
-    }
-  }
-}
-```
-
-**GET /trucks/2**
-```json
-{
-  "data": {
-    "id": "2", 
-    "type": "trucks",
-    "attributes": {
-      "name": "F-150",
-      "brand": "Ford",
-      "year": 2023,
-      "cargo_capacity": 1200
-    },
-    "meta": {
-      "created_at": "2024-01-15T11:00:00Z",
-      "updated_at": "2024-01-15T11:00:00Z"
-    }
-  }
-}
-```
-
-**GET /vehicles (Mixed STI Collection)**
-```json
-{
-  "data": [
-    {
-      "id": "1",
-      "type": "cars",
-      "attributes": {
-        "name": "Model 3",
-        "brand": "Tesla",
-        "year": 2023,
-        "engine_size": 0
-      }
-    },
-    {
-      "id": "2",
-      "type": "trucks", 
-      "attributes": {
-        "name": "F-150",
-        "brand": "Ford",
-        "year": 2023,
-        "cargo_capacity": 1200
-      }
-    }
-  ]
-}
-```
-
-**7. Creating STI Records**
-
-**POST /cars**
-```json
-{
-  "data": {
-    "type": "cars",
-    "attributes": {
-      "name": "Model Y",
-      "brand": "Tesla",
-      "year": 2024,
-      "engine_size": 0
-    }
-  }
-}
-```
-
-#### Custom STI Types
-
-You can override the automatic type inference if needed:
-
-```ruby
-class CarResource < VehicleResource
-  type 'automobiles'  # Custom type instead of 'cars'
-  attributes :engine_size
-end
-```
-
-### Authorization and Scoping
+### Custom Sorting
 
-Override the default scope method to add authorization:
+Implement complex sorting logic:
 
 ```ruby
-class PostResource < JPie::Resource  
-  attributes :title, :content
-  
-  def self.scope(context = {})
-    current_user = context[:current_user]
-    return model.none unless current_user
-    Pundit.policy_scope(current_user, model)
+class PostResource < JPie::Resource
+  sortable :popularity do |query, direction|
+    query.joins(:likes, :comments)
+         .group('posts.id')
+         .order("COUNT(likes.id) + COUNT(comments.id) #{direction.to_s.upcase}")
   end
 end
 ```
 
-### Custom Context
+## Performance & Best Practices
 
-Override the context building to pass additional data to resources:
+- **Efficient serialization** with automatic deduplication
+- **Smart includes** with optimized queries
+- **Validation caching** for improved performance
+- **Error handling** that doesn't impact performance
 
-```ruby
-class UsersController < ApplicationController
-  include JPie::Controller
-  
-  private
-  
-  def build_context
-    {
-      current_user: current_user,
-      controller: self,
-      action: action_name,
-      request_ip: request.remote_ip,
-      user_agent: request.user_agent
-    }
-  end
-end
-```
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/emilkampp/jpie.
 
 ## License