millas 0.2.9 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "A modern batteries-included backend framework for Node.js — built on Express, inspired by Laravel, Django, and FastAPI",
   "main": "src/index.js",
   "exports": {

package/src/container/MillasApp.js

@@ -0,0 +1,307 @@
+'use strict';
+
+const express  = require('express');
+const Application = require('./Application');
+
+/**
+ * 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 ───────────────────────────────────────────────────────────────────
+ *
+ *   require('dotenv').config();
+ *   const { MillasApp } = require('millas');
+ *   const AppServiceProvider = require('../providers/AppServiceProvider');
+ *
+ *   const app = MillasApp.create()
+ *     .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
+ *
+ * ── Advanced ────────────────────────────────────────────────────────────────
+ *
+ *   MillasApp.create({
+ *     // Disable a core provider
+ *     mail:    false,
+ *     queue:   false,
+ *
+ *     // 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}`),
+ *   })
+ */
+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 ───────────────────────────────────────────────────────────
+
+  /**
+   * Register application service providers.
+   *
+   *   .providers([AppServiceProvider, PaymentServiceProvider])
+   */
+  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. */
+  get kernel()     { return this._kernel; }
+
+  /** The DI container. */
+  get container()  { return this._kernel?._container; }
+
+  /** The Route instance (for programmatic route registration). */
+  get route()      { return this._kernel?._route; }
+
+  // ─── module.exports helper ────────────────────────────────────────────────
+
+  /**
+   * Returns a plain object suitable for module.exports.
+   * Matches the shape existing code expects.
+   */
+  toModule() {
+    const self = this;
+    return {
+      app:        this._kernel,
+      expressApp: this._expressApp,
+      get route() { return self._kernel?._route; },
+    };
+  }
+
+  // ─── 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;
+  }
+}
+
+module.exports = MillasApp;

package/src/container/index.js

@@ -2,12 +2,14 @@
 
 const Container        = require('./Container');
 const Application      = require('./Application');
+const MillasApp        = require('./MillasApp');
 const ServiceProvider  = require('../providers/ServiceProvider');
 const ProviderRegistry = require('../providers/ProviderRegistry');
 
 module.exports = {
   Container,
   Application,
+  MillasApp,
   ServiceProvider,
   ProviderRegistry,
 };

package/src/index.js

@@ -1,21 +1,5 @@
 'use strict';
 
-// ── Logger ────────────────────────────────────────────────────────
-const {
-  Log,
-  Logger,
-  LEVELS,
-  LEVEL_NAMES,
-  PrettyFormatter,
-  JsonFormatter,
-  SimpleFormatter,
-  ConsoleChannel,
-  FileChannel,
-  NullChannel,
-  StackChannel,
-} = require('./logger/index');
-const LogServiceProvider = require('./providers/LogServiceProvider');
-
 // ── HTTP Layer ────────────────────────────────────────────────────
 const Controller         = require('./controller/Controller');
 const Middleware         = require('./middleware/Middleware');
@@ -28,6 +12,7 @@ const HttpError          = require('./errors/HttpError');
 // ── DI Container ─────────────────────────────────────────────────
 const Container          = require('./container/Container');
 const Application        = require('./container/Application');
+const MillasApp          = require('./container/MillasApp');
 const ServiceProvider    = require('./providers/ServiceProvider');
 const ProviderRegistry   = require('./providers/ProviderRegistry');
 
