millas 0.2.6 → 0.2.8

package/src/logger/channels/index.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * NullChannel
+ *
+ * Silently discards all log entries.
+ * Useful in tests where you want to suppress all output.
+ *
+ *   Log.configure({ channels: [new NullChannel()] });
+ */
+class NullChannel {
+  write() { /* intentionally empty */ }
+}
+
+/**
+ * StackChannel
+ *
+ * Fans a single log entry out to multiple channels simultaneously.
+ * This is the standard "stack" pattern — one channel for console,
+ * another for file, optionally one for an external service.
+ *
+ *   new StackChannel([
+ *     new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *     new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.INFO }),
+ *   ])
+ */
+class StackChannel {
+  /**
+   * @param {Array} channels — array of channel instances
+   */
+  constructor(channels = []) {
+    this._channels = channels;
+  }
+
+  /** Add a channel at runtime. */
+  add(channel) {
+    this._channels.push(channel);
+    return this;
+  }
+
+  write(entry) {
+    for (const ch of this._channels) {
+      try { ch.write(entry); } catch {}
+    }
+  }
+}
+
+module.exports = { NullChannel, StackChannel };

package/src/logger/formatters/JsonFormatter.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { LEVEL_NAMES } = require('../levels');
+
+/**
+ * JsonFormatter
+ *
+ * Emits one JSON object per log entry — ideal for production environments
+ * where logs are shipped to Datadog, Elasticsearch, CloudWatch, etc.
+ *
+ * Output (one line per entry):
+ *   {"ts":"2026-03-15T12:00:00.000Z","level":"INFO","tag":"Auth","msg":"Login","ctx":{...}}
+ */
+class JsonFormatter {
+  /**
+   * @param {object} options
+   * @param {boolean} [options.pretty=false]   — pretty-print JSON (for debugging)
+   * @param {object}  [options.extra]          — static fields merged into every entry (e.g. service name)
+   */
+  constructor(options = {}) {
+    this.pretty = options.pretty || false;
+    this.extra  = options.extra  || {};
+  }
+
+  format(entry) {
+    const { level, tag, message, context, error, timestamp } = entry;
+
+    const record = {
+      ts:    timestamp || new Date().toISOString(),
+      level: LEVEL_NAMES[level] || String(level),
+      ...this.extra,
+    };
+
+    if (tag)     record.tag = tag;
+    record.msg = message;
+    if (context !== undefined && context !== null) record.ctx = context;
+
+    if (error instanceof Error) {
+      record.error = {
+        message: error.message,
+        name:    error.name,
+        stack:   error.stack,
+      };
+    }
+
+    return this.pretty
+      ? JSON.stringify(record, null, 2)
+      : JSON.stringify(record);
+  }
+}
+
+module.exports = JsonFormatter;

