webspresso 0.0.101 → 0.0.102

package/plugins/lazy.js

@@ -0,0 +1,258 @@
+/**
+ * Webspresso On-Demand (Lazy) Plugin Wrapper
+ *
+ * Defers execution of heavy plugin initialization, filesystem scans, route mounting,
+ * and dependency loading until the plugin is actually accessed via:
+ * 1. HTTP request matching its configured URL prefix (e.g. /_admin)
+ * 2. Service execution (e.g. ctx.service('email.send'))
+ * 3. Direct inter-plugin API access (e.g. ctx.usePlugin('admin-panel'))
+ * 4. Template helper execution (e.g. fsy.adminHelper())
+ * 5. Explicit programmatic hydration (lazyPlugin.hydrate())
+ *
+ * @module plugins/lazy
+ */
+
+const express = require('express');
+
+/**
+ * Wraps a plugin definition or factory function into an on-demand lazy plugin.
+ *
+ * @param {Function|Object} pluginFactory - Factory `() => plugin` or plugin definition object
+ * @param {Object} [lazyOptions={}]
+ * @param {string} [lazyOptions.name] - Plugin name (inferred if not provided)
+ * @param {string|string[]} [lazyOptions.prefix] - URL path prefix(es) that trigger on-demand hydration (e.g. '/_admin')
+ * @param {string[]} [lazyOptions.services=[]] - Service names that trigger on-demand hydration
+ * @param {string[]} [lazyOptions.helpers=[]] - Template helpers that trigger on-demand hydration
+ * @param {string[]} [lazyOptions.events=[]] - Event names that trigger on-demand hydration
+ * @param {Object} [lazyOptions.dependencies] - Plugin dependencies
+ * @param {Object} [lazyOptions.csp] - Content Security Policy requirements
+ * @param {Function} [lazyOptions.onHydrate] - Callback invoked when hydration finishes
+ * @returns {Object} Webspresso Lazy Plugin definition
+ */
+function lazyPlugin(pluginFactory, lazyOptions = {}) {
+  let realPlugin = null;
+  let isHydrated = false;
+  let isHydrating = false;
+
+  let regCtx = null;
+  let routesCtx = null;
+  const router = express.Router();
+
+  const name =
+    lazyOptions.name ||
+    (typeof pluginFactory === 'object' && pluginFactory ? pluginFactory.name : null) ||
+    'anonymous-lazy-plugin';
+
+  const rawPrefixes = lazyOptions.prefix
+    ? (Array.isArray(lazyOptions.prefix) ? lazyOptions.prefix : [lazyOptions.prefix])
+    : [];
+  // Normalize prefixes: ensure leading slash, remove trailing slash (except root '/')
+  const prefixes = rawPrefixes.map(p => {
+    let norm = String(p).trim();
+    if (!norm.startsWith('/')) norm = '/' + norm;
+    if (norm.length > 1 && norm.endsWith('/')) norm = norm.slice(0, -1);
+    return norm;
+  });
+
+  const lazyServices = Array.isArray(lazyOptions.services) ? lazyOptions.services : [];
+  const lazyHelpers = Array.isArray(lazyOptions.helpers) ? lazyOptions.helpers : [];
+  const lazyEvents = Array.isArray(lazyOptions.events) ? lazyOptions.events : [];
+
+  function hydrate() {
+    if (isHydrated) return realPlugin;
+    if (isHydrating) return realPlugin;
+    isHydrating = true;
+
+    try {
+      realPlugin = typeof pluginFactory === 'function' ? pluginFactory() : pluginFactory;
+      if (!realPlugin) {
+        throw new Error(`[lazyPlugin] Factory for plugin "${name}" did not return a valid plugin object`);
+      }
+
+      // 1. Call setup hook if present
+      if (typeof realPlugin.setup === 'function' && regCtx?.app) {
+        const disposer = realPlugin.setup(regCtx.app);
+        if (typeof disposer === 'function' && regCtx.onDispose) {
+          regCtx.onDispose(disposer);
+        }
+      }
+
+      // 2. Call register hook
+      if (typeof realPlugin.register === 'function' && regCtx) {
+        const disposer = realPlugin.register(regCtx);
+        if (typeof disposer === 'function' && regCtx.onDispose) {
+          regCtx.onDispose(disposer);
+        }
+      }
+
+      // 3. Register real routes onto the lazy router
+      if (typeof realPlugin.onRoutesReady === 'function' && routesCtx) {
+        const customRoutesCtx = {
+          ...routesCtx,
+          addRoute(method, routePath, ...handlers) {
+            const m = String(method).toLowerCase();
+            let matchedPrefix = null;
+            for (const p of prefixes) {
+              if (routePath === p || routePath.startsWith(p + '/')) {
+                matchedPrefix = p;
+                break;
+              }
+            }
+
+            if (matchedPrefix) {
+              // Convert absolute route path to router-relative subpath
+              let subPath = routePath.slice(matchedPrefix.length);
+              if (!subPath || !subPath.startsWith('/')) {
+                subPath = '/' + (subPath || '');
+              }
+              if (router[m]) {
+                router[m](subPath, ...handlers);
+              } else if (router.all) {
+                router.all(subPath, ...handlers);
+              }
+            } else {
+              // Route is outside configured prefix: mount directly on app
+              if (routesCtx.addRoute) {
+                routesCtx.addRoute(method, routePath, ...handlers);
+              } else if (routesCtx.app && routesCtx.app[m]) {
+                routesCtx.app[m](routePath, ...handlers);
+              }
+            }
+          },
+        };
+
+        const disposer = realPlugin.onRoutesReady(customRoutesCtx);
+        if (typeof disposer === 'function' && routesCtx.onDispose) {
+          routesCtx.onDispose(disposer);
+        }
+      }
+
+      // 4. Update exposed API
+      if (realPlugin.api && lazyWrapper.api) {
+        Object.assign(lazyWrapper.api, realPlugin.api);
+      }
+
+      // 5. Fire optional callback
+      if (typeof lazyOptions.onHydrate === 'function') {
+        try {
+          lazyOptions.onHydrate(realPlugin);
+        } catch (_) {}
+      }
+
+      isHydrated = true;
+      return realPlugin;
+    } finally {
+      isHydrating = false;
+    }
+  }
+
+  // Create API Proxy that auto-hydrates on property access
+  const apiProxy = new Proxy({}, {
+    get(target, prop, receiver) {
+      if (prop === '_isLazyProxy') return true;
+      if (prop === 'hydrate') return hydrate;
+      if (prop === 'isHydrated') return isHydrated;
+      hydrate();
+      if (realPlugin && realPlugin.api) {
+        const val = Reflect.get(realPlugin.api, prop, receiver);
+        return typeof val === 'function' ? val.bind(realPlugin.api) : val;
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+    has(target, prop) {
+      hydrate();
+      return realPlugin && realPlugin.api ? Reflect.has(realPlugin.api, prop) : Reflect.has(target, prop);
+    },
+    set(target, prop, value, receiver) {
+      hydrate();
+      if (realPlugin && realPlugin.api) {
+        return Reflect.set(realPlugin.api, prop, value, receiver);
+      }
+      return Reflect.set(target, prop, value, receiver);
+    },
+  });
+
+  const lazyWrapper = {
+    name,
+    version: lazyOptions.version || (typeof pluginFactory === 'object' && pluginFactory?.version) || '1.0.0',
+    dependencies: lazyOptions.dependencies || (typeof pluginFactory === 'object' && pluginFactory?.dependencies) || {},
+    csp: lazyOptions.csp || (typeof pluginFactory === 'object' && pluginFactory?.csp) || null,
+    isLazy: true,
+    get isHydrated() { return isHydrated; },
+    hydrate,
+    api: apiProxy,
+
+    register(ctx) {
+      regCtx = ctx;
+
+      // Register proxy services in app service registry
+      if (ctx.app && ctx.app.serviceRegistry && lazyServices.length > 0) {
+        for (const svcName of lazyServices) {
+          if (!ctx.app.serviceRegistry.has(svcName)) {
+            const proxyHandler = async (input, serviceCtx) => {
+              hydrate();
+              const realDef = ctx.app.serviceRegistry.get(svcName);
+              if (realDef && typeof realDef.handler === 'function' && realDef.handler !== proxyHandler) {
+                return typeof realDef.rawHandler === 'function'
+                  ? realDef.rawHandler(input, serviceCtx)
+                  : realDef.handler(input, serviceCtx);
+              }
+              return null;
+            };
+
+            ctx.app.serviceRegistry.register(
+              svcName,
+              { handler: proxyHandler },
+              { overwrite: true }
+            );
+          }
+        }
+      }
+
+      // Register proxy helpers in template engine
+      if (typeof ctx.addHelper === 'function' && lazyHelpers.length > 0) {
+        for (const helperName of lazyHelpers) {
+          ctx.addHelper(helperName, (...args) => {
+            hydrate();
+            const helpers = regCtx?.pluginManager?.getHelpers ? regCtx.pluginManager.getHelpers() : {};
+            if (typeof helpers[helperName] === 'function') {
+              return helpers[helperName](...args);
+            }
+          });
+        }
+      }
+
+      // Wire event triggers if eventDispatcher is available
+      if (ctx.app?.events && lazyEvents.length > 0) {
+        for (const eventName of lazyEvents) {
+          ctx.app.events.on(eventName, () => {
+            hydrate();
+          });
+        }
+      }
+    },
+
+    onRoutesReady(ctx) {
+      routesCtx = ctx;
+
+      if (!ctx.app) return;
+
+      // Mount lazy trigger router for each prefix
+      for (const prefix of prefixes) {
+        ctx.app.use(prefix, (req, res, next) => {
+          if (!isHydrated) {
+            hydrate();
+          }
+          router(req, res, next);
+        });
+      }
+    },
+  };
+
+  return lazyWrapper;
+}
+
+module.exports = {
+  lazyPlugin,
+  defineLazyPlugin: lazyPlugin,
+};

package/src/api/api-loader.js

@@ -6,9 +6,11 @@
  * @module src/api/api-loader
  */
 
+const path = require('path');
 const { ZodError } = require('zod');
 const { z: zForApi } = require('../../core/validation');
 const { resolveMiddlewares } = require('../file-router');
+const { translateValidationIssues, getTranslatorForRequest } = require('./validation-i18n');
 
 /**
  * Compiles a schema definition from an API module
@@ -147,9 +149,17 @@ function createApiHandler(descriptor, context) {
           validateRequestInput(req, compiledSchema);
         } catch (err) {
           if (err instanceof ZodError || err.name === 'ZodError' || Array.isArray(err?.issues)) {
+            const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
+            const routeDir = descriptor.file ? path.dirname(descriptor.file) : '';
+            const translatedIssues = translateValidationIssues(err.issues, {
+              req,
+              pagesDir,
+              routeDir,
+              isDev,
+            });
             return res.status(400).json({
               error: 'Validation Error',
-              issues: err.issues,
+              issues: translatedIssues,
             });
           }
           throw err;
@@ -185,6 +195,10 @@ function createApiHandler(descriptor, context) {
       }
 
       // 5. Execute handler
+      const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
+      const routeDir = descriptor.file ? path.dirname(descriptor.file) : '';
+      const tr = getTranslatorForRequest(req, { pagesDir, routeDir, isDev });
+
       const apiCtx = {
         req,
         res,
@@ -192,6 +206,8 @@ function createApiHandler(descriptor, context) {
         query: req.query || {},
         body: req.body || {},
         input: req.input,
+        locale: tr.locale,
+        t: tr.t,
         service: (name, input, opts) =>
           serviceRegistry ? serviceRegistry.call(name, input, { req, res, db }, opts) : null,
         module: descriptor.module || null,

package/src/api/validation-i18n.js

@@ -0,0 +1,231 @@
+'use strict';
+
+/**
+ * Webspresso API Validation i18n & Error Translator
+ * Automatically localizes Zod validation error messages and keys based on request locale
+ * @module src/api/validation-i18n
+ */
+
+const path = require('path');
+
+const EMPTY_OBJECT = Object.freeze({});
+
+let _fileRouter = null;
+function getFileRouter() {
+  if (!_fileRouter) {
+    _fileRouter = require('../file-router');
+  }
+  return _fileRouter;
+}
+
+/**
+ * Resolves or creates a cached translator function for the given request and directory context
+ * @param {import('express').Request} req - Express request
+ * @param {Object} [options]
+ * @param {string} [options.pagesDir] - Pages directory path
+ * @param {string} [options.routeDir] - Route-specific directory
+ * @param {boolean} [options.isDev] - Is development environment
+ * @returns {{ t: Function, locale: string }}
+ */
+function getTranslatorForRequest(req, options = {}) {
+  if (req && req.t && req.locale) {
+    return { t: req.t, locale: req.locale };
+  }
+
+  const {
+    loadI18n,
+    createTranslator,
+    detectLocale,
+    translatorCache,
+  } = getFileRouter();
+
+  const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
+  const locale = (req && req.locale) ? req.locale : (req ? detectLocale(req) : defaultLocale);
+
+  const rawPagesDir = options.pagesDir || (req?.app?.get?.('pagesDir')) || 'pages';
+  const pagesDir = path.resolve(rawPagesDir);
+  const routeDir = options.routeDir ? path.resolve(options.routeDir) : '';
+  const isDev = options.isDev !== undefined ? options.isDev : process.env.NODE_ENV !== 'production';
+
+  let t;
+  if (!isDev && translatorCache) {
+    const transKey = `${pagesDir}::${routeDir}::${locale}::${defaultLocale}`;
+    t = translatorCache.get(transKey);
+    if (!t) {
+      const translations = loadI18n(pagesDir, routeDir, locale, false);
+      const fallbackTranslations = (locale !== defaultLocale)
+        ? loadI18n(pagesDir, routeDir, defaultLocale, false)
+        : EMPTY_OBJECT;
+      t = createTranslator(translations, {
+        locale,
+        fallbackTranslations,
+        fallbackLocale: defaultLocale,
+      });
+      translatorCache.set(transKey, t);
+    }
+  } else {
+    const translations = loadI18n(pagesDir, routeDir, locale, true);
+    const fallbackTranslations = (locale !== defaultLocale)
+      ? loadI18n(pagesDir, routeDir, defaultLocale, true)
+      : EMPTY_OBJECT;
+    t = createTranslator(translations, {
+      locale,
+      fallbackTranslations,
+      fallbackLocale: defaultLocale,
+    });
+  }
+
+  if (req) {
+    req.locale = locale;
+    req.t = t;
+  }
+
+  return { t, locale };
+}
+
+/**
+ * Translates a single Zod issue using candidate keys and parameter interpolation
+ * @param {Object} issue - Zod issue
+ * @param {Function} t - Translator function
+ * @returns {Object} Translated issue clone
+ */
+function translateSingleIssue(issue, t) {
+  if (!issue || typeof issue !== 'object') return issue;
+
+  const pathKey = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path.join('.') : '';
+  const field = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path[issue.path.length - 1] : '';
+  const isRequired = (issue.code === 'invalid_type' && (issue.received === 'undefined' || issue.message === 'Required'))
+    || issue.message === 'Required';
+
+  const params = Object.assign(
+    {
+      path: pathKey,
+      field,
+      min: issue.minimum !== undefined ? issue.minimum : undefined,
+      max: issue.maximum !== undefined ? issue.maximum : undefined,
+      minimum: issue.minimum !== undefined ? issue.minimum : undefined,
+      maximum: issue.maximum !== undefined ? issue.maximum : undefined,
+      limit: issue.minimum !== undefined ? issue.minimum : (issue.maximum !== undefined ? issue.maximum : undefined),
+      expected: issue.expected,
+      received: issue.received,
+      type: issue.type,
+      validation: issue.validation,
+    },
+    issue
+  );
+
+  const candidates = [];
+
+  // 1. Explicit key in custom message (e.g. z.string({ message: 'auth.email_required' }))
+  if (typeof issue.message === 'string' && typeof t.has === 'function' && t.has(issue.message)) {
+    candidates.push(issue.message);
+  } else if (typeof issue.message === 'string' && issue.message.includes('{{')) {
+    const interpolated = issue.message.replace(/{{\s*(\w+)\s*}}/g, (_, k) =>
+      params[k] !== undefined ? String(params[k]) : ''
+    );
+    return Object.assign({}, issue, { message: interpolated });
+  }
+
+  // 2. Field-specific overrides (e.g. validation.fields.email.required or validation.email.required)
+  if (pathKey) {
+    if (isRequired) {
+      candidates.push(`validation.fields.${pathKey}.required`);
+      candidates.push(`validation.${pathKey}.required`);
+      candidates.push(`validation.fields.${pathKey}`);
+      candidates.push(`validation.${pathKey}`);
+    } else {
+      if (issue.validation) {
+        candidates.push(`validation.fields.${pathKey}.${issue.validation}`);
+        candidates.push(`validation.${pathKey}.${issue.validation}`);
+      }
+      candidates.push(`validation.fields.${pathKey}.${issue.code}`);
+      candidates.push(`validation.${pathKey}.${issue.code}`);
+      candidates.push(`validation.fields.${pathKey}`);
+      candidates.push(`validation.${pathKey}`);
+    }
+  }
+
+  // 3. General validation code translations
+  if (isRequired) {
+    candidates.push('validation.required');
+    candidates.push('zod.required');
+    candidates.push('validation.invalid_type');
+    candidates.push('zod.invalid_type');
+  } else if (issue.code === 'invalid_string' && issue.validation) {
+    candidates.push(`validation.invalid_string.${issue.validation}`);
+    candidates.push(`validation.${issue.validation}`);
+    candidates.push(`zod.invalid_string.${issue.validation}`);
+    candidates.push(`zod.${issue.validation}`);
+    candidates.push('validation.invalid_string');
+    candidates.push('zod.invalid_string');
+  } else {
+    candidates.push(`validation.${issue.code}`);
+    candidates.push(`zod.${issue.code}`);
+  }
+
+  let matchedKey = null;
+  if (typeof t.has === 'function') {
+    for (const key of candidates) {
+      if (t.has(key)) {
+        matchedKey = key;
+        break;
+      }
+    }
+  }
+
+  if (matchedKey) {
+    return Object.assign({}, issue, {
+      message: t(matchedKey, params),
+      key: matchedKey,
+    });
+  }
+
+  // If no translation found, interpolate params in custom message if it contains placeholders
+  if (typeof issue.message === 'string' && issue.message.includes('{{')) {
+    const interpolated = issue.message.replace(/{{\s*(\w+)\s*}}/g, (_, k) =>
+      params[k] !== undefined ? String(params[k]) : ''
+    );
+    return Object.assign({}, issue, { message: interpolated });
+  }
+
+  return Object.assign({}, issue);
+}
+
+/**
+ * Translates an array of Zod validation issues using the active request locale
+ * @param {Array<Object>} issues - Zod error issues array
+ * @param {Object} [options]
+ * @param {import('express').Request} [options.req] - Express request
+ * @param {Function} [options.t] - Optional direct translator
+ * @param {string} [options.locale] - Optional direct locale
+ * @param {string} [options.pagesDir] - Pages directory path
+ * @param {string} [options.routeDir] - Route directory path
+ * @param {boolean} [options.isDev] - Is development environment
+ * @returns {Array<Object>} Translated issues
+ */
+function translateValidationIssues(issues, options = {}) {
+  if (!Array.isArray(issues) || issues.length === 0) {
+    return issues;
+  }
+
+  let t = options.t || options.req?.t;
+  let locale = options.locale || options.req?.locale;
+
+  if (!t && options.req) {
+    const tr = getTranslatorForRequest(options.req, options);
+    t = tr.t;
+    locale = tr.locale;
+  }
+
+  if (!t) {
+    return issues;
+  }
+
+  return issues.map((issue) => translateSingleIssue(issue, t));
+}
+
+module.exports = {
+  getTranslatorForRequest,
+  translateSingleIssue,
+  translateValidationIssues,
+};