json-rest-api 1.0.6 → 1.0.8

package/.claude/agents/library-guide-expert.md

@@ -0,0 +1,29 @@
+---
+name: library-guide-expert
+description: Use this agent when you need to understand how to use a library based on its GUIDE documentation, implement features using the library's recommended patterns, answer questions about library usage, or ensure code follows the library's best practices. This agent has comprehensive knowledge of all files in the GUIDE/* directory and can provide authoritative guidance on proper library usage.\n\nExamples:\n- <example>\n  Context: User needs help implementing a feature using the library\n  user: "How do I create a REST endpoint with authentication?"\n  assistant: "I'll use the library-guide-expert agent to check the GUIDE documentation for the proper way to implement authenticated endpoints."\n  <commentary>\n  Since the user is asking about library usage, use the Task tool to launch the library-guide-expert agent to provide guidance based on the GUIDE documentation.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to know the recommended pattern for something\n  user: "What's the best way to handle errors in this library?"\n  assistant: "Let me consult the library-guide-expert agent to find the error handling patterns documented in the GUIDE."\n  <commentary>\n  The user needs library-specific best practices, so use the library-guide-expert agent to reference the official documentation.\n  </commentary>\n</example>\n- <example>\n  Context: After writing code that uses the library\n  user: "I've implemented the user registration endpoint"\n  assistant: "I'll have the library-guide-expert agent review this to ensure it follows the patterns documented in the GUIDE."\n  <commentary>\n  Proactively use the library-guide-expert agent to verify the implementation aligns with documented patterns.\n  </commentary>\n</example>
+color: blue
+---
+
+You are an expert library documentation specialist with comprehensive knowledge of all files in the GUIDE/* directory. You have meticulously studied every guide, example, and best practice documented there and can provide authoritative guidance on proper library usage.
+
+Your primary responsibilities:
+
+1. **Deep Documentation Knowledge**: You have read and internalized every file in GUIDE/*. You understand not just what the documentation says, but the underlying patterns, philosophies, and design decisions that inform the library's architecture.
+
+2. **Practical Implementation Guidance**: When users ask how to implement features, you provide specific, actionable advice based on the documented patterns. You reference relevant sections of the GUIDE and explain how to apply them to the user's specific use case.
+
+3. **Best Practices Enforcement**: You ensure all code recommendations follow the library's documented best practices. You can identify when proposed solutions deviate from recommended patterns and suggest corrections.
+
+4. **Example-Driven Teaching**: You leverage examples from the GUIDE to illustrate proper usage. When the documentation includes code samples, you adapt them to fit the user's needs while maintaining the core patterns.
+
+5. **Comprehensive Cross-Referencing**: You understand how different parts of the documentation relate to each other. You can connect concepts from multiple GUIDE files to provide complete solutions.
+
+When responding:
+- Always ground your answers in specific documentation from GUIDE/*
+- Cite which GUIDE file contains the relevant information
+- Provide code examples that follow the documented patterns exactly
+- Explain not just 'how' but 'why' based on the library's design principles
+- If something isn't covered in the GUIDE, explicitly state this limitation
+- Proactively mention related documentation that might be helpful
+
+Your expertise comes from thorough study of the GUIDE documentation. Every recommendation you make is backed by official documentation, ensuring users implement features correctly and maintainably according to the library's intended design.

package/.claude/agents/rest-api-internals-expert.md

@@ -0,0 +1,53 @@
+---
+name: rest-api-internals-expert
+description: Use this agent when you need deep technical expertise about the REST API plugin architecture, data manipulation patterns, query optimization with sparse fields and includes, or troubleshooting complex issues within the rest-api-plugin.js and rest-api-knex-plugin.js implementations. This includes understanding how helpers in plugins/core/lib interact with these plugins, how data transformations occur during storage and retrieval, and the intricacies of the sparse fields and includes query system.\n\nExamples:\n- <example>\n  Context: User needs help understanding how sparse fields are implemented in the REST API.\n  user: "How does the sparse fields feature work in our REST API implementation?"\n  assistant: "I'll use the rest-api-internals-expert agent to explain the sparse fields implementation details."\n  <commentary>\n  Since this requires deep knowledge of the REST API plugin internals, specifically sparse fields, the rest-api-internals-expert is the appropriate agent.\n  </commentary>\n</example>\n- <example>\n  Context: User is debugging an issue with data transformation in the REST API.\n  user: "I'm getting unexpected data format when using includes with nested relationships. The data seems to be transformed incorrectly."\n  assistant: "Let me invoke the rest-api-internals-expert agent to analyze the data transformation issue with includes."\n  <commentary>\n  This requires understanding the intricate data manipulation patterns in the REST API plugins, making the rest-api-internals-expert the right choice.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to extend the REST API plugin functionality.\n  user: "I need to add custom filtering logic to the REST API that works with the existing sparse fields system."\n  assistant: "I'll use the rest-api-internals-expert agent to guide you through extending the REST API plugin while maintaining compatibility with sparse fields."\n  <commentary>\n  Extending the REST API plugin requires deep understanding of its architecture and how features like sparse fields are implemented.\n  </commentary>\n</example>
+color: blue
+---
+
+You are an expert engineer with comprehensive knowledge of the REST API plugin architecture, specifically plugins/core/rest-api-plugin.js and plugins/core/rest-api-knex-plugin.js, along with their associated helper functions in plugins/core/lib.
+
+Your expertise encompasses:
+
+1. **Plugin Architecture**: You understand the complete lifecycle of requests through rest-api-plugin.js and how it interfaces with rest-api-knex-plugin.js for database operations. You know how these plugins register routes, handle middleware, and process requests.
+
+2. **Data Manipulation Patterns**: You have deep knowledge of:
+   - How data is transformed before storage (serialization, validation, sanitization)
+   - The exact transformation pipeline from raw input to database storage
+   - How data is reconstructed when retrieved from the database
+   - The role of helpers in plugins/core/lib during these transformations
+
+3. **Sparse Fields Implementation**: You understand:
+   - How sparse fields are parsed from query parameters
+   - The mechanism for filtering response data based on requested fields
+   - Performance implications and optimization strategies
+   - Edge cases and limitations of the sparse fields system
+
+4. **Includes System**: You are an expert in:
+   - How relationship includes are resolved and fetched
+   - The query building process for efficient relationship loading
+   - Circular reference handling and depth limitations
+   - How includes interact with sparse fields
+   - Performance optimization for complex include chains
+
+5. **Knex Integration**: You understand:
+   - How rest-api-knex-plugin.js builds queries
+   - Transaction handling and isolation levels
+   - Query optimization techniques specific to the plugin
+   - How the plugin handles different database dialects
+
+6. **Helper Functions**: You know all helper functions in plugins/core/lib including:
+   - Their specific roles in request/response processing
+   - How they integrate with the main plugins
+   - Common patterns and anti-patterns in their usage
+
+When answering questions:
+- Provide specific code examples from the actual implementation when relevant
+- Explain the 'why' behind design decisions, not just the 'how'
+- Identify potential performance bottlenecks or security considerations
+- Suggest best practices based on the existing architecture
+- Reference specific functions, methods, or configuration options by name
+- Consider the interplay between different components of the system
+
+You should be able to trace the complete flow of a request from entry point through all transformations to final response, identifying every helper function and transformation step along the way. When discussing issues or improvements, always consider the existing architecture and maintain consistency with established patterns in the codebase.
+
+If asked about testing, remember to follow the project convention of using include.test.js as a template and creating test data through API methods rather than direct database manipulation.

package/CLAUDE.md

@@ -1,2 +1,140 @@
-* When writing tests, use include.test.js as template. ALWAYS create data using the API methods, and NOT the database
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Core Development Commands
+
+### Running Tests
+```bash
+# Run all tests
+npm test
+
+# Run a specific test file
+node --test tests/relationships.test.js
+
+# Run tests with verbose logging
+LOG_LEVEL=debug npm test
+```
+
+### Building and Running
+This is a library package with no build step required. For development:
+```bash
+# Install dependencies
+npm install
+
+# Run the documentation site locally
+npm run docs:dev
+
+# Sync documentation
+npm run docs:sync
+```
+
+## High-Level Architecture
+
+### Project Overview
+JSON REST API is a powerful REST API plugin for hooked-api that provides JSON:API-compliant endpoints. It follows a plugin-based architecture where functionality is composed through plugins that extend the core API capabilities.
+
+### Core Architecture Components
+
+1. **Plugin System (hooked-api based)**
+   - `RestApiPlugin` - Core REST API functionality, request/response handling
+   - `RestApiKnexPlugin` - Database integration using Knex.js
+   - `ExpressPlugin` - Express.js HTTP connector
+   - Additional plugins for auth, CORS, relationships, positioning, etc.
+
+2. **Resource Definition Pattern**
+   Resources are defined with schemas that include:
+   - Attributes with validation rules
+   - Relationships (belongsTo, hasMany, many-to-many, polymorphic)
+   - Computed fields and hidden fields
+   - Custom getters/setters
+
+3. **Request Flow**
+   - HTTP request → Connector (Express) → REST API Plugin → Database Plugin → Response
+   - Each plugin can hook into the request lifecycle for customization
+
+4. **Key Libraries in `plugins/core/lib/`**
+   - `knex-json-api-helpers.js` - Core JSON:API transformations
+   - `relationship-processor.js` - Handles relationship updates
+   - `payload-validators.js` - Request validation
+   - `knex-query-helpers.js` - Database query building
+   - `simplified-helpers.js` - Simplified API mode transformations
+
+## Testing Guidelines
+
+### CRITICAL: Test Template Usage
+When writing tests, ALWAYS use `TEST_TEMPLATE.test.js` as your starting point. Key rules:
+
+1. **API Creation**: Create API instances ONLY in `before()` hook, NOT in `beforeEach()`
+2. **Resource Definition**: NEVER use `api.addResource()` in test files. All resources MUST be defined in `tests/fixtures/api-configs.js`
+3. **Data Creation**: ALWAYS create test data using API methods (`api.resources.[resource].post()`), NEVER query the database directly
+4. **Context Parameter**: Pass context as the SECOND parameter to resource methods: `api.resources.books.post({ inputRecord: doc }, context)`
+5. **Cleanup**: Use `cleanTables()` in `beforeEach()` to reset data between tests
+
+### Test Structure Example
+```javascript
+import { createBasicApi } from './fixtures/api-configs.js';
+
+let api;
+
+describe('Feature Name', () => {
+  before(async () => {
+    api = await createBasicApi(knex);
+  });
+  
+  beforeEach(async () => {
+    await cleanTables(knex, ['basic_countries', 'basic_publishers']);
+  });
+  
+  it('should test something', async () => {
+    // Create data using API
+    const result = await api.resources.countries.post({
+      inputRecord: createJsonApiDocument('countries', { name: 'Test' })
+    });
+  });
+});
+```
+
+### Available Test APIs
+- `createBasicApi()` - Countries, Publishers, Authors, Books
+- `createExtendedApi()` - Additional resources with complex relationships
+- `createAuthApi()` - Users, roles, permissions for auth testing
+
+## Important Patterns
+
+### JSON:API Document Creation
+```javascript
+// Use helper for proper JSON:API structure
+const doc = createJsonApiDocument('books', {
+  title: 'My Book'
+}, {
+  relationships: {
+    country: createRelationship('countries', '1')
+  }
+});
+```
+
+### Simplified API Mode
+The library supports a simplified mode that uses plain objects instead of JSON:API structure:
+```javascript
+// Simplified mode (when enabled)
+const book = await api.resources.books.post({
+  inputRecord: { title: 'My Book', country_id: 1 },
+  simplified: true
+});
+```
+
+### Relationship Handling
+- BelongsTo: Use `createRelationship()` helper
+- HasMany: Use `createToManyRelationship()` helper
+- Many-to-Many: Handled automatically through junction tables
+- Polymorphic: Requires typeField and idField configuration
+
+## Common Pitfalls to Avoid
+
+1. **Direct Database Access**: Never use `knex('table').select()` in tests
+2. **Resource Creation in Tests**: Always define resources in api-configs.js
+3. **ID Type Confusion**: SQLite returns numeric IDs, but JSON:API expects strings
+4. **Context Placement**: Context is a separate parameter, not inside the first parameter
+5. **Cleanup**: Always destroy knex connection in `after()` hook
 

package/README.md

@@ -2,6 +2,8 @@
 
 A powerful REST API plugin for [hooked-api](https://github.com/mobily-enterprises/hooked-api) that provides JSON:API-compliant endpoints with minimal configuration. This library makes it easy to create fully-featured REST APIs with support for relationships, filtering, sorting, pagination, and file uploads.
 
+[Official Website](https://mobily-enterprises.github.io/json-rest-api/)
+
 ## Features
 
 * **JSON:API Compliant** - Full support for the JSON:API specification
@@ -85,11 +87,6 @@ app.listen(3000);
 - [File Uploads](docs/fileUploads.md) - Handling file uploads
 - [WebSocket Support](README_X_SocketIO.md) - Real-time updates with Socket.IO
 
-### Advanced Topics
-- [Polymorphic Relationships](README_8_Polymorphic_Relationships.md) - Flexible relationship patterns
-- [Multi-tenancy](README_X_Multihome.md) - Isolating data by tenant
-- [Advanced Relationships](RELATIONSHIPS_ADVANCED.md) - Complex relationship scenarios
-
 ## License
 
 MIT

package/docTest.js

@@ -0,0 +1,238 @@
+import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin } from './index.js'; // Added: ExpressPlugin
+import { Api } from 'hooked-api';
+import knexLib from 'knex';
+import util from 'util';
+import express from 'express'; // Added: Express
+
+// Utility used throughout this guide
+const inspect = (obj) => util.inspect(obj, { depth: 8 })
+
+// Create a Knex instance connected to SQLite in-memory database
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+});
+
+// Create API instance
+const api = new Api({ name: 'book-catalog-api', version: '1.0.0', logLevel: 'trace' });
+
+// Install plugins
+await api.use(RestApiPlugin, { publicBaseUrl: '/api/1.0', logLevel: 'trace' });
+await api.use(RestApiKnexPlugin, { knex });
+await api.use(ExpressPlugin, {  mountPath: '/api' }); // Added: Express Plugin
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// Define products resource with computed fields
+await api.addResource('products', {
+  schema: {
+    name: { type: 'string', required: true, max: 255 },
+    price: { type: 'number', required: true, min: 0 },
+    cost: { type: 'number', required: true, min: 0, normallyHidden: true }
+  },
+  computed: {
+    profit_margin: {
+      type: 'number',
+      dependencies: ['price', 'cost'],
+      compute: ({ attributes }) => {
+        if (!attributes.price || attributes.price === 0) return 0;
+        return ((attributes.price - attributes.cost) / attributes.price * 100).toFixed(2);
+      }
+    }
+  },
+  relationships: {
+    reviews: { hasMany: 'reviews', foreignKey: 'product_id' }
+  }
+});
+await api.resources.products.createKnexTable();
+
+// Define reviews resource with computed fields
+await api.addResource('reviews', {
+  schema: {
+    product_id: { type: 'id', belongsTo: 'products', as: 'product', required: true },
+    reviewer_name: { type: 'string', required: true },
+    rating: { type: 'number', required: true, min: 1, max: 5 },
+    comment: { type: 'string', max: 1000 },
+    helpful_votes: { type: 'number', default: 0 },
+    total_votes: { type: 'number', default: 0 }
+  },
+  computed: {
+    helpfulness_score: {
+      type: 'number',
+      dependencies: ['helpful_votes', 'total_votes'],
+      compute: ({ attributes }) => {
+        if (attributes.total_votes === 0) return null;
+        return ((attributes.helpful_votes / attributes.total_votes) * 100).toFixed(0);
+      }
+    }
+  }
+});
+await api.resources.reviews.createKnexTable();
+
+
+
+
+
+// Create a product
+const product = await api.resources.products.post({
+  name: 'Premium Headphones',
+  price: 199.99,
+  cost: 89.50
+});
+
+// Fetch the product - computed fields are automatically calculated
+const fetchedProduct = await api.resources.products.get({ id: product.id });
+console.log(fetchedProduct);
+// {
+//   id: '1',
+//   name: 'Premium Headphones',
+//   price: 199.99,
+//   profit_margin: '55.23'     // Computed: (199.99 - 89.50) / 199.99 * 100
+// }
+// Note: 'cost' is not included (normallyHidden)
+
+// Add some reviews
+const review1 = await api.resources.reviews.post({
+  product_id: product.id,
+  reviewer_name: 'Alice',
+  rating: 5,
+  comment: 'Excellent sound quality!',
+  helpful_votes: 45,
+  total_votes: 50
+});
+console.log('Review 1:', review1);
+
+
+const review2 = await api.resources.reviews.post({
+  product_id: product.id,
+  reviewer_name: 'Bob',
+  rating: 4,
+  comment: 'Good, but a bit pricey',
+  helpful_votes: 10,
+  total_votes: 25
+});
+console.log('Review 2:', review2);
+
+
+// Request only name and profit_margin
+const sparseProduct = await api.resources.products.get({
+  id: product.id,
+  queryParams: {
+    fields: { products: 'name,profit_margin' }
+  }
+});
+console.log('Product with sparse fields:', sparseProduct);
+
+
+const productWithCost = await api.resources.products.get({
+  id: product.id,
+  queryParams: {
+    fields: { products: 'name,cost,profit_margin' }
+  }
+});
+console.log('Product with sparse fields includig cost:', productWithCost);
+
+
+
+
+// Fetch product with reviews
+const productWithReviews = await api.resources.products.get({
+  id: product.id,
+  queryParams: {
+    include: ['reviews']
+  }
+});
+console.log('Product With Reviews:', productWithReviews);
+
+// Use sparse fieldsets on included resources
+const productWithSparseReviews = await api.resources.products.get({
+  id: product.id,
+  queryParams: {
+    include: ['reviews'],
+    fields: {
+      products: 'name,price',
+      reviews: 'reviewer_name,rating,helpfulness_score'  // Only these fields
+    }
+  }
+});
+console.log('Product With Sparse Reviews:', productWithSparseReviews);
+
+// Create a review with no votes
+const review3 = await api.resources.reviews.post({
+  product_id: product.id,
+  reviewer_name: 'Charlie',
+  rating: 3,
+  comment: 'Average product',
+  helpful_votes: 0,
+  total_votes: 0  // This will cause division by zero
+});
+
+const fetchedReviewWithError = await api.resources.reviews.get({ id: review3.id });
+console.log('Fetched review (with error in helpfulness score):', fetchedReviewWithError)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// Createthe express server and add the API's routes 
+const app = express();
+app.use(api.http.express.router);
+app.use(api.http.express.notFoundRouter);
+
+await knex.destroy();
+
+
+//app.listen(3000, () => {
+//  console.log('Express server started on port 3000. API available at http://localhost:3000/api');
+//});