@coherent.js/api 1.0.0-beta.2

package/dist/api/middleware.js

@@ -0,0 +1,244 @@
+/**
+ * Middleware system for Coherent.js API framework
+ * @fileoverview Common middleware utilities for API routes
+ */
+/**
+ * Creates a custom API middleware with error handling
+ * @param {Function} handler - Middleware handler function
+ * @returns {Function} Middleware function that catches errors
+ */
+export function createApiMiddleware(handler) {
+    return (req, res, next) => {
+        try {
+            return handler(req, res, next);
+        }
+        catch (error) {
+            // Pass errors to next middleware
+            next(error);
+        }
+    };
+}
+/**
+ * Authentication middleware
+ * @param {Function} verifyToken - Function to verify authentication token
+ * @returns {Function} Middleware function
+ */
+export function withAuth(verifyToken) {
+    return createApiMiddleware((req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader) {
+            return res.status(401).json({
+                error: 'Unauthorized',
+                message: 'Missing authorization header'
+            });
+        }
+        const token = authHeader.replace('Bearer ', '');
+        try {
+            const user = verifyToken(token);
+            req.user = user;
+            next();
+        }
+        catch {
+            return res.status(401).json({
+                error: 'Unauthorized',
+                message: 'Invalid token'
+            });
+        }
+    });
+}
+/**
+ * Authorization middleware
+ * @param {Function} checkPermission - Function to check user permissions
+ * @returns {Function} Middleware function
+ */
+export function withPermission(checkPermission) {
+    return createApiMiddleware((req, res, next) => {
+        if (!req.user) {
+            return res.status(401).json({
+                error: 'Unauthorized',
+                message: 'User not authenticated'
+            });
+        }
+        try {
+            const hasPermission = checkPermission(req.user, req);
+            if (!hasPermission) {
+                return res.status(403).json({
+                    error: 'Forbidden',
+                    message: 'Insufficient permissions'
+                });
+            }
+            next();
+        }
+        catch {
+            return res.status(403).json({
+                error: 'Forbidden',
+                message: 'Permission check failed'
+            });
+        }
+    });
+}
+/**
+ * Logging middleware
+ * @param {Object} options - Logging options
+ * @returns {Function} Middleware function
+ */
+export function withLogging(options = {}) {
+    const { logger = console, level = 'info' } = options;
+    return createApiMiddleware((req, res, next) => {
+        const startTime = Date.now();
+        // Log request
+        logger[level](`[${new Date().toISOString()}] ${req.method} ${req.url}`);
+        // Capture response finish to log completion
+        const originalSend = res.send;
+        res.send = function (body) {
+            const duration = Date.now() - startTime;
+            logger[level](`[${new Date().toISOString()}] ${req.method} ${req.url} ${res.statusCode} - ${duration}ms`);
+            return originalSend.call(this, body);
+        };
+        next();
+    });
+}
+/**
+ * CORS middleware
+ * @param {Object} options - CORS options
+ * @returns {Function} Middleware function
+ */
+export function withCors(options = {}) {
+    const { origin = '*', methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], allowedHeaders = ['Content-Type', 'Authorization'], exposedHeaders = [], credentials = false, maxAge = 86400 } = options;
+    return createApiMiddleware((req, res, next) => {
+        // Set CORS headers
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        if (credentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        if (req.method === 'OPTIONS') {
+            // Preflight request
+            res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
+            res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+            res.setHeader('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+            res.setHeader('Access-Control-Max-Age', maxAge.toString());
+            res.status(204).send('');
+            return;
+        }
+        next();
+    });
+}
+/**
+ * Rate limiting middleware
+ * @param {Object} options - Rate limiting options
+ * @returns {Function} Middleware function
+ */
+export function withRateLimit(options = {}) {
+    const { windowMs = 60000, // 1 minute
+    max = 100, // limit each IP to 100 requests per windowMs
+    message = 'Too many requests, please try again later', statusCode = 429 } = options;
+    // Store request counts per IP
+    const requestCounts = new Map();
+    // Cleanup old entries periodically (do not keep event loop alive)
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [ip, record] of requestCounts.entries()) {
+            if (now - record.resetTime > windowMs) {
+                requestCounts.delete(ip);
+            }
+        }
+    }, windowMs);
+    if (typeof cleanupInterval.unref === 'function') {
+        cleanupInterval.unref();
+    }
+    return createApiMiddleware((req, res, next) => {
+        const ip = req.ip || req.connection.remoteAddress;
+        const now = Date.now();
+        if (!requestCounts.has(ip)) {
+            requestCounts.set(ip, {
+                count: 0,
+                resetTime: now + windowMs
+            });
+        }
+        const record = requestCounts.get(ip);
+        // Reset count if window has passed
+        if (now > record.resetTime) {
+            record.count = 0;
+            record.resetTime = now + windowMs;
+        }
+        // Increment count
+        record.count++;
+        // Check if limit exceeded
+        if (record.count > max) {
+            return res.status(statusCode).json({
+                error: 'Rate limit exceeded',
+                message
+            });
+        }
+        // Add rate limit info to response headers
+        res.setHeader('X-RateLimit-Limit', max);
+        res.setHeader('X-RateLimit-Remaining', Math.max(0, max - record.count));
+        res.setHeader('X-RateLimit-Reset', new Date(record.resetTime).toISOString());
+        next();
+    });
+}
+/**
+ * Input sanitization middleware
+ * @param {Object} options - Sanitization options
+ * @returns {Function} Middleware function
+ */
+export function withSanitization(options = {}) {
+    const { sanitizeBody = true, sanitizeQuery = true, sanitizeParams = true } = options;
+    return createApiMiddleware((req, res, next) => {
+        if (sanitizeBody && req.body) {
+            req.body = sanitizeObject(req.body);
+        }
+        if (sanitizeQuery && req.query) {
+            req.query = sanitizeObject(req.query);
+        }
+        if (sanitizeParams && req.params) {
+            req.params = sanitizeObject(req.params);
+        }
+        next();
+    });
+}
+/**
+ * Sanitize an object by escaping HTML entities
+ * @param {any} obj - Object to sanitize
+ * @returns {any} Sanitized object
+ */
+function sanitizeObject(obj) {
+    if (typeof obj === 'string') {
+        return sanitizeString(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sanitizeObject);
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(obj)) {
+            sanitized[key] = sanitizeObject(value);
+        }
+        return sanitized;
+    }
+    return obj;
+}
+/**
+ * Sanitize a string by escaping HTML entities
+ * @param {string} str - String to sanitize
+ * @returns {string} Sanitized string
+ */
+function sanitizeString(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#x27;');
+}
+// Export middleware utilities
+export default {
+    createApiMiddleware,
+    withAuth,
+    withPermission,
+    withLogging,
+    withCors,
+    withRateLimit,
+    withSanitization
+};
+//# sourceMappingURL=middleware.js.map