package/src/logger/formatters/PrettyFormatter.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { LEVEL_NAMES, LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD, DIM } = require('../levels');
+
+/**
+ * PrettyFormatter
+ *
+ * Colourful, human-readable output. Designed for development.
+ * Inspired by Timber (Android) and Laravel's log formatting.
+ *
+ * Output:
+ *   [2026-03-15 12:00:00] I  UserController  User #5 logged in
+ *   [2026-03-15 12:00:01] E  Database        Connection refused  { host: 'localhost' }
+ *   [2026-03-15 12:00:02] W  Auth            Token expiring soon
+ *
+ * WTF level also prints the full stack trace.
+ */
+class PrettyFormatter {
+  /**
+   * @param {object} options
+   * @param {boolean} [options.timestamp=true]    — show timestamp
+   * @param {boolean} [options.tag=true]          — show tag/component name
+   * @param {boolean} [options.colour=true]       — ANSI colour (disable for pipes/files)
+   * @param {string}  [options.timestampFormat]   — 'iso' | 'short' (default: 'short')
+   */
+  constructor(options = {}) {
+    this.showTimestamp = options.timestamp !== false;
+    this.showTag       = options.tag       !== false;
+    this.colour        = options.colour    !== false;
+    this.tsFormat      = options.timestampFormat || 'short';
+  }
+
+  format(entry) {
+    const { level, tag, message, context, error } = entry;
+
+    const c    = this.colour ? LEVEL_COLOURS[level] : '';
+    const r    = this.colour ? RESET                : '';
+    const b    = this.colour ? BOLD                 : '';
+    const d    = this.colour ? '\x1b[2m'            : '';
+    const lvl  = LEVEL_TAGS[level] || '?';
+
+    const parts = [];
+
+    // Timestamp
+    if (this.showTimestamp) {
+      const ts = this._timestamp();
+      parts.push(`${d}[${ts}]${r}`);
+    }
+
+    // Level tag (single letter, coloured)
+    parts.push(`${c}${b}${lvl}${r}`);
+
+    // Component/tag
+    if (this.showTag && tag) {
+      const tagStr = tag.padEnd(18);
+      parts.push(`${b}${tagStr}${r}`);
+    }
+
+    // Message
+    parts.push(`${c}${message}${r}`);
+
+    // Context object
+    if (context !== undefined && context !== null) {
+      const ctx = typeof context === 'object'
+        ? JSON.stringify(context, null, 0)
+        : String(context);
+      parts.push(`${d}${ctx}${r}`);
+    }
+
+    let output = parts.join('  ');
+
+    // Error stack
+    if (error instanceof Error) {
+      output += `\n${d}${error.stack || error.message}${r}`;
+    }
+
+    // WTF: print big warning banner
+    if (level === 5) {
+      const banner = this.colour
+        ? `\x1b[35m\x1b[1m${'━'.repeat(60)}\x1b[0m`
+        : '━'.repeat(60);
+      output = `${banner}\n${output}\n${banner}`;
+    }
+
+    return output;
+  }
+
+  _timestamp() {
+    const now = new Date();
+    if (this.tsFormat === 'iso') return now.toISOString();
+    return now.toISOString().replace('T', ' ').slice(0, 19);
+  }
+}
+
+module.exports = PrettyFormatter;

package/src/logger/formatters/SimpleFormatter.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { LEVEL_NAMES } = require('../levels');
+
+/**
+ * SimpleFormatter
+ *
+ * Plain, no-colour text. Suitable for file output or any sink
+ * where ANSI codes would be noise.
+ *
+ * Output:
+ *   [2026-03-15 12:00:00] [INFO]  Auth: User logged in
+ *   [2026-03-15 12:00:01] [ERROR] DB: Query failed {"table":"users"}
+ */
+class SimpleFormatter {
+  format(entry) {
+    const { level, tag, message, context, error, timestamp } = entry;
+
+    const ts      = (timestamp || new Date().toISOString()).replace('T', ' ').slice(0, 23);
+    const lvlName = (LEVEL_NAMES[level] || String(level)).padEnd(7);
+    const tagPart = tag ? `${tag}: ` : '';
+
+    let line = `[${ts}] [${lvlName}] ${tagPart}${message}`;
+
+    if (context !== undefined && context !== null) {
+      line += ' ' + (typeof context === 'object' ? JSON.stringify(context) : String(context));
+    }
+
+    if (error instanceof Error) {
+      line += '\n  ' + (error.stack || error.message).replace(/\n/g, '\n  ');
+    }
+
+    return line;
+  }
+}
+
+module.exports = SimpleFormatter;

