json-rest-api 1.0.6 → 1.0.8

package/connectors_ideas/express-plugin.js

@@ -1,120 +0,0 @@
-/**
- * http-plugin-express.js
- * This plugin for Hooked API provides an HTTP layer using the Express.js framework.
- * It automatically generates JSON:API compliant RESTful routes for each scope
- * added to the API instance.
- */
-import { HookedApiError } from './hooked-api.js';
-import { handleApiError } from './error-handler.js';
-
-export const HttpExpressPlugin = {
-  name: 'http-express',
-
-  /**
-   * Installs the HTTP plugin, connecting the API to an Express app.
-   * @param {object} context - The installation context from Hooked API.
-   * @param {object} context.pluginOptions - Options passed during `api.use()`.
-   * @param {Express.Application} context.pluginOptions.http.app - The Express app instance. (Required)
-   * @param {string} [context.pluginOptions.http.prefix='/api'] - The URL prefix for all API routes.
-   * @param {Api} api - The API instance itself.
-   */
-  install(context, api) {
-    const { pluginOptions, log } = context;
-    const httpOptions = pluginOptions.http || {};
-    
-    const { app, prefix = '/api' } = httpOptions;
-
-    if (!app) {
-      throw new HookedApiError(
-        "The 'http-express' plugin requires an Express 'app' instance to be passed in the options. Example: api.use(HttpExpressPlugin, { http: { app: myExpressApp } })",
-        'CONFIGURATION_ERROR'
-      );
-    }
-
-    log.info(`Express HTTP plugin installed. Routes will be prefixed with '${prefix}'.`);
-
-    /**
-     * Creates a generic Express request handler for a specific API method.
-     * This factory function avoids code duplication for route handlers.
-     * @param {string} methodName - The name of the scope method to call (e.g., 'get', 'query').
-     * @returns {Function} An async Express route handler.
-     */
-    const _createRequestHandler = (methodName) => {
-      // This is an async function that Express 5 will handle correctly,
-      // automatically catching promise rejections and passing them to the error handler.
-      return async (req, res, next) => {
-        const { scopeName, id } = req.params;
-
-        try {
-          // 1. Translate Express req into the API method's specific params object.
-          const apiParams = {};
-
-          if (['get', 'put', 'patch', 'delete'].includes(methodName)) {
-            apiParams.id = id;
-          }
-          if (['query', 'get', 'post', 'put', 'patch'].includes(methodName)) {
-            // Express automatically parses simple query strings. For nested objects
-            // like `fields[articles]`, ensure the 'qs' query parser is enabled in your main app.
-            apiParams.queryParams = req.query;
-          }
-          if (['post', 'put', 'patch'].includes(methodName)) {
-            // Assumes `express.json()` body-parser middleware is used on the app.
-            apiParams.inputRecord = req.body;
-          }
-
-          log.debug(`Express request for ${scopeName}.${methodName}`, { id, query: req.query });
-
-          // 2. Execute the corresponding API method
-          const result = await api.scopes[scopeName][methodName](apiParams);
-
-          // 3. Send the successful HTTP response
-          switch (methodName) {
-            case 'post':
-              res.status(201).json(result);
-              break;
-            case 'delete':
-              res.status(204).send();
-              break;
-            default:
-              res.status(200).json(result);
-          }
-        } catch (error) {
-          // 4. Pass any errors to Express's next-tick error handler.
-          next(error);
-        }
-      };
-    };
-
-    /**
-     * Creates all the standard RESTful routes for a given scope.
-     * @param {string} scopeName - The name of the scope to create routes for.
-     */
-    const _createRoutesForScope = (scopeName) => {
-      // Use a new router for each scope to keep things clean.
-      const router = express.Router();
-      const basePath = `/${scopeName}`;
-      const singlePath = `${basePath}/:id`;
-
-      log.info(`Creating Express HTTP routes for scope: '${scopeName}'`);
-
-      router.get('/', _createRequestHandler('query'));
-      router.get('/:id', _createRequestHandler('get'));
-      router.post('/', _createRequestHandler('post'));
-      router.put('/:id', _createRequestHandler('put'));
-      router.patch('/:id', _createRequestHandler('patch'));
-      router.delete('/:id', _createRequestHandler('delete'));
-      
-      // Mount the scope's router on the main app at the correct prefix.
-      app.use(prefix, router);
-    };
-
-    // --- Main Logic: Wrap `addScope` to automate route creation ---
-    const originalAddScope = api.addScope;
-
-    api.addScope = (name, options, extras) => {
-      const result = originalAddScope.call(api, name, options, extras);
-      _createRoutesForScope(name);
-      return result;
-    };
-  }
-};

