webspresso 0.0.95 → 0.0.96

package/src/api/api-loader.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Webspresso API Loader
+ * Handles validation and execution of defineApi() endpoints
+ * @module src/api/api-loader
+ */
+
+const { ZodError } = require('zod');
+const { z: zForApi } = require('../../core/validation');
+const { resolveMiddlewares } = require('../file-router');
+
+/**
+ * Compiles a schema definition from an API module
+ * @param {Object|Function} schemaDef
+ * @returns {Object|null}
+ */
+function compileApiSchema(schemaDef) {
+  if (!schemaDef) return null;
+  if (typeof schemaDef === 'function') {
+    try {
+      return schemaDef({ z: zForApi });
+    } catch (err) {
+      throw new Error(`Failed to compile API schema: ${err.message}`);
+    }
+  }
+  if (typeof schemaDef === 'object') {
+    return schemaDef;
+  }
+  return null;
+}
+
+/**
+ * Validates request input against compiled schema
+ * @param {import('express').Request} req
+ * @param {Object} compiledSchema
+ */
+function validateRequestInput(req, compiledSchema) {
+  req.input = {
+    body: undefined,
+    params: undefined,
+    query: undefined,
+    headers: undefined,
+  };
+
+  if (!compiledSchema) return;
+
+  if (compiledSchema.body && typeof compiledSchema.body.parse === 'function') {
+    req.input.body = compiledSchema.body.parse(req.body);
+  } else {
+    req.input.body = req.body;
+  }
+
+  if (compiledSchema.params && typeof compiledSchema.params.parse === 'function') {
+    req.input.params = compiledSchema.params.parse(req.params);
+  } else {
+    req.input.params = req.params;
+  }
+
+  if (compiledSchema.query && typeof compiledSchema.query.parse === 'function') {
+    req.input.query = compiledSchema.query.parse(req.query);
+  } else {
+    req.input.query = req.query;
+  }
+
+  if (compiledSchema.headers && typeof compiledSchema.headers.parse === 'function') {
+    req.input.headers = compiledSchema.headers.parse(req.headers);
+  }
+}
+
+/**
+ * Creates an Express route handler for a discovered API descriptor
+ * @param {Object} descriptor - Route descriptor
+ * @param {Object} context - Server context
+ * @returns {Function}
+ */
+function createApiHandler(descriptor, context) {
+  const {
+    middlewares = {},
+    serviceRegistry = null,
+    db = null,
+    options: appOptions = {},
+  } = context;
+
+  const isDev = process.env.NODE_ENV === 'development';
+  let cachedMiddlewares = null;
+  let cachedApiDef = null;
+  let cachedHandlerFn = null;
+  let cachedCompiledSchema = null;
+
+  return async (req, res, next) => {
+    try {
+      // 1. Reload module in development
+      if (isDev) {
+        try {
+          const resolvedPath = require.resolve(descriptor.file);
+          if (require.cache[resolvedPath]) {
+            delete require.cache[resolvedPath];
+            cachedMiddlewares = null;
+            cachedApiDef = null;
+            cachedHandlerFn = null;
+            cachedCompiledSchema = null;
+          }
+        } catch {}
+      }
+
+      let apiDef = cachedApiDef;
+      let handlerFn = cachedHandlerFn;
+      let compiledSchema = cachedCompiledSchema;
+
+      if (!apiDef) {
+        let apiModule = {};
+        try {
+          apiModule = require(descriptor.file);
+        } catch (loadErr) {
+          return next(loadErr);
+        }
+
+        apiDef = typeof apiModule === 'function' ? { handler: apiModule } : apiModule.default || apiModule;
+        handlerFn = apiDef.handler || (typeof apiModule === 'function' ? apiModule : null);
+
+        if (typeof handlerFn !== 'function') {
+          throw new Error(`API file "${descriptor.source}" does not export a valid handler function`);
+        }
+
+        compiledSchema = compileApiSchema(apiDef.schema);
+
+        if (!isDev) {
+          cachedApiDef = apiDef;
+          cachedHandlerFn = handlerFn;
+          cachedCompiledSchema = compiledSchema;
+        }
+      }
+
+      // 2. Injections
+      if (db) req.db = db;
+      if (serviceRegistry) {
+        req.service = (name, input, opts) =>
+          serviceRegistry.call(name, input, { req, res, db }, opts);
+      }
+
+      // 3. Schema validation
+      if (compiledSchema) {
+        try {
+          validateRequestInput(req, compiledSchema);
+        } catch (err) {
+          if (err instanceof ZodError || err.name === 'ZodError' || Array.isArray(err?.issues)) {
+            return res.status(400).json({
+              error: 'Validation Error',
+              issues: err.issues,
+            });
+          }
+          throw err;
+        }
+      } else {
+        req.input = {
+          body: req.body,
+          params: req.params,
+          query: req.query,
+        };
+      }
+
+      // 4. Resolve and execute middlewares (module-local first, cached across requests)
+      if (!cachedMiddlewares) {
+        const moduleMiddlewares = descriptor.moduleConfig?.middlewares || {};
+        const combinedRegistry = Object.assign({}, middlewares, moduleMiddlewares);
+        cachedMiddlewares = resolveMiddlewares(apiDef.middleware, combinedRegistry);
+      }
+
+      for (const mw of cachedMiddlewares) {
+        if (typeof mw !== 'function') continue;
+        await new Promise((resolve, reject) => {
+          try {
+            mw(req, res, (err) => {
+              if (err) reject(err);
+              else resolve();
+            });
+          } catch (syncErr) {
+            reject(syncErr);
+          }
+        });
+        if (res.headersSent) return;
+      }
+
+      // 5. Execute handler
+      const apiCtx = {
+        req,
+        res,
+        params: req.params || {},
+        query: req.query || {},
+        body: req.body || {},
+        input: req.input,
+        service: (name, input, opts) =>
+          serviceRegistry ? serviceRegistry.call(name, input, { req, res, db }, opts) : null,
+        module: descriptor.module || null,
+        config: appOptions,
+        logger: console,
+        db,
+      };
+
+      req.ctx = apiCtx;
+      res.service = apiCtx.service;
+      res.input = apiCtx.input;
+      res.module = apiCtx.module;
+
+      const result = await handlerFn(req, res, apiCtx);
+
+      // 6. Auto-respond if handler returned a value and response not yet sent
+      if (!res.headersSent) {
+        if (result !== undefined) {
+          return res.json(result);
+        }
+      }
+    } catch (err) {
+      if (err && typeof err === 'object') {
+        if (!err.route) err.route = descriptor.path;
+        if (!err.method) err.method = descriptor.method ? descriptor.method.toUpperCase() : (req.method || 'GET');
+        if (!err.source) err.source = descriptor.source || descriptor.file;
+        if (!err.file) err.file = descriptor.file;
+        if (!err.module) err.module = descriptor.module || null;
+        if (!err.phase) err.phase = 'handler';
+        if (!err.requestId) err.requestId = req.id || (req.headers && req.headers['x-request-id']) || null;
+      }
+      return next(err);
+    }
+  };
+}
+
+module.exports = {
+  createApiHandler,
+  compileApiSchema,
+  validateRequestInput,
+};

