millas 0.1.0

package/src/providers/CacheStorageServiceProvider.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const Cache           = require('../cache/Cache');
+const Storage         = require('../storage/Storage');
+
+/**
+ * CacheServiceProvider
+ *
+ * Configures the Cache facade with config/cache.js settings.
+ */
+class CacheServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Cache', Cache);
+  }
+
+  async boot() {
+    let cacheConfig;
+    try {
+      cacheConfig = require(process.cwd() + '/config/cache');
+    } catch {
+      cacheConfig = {
+        default: process.env.CACHE_DRIVER || 'memory',
+        prefix:  process.env.CACHE_PREFIX  || '',
+        drivers: {
+          memory: {},
+          file:   { path: 'storage/cache' },
+          null:   {},
+        },
+      };
+    }
+    Cache.configure(cacheConfig);
+  }
+}
+
+/**
+ * StorageServiceProvider
+ *
+ * Configures the Storage facade with config/storage.js settings.
+ */
+class StorageServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Storage', Storage);
+  }
+
+  async boot() {
+    let storageConfig;
+    try {
+      storageConfig = require(process.cwd() + '/config/storage');
+    } catch {
+      storageConfig = {
+        default: process.env.STORAGE_DRIVER || 'local',
+        disks: {
+          local: {
+            driver:  'local',
+            root:    'storage/uploads',
+            baseUrl: '/storage',
+          },
+          public: {
+            driver:  'local',
+            root:    'public/storage',
+            baseUrl: '/storage',
+          },
+        },
+      };
+    }
+    Storage.configure(storageConfig);
+  }
+}
+
+module.exports = { CacheServiceProvider, StorageServiceProvider };

package/src/providers/DatabaseServiceProvider.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const DatabaseManager = require('../orm/drivers/DatabaseManager');
+const SchemaBuilder   = require('../orm/migration/SchemaBuilder');
+
+/**
+ * DatabaseServiceProvider
+ *
+ * Configures the DatabaseManager with the app's database config
+ * and registers DB-related bindings into the container.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([DatabaseServiceProvider, AppServiceProvider])
+ */
+class DatabaseServiceProvider extends ServiceProvider {
+  register(container) {
+    // Make DatabaseManager available as a singleton in the container
+    container.instance('db',              DatabaseManager);
+    container.instance('DatabaseManager', DatabaseManager);
+  }
+
+  async boot(container) {
+    // Load the database config
+    let dbConfig;
+    try {
+      dbConfig = require(process.cwd() + '/config/database');
+    } catch {
+      // Fallback for tests / programmatic use
+      dbConfig = {
+        default: 'sqlite',
+        connections: {
+          sqlite: { driver: 'sqlite', database: ':memory:' },
+        },
+      };
+    }
+
+    DatabaseManager.configure(dbConfig);
+
+    // Register SchemaBuilder against the default connection
+    container.instance('schema', new SchemaBuilder(DatabaseManager.connection()));
+  }
+}
+
+module.exports = DatabaseServiceProvider;

package/src/providers/EventServiceProvider.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const EventEmitter    = require('../events/EventEmitter');
+const { emit }        = require('../events/EventEmitter');
+
+/**
+ * EventServiceProvider
+ *
+ * Registers the EventEmitter singleton in the container
+ * and connects it to the Queue for async listeners.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([..., EventServiceProvider, AppServiceProvider])
+ *
+ * Register event → listener mappings in AppServiceProvider.boot():
+ *   EventEmitter.listen(UserRegistered, [SendWelcomeEmail, NotifyAdmin]);
+ */
+class EventServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('EventEmitter', EventEmitter);
+    container.instance('emit',         emit);
+  }
+
+  async boot(container) {
+    // Connect queue to emitter for async listener support
+    if (container.has('Queue')) {
+      const Queue = container.make('Queue');
+      EventEmitter.setQueue(Queue);
+    }
+  }
+}
+
+module.exports = EventServiceProvider;

