webspresso 0.0.89 → 0.0.91

package/src/app-context.js

@@ -3,21 +3,23 @@
  * @module src/app-context
  */
 
-/** @type {{ db: object|null }} */
+/** @type {{ db: object|null, shutdownManager: object|null, serviceRegistry: object|null }} */
 let context = {
   db: null,
+  shutdownManager: null,
+  serviceRegistry: null,
 };
 
 /**
  * Merge into the current context (typically called once from createApp).
- * @param {{ db?: object|null }} partial
+ * @param {{ db?: object|null, shutdownManager?: object|null, serviceRegistry?: object|null }} partial
  */
 function setAppContext(partial) {
   context = { ...context, ...partial };
 }
 
 /**
- * @returns {{ db: object|null }}
+ * @returns {{ db: object|null, shutdownManager: object|null, serviceRegistry: object|null }}
  */
 function getAppContext() {
   return context;
@@ -45,23 +47,57 @@ function hasDb() {
   return context.db != null;
 }
 
+/**
+ * @returns {object|null}
+ */
+function getShutdownManager() {
+  return context.shutdownManager;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasShutdownManager() {
+  return context.shutdownManager != null;
+}
+
+/**
+ * Get the registered ServiceRegistry instance
+ * @returns {object|null}
+ */
+function getServiceRegistry() {
+  return context.serviceRegistry;
+}
+
+/**
+ * Check if a ServiceRegistry is registered
+ * @returns {boolean}
+ */
+function hasServiceRegistry() {
+  return context.serviceRegistry != null;
+}
+
 /**
  * Clear context (e.g. between tests).
  */
 function resetAppContext() {
-  context = { db: null };
+  context = { db: null, shutdownManager: null, serviceRegistry: null };
 }
 
 /**
- * Express middleware: sets `req.db` from registered app context.
+ * Express middleware: sets `req.db` and `req.service` from registered app context.
  * File-based `pages/api/*` routes attach this automatically; use in `setupRoutes`
- * for manually registered handlers that need `req.db`.
+ * for manually registered handlers that need `req.db` and `req.service`.
  * @type {import('express').RequestHandler}
  */
 function attachDbMiddleware(req, res, next) {
   if (context.db != null) {
     req.db = context.db;
   }
+  if (context.serviceRegistry != null) {
+    req.service = (name, input, opts) =>
+      context.serviceRegistry.call(name, input, req.context || { req, res, db: context.db }, opts);
+  }
   next();
 }
 
@@ -70,6 +106,10 @@ module.exports = {
   getAppContext,
   getDb,
   hasDb,
+  getShutdownManager,
+  hasShutdownManager,
+  getServiceRegistry,
+  hasServiceRegistry,
   resetAppContext,
   attachDbMiddleware,
 };

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,36 +433,104 @@ function loadI18n(pagesDir, routeDir, locale) {
   return data;
 }
 
+// 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 function
- * @param {Object} translations - Translation object
- * @returns {Function} Translation function t(key)
+ * 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) {
-  return function t(key, params = EMPTY_OBJECT) {
-    let value = translations[key];
-    
-    if (value === undefined) {
-      // 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];
+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 = 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 key; // Return key if translation not found
+      return defaultValue !== null && defaultValue !== undefined ? defaultValue : key;
     }
-    
+
+    if (typeof value !== 'string') {
+      return value;
+    }
+
     // Replace params like {{name}} in the translation
-    if (typeof value === 'string' && params && params !== EMPTY_OBJECT && Object.keys(params).length > 0) {
-      for (const [paramKey, paramValue] of Object.entries(params)) {
+    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) {
           const escaped = escapeRegExp(paramKey);
@@ -470,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;
 }
 
 /**
@@ -679,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'
@@ -814,6 +956,18 @@ function mountPages(app, options) {
   sortRoutes(apiRoutes);
   sortRoutes(ssrRoutes);
 
+  // Check for duplicate route bindings
+  const registeredRouteMap = new Map();
+  for (const r of [...apiRoutes, ...ssrRoutes]) {
+    const key = `${(r.method || 'GET').toUpperCase()} ${r.routePath}`;
+    if (registeredRouteMap.has(key)) {
+      const existing = registeredRouteMap.get(key);
+      console.warn(`[webspresso] WARNING: Duplicate route detected: ${key} in "${r.file}" conflicts with existing route in "${existing.file}".`);
+    } else {
+      registeredRouteMap.set(key, r);
+    }
+  }
+
   const apiStatic = apiRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier === 0);
   const apiDynamic = apiRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier !== 0);
   const ssrStatic = ssrRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier === 0);
@@ -841,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)]) {
@@ -918,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');
@@ -949,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,
@@ -1002,7 +1175,9 @@ function mountPages(app, options) {
         // Run load function
         if (config?.load && typeof config.load === 'function') {
           const loadData = await config.load(req, ctx);
-          ctx.data = { ...ctx.data, ...loadData };
+          if (loadData && typeof loadData === 'object' && !Array.isArray(loadData)) {
+            ctx.data = { ...ctx.data, ...loadData };
+          }
         }
         
         // Execute hooks: afterLoad
@@ -1012,7 +1187,9 @@ function mountPages(app, options) {
         // Run meta function
         if (config?.meta && typeof config.meta === 'function') {
           const metaData = await config.meta(req, ctx);
-          ctx.meta = { ...ctx.meta, ...metaData };
+          if (metaData && typeof metaData === 'object' && !Array.isArray(metaData)) {
+            ctx.meta = { ...ctx.meta, ...metaData };
+          }
         }
         
         // Execute hooks: beforeRender
@@ -1041,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 })
@@ -1058,6 +1247,9 @@ function mountPages(app, options) {
         await executeHook(globalHooks, 'afterRender', ctx);
         await executeHook(routeHooks, 'afterRender', ctx);
         
+        if (route.routePath === '/404' || route.file === '404.njk') {
+          res.status(404);
+        }
         res.send(ctx.html);
       } catch (err) {
         console.error(`SSR error ${route.routePath}:`, err);

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
@@ -236,7 +254,7 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     q(name, def = null) {
-      return req.query[name] !== undefined ? req.query[name] : def;
+      return req && req.query && req.query[name] !== undefined ? req.query[name] : def;
     },
 
     /**
@@ -246,7 +264,7 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     param(name, def = null) {
-      return req.params[name] !== undefined ? req.params[name] : def;
+      return req && req.params && req.params[name] !== undefined ? req.params[name] : def;
     },
 
     /**
@@ -256,7 +274,8 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     hdr(name, def = null) {
-      return req.get(name) || def;
+      if (!req) return def;
+      return (typeof req.get === 'function' ? req.get(name) : (req.headers && req.headers[name.toLowerCase()])) || def;
     },
 
     /**