package/connectors_ideas/http-plugin.js

@@ -1,138 +0,0 @@
-/**
- * http-plugin.js
- * * This plugin for Hooked API provides a lightweight HTTP layer using Node.js's native `http` module.
- * It creates a server and automatically generates JSON:API compliant RESTful routes for each scope.
- *
- * It uses the 'qs' library to parse complex query strings, just like Express.
- * You'll need to install it: npm install qs
- */
-import http from 'http';
-import qs from 'qs'; // The same query string parser Express uses
-import { HookedApiError } from './hooked-api.js';
-import { handleApiError } from './error-handler.js';
-
-/**
- * A helper function to parse the JSON body from an incoming request.
- * @param {http.IncomingMessage} req - The request object.
- * @returns {Promise<object|null>} A promise that resolves with the parsed JSON object or null.
- */
-async function parseJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    if (req.method !== 'POST' && req.method !== 'PUT' && req.method !== 'PATCH') {
-      return resolve(null);
-    }
-
-    let body = '';
-    req.on('data', chunk => {
-      body += chunk.toString();
-    });
-    req.on('end', () => {
-      try {
-        resolve(body ? JSON.parse(body) : null);
-      } catch (error) {
-        reject(new HookedApiError('Invalid JSON in request body.', 'BAD_REQUEST'));
-      }
-    });
-    req.on('error', reject);
-  });
-}
-
-export const HttpPlugin = {
-  name: 'http',
-
-  install(context, api) {
-    const { pluginOptions, log } = context;
-    const httpOptions = pluginOptions.http || {};
-    const { port = 3000, prefix = '/api' } = httpOptions;
-
-    // This map will store our route handlers
-    const routes = new Map();
-
-    // A simple regex to match our API routes
-    // It captures the scope name and an optional ID
-    const routeRegex = new RegExp(`^${prefix}/([a-zA-Z0-9_-]+)(?:/([a-zA-Z0-9_-]+))?/?$`);
-
-    /**
-     * The main request handler for the http.Server.
-     * This function acts as our router.
-     */
-    const requestListener = async (req, res) => {
-      const { url, method } = req;
-      const [path, queryString] = url.split('?');
-
-      const match = path.match(routeRegex);
-
-      if (!match) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        return res.end(JSON.stringify({ errors: [{ status: '404', title: 'Not Found' }] }));
-      }
-
-      const [, scopeName, id] = match;
-
-      // Determine the API method based on the HTTP verb and presence of an ID
-      let apiMethodName;
-      if (method === 'GET') {
-        apiMethodName = id ? 'get' : 'query';
-      } else if (method === 'POST' && !id) {
-        apiMethodName = 'post';
-      } else if (method === 'PUT' && id) {
-        apiMethodName = 'put';
-      } else if (method === 'PATCH' && id) {
-        apiMethodName = 'patch';
-      } else if (method === 'DELETE' && id) {
-        apiMethodName = 'delete';
-      }
-
-      if (!apiMethodName || !api.scopes[scopeName]) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        return res.end(JSON.stringify({ errors: [{ status: '404', title: 'Not Found' }] }));
-      }
-
-      try {
-        // 1. Translate the native request into API method params
-        const apiParams = {};
-        
-        // Use 'qs' to parse the query string into a nested object
-        apiParams.queryParams = queryString ? qs.parse(queryString) : {};
-        apiParams.inputRecord = await parseJsonBody(req);
-        if (id) {
-          apiParams.id = id;
-        }
-
-        log.debug(`HTTP request for ${scopeName}.${apiMethodName}`, { id, query: apiParams.queryParams });
-
-        // 2. Execute the corresponding API method
-        const result = await api.scopes[scopeName][apiMethodName](apiParams);
-
-        // 3. Send the successful HTTP response
-        let statusCode = 200;
-        let responseBody = JSON.stringify(result);
-        
-        if (apiMethodName === 'post') {
-            statusCode = 201;
-        } else if (apiMethodName === 'delete') {
-            statusCode = 204;
-            responseBody = null;
-        }
-
-        res.setHeader('Content-Type', 'application/json');
-        res.writeHead(statusCode);
-        res.end(responseBody);
-
-      } catch (error) {
-        // 4. Handle any errors thrown by the API
-        // Note: The error handler now needs the `res` object directly
-        handleApiError(error, res, log);
-      }
-    };
-
-    // Create and start the HTTP server
-    const server = http.createServer(requestListener);
-    server.listen(port, () => {
-      log.info(`HTTP server started on http://localhost:${port}`);
-    });
-
-    // We no longer need to wrap addScope, as the router is dynamic.
-    // The plugin's job is simply to start the server.
-  }
-};

