json-rest-api 1.0.0 → 1.0.1

package/plugins/api-versioning.md

@@ -1,135 +0,0 @@
-
-  1. Creating Versioned APIs
-
-  // Just specify name and version - that's it!
-  const userApi = createApi({
-    name: 'users',
-    version: '1.0.0',
-    storage: 'memory'
-  });
-
-  // Create a new version
-  const userApiV2 = createApi({
-    name: 'users',
-    version: '2.0.0',
-    storage: 'memory'
-  });
-
-  2. Using APIs Programmatically
-
-  // Get latest version automatically
-  const api = Api.get('users', 'latest');
-
-  // Get specific version
-  const apiV1 = Api.get('users', '1.0.0');
-
-  // Get minimum version (2.0.0 or higher)
-  const apiV2Plus = Api.get('users', '2.0.0');
-
-  // Use it
-  const user = await api.insert({
-    name: 'John',
-    email: 'john@example.com'
-  }, { type: 'users' });
-
-  3. Cross-API Communication
-
-  APIs can access each other automatically with version compatibility:
-
-  const ordersApi = createApi({
-    name: 'orders',
-    version: '1.0.0'
-  });
-
-  // Inside orders API, access users API automatically
-  ordersApi.hook('afterInsert', async (context) => {
-    // This gets a compatible users API automatically!
-    const usersApi = ordersApi.apis.users;
-    const user = await usersApi.get(context.data.userId, { type: 'users'
-  });
-  });
-
-  4. HTTP Version Negotiation
-
-  The library handles all HTTP version routing automatically:
-
-  // Mount APIs - versioning is automatic
-  userApiV1.mount(app);   // Available at /api/1.0.0/users
-  userApiV2.mount(app);   // Available at /api/2.0.0/users
-
-  // Clients can request versions:
-  // Via header
-  fetch('/api/users', {
-    headers: { 'API-Version': '2.0.0' }
-  });
-
-  // Via query
-  fetch('/api/users?v=2.0.0');
-
-  // Via path
-  fetch('/api/2.0.0/users');
-
-  5. Version Resolution Rules
-
-  The library automatically finds the right version:
-
-  - 'latest' → Newest version
-  - '2.0.0' → Exactly 2.0.0 OR the newest version ≥ 2.0.0
-  - '^2.0.0' → Any 2.x.x version (npm style)
-  - '~2.1.0' → Any 2.1.x version (npm style)
-  - '>=2.0.0' → Any version ≥ 2.0.0
-
-  6. Complete Working Example
-
-  // Define v1
-  const apiV1 = createApi({
-    name: 'products',
-    version: '1.0.0',
-    storage: 'memory'
-  });
-
-  apiV1.addResource('products', new Schema({
-    id: { type: 'id' },
-    name: { type: 'string', required: true },
-    price: { type: 'number', required: true }
-  }));
-
-  // Define v2 with new field
-  const apiV2 = createApi({
-    name: 'products',
-    version: '2.0.0',
-    storage: 'memory'
-  });
-
-  apiV2.addResource('products', new Schema({
-    id: { type: 'id' },
-    name: { type: 'string', required: true },
-    price: { type: 'number', required: true },
-    category: { type: 'string', required: true }  // New!
-  }));
-
-  // Use programmatically - version selection is automatic
-  async function createProduct(data) {
-    // Automatically picks the right version based on data
-    const hasCategory = 'category' in data;
-    const minVersion = hasCategory ? '2.0.0' : '1.0.0';
-
-    const api = Api.get('products', minVersion);
-    return api.insert(data, { type: 'products' });
-  }
-
-  // Works with v1
-  await createProduct({
-    name: 'Widget',
-    price: 9.99
-  });
-
-  // Automatically uses v2
-  await createProduct({
-    name: 'Gadget',
-    price: 19.99,
-    category: 'Electronics'
-  });
-
-  The library handles all the complexity - you just specify name and
-  version when creating APIs, and the library does the rest!

package/plugins/http.js

@@ -1,273 +0,0 @@
-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

@@ -1,255 +0,0 @@
-/**
- * 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);
-}