package/dist/api/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../../src/api/middleware.js"],"names":[],"mappings":"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"}

package/dist/api/openapi.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OpenAPI/Swagger integration for Coherent.js API framework
+ */
+/**
+ * Create OpenAPI documentation middleware
+ * @param {Object} options - OpenAPI options
+ * @param {string} options.summary - Endpoint summary
+ * @param {string} options.description - Endpoint description
+ * @param {Object} options.responses - Response schemas
+ * @param {Object} options.requestBody - Request body schema
+ * @param {Object} options.parameters - Path/query parameters
+ * @returns {Function} Middleware function
+ */
+export function withOpenApi(options?: {
+    summary: string;
+    description: string;
+    responses: Object;
+    requestBody: Object;
+    parameters: Object;
+}): Function;
+/**
+ * Generate OpenAPI specification from registered routes
+ * @param {Object} appInfo - Application information
+ * @param {string} appInfo.title - Application title
+ * @param {string} appInfo.version - Application version
+ * @param {string} appInfo.description - Application description
+ * @param {Array} routes - Registered routes
+ * @returns {Object} OpenAPI specification
+ */
+export function generateOpenApiSpec(appInfo?: {
+    title: string;
+    version: string;
+    description: string;
+}, routes?: any[]): Object;
+/**
+ * Create OpenAPI documentation endpoint
+ * @param {Object} appInfo - Application information
+ * @param {Array} routes - Registered routes
+ * @returns {Function} Handler function
+ */
+export function createOpenApiHandler(appInfo?: Object, routes?: any[]): Function;
+/**
+ * Create Swagger UI endpoint
+ * @returns {Function} Handler function
+ */
+export function createSwaggerUIHandler(): Function;
+declare namespace _default {
+    export { withOpenApi };
+    export { generateOpenApiSpec };
+    export { createOpenApiHandler };
+    export { createSwaggerUIHandler };
+}
+export default _default;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/api/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../../src/api/openapi.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,sCAPG;IAAwB,OAAO,EAAvB,MAAM;IACU,WAAW,EAA3B,MAAM;IACU,SAAS,EAAzB,MAAM;IACU,WAAW,EAA3B,MAAM;IACU,UAAU,EAA1B,MAAM;CACd,YAoBF;AAED;;;;;;;;GAQG;AACH,8CANG;IAAwB,KAAK,EAArB,MAAM;IACU,OAAO,EAAvB,MAAM;IACU,WAAW,EAA3B,MAAM;CACd,mBACU,MAAM,CA+ClB;AAYD;;;;;GAKG;AACH,+CAJW,MAAM,4BAUhB;AAED;;;GAGG;AACH,mDA6BC"}