package/src/logger/index.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const Logger          = require('./Logger');
+const { LEVELS, LEVEL_NAMES } = require('./levels');
+const PrettyFormatter = require('./formatters/PrettyFormatter');
+const JsonFormatter   = require('./formatters/JsonFormatter');
+const SimpleFormatter = require('./formatters/SimpleFormatter');
+const ConsoleChannel  = require('./channels/ConsoleChannel');
+const FileChannel     = require('./channels/FileChannel');
+const { NullChannel, StackChannel } = require('./channels/index');
+
+/**
+ * Log
+ *
+ * The global logger singleton — the one you import everywhere.
+ *
+ *   const { Log } = require('millas');
+ *
+ *   Log.i('App booted');
+ *   Log.tag('UserService').d('Fetching user', { id: 5 });
+ *   Log.e('Payment', 'Stripe failed', error);
+ *   Log.wtf('Impossible state reached');
+ *
+ * Configured automatically by LogServiceProvider when you add it
+ * to your providers list. For manual setup:
+ *
+ *   Log.configure({
+ *     minLevel: LEVELS.INFO,
+ *     channel: new StackChannel([
+ *       new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *       new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.WARN }),
+ *     ]),
+ *   });
+ */
+const Log = new Logger();
+
+// Apply sensible defaults so Log works out-of-the-box before
+// LogServiceProvider runs (during framework boot, tests, etc.)
+Log.configure({
+  minLevel: process.env.NODE_ENV === 'production' ? LEVELS.INFO : LEVELS.DEBUG,
+  channel: new ConsoleChannel({
+    formatter: new PrettyFormatter({
+      colour: process.stdout.isTTY !== false,
+    }),
+  }),
+});
+
+module.exports = {
+  // The singleton you use everywhere
+  Log,
+
+  // The class (for constructing named loggers)
+  Logger,
+
+  // Level constants
+  LEVELS,
+  LEVEL_NAMES,
+
+  // Formatters
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+
+  // Channels
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+};

package/src/logger/levels.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Log levels — ordered by severity (lowest to highest).
+ *
+ * Inspired by Android's Timber / Log class:
+ *   VERBOSE  — extremely detailed; usually filtered out in production
+ *   DEBUG    — development diagnostics
+ *   INFO     — normal operational messages (default minimum in production)
+ *   WARN     — something unexpected but recoverable
+ *   ERROR    — something failed; needs attention
+ *   WTF      — "What a Terrible Failure" — should never happen; always logged
+ */
+const LEVELS = {
+  VERBOSE: 0,
+  DEBUG:   1,
+  INFO:    2,
+  WARN:    3,
+  ERROR:   4,
+  WTF:     5,
+};
+
+/** Reverse map: number → name */
+const LEVEL_NAMES = Object.fromEntries(
+  Object.entries(LEVELS).map(([k, v]) => [v, k])
+);
+
+/** Single-letter tags (like Android logcat) */
+const LEVEL_TAGS = {
+  0: 'V',
+  1: 'D',
+  2: 'I',
+  3: 'W',
+  4: 'E',
+  5: 'F', // Fatal / WTF
+};
+
+/** ANSI colour codes for each level */
+const LEVEL_COLOURS = {
+  0: '\x1b[90m',   // VERBOSE  — dark grey
+  1: '\x1b[36m',   // DEBUG    — cyan
+  2: '\x1b[32m',   // INFO     — green
+  3: '\x1b[33m',   // WARN     — yellow
+  4: '\x1b[31m',   // ERROR    — red
+  5: '\x1b[35m',   // WTF      — magenta
+};
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+
+module.exports = { LEVELS, LEVEL_NAMES, LEVEL_TAGS, LEVEL_COLOURS, RESET, BOLD, DIM };

package/src/middleware/LogMiddleware.js

