jpie 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b3ade425c9173f2c516edbab70ee2991201648fb15d2e461b58667fda6a46a8
-  data.tar.gz: 7783e2e57be4b1a2f7e50fec35240413d873af2e1ab98ba8ed7f8305af272c9e
+  metadata.gz: f0e1d1634f188bca4057e3550479af557bd00ba0d262c919ba221aa99997490e
+  data.tar.gz: 89db580da555f310a1b840daad204e2315fcb8b7828278b328271412d3bc321d
 SHA512:
-  metadata.gz: 582998bde4d3fc2b44c280a8a4e87e45477bd66f808790c07a90f7110ca405b7e4695f4c306280fdd8a85b4bf36d4f1413b55a542c40d96a340d828ff2aaf2b2
-  data.tar.gz: 63d5d8f010159cb9aff0bcc99a5c8f5739c5d879b62611e980eb0c3ca0312ef02f31d550bfb14b5cbee0d0978c236fe28beb0df79a1006178c429c04d1457aa6
+  metadata.gz: d2ced2be2db661db82e08200be2e5df033c072dcbf249565719336d3b08532d2cb01c4bbcec78cfb5e14fbbbadddb0c127292b70a9b970da3ecc20891bc8c8ab
+  data.tar.gz: 5d1ac4453eb74ba6a8ea04036f00065e26a54c2ff85a603525dd90106bd4f82a839ed3985083c5ff60d087b6bb1239c7a618a7a024e7e3fa1955c82d863aefa8

data/.cursorrules

@@ -5,6 +5,10 @@
 - Follow Ruby style guide and RuboCop rules defined in .rubocop.yml
 - Prefer rubocop autocorrect 
 - Always pass rubocop before committing to git
+- Use `{data:}` rather than `{data: data}`
+- Only use code comments when abasolutely necessary
+- Keep any code comments short and concise
+- Don't update the .rubocop.yml unless it's absolutely necessarry
 
 # Documentation requirements
 - Keep README.md up to date with installation and usage instructions
@@ -33,6 +37,8 @@
 - Place tests in spec/jpie/
 - Use proper namespacing (JPie module)
 - Follow Ruby gem best practices
+- Do not update the spec/jpie/database.rb unless it's absolutely necessarry
+- Do not update the spec/jpie/resources.rb unless it's absolutely necessarry
 
 # Dependency management
 - Keep dependencies minimal and justified
@@ -56,14 +62,12 @@
 - Support Rails 8+ integration
 - Follow JSON:API specification strictly
 
-# Styleguide
-- Use `{data:}` rather than `{data: data}`
-
 # When implementing new features or refactoring
 - Always read the .aiconfig file 
 - Always implement code slowly and methodically 
 - Always test as you go
 - Always make sure rubocop passes
+- Do not add any functionality for the new feature to existing tests unless absolutely necessarry.
 
 # Examples
 - The examples must _only_ include _required_ code

data/.overcommit.yml

@@ -0,0 +1,35 @@
+# Use this file to configure the Overcommit hooks you wish to use. This will
+# extend the default configuration defined in:
+# https://github.com/sds/overcommit/blob/master/config/default.yml
+
+# Global settings
+verify_signatures: false
+
+PreCommit:
+  ALL:
+    problem_on_unmodified_line: ignore
+    requires_files: true
+    quiet: false
+
+  # Run RuboCop on Ruby files before commit
+  RuboCop:
+    enabled: true
+    command: ['bundle', 'exec', 'rubocop']
+    flags: ['--force-exclusion']
+    on_warn: fail
+
+  # Check for trailing whitespace
+  TrailingWhitespace:
+    enabled: true
+    exclude:
+      - '**/*.md'
+
+  # Check for merge conflicts
+  MergeConflicts:
+    enabled: true
+
+PrePush:
+  # Run RSpec tests before push
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2025-01-25
+
+### Added
+- **Pagination Example**: Comprehensive pagination example demonstrating both simple and JSON:API standard pagination formats
+  - Simple pagination parameters (`page`, `per_page`)
+  - JSON:API standard pagination format (`page[number]`, `page[size]`)
+  - Pagination combined with sorting functionality
+  - Edge cases including last page and empty results
+  - Complete HTTP request/response examples following project format
+
+### Enhanced
+- **Documentation**: Improved example coverage with detailed pagination use cases
+- **Developer Experience**: Clear examples for implementing pagination in JPie applications
+
 ## [0.4.1] - 2025-01-25
 
 ### Fixed

data/README.md

