millas 0.2.12-beta → 0.2.12-beta-2

package/src/http/adapters/HttpAdapter.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * HttpAdapter
+ *
+ * Abstract interface between the Millas kernel and any underlying HTTP engine.
+ * The kernel never imports Express (or Fastify, or Hono) directly — it only
+ * calls the methods defined here.
+ *
+ * To add a new HTTP engine, create a class that extends HttpAdapter and
+ * implements every method. The kernel works unchanged.
+ *
+ * ── Implemented by ───────────────────────────────────────────────────────────
+ *
+ *   ExpressAdapter   (default, ships with Millas)
+ *   FastifyAdapter   (future)
+ *   HonoAdapter      (future)
+ *
+ * ── Lifecycle ────────────────────────────────────────────────────────────────
+ *
+ *   1. adapter.applyBodyParsers()          — JSON + urlencoded
+ *   2. adapter.applyMiddleware(fn)         — any raw adapter-level middleware
+ *   3. adapter.mountRoute(verb, path, handlers) — register app routes
+ *   4. adapter.mountWelcome(handler)       — optional dev welcome page
+ *   5. adapter.mountNotFound()             — 404 handler
+ *   6. adapter.mountErrorHandler()         — global error handler
+ *   7. await adapter.listen(port, host)    — start accepting connections
+ *   8. adapter.close()                     — graceful shutdown
+ */
+class HttpAdapter {
+
+  // ── Setup ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Apply JSON + urlencoded body parsers.
+   * Called once during bootstrap, before any routes are mounted.
+   */
+  applyBodyParsers() {
+    throw new Error(`${this.constructor.name} must implement applyBodyParsers()`);
+  }
+
+  /**
+   * Apply a single raw middleware function at the adapter level.
+   * Used for things like helmet(), compression() that are engine-specific.
+   *
+   * @param {Function} fn  — adapter-native middleware function
+   */
+  applyMiddleware(fn) {
+    throw new Error(`${this.constructor.name} must implement applyMiddleware(fn)`);
+  }
+
+  // ── Route mounting ─────────────────────────────────────────────────────────
+
+  /**
+   * Register a route handler.
+   *
+   * @param {string}     verb      — 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS'
+   * @param {string}     path      — e.g. '/users/:id'
+   * @param {Function[]} handlers  — [middleware..., terminalHandler]
+   *                                 Each handler is a Millas kernel handler
+   *                                 (expressReq, expressRes, expressNext) already
+   *                                 converted by the adapter's wrapKernelHandler().
+   */
+  mountRoute(verb, path, handlers) {
+    throw new Error(`${this.constructor.name} must implement mountRoute(verb, path, handlers)`);
+  }
+
+  /**
+   * Mount the dev welcome page for GET /.
+   * Only called when no user route covers GET /.
+   *
+   * @param {Function} handler  — adapter-native handler function
+   */
+  mountWelcome(handler) {
+    throw new Error(`${this.constructor.name} must implement mountWelcome(handler)`);
+  }
+
+  /**
+   * Mount the 404 fallback handler.
+   * Must be called AFTER all routes and mountWelcome().
+   */
+  mountNotFound() {
+    throw new Error(`${this.constructor.name} must implement mountNotFound()`);
+  }
+
+  /**
+   * Mount the global error handler.
+   * Must be called LAST — after mountNotFound().
+   */
+  mountErrorHandler() {
+    throw new Error(`${this.constructor.name} must implement mountErrorHandler()`);
+  }
+
+  // ── Request / Response bridge ──────────────────────────────────────────────
+
+  /**
+   * Wrap a Millas kernel handler function into an adapter-native handler.
+   *
+   * The kernel handler signature is:
+   *   (millaCtx: RequestContext, trackedNext: Function) => Promise<MillasResponse>
+   *
+   * The adapter wraps this into whatever its native handler signature is,
+   * e.g. (req, res, next) for Express.
+   *
+   * @param {Function} kernelFn
+   * @param {string}   displayName  — for error messages
+   * @param {object}   container    — DI container
+   * @returns {Function}  adapter-native handler
+   */
+  wrapKernelHandler(kernelFn, displayName, container) {
+    throw new Error(`${this.constructor.name} must implement wrapKernelHandler()`);
+  }
+
+  /**
+   * Wrap a Millas middleware instance into an adapter-native handler.
+   *
+   * @param {object} instance  — Millas Middleware instance with handle(ctx, next)
+   * @param {object} container — DI container
+   * @returns {Function}  adapter-native handler
+   */
+  wrapMiddleware(instance, container) {
+    throw new Error(`${this.constructor.name} must implement wrapMiddleware()`);
+  }
+
+  /**
+   * Dispatch a MillasResponse to the underlying engine's response object.
+   *
+   * @param {MillasResponse} response
+   * @param {*}              nativeRes  — e.g. Express res
+   */
+  dispatch(response, nativeRes) {
+    throw new Error(`${this.constructor.name} must implement dispatch(response, nativeRes)`);
+  }
+
+  // ── Server lifecycle ───────────────────────────────────────────────────────
+
+  /**
+   * Start listening on port/host.
+   * Returns a Promise that resolves once the server is bound.
+   *
+   * @param {number} port
+   * @param {string} host
+   * @returns {Promise<void>}
+   */
+  listen(port, host) {
+    throw new Error(`${this.constructor.name} must implement listen(port, host)`);
+  }
+
+  /**
+   * Gracefully close the server.
+   * Returns a Promise that resolves once all connections are drained.
+   *
+   * @returns {Promise<void>}
+   */
+  close() {
+    throw new Error(`${this.constructor.name} must implement close()`);
+  }
+
+  /**
+   * The name of this adapter, used in logs and error messages.
+   * @returns {string}
+   */
+  get name() {
+    return this.constructor.name;
+  }
+}
+
+module.exports = HttpAdapter;

