millas 0.1.0

package/src/index.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// ── HTTP Layer ────────────────────────────────────────────────────
+const Controller         = require('./controller/Controller');
+const Middleware         = require('./middleware/Middleware');
+const MiddlewarePipeline = require('./middleware/MiddlewarePipeline');
+const CorsMiddleware     = require('./middleware/CorsMiddleware');
+const ThrottleMiddleware = require('./middleware/ThrottleMiddleware');
+const LogMiddleware      = require('./middleware/LogMiddleware');
+const HttpError          = require('./errors/HttpError');
+
+// ── DI Container ─────────────────────────────────────────────────
+const Container          = require('./container/Container');
+const Application        = require('./container/Application');
+const ServiceProvider    = require('./providers/ServiceProvider');
+const ProviderRegistry   = require('./providers/ProviderRegistry');
+
+// ── ORM ───────────────────────────────────────────────────────────
+const { Model, fields, QueryBuilder, DatabaseManager,
+        SchemaBuilder, MigrationRunner, ModelInspector } = require('./orm');
+const DatabaseServiceProvider = require('./providers/DatabaseServiceProvider');
+
+// ── Auth ──────────────────────────────────────────────────────────
+const Auth                = require('./auth/Auth');
+const Hasher              = require('./auth/Hasher');
+const JwtDriver           = require('./auth/JwtDriver');
+const AuthMiddleware      = require('./auth/AuthMiddleware');
+const RoleMiddleware      = require('./auth/RoleMiddleware');
+const AuthController      = require('./auth/AuthController');
+const AuthServiceProvider = require('./providers/AuthServiceProvider');
+
+// ── Mail ──────────────────────────────────────────────────────────
+const { Mail, MailMessage, TemplateEngine,
+        SmtpDriver, SendGridDriver, MailgunDriver, LogDriver } = require('./mail');
+const MailServiceProvider = require('./providers/MailServiceProvider');
+
+// ── Queue ─────────────────────────────────────────────────────────
+const Queue              = require('./queue/Queue');
+const Job                = require('./queue/Job');
+const QueueWorker        = require('./queue/workers/QueueWorker');
+const { dispatch }       = require('./queue/Queue');
+const QueueServiceProvider = require('./providers/QueueServiceProvider');
+
+// ── Events ────────────────────────────────────────────────────────
+const EventEmitter         = require('./events/EventEmitter');
+const Event                = require('./events/Event');
+const Listener             = require('./events/Listener');
+const { emit }             = require('./events/EventEmitter');
+const EventServiceProvider = require('./providers/EventServiceProvider');
+
+// ── Cache ─────────────────────────────────────────────────────────
+const Cache        = require('./cache/Cache');
+const MemoryDriver = require('./cache/drivers/MemoryDriver');
+const FileDriver   = require('./cache/drivers/FileDriver');
+const NullDriver   = require('./cache/drivers/NullDriver');
+const { CacheServiceProvider, StorageServiceProvider } = require('./providers/CacheStorageServiceProvider');
+
+// ── Storage ───────────────────────────────────────────────────────
+const Storage     = require('./storage/Storage');
+const LocalDriver = require('./storage/drivers/LocalDriver');
+
+module.exports = {
+  // HTTP
+  Controller, Middleware, MiddlewarePipeline,
+  CorsMiddleware, ThrottleMiddleware, LogMiddleware, HttpError,
+  // DI
+  Container, Application, ServiceProvider, ProviderRegistry,
+  // ORM
+  Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
+  MigrationRunner, ModelInspector, DatabaseServiceProvider,
+  // Auth
+  Auth, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware,
+  AuthController, AuthServiceProvider,
+  // Mail
+  Mail, MailMessage, TemplateEngine,
+  SmtpDriver, SendGridDriver, MailgunDriver, LogDriver, MailServiceProvider,
+  // Queue
+  Queue, Job, QueueWorker, dispatch, QueueServiceProvider,
+  // Events
+  EventEmitter, Event, Listener, emit, EventServiceProvider,
+  // Cache
+  Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
+  // Storage
+  Storage, LocalDriver, StorageServiceProvider,
+};
+
+// ── Admin ─────────────────────────────────────────────────────────
+const { Admin, AdminResource, AdminField, AdminFilter } = require('./admin');
+const AdminServiceProvider = require('./providers/AdminServiceProvider');
+
+Object.assign(module.exports, {
+  Admin, AdminResource, AdminField, AdminFilter, AdminServiceProvider,
+});

