json-rest-api 0.1.0 → 1.0.0

package/plugins/http.js

@@ -0,0 +1,273 @@
+import express from 'express';
+
+/**
+ * HTTP plugin for JSON REST API with JSON:API compliance
+ */
+export const HTTPPlugin = {
+  install(api, options = {}) {
+    const router = express.Router();
+    api.router = router;
+
+    // Middleware for JSON parsing
+    router.use(express.json({
+      type: ['application/json', 'application/vnd.api+json']
+    }));
+
+    // Base path for all routes
+    const basePath = options.basePath || '/api';
+
+    // Helper to parse JSON:API request body
+    const parseJsonApiBody = (body) => {
+      if (body.data) {
+        if (body.data.attributes) {
+          // JSON:API format
+          return { ...body.data.attributes, id: body.data.id };
+        }
+        // Assume data is the actual data
+        return body.data;
+      }
+      // Plain format
+      return body;
+    };
+
+    // Helper to format JSON:API errors
+    const formatErrors = (errors, status = 400) => {
+      if (!Array.isArray(errors)) {
+        errors = [errors];
+      }
+
+      return {
+        errors: errors.map(err => {
+          if (err.status) return err; // Already formatted
+          
+          return {
+            status: String(status),
+            title: err.code || 'Error',
+            detail: err.message || String(err),
+            source: err.field ? { pointer: `/data/attributes/${err.field}` } : undefined
+          };
+        })
+      };
+    };
+
+    // Parse query parameters
+    const parseQueryParams = (req) => {
+      const params = {
+        filter: {},
+        sort: req.query.sort,
+        page: {
+          size: req.query['page[size]'] || req.query.pageSize,
+          number: req.query['page[number]'] || req.query.page
+        },
+        include: req.query.include,
+        fields: {}
+      };
+
+      // Parse filters
+      for (const [key, value] of Object.entries(req.query)) {
+        if (key.startsWith('filter[') && key.endsWith(']')) {
+          const filterKey = key.slice(7, -1);
+          params.filter[filterKey] = value;
+        } else if (key.startsWith('fields[') && key.endsWith(']')) {
+          const fieldType = key.slice(7, -1);
+          params.fields[fieldType] = value.split(',');
+        }
+      }
+
+      // Legacy filter support
+      if (Object.keys(params.filter).length === 0) {
+        // Copy non-standard query params as filters
+        for (const [key, value] of Object.entries(req.query)) {
+          if (!['sort', 'page', 'pageSize', 'include', 'fields'].includes(key) &&
+              !key.includes('[')) {
+            params.filter[key] = value;
+          }
+        }
+      }
+
+      return params;
+    };
+
+    // Build links for pagination
+    const buildLinks = (req, params, meta) => {
+      const links = {};
+      const baseUrl = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`;
+      const queryParams = new URLSearchParams(req.query);
+
+      // Self link
+      links.self = `${baseUrl}?${queryParams}`;
+
+      if (meta.totalPages > 1) {
+        const currentPage = meta.pageNumber;
+
+        // First page
+        queryParams.set('page[number]', '1');
+        links.first = `${baseUrl}?${queryParams}`;
+
+        // Last page
+        queryParams.set('page[number]', String(meta.totalPages));
+        links.last = `${baseUrl}?${queryParams}`;
+
+        // Previous page
+        if (currentPage > 1) {
+          queryParams.set('page[number]', String(currentPage - 1));
+          links.prev = `${baseUrl}?${queryParams}`;
+        }
+
+        // Next page
+        if (currentPage < meta.totalPages) {
+          queryParams.set('page[number]', String(currentPage + 1));
+          links.next = `${baseUrl}?${queryParams}`;
+        }
+      }
+
+      return links;
+    };
+
+    // Version-aware routing
+    if (api.options.name && api.options.version) {
+      // Add version info to all responses
+      router.use((req, res, next) => {
+        res.set('API-Version', api.options.version);
+        next();
+      });
+    }
+    
+    // Routes
+    
+    // GET collection
+    router.get('/:type', async (req, res) => {
+      try {
+        const params = parseQueryParams(req);
+        const result = await api.query(params, {
+          type: req.params.type,
+          ...options.typeOptions?.[req.params.type]
+        });
+
+        // Add links
+        if (result.meta) {
+          result.links = buildLinks(req, params, result.meta);
+        }
+
+        res.json(result);
+      } catch (error) {
+        const status = error.status || 400;
+        res.status(status).json(formatErrors(error.errors || error, status));
+      }
+    });
+
+    // GET single resource
+    router.get('/:type/:id', async (req, res) => {
+      try {
+        const result = await api.get(req.params.id, {
+          type: req.params.type,
+          ...options.typeOptions?.[req.params.type]
+        });
+
+        if (!result.data) {
+          res.status(404).json(formatErrors({
+            message: 'Resource not found',
+            code: 'NOT_FOUND'
+          }, 404));
+          return;
+        }
+
+        res.json(result);
+      } catch (error) {
+        const status = error.status || 400;
+        res.status(status).json(formatErrors(error.errors || error, status));
+      }
+    });
+
+    // POST new resource
+    router.post('/:type', async (req, res) => {
+      try {
+        const data = parseJsonApiBody(req.body);
+        const result = await api.insert(data, {
+          type: req.params.type,
+          ...options.typeOptions?.[req.params.type]
+        });
+
+        res.status(201)
+           .location(`${basePath}/${req.params.type}/${result.data.id}`)
+           .json(result);
+      } catch (error) {
+        const status = error.status || 400;
+        res.status(status).json(formatErrors(error.errors || error, status));
+      }
+    });
+
+    // PATCH update resource
+    router.patch('/:type/:id', async (req, res) => {
+      try {
+        const data = parseJsonApiBody(req.body);
+        const result = await api.update(req.params.id, data, {
+          type: req.params.type,
+          ...options.typeOptions?.[req.params.type]
+        });
+
+        if (!result.data) {
+          res.status(404).json(formatErrors({
+            message: 'Resource not found',
+            code: 'NOT_FOUND'
+          }, 404));
+          return;
+        }
+
+        res.json(result);
+      } catch (error) {
+        const status = error.status || 400;
+        res.status(status).json(formatErrors(error.errors || error, status));
+      }
+    });
+
+    // DELETE resource
+    router.delete('/:type/:id', async (req, res) => {
+      try {
+        await api.delete(req.params.id, {
+          type: req.params.type,
+          ...options.typeOptions?.[req.params.type]
+        });
+
+        res.status(204).end();
+      } catch (error) {
+        const status = error.status || 400;
+        res.status(status).json(formatErrors(error.errors || error, status));
+      }
+    });
+
+    // OPTIONS for CORS
+    router.options('*', (req, res) => {
+      res.header('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+      res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+      res.status(204).end();
+    });
+
+    // Mount router on Express app if provided
+    if (options.app) {
+      options.app.use(basePath, router);
+    }
+
+    // Add method to manually mount router
+    api.mount = (app, path = basePath) => {
+      app.use(path, router);
+      return api;
+    };
+
+    // Add middleware support
+    api.useMiddleware = (middleware) => {
+      router.use(middleware);
+      return api;
+    };
+
+    // Add route-specific middleware
+    api.useRouteMiddleware = (method, path, ...middlewares) => {
+      // Store middleware to be applied when routes are defined
+      if (!api._routeMiddlewares) {
+        api._routeMiddlewares = [];
+      }
+      api._routeMiddlewares.push({ method, path, middlewares });
+      return api;
+    };
+  }
+};

package/plugins/logging.js

@@ -0,0 +1,255 @@
+/**
+ * Logging plugin implementing structured logging best practices
+ */
+export const LoggingPlugin = {
+  install(api, options = {}) {
+    const defaultOptions = {
+      level: process.env.LOG_LEVEL || 'info',
+      format: 'json', // 'json' or 'pretty'
+      includeRequest: true,
+      includeResponse: true,
+      includeTiming: true,
+      sensitiveFields: ['password', 'token', 'secret', 'authorization'],
+      logger: console, // Can be replaced with winston, bunyan, etc.
+      ...options
+    };
+
+    const levels = {
+      error: 0,
+      warn: 1,
+      info: 2,
+      debug: 3
+    };
+
+    // Create structured logger
+    const log = (level, message, meta = {}) => {
+      if (levels[level] > levels[defaultOptions.level]) return;
+
+      const timestamp = new Date().toISOString();
+      const logEntry = {
+        timestamp,
+        level,
+        message,
+        ...meta
+      };
+
+      // Remove sensitive data
+      const sanitized = sanitizeLogData(logEntry, defaultOptions.sensitiveFields);
+
+      if (defaultOptions.format === 'json') {
+        defaultOptions.logger[level](JSON.stringify(sanitized));
+      } else {
+        defaultOptions.logger[level](`[${timestamp}] ${level.toUpperCase()}: ${message}`, meta);
+      }
+    };
+
+    // Add logging methods to API
+    api.log = {
+      error: (message, meta) => log('error', message, meta),
+      warn: (message, meta) => log('warn', message, meta),
+      info: (message, meta) => log('info', message, meta),
+      debug: (message, meta) => log('debug', message, meta)
+    };
+
+    // Log all operations
+    const timings = new WeakMap();
+
+    // Start timing
+    api.hook('beforeValidate', async (context) => {
+      if (defaultOptions.includeTiming) {
+        timings.set(context, Date.now());
+      }
+
+      if (defaultOptions.includeRequest) {
+        api.log.info(`${context.method.toUpperCase()} ${context.options.type}`, {
+          operation: context.method,
+          type: context.options.type,
+          id: context.id,
+          requestId: context.options.requestId,
+          userId: context.options.userId,
+          data: context.method === 'query' ? context.params : context.data
+        });
+      }
+    });
+
+    // Log successful operations
+    api.hook('beforeSend', async (context) => {
+      const duration = defaultOptions.includeTiming && timings.has(context) 
+        ? Date.now() - timings.get(context) 
+        : undefined;
+
+      if (defaultOptions.includeResponse) {
+        api.log.info(`${context.method.toUpperCase()} ${context.options.type} completed`, {
+          operation: context.method,
+          type: context.options.type,
+          id: context.id || context.result?.id,
+          requestId: context.options.requestId,
+          userId: context.options.userId,
+          duration,
+          resultCount: context.results?.length
+        });
+      }
+
+      // Clean up timing
+      if (timings.has(context)) {
+        timings.delete(context);
+      }
+    });
+
+    // Log errors
+    api.hook('afterValidate', async (context) => {
+      if (context.errors.length > 0) {
+        api.log.warn('Validation errors', {
+          operation: context.method,
+          type: context.options.type,
+          errors: context.errors,
+          requestId: context.options.requestId,
+          userId: context.options.userId
+        });
+      }
+    });
+
+    // Log database operations
+    if (api.mysqlPools) {
+      // Wrap MySQL query method to add logging
+      const originalGetConnection = api.getConnection;
+      api.getConnection = (name) => {
+        const conn = originalGetConnection.call(api, name);
+        
+        // Wrap the query method
+        const originalQuery = conn.pool.query.bind(conn.pool);
+        conn.pool.query = async (sql, params) => {
+          const start = Date.now();
+          
+          try {
+            const result = await originalQuery(sql, params);
+            
+            api.log.debug('SQL query executed', {
+              sql: sql.substring(0, 200), // Truncate long queries
+              duration: Date.now() - start,
+              rowCount: result[0]?.length
+            });
+            
+            return result;
+          } catch (error) {
+            api.log.error('SQL query failed', {
+              sql: sql.substring(0, 200),
+              error: error.message,
+              duration: Date.now() - start
+            });
+            throw error;
+          }
+        };
+        
+        return conn;
+      };
+    }
+
+    // HTTP request logging
+    if (api.router) {
+      api.router.use((req, res, next) => {
+        const start = Date.now();
+        const requestId = req.headers['x-request-id'] || generateId();
+        
+        // Add request ID to context
+        req.requestId = requestId;
+        
+        // Log request
+        api.log.info('HTTP request', {
+          method: req.method,
+          url: req.url,
+          ip: req.ip,
+          userAgent: req.headers['user-agent'],
+          requestId
+        });
+
+        // Log response
+        const originalSend = res.send;
+        res.send = function(data) {
+          res.send = originalSend;
+          
+          api.log.info('HTTP response', {
+            method: req.method,
+            url: req.url,
+            status: res.statusCode,
+            duration: Date.now() - start,
+            requestId
+          });
+          
+          return res.send(data);
+        };
+
+        next();
+      });
+    }
+
+    // Audit logging for sensitive operations
+    api.hook('afterInsert', async (context) => {
+      if (options.auditLog) {
+        api.log.info('Resource created', {
+          audit: true,
+          operation: 'create',
+          type: context.options.type,
+          id: context.result?.id,
+          userId: context.options.userId,
+          changes: context.data
+        });
+      }
+    });
+
+    api.hook('afterUpdate', async (context) => {
+      if (options.auditLog) {
+        api.log.info('Resource updated', {
+          audit: true,
+          operation: 'update',
+          type: context.options.type,
+          id: context.id,
+          userId: context.options.userId,
+          changes: context.data
+        });
+      }
+    });
+
+    api.hook('afterDelete', async (context) => {
+      if (options.auditLog) {
+        api.log.info('Resource deleted', {
+          audit: true,
+          operation: 'delete',
+          type: context.options.type,
+          id: context.id,
+          userId: context.options.userId
+        });
+      }
+    });
+  }
+};
+
+// Helper to sanitize sensitive data
+function sanitizeLogData(data, sensitiveFields) {
+  if (typeof data !== 'object' || data === null) return data;
+  
+  const sanitized = Array.isArray(data) ? [] : {};
+  
+  for (const [key, value] of Object.entries(data)) {
+    const lowerKey = key.toLowerCase();
+    
+    // Check if field is sensitive
+    const isSensitive = sensitiveFields.some(field => 
+      lowerKey.includes(field.toLowerCase())
+    );
+    
+    if (isSensitive) {
+      sanitized[key] = '[REDACTED]';
+    } else if (typeof value === 'object') {
+      sanitized[key] = sanitizeLogData(value, sensitiveFields);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  
+  return sanitized;
+}
+
+function generateId() {
+  return Math.random().toString(36).substring(2, 15);
+}

package/plugins/memory.js

@@ -0,0 +1,182 @@
+import firstBy from 'thenby';
+
+/**
+ * Memory storage plugin for JSON REST API
+ */
+export const MemoryPlugin = {
+  install(api, options = {}) {
+    // Initialize data storage
+    api.memoryData = options.initialData || [];
+    api.memoryIdCounter = options.initialIdCounter || 1;
+
+    // Implement CRUD operations
+    api.implement('get', async (context) => {
+      const { id, options } = context;
+      const idProperty = options.idProperty || api.options.idProperty;
+      
+      const record = api.memoryData.find(item => 
+        String(item[idProperty]) === String(id)
+      );
+      
+      return record || null;
+    });
+
+    api.implement('query', async (context) => {
+      const { params, options } = context;
+      let data = [...api.memoryData];
+
+      // Apply filters
+      if (params.filter) {
+        data = data.filter(item => {
+          for (const [key, value] of Object.entries(params.filter)) {
+            if (item[key] !== value) return false;
+          }
+          return true;
+        });
+      }
+
+      // Apply search (if search parameter exists)
+      if (params.search && options.searchFields) {
+        const searchLower = params.search.toLowerCase();
+        data = data.filter(item => {
+          return options.searchFields.some(field => {
+            const fieldValue = String(item[field] || '').toLowerCase();
+            return fieldValue.includes(searchLower);
+          });
+        });
+      }
+
+      // Count total before pagination
+      const total = data.length;
+
+      // Apply sorting
+      if (params.sort) {
+        const sorts = params.sort.split(',');
+        let sortChain = firstBy(() => 0);
+        
+        for (const sortField of sorts) {
+          const descending = sortField.startsWith('-');
+          const field = sortField.replace(/^-/, '');
+          
+          sortChain = sortChain.thenBy(
+            item => item[field],
+            { direction: descending ? -1 : 1, ignoreCase: true }
+          );
+        }
+        
+        data.sort(sortChain);
+      }
+
+      // Apply pagination
+      const pageSize = Number(params.page?.size) || 10;
+      const pageNumber = Number(params.page?.number) || 1;
+      const skip = (pageNumber - 1) * pageSize;
+      
+      data = data.slice(skip, skip + pageSize);
+
+      return {
+        results: data,
+        meta: {
+          total,
+          pageSize,
+          pageNumber,
+          totalPages: Math.ceil(total / pageSize)
+        }
+      };
+    });
+
+    api.implement('insert', async (context) => {
+      const { data, options } = context;
+      const idProperty = options.idProperty || api.options.idProperty;
+      
+      // Generate ID if not provided
+      if (!data[idProperty]) {
+        data[idProperty] = api.memoryIdCounter++;
+      }
+      
+      // Handle positioning if enabled
+      if (options.positionField && data[options.beforeIdField] !== undefined) {
+        await handlePositioning(api, data, options);
+      }
+      
+      // Add to memory
+      api.memoryData.push(data);
+      
+      return { ...data };
+    });
+
+    api.implement('update', async (context) => {
+      const { id, data, options } = context;
+      const idProperty = options.idProperty || api.options.idProperty;
+      
+      const index = api.memoryData.findIndex(item => 
+        String(item[idProperty]) === String(id)
+      );
+      
+      if (index === -1) {
+        throw new Error('Resource not found');
+      }
+      
+      // Handle positioning
+      if (options.positionField && data[options.beforeIdField] !== undefined) {
+        await handlePositioning(api, { ...api.memoryData[index], ...data }, options);
+      }
+      
+      // Update record
+      api.memoryData[index] = { ...api.memoryData[index], ...data };
+      
+      return api.memoryData[index];
+    });
+
+    api.implement('delete', async (context) => {
+      const { id, options } = context;
+      const idProperty = options.idProperty || api.options.idProperty;
+      
+      const index = api.memoryData.findIndex(item => 
+        String(item[idProperty]) === String(id)
+      );
+      
+      if (index === -1) {
+        throw new Error('Resource not found');
+      }
+      
+      api.memoryData.splice(index, 1);
+    });
+  }
+};
+
+/**
+ * Handle record positioning
+ */
+async function handlePositioning(api, record, options) {
+  const { positionField, beforeIdField } = options;
+  const idProperty = options.idProperty || api.options.idProperty;
+  const beforeId = record[beforeIdField];
+  
+  if (beforeId === null) {
+    // Place at end
+    const maxPosition = Math.max(...api.memoryData.map(r => r[positionField] || 0));
+    record[positionField] = maxPosition + 1;
+  } else if (beforeId !== undefined) {
+    // Find the record to place before
+    const beforeRecord = api.memoryData.find(r => 
+      String(r[idProperty]) === String(beforeId)
+    );
+    
+    if (beforeRecord) {
+      const position = beforeRecord[positionField] || 0;
+      
+      // Shift positions of records after this position
+      api.memoryData.forEach(r => {
+        if (r[positionField] >= position) {
+          r[positionField]++;
+        }
+      });
+      
+      record[positionField] = position;
+    }
+  }
+  
+  // Remove beforeId from record as it's virtual
+  delete record[beforeIdField];
+}