package/src/providers/MailServiceProvider.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const Mail            = require('../mail/Mail');
+const MailMessage     = require('../mail/MailMessage');
+
+/**
+ * MailServiceProvider
+ *
+ * Configures the Mail facade with config/mail.js settings.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([
+ *     DatabaseServiceProvider,
+ *     AuthServiceProvider,
+ *     MailServiceProvider,
+ *     AppServiceProvider,
+ *   ])
+ */
+class MailServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Mail',        Mail);
+    container.instance('MailMessage', MailMessage);
+  }
+
+  async boot(container) {
+    let mailConfig;
+    try {
+      mailConfig = require(process.cwd() + '/config/mail');
+    } catch {
+      mailConfig = {
+        default:  process.env.MAIL_DRIVER || 'log',
+        from:     { address: 'noreply@millas.dev', name: 'Millas' },
+        drivers:  {
+          log:  {},
+          smtp: {
+            host:       process.env.MAIL_HOST     || 'localhost',
+            port:       Number(process.env.MAIL_PORT) || 587,
+            username:   process.env.MAIL_USERNAME  || '',
+            password:   process.env.MAIL_PASSWORD  || '',
+            encryption: 'tls',
+          },
+        },
+      };
+    }
+
+    Mail.configure(mailConfig);
+  }
+}
+
+module.exports = MailServiceProvider;

package/src/providers/ProviderRegistry.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * ProviderRegistry
+ *
+ * Manages the lifecycle of all service providers:
+ *
+ *   1. Load — require() each provider file
+ *   2. Register — call provider.register(container) on all providers
+ *   3. Boot — call provider.boot(container, app) on all providers
+ *
+ * This two-phase approach (register then boot) ensures every binding
+ * exists before any provider tries to resolve another.
+ *
+ * Usage (in bootstrap/app.js):
+ *
+ *   const registry = new ProviderRegistry(container, app);
+ *   registry.add(AppServiceProvider);
+ *   registry.add('./providers/DatabaseServiceProvider');
+ *   await registry.boot();
+ */
+class ProviderRegistry {
+  constructor(container, expressApp) {
+    this._container = container;
+    this._app       = expressApp;
+    this._providers = [];
+  }
+
+  /**
+   * Add a provider class or path to the registry.
+   * @param {Function|string} provider — class or file path
+   */
+  add(provider) {
+    let Cls = provider;
+
+    if (typeof provider === 'string') {
+      Cls = require(provider);
+      // Support ES module default export
+      if (Cls.default) Cls = Cls.default;
+    }
+
+    this._providers.push(new Cls());
+    return this;
+  }
+
+  /**
+   * Add multiple providers at once.
+   * @param {Array} providers
+   */
+  addMany(providers = []) {
+    for (const p of providers) this.add(p);
+    return this;
+  }
+
+  /**
+   * Run the full register → boot lifecycle.
+   */
+  async boot() {
+    // Phase 1: register all bindings
+    for (const provider of this._providers) {
+      if (typeof provider.register === 'function') {
+        provider.register(this._container);
+      }
+    }
+
+    // Phase 2: boot all providers (async-safe)
+    for (const provider of this._providers) {
+      if (typeof provider.boot === 'function') {
+        await provider.boot(this._container, this._app);
+      }
+    }
+  }
+
+  /**
+   * Return a list of provider class names (for debugging).
+   */
+  list() {
+    return this._providers.map(p => p.constructor.name);
+  }
+}
+
+module.exports = ProviderRegistry;

package/src/providers/QueueServiceProvider.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const Queue           = require('../queue/Queue');
+const { dispatch }    = require('../queue/Queue');
+
+/**
+ * QueueServiceProvider
+ *
+ * Configures the Queue facade and registers it in the container.
+ * Also connects the Mail facade to the queue for async sending.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([
+ *     DatabaseServiceProvider,
+ *     AuthServiceProvider,
+ *     MailServiceProvider,
+ *     QueueServiceProvider,
+ *     AppServiceProvider,
+ *   ])
+ */
+class QueueServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Queue',    Queue);
+    container.instance('dispatch', dispatch);
+  }
+
+  async boot(container) {
+    let queueConfig;
+    try {
+      queueConfig = require(process.cwd() + '/config/queue');
+    } catch {
+      queueConfig = {
+        default: process.env.QUEUE_DRIVER || 'sync',
+        drivers: {
+          sync:     {},
+          database: { connection: null, table: 'millas_jobs' },
+        },
+      };
+    }
+
+    Queue.configure(queueConfig);
+
+    // Connect Mail to Queue so Mail.queue() works
+    if (container.has('Mail')) {
+      const Mail = container.make('Mail');
+      Mail.setQueue(Queue);
+    }
+  }
+}
+
+module.exports = QueueServiceProvider;

