webspresso 0.0.90 → 0.0.91

package/src/file-router.js

@@ -15,6 +15,7 @@ const {
   frontmatterToPatches,
   clearNjkFrontmatterCaches,
 } = require('./njk-frontmatter');
+const { renderStream } = require('../core/ssr/stream');
 
 const NOOP = () => {};
 const EMPTY_OBJECT = Object.freeze({});
@@ -432,33 +433,103 @@ function loadI18n(pagesDir, routeDir, locale) {
   return data;
 }
 
-function createTranslator(translations = {}) {
-  return function t(key, params = EMPTY_OBJECT, defaultVal = null) {
+// Cache for Intl.PluralRules instances
+const pluralRulesCache = new Map();
+
+function getPluralRules(locale) {
+  let pr = pluralRulesCache.get(locale);
+  if (!pr) {
+    try {
+      pr = new Intl.PluralRules(locale);
+    } catch {
+      pr = new Intl.PluralRules('en');
+    }
+    if (pluralRulesCache.size < 100) {
+      pluralRulesCache.set(locale, pr);
+    }
+  }
+  return pr;
+}
+
+function resolveTranslationValue(dict, key) {
+  if (!dict || typeof dict !== 'object') return undefined;
+  if (dict[key] !== undefined) return dict[key];
+
+  const parts = key.split('.');
+  let curr = dict;
+  for (const part of parts) {
+    if (curr && typeof curr === 'object') {
+      curr = curr[part];
+    } else {
+      return undefined;
+    }
+  }
+  return curr;
+}
+
+/**
+ * Create a translation helper function with pluralization, fallback, and formatting support
+ * @param {Object} translations - Primary locale translations dictionary
+ * @param {Object|string} [options] - Options object or locale string
+ * @param {string} [options.locale='en'] - Active locale code
+ * @param {Object} [options.fallbackTranslations] - Fallback translations dictionary
+ * @param {string} [options.fallbackLocale='en'] - Fallback locale code
+ * @returns {Function} Translation function `t`
+ */
+function createTranslator(translations = {}, options = EMPTY_OBJECT) {
+  const opts = typeof options === 'string' ? { locale: options } : (options || EMPTY_OBJECT);
+  const locale = opts.locale || 'en';
+  const fallbackTranslations = opts.fallbackTranslations || null;
+
+  function t(key, params = EMPTY_OBJECT, defaultVal = null) {
     const defaultValue = typeof params === 'string' ? params : defaultVal;
     const interpolationParams = typeof params === 'object' && params !== null ? params : EMPTY_OBJECT;
 
-    let value = translations ? translations[key] : undefined;
-    
-    if (value === undefined && translations) {
-      // Try nested key lookup (e.g., "meta.title")
-      const parts = key.split('.');
-      value = translations;
-      for (const part of parts) {
-        if (value && typeof value === 'object') {
-          value = value[part];
+    let value = resolveTranslationValue(translations, key);
+
+    // If missing in primary locale, fallback to fallback translations
+    if (value === undefined && fallbackTranslations) {
+      value = resolveTranslationValue(fallbackTranslations, key);
+    }
+
+    // Handle Pluralization if value is an object (or when count is passed)
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const count = interpolationParams.count !== undefined
+        ? Number(interpolationParams.count)
+        : (interpolationParams.n !== undefined
+          ? Number(interpolationParams.n)
+          : (interpolationParams.cardinal !== undefined ? Number(interpolationParams.cardinal) : undefined));
+
+      if (count !== undefined && !Number.isNaN(count)) {
+        const countStr = String(count);
+        if (typeof value[countStr] === 'string') {
+          value = value[countStr];
+        } else if (count === 0 && typeof value.zero === 'string') {
+          value = value.zero;
         } else {
-          value = undefined;
-          break;
+          const category = getPluralRules(locale).select(count);
+          if (typeof value[category] === 'string') {
+            value = value[category];
+          } else if (typeof value.other === 'string') {
+            value = value.other;
+          } else {
+            const firstString = Object.values(value).find((v) => typeof v === 'string');
+            value = firstString !== undefined ? firstString : key;
+          }
         }
       }
     }
-    
+
     if (value === undefined) {
       return defaultValue !== null && defaultValue !== undefined ? defaultValue : key;
     }
-    
+
+    if (typeof value !== 'string') {
+      return value;
+    }
+
     // Replace params like {{name}} in the translation
-    if (typeof value === 'string' && interpolationParams && interpolationParams !== EMPTY_OBJECT && Object.keys(interpolationParams).length > 0) {
+    if (interpolationParams && interpolationParams !== EMPTY_OBJECT && Object.keys(interpolationParams).length > 0) {
       for (const [paramKey, paramValue] of Object.entries(interpolationParams)) {
         let regex = paramRegexCache.get(paramKey);
         if (regex === undefined) {
@@ -468,12 +539,84 @@ function createTranslator(translations = {}) {
             paramRegexCache.set(paramKey, regex);
           }
         }
-        value = value.replace(regex, paramValue);
+        value = value.replace(regex, () => String(paramValue));
       }
     }
-    
+
     return value;
+  }
+
+  // Attach metadata & native formatting helpers to `t`
+  t.locale = locale;
+  t.translations = translations;
+
+  t.number = function formatNumber(num, numOpts) {
+    if (num === null || num === undefined || Number.isNaN(Number(num))) return '';
+    try {
+      return new Intl.NumberFormat(locale, numOpts).format(Number(num));
+    } catch {
+      return String(num);
+    }
+  };
+  t.formatNumber = t.number;
+
+  t.currency = function formatCurrency(amount, currency = 'USD', currOpts = {}) {
+    if (amount === null || amount === undefined || Number.isNaN(Number(amount))) return '';
+    try {
+      return new Intl.NumberFormat(locale, { style: 'currency', currency, ...currOpts }).format(Number(amount));
+    } catch {
+      return `${amount} ${currency}`;
+    }
+  };
+  t.formatCurrency = t.currency;
+
+  t.date = function formatDate(date, dateOpts = { dateStyle: 'medium' }) {
+    if (!date) return '';
+    try {
+      const d = date instanceof Date ? date : new Date(date);
+      if (Number.isNaN(d.getTime())) return '';
+      return new Intl.DateTimeFormat(locale, dateOpts).format(d);
+    } catch {
+      return String(date);
+    }
+  };
+  t.formatDate = t.date;
+
+  t.relativeTime = function formatRelativeTime(val, unit = 'day', relOpts = { numeric: 'auto' }) {
+    if (val === null || val === undefined || Number.isNaN(Number(val))) return '';
+    try {
+      return new Intl.RelativeTimeFormat(locale, relOpts).format(Number(val), unit);
+    } catch {
+      return `${val} ${unit}`;
+    }
+  };
+  t.formatRelativeTime = t.relativeTime;
+
+  t.plural = function inlinePlural(count, forms, params = {}) {
+    if (!forms || typeof forms !== 'object') return '';
+    const num = Number(count);
+    const countStr = String(num);
+    let template = forms[countStr];
+    if (typeof template !== 'string') {
+      if (num === 0 && typeof forms.zero === 'string') {
+        template = forms.zero;
+      } else {
+        const category = getPluralRules(locale).select(num);
+        template = forms[category] || forms.other || Object.values(forms)[0] || '';
+      }
+    }
+    const allParams = { count: num, ...params };
+    return template.replace(/{{\s*(\w+)\s*}}/g, (_, k) => String(allParams[k] ?? ''));
+  };
+
+  t.has = function hasKey(key) {
+    if (resolveTranslationValue(translations, key) !== undefined) return true;
+    if (fallbackTranslations && resolveTranslationValue(fallbackTranslations, key) !== undefined) return true;
+    return false;
   };
+  t.exists = t.has;
+
+  return t;
 }
 
 /**
@@ -677,6 +820,7 @@ function mountPages(app, options) {
     db = null,
     clientRuntime: clientRuntimeOpt = null,
     pageAssets: pageAssetsOpt = null,
+    serviceRegistry = null,
   } = options;
   const pageAssetsResolved = resolvePageAssets(pageAssetsOpt);
   const clientRuntime = clientRuntimeOpt && typeof clientRuntimeOpt === 'object'
@@ -851,6 +995,10 @@ function mountPages(app, options) {
         if (db != null) {
           req.db = db;
         }
+        if (serviceRegistry != null) {
+          req.service = (name, input, opts) =>
+            serviceRegistry.call(name, input, { req, res, db }, opts);
+        }
 
         // Reload handler in dev mode
         if (isDev && require.cache[require.resolve(route.fullPath)]) {
@@ -928,17 +1076,26 @@ function mountPages(app, options) {
       try {
         // Detect locale
         const locale = detectLocale(req);
+        const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
         
-        // Load translations
+        // Load translations (primary + fallback)
         const translations = loadI18n(absolutePagesDir, route.routeDir, locale);
-        const t = createTranslator(translations);
+        const fallbackTranslations = (locale !== defaultLocale)
+          ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale)
+          : EMPTY_OBJECT;
+
+        const t = createTranslator(translations, {
+          locale,
+          fallbackTranslations,
+          fallbackLocale: defaultLocale,
+        });
         
         // Load route config
         const config = loadRouteConfig(route.configPath, isDev);
         const routeHooks = config?.hooks || EMPTY_OBJECT;
         
         // Create context with plugin helpers merged
-        const baseHelpers = createHelpers({ req, res, locale });
+        const baseHelpers = createHelpers({ req, res, locale, t });
         const pluginHelpers = pluginManager ? pluginManager.getHelpers() : EMPTY_OBJECT;
         if (pluginManager) {
           const contentApi = pluginManager.getPluginAPI('content');
@@ -959,6 +1116,12 @@ function mountPages(app, options) {
           routeDir: route.routeDir,
           locale,
           t,
+          service: (name, input, opts) => {
+            if (serviceRegistry) {
+              return serviceRegistry.call(name, input, ctx, opts);
+            }
+            throw new Error(`Services not configured. Cannot call service '${name}'.`);
+          },
           data: { ...njkTpl.dataPatch },
           meta: {
             title: t('meta.title') !== 'meta.title' ? t('meta.title') : null,
@@ -1055,6 +1218,18 @@ function mountPages(app, options) {
         
         // Render the template
         const templatePath = route.file.split(path.sep).join('/');
+
+        // SSR Streaming mode (chunked transfer)
+        if (config?.stream || ctx.data?.__stream || ctx.defer) {
+          const streamDefer = ctx.defer || ctx.data?.__defer || {};
+          const status = (route.routePath === '/404' || route.file === '404.njk') ? 404 : 200;
+          return await renderStream(res, templatePath, renderContext, {
+            env: nunjucks,
+            defer: streamDefer,
+            status,
+          });
+        }
+
         let html =
           njkTpl.useStringRender && njkTpl.templateBody != null
             ? nunjucks.renderString(njkTpl.templateBody, renderContext, { path: route.fullPath })

package/src/helpers.js

@@ -140,7 +140,7 @@ class AssetManager {
    */
   buildAttributes(attrs) {
     return Object.entries(attrs)
-      .filter(([_, v]) => v !== undefined && v !== null && v !== false)
+      .filter(([k, v]) => v !== undefined && v !== null && v !== false && /^[a-zA-Z0-9_\-:]+$/.test(k))
       .map(([k, v]) => v === true ? k : `${k}="${this.escapeHtml(String(v))}"`)
       .join(' ');
   }
@@ -186,9 +186,27 @@ function getAssetManager() {
  * @returns {Object} fsy helper object
  */
 function createHelpers(ctx) {
-  const { req, res, baseUrl = process.env.BASE_URL || 'http://localhost:3000' } = ctx;
+  const { req, res, baseUrl = process.env.BASE_URL || 'http://localhost:3000', locale = 'en', t = null } = ctx || {};
 
   return {
+    /** Active request locale */
+    locale,
+
+    /** Active i18n translator function */
+    t,
+
+    /**
+     * Generate URL for switching to a target locale with current query parameters preserved
+     * @param {string} targetLocale - Locale code to switch to (e.g. 'en', 'tr')
+     * @param {string} [customPath] - Optional custom path (defaults to current req.path)
+     * @returns {string} URL string with updated locale query param
+     */
+    localeUrl(targetLocale, customPath) {
+      const p = customPath || (req && req.path ? req.path : '/');
+      const q = { ...(req && req.query ? req.query : {}), lang: targetLocale };
+      return this.url(p, q);
+    },
+
     /**
      * Build a URL path with optional query parameters
      * @param {string} path - URL path

package/src/plugin-manager.js

@@ -123,20 +123,37 @@ class PluginManager {
     this.routes = [];                   // Collected route metadata
     this.customRoutes = [];             // Routes added by plugins
     this.cspDirectives = new Map();     // directive -> Set of sources (from plugins)
+    this.disposers = [];                // Array<{ name: string, fn: Function }>
     this.app = null;
     this.nunjucksEnv = null;
+    this.shutdownManager = null;
+  }
+
+  /**
+   * Register a plugin disposer
+   * @param {string} name
+   * @param {Function} fn
+   */
+  registerDisposer(name, fn) {
+    if (typeof fn === 'function') {
+      this.disposers.push({ name: name || 'plugin', fn });
+      if (this.shutdownManager && typeof this.shutdownManager.registerDisposer === 'function') {
+        this.shutdownManager.registerDisposer(name, fn);
+      }
+    }
   }
 
   /**
    * Register plugins with the manager (async version)
    * @param {Array} plugins - Array of plugin definitions or factory functions
-   * @param {Object} context - Context object `{ app, nunjucksEnv, options, middlewares? }`
+   * @param {Object} context - Context object `{ app, nunjucksEnv, options, middlewares?, shutdownManager? }`
    */
   async register(plugins, context) {
     if (!plugins || !Array.isArray(plugins)) return;
 
     this.app = context.app;
     this.nunjucksEnv = context.nunjucksEnv;
+    this.shutdownManager = context.shutdownManager || null;
 
     // Normalize plugins (handle factory functions)
     const normalizedPlugins = plugins.map(p => {
@@ -159,13 +176,14 @@ class PluginManager {
   /**
    * Register plugins with the manager (sync version)
    * @param {Array} plugins - Array of plugin definitions or factory functions
-   * @param {Object} context - Context object `{ app, nunjucksEnv, options, middlewares? }`
+   * @param {Object} context - Context object `{ app, nunjucksEnv, options, middlewares?, shutdownManager? }`
    */
   registerSync(plugins, context) {
     if (!plugins || !Array.isArray(plugins)) return;
 
     this.app = context.app;
     this.nunjucksEnv = context.nunjucksEnv;
+    this.shutdownManager = context.shutdownManager || null;
 
     // Normalize plugins (handle factory functions)
     const normalizedPlugins = plugins.map(p => {
@@ -276,10 +294,32 @@ class PluginManager {
       this._collectCspDirectives(plugin.csp);
     }
 
+    let hasDisposer = false;
+
+    // Call setup hook if provided
+    if (typeof plugin.setup === 'function') {
+      try {
+        const result = await plugin.setup(ctx.app || ctx);
+        if (typeof result === 'function') {
+          this.registerDisposer(plugin.name, result);
+          hasDisposer = true;
+        }
+      } catch (err) {
+        console.warn(`[plugin-manager] Plugin "${plugin.name}" setup() failed:`, err.message);
+        this.plugins.delete(plugin.name);
+        if (plugin.api) this.pluginAPIs.delete(plugin.name);
+        return;
+      }
+    }
+
     // Call register hook
     if (typeof plugin.register === 'function') {
       try {
-        await plugin.register(ctx);
+        const result = await plugin.register(ctx);
+        if (typeof result === 'function') {
+          this.registerDisposer(plugin.name, result);
+          hasDisposer = true;
+        }
       } catch (err) {
         console.warn(`[plugin-manager] Plugin "${plugin.name}" register() failed:`, err.message);
         this.plugins.delete(plugin.name);
@@ -288,6 +328,15 @@ class PluginManager {
       }
     }
 
+    // Support explicit shutdown or dispose methods if not already registered
+    if (!hasDisposer) {
+      if (typeof plugin.shutdown === 'function') {
+        this.registerDisposer(plugin.name, () => plugin.shutdown(ctx.app || ctx));
+      } else if (typeof plugin.dispose === 'function') {
+        this.registerDisposer(plugin.name, () => plugin.dispose(ctx));
+      }
+    }
+
     // Apply registered helpers to nunjucks
     this._applyHelpersAndFilters();
   }
@@ -320,10 +369,32 @@ class PluginManager {
       this._collectCspDirectives(plugin.csp);
     }
 
+    let hasDisposer = false;
+
+    // Call setup hook if provided
+    if (typeof plugin.setup === 'function') {
+      try {
+        const result = plugin.setup(ctx.app || ctx);
+        if (typeof result === 'function') {
+          this.registerDisposer(plugin.name, result);
+          hasDisposer = true;
+        }
+      } catch (err) {
+        console.warn(`[plugin-manager] Plugin "${plugin.name}" setup() failed:`, err.message);
+        this.plugins.delete(plugin.name);
+        if (plugin.api) this.pluginAPIs.delete(plugin.name);
+        return;
+      }
+    }
+
     // Call register hook (sync - if plugin has async register, it won't wait)
     if (typeof plugin.register === 'function') {
       try {
-        plugin.register(ctx);
+        const result = plugin.register(ctx);
+        if (typeof result === 'function') {
+          this.registerDisposer(plugin.name, result);
+          hasDisposer = true;
+        }
       } catch (err) {
         console.warn(`[plugin-manager] Plugin "${plugin.name}" register() failed:`, err.message);
         this.plugins.delete(plugin.name);
@@ -332,6 +403,15 @@ class PluginManager {
       }
     }
 
+    // Support explicit shutdown or dispose methods if not already registered
+    if (!hasDisposer) {
+      if (typeof plugin.shutdown === 'function') {
+        this.registerDisposer(plugin.name, () => plugin.shutdown(ctx.app || ctx));
+      } else if (typeof plugin.dispose === 'function') {
+        this.registerDisposer(plugin.name, () => plugin.dispose(ctx));
+      }
+    }
+
     // Apply registered helpers to nunjucks
     this._applyHelpersAndFilters();
   }
@@ -421,6 +501,22 @@ class PluginManager {
       // Script Injection API
       // ============================================
 
+      /**
+       * Register a cleanup / disposer hook for this plugin
+       * @param {Function} fn
+       */
+      onDispose(fn) {
+        self.registerDisposer(plugin.name, fn);
+      },
+
+      /**
+       * Alias for onDispose
+       * @param {Function} fn
+       */
+      onShutdown(fn) {
+        self.registerDisposer(plugin.name, fn);
+      },
+
       /**
        * Inject content into head section
        * @param {string} content - HTML/script content
@@ -583,6 +679,30 @@ class PluginManager {
     return this.plugins.has(name);
   }
 
+  /**
+   * Get all registered disposers
+   * @returns {Array<{ name: string, fn: Function }>}
+   */
+  getDisposers() {
+    return this.disposers.slice();
+  }
+
+  /**
+   * Execute all registered plugin disposers in reverse registration order
+   * @returns {Promise<void>}
+   */
+  async dispose() {
+    const reverseDisposers = this.disposers.slice().reverse();
+    for (const { name, fn } of reverseDisposers) {
+      try {
+        await fn();
+      } catch (err) {
+        console.warn(`[plugin-manager] Plugin "${name}" disposer failed:`, err.message);
+      }
+    }
+    this.disposers = [];
+  }
+
   /**
    * Get all registered plugin names
    */