package/docs/examples/express-plugin.js

@@ -1,366 +0,0 @@
-import express from 'express';
-
-/**
- * Express Plugin for Hooked API
- * 
- * This plugin creates HTTP endpoints for your REST API by translating
- * Express HTTP requests into hooked-api method calls.
- * 
- * Features:
- * - Automatic route creation for all scopes (including dynamically added ones)
- * - JSON:API compliant request/response handling
- * - Query parameter parsing (include, fields, filter, sort, page)
- * - Error mapping to HTTP status codes
- * - Content type validation
- * - Middleware injection points
- * 
- * Usage:
- * ```javascript
- * import { ExpressPlugin } from './express-plugin.js';
- * 
- * const api = new Api({ name: 'my-api', version: '1.0.0' });
- * api.use(RestApiPlugin);
- * api.use(ExpressPlugin, {
- *   basePath: '/api',          // Default: '/api'
- *   strictContentType: true,   // Default: true
- *   requestSizeLimit: '10mb'   // Default: '1mb'
- * });
- * 
- * // In your Express app:
- * app.use(api.express.router);
- * // or
- * api.express.mount(app, '/v1');
- * ```
- */
-
-export const ExpressPlugin = {
-  name: 'express',
-  dependencies: ['rest-api'],
-  
-  install({ on, vars, helpers, pluginOptions, log, scopes, api }) {
-    const expressOptions = pluginOptions.express || {};
-    const basePath = expressOptions.basePath || '/api';
-    const strictContentType = expressOptions.strictContentType !== false;
-    const requestSizeLimit = expressOptions.requestSizeLimit || '1mb';
-    
-    // Track which scopes have routes created
-    const routesCreated = new Set();
-    
-    // Create Express router
-    const router = expressOptions.router || express.Router();
-    
-    // Add body parsing middleware
-    router.use(express.json({ 
-      limit: requestSizeLimit,
-      type: ['application/json', 'application/vnd.api+json']
-    }));
-    
-    // Content type validation middleware
-    if (strictContentType) {
-      router.use((req, res, next) => {
-        // Only validate for requests with bodies
-        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
-          const contentType = req.get('Content-Type');
-          
-          if (contentType && !contentType.includes('application/vnd.api+json') && !contentType.includes('application/json')) {
-            return res.status(415).json({
-              errors: [{
-                status: '415',
-                title: 'Unsupported Media Type',
-                detail: `Content-Type must be application/vnd.api+json or application/json`
-              }]
-            });
-          }
-        }
-        next();
-      });
-    }
-    
-    /**
-     * Query parameter parser
-     * Handles both standard notation (filter.status) and bracket notation (filter[status])
-     */
-    const parseQueryParams = (req) => {
-      const query = req.query;
-      const queryParams = {};
-      
-      // Parse include (comma-separated string to array)
-      if (query.include) {
-        queryParams.include = query.include.split(',').map(s => s.trim());
-      }
-      
-      // Parse fields (nested object)
-      queryParams.fields = {};
-      
-      // Parse filter (object)
-      queryParams.filters = {};
-      
-      // Parse page (object)
-      queryParams.page = {};
-      
-      // Process all query parameters
-      for (const key in query) {
-        const value = query[key];
-        
-        // Handle bracket notation: fields[articles]=title,body
-        let match;
-        if ((match = key.match(/^fields\[(.+)\]$/))) {
-          queryParams.fields[match[1]] = value;
-        } else if ((match = key.match(/^filter\[(.+)\]$/))) {
-          queryParams.filters[match[1]] = value;
-        } else if ((match = key.match(/^page\[(.+)\]$/))) {
-          queryParams.page[match[1]] = value;
-        }
-      }
-      
-      // Handle object notation if express query parser is configured
-      if (typeof query.fields === 'object' && !Array.isArray(query.fields)) {
-        Object.assign(queryParams.fields, query.fields);
-      }
-      if (typeof query.filters === 'object' && !Array.isArray(query.filters)) {
-        Object.assign(queryParams.filters, query.filters);
-      }
-      if (typeof query.page === 'object' && !Array.isArray(query.page)) {
-        Object.assign(queryParams.page, query.page);
-      }
-      
-      // Parse sort (comma-separated string to array)
-      if (query.sort) {
-        queryParams.sort = query.sort.split(',').map(s => s.trim());
-      }
-      
-      // Clean up empty objects
-      if (Object.keys(queryParams.fields).length === 0) delete queryParams.fields;
-      if (Object.keys(queryParams.filters).length === 0) delete queryParams.filters;
-      if (Object.keys(queryParams.page).length === 0) delete queryParams.page;
-      
-      return queryParams;
-    };
-    
-    /**
-     * Error handler - maps API errors to HTTP responses
-     */
-    const handleError = (error, res) => {
-      let status = 500;
-      let errorResponse = {
-        errors: [{
-          status: '500',
-          title: 'Internal Server Error',
-          detail: error.message
-        }]
-      };
-      
-      // Check for RestApiError types by code
-      if (error.code) {
-        switch (error.code) {
-          case 'REST_API_VALIDATION':
-            status = 422;
-            errorResponse.errors = [{
-              status: '422',
-              title: 'Validation Error',
-              detail: error.message,
-              source: error.details
-            }];
-            if (error.violations) {
-              errorResponse.errors = error.violations.map(v => ({
-                status: '422',
-                title: 'Validation Error',
-                detail: v.message,
-                source: { pointer: v.field }
-              }));
-            }
-            break;
-            
-          case 'REST_API_RESOURCE':
-            // Map subtype to status
-            switch (error.subtype) {
-              case 'not_found':
-                status = 404;
-                errorResponse.errors[0].status = '404';
-                errorResponse.errors[0].title = 'Not Found';
-                break;
-              case 'conflict':
-                status = 409;
-                errorResponse.errors[0].status = '409';
-                errorResponse.errors[0].title = 'Conflict';
-                break;
-              case 'forbidden':
-                status = 403;
-                errorResponse.errors[0].status = '403';
-                errorResponse.errors[0].title = 'Forbidden';
-                break;
-              default:
-                status = 400;
-                errorResponse.errors[0].status = '400';
-                errorResponse.errors[0].title = 'Bad Request';
-            }
-            break;
-            
-          case 'REST_API_PAYLOAD':
-            status = 400;
-            errorResponse.errors = [{
-              status: '400',
-              title: 'Bad Request',
-              detail: error.message,
-              source: { pointer: error.path }
-            }];
-            break;
-        }
-      }
-      
-      res.status(status).json(errorResponse);
-    };
-    
-    /**
-     * Creates request handler for a specific HTTP method
-     */
-    const createRequestHandler = (scopeName, methodName) => {
-      return async (req, res) => {
-        try {
-          const params = {};
-          
-          // Add ID parameter for single-resource operations
-          if (['get', 'put', 'patch', 'delete'].includes(methodName)) {
-            params.id = req.params.id;
-          }
-          
-          // Add query parameters
-          if (['query', 'get'].includes(methodName)) {
-            params.queryParams = parseQueryParams(req);
-          }
-          
-          // Add body for mutations
-          if (['post', 'put', 'patch'].includes(methodName)) {
-            params.inputRecord = req.body;
-            
-            // For PUT and PATCH, also parse query params
-            if (['put', 'patch'].includes(methodName)) {
-              params.queryParams = parseQueryParams(req);
-            }
-          }
-          
-          // Store Express request/response in params for plugins that need it
-          params._expressReq = req;
-          params._expressRes = res;
-          
-          log.debug(`HTTP ${req.method} ${req.path}`, { scopeName, methodName, params });
-          
-          // Call the API method
-          const scope = scopes[scopeName];
-          if (!scope) {
-            return handleError({ 
-              code: 'REST_API_RESOURCE', 
-              subtype: 'not_found',
-              message: `Scope '${scopeName}' not found`
-            }, res);
-          }
-          
-          const result = await scope[methodName](params);
-          
-          // Send response
-          res.set('Content-Type', 'application/vnd.api+json');
-          
-          switch (methodName) {
-            case 'post':
-              res.status(201).json(result);
-              break;
-            case 'delete':
-              res.sendStatus(204);
-              break;
-            default:
-              res.json(result);
-          }
-        } catch (error) {
-          handleError(error, res);
-        }
-      };
-    };
-    
-    /**
-     * Creates routes for a scope
-     */
-    const createRoutesForScope = (scopeName) => {
-      if (routesCreated.has(scopeName)) {
-        log.trace(`Routes already created for scope '${scopeName}'`);
-        return;
-      }
-      
-      const scopePath = `${basePath}/${scopeName}`;
-      
-      log.info(`Creating Express routes for scope '${scopeName}' at ${scopePath}`);
-      
-      // Apply any before middleware
-      const beforeMiddleware = expressOptions.middleware?.beforeScope?.[scopeName] || [];
-      
-      // GET /api/{scope} - Query collection
-      router.get(scopePath, ...beforeMiddleware, createRequestHandler(scopeName, 'query'));
-      
-      // GET /api/{scope}/{id} - Get single resource
-      router.get(`${scopePath}/:id`, ...beforeMiddleware, createRequestHandler(scopeName, 'get'));
-      
-      // POST /api/{scope} - Create resource
-      router.post(scopePath, ...beforeMiddleware, createRequestHandler(scopeName, 'post'));
-      
-      // PUT /api/{scope}/{id} - Replace resource
-      router.put(`${scopePath}/:id`, ...beforeMiddleware, createRequestHandler(scopeName, 'put'));
-      
-      // PATCH /api/{scope}/{id} - Update resource
-      router.patch(`${scopePath}/:id`, ...beforeMiddleware, createRequestHandler(scopeName, 'patch'));
-      
-      // DELETE /api/{scope}/{id} - Delete resource
-      router.delete(`${scopePath}/:id`, ...beforeMiddleware, createRequestHandler(scopeName, 'delete'));
-      
-      // Apply any after middleware
-      const afterMiddleware = expressOptions.middleware?.afterScope?.[scopeName] || [];
-      if (afterMiddleware.length > 0) {
-        router.use(scopePath, ...afterMiddleware);
-      }
-      
-      routesCreated.add(scopeName);
-    };
-    
-    // Listen for scope additions
-    addHook('scope:added', 'createExpressRoutes', {}, ({ context }) => {
-      createRoutesForScope(context.scopeName);
-    });
-    
-    // Create routes for any existing scopes
-    for (const scopeName of Object.keys(scopes)) {
-      createRoutesForScope(scopeName);
-    }
-    
-    // 404 handler for unmatched routes within the API
-    router.use((req, res) => {
-      res.status(404).json({
-        errors: [{
-          status: '404',
-          title: 'Not Found',
-          detail: `The requested endpoint ${req.method} ${req.path} does not exist`
-        }]
-      });
-    });
-    
-    // Apply global middleware if configured
-    let finalRouter = router;
-    if (expressOptions.middleware?.beforeAll) {
-      const globalRouter = express.Router();
-      globalRouter.use(...expressOptions.middleware.beforeAll);
-      globalRouter.use(router);
-      finalRouter = globalRouter;
-    }
-    
-    // Initialize express namespace
-    api.express = {};
-    
-    // Store router in express namespace
-    api.express.router = finalRouter;
-    
-    // Add convenient mounting method
-    api.express.mount = (app, path = '') => {
-      app.use(path, finalRouter);
-      log.info(`Express routes mounted at ${path || '/'}`);
-    };
-    
-    log.info('Express plugin initialized successfully');
-  }
-};