json-rest-api 1.0.0 → 1.0.2

package/examples/express-plugin.js

@@ -0,0 +1,366 @@
+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.filter = {};
+      
+      // 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.filter[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.filter === 'object' && !Array.isArray(query.filter)) {
+        Object.assign(queryParams.filter, query.filter);
+      }
+      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.filter).length === 0) delete queryParams.filter;
+      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
+    on('scope:added', 'createExpressRoutes', ({ eventData }) => {
+      createRoutesForScope(eventData.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');
+  }
+};

package/examples/file-upload-example.js

@@ -0,0 +1,205 @@
+/**
+ * File Upload Example
+ * 
+ * This example demonstrates how to use the file handling plugin
+ * with various storage backends and protocols.
+ */
+
+import { Api } from 'hooked-api';
+import { 
+  RestApiPlugin, 
+  FileHandlingPlugin,
+  ExpressPlugin,
+  HttpPlugin 
+} from '../index.js';
+import { LocalStorage } from '../plugins/storage/local-storage.js';
+import { S3Storage } from '../plugins/storage/s3-storage.js';
+import express from 'express';
+
+// Create API instance
+const api = new Api({
+  name: 'file-upload-example',
+  version: '1.0.0'
+});
+
+// Configure storage backends
+const localStorage = new LocalStorage({
+  directory: './uploads/images',
+  baseUrl: 'http://localhost:3000/uploads/images'
+});
+
+const s3Storage = new S3Storage({
+  bucket: 'my-app-uploads',
+  region: 'us-east-1',
+  prefix: 'user-uploads/',
+  mockMode: true // Using mock mode for this example
+});
+
+// Use plugins - order matters!
+api.use(RestApiPlugin);
+api.use(FileHandlingPlugin); // Must come after RestApiPlugin
+api.use(ExpressPlugin, {
+  fileParser: 'busboy', // or 'formidable'
+  fileParserOptions: {
+    limits: { 
+      fileSize: 10 * 1024 * 1024, // 10MB
+      files: 5 // Max 5 files per request
+    }
+  }
+});
+
+// Define schemas with file fields
+api.addScope('users', {
+  schema: {
+    name: { type: 'string', required: true },
+    email: { type: 'string', required: true },
+    avatar: {
+      type: 'file',
+      storage: localStorage,
+      accepts: ['image/jpeg', 'image/png', 'image/gif'],
+      maxSize: '5mb',
+      required: false
+    }
+  }
+});
+
+api.addScope('documents', {
+  schema: {
+    title: { type: 'string', required: true },
+    description: { type: 'string' },
+    file: {
+      type: 'file',
+      storage: s3Storage,
+      accepts: ['application/pdf', 'application/msword', 'text/plain'],
+      maxSize: '50mb',
+      required: true
+    },
+    thumbnail: {
+      type: 'file',
+      storage: localStorage,
+      accepts: ['image/*'],
+      maxSize: '2mb',
+      required: false
+    }
+  }
+});
+
+// Add storage helpers for demonstration
+api.helpers.dataPost = async ({ scopeName, inputRecord }) => {
+  console.log(`Creating ${scopeName}:`, inputRecord);
+  
+  // Simulate database save
+  const id = Math.random().toString(36).substring(7);
+  
+  return {
+    data: {
+      type: scopeName,
+      id: id,
+      attributes: inputRecord.data.attributes
+    }
+  };
+};
+
+api.helpers.dataGet = async ({ scopeName, id }) => {
+  // Simulate database fetch
+  return {
+    data: {
+      type: scopeName,
+      id: id,
+      attributes: {
+        // Would normally fetch from database
+      }
+    }
+  };
+};
+
+// Create Express app
+const app = express();
+
+// Serve uploaded files statically
+app.use('/uploads', express.static('./uploads'));
+
+// Mount API
+api.express.mount(app, '/api');
+
+// Add a simple upload form for testing
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>File Upload Example</title>
+    </head>
+    <body>
+      <h1>File Upload Example</h1>
+      
+      <h2>Create User with Avatar</h2>
+      <form action="/api/users" method="POST" enctype="multipart/form-data">
+        <div>
+          <label>Name: <input name="name" required></label>
+        </div>
+        <div>
+          <label>Email: <input name="email" type="email" required></label>
+        </div>
+        <div>
+          <label>Avatar: <input name="avatar" type="file" accept="image/*"></label>
+        </div>
+        <button type="submit">Create User</button>
+      </form>
+      
+      <h2>Upload Document</h2>
+      <form action="/api/documents" method="POST" enctype="multipart/form-data">
+        <div>
+          <label>Title: <input name="title" required></label>
+        </div>
+        <div>
+          <label>Description: <textarea name="description"></textarea></label>
+        </div>
+        <div>
+          <label>Document: <input name="file" type="file" accept=".pdf,.doc,.txt" required></label>
+        </div>
+        <div>
+          <label>Thumbnail: <input name="thumbnail" type="file" accept="image/*"></label>
+        </div>
+        <button type="submit">Upload Document</button>
+      </form>
+      
+      <hr>
+      <p>Note: The form data will be automatically converted to JSON:API format by the file handling plugin.</p>
+    </body>
+    </html>
+  `);
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`File upload example running at http://localhost:${PORT}`);
+  console.log(`API endpoints:`);
+  console.log(`  POST http://localhost:${PORT}/api/users (with multipart form data)`);
+  console.log(`  POST http://localhost:${PORT}/api/documents (with multipart form data)`);
+});
+
+// Example cURL commands:
+/*
+# Upload user with avatar
+curl -X POST http://localhost:3000/api/users \
+  -F "name=John Doe" \
+  -F "email=john@example.com" \
+  -F "avatar=@/path/to/avatar.jpg"
+
+# Upload document with thumbnail
+curl -X POST http://localhost:3000/api/documents \
+  -F "title=Important Document" \
+  -F "description=This is a very important document" \
+  -F "file=@/path/to/document.pdf" \
+  -F "thumbnail=@/path/to/thumbnail.png"
+
+# The file handling plugin will:
+# 1. Detect the multipart upload
+# 2. Parse the files
+# 3. Validate file types and sizes
+# 4. Upload to configured storage
+# 5. Replace file fields with URLs
+# 6. Convert to JSON:API format
+*/

