json-rest-api 1.0.29 → 2.1.0

package/docs/ONBOARDING.md

@@ -1,315 +0,0 @@
-# Developer Contribution Guide
-
-This guide is for developers who want to contribute to the json-rest-api codebase and understand its internal architecture.
-
-## Introduction
-
-json-rest-api is NOT a standalone library - it's a collection of plugins for [hooked-api](https://github.com/mercmobily/hooked-api). Each plugin extends the API with specific functionality by:
-
-- Adding methods to the API or to resources
-- Running hooks at strategic points
-- Listening to global events
-
-## What Each Plugin Does
-
-### Core Pattern
-Every plugin follows this structure:
-```javascript
-export const SomePlugin = {
-  name: 'plugin-name',
-  dependencies: ['other-plugin'], // optional
-  
-  install({ helpers, addScopeMethod, addApiMethod, vars, addHook, runHooks, on, /* ... */ }) {
-    // 1. Add methods (API-level or resource-level)
-    // 2. Add hooks to extend behavior
-    // 3. Listen to events from other plugins
-    // 4. Set up helpers for other plugins to use
-  }
-}
-```
-
-### Key Plugins
-- **RestApiPlugin**: Defines REST methods (get, post, patch, delete) and core hooks
-- **RestApiKnexPlugin**: Implements data helpers used by REST methods
-- **ExpressPlugin**: Creates HTTP endpoints by listening to route events
-
-## Resources vs Scopes
-
-An important concept: `api.resources` is just an alias to `api.scopes`:
-
-```javascript
-// In rest-api-plugin.js
-setScopeAlias('resources', 'addResource');
-```
-
-This means:
-- `api.resources` === `api.scopes`
-- `api.addResource()` === `api.addScope()`
-- "Resource" is REST terminology, "Scope" is hooked-api terminology
-- They're the same thing!
-
-## Global Hooks Run by the Library
-
-### Core hooked-api Hooks
-
-The hooked-api framework provides several system-level hooks that plugins can use:
-
-1. **scope:added** - Fired when a new scope (resource) is added via `api.addScope()` or `api.addResource()`
-   - This is the most important  hook for plugins that need to set up resources
-   - Receives context with `scopeName`, `scopeOptions`, and `vars`
-   - Used by rest-api-plugin to compile schemas, validate relationships, and register routes
-
-3. **plugin:installed** - Fired after each plugin is installed
-   - Receives the plugin name and configuration
-
-4. **error** - Global error handling hook
-   - Allows plugins to intercept and handle errors
-
-Example of using scope:added:
-```javascript
-// This is how rest-api-plugin uses scope:added to set up resources
-addHook('scope:added', 'compileResourceSchemas', {}, async ({ context, scopes, runHooks }) => {
-  // context.scopeName contains the resource name
-  // This runs for EVERY resource added to the API
-  const scope = scopes[context.scopeName];
-  await compileSchemas(scope, { context, runHooks });
-});
-```
-
-## Understanding vars and helpers in hooked-api
-
-### vars
-The `vars` object is a cascading configuration system:
-- Set at global level: `vars.someValue = 'default'`
-- Override at scope level: `scope.vars.someValue = 'specific'`
-- Values cascade: scope → global → undefined
-
-Example from rest-api-plugin:
-```javascript
-vars.queryDefaultLimit = restApiOptions.queryDefaultLimit || DEFAULT_QUERY_LIMIT
-vars.queryMaxLimit = restApiOptions.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT
-```
-
-### helpers
-Helpers are shared functions that plugins provide for others to use:
-- Pure functions (no side effects)
-- Set by one plugin, used by others
-- Example: Knex plugin provides `helpers.dataGet`, REST plugin uses it
-
-```javascript
-// Knex plugin sets:
-helpers.dataGet = async ({ scopeName, context }) => { /* ... */ }
-
-// REST plugin uses:
-context.record = await helpers.dataGet({ scopeName, context, runHooks })
-```
-
-## Plugin Event Listening and Method Definition
-
-Plugins interact through three mechanisms:
-
-### 1. Global API Methods
-```javascript
-// Define
-addApiMethod('addRoute', addRouteMethod);
-
-// Use
-api.addRoute({ method: 'GET', path: '/users', handler: myHandler })
-```
-
-### 2. Resource Methods
-```javascript
-// Define
-addScopeMethod('get', getMethod);
-
-// Use
-api.resources.users.get({ id: '123' })
-```
-
-### 3. Event Listening
-```javascript
-// Listen
-on('route:added', ({ route, scopeName }) => {
-  console.log(`Route added for ${scopeName}`)
-})
-
-// Emit (done internally by hooked-api)
-```
-
-## Relationship Between rest-api-plugin and rest-api-knex-plugin
-
-The relationship is complementary:
-
-### rest-api-plugin.js
-- Defines the REST API interface (methods like get, post, patch, delete)
-- Orchestrates the request flow through hooks
-- Validates inputs
-- Transforms between formats (JSON:API ↔ simplified)
-- Does NOT touch the database
-
-### rest-api-knex-plugin.js
-- Implements the data helpers that rest-api-plugin calls
-- Provides: `dataGet`, `dataPost`, `dataPatch`, `dataDelete`, etc.
-- Handles all database operations
-- Transforms between database format and JSON:API
-- Manages relationships at the database level
-
-Example flow:
-```javascript
-// In rest-api-plugin get method:
-await runHooks('beforeDataGet');
-context.record = await helpers.dataGet({ scopeName, context, runHooks });
-await runHooks('afterDataGet');
-
-// dataGet is provided by rest-api-knex-plugin
-```
-
-## API Methods Run Hooks for Extensibility
-
-Every REST method (get, post, patch, delete) follows this pattern:
-
-```javascript
-async function someMethod({ params, context, runHooks, /* ... */ }) {
-  // 1. Validate
-  validatePayload(params);
-  
-  // 2. Check permissions
-  await scope.checkPermissions({ method: 'get', /* ... */ });
-  
-  // 3. Run before hooks
-  await runHooks('beforeData');
-  await runHooks('beforeDataGet');
-  
-  // 4. Perform operation (via helper)
-  context.record = await helpers.dataGet({ /* ... */ });
-  
-  // 5. Run after hooks
-  await runHooks('enrichRecord');
-  
-  // 6. Run finish hooks
-  await runHooks('finish');
-  await runHooks('finishGet');
-  
-  return context.record;
-}
-```
-
-This allows plugins to hook into any phase of the request.
-
-## How addRoute() Works in Detail
-
-The `addRoute` implementation demonstrates the plugin communication pattern perfectly:
-
-### 1. API Method Definition (rest-api-plugin)
-```javascript
-// In rest-api-plugin.js
-addApiMethod('addRoute', addRouteMethod);
-
-// In add-route.js
-export default async ({ params, context, runHooks }) => {
-  const { method, path, handler } = params;
-  
-  // Validate
-  if (!method || !path || !handler) {
-    throw new ValidationError('Route requires method, path, and handler');
-  }
-  
-  // Copy params to context for hooks
-  Object.assign(context, params);
-  
-  // Run the hook - this notifies all listeners
-  await runHooks('addRoute');
-  
-  return { registered: true, method, path };
-}
-```
-
-### 2. Route Registration (registerScopeRoutes hook)
-When a resource is added, routes are automatically registered:
-```javascript
-// In register-scope-routes.js
-await api.addRoute({
-  method: 'GET',
-  path: `${basePath}/${scopeName}`,
-  handler: createRouteHandler(scopeName, 'query')
-});
-
-await api.addRoute({
-  method: 'GET',
-  path: `${basePath}/${scopeName}/:id`,
-  handler: createRouteHandler(scopeName, 'get')
-});
-// ... etc for POST, PUT, PATCH, DELETE
-```
-
-### 3. Transport Implementation (express-plugin)
-The Express plugin listens for the addRoute hook:
-```javascript
-// In express-plugin.js
-addHook('addRoute', 'expressRouteCreator', {}, async ({ context }) => {
-  const { method, path, handler } = context;
-  
-  // Convert to Express format
-  const expressMethod = method.toLowerCase();
-  const expressPath = convertToExpressPattern(path);
-  
-  // Create Express route
-  router[expressMethod](expressPath, async (req, res) => {
-    try {
-      // Call the generic handler
-      const result = await handler({
-        queryString: req.url.split('?')[1] || '',
-        headers: req.headers,
-        params: req.params,
-        body: req.body,
-        context: createContext(req, res, 'express')
-      });
-      
-      // Send response
-      res.status(200).json(result);
-    } catch (error) {
-      // Handle errors
-      handleError(error, req, res);
-    }
-  });
-});
-```
-
-### 4. The Handler Function
-The handler passed to addRoute is transport-agnostic:
-```javascript
-const createRouteHandler = (scopeName, methodName) => {
-  return async ({ queryString, headers, params, body, context }) => {
-    const scope = api.scopes[scopeName];
-    
-    // Build method parameters
-    const methodParams = {};
-    if (params.id) methodParams.id = params.id;
-    if (body) methodParams.inputRecord = body;
-    if (queryString) methodParams.queryParams = parseJsonApiQuery(queryString);
-    
-    // Call the resource method
-    return await scope[methodName](methodParams, context);
-  };
-};
-```
-
-This architecture means:
-- The REST plugin doesn't know about Express
-- The Express plugin doesn't know about REST semantics
-- They communicate through the addRoute hook
-- Other transports (Fastify, Koa) can implement the same hook
-
-## Summary
-
-The power of json-rest-api comes from:
-1. **Plugin composition** - Each plugin does one thing well
-2. **Hook-based extensibility** - Any behavior can be extended
-3. **Transport agnosticism** - REST logic is separate from HTTP handling
-4. **Pure helpers** - Data operations are predictable and testable
-
-When contributing:
-- Identify which plugin your change belongs in
-- Use hooks to extend, don't modify core code
-- Keep helpers pure
-- Follow the established patterns