@@ -5,53 +5,79 @@ const Middleware = require('./Middleware');
 /**
  * LogMiddleware
  *
- * Logs every incoming request and its response time.
+ * Django-style HTTP request logger.
+ * Uses the Millas Log singleton — output goes through your configured channels.
  *
- * Output format:
- *   [2026-03-14 12:00:00] GET /api/users 200 12ms
+ * Log levels per status:
+ *   2xx, 3xx  → INFO   (green)
+ *   4xx       → WARN   (yellow)
+ *   5xx       → ERROR  (red)
+ *   slow req  → WARN   (with slow=true in context)
  *
- * Register:
- *   middlewareRegistry.register('log', LogMiddleware);
+ * Output:
+ *   I  HTTP  GET /api/users 200 4ms
+ *   W  HTTP  POST /api/login 401 12ms
+ *   E  HTTP  GET /api/crash 500 3ms
+ *
+ * Usage (register as middleware):
+ *   app.use(new LogMiddleware().handle.bind(new LogMiddleware()));
+ *
+ * Or use Log.requestMiddleware() directly for more options.
  *
  * Options:
- *   silent  — suppress output (default: false)
- *   format  — 'dev' (coloured) | 'combined' (plain)
+ *   silent        — suppress all output (default: false)
+ *   includeQuery  — include query string in URL (default: false)
+ *   includeIp     — include client IP (default: true)
+ *   slowThreshold — warn if response > Nms (default: 1000)
+ *   skip          — function(req, res) => bool — skip matching routes
  */
 class LogMiddleware extends Middleware {
   constructor(options = {}) {
     super();
-    this.silent = options.silent || false;
-    this.format = options.format || 'dev';
+    this.silent        = options.silent        ?? false;
+    this.includeQuery  = options.includeQuery  ?? false;
+    this.includeIp     = options.includeIp     ?? true;
+    this.slowThreshold = options.slowThreshold ?? 1000;
+    this.skip          = options.skip          ?? null;
   }
 
   async handle(req, res, next) {
     if (this.silent) return next();
+    if (typeof this.skip === 'function' && this.skip(req, res)) return next();
+
+    // Lazy-require Log so this file loads even before LogServiceProvider runs
+    let Log;
+    try {
+      Log = require('../logger/index').Log;
+    } catch {
+      return next();
+    }
 
     const start = Date.now();
-    const { method, path: routePath, url } = req;
+    const { LEVELS } = require('../logger/levels');
 
     res.on('finish', () => {
       const ms     = Date.now() - start;
       const status = res.statusCode;
-      const ts     = new Date().toISOString().replace('T', ' ').slice(0, 19);
-
-      if (this.format === 'dev') {
-        const statusColor = status < 300 ? '\x1b[32m'
-          : status < 400 ? '\x1b[36m'
-          : status < 500 ? '\x1b[33m'
-          : '\x1b[31m';
-        const reset = '\x1b[0m';
-        const methodColor = '\x1b[1m';
-        console.log(
-          `  ${'\x1b[90m'}[${ts}]${reset} ` +
-          `${methodColor}${method.padEnd(7)}${reset} ` +
-          `${routePath || url} ` +
-          `${statusColor}${status}${reset} ` +
-          `${'\x1b[90m'}${ms}ms${reset}`
-        );
-      } else {
-        console.log(`[${ts}] ${method} ${routePath || url} ${status} ${ms}ms`);
+      const method = req.method;
+      let   url    = req.path || req.url || '/';
+
+      if (this.includeQuery && req.url && req.url.includes('?')) {
+        url = req.url;
       }
+
+      // Level based on status + response time
+      let level;
+      if      (status >= 500)          level = LEVELS.ERROR;
+      else if (status >= 400)          level = LEVELS.WARN;
+      else if (ms > this.slowThreshold) level = LEVELS.WARN;
+      else                             level = LEVELS.INFO;
+
+      const ctx = { status, ms };
+      if (this.includeIp) ctx.ip = req.ip || req.connection?.remoteAddress;
+      if (ms > this.slowThreshold) ctx.slow = true;
+
+      Log._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
     });
 
     next();

package/src/providers/LogServiceProvider.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const ServiceProvider = require('./ServiceProvider');
+const {
+  Log,
+  Logger,
+  LEVELS,
+  PrettyFormatter,
+  JsonFormatter,
+  SimpleFormatter,
+  ConsoleChannel,
+  FileChannel,
+  NullChannel,
+  StackChannel,
+} = require('../logger/index');
+
+/**
+ * LogServiceProvider
+ *
+ * Reads config/logging.js and configures the Log singleton.
+ * Also registers Log and Logger in the DI container.
+ *
+ * Add to bootstrap/app.js:
+ *   app.providers([LogServiceProvider, ...]);
+ *
+ * The provider is intentionally ordered first so every other provider
+ * can use Log during their boot() method.
+ *
+ * config/logging.js is optional — sensible defaults apply if absent.
+ */
+class LogServiceProvider extends ServiceProvider {
+  register(container) {
+    container.instance('Log',    Log);
+    container.instance('Logger', Logger);
+  }
+
+  async boot(container, app) {
+    let config = {};
+    try {
+      config = require(process.cwd() + '/config/logging');
+    } catch {
+      // No config — use defaults already set in logger/index.js
+      return;
+    }
+
+    const channels = this._buildChannels(config);
+
+    Log.configure({
+      minLevel:   this._resolveLevel(config.level ?? config.minLevel),
+      defaultTag: config.defaultTag || 'App',
+      channel:    channels.length === 1
+        ? channels[0]
+        : new StackChannel(channels),
+    });
+
+    Log.tag('Millas').i(`Logger configured — level: ${this._levelName(Log._minLevel)}, channels: ${channels.length}`);
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  _buildChannels(config) {
+    const channelDefs = config.channels || ['console'];
+    const built       = [];
+
+    for (const def of channelDefs) {
+      // String shorthand: 'console' | 'file' | 'null'
+      if (def === 'console' || def?.driver === 'console') {
+        built.push(this._buildConsole(def));
+      } else if (def === 'file' || def?.driver === 'file') {
+        built.push(this._buildFile(def));
+      } else if (def === 'null' || def?.driver === 'null') {
+        built.push(new NullChannel());
+      } else if (def && typeof def.write === 'function') {
+        // Already an instantiated channel — use directly
+        built.push(def);
+      }
+    }
+
+    // Always have at least a console channel
+    if (!built.length) built.push(this._buildConsole({}));
+
+    return built;
+  }
+
+  _buildConsole(opts = {}) {
+    const fmt = this._buildFormatter(opts.formatter || opts.format || 'pretty', opts);
+    return new ConsoleChannel({
+      formatter: fmt,
+      minLevel:  this._resolveLevel(opts.level ?? opts.minLevel),
+    });
+  }
+
+  _buildFile(opts = {}) {
+    const fmt = this._buildFormatter(opts.formatter || opts.format || 'simple', opts);
+    return new FileChannel({
+      path:      opts.path     || 'storage/logs',
+      prefix:    opts.prefix   || 'millas',
+      formatter: fmt,
+      minLevel:  this._resolveLevel(opts.level ?? opts.minLevel),
+      maxFiles:  opts.maxFiles ?? 30,
+    });
+  }
+
+  _buildFormatter(name, opts = {}) {
+    if (name && typeof name === 'object' && typeof name.format === 'function') {
+      return name; // already an instance
+    }
+    switch (String(name).toLowerCase()) {
+      case 'json':
+        return new JsonFormatter({ extra: opts.extra });
+      case 'simple':
+        return new SimpleFormatter();
+      case 'pretty':
+      default:
+        return new PrettyFormatter({
+          colour:           opts.colour !== false && process.stdout.isTTY !== false,
+          timestamp:        opts.timestamp !== false,
+          tag:              opts.tag !== false,
+          timestampFormat:  opts.timestampFormat || 'short',
+        });
+    }
+  }
+
+  _resolveLevel(level) {
+    if (level === undefined || level === null) {
+      return process.env.NODE_ENV === 'production' ? LEVELS.INFO : LEVELS.DEBUG;
+    }
+    if (typeof level === 'number') return level;
+    return LEVELS[String(level).toUpperCase()] ?? LEVELS.DEBUG;
+  }
+
+  _levelName(n) {
+    const names = ['VERBOSE','DEBUG','INFO','WARN','ERROR','WTF'];
+    return names[n] || String(n);
+  }
+}
+
+module.exports = LogServiceProvider;