package/examples/filename-strategies.js

@@ -0,0 +1,140 @@
+/**
+ * Filename Strategy Examples
+ * 
+ * Different approaches to handling uploaded filenames
+ */
+
+import { LocalStorage } from '../plugins/storage/local-storage.js';
+
+// Strategy 1: Random hash (most secure, default)
+const hashStorage = new LocalStorage({
+  directory: './uploads/images',
+  baseUrl: '/uploads/images',
+  nameStrategy: 'hash',
+  preserveExtension: true
+});
+// Uploads as: "a7f8d9e2b4c6e1f3.jpg"
+
+// Strategy 2: Timestamp-based (sortable)
+const timestampStorage = new LocalStorage({
+  directory: './uploads/documents',
+  baseUrl: '/uploads/documents',
+  nameStrategy: 'timestamp',
+  preserveExtension: true
+});
+// Uploads as: "1672531200000_a8f9.pdf"
+
+// Strategy 3: Sanitized original (user-friendly)
+const originalStorage = new LocalStorage({
+  directory: './uploads/user-files',
+  baseUrl: '/uploads/user-files',
+  nameStrategy: 'original',
+  preserveExtension: true,
+  maxFilenameLength: 100
+});
+// "My Resume 2024!.pdf" uploads as: "My_Resume_2024_.pdf"
+// Duplicates become: "My_Resume_2024_1.pdf", "My_Resume_2024_2.pdf"
+
+// Strategy 4: Custom naming function
+const customStorage = new LocalStorage({
+  directory: './uploads/profiles',
+  baseUrl: '/uploads/profiles',
+  nameStrategy: 'custom',
+  nameGenerator: async (file) => {
+    // Example: user ID + timestamp
+    const userId = file.userId || 'anonymous';
+    const timestamp = Date.now();
+    return `user_${userId}_${timestamp}`;
+  }
+});
+// Uploads as: "user_12345_1672531200000.jpg"
+
+// Strategy 5: High security (no extensions)
+const secureStorage = new LocalStorage({
+  directory: './uploads/secure',
+  baseUrl: '/uploads/secure',
+  nameStrategy: 'hash',
+  preserveExtension: false  // Store as .bin
+});
+// All files upload as: "a7f8d9e2b4c6e1f3.bin"
+
+// Strategy 6: Whitelist extensions
+const whitelistStorage = new LocalStorage({
+  directory: './uploads/images',
+  baseUrl: '/uploads/images',
+  nameStrategy: 'hash',
+  preserveExtension: true,
+  allowedExtensions: ['.jpg', '.jpeg', '.png', '.gif', '.webp']
+});
+// Only allows specific image extensions
+
+// Example: Organization by date
+const dateOrganizedStorage = new LocalStorage({
+  directory: './uploads',
+  baseUrl: '/uploads',
+  nameStrategy: 'custom',
+  nameGenerator: async (file) => {
+    const date = new Date();
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const random = crypto.randomBytes(8).toString('hex');
+    
+    // Create date-based subdirectory
+    const dateDir = `${year}/${month}/${day}`;
+    await fs.mkdir(path.join('./uploads', dateDir), { recursive: true });
+    
+    return `${dateDir}/${random}`;
+  }
+});
+// Uploads as: "2024/01/15/a7f8d9e2b4c6e1f3.jpg"
+
+// Example: Content-based naming
+const contentStorage = new LocalStorage({
+  directory: './uploads/media',
+  baseUrl: '/uploads/media',
+  nameStrategy: 'custom',
+  nameGenerator: async (file) => {
+    // Generate hash of file content for deduplication
+    const crypto = require('crypto');
+    const hash = crypto.createHash('sha256');
+    hash.update(file.data);
+    const contentHash = hash.digest('hex').substring(0, 16);
+    
+    // Prefix by type
+    const typePrefix = file.mimetype.startsWith('image/') ? 'img' :
+                      file.mimetype.startsWith('video/') ? 'vid' :
+                      file.mimetype.startsWith('audio/') ? 'aud' : 'doc';
+    
+    return `${typePrefix}_${contentHash}`;
+  }
+});
+// Uploads as: "img_a7f8d9e2b4c6e1f3.jpg" (same file always gets same name)
+
+// Example usage in schema
+api.addScope('products', {
+  schema: {
+    name: { type: 'string', required: true },
+    
+    // Product images need user-friendly names
+    mainImage: {
+      type: 'file',
+      storage: originalStorage,
+      accepts: ['image/*']
+    },
+    
+    // Technical documents use timestamp
+    manual: {
+      type: 'file',
+      storage: timestampStorage,
+      accepts: ['application/pdf']
+    },
+    
+    // User uploads use high security
+    attachment: {
+      type: 'file',
+      storage: secureStorage,
+      accepts: ['*']
+    }
+  }
+});