jpie 0.4.0 → 0.4.2

data/examples/pagination.md

@@ -0,0 +1,303 @@
+# Pagination Example
+
+This example demonstrates how to implement pagination with JPie resources using both simple and JSON:API standard pagination parameters.
+
+## Setup
+
+### 1. Model (`app/models/article.rb`)
+```ruby
+class Article < ActiveRecord::Base
+  validates :title, presence: true
+  validates :content, presence: true
+end
+```
+
+### 2. Resource (`app/resources/article_resource.rb`)
+```ruby
+class ArticleResource < JPie::Resource
+  attributes :title, :content, :published_at
+end
+```
+
+### 3. Controller (`app/controllers/articles_controller.rb`)
+```ruby
+class ArticlesController < ApplicationController
+  include JPie::Controller
+end
+```
+
+### 4. Routes (`config/routes.rb`)
+```ruby
+Rails.application.routes.draw do
+  resources :articles
+end
+```
+
+## HTTP Examples
+
+### Simple Pagination Parameters
+
+#### Get First Page with 5 Articles
+```http
+GET /articles?page=1&per_page=5
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "articles",
+      "attributes": {
+        "title": "First Article",
+        "content": "Content of first article",
+        "published_at": "2024-01-01T10:00:00Z"
+      }
+    },
+    {
+      "id": "2",
+      "type": "articles",
+      "attributes": {
+        "title": "Second Article",
+        "content": "Content of second article",
+        "published_at": "2024-01-02T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 1,
+      "per_page": 5,
+      "total_pages": 4,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?page=1&per_page=5",
+    "first": "http://example.com/articles?page=1&per_page=5",
+    "last": "http://example.com/articles?page=4&per_page=5",
+    "next": "http://example.com/articles?page=2&per_page=5"
+  }
+}
+```
+
+#### Get Second Page
+```http
+GET /articles?page=2&per_page=5
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "6",
+      "type": "articles",
+      "attributes": {
+        "title": "Sixth Article",
+        "content": "Content of sixth article",
+        "published_at": "2024-01-06T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 2,
+      "per_page": 5,
+      "total_pages": 4,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?page=2&per_page=5",
+    "first": "http://example.com/articles?page=1&per_page=5",
+    "last": "http://example.com/articles?page=4&per_page=5",
+    "prev": "http://example.com/articles?page=1&per_page=5",
+    "next": "http://example.com/articles?page=3&per_page=5"
+  }
+}
+```
+
+### JSON:API Standard Pagination Parameters
+
+#### Get First Page Using JSON:API Format
+```http
+GET /articles?page[number]=1&page[size]=3
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "articles",
+      "attributes": {
+        "title": "First Article",
+        "content": "Content of first article",
+        "published_at": "2024-01-01T10:00:00Z"
+      }
+    },
+    {
+      "id": "2",
+      "type": "articles",
+      "attributes": {
+        "title": "Second Article",
+        "content": "Content of second article",
+        "published_at": "2024-01-02T10:00:00Z"
+      }
+    },
+    {
+      "id": "3",
+      "type": "articles",
+      "attributes": {
+        "title": "Third Article",
+        "content": "Content of third article",
+        "published_at": "2024-01-03T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 1,
+      "per_page": 3,
+      "total_pages": 7,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?page=1&per_page=3",
+    "first": "http://example.com/articles?page=1&per_page=3",
+    "last": "http://example.com/articles?page=7&per_page=3",
+    "next": "http://example.com/articles?page=2&per_page=3"
+  }
+}
+```
+
+### Pagination with Sorting
+
+#### Get Sorted and Paginated Results
+```http
+GET /articles?sort=-published_at&page=1&per_page=3
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "20",
+      "type": "articles",
+      "attributes": {
+        "title": "Latest Article",
+        "content": "Most recent content",
+        "published_at": "2024-01-20T10:00:00Z"
+      }
+    },
+    {
+      "id": "19",
+      "type": "articles",
+      "attributes": {
+        "title": "Second Latest Article",
+        "content": "Second most recent content",
+        "published_at": "2024-01-19T10:00:00Z"
+      }
+    },
+    {
+      "id": "18",
+      "type": "articles",
+      "attributes": {
+        "title": "Third Latest Article",
+        "content": "Third most recent content",
+        "published_at": "2024-01-18T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 1,
+      "per_page": 3,
+      "total_pages": 7,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?sort=-published_at&page=1&per_page=3",
+    "first": "http://example.com/articles?sort=-published_at&page=1&per_page=3",
+    "last": "http://example.com/articles?sort=-published_at&page=7&per_page=3",
+    "next": "http://example.com/articles?sort=-published_at&page=2&per_page=3"
+  }
+}
+```
+
+### Last Page Response
+
+#### Get Last Page
+```http
+GET /articles?page=4&per_page=5
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "20",
+      "type": "articles",
+      "attributes": {
+        "title": "Last Article",
+        "content": "Content of last article",
+        "published_at": "2024-01-20T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "page": 4,
+      "per_page": 5,
+      "total_pages": 4,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?page=4&per_page=5",
+    "first": "http://example.com/articles?page=1&per_page=5",
+    "last": "http://example.com/articles?page=4&per_page=5",
+    "prev": "http://example.com/articles?page=3&per_page=5"
+  }
+}
+```
+
+### Empty Results
+
+#### Get Page Beyond Available Data
+```http
+GET /articles?page=10&per_page=5
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [],
+  "meta": {
+    "pagination": {
+      "page": 10,
+      "per_page": 5,
+      "total_pages": 4,
+      "total_count": 20
+    }
+  },
+  "links": {
+    "self": "http://example.com/articles?page=10&per_page=5",
+    "first": "http://example.com/articles?page=1&per_page=5",
+    "last": "http://example.com/articles?page=4&per_page=5"
+  }
+}
+``` 

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"
+    }
+  }
+}
+```