package/docs/_config.yml

@@ -1,36 +0,0 @@
-title: JSON REST API
-description: A lightweight, plugin-based REST API framework for Node.js
-baseurl: "/json-rest-api"
-url: "https://mobily-enterprises.github.io"
-
-plugins:
-  - jekyll-relative-links
-  - jekyll-seo-tag
-
-relative_links:
-  enabled: true
-  collections: true
-
-include:
-  - README.md
-
-exclude:
-  - vendor/
-  - Gemfile
-  - Gemfile.lock
-
-highlighter: rouge
-
-markdown: kramdown
-kramdown:
-  input: GFM
-  syntax_highlighter: rouge
-  syntax_highlighter_opts:
-    block:
-      line_numbers: false
-
-defaults:
-  - scope:
-      path: ""
-    values:
-      layout: "default"

package/docs/_layouts/default.html

@@ -1,123 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{% if page.title %}{{ page.title }} - {% endif %}{{ site.title }}</title>
-  <meta name="description" content="{{ page.description | default: site.description }}">
-  <link rel="icon" type="image/svg+xml" href="{{ '/favicon.svg' | relative_url }}">
-  <link rel="apple-touch-icon" href="{{ '/apple-touch-icon.svg' | relative_url }}">
-  <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
-  {% seo %}
-  <style>
-    .highlight {
-      position: relative;
-    }
-    pre {
-      position: relative;
-    }
-    .copy-button {
-      position: absolute;
-      top: 8px;
-      right: 8px;
-      padding: 6px 12px;
-      font-size: 12px;
-      font-weight: 500;
-      background: rgba(255, 255, 255, 0.9);
-      border: 1px solid rgba(0, 0, 0, 0.1);
-      border-radius: 6px;
-      cursor: pointer;
-      transition: all 0.2s;
-      color: #333;
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-    }
-    .copy-button:hover {
-      background: rgba(255, 255, 255, 1);
-      border-color: rgba(0, 0, 0, 0.2);
-      transform: translateY(-1px);
-      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
-    }
-    .copy-button:active {
-      transform: translateY(0);
-      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
-    }
-    .copy-button.copied {
-      background: #10b981;
-      color: white;
-      border-color: #10b981;
-    }
-  </style>
-</head>
-<body>
-  <header>
-    <div class="wrapper">
-      <h1><a href="{{ '/' | relative_url }}">{{ site.title }}</a></h1>
-      <nav>
-        <a href="{{ '/QUICKSTART' | relative_url }}">Quick Start</a>
-        <a href="{{ '/GUIDE' | relative_url }}">Guide</a>
-        <a href="{{ '/API' | relative_url }}">API Reference</a>
-        <a href="{{ '/ONBOARDING' | relative_url }}">Contribute</a>
-        <a href="{{ '/COMPARISON' | relative_url }}">Why json-rest-api</a>
-      </nav>
-    </div>
-  </header>
-
-  <main>
-    <div class="page-content">
-      {{ content }}
-    </div>
-  </main>
-
-  <footer>
-    <div class="wrapper">
-      <p>{{ site.title }} &copy; {{ 'now' | date: '%Y' }} - MIT License</p>
-    </div>
-  </footer>
-
-  <script>
-    document.addEventListener('DOMContentLoaded', function() {
-      // Add copy buttons to all code blocks
-      document.querySelectorAll('pre').forEach(function(pre) {
-        // Skip if button already exists
-        if (pre.querySelector('.copy-button')) return;
-        
-        const button = document.createElement('button');
-        button.className = 'copy-button';
-        button.textContent = 'Copy';
-        button.addEventListener('click', function() {
-          const code = pre.querySelector('code') ? 
-            pre.querySelector('code').textContent : 
-            pre.textContent;
-          
-          navigator.clipboard.writeText(code).then(function() {
-            button.textContent = '✓ Copied!';
-            button.classList.add('copied');
-            setTimeout(() => {
-              button.textContent = 'Copy';
-              button.classList.remove('copied');
-            }, 2000);
-          }).catch(function() {
-            // Fallback for older browsers
-            const textarea = document.createElement('textarea');
-            textarea.value = code;
-            textarea.style.position = 'fixed';
-            textarea.style.opacity = '0';
-            document.body.appendChild(textarea);
-            textarea.select();
-            document.execCommand('copy');
-            document.body.removeChild(textarea);
-            
-            button.textContent = '✓ Copied!';
-            button.classList.add('copied');
-            setTimeout(() => {
-              button.textContent = 'Copy';
-              button.classList.remove('copied');
-            }, 2000);
-          });
-        });
-        pre.appendChild(button);
-      });
-    });
-  </script>
-</body>
-</html>

package/docs/apple-touch-icon.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180">
-  <rect width="180" height="180" rx="20" fill="#1976d2"/>
-  <text x="90" y="120" font-family="system-ui, -apple-system, sans-serif" font-size="80" font-weight="bold" text-anchor="middle" fill="white">API</text>
-</svg>