jpie 0.4.0 → 0.4.1

data/README.md

@@ -13,9 +13,11 @@ JPie is a modern, lightweight Rails library for developing JSON:API compliant se
 ⚡ **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
 
@@ -25,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
 
@@ -35,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
 ```
 
@@ -43,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
 ```
 
@@ -62,16 +71,28 @@ Rails.application.routes.draw do
 end
 ```
 
-That's it! You now have a fully functional JSON:API compliant server.
+That's it! You now have a fully functional JSON:API compliant server with automatic CRUD operations, sorting, includes, and validation.
+
+## 📚 Comprehensive Examples
+
+JPie includes a complete set of examples demonstrating all features:
+
+- **[🚀 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
+
+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/)**
 
 ## Generators
 
-JPie includes a resource generator for quickly creating new resource classes with proper JSON:API structure.
+JPie includes a resource generator for quickly creating new resource classes:
 
 ### Basic Usage
 
-The generator uses semantic field definitions that explicitly categorize each field by its JSON:API purpose:
-
 ```bash
 # Generate a basic resource with semantic syntax
 rails generate jpie:resource User attribute:name attribute:email meta:created_at
@@ -85,13 +106,10 @@ rails generate jpie:resource User attribute:name email created_at updated_at
 
 **Generated file:**
 ```ruby
-# frozen_string_literal: true
-
 class UserResource < JPie::Resource
   attributes :name, :email
-
   meta_attributes :created_at, :updated_at
-
+  
   has_many :comments
   has_one :author
 end
@@ -99,122 +117,52 @@ end
 
 ### Semantic Field Syntax
 
-The generator uses a semantic approach focused on JSON:API concepts rather than database types:
-
 | 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` |
-| `relationship:type:resource` | Explicit relationship | `relationship:has_many:posts` |
-
-### Advanced Examples
-
-##### Comprehensive Resource
-
-```bash
-rails generate jpie:resource Article \
-  attribute:title \
-  attribute:content \
-  meta:published_at \
-  meta:created_at \
-  meta:updated_at \
-  has_one:author \
-  has_many:comments \
-  has_many:tags \
-  --model=Post
-```
-
-**Generated file:**
-```ruby
-# frozen_string_literal: true
-
-class ArticleResource < JPie::Resource
-  model Post
 
-  attributes :title, :content
-
-  meta_attributes :published_at, :created_at, :updated_at
-
-  has_one :author
-  has_many :comments
-  has_many :tags
-end
-```
+### Generator Options
 
-##### Empty Resource Template
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--model=NAME` | Specify model class | `--model=Person` |
+| `--skip-model` | Skip explicit model declaration | `--skip-model` |
 
-```bash
-rails generate jpie:resource User
-```
+## Core Features
 
-**Generated file:**
-```ruby
-# frozen_string_literal: true
+### JSON:API Compliance
 
-class UserResource < JPie::Resource
-  # Define your attributes here:
-  # attributes :name, :email, :title
+JPie automatically handles all JSON:API specification requirements:
 
-  # Define your meta attributes here:
-  # meta_attributes :created_at, :updated_at
-
-  # Define your relationships here:
-  # has_many :posts
-  # has_one :user
-end
+#### Sorting
+```http
+GET /users?sort=name,-created_at
 ```
 
-### Legacy Syntax Support
-
-The generator maintains backward compatibility with the Rails-style `field:type` syntax, but ignores the type portion:
-
-```bash
-# Legacy syntax (still works, types ignored)
-rails generate jpie:resource User name:string email:string created_at:datetime
+#### Includes
+```http
+GET /posts?include=author,comments,comments.author
 ```
 
-This generates the same output as the semantic syntax, with automatic detection of meta attributes based on common field names.
-
-### Generator Options
-
-| Option | Type | Description | Example |
-|--------|------|-------------|---------|
-| `--model=NAME` | String | Specify model class (overrides inference) | `--model=Person` |
-| `--skip-model` | Boolean | Skip explicit model declaration | `--skip-model` |
+#### Validation
+- Request structure validation for POST/PATCH operations
+- Include parameter validation  
+- Sort parameter validation with clear error messages
 
-### Automatic Features
-
-- **Model Inference**: Automatically infers model class from resource name
-- **Resource Inference**: Automatically infers related resource classes for relationships
-- **Meta Detection**: Auto-detects common meta attributes (`created_at`, `updated_at`, etc.)
-- **Clean Output**: Generates well-structured, commented resource files
-
-### Best Practices
-
-1. **Use semantic syntax** for clarity and JSON:API-appropriate thinking
-2. **Be explicit about categorization** when the intent might be unclear
-3. **Let JPie handle inference** for standard naming conventions
-4. **Use `--model` only when necessary** for non-standard model mappings
-
-## Modern DSL Examples
-
-JPie provides a clean, modern DSL that follows Rails conventions:
-
-### Resource Definition
+### Modern DSL
 
 ```ruby
 class UserResource < JPie::Resource
