jpie 0.3.1 → 0.4.1

data/examples/resource_attribute_configuration.md

@@ -0,0 +1,147 @@
+# Resource Attribute Configuration Example
+
+This example demonstrates all the different ways to configure resource attributes in JPie, showcasing the various configuration patterns and customization techniques available for attributes.
+
+## Setup
+
+### 1. Model (`app/models/user.rb`)
+```ruby
+class User < ActiveRecord::Base
+  validates :first_name, presence: true
+  validates :last_name, presence: true
+  validates :email, presence: true, uniqueness: true
+  validates :username, presence: true, uniqueness: true
+  
+  def active?
+    true # Simple boolean for demonstration
+  end
+end
+```
+
+### 2. Resource with All Attribute Configuration Types (`app/resources/user_resource.rb`)
+```ruby
+class UserResource < JPie::Resource
+  # 1. Basic attributes - direct model attribute access
+  attributes :email, :first_name, :last_name
+  
+  # 2. Attribute with custom attr mapping (maps to different model attribute)
+  attribute :display_name, attr: :username
+  
+  # 3. Attribute with block override
+  attribute :status do
+    object.active? ? 'active' : 'inactive'
+  end
+  
+  # 4. Attribute with custom method override
+  attribute :full_name
+  
+  private
+  
+  # Custom method for attribute override
+  def full_name
+    "#{object.first_name} #{object.last_name}".strip
+  end
+end
+```
+
+### 3. Controller (`app/controllers/users_controller.rb`)
+```ruby
+class UsersController < ApplicationController
+  include JPie::Controller
+end
+```
+
+## HTTP Examples
+
+### Create User
+```http
+POST /users
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "attributes": {
+      "email": "john.doe@example.com",
+      "first_name": "John",
+      "last_name": "Doe"
+    }
+  }
+}
+
+HTTP/1.1 201 Created
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "email": "john.doe@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "display_name": "johndoe",
+      "status": "active",
+      "full_name": "John Doe"
+    }
+  }
+}
+```
+
+### Update User
+```http
+PATCH /users/1
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "first_name": "Jonathan"
+    }
+  }
+}
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "email": "john.doe@example.com",
+      "first_name": "Jonathan",
+      "last_name": "Doe",
+      "display_name": "johndoe",
+      "status": "active",
+      "full_name": "Jonathan Doe"
+    }
+  }
+}
+```
+
+### Get User with All Attribute Configuration Types
+```http
+GET /users/1
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "email": "john.doe@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "display_name": "johndoe",
+      "status": "active",
+      "full_name": "John Doe"
+    }
+  }
+}
+```

data/examples/resource_meta_configuration.md