@@ -27,6 +27,63 @@ Add JPie to your Rails application:
 bundle add jpie
 ```
 
+## Development Setup
+
+This project uses [Overcommit](https://github.com/sds/overcommit) to enforce code quality through Git hooks. After cloning the repository:
+
+### Quick Setup (Recommended)
+
+```bash
+# One command to set up everything
+./bin/setup-hooks
+```
+
+### Manual Setup
+
+If you prefer to set up manually:
+
+```bash
+# 1. Install dependencies
+bundle install
+
+# 2. Install overcommit globally (one-time setup)
+gem install overcommit
+
+# 3. Install the Git hooks for this project
+overcommit --install
+
+# 4. Sign the configuration (required for security)
+overcommit --sign
+```
+
+### 3. Automated Quality Checks
+
+The following checks run automatically:
+
+**Pre-commit hooks:**
+- ✅ **RuboCop** - Code style and quality analysis
+- ✅ **Trailing whitespace** - Prevents whitespace issues
+- ✅ **Merge conflicts** - Catches unresolved conflicts
+
+**Pre-push hooks:**
+- ✅ **RSpec** - Full test suite execution
+
+### 4. Manual Quality Checks
+
+You can run these checks manually:
+
+```bash
+# Run RuboCop with auto-fix
+bundle exec rubocop -A
+
+# Run tests
+bundle exec rspec
+
+# Test hooks without committing
+overcommit --run pre-commit
+overcommit --run pre-push
+```
+
 ## Quick Start
 
 JPie works out of the box with minimal configuration:
@@ -131,27 +188,6 @@ end
 | `--model=NAME` | Specify model class | `--model=Person` |
 | `--skip-model` | Skip explicit model declaration | `--skip-model` |
 
-## Core Features
-
-### JSON:API Compliance
-
-JPie automatically handles all JSON:API specification requirements:
-
-#### Sorting
-```http
-GET /users?sort=name,-created_at
-```
-
-#### Includes
-```http
-GET /posts?include=author,comments,comments.author
-```
-
-#### Validation
-- Request structure validation for POST/PATCH operations
-- Include parameter validation  
-- Sort parameter validation with clear error messages
-
 ### Modern DSL
 
 ```ruby
@@ -180,183 +216,7 @@ class UserResource < JPie::Resource
 end
 ```
 
-### Through Associations
-
-JPie seamlessly supports Rails `:through` associations:
-
-```ruby
-class CarResource < JPie::Resource
-  attributes :make, :model, :year
-  
-  # JPie handles the through association automatically
-  has_many :drivers, through: :car_drivers
-end
-```
-
-The join table is completely hidden from the API response, providing a clean interface.
-
-### Custom Attributes
-
-Define custom computed attributes using method overrides:
-
-```ruby
-class UserResource < JPie::Resource
-  attributes :first_name, :last_name
-  attribute :full_name
-  
-  private
-  
-  def full_name
-    "#{object.first_name} #{object.last_name}"
-  end
-end
-```
-
-### Authorization & Context
-
-Pass context for authorization-aware responses:
-
-```ruby
-class UsersController < ApplicationController
-  include JPie::Controller
-  
-  def show
-    user = User.find(params[:id])
-    render_jsonapi(user, context: { current_user: current_user })
-  end
-end
-```
-
-## Error Handling
-
-JPie provides robust error handling with full customization options:
-
-### Default Error Handling
-
-JPie automatically handles common errors:
-
-| 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 |
-
-### Customization Options
-
-#### Override Specific Handlers
-
-```ruby
-class ApplicationController < ActionController::Base
-  # Define your handlers first
-  rescue_from ActiveRecord::RecordNotFound, with: :my_not_found_handler
-  
-  include JPie::Controller
-  # JPie will detect existing handler and won't override it
-end
-```
-
-#### Extend JPie Handlers
-
-```ruby
-class ApplicationController < ActionController::Base
-  include JPie::Controller
-  
-  private
-  
-  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
-```
-
-#### Disable All JPie Error Handlers
-
-```ruby
-class ApplicationController < ActionController::Base
-  include JPie::Controller
-  
-  disable_jpie_error_handlers
-  
-  # Define your own handlers
-  rescue_from StandardError, with: :handle_standard_error
-end
-```
-
-### Custom JPie Errors
-
-```ruby
-class CustomBusinessError < JPie::Errors::Error
-  def initialize(detail: 'Business logic error')
-    super(status: 422, title: 'Business Error', detail: detail)
-  end
-end
-
-# Use in controllers
-raise CustomBusinessError.new(detail: 'Custom validation failed')
-```
-
-## Advanced Features
-
-### Polymorphic Associations
-
-JPie supports polymorphic associations for complex data relationships:
-
-```ruby
-class CommentResource < JPie::Resource
-  attributes :content
-  has_one :author
-  
-  # Polymorphic commentable (posts, articles, videos, etc.)
-  private
-  
-  def author
-    object.author
-  end
-end
-```
-
-### Single Table Inheritance
-
-JPie automatically handles STI models:
-
-```ruby
-# Base resource
-class VehicleResource < JPie::Resource
-  attributes :name, :brand, :year
-end
-
-# STI resources inherit automatically
-class CarResource < VehicleResource
-  attributes :engine_size, :doors  # Car-specific attributes
-end
-```
-
-STI types are automatically inferred in JSON:API responses.
-
-### Custom Sorting
-
-Implement complex sorting logic:
-
-```ruby
-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
-```
-
-## Performance & Best Practices
-
-- **Efficient serialization** with automatic deduplication
-- **Smart includes** with optimized queries
-- **Validation caching** for improved performance
-- **Error handling** that doesn't impact performance
+See the examples folder for more examples of how to use the DSL to solve various serialization/deserialization scenarios.
 
 ## Contributing
 

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