package/src/api/define-api.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Webspresso API Definition Helper
+ * @module src/api/define-api
+ */
+
+/**
+ * Defines an API route with schema validation, response metadata, and handler
+ * @param {Object} config
+ * @param {string} [config.description] - Endpoint description for OpenAPI
+ * @param {Array<string>} [config.tags] - Endpoint tags for OpenAPI
+ * @param {Array<string|Function>} [config.middleware] - Named or functional middlewares
+ * @param {Object|Function} [config.schema] - Request schemas (params, query, body, headers)
+ * @param {Object} [config.response] - Expected response schemas by status code
+ * @param {Function} config.handler - Request handler: async (req, ctx) => data
+ * @returns {Object}
+ */
+function defineApi(config = {}) {
+  if (typeof config === 'function') {
+    return {
+      handler: config,
+      __isWebspressoApi: true,
+    };
+  }
+
+  return {
+    ...config,
+    __isWebspressoApi: true,
+  };
+}
+
+module.exports = {
+  defineApi,
+};

package/src/discovery/file-route-parser.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Webspresso File Route Parser
+ * Converts relative filesystem paths into Express route paths and HTTP methods
+ * @module src/discovery/file-route-parser
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SUPPORTED_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head']);
+const SUPPORTED_EXTENSIONS = new Set(['.js', '.njk']);
+const METHOD_SUFFIX_REGEX = /\.([a-zA-Z]+)\.js$/;
+const TEMPORARY_FILE_REGEX = /(?:~|\.swp|\.tmp|\.bak|\.DS_Store)$/;
+
+/**
+ * Safely scans a directory recursively for route files
+ * @param {string} dirPath - Absolute directory path
+ * @param {string} [baseDir=dirPath] - Base directory for computing relative paths
+ * @returns {Array<{ absolutePath: string, relativePath: string }>}
+ */
+function scanDirSafely(dirPath, baseDir = dirPath) {
+  const results = [];
+  if (!fs.existsSync(dirPath)) return results;
+
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const name = entry.name;
+      if (isPrivateOrIgnored(name)) continue;
+
+      const fullPath = path.join(dirPath, name);
+      const relPath = path.relative(baseDir, fullPath);
+
+      if (entry.isDirectory()) {
+        results.push(...scanDirSafely(fullPath, baseDir));
+      } else if (entry.isFile()) {
+        const ext = path.extname(name);
+        if (SUPPORTED_EXTENSIONS.has(ext)) {
+          results.push({
+            absolutePath: fullPath,
+            relativePath: relPath,
+          });
+        }
+      }
+    }
+  } catch (err) {
+    console.warn(`[webspresso] Failed to scan directory ${dirPath}:`, err.message);
+  }
+
+  return results;
+}
+
+/**
+ * Checks if a filename or directory name should be ignored (private or temporary)
+ * @param {string} name - File or directory basename
+ * @returns {boolean}
+ */
+function isPrivateOrIgnored(name) {
+  if (!name || typeof name !== 'string') return true;
+  // Hidden files/directories (.git, .DS_Store, .login.js.swp)
+  if (name.startsWith('.')) return true;
+  // Private files/directories (_components, _helpers, _private.js)
+  if (name.startsWith('_')) return true;
+  // Temporary editor files
+  if (TEMPORARY_FILE_REGEX.test(name)) return true;
+  return false;
+}
+
+/**
+ * Converts parameter markers [id] -> :id and catch-all [...path] -> *
+ * @param {string} segment
+ * @returns {string}
+ */
+function transformDynamicSegment(segment) {
+  if (!segment || typeof segment !== 'string') return segment || '';
+  if (segment.startsWith('[...') && segment.endsWith(']')) {
+    const paramName = segment.slice(4, -1).trim();
+    return paramName ? `*${paramName}` : '*';
+  }
+  if (segment.startsWith('[') && segment.endsWith(']')) {
+    const paramName = segment.slice(1, -1).trim();
+    return paramName ? `:${paramName}` : segment;
+  }
+  return segment;
+}
+
+/**
+ * Normalizes a URL prefix to have a leading slash and no trailing slash
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+function normalizePrefix(prefix = '') {
+  if (!prefix || typeof prefix !== 'string') return '';
+  let clean = prefix.trim().replace(/\\/g, '/');
+  clean = clean.replace(/\/+/g, '/');
+  if (clean === '/' || !clean) return '';
+  if (!clean.startsWith('/')) clean = '/' + clean;
+  if (clean.endsWith('/')) clean = clean.slice(0, -1);
+  return clean === '/' ? '' : clean;
+}
+
+/**
+ * Parses a relative file path for an API or Page route
+ * @param {string} relativePath - Relative path from directory root (e.g. 'users/[id].get.js' or 'blog/[slug].js')
+ * @param {Object} [options]
+ * @param {string} [options.type='page'] - 'page' | 'api'
+ * @param {string} [options.prefix=''] - Base prefix (e.g. '/api' or '/auth')
+ * @returns {{ path: string, method: string, isValid: boolean, isPrivate: boolean, originalMethodPart?: string }}
+ */
+function parseFileRoute(relativePath, options = {}) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    return { path: '', method: '', isValid: false, isPrivate: false };
+  }
+
+  const { type = 'page', prefix = '' } = options;
+
+  // Normalize path separators to forward slashes
+  const normalizedPath = relativePath.split(path.sep).join('/').replace(/\\/g, '/');
+  const segments = normalizedPath.split('/').filter(Boolean);
+
+  // Check if any segment is private or ignored
+  for (const seg of segments) {
+    if (isPrivateOrIgnored(seg)) {
+      return { path: '', method: '', isValid: false, isPrivate: true };
+    }
+  }
+
+  const filename = segments[segments.length - 1];
+  if (!filename) {
+    return { path: '', method: '', isValid: false, isPrivate: false };
+  }
+
+  let method = 'get';
+  let cleanFilename = filename;
+  let originalMethodPart = null;
+
+  // Check for HTTP method suffix: e.g. health.get.js, [id].patch.js
+  const methodMatch = filename.match(METHOD_SUFFIX_REGEX);
+  if (methodMatch) {
+    const rawMethod = methodMatch[1].toLowerCase();
+    originalMethodPart = rawMethod;
+    if (SUPPORTED_METHODS.has(rawMethod)) {
+      method = rawMethod;
+      cleanFilename = filename.replace(`.${methodMatch[1]}.js`, '');
+    } else {
+      // Invalid HTTP method in filename
+      return { path: '', method: rawMethod, isValid: false, isPrivate: false, invalidMethod: true };
+    }
+  } else if (filename.endsWith('.js')) {
+    cleanFilename = filename.slice(0, -3);
+  } else if (filename.endsWith('.njk')) {
+    cleanFilename = filename.slice(0, -4);
+  }
+
+  // Replace last segment with cleanFilename
+  const routeSegments = [...segments.slice(0, -1), cleanFilename];
+
+  // Process dynamic brackets in segments
+  const transformedSegments = routeSegments.map(transformDynamicSegment);
+
+  // Handle 'index' at the end of path
+  if (transformedSegments[transformedSegments.length - 1] === 'index') {
+    transformedSegments.pop();
+  }
+
+  let routePath = '/' + transformedSegments.join('/');
+  if (routePath === '//' || routePath === '') {
+    routePath = '/';
+  }
+
+  // Combine with prefix
+  const cleanPrefix = normalizePrefix(prefix);
+  if (cleanPrefix) {
+    if (routePath === '/') {
+      routePath = cleanPrefix;
+    } else {
+      routePath = `${cleanPrefix}${routePath}`;
+    }
+  }
+
+  return {
+    path: routePath,
+    method: method.toUpperCase(),
+    isValid: true,
+    isPrivate: false,
+    originalMethodPart,
+  };
+}
+
+module.exports = {
+  parseFileRoute,
+  isPrivateOrIgnored,
+  normalizePrefix,
+  transformDynamicSegment,
+  scanDirSafely,
+  SUPPORTED_METHODS,
+  SUPPORTED_EXTENSIONS,
+};