package/src/http/adapters/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const HttpAdapter    = require('./HttpAdapter');
+const ExpressAdapter = require('./ExpressAdapter');
+
+module.exports = {
+  HttpAdapter,
+  ExpressAdapter,
+};

package/src/i18n/I18nServiceProvider.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const path        = require('path');
+const fs          = require('fs');
+const ServiceProvider = require('../providers/ServiceProvider');
+const Translator  = require('./Translator');
+
+/**
+ * I18nServiceProvider
+ *
+ * Boots the translation system and registers the Trans singleton
+ * into the DI container.
+ *
+ * ── Setup in bootstrap/app.js ─────────────────────────────────────────────
+ *
+ *   const { Millas } = require('millas');
+ *   const I18nServiceProvider = require('millas/src/i18n/I18nServiceProvider');
+ *
+ *   module.exports = Millas.config()
+ *     .providers([I18nServiceProvider, AppServiceProvider])
+ *     .create();
+ *
+ * ── config/app.js ─────────────────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     locale:   'en',       // default locale
+ *     fallback: 'en',       // fallback when translation missing
+ *   };
+ *
+ * ── lang/ directory ───────────────────────────────────────────────────────
+ *
+ *   Place translation files at <basePath>/lang/:
+ *
+ *   lang/
+ *     en.js     ← source language
+ *     sw.js     ← Swahili
+ *     fr.js     ← French
+ *
+ * ── Route-level locale switching ──────────────────────────────────────────
+ *
+ *   Use the built-in middleware to auto-detect locale from requests:
+ *
+ *   const { Trans } = require('millas/src/i18n');
+ *   app.use(Trans.middleware());
+ *
+ *   Or manually in a route:
+ *   Trans.setLocale('sw');
+ */
+class I18nServiceProvider extends ServiceProvider {
+
+  register(container) {
+    // Register the Trans singleton into the DI container
+    const trans = require('./index').Trans;
+    container.instance('trans', trans);
+    container.instance('Trans', trans);
+    container.alias('i18n', 'trans');
+  }
+
+  async boot(container, app) {
+    const basePath = container.make('basePath') || process.cwd();
+    const trans    = container.make('trans');
+
+    // Load config/app.js for locale settings
+    let locale   = 'en';
+    let fallback = 'en';
+    let warnMissing = process.env.NODE_ENV !== 'production';
+
+    try {
+      const appConfig = require(path.join(basePath, 'config/app'));
+      if (appConfig.locale)   locale   = appConfig.locale;
+      if (appConfig.fallback) fallback = appConfig.fallback;
+    } catch { /* config/app.js not found or no locale keys */ }
+
+    // Lang path: <basePath>/lang/
+    const langPath = path.join(basePath, 'lang');
+
+    trans.configure({ locale, fallback, langPath, warnMissing });
+
+    // Log available locales on startup in debug mode
+    if (process.env.DEBUG || process.env.NODE_ENV === 'development') {
+      const available = trans.availableLocales();
+      if (available.length > 0 && !(available.length === 1 && available[0] === 'en')) {
+        process.stdout.write(
+          `[i18n] Locale: ${locale} | Fallback: ${fallback} | Available: ${available.join(', ')}\n`
+        );
+      }
+    }
+  }
+}
+
+module.exports = I18nServiceProvider;