package/dist/api/openapi.js

@@ -0,0 +1,144 @@
+/**
+ * OpenAPI/Swagger integration for Coherent.js API framework
+ */
+/**
+ * Create OpenAPI documentation middleware
+ * @param {Object} options - OpenAPI options
+ * @param {string} options.summary - Endpoint summary
+ * @param {string} options.description - Endpoint description
+ * @param {Object} options.responses - Response schemas
+ * @param {Object} options.requestBody - Request body schema
+ * @param {Object} options.parameters - Path/query parameters
+ * @returns {Function} Middleware function
+ */
+export function withOpenApi(options = {}) {
+    return (req, res, next) => {
+        // Add OpenAPI metadata to request for documentation generation
+        if (!req.openapi) {
+            req.openapi = {};
+        }
+        // Store endpoint metadata
+        req.openapi[req.method + req.url] = {
+            summary: options.summary || '',
+            description: options.description || '',
+            responses: options.responses || {},
+            requestBody: options.requestBody,
+            parameters: options.parameters || []
+        };
+        next();
+    };
+}
+/**
+ * Generate OpenAPI specification from registered routes
+ * @param {Object} appInfo - Application information
+ * @param {string} appInfo.title - Application title
+ * @param {string} appInfo.version - Application version
+ * @param {string} appInfo.description - Application description
+ * @param {Array} routes - Registered routes
+ * @returns {Object} OpenAPI specification
+ */
+export function generateOpenApiSpec(appInfo = {}, routes = []) {
+    const spec = {
+        openapi: '3.0.0',
+        info: {
+            title: appInfo.title || 'Coherent.js API',
+            version: appInfo.version || '1.0.0',
+            description: appInfo.description || 'API documentation for Coherent.js application'
+        },
+        paths: {}
+    };
+    // Process each route
+    routes.forEach(route => {
+        const path = normalizePath(route.path);
+        const method = route.method.toLowerCase();
+        if (!spec.paths[path]) {
+            spec.paths[path] = {};
+        }
+        // Add operation
+        spec.paths[path][method] = {
+            summary: route.openapi?.summary || '',
+            description: route.openapi?.description || '',
+            parameters: route.openapi?.parameters || [],
+            responses: route.openapi?.responses || {
+                '200': {
+                    description: 'Successful response'
+                }
+            }
+        };
+        // Add request body if specified
+        if (route.openapi?.requestBody) {
+            spec.paths[path][method].requestBody = {
+                content: {
+                    'application/json': {
+                        schema: route.openapi.requestBody
+                    }
+                }
+            };
+        }
+    });
+    return spec;
+}
+/**
+ * Normalize path for OpenAPI
+ * @param {string} path - Route path
+ * @returns {string} Normalized path
+ */
+function normalizePath(path) {
+    // Convert Express-style params (:id) to OpenAPI style ({id})
+    return path.replace(/:(\w+)/g, '{$1}');
+}
+/**
+ * Create OpenAPI documentation endpoint
+ * @param {Object} appInfo - Application information
+ * @param {Array} routes - Registered routes
+ * @returns {Function} Handler function
+ */
+export function createOpenApiHandler(appInfo = {}, routes = []) {
+    return (req, res) => {
+        const spec = generateOpenApiSpec(appInfo, routes);
+        res.setHeader('Content-Type', 'application/json');
+        return spec;
+    };
+}
+/**
+ * Create Swagger UI endpoint
+ * @returns {Function} Handler function
+ */
+export function createSwaggerUIHandler() {
+    return (req, res) => {
+        const html = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Coherent.js API Documentation</title>
+  <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@4/swagger-ui-bundle.css" />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@4/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '/api/docs/json',
+      dom_id: '#swagger-ui',
+      presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIBundle.presets.standalone
+      ]
+    });
+  </script>
+</body>
+</html>
+`;
+        res.setHeader('Content-Type', 'text/html');
+        return html;
+    };
+}
+// Export OpenAPI utilities
+export default {
+    withOpenApi,
+    generateOpenApiSpec,
+    createOpenApiHandler,
+    createSwaggerUIHandler
+};
+//# sourceMappingURL=openapi.js.map

package/dist/api/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../../src/api/openapi.js"],"names":[],"mappings":"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"}