-  # Attributes (multiple syntaxes supported)
+  # Multiple attributes at once
   attributes :name, :email, :created_at
-  attribute :full_name
   
-  # Meta attributes
+  # Meta attributes (for additional data)
   meta :account_status, :last_login
-  # or: meta_attributes :account_status, :last_login
   
-  # Includes for related data (used with ?include= parameter)
+  # Relationships for includes
   has_many :posts
   has_one :profile
   
@@ -222,971 +170,197 @@ class UserResource < JPie::Resource
   sortable :popularity do |query, direction|
     query.order(likes_count: direction)
   end
-  # or: sortable_by :popularity do |query, direction|
   
-  # Custom attribute methods
+  # Custom attribute methods (modern approach)
   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
-    attributes = deserialize_params
-    user = model_class.new(attributes)
-    user.created_by = current_user
-    user.save!
-    
-    render_jsonapi(user, status: :created)
-  end
-end
-```
-
-## Suported JSON:API features
-
-### Sorting
-All defined attributes are automatically sortable:
-
-```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"
-      }
-    }
-  ]
-}
-```
-
-Or by name in reverse order by name:
+### Through Associations
 
-```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"
-      }
-    }
-  ]
-}
-```
-
-### Includes
-
-JPie supports including related resources using the `?include=` parameter. Related resources are returned in the `included` section of the JSON:API response:
-
-```http
-GET /posts/1?include=author
-HTTP/1.1 200 OK
-Content-Type: application/vnd.api+json
-{
-  "data": {
-    "id": "1",
-    "type": "posts",
-    "attributes": {
-      "title": "My First Post",
-      "content": "This is the content of my first post."
-    }
-  },
-  "included": [
-    {
-      "id": "5",
-      "type": "users",
-      "attributes": {
-        "name": "John Doe",
-        "email": "john@example.com"
-      }
-    }
-  ]
-}
-```
-
-Multiple includes and nested includes are also supported:
-
-```http
-GET /posts?include=author,comments,comments.author
-```
-
-## Customization and Overrides
-
-Once you have the basic implementation working, you can customize JPie's behavior as needed:
-
-### Resource Class Inference Override
-
-JPie automatically infers the resource class from your controller name, but you can override this:
+JPie seamlessly supports Rails `:through` associations:
 
 ```ruby
-# Automatic inference (default behavior)
-class UsersController < ApplicationController
-  include JPie::Controller
-  # Automatically uses UserResource
-end
-
-# 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
-```
-
-### Model Specification Override
-
-JPie automatically infers the model from your resource class name, but you can override this:
-
-```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 = model_class.new(attributes)
-    user.created_by = current_user
-    user.save!
-    
-    render_jsonapi(user, status: :created)
-  end
+class CarResource < JPie::Resource
+  attributes :make, :model, :year
   
-  # show, update, destroy still use the automatic implementations
+  # JPie handles the through association automatically
+  has_many :drivers, through: :car_drivers
 end
 ```
 
-### Custom Attributes
-
-Add computed or transformed attributes to your resources using either blocks or method overrides:
+The join table is completely hidden from the API response, providing a clean interface.
 
-#### 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
-```
-
-#### Using Method Overrides (New Approach)
+### Custom Attributes
 
