millas 0.2.11 → 0.2.12-beta-1

package/src/container/MillasApp.js

@@ -1,299 +1,42 @@
 'use strict';
 
-const express  = require('express');
-const Application = require('./Application');
+const MillasConfig = require('./MillasConfig');
 
 /**
- * MillasApp
- *
- * A clean factory wrapper around Application that wires up Express,
- * core providers, routes, and the admin panel automatically.
- *
- * Reduces bootstrap/app.js from ~60 lines to ~8.
- *
- * ── Usage ───────────────────────────────────────────────────────────────────
+ * Millas
+
+ * ── bootstrap/app.js ────────────────────────────────────────────────────────
  *
- *   require('dotenv').config();
- *   const { MillasApp } = require('millas');
- *   const AppServiceProvider = require('../providers/AppServiceProvider');
+ *   const { Millas } = require('millas');
  *
- *   const app = MillasApp.create()
+ *   module.exports = Millas.config()
  *     .providers([AppServiceProvider])
  *     .routes(Route => {
  *       require('../routes/web')(Route);
  *       require('../routes/api')(Route);
  *     })
- *     .withAdmin();
- *
- *   module.exports = app.start();
- *
- * ── Escape hatches ──────────────────────────────────────────────────────────
- *
- *   // Access the raw Express app
- *   app.express.use(someExpressMiddleware());
- *
- *   // Access the DI container
- *   app.container.make('db');
- *
- *   // Access the underlying Application kernel
- *   app.kernel
+ *     .withAdmin()
+ *     .create();
  *
- * ── Advanced ────────────────────────────────────────────────────────────────
+ * That is everything a developer writes. The rest is handled internally.
  *
- *   MillasApp.create({
- *     // Disable a core provider
- *     mail:    false,
- *     queue:   false,
+ * Millas.config()   → MillasConfig  (chainable, collects config only)
+ * .create()         → MillasInstance (sealed carrier, no callable methods)
  *
- *     // Custom admin prefix
- *     admin:   { prefix: '/cms', title: 'My CMS' },
- *
- *     // Add Express middleware before routes
- *     expressMiddleware: [cors(), helmet()],
- *
- *     // Called once the app is listening
- *     onStart: (port, host) => console.log(`Running on ${host}:${port}`),
- *   })
+ * The framework's AppInitialiser receives the MillasInstance, reads its
+ * config, and boots the full application — adapter, kernel, providers,
+ * routes, admin, HTTP server — without the developer being involved.
  */