@@ -76,16 +61,11 @@ const Storage     = require('./storage/Storage');
 const LocalDriver = require('./storage/drivers/LocalDriver');
 
 module.exports = {
-  // Logger
-  Log, Logger, LEVELS, LEVEL_NAMES,
-  PrettyFormatter, JsonFormatter, SimpleFormatter,
-  ConsoleChannel, FileChannel, NullChannel, StackChannel,
-  LogServiceProvider,
   // HTTP
   Controller, Middleware, MiddlewarePipeline,
   CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
   // DI
-  Container, Application, ServiceProvider, ProviderRegistry,
+  Container, Application, MillasApp, ServiceProvider, ProviderRegistry,
   // ORM
   Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
   MigrationRunner, ModelInspector, DatabaseServiceProvider,

package/src/scaffold/templates.js

@@ -88,77 +88,18 @@ module.exports = {
 
 require('dotenv').config();
 
-const express = require('express');
-
-function resolveMillas() {
-  try { return require('millas/src'); } catch {}
-  try {
-    const path     = require('path');
-    const cliPath  = require.resolve('millas/bin/millas.js');
-    const millasSrc = path.join(path.dirname(cliPath), '..', 'src', 'index.js');
-    return require(millasSrc);
-  } catch {}
-  throw new Error('Cannot find millas. Run: npm install millas');
-}
-
-const {
-  Application,
-  Admin,
-  LogServiceProvider,
-  CacheServiceProvider,
-  StorageServiceProvider,
-  MailServiceProvider,
-  QueueServiceProvider,
-  EventServiceProvider,
-} = resolveMillas();
-
+const { MillasApp } = require('millas');
 const AppServiceProvider = require('../providers/AppServiceProvider');
 
-const expressApp = express();
-expressApp.use(express.json());
-expressApp.use(express.urlencoded({ extended: true }));
-
-// ── Build the Millas application kernel ─────────────────────────
-const app = new Application(expressApp);
-
-// ── Register service providers ──────────────────────────────────
-app.providers([
-  LogServiceProvider,       // first — so Log works in all other providers
-  CacheServiceProvider,
-  StorageServiceProvider,
-  MailServiceProvider,
-  QueueServiceProvider,
-  EventServiceProvider,
-  AppServiceProvider,
-]);
-
-// ── Define routes ────────────────────────────────────────────────
-app.routes(Route => {
-  require('../routes/web')(Route);
-  require('../routes/api')(Route);
-});
-
-// ── Boot + mount + listen ────────────────────────────────────────
-(async () => {
-  await app.boot();
-
-  if (!process.env.MILLAS_ROUTE_LIST) {
-    // Register app routes first (without 404 handler yet)
-    app.mountRoutes();
-
-    // Admin panel mounts here — before the 404 fallback
-    // To disable: comment out this line
-    // To change path: Admin.configure({ prefix: '/cms' });
-    Admin.mount(expressApp);
-
-    // Add 404 + error handlers LAST
-    app.mountFallbacks();
-
-    app.listen();
-  }
-})();
+const app = MillasApp.create()
+  .providers([AppServiceProvider])
+  .routes(Route => {
+    require('../routes/web')(Route);
+    require('../routes/api')(Route);
+  })
+  .withAdmin();
 
-module.exports = { app, expressApp, get route() { return app.route; } };
+module.exports = app.start();
 `,
 
     // ─── routes/web.js ────────────────────────────────────────────
@@ -198,38 +139,6 @@ module.exports = function (Route) {
 
   });
 };
-`,
-
-    // ─── config/logging.js ────────────────────────────────────────
-    'config/logging.js': `'use strict';
-
-/**
- * Logging Configuration
- *
- * Levels (lowest → highest): verbose | debug | info | warn | error | wtf
- * Channels: 'console' | 'file' | 'null'
- * Formats:  'pretty' (coloured) | 'simple' (plain text) | 'json' (structured)
- */
-module.exports = {
-  level: process.env.LOG_LEVEL || (process.env.NODE_ENV === 'production' ? 'info' : 'debug'),
-
-  defaultTag: process.env.APP_NAME || 'App',
-
-  channels: [
-    {
-      driver: 'console',
-      format: 'pretty',
-    },
-    {
-      driver:   'file',
-      format:   'simple',
-      path:     'storage/logs',
-      prefix:   '${projectName}',
-      level:    'warn',
-      maxFiles: 30,
-    },
-  ],
-};
 `,
 
     // ─── config/app.js ────────────────────────────────────────────
@@ -332,25 +241,15 @@ module.exports = {
     // ─── providers/AppServiceProvider.js ──────────────────────────
     'providers/AppServiceProvider.js': `'use strict';
 
-function resolveMillas() {
-  try { return require('millas/src'); } catch {}
-  try {
-    const path = require('path');
-    const cli  = require.resolve('millas/bin/millas.js');
-    return require(path.join(path.dirname(cli), '..', 'src', 'index.js'));
-  } catch {}
-  throw new Error('Cannot find millas. Run: npm install millas');
-}
-
-const { ServiceProvider } = resolveMillas();
+const { ServiceProvider } = require('millas');
 
 /**
  * AppServiceProvider
  *
  * Register and bootstrap your application services here.
  *
- * register()  — bind things into the container
- * boot()      — called after all providers have registered
+ * register()  — bind things into the container (synchronous)
+ * boot()      — called after all providers have registered (async OK)
  */
 class AppServiceProvider extends ServiceProvider {
   register(container) {
@@ -360,7 +259,13 @@ class AppServiceProvider extends ServiceProvider {
   }
 
   async boot(container, app) {
-    // const logger = container.make('Logger');
+    // const { Log } = require('millas');
+    // Log.tag('AppServiceProvider').i('Booted');
+
+    // Register resources in the Admin panel:
+    // const { Admin, AdminResource } = require('millas');
+    // const Post = require('../app/models/Post');
+    // Admin.register(Post);
   }
 }