-You can now define custom methods directly on your resource class instead of using blocks:
+Define custom computed attributes using method overrides:
 
 ```ruby
 class UserResource < JPie::Resource
-  attributes :name, :email
+  attributes :first_name, :last_name
   attribute :full_name
-  attribute :display_name
-  meta_attribute :user_stats
-
+  
   private
-
+  
   def full_name
     "#{object.first_name} #{object.last_name}"
   end
-
-  def display_name
-    if context[:admin]
-      "#{full_name} [ADMIN VIEW] - #{object.email}"
-    else
-      full_name
-    end
-  end
-
-  def user_stats
-    {
-      name_length: object.name.length,
-      email_domain: object.email.split('@').last,
-      account_status: object.active? ? 'active' : 'inactive'
-    }
-  end
 end
 ```
 
-**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
+### Authorization & Context
 
-**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.
-
-#### Using meta_attributes Macro
-
-It's easy to add meta attributes:
+Pass context for authorization-aware responses:
 
 ```ruby
-class UserResource < JPie::Resource
-  meta_attributes :created_at, :updated_at
-  meta_attributes :last_login_at
-end
-```
-
-#### Using Custom meta Method
-
-For more complex meta data, you can define a `meta` method that returns a hash:
-
-```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
-    )
+class UsersController < ApplicationController
+  include JPie::Controller
+  
+  def show
+    user = User.find(params[:id])
+    render_jsonapi(user, context: { current_user: current_user })
   end
 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"
-    }
-  }
-}
-```
-
-#### Meta Method Inheritance
-
-Meta methods work seamlessly with inheritance:
-
-```ruby
-class BaseResource < JPie::Resource
-  meta_attributes :created_at, :updated_at
+## Error Handling
 
-  def meta
-    super.merge(
-      resource_version: '1.0',
-      timestamp: Time.current.iso8601
-    )
-  end
-end
+JPie provides robust error handling with full customization options:
 
-class UserResource < BaseResource
-  attributes :name, :email
-  meta_attributes :last_login_at
+### Default Error Handling
 
-  def meta
-    super.merge(
-      user_specific_data: calculate_user_metrics
-    )
-  end
-
-  private
-
-  def calculate_user_metrics
-    {
-      post_count: object.posts.count,
-      comment_count: object.comments.count
-    }
-  end
-end
-```
-
-### Custom Sorting
-
-Override the default sorting behavior with custom logic:
-
-```ruby
-class PostResource < JPie::Resource
-  attributes :title, :content
-  
-  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
-  end
-end
-```
+JPie automatically handles common errors:
 
-### Polymorphic Associations
+| 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 |
 
-JPie supports polymorphic associations for includes. Here's a complete example with comments that can belong to multiple types of commentable resources:
+### Customization Options
 
-#### Models with Polymorphic Associations
+#### Override Specific Handlers
 
 ```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
-
-# 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
-
-# Article model with has_many polymorphic association  
-class Article < ActiveRecord::Base
-  has_many :comments, as: :commentable, dependent: :destroy
-  belongs_to :author, class_name: 'User'
+class ApplicationController < ActionController::Base
+  # Define your handlers first
+  rescue_from ActiveRecord::RecordNotFound, with: :my_not_found_handler
   
-  validates :title, :body, presence: true
+  include JPie::Controller
+  # JPie will detect existing handler and won't override it
 end
 ```
 
-#### Resources for Polymorphic Associations
+#### Extend JPie Handlers
 
 ```ruby
-# Comment resource
-class CommentResource < JPie::Resource
-  attributes :content, :created_at
-  
-  # Define methods for includes
-  has_many :comments  # For including nested comments
-  has_one :author     # For including the comment author
-  
-  private
-  
-  def commentable
-    object.commentable
-  end
-  
-  def author
-    object.author
-  end
-end
-
-# Post resource  
-class PostResource < JPie::Resource
-  attributes :title, :content, :published_at
-  
-  # Define methods for includes
-  has_many :comments
-  has_one :author
-  
-  private
-  
-  def comments
-    object.comments
-  end
-  
-  def author
-    object.author
-  end
-end
-
-# Article resource
-class ArticleResource < JPie::Resource
-  attributes :title, :body, :published_at
-  
-  # Define methods for includes
-  has_many :comments
-  has_one :author
+class ApplicationController < ActionController::Base
+  include JPie::Controller
   
   private
   
-  def comments
-    object.comments
-  end
-  
-  def author
-    object.author
+  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
 ```
 