-class MillasApp {
-
-  // ─── Factory ──────────────────────────────────────────────────────────────
-
-  /**
-   * Create a new MillasApp instance.
-   * @param {object} [options]
-   * @param {boolean} [options.database=true]   — register DatabaseServiceProvider
-   * @param {boolean} [options.cache=true]      — register CacheServiceProvider
-   * @param {boolean} [options.storage=true]    — register StorageServiceProvider
-   * @param {boolean} [options.mail=true]       — register MailServiceProvider
-   * @param {boolean} [options.queue=true]      — register QueueServiceProvider
-   * @param {boolean} [options.events=true]     — register EventServiceProvider
-   * @param {boolean} [options.logging=true]    — register LogServiceProvider
-   * @param {Array}   [options.expressMiddleware] — Express middleware applied before routes
-   * @param {Function}[options.onStart]         — callback(port, host) after listen
-   */
-  static create(options = {}) {
-    return new MillasApp(options);
-  }
-
-  constructor(options = {}) {
-    this._options      = options;
-    this._userProviders = [];
-    this._routesCb     = null;
-    this._adminOptions = null;   // null = no admin; object/true = mount admin
-    this._expressApp   = null;
-    this._kernel       = null;
-    this._started      = false;
-  }
-
-  // ─── Fluent API ───────────────────────────────────────────────────────────
-
+const Millas = {
   /**
-   * Register application service providers.
+   * Start building an application config.
+   * Returns a MillasConfig chain ending in .create().
    *
-   *   .providers([AppServiceProvider, PaymentServiceProvider])
+   * @returns {MillasConfig}
    */
-  providers(list = []) {
-    this._userProviders.push(...list);
-    return this;
-  }
-
-  /**
-   * Define application routes.
-   *
-   *   .routes(Route => {
-   *     require('../routes/web')(Route);
-   *     require('../routes/api')(Route);
-   *   })
-   */
-  routes(callback) {
-    this._routesCb = callback;
-    return this;
-  }
-
-  /**
-   * Register a named middleware alias.
-   * Must be called before start().
-   *
-   *   .middleware('verified', EmailVerifiedMiddleware)
-   */
-  middleware(alias, handler) {
-    if (!this._pendingMiddleware) this._pendingMiddleware = [];
-    this._pendingMiddleware.push({ alias, handler });
-    return this;
-  }
-
-  /**
-   * Mount the admin panel.
-   *
-   *   .withAdmin()                          // default /admin
-   *   .withAdmin({ prefix: '/cms' })        // custom prefix
-   *   .withAdmin({ prefix: '/admin', auth: { users: [...] } })
-   */
-  withAdmin(options = {}) {
-    this._adminOptions = options;
-    return this;
-  }
-
-  // ─── Start ────────────────────────────────────────────────────────────────
-
-  /**
-   * Boot all providers, mount routes, and start listening.
-   * Returns an object with { app, expressApp, route } for module.exports.
-   *
-   * Safe to await if you need to run code after boot:
-   *   const { app } = await MillasApp.create()...start();
-   */
-  start() {
-    // Build Express + Application kernel
-    this._expressApp = express();
-    this._expressApp.use(express.json());
-    this._expressApp.use(express.urlencoded({ extended: true }));
-
-    // Apply any extra Express middleware (e.g. helmet, cors)
-    for (const mw of (this._options.expressMiddleware || [])) {
-      this._expressApp.use(mw);
-    }
-
-    this._kernel = new Application(this._expressApp);
-
-    // Register pending middleware aliases
-    for (const { alias, handler } of (this._pendingMiddleware || [])) {
-      this._kernel.middleware(alias, handler);
-    }
-
-    // Register core providers (auto, unless disabled)
-    const coreProviders = this._buildCoreProviders();
-    this._kernel.providers([...coreProviders, ...this._userProviders]);
-
-    // Register routes
-    if (this._routesCb) {
-      this._kernel.routes(this._routesCb);
-    }
-
-    // Boot asynchronously
-    const self = this;
-    const boot = (async () => {
-      await self._kernel.boot();
-
-      if (!process.env.MILLAS_ROUTE_LIST) {
-        self._kernel.mountRoutes();
-
-        // Admin panel (mounted between routes and fallbacks)
-        if (self._adminOptions !== null) {
-          const adminOpts = typeof self._adminOptions === 'object'
-            ? self._adminOptions
-            : {};
-
-          try {
-            const Admin = require('../admin/Admin');
-            if (Object.keys(adminOpts).length) {
-              Admin.configure(adminOpts);
-            }
-            Admin.mount(self._expressApp);
-          } catch (err) {
-            process.stderr.write(`[millas] Admin mount failed: ${err.message}\n`);
-          }
-        }
-
-        self._kernel.mountFallbacks();
-
-        const onStart = self._options.onStart || null;
-        self._kernel.listen(undefined, undefined, onStart || undefined);
-      }
-
-      self._started = true;
-    })();
-
-    // Expose the promise for testing / programmatic use
-    this._bootPromise = boot;
-
-    return this;
-  }
-
-  /**
-   * Await the boot promise. Useful in tests or scripts.
-   *
-   *   const app = await MillasApp.create().routes(...).start().ready();
-   */
-  async ready() {
-    await (this._bootPromise || Promise.resolve());
-    return this;
-  }
-
-  // ─── Escape hatches ───────────────────────────────────────────────────────
-
-  /** The raw Express application instance. */
-  get express()    { return this._expressApp; }
-
-  /** The underlying Application kernel (also accessible as .app for back-compat). */
-  get kernel()     { return this._kernel; }
-  get app()        { return this._kernel; }
-
-  /** The DI container. */
-  get container()  { return this._kernel?._container; }
-
-  /** The Route instance — used by route:list command. */
-  get route()      { return this._kernel?._route; }
-
-  /**
-   * The raw Express app — backward-compatible alias.
-   * Allows: const { expressApp } = require('./bootstrap/app')
-   */
-  get expressApp() { return this._expressApp; }
-
-  // ─── Internal ─────────────────────────────────────────────────────────────
-
-  _buildCoreProviders() {
-    const opts = this._options;
-    const providers = [];
-
-    // Helper — require a provider, silently skip if not found
-    const load = (path) => {
-      try { return require(path); } catch { return null; }
-    };
-
-    // Logging — first so all other providers can use Log
-    if (opts.logging !== false) {
-      const p = load('../providers/LogServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Database
-    if (opts.database !== false) {
-      const p = load('../providers/DatabaseServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Cache + Storage
-    if (opts.cache !== false || opts.storage !== false) {
-      const p = load('../providers/CacheStorageServiceProvider');
-      if (p) {
-        if (opts.cache    !== false && p.CacheServiceProvider)   providers.push(p.CacheServiceProvider);
-        if (opts.storage  !== false && p.StorageServiceProvider) providers.push(p.StorageServiceProvider);
-      }
-    }
-
-    // Mail
-    if (opts.mail !== false) {
-      const p = load('../providers/MailServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Queue
-    if (opts.queue !== false) {
-      const p = load('../providers/QueueServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    // Events
-    if (opts.events !== false) {
-      const p = load('../providers/EventServiceProvider');
-      if (p) providers.push(p);
-    }
-
-    return providers;
-  }
-}
+  config() {
+    return new MillasConfig();
+  },
+};
 
-module.exports = MillasApp;
+module.exports = Millas;

package/src/container/MillasConfig.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const AppInitializer = require("./AppInitializer");
+
+/**
+ * MillasConfig
+ *
+ * A pure config collector — no side effects, no HTTP, no booting.
+ * Every method returns `this` for chaining.
+ * The chain ends with .create() which seals the config into a MillasInstance.
+ *
+ * ── Usage (bootstrap/app.js) ─────────────────────────────────────────────────
+ *
+ *   const { Millas } = require('millas');
+ *
+ *   module.exports = Millas.config()
+ *     .providers([AppServiceProvider])
+ *     .routes(Route => {
+ *       require('../routes/web')(Route);
+ *       require('../routes/api')(Route);
+ *     })
+ *     .withAdmin()
+ *     .create();
+ */
+class MillasConfig {
+    constructor() {
+        this._config = {
+            // Service providers
+            providers: [],
+
+            // Route registration callback: (Route) => void
+            routes: null,
+
+            // Named middleware aliases: [{ alias, handler }]
+            middleware: [],
+
+            // Core service toggles
+            database: true,
+            cache: true,
+            storage: true,
+            mail: true,
+            queue: true,
+            events: true,
+            logging: true,
+
+            // Admin panel — null means disabled, {} or options object means enabled
+            admin: null,
+
+            // Raw adapter-level middleware (e.g. helmet, compression)
+            adapterMiddleware: [],
+
+            // Lifecycle callbacks
+            onStart: null,
+            onShutdown: null,
+        };
+    }
+
+    // ── Chainable config methods ───────────────────────────────────────────────
+
+    /**
+     * Register application service providers.
+     *
+     *   .providers([AppServiceProvider, PaymentServiceProvider])
+     */
+    providers(list = []) {
+        this._config.providers.push(...list);
+        return this;
+    }
+
+    /**
+     * Register application routes.
+     *
+     *   .routes(Route => {
+     *     require('../routes/web')(Route);
+     *     require('../routes/api')(Route);
+     *   })
+     */
+    routes(callback) {
+        this._config.routes = callback;
+        return this;
+    }
+
+    /**
+     * Register a named middleware alias.
+     *
+     *   .middleware('verified', EmailVerifiedMiddleware)
+     */
+    middleware(alias, handler) {
+        this._config.middleware.push({alias, handler});
+        return this;
+    }
+
+    /**
+     * Enable the admin panel.
+     *
+     *   .withAdmin()
+     *   .withAdmin({ prefix: '/cms', title: 'My CMS' })
+     */
+    withAdmin(options = {}) {
+        this._config.admin = options;
+        return this;
+    }
+
+    /**
+     * Disable individual core services.
+     *
+     *   .disable('mail', 'queue')
+     */
+    disable(...services) {
+        for (const svc of services) {
+            if (svc in this._config) this._config[svc] = false;
+        }
+        return this;
+    }
+
+    /**
+     * Apply raw adapter-level middleware (e.g. helmet, compression).
+     * These are applied before any Millas routes.
+     *
+     *   .use(helmet())
+     *   .use(compression())
+     */
+    use(...fns) {
+        this._config.adapterMiddleware.push(...fns);
+        return this;
+    }
+
+    /**
+     * Called once the server is listening.
+     *
+     *   .onStart((port, host) => console.log(`up on ${host}:${port}`))
+     */
+    onStart(fn) {
+        this._config.onStart = fn;
+        return this;
+    }
+
+    /**
+     * Called before graceful shutdown.
+     *
+     *   .onShutdown(async () => db.close())
+     */
+    onShutdown(fn) {
+        this._config.onShutdown = fn;
+        return this;
+    }
+
+    // ── Terminal method ────────────────────────────────────────────────────────
+
+    /**
+     *
+     *
+     *   module.exports = Millas.config()
+     *     .providers([AppServiceProvider])
+     *     .routes(...)
+     *     .create();
+     */
+    async create() {
+        return (new AppInitializer(Object.freeze({...this._config}))).boot();
+    }
+}
+
+module.exports = MillasConfig;