package/src/providers/ServiceProvider.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * ServiceProvider
+ *
+ * Base class for all Millas service providers.
+ *
+ * Providers have two lifecycle hooks:
+ *
+ *   register(container)
+ *     Called first. Bind things into the container.
+ *     Do NOT use other bindings here — they may not exist yet.
+ *
+ *   boot(container, app)
+ *     Called after ALL providers have registered.
+ *     Safe to resolve other bindings and set up routes,
+ *     event listeners, middleware, etc.
+ *
+ * Usage:
+ *   class AppServiceProvider extends ServiceProvider {
+ *     register(container) {
+ *       container.singleton('UserService', UserService);
+ *     }
+ *     async boot(container, app) {
+ *       const logger = container.make('Logger');
+ *       logger.info('AppServiceProvider booted');
+ *     }
+ *   }
+ */
+class ServiceProvider {
+  /**
+   * Register bindings into the container.
+   * @param {import('./Container')} container
+   */
+  register(container) {}
+
+  /**
+   * Bootstrap services after all providers have registered.
+   * @param {import('./Container')} container
+   * @param {import('express').Application} app
+   */
+  async boot(container, app) {}
+}
+
+module.exports = ServiceProvider;

package/src/queue/Job.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * Job
+ *
+ * Base class for all Millas background jobs.
+ *
+ * Usage:
+ *   class SendEmailJob extends Job {
+ *     static queue    = 'emails';   // which queue to push to
+ *     static tries    = 3;          // max attempts before failing
+ *     static delay    = 0;          // seconds before first attempt
+ *     static timeout  = 60;         // seconds before job times out
+ *     static backoff  = 'exponential'; // 'fixed' | 'exponential'
+ *
+ *     constructor(user, subject) {
+ *       super();
+ *       this.user    = user;
+ *       this.subject = subject;
+ *     }
+ *
+ *     async handle() {
+ *       await Mail.send({ to: this.user.email, subject: this.subject });
+ *     }
+ *
+ *     async failed(error) {
+ *       console.error('SendEmailJob failed:', error.message);
+ *     }
+ *   }
+ *
+ * Dispatch:
+ *   dispatch(new SendEmailJob(user, 'Welcome!'));
+ *   dispatch(new SendEmailJob(user)).delay(60);   // delay 60 seconds
+ *   dispatch(new SendEmailJob(user)).onQueue('priority');
+ */
+class Job {
+  // ─── Static config (override per job class) ───────────────────────────────
+
+  /** Queue name this job belongs to */
+  static queue   = 'default';
+
+  /** Max attempts before marking as failed */
+  static tries   = 3;
+
+  /** Seconds to wait before first execution */
+  static delay   = 0;
+
+  /** Seconds before the job is considered timed out */
+  static timeout = 60;
+
+  /** Backoff strategy: 'fixed' | 'exponential' */
+  static backoff = 'exponential';
+
+  // ─── Instance ─────────────────────────────────────────────────────────────
+
+  constructor() {
+    this._queue    = null;   // runtime override
+    this._delay    = null;   // runtime override
+    this._attempts = 0;
+  }
+
+  /**
+   * Execute the job. Must be implemented by subclasses.
+   */
+  async handle() {
+    throw new Error(`${this.constructor.name} must implement handle()`);
+  }
+
+  /**
+   * Called when the job fails after all retries.
+   * Override to notify, log, or clean up.
+   */
+  async failed(error) {}
+
+  // ─── Fluent dispatch modifiers ────────────────────────────────────────────
+
+  /**
+   * Override the queue name at dispatch time.
+   */
+  onQueue(name) {
+    this._queue = name;
+    return this;
+  }
+
+  /**
+   * Delay execution by N seconds.
+   */
+  delay(seconds) {
+    this._delay = seconds;
+    return this;
+  }
+
+  // ─── Serialisation ────────────────────────────────────────────────────────
+
+  /**
+   * Serialize this job for storage in the queue driver.
+   */
+  serialize() {
+    return {
+      class:     this.constructor.name,
+      queue:     this._queue     || this.constructor.queue  || 'default',
+      tries:     this.constructor.tries   || 3,
+      timeout:   this.constructor.timeout || 60,
+      backoff:   this.constructor.backoff || 'exponential',
+      delay:     this._delay !== null
+                   ? this._delay
+                   : (this.constructor.delay || 0),
+      payload:   this._getPayload(),
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Get the serializable payload (all own non-private properties).
+   */
+  _getPayload() {
+    const payload = {};
+    for (const key of Object.keys(this)) {
+      if (!key.startsWith('_')) payload[key] = this[key];
+    }
+    return payload;
+  }
+
+  /**
+   * Restore a job instance from a serialized record.
+   */
+  static deserialize(record, JobClass) {
+    const instance = new JobClass();
+    Object.assign(instance, record.payload || {});
+    instance._attempts = record.attempts || 0;
+    return instance;
+  }
+}
+
+module.exports = Job;

package/src/queue/Queue.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const SyncDriver = require('./drivers/SyncDriver');
+
+/**
+ * Queue
+ *
+ * The primary queue facade.
+ *
+ * Usage:
+ *   const { Queue, dispatch } = require('millas/src');
+ *
+ *   // Dispatch a job
+ *   await dispatch(new SendEmailJob(user));
+ *
+ *   // Dispatch with options
+ *   await dispatch(new SendEmailJob(user).delay(60).onQueue('emails'));
+ *
+ *   // Direct facade methods
+ *   await Queue.push(new SendEmailJob(user));
+ *   await Queue.size('default');
+ *   await Queue.clear('default');
+ */
+class Queue {
+  constructor() {
+    this._driver   = null;
+    this._config   = null;
+    this._registry = new Map();  // className → JobClass
+  }
+
+  // ─── Configuration ─────────────────────────────────────────────────────────
+
+  configure(config) {
+    this._config = config;
+    this._driver = null;  // reset so driver is rebuilt with new config
+  }
+
+  /**
+   * Register a Job class so the worker can deserialize it.
+   */
+  register(JobClass) {
+    this._registry.set(JobClass.name, JobClass);
+    return this;
+  }
+
+  registerMany(classes = []) {
+    classes.forEach(c => this.register(c));
+    return this;
+  }
+
+  // ─── Core API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Push a job onto the queue.
+   * Returns { id, status, queue }
+   */
+  async push(job) {
+    return this._getDriver().push(job);
+  }
+
+  /**
+   * Get the number of pending jobs on a queue.
+   */
+  async size(queue = 'default') {
+    return this._getDriver().size(queue);
+  }
+
+  /**
+   * Clear all pending jobs from a queue.
+   */
+  async clear(queue = 'default') {
+    return this._getDriver().clear(queue);
+  }
+
+  /**
+   * Get queue statistics (DatabaseDriver only).
+   */
+  async stats() {
+    const driver = this._getDriver();
+    if (typeof driver.stats === 'function') return driver.stats();
+    return {};
+  }
+
+  /**
+   * Get processed jobs (SyncDriver only — for testing).
+   */
+  processed() {
+    const driver = this._getDriver();
+    if (typeof driver.processed === 'function') return driver.processed();
+    return [];
+  }
+
+  /**
+   * Get the job registry Map (used by QueueWorker).
+   */
+  getRegistry() {
+    return this._registry;
+  }
+
+  getDriver() {
+    return this._getDriver();
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────────
+
+  _getDriver() {
+    if (this._driver) return this._driver;
+
+    const driverName = this._config?.default
+      || process.env.QUEUE_DRIVER
+      || 'sync';
+
+    const driverConf = this._config?.drivers?.[driverName] || {};
+
+    switch (driverName) {
+      case 'database': {
+        const DatabaseDriver = require('./drivers/DatabaseDriver');
+        this._driver = new DatabaseDriver(driverConf);
+        break;
+      }
+      case 'sync':
+      default: {
+        this._driver = new SyncDriver();
+        break;
+      }
+    }
+
+    return this._driver;
+  }
+}
+
+// Singleton
+const queue = new Queue();
+module.exports = queue;
+module.exports.Queue = Queue;
+
+/**
+ * dispatch()
+ *
+ * Global helper — push a job onto the queue.
+ *
+ *   const { dispatch } = require('millas/src');
+ *   await dispatch(new SendEmailJob(user));
+ */
+module.exports.dispatch = async function dispatch(job) {
+  return queue.push(job);
+};