jpie 0.4.5 → 1.0.0

data/examples/resource_meta_configuration.md

@@ -1,244 +0,0 @@
-# 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/rspec_testing.md

@@ -1,130 +0,0 @@
-# Testing JPie Resources with RSpec
-
-This guide demonstrates how to use JPie's RSpec matchers and helpers to test your JSON:API resources.
-
-## Setup
-
-Add to your `spec/rails_helper.rb` or `spec/spec_helper.rb`:
-
-```ruby
-require 'jpie/rspec'
-JPie::RSpec.configure!
-```
-
-## Example Usage
-
-Given a basic resource setup:
-
-```ruby
-# app/models/book.rb
-class Book < ApplicationRecord
-  belongs_to :author
-  has_many :reviews
-  
-  def reading_time_minutes
-    (content.split.length / 200.0).ceil
-  end
-end
-
-# app/resources/book_resource.rb
-class BookResource < JPie::Resource
-  type :books
-  
-  attribute :title
-  meta_attribute :reading_time
-  relationship :author
-  relationship :reviews
-  
-  def reading_time
-    { minutes: object.reading_time_minutes }
-  end
-end
-```
-
-Here's how to test it:
-
-```ruby
-# spec/resources/book_resource_spec.rb
-RSpec.describe BookResource, type: :resource do
-  let(:author) { create(:author) }
-  let(:book) { create(:book, author: author) }
-  let(:resource) { described_class.new(model: book) }
-
-  # Test resource structure
-  it { is_expected.to have_type(:books) }
-  it { is_expected.to have_attribute(:title) }
-  it { is_expected.to have_meta_attribute(:reading_time) }
-  it { is_expected.to have_relationship(:author) }
-  it { is_expected.to have_relationship(:reviews) }
-
-  # Test meta values
-  it 'has correct reading time' do
-    expect(resource).to have_meta_value(:reading_time).including(
-      minutes: book.reading_time_minutes
-    )
-  end
-
-  # Test relationship linkage
-  it 'has correct author linkage' do
-    expect(resource).to have_relationship_linkage(:author).with_id(author.id.to_s)
-  end
-end
-
-# spec/requests/books_controller_spec.rb
-RSpec.describe BooksController, type: :request do
-  let!(:books) { create_list(:book, 10) }
-
-  describe 'GET /books' do
-    it 'handles pagination and includes' do
-      get '/books', params: { 
-        page: 1, 
-        per_page: 5,
-        include: 'author,reviews'
-      }
-      
-      # Test pagination
-      expect(response).to be_paginated
-      expect(response).to have_page_size(5)
-      expect(response).to have_pagination_links.including(:first, :last, :next)
-
-      # Test includes
-      expect(response).to include_related(:author)
-      expect(response).to include_related(:reviews)
-    end
-  end
-end
-```
-
-## Helper Methods
-
-```ruby
-# Build without saving
-book = build_jpie_resource(:books, { title: 'Test Book' })
-
-# Create with relationships
-author = create_jpie_resource(:authors, { name: 'Author' })
-book = create_jpie_resource(:books, { title: 'Test Book' }, { author: author })
-
-# Clean up
-cleanup_jpie_resources([book, author])
-```
-
-## Best Practices
-
-1. Always clean up your test resources using `cleanup_jpie_resources`
-2. Test both the presence of attributes/relationships and their values
-3. Group your tests logically by resource features (attributes, relationships, meta)
-4. Test pagination with different page sizes and page numbers
-5. Test relationship includes with various combinations
-6. Test meta fields with both simple and complex values
-7. Use factories (like FactoryBot) to create test data
-8. Test edge cases and validations specific to your resource configuration
-
-## Common Gotchas
-
-- Remember that `have_attribute` and `have_relationship` check both the presence of the method and the attribute/relationship in the resource's configuration
-- The cleanup helper will only destroy persisted resources
-- When testing relationships, make sure to test both the relationship configuration and the actual related resources
-- Meta field values should match exactly, including nested structures
-- Pagination tests should verify both the metadata and the actual number of records returned
-- When testing includes, verify both the presence of the included data and its structure 

data/examples/single_table_inheritance.md

@@ -1,160 +0,0 @@
-# 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/configuration.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module JPie
-  class Configuration
-    attr_accessor :default_page_size, :maximum_page_size
-
-    def initialize
-      @default_page_size = 20
-      @maximum_page_size = 100
-    end
-  end
-end

data/lib/jpie/controller/crud_actions.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-module JPie
-  module Controller
-    module CrudActions
-      extend ActiveSupport::Concern
-
-      class_methods do
-        def jsonapi_resource(resource_class)
-          setup_jsonapi_resource(resource_class)
-        end
-
-        # More concise alias for modern Rails style
-        alias_method :resource, :jsonapi_resource
-
-        private
-
-        def setup_jsonapi_resource(resource_class)
-          define_method :resource_class do
-            resource_class
-          end
-
-          # Define automatic CRUD methods
-          define_automatic_crud_methods(resource_class)
-        end
-
-        def define_automatic_crud_methods(resource_class)
-          define_index_method(resource_class)
-          define_show_method(resource_class)
-          define_create_method(resource_class)
-          define_update_method(resource_class)
-          define_destroy_method(resource_class)
-        end
-
-        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?
-
-            pagination_params = parse_pagination_params
-            original_resources = resources
-            resources = apply_pagination(resources, pagination_params)
-
-            render_jsonapi(resources, pagination: pagination_params, original_scope: original_resources)
-          end
-        end
-
-        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
-        end
-
-        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)
-          end
-        end
-
-        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)
-            render_jsonapi(resource)
-          end
-        end
-
-        def define_destroy_method(resource_class)
-          define_method :destroy do
-            resource = resource_class.scope(context).find(params[:id])
-            resource.destroy!
-            head :no_content
-          end
-        end
-      end
-
-      # 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?
-
-        pagination_params = parse_pagination_params
-        original_resources = resources
-        resources = apply_pagination(resources, pagination_params)
-
-        render_jsonapi(resources, pagination: pagination_params, original_scope: original_resources)
-      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)
-        render_jsonapi(resource)
-      end
-
-      def destroy
-        resource = resource_class.scope(context).find(params[:id])
-        resource.destroy!
-        head :no_content
-      end
-
-      private
-
-      def apply_pagination(resources, pagination_params)
-        return resources unless pagination_params[:per_page]
-
-        page = pagination_params[:page] || 1
-        per_page = pagination_params[:per_page]
-
-        resources.limit(per_page).offset((page - 1) * per_page)
-      end
-    end
-  end
-end