package/src/mail/Mail.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const MailMessage    = require('./MailMessage');
+const TemplateEngine = require('./TemplateEngine');
+
+/**
+ * Mail
+ *
+ * The primary mail facade.
+ *
+ * Usage:
+ *   const { Mail } = require('millas/src');
+ *
+ *   // Simple HTML
+ *   await Mail.send(
+ *     new MailMessage()
+ *       .to('alice@example.com', 'Alice')
+ *       .subject('Welcome!')
+ *       .html('<h1>Hello Alice!</h1>')
+ *   );
+ *
+ *   // Shorthand — object instead of MailMessage
+ *   await Mail.send({
+ *     to:       'alice@example.com',
+ *     subject:  'Welcome!',
+ *     template: 'welcome',
+ *     data:     { name: 'Alice' },
+ *   });
+ *
+ *   // Raw send with builder callback
+ *   await Mail.to('alice@example.com')
+ *             .subject('Hi!')
+ *             .html('<p>Hi!</p>')
+ *             .send();
+ */
+class Mail {
+  constructor() {
+    this._driver   = null;
+    this._config   = null;
+    this._engine   = null;
+    this._queue    = null;   // set by QueueServiceProvider in Phase 9
+  }
+
+  // ─── Configuration ─────────────────────────────────────────────────────────
+
+  /**
+   * Configure Mail. Called by MailServiceProvider.
+   */
+  configure(config) {
+    this._config = config;
+    this._engine = new TemplateEngine(config.templatesPath);
+  }
+
+  /**
+   * Set the queue instance for async mail (Phase 9).
+   */
+  setQueue(queue) {
+    this._queue = queue;
+  }
+
+  // ─── Primary API ───────────────────────────────────────────────────────────
+
+  /**
+   * Send an email immediately.
+   *
+   * @param {MailMessage|object} message
+   */
+  async send(message) {
+    const msg = await this._resolve(message);
+    const driver = this._getDriver();
+    return driver.send(msg);
+  }
+
+  /**
+   * Queue an email for background delivery (requires Phase 9).
+   * Falls back to immediate send if no queue configured.
+   *
+   * @param {MailMessage|object} message
+   */
+  async queue(message) {
+    if (!this._queue) {
+      // Graceful degradation — send immediately
+      return this.send(message);
+    }
+    const msg = await this._resolve(message);
+    return this._queue.push('mail', msg);
+  }
+
+  /**
+   * Send later (alias for queue).
+   */
+  async later(message) {
+    return this.queue(message);
+  }
+
+  /**
+   * Send to multiple recipients in a loop.
+   *
+   * await Mail.sendBulk([
+   *   { to: 'a@b.com', subject: 'Hi', template: 'welcome', data: { name: 'A' } },
+   *   { to: 'c@d.com', subject: 'Hi', template: 'welcome', data: { name: 'C' } },
+   * ]);
+   */
+  async sendBulk(messages) {
+    return Promise.all(messages.map(m => this.send(m)));
+  }
+
+  // ─── Fluent builder entry point ────────────────────────────────────────────
+
+  /**
+   * Start building a message fluently.
+   * Returns a MailMessage with a .send() shortcut bound to this Mail instance.
+   *
+   * await Mail.to('alice@test.com').subject('Hi').html('<p>Hi</p>').send();
+   */
+  to(address, name) {
+    const mail = this;
+    const msg  = new MailMessage().to(address, name);
+    // Attach a .send() shortcut
+    msg.send = () => mail.send(msg);
+    return msg;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve a MailMessage or plain object into a built message payload.
+   */
+  async _resolve(message) {
+    // Plain object shorthand
+    if (!(message instanceof MailMessage)) {
+      const msg = new MailMessage();
+      if (message.to)       msg.to(message.to, message.toName);
+      if (message.cc)       msg.cc(message.cc);
+      if (message.bcc)      msg.bcc(message.bcc);
+      if (message.from)     msg.from(message.from);
+      if (message.replyTo)  msg.replyTo(message.replyTo);
+      if (message.subject)  msg.subject(message.subject);
+      if (message.html)     msg.html(message.html);
+      if (message.text)     msg.text(message.text);
+      if (message.template) msg.template(message.template, message.data || {});
+      message = msg;
+    }
+
+    const defaults = {
+      from: this._config?.from
+        ? `${this._config.from.name || 'Millas'} <${this._config.from.address}>`
+        : 'noreply@millas.dev',
+    };
+
+    const built = message.build(defaults);
+
+    // Render template if specified
+    if (built._template && this._engine) {
+      const rendered = await this._engine.render(built._template, built._data || {});
+      built.html = built.html || rendered.html;
+      built.text = built.text || rendered.text;
+    }
+
+    // Clean up internal properties
+    delete built._template;
+    delete built._data;
+
+    return built;
+  }
+
+  _getDriver() {
+    if (this._driver) return this._driver;
+
+    if (!this._config) {
+      // No config — use LogDriver so mail never throws in tests/dev
+      const LogDriver = require('./drivers/LogDriver');
+      return new LogDriver();
+    }
+
+    const driverName = this._config.default || 'log';
+    const driverConf = this._config.drivers?.[driverName] || {};
+
+    switch (driverName) {
+      case 'smtp': {
+        const SmtpDriver = require('./drivers/SmtpDriver');
+        this._driver = new SmtpDriver(driverConf);
+        break;
+      }
+      case 'sendgrid': {
+        const SendGridDriver = require('./drivers/SendGridDriver');
+        this._driver = new SendGridDriver(driverConf);
+        break;
+      }
+      case 'mailgun': {
+        const MailgunDriver = require('./drivers/MailgunDriver');
+        this._driver = new MailgunDriver(driverConf);
+        break;
+      }
+      case 'log':
+      default: {
+        const LogDriver = require('./drivers/LogDriver');
+        this._driver = new LogDriver(driverConf);
+        break;
+      }
+    }
+
+    return this._driver;
+  }
+}
+
+// Singleton
+module.exports = new Mail();
+module.exports.Mail        = Mail;
+module.exports.MailMessage = MailMessage;

package/src/mail/MailMessage.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * MailMessage
+ *
+ * Fluent builder for composing email messages.
+ *
+ * Usage:
+ *   const msg = new MailMessage()
+ *     .to('alice@example.com', 'Alice')
+ *     .subject('Welcome!')
+ *     .html('<h1>Hello Alice</h1>')
+ *     .text('Hello Alice');
+ *
+ * Or with a template:
+ *   const msg = new MailMessage()
+ *     .to('alice@example.com')
+ *     .subject('Welcome!')
+ *     .template('welcome', { name: 'Alice' });
+ */
+class MailMessage {
+  constructor() {
+    this._to          = [];
+    this._cc          = [];
+    this._bcc         = [];
+    this._from        = null;
+    this._replyTo     = null;
+    this._subject     = '';
+    this._html        = null;
+    this._text        = null;
+    this._template    = null;
+    this._data        = {};
+    this._attachments = [];
+    this._headers     = {};
+    this._priority    = 'normal';
+  }
+
+  // ─── Recipients ────────────────────────────────────────────────────────────
+
+  /**
+   * Set the To recipient(s).
+   * @param {string|Array} address
+   * @param {string} name
+   */
+  to(address, name) {
+    this._to = this._normalise(address, name);
+    return this;
+  }
+
+  /**
+   * Add CC recipient(s).
+   */
+  cc(address, name) {
+    this._cc = [...this._cc, ...this._normalise(address, name)];
+    return this;
+  }
+
+  /**
+   * Add BCC recipient(s).
+   */
+  bcc(address, name) {
+    this._bcc = [...this._bcc, ...this._normalise(address, name)];
+    return this;
+  }
+
+  /**
+   * Override the From address for this message.
+   */
+  from(address, name) {
+    this._from = name ? `${name} <${address}>` : address;
+    return this;
+  }
+
+  /**
+   * Set the Reply-To address.
+   */
+  replyTo(address, name) {
+    this._replyTo = name ? `${name} <${address}>` : address;
+    return this;
+  }
+
+  // ─── Content ───────────────────────────────────────────────────────────────
+
+  /**
+   * Set the email subject line.
+   */
+  subject(subject) {
+    this._subject = subject;
+    return this;
+  }
+
+  /**
+   * Set HTML body.
+   */
+  html(content) {
+    this._html = content;
+    return this;
+  }
+
+  /**
+   * Set plain-text body.
+   */
+  text(content) {
+    this._text = content;
+    return this;
+  }
+
+  /**
+   * Use a named template with data.
+   * Template is resolved by the TemplateEngine.
+   *
+   * .template('welcome', { name: 'Alice', verifyUrl: '...' })
+   */
+  template(name, data = {}) {
+    this._template = name;
+    this._data     = data;
+    return this;
+  }
+
+  // ─── Attachments ───────────────────────────────────────────────────────────
+
+  /**
+   * Attach a file.
+   * @param {string} filePath   — absolute path or Buffer
+   * @param {string} filename   — name shown in email
+   * @param {string} contentType
+   */
+  attach(filePath, filename, contentType) {
+    this._attachments.push({ path: filePath, filename, contentType });
+    return this;
+  }
+
+  /**
+   * Attach raw content (string or Buffer).
+   */
+  attachRaw(content, filename, contentType = 'text/plain') {
+    this._attachments.push({ content, filename, contentType });
+    return this;
+  }
+
+  // ─── Meta ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Set a custom header.
+   */
+  header(key, value) {
+    this._headers[key] = value;
+    return this;
+  }
+
+  /**
+   * Set message priority: 'high' | 'normal' | 'low'
+   */
+  priority(level) {
+    this._priority = level;
+    return this;
+  }
+
+  // ─── Build ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Build the final message object for the transport driver.
+   * Applies defaults from a config object.
+   */
+  build(defaults = {}) {
+    return {
+      from:        this._from || defaults.from || 'noreply@millas.dev',
+      to:          this._to,
+      cc:          this._cc.length     ? this._cc  : undefined,
+      bcc:         this._bcc.length    ? this._bcc : undefined,
+      replyTo:     this._replyTo       || undefined,
+      subject:     this._subject,
+      html:        this._html          || undefined,
+      text:        this._text          || undefined,
+      attachments: this._attachments.length ? this._attachments : undefined,
+      headers:     Object.keys(this._headers).length ? this._headers : undefined,
+      priority:    this._priority !== 'normal' ? this._priority : undefined,
+      // Internal use
+      _template:   this._template,
+      _data:       this._data,
+    };
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  _normalise(address, name) {
+    if (Array.isArray(address)) {
+      return address.map(a =>
+        typeof a === 'string' ? a : (a.name ? `${a.name} <${a.address}>` : a.address)
+      );
+    }
+    return [name ? `${name} <${address}>` : address];
+  }
+}
+
+module.exports = MailMessage;

package/src/mail/TemplateEngine.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const fs   = require('fs-extra');
+const path = require('path');
+
+/**
+ * TemplateEngine
+ *
+ * Renders email templates from the resources/mail/ directory.
+ *
+ * Supports:
+ *   - Plain HTML files  (.html)
+ *   - Simple template syntax: {{ variable }}, {{ if condition }}, {{ each items }}
+ *
+ * Usage:
+ *   const engine = new TemplateEngine('./resources/mail');
+ *   const html   = await engine.render('welcome', { name: 'Alice' });
+ *
+ * Template file: resources/mail/welcome.html
+ *   <h1>Welcome, {{ name }}!</h1>
+ */
+class TemplateEngine {
+  constructor(templatesPath) {
+    this._path = templatesPath || path.join(process.cwd(), 'resources/mail');
+  }
+
+  /**
+   * Render a named template with data.
+   * @param {string} name — template name without extension
+   * @param {object} data — variables to interpolate
+   * @returns {Promise<{html: string, text: string}>}
+   */
+  async render(name, data = {}) {
+    const htmlPath = path.join(this._path, `${name}.html`);
+    const textPath = path.join(this._path, `${name}.txt`);
+
+    let html = null;
+    let text = null;
+
+    if (await fs.pathExists(htmlPath)) {
+      const raw = await fs.readFile(htmlPath, 'utf8');
+      html = this._interpolate(raw, data);
+    }
+
+    if (await fs.pathExists(textPath)) {
+      const raw = await fs.readFile(textPath, 'utf8');
+      text = this._interpolate(raw, data);
+    }
+
+    // Auto-generate plain text from HTML if no .txt file
+    if (html && !text) {
+      text = this._htmlToText(html);
+    }
+
+    if (!html && !text) {
+      throw new Error(
+        `Mail template "${name}" not found in ${this._path}. ` +
+        `Create ${name}.html or ${name}.txt.`
+      );
+    }
+
+    return { html, text };
+  }
+
+  /**
+   * Render an inline HTML string with data.
+   */
+  renderInline(htmlString, data = {}) {
+    return {
+      html: this._interpolate(htmlString, data),
+      text: this._htmlToText(this._interpolate(htmlString, data)),
+    };
+  }
+
+  // ─── Template syntax ───────────────────────────────────────────────────────
+
+  /**
+   * Simple template interpolation.
+   *
+   * Supports:
+   *   {{ name }}                — variable substitution
+   *   {{ user.email }}          — dot notation
+   *   {{# if condition }}...{{/ if }}  — conditionals
+   *   {{# each items }}...{{/ each }}  — loops (item available as {{ this }})
+   */
+  _interpolate(template, data) {
+    let result = template;
+
+    // {{# each array }}...{{/ each }}
+    result = result.replace(
+      /\{\{#\s*each\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/\s*each\s*\}\}/g,
+      (_, key, body) => {
+        const list = this._resolve(key, data);
+        if (!Array.isArray(list)) return '';
+        return list.map(item => {
+          return body
+            .replace(/\{\{\s*this\s*\}\}/g, String(item))
+            .replace(/\{\{\s*this\.([\w.]+)\s*\}\}/g, (__, prop) =>
+              String(this._resolve(prop, item) ?? '')
+            );
+        }).join('');
+      }
+    );
+
+    // {{# if condition }}...{{/ if }}
+    result = result.replace(
+      /\{\{#\s*if\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/\s*if\s*\}\}/g,
+      (_, key, body) => this._resolve(key, data) ? body : ''
+    );
+
+    // {{ variable }} and {{ dot.notation }}
+    result = result.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => {
+      const val = this._resolve(key, data);
+      return val !== undefined && val !== null ? String(val) : '';
+    });
+
+    return result;
+  }
+
+  _resolve(key, data) {
+    return key.split('.').reduce((obj, k) =>
+      obj && typeof obj === 'object' ? obj[k] : undefined, data
+    );
+  }
+
+  /**
+   * Strip HTML tags to produce a basic plain-text version.
+   */
+  _htmlToText(html) {
+    return html
+      .replace(/<style[\s\S]*?<\/style>/gi, '')
+      .replace(/<script[\s\S]*?<\/script>/gi, '')
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/<\/p>/gi, '\n\n')
+      .replace(/<\/h[1-6]>/gi, '\n\n')
+      .replace(/<\/li>/gi, '\n')
+      .replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, '$2 ($1)')
+      .replace(/<[^>]+>/g, '')
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#039;/g, "'")
+      .replace(/&nbsp;/g, ' ')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+  }
+}
+
+module.exports = TemplateEngine;

package/src/mail/drivers/LogDriver.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * LogDriver
+ *
+ * Development mail driver — logs messages to the console
+ * instead of actually sending them.
+ *
+ * Set MAIL_DRIVER=log in .env to activate.
+ * Also used as a fallback when no driver is configured.
+ */
+class LogDriver {
+  constructor(config = {}) {
+    this._silent = config.silent || false;
+  }
+
+  async send(message) {
+    if (this._silent) return { logged: true, message };
+
+    const sep = '─'.repeat(60);
+    console.log(`\n  📧 Mail (LogDriver)\n  ${sep}`);
+    console.log(`  From:    ${message.from}`);
+    console.log(`  To:      ${[].concat(message.to).join(', ')}`);
+    if (message.cc)  console.log(`  CC:      ${[].concat(message.cc).join(', ')}`);
+    if (message.bcc) console.log(`  BCC:     ${[].concat(message.bcc).join(', ')}`);
+    console.log(`  Subject: ${message.subject}`);
+    if (message.text) {
+      console.log(`  \n  ${message.text.slice(0, 200)}${message.text.length > 200 ? '...' : ''}`);
+    }
+    console.log(`  ${sep}\n`);
+
+    return { logged: true, message };
+  }
+}
+
+module.exports = LogDriver;