-#### Controllers for Polymorphic Resources
+#### Disable All JPie Error 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(comment, status: :created)
-  end
-  
-  private
+  disable_jpie_error_handlers
   
-  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
-  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
+  # Define your own handlers
+  rescue_from StandardError, with: :handle_standard_error
 end
 ```
 
-#### Routes for Polymorphic Resources
+### Custom JPie Errors
 
 ```ruby
-Rails.application.routes.draw do
-  resources :posts do
-    resources :comments, only: [:index, :create]
-  end
-  
-  resources :articles do
-    resources :comments, only: [:index, :create]
+class CustomBusinessError < JPie::Errors::Error
+  def initialize(detail: 'Business logic error')
+    super(status: 422, title: 'Business Error', detail: detail)
   end
-  
-  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"
-    }
-  },
-  "included": [
-    {
-      "id": "1",
-      "type": "comments",
-      "attributes": {
-        "content": "Great post!",
-        "created_at": "2024-01-15T11:00:00Z"
-      }
-    },
-    {
-      "id": "2", 
-      "type": "comments",
-      "attributes": {
-        "content": "Thanks for sharing!",
-        "created_at": "2024-01-15T12:00:00Z"
-      }
-    },
-    {
-      "id": "5",
-      "type": "users",
-      "attributes": {
-        "name": "John Doe",
-        "email": "john@example.com"
-      }
-    },
-    {
-      "id": "6",
-      "type": "users",
-      "attributes": {
-        "name": "Jane Smith",
-        "email": "jane@example.com"
-      }
-    }
-  ]
-}
+# Use in controllers
+raise CustomBusinessError.new(detail: 'Custom validation failed')
 ```
 
-### Single Table Inheritance (STI)
+## Advanced Features
 
-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.
+### Polymorphic Associations
 
-#### STI Models
+JPie supports polymorphic associations for complex data relationships:
 
 ```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
+class CommentResource < JPie::Resource
+  attributes :content
+  has_one :author
+  
+  # Polymorphic commentable (posts, articles, videos, etc.)
+  private
+  
+  def author
+    object.author
+  end
 end
 ```
 
-#### STI Resources
+### Single Table Inheritance
 
-JPie automatically handles STI type inference and resource inheritance:
+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 from base resource
+# STI resources inherit automatically
 class CarResource < VehicleResource
-  attributes :engine_size  # Car-specific attribute
-end
-
-class TruckResource < VehicleResource
-  attributes :cargo_capacity  # Truck-specific attribute
+  attributes :engine_size, :doors  # Car-specific attributes
 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
+STI types are automatically inferred in JSON:API responses.
 
-Controllers work seamlessly with STI models:
-
-```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.)
-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)
-```
-
-#### Complete STI Example
-
-Here's a complete example showing STI in action with HTTP requests and responses:
+### Custom Sorting
 
-**1. Database Setup**
+Implement complex sorting logic:
 
 ```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 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
 ```
 
-**2. Models**
-
-```ruby
-class Vehicle < ApplicationRecord
-  validates :name, :brand, :year, presence: true
-end
-
-class Car < Vehicle
-  validates :engine_size, presence: true
-end
-
-class Truck < Vehicle  
-  validates :cargo_capacity, presence: true
-end
-```
-
-**3. Resources**
-
-```ruby
-class VehicleResource < JPie::Resource
-  attributes :name, :brand, :year
-  meta_attributes :created_at, :updated_at
-end
-
-class CarResource < VehicleResource
-  attributes :engine_size
-end
-
-class TruckResource < VehicleResource
-  attributes :cargo_capacity
-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
-
-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
+## Performance & Best Practices
 
-Override the default scope method to add authorization:
+- **Efficient serialization** with automatic deduplication
+- **Smart includes** with optimized queries
+- **Validation caching** for improved performance
+- **Error handling** that doesn't impact performance
 
-```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)
-  end
-end
-```
+## Contributing
 
-### Custom Context
-
-Override the context building to pass additional data to resources:
-
-```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
-```
+Bug reports and pull requests are welcome on GitHub at https://github.com/emilkampp/jpie.
 
 ## License