@@ -0,0 +1,244 @@
+# Meta Field Configuration Example
+
+This example demonstrates all the different ways to define and configure meta fields in JPie, focusing on the various configuration patterns and syntax options available.
+
+## Setup
+
+### 1. Article model
+```ruby
+class Article < ActiveRecord::Base
+  validates :title, presence: true
+  validates :content, presence: true
+  validates :status, inclusion: { in: %w[draft published archived] }
+  
+  belongs_to :author, class_name: 'User'
+  
+  def word_count
+    content.split.length
+  end
+  
+  def reading_time_minutes
+    (word_count / 200.0).ceil
+  end
+end
+```
+
+### 2. Resource with All Meta Field Configuration Types 
+```ruby
+class ArticleResource < JPie::Resource
+  # 1. Basic meta attributes - direct model access and custom methods
+  meta_attributes :created_at, :updated_at
+  meta_attribute :reading_time
+  
+  # 2. Meta attribute with attr mapping (maps to different model attribute)
+  meta_attribute :author_name, attr: :author_email
+  
+  # 3. Meta attribute with block (legacy style)
+  meta_attribute :word_count do
+    object.word_count
+  end
+  
+  # 4. Meta attribute with proc block (alternative legacy style)
+  meta_attribute :character_count, block: proc { object.content.length }
+  
+  # 5. Short alias syntax (modern style)
+  meta :api_version
+  metas :request_id, :cache_key
+  
+  # 6. Custom meta method for dynamic metadata
+  def meta
+    # Start with declared meta attributes
+    base_meta = super
+    
+    # Add dynamic metadata
+    dynamic_meta = {
+      timestamp: Time.current.iso8601,
+      resource_version: '2.1'
+    }
+    
+    # Conditional metadata based on context
+    if context[:include_debug]
+      dynamic_meta[:debug_info] = {
+        object_class: object.class.name,
+        context_keys: context.keys
+      }
+    end
+    
+    # Merge and return
+    base_meta.merge(dynamic_meta)
+  end
+  
+  private
+  
+  # Custom method for reading_time meta attribute
+  def reading_time
+    {
+      minutes: object.reading_time_minutes,
+      formatted: "#{object.reading_time_minutes} min read"
+    }
+  end
+  
+  # Meta attribute accessing context
+  def user_role
+    context[:current_user]&.role || 'anonymous'
+  end
+  
+  # Meta attribute with conditional logic
+  def edit_permissions
+    current_user = context[:current_user]
+    return false unless current_user
+    
+    current_user.admin? || current_user == object.author
+  end
+  
+  # Meta attributes using short alias syntax
+  def api_version
+    '1.0'
+  end
+  
+  def request_id
+    context[:request_id] || SecureRandom.uuid
+  end
+  
+  def cache_key
+    "article:#{object.id}:#{object.updated_at.to_i}"
+  end
+end
+```
+
+## HTTP Examples
+
+### Create Article
+```http
+POST /articles
+Content-Type: application/vnd.api+json
+Authorization: Bearer user_token
+
+{
+  "data": {
+    "type": "articles",
+    "attributes": {
+      "title": "Meta Field Configuration Guide",
+      "content": "This guide demonstrates all the different ways to configure meta fields in JPie...",
+      "status": "draft"
+    }
+  }
+}
+
+HTTP/1.1 201 Created
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "articles",
+    "attributes": {
+      "title": "Meta Field Configuration Guide",
+      "content": "This guide demonstrates all the different ways to configure meta fields in JPie...",
+      "status": "draft"
+    },
+    "meta": {
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-15T10:30:00Z",
+      "reading_time": {
+        "minutes": 3,
+        "formatted": "3 min read"
+      },
+      "author_name": "john@example.com",
+      "word_count": 450,
+      "character_count": 2700,
+      "api_version": "1.0",
+      "request_id": "req_abc123def456",
+      "cache_key": "article:1:1705492800",
+      "timestamp": "2024-03-15T16:45:30Z",
+      "resource_version": "2.1"
+    }
+  }
+}
+```
+
+### Update Article
+```http
+PATCH /articles/1
+Content-Type: application/vnd.api+json
+Authorization: Bearer user_token
+
+{
+  "data": {
+    "id": "1",
+    "type": "articles",
+    "attributes": {
+      "status": "published"
+    }
+  }
+}
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "articles",
+    "attributes": {
+      "title": "Meta Field Configuration Guide",
+      "content": "This guide demonstrates all the different ways to configure meta fields in JPie...",
+      "status": "published"
+    },
+    "meta": {
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-16T14:20:00Z",
+      "reading_time": {
+        "minutes": 3,
+        "formatted": "3 min read"
+      },
+      "author_name": "john@example.com",
+      "word_count": 450,
+      "character_count": 2700,
+      "api_version": "1.0",
+      "request_id": "req_xyz789ghi012",
+      "cache_key": "article:1:1705492800",
+      "timestamp": "2024-03-16T14:20:00Z",
+      "resource_version": "2.1"
+    }
+  }
+}
+```
+
+### Get Article with All Meta Field Configurations
+```http
+GET /articles/1
+Accept: application/vnd.api+json
+Authorization: Bearer user_token
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "articles",
+    "attributes": {
+      "title": "Meta Field Configuration Guide",
+      "content": "This guide demonstrates all the different ways to configure meta fields in JPie...",
+      "status": "published"
+    },
+    "meta": {
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-16T14:20:00Z",
+      "reading_time": {
+        "minutes": 3,
+        "formatted": "3 min read"
+      },
+      "author_name": "john@example.com",
+      "word_count": 450,
+      "character_count": 2700,
+      "api_version": "1.0",
+      "request_id": "req_abc123def456",
+      "cache_key": "article:1:1705492800",
+      "timestamp": "2024-03-16T14:20:00Z",
+      "resource_version": "2.1"
+    }
+  }
+}
+```

data/examples/single_table_inheritance.md

@@ -0,0 +1,160 @@
+# Single Table Inheritance (STI) Example
+
+This example demonstrates the minimal setup required to implement Single Table Inheritance with JPie resources and controllers.
+
+## Setup
+
+### 1. Base Model (`app/models/vehicle.rb`)
+```ruby
+class Vehicle < ApplicationRecord
+  validates :name, presence: true
+  validates :brand, presence: true
+  validates :year, presence: true
+end
+```
+
+### 2. STI Models (`app/models/car.rb`, `app/models/truck.rb`)
+```ruby
+class Car < Vehicle
+  validates :engine_size, presence: true
+end
+
+class Truck < Vehicle
+  validates :cargo_capacity, presence: true
+end
+```
+
+### 3. Base Resource (`app/resources/vehicle_resource.rb`)
+```ruby
+class VehicleResource < JPie::Resource
+  attributes :name, :brand, :year
+end
+```
+
+### 4. STI Resources (`app/resources/car_resource.rb`, `app/resources/truck_resource.rb`)
+```ruby
+class CarResource < VehicleResource
+  attributes :engine_size
+end
+
+class TruckResource < VehicleResource
+  attributes :cargo_capacity
+end
+```
+
+### 5. Controller (`app/controllers/vehicles_controller.rb`)
+```ruby
+class VehiclesController < ApplicationController
+  include JPie::Controller
+end
+```
+
+### 6. Routes (`config/routes.rb`)
+```ruby
+Rails.application.routes.draw do
+  resources :vehicles
+end
+```
+
+## HTTP Examples
+
+### Create Car
+```http
+POST /vehicles
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "cars",
+    "attributes": {
+      "name": "Civic",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1500
+    }
+  }
+}
+
+HTTP/1.1 201 Created
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1500
+    }
+  }
+}
+```
+
+### Update Car
+```http
+PATCH /vehicles/1
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic Hybrid",
+      "engine_size": 1800
+    }
+  }
+}
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "cars",
+    "attributes": {
+      "name": "Civic Hybrid",
+      "brand": "Honda",
+      "year": 2024,
+      "engine_size": 1800
+    }
+  }
+}
+```
+
+### Get Mixed Vehicles
+```http
+GET /vehicles
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "cars",
+      "attributes": {
+        "name": "Civic",
+        "brand": "Honda",
+        "year": 2024,
+        "engine_size": 1500
+      }
+    },
+    {
+      "id": "2",
+      "type": "trucks",
+      "attributes": {
+        "name": "F-150",
+        "brand": "Ford",
+        "year": 2024,
+        "cargo_capacity": 1000
+      }
+    }
+  ]
+}
+``` 

data/lib/jpie/controller/crud_actions.rb

@@ -34,6 +34,8 @@ module JPie
 
         def define_index_method(resource_class)
           define_method :index do
+            validate_include_params
+            validate_sort_params
             resources = resource_class.scope(context)
             sort_fields = parse_sort_params
             resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
@@ -43,6 +45,7 @@ module JPie
 
         def define_show_method(resource_class)
           define_method :show do
+            validate_include_params
             resource = resource_class.scope(context).find(params[:id])
             render_jsonapi(resource)
           end
@@ -50,6 +53,7 @@ module JPie
 
         def define_create_method(resource_class)
           define_method :create do
+            validate_json_api_request
             attributes = deserialize_params
             resource = resource_class.model.create!(attributes)
             render_jsonapi(resource, status: :created)
@@ -58,6 +62,7 @@ module JPie
 
         def define_update_method(resource_class)
           define_method :update do
+            validate_json_api_request
             resource = resource_class.scope(context).find(params[:id])
             attributes = deserialize_params
             resource.update!(attributes)
@@ -76,6 +81,8 @@ module JPie
 
       # These methods can still be called manually or used to override defaults
       def index
+        validate_include_params
+        validate_sort_params
         resources = resource_class.scope(context)
         sort_fields = parse_sort_params
         resources = resource_class.sort(resources, sort_fields) if sort_fields.any?
@@ -83,17 +90,20 @@ module JPie
       end
 
       def show
+        validate_include_params
         resource = resource_class.scope(context).find(params[:id])
         render_jsonapi(resource)
       end
 
       def create
+        validate_json_api_request
         attributes = deserialize_params
         resource = model_class.create!(attributes)
         render_jsonapi(resource, status: :created)
       end
 
       def update
+        validate_json_api_request
         resource = resource_class.scope(context).find(params[:id])
         attributes = deserialize_params
         resource.update!(attributes)