millas 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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/admin/resources/AdminResource.js

@@ -165,37 +165,80 @@ class AdminResource {
     const limit  = perPage || this.perPage;
     const offset = (page - 1) * limit;
 
-    let qb = this.model.query().orderBy(sort, order);
+    // _db() is available on all ORM versions — it returns a raw knex table query.
+    // We build everything via knex directly so this works regardless of whether
+    // the ORM changes (changes3) have been applied.
+    let q = this.model._db().orderBy(sort, order);
 
-    // Search
+    // ── Search ───────────────────────────────────────────────────────────────
     if (search && this.searchable.length) {
-      const searchable = this.searchable;
-      qb._query = qb._query.where(function () {
-        for (const col of searchable) {
+      const cols = this.searchable;
+      q = q.where(function () {
+        for (const col of cols) {
           this.orWhere(col, 'like', `%${search}%`);
         }
       });
     }
 
-    // Filters (supports __ lookups)
+    // ── Filters ──────────────────────────────────────────────────────────────
+    // Translate __ lookup syntax into knex calls so filter controls work
+    // even without the ORM changes applied.
     for (const [key, value] of Object.entries(filters)) {
-      if (value !== '' && value !== null && value !== undefined) {
-        qb.where(key, value);
+      if (value === '' || value === null || value === undefined) continue;
+
+      const dunder = key.lastIndexOf('__');
+      if (dunder === -1) {
+        q = q.where(key, value);
+        continue;
+      }
+
+      const col    = key.slice(0, dunder);
+      const lookup = key.slice(dunder + 2);
+
+      switch (lookup) {
+        case 'exact':   q = q.where(col, value);           break;
+        case 'not':     q = q.where(col, '!=', value);     break;
+        case 'gt':      q = q.where(col, '>',  value);     break;
+        case 'gte':     q = q.where(col, '>=', value);     break;
+        case 'lt':      q = q.where(col, '<',  value);     break;
+        case 'lte':     q = q.where(col, '<=', value);     break;
+        case 'isnull':  q = value ? q.whereNull(col) : q.whereNotNull(col); break;
+        case 'in':      q = q.whereIn(col, Array.isArray(value) ? value : [value]); break;
+        case 'notin':   q = q.whereNotIn(col, Array.isArray(value) ? value : [value]); break;
+        case 'between': q = q.whereBetween(col, value);    break;
+        case 'contains':
+        case 'icontains': q = q.where(col, 'like', `%${value}%`); break;
+        case 'startswith':
+        case 'istartswith': q = q.where(col, 'like', `${value}%`); break;
+        case 'endswith':
+        case 'iendswith': q = q.where(col, 'like', `%${value}`); break;
+        default:        q = q.where(key, value);           break;
       }
     }
 
-    // Date hierarchy drill-down
+    // ── Date hierarchy ────────────────────────────────────────────────────────
     if (this.dateHierarchy) {
-      if (year)  qb.where(`${this.dateHierarchy}__year`, Number(year));
-      if (month) qb.where(`${this.dateHierarchy}__month`, Number(month));
+      const col = this.dateHierarchy;
+      if (year) {
+        // SQLite / MySQL / PG compatible
+        q = q.whereRaw(`strftime('%Y', "${col}") = ?`, [String(year)])
+          .catch
+          // If strftime not available (PG), fall through — best effort
+          || q;
+      }
+      if (month) {
+        q = q.whereRaw(`strftime('%m', "${col}") = ?`, [String(month).padStart(2, '0')]);
+      }
     }
 
-    const [rows, total] = await Promise.all([
-      qb._query.clone().limit(limit).offset(offset),
-      qb._query.clone().clearSelect().count('* as count').first()
-        .then(r => Number(r?.count ?? 0)),
+    // ── Execute ───────────────────────────────────────────────────────────────
+    const [rows, countResult] = await Promise.all([
+      q.clone().limit(limit).offset(offset),
+      q.clone().count('* as count').first(),
     ]);
 
+    const total = Number(countResult?.count ?? 0);
+
     return {
       data:     rows.map(r => this.model._hydrate(r)),
       total,
@@ -494,11 +537,11 @@ class AdminInline {
   async fetchRows(parentId) {
     if (!this.model || !this.foreignKey) return [];
     try {
-      const rows = await this.model.query()
+      const rows = await this.model._db()
         .where(this.foreignKey, parentId)
         .limit(this.perPage)
-        .get();
-      return rows.map(r => r.toJSON ? r.toJSON() : r);
+        .orderBy('id', 'desc');
+      return rows.map(r => this.model._hydrate ? this.model._hydrate(r) : r);
     } catch { return []; }
   }
 

package/src/admin/views/layouts/base.njk

@@ -1137,7 +1137,7 @@
       const prefix = '{{ adminPrefix }}';
       const resources = [
         {% for r in resources %}
-        { slug: '{{ r.slug }}', index: {{ r.index }} }{% if not loop.last %},{% endif %}
+        { slug: '{{ r.slug }}', index: {{ r.index |  default('null')}} }{% if not loop.last %},{% endif %}
         {% endfor %}
       ];
 

package/src/index.js

@@ -1,5 +1,21 @@
 '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');
@@ -16,13 +32,8 @@ const ServiceProvider    = require('./providers/ServiceProvider');
 const ProviderRegistry   = require('./providers/ProviderRegistry');
 
 // ── ORM ───────────────────────────────────────────────────────────
-const {
-  Model, fields, QueryBuilder, DatabaseManager,
-  SchemaBuilder, MigrationRunner, ModelInspector,
-  Q, LookupParser,
-  Sum, Avg, Min, Max, Count, AggregateExpression,
-  HasOne, HasMany, BelongsTo, BelongsToMany,
-} = require('./orm');
+const { Model, fields, QueryBuilder, DatabaseManager,
+        SchemaBuilder, MigrationRunner, ModelInspector } = require('./orm');
 const DatabaseServiceProvider = require('./providers/DatabaseServiceProvider');
 
 // ── Auth ──────────────────────────────────────────────────────────
@@ -65,6 +76,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,
@@ -73,9 +89,6 @@ module.exports = {
   // ORM
   Model, fields, QueryBuilder, DatabaseManager, SchemaBuilder,
   MigrationRunner, ModelInspector, DatabaseServiceProvider,
-  Q, LookupParser,
-  Sum, Avg, Min, Max, Count, AggregateExpression,
-  HasOne, HasMany, BelongsTo, BelongsToMany,
   // Auth
   Auth, Hasher, JwtDriver, AuthMiddleware, RoleMiddleware,
   AuthController, AuthServiceProvider,

package/src/logger/Logger.js

@@ -0,0 +1,341 @@
+'use strict';
+
+const { LEVELS } = require('./levels');
+
+/**
+ * Logger
+ *
+ * The Millas application logger. Inspired by Android's Timber library —
+ * a small, extensible logging tree where you plant channels ("trees")
+ * and log through a unified facade.
+ *
+ * ── Quick start ────────────────────────────────────────────────────────────
+ *
+ *   const { Log } = require('millas');
+ *
+ *   Log.i('Server started on port 3000');
+ *   Log.d('QueryBuilder', 'SELECT * FROM users', { duration: '4ms' });
+ *   Log.w('Auth', 'Token expiring soon', { userId: 5 });
+ *   Log.e('Database', 'Connection failed', error);
+ *   Log.wtf('Payment', 'Stripe returned null transaction');
+ *
+ * ── Tag chaining (like Timber.tag()) ───────────────────────────────────────
+ *
+ *   Log.tag('UserService').i('User created', { id: 5 });
+ *   Log.tag('Mailer').d('Sending email', { to: 'a@b.com' });
+ *
+ * ── Full signatures ────────────────────────────────────────────────────────
+ *
+ *   Log.v(message)
+ *   Log.v(tag, message)
+ *   Log.v(tag, message, context)        // context = object | primitive
+ *   Log.v(tag, message, error)          // error = Error instance
+ *   Log.v(tag, message, context, error)
+ *
+ * ── Configuration ──────────────────────────────────────────────────────────
+ *
+ *   Log.configure({
+ *     minLevel: LEVELS.INFO,     // filter out VERBOSE + DEBUG in production
+ *     channel:  new StackChannel([
+ *       new ConsoleChannel({ formatter: new PrettyFormatter() }),
+ *       new FileChannel({ formatter: new SimpleFormatter(), minLevel: LEVELS.WARN }),
+ *     ]),
+ *   });
+ *
+ * ── Request logging (Django-style) ─────────────────────────────────────────
+ *
+ *   // In bootstrap/app.js — installed automatically by LogServiceProvider
+ *   app.use(Log.requestMiddleware());
+ *   // Logs: [2026-03-15 12:00:00] I  HTTP  POST /api/users 201 14ms
+ */
+class Logger {
+  constructor() {
+    this._channel    = null;      // primary channel (StackChannel in production)
+    this._minLevel   = LEVELS.DEBUG;
+    this._tag        = null;      // set by .tag() for a single chained call
+    this._defaultTag = 'App';
+  }
+
+  // ─── Configuration ────────────────────────────────────────────────────────
+
+  /**
+   * Configure the logger.
+   *
+   * @param {object} options
+   * @param {object}  [options.channel]    — a channel or StackChannel instance
+   * @param {number}  [options.minLevel]   — minimum level to emit (LEVELS.*)
+   * @param {string}  [options.defaultTag] — fallback tag when none supplied
+   */
+  configure(options = {}) {
+    if (options.channel  !== undefined) this._channel    = options.channel;
+    if (options.minLevel !== undefined) this._minLevel   = options.minLevel;
+    if (options.defaultTag !== undefined) this._defaultTag = options.defaultTag;
+    return this;
+  }
+
+  /**
+   * Set a one-shot tag for the next log call.
+   * Returns a proxy that resets the tag after the call.
+   *
+   *   Log.tag('UserService').i('Created user', { id: 5 });
+   */
+  tag(name) {
+    // Return a lightweight proxy that carries the tag
+    return new TaggedLogger(this, name);
+  }
+
+  // ─── Timber-style level methods ───────────────────────────────────────────
+
+  /** VERBOSE — very detailed tracing, usually disabled in production */
+  v(...args) { return this._log(LEVELS.VERBOSE, null, ...args); }
+
+  /** DEBUG — development diagnostics */
+  d(...args) { return this._log(LEVELS.DEBUG, null, ...args); }
+
+  /** INFO — normal operational messages */
+  i(...args) { return this._log(LEVELS.INFO, null, ...args); }
+
+  /** WARN — unexpected but recoverable */
+  w(...args) { return this._log(LEVELS.WARN, null, ...args); }
+
+  /** ERROR — something failed */
+  e(...args) { return this._log(LEVELS.ERROR, null, ...args); }
+
+  /**
+   * WTF — "What a Terrible Failure"
+   * A condition that should NEVER happen. Always logged regardless of minLevel.
+   * Triggers a big visual warning in the console.
+   */
+  wtf(...args) { return this._log(LEVELS.WTF, null, ...args); }
+
+  // ─── Verbose aliases (for readability) ────────────────────────────────────
+
+  /** Alias for i() */
+  info(...args)    { return this.i(...args); }
+  /** Alias for d() */
+  debug(...args)   { return this.d(...args); }
+  /** Alias for w() */
+  warn(...args)    { return this.w(...args); }
+  /** Alias for e() */
+  error(...args)   { return this.e(...args); }
+  /** Alias for v() */
+  verbose(...args) { return this.v(...args); }
+
+  // ─── Request middleware (Django-style) ────────────────────────────────────
+
+  /**
+   * Returns an Express middleware that logs every HTTP request.
+   *
+   * Log format:
+   *   POST /api/users 201 14ms  (coloured by status)
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.includeQuery=false]   — append ?query to path
+   * @param {boolean} [options.includeBody=false]    — log request body (be careful with PII)
+   * @param {number}  [options.slowThreshold=1000]   — warn if response > Nms
+   * @param {Function} [options.skip]                — (req, res) => bool — skip certain routes
+   */
+  requestMiddleware(options = {}) {
+    const self = this;
+    const {
+      includeQuery   = false,
+      includeBody    = false,
+      slowThreshold  = 1000,
+      skip,
+    } = options;
+
+    return function millaRequestLogger(req, res, next) {
+      if (typeof skip === 'function' && skip(req, res)) return next();
+
+      const start = Date.now();
+
+      res.on('finish', () => {
+        const ms     = Date.now() - start;
+        const status = res.statusCode;
+        const method = req.method;
+        let   url    = req.path || req.url || '/';
+
+        if (includeQuery && req.url && req.url.includes('?')) {
+          url = req.url;
+        }
+
+        // Determine log level from status code — mirrors Django's request logging
+        let level;
+        if      (status >= 500) level = LEVELS.ERROR;
+        else if (status >= 400) level = LEVELS.WARN;
+        else if (ms > slowThreshold) level = LEVELS.WARN;
+        else                    level = LEVELS.INFO;
+
+        const ctx = {
+          method,
+          status,
+          ms,
+          ip: req.ip || req.connection?.remoteAddress,
+        };
+
+        if (includeBody && req.body && Object.keys(req.body).length) {
+          ctx.body = req.body;
+        }
+
+        if (ms > slowThreshold) {
+          ctx.slow = true;
+        }
+
+        self._log(level, 'HTTP', `${method} ${url} ${status} ${ms}ms`, ctx);
+      });
+
+      next();
+    };
+  }
+
+  // ─── Timer utility ────────────────────────────────────────────────────────
+
+  /**
+   * Start a named timer. Returns a function that logs the elapsed time.
+   *
+   *   const done = Log.time('Database query');
+   *   await db.query(...);
+   *   done(); // → I  Timer  Database query: 42ms
+   */
+  time(label) {
+    const start = Date.now();
+    return (extraTag) => {
+      const ms = Date.now() - start;
+      this._log(LEVELS.DEBUG, extraTag || 'Timer', `${label}: ${ms}ms`, { ms });
+      return ms;
+    };
+  }
+
+  /**
+   * Wrap an async function and log its execution time.
+   *
+   *   const result = await Log.timed('fetchUsers', () => User.all());
+   */
+  async timed(label, fn, tag) {
+    const done = this.time(label);
+    try {
+      const result = await fn();
+      done(tag);
+      return result;
+    } catch (err) {
+      this._log(LEVELS.ERROR, tag || 'Timer', `${label} threw`, err);
+      throw err;
+    }
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  /**
+   * Core dispatch method.
+   *
+   * Signatures:
+   *   _log(level, forcedTag, message)
+   *   _log(level, forcedTag, tag, message)
+   *   _log(level, forcedTag, tag, message, context)
+   *   _log(level, forcedTag, tag, message, context, error)
+   *   _log(level, forcedTag, tag, message, error)          // Error as 4th arg
+   */
+  _log(level, forcedTag, ...args) {
+    // WTF is always emitted regardless of minLevel
+    if (level !== LEVELS.WTF && level < this._minLevel) return;
+
+    const entry = this._parse(level, forcedTag, args);
+    this._emit(entry);
+  }
+
+  _parse(level, forcedTag, args) {
+    let tag, message, context, error;
+
+    // Normalise arguments
+    if (args.length === 0) {
+      message = '';
+    } else if (args.length === 1) {
+      // Single arg — could be a string message or an Error
+      if (args[0] instanceof Error) {
+        error   = args[0];
+        message = error.message;
+      } else {
+        message = String(args[0]);
+      }
+    } else if (args.length === 2) {
+      // (tag, message) OR (message, context/error)
+      if (typeof args[0] === 'string' && typeof args[1] === 'string') {
+        // Both strings: tag + message
+        tag     = args[0];
+        message = args[1];
+      } else if (args[1] instanceof Error) {
+        message = String(args[0]);
+        error   = args[1];
+      } else if (typeof args[0] === 'string') {
+        message = args[0];
+        context = args[1];
+      } else {
+        message = String(args[0]);
+        context = args[1];
+      }
+    } else if (args.length === 3) {
+      // (tag, message, context/error)
+      tag     = String(args[0]);
+      message = String(args[1]);
+      if (args[2] instanceof Error) error   = args[2];
+      else                          context = args[2];
+    } else {
+      // (tag, message, context, error)
+      tag     = String(args[0]);
+      message = String(args[1]);
+      context = args[2];
+      error   = args[3] instanceof Error ? args[3] : undefined;
+    }
+
+    return {
+      level,
+      tag:       forcedTag || tag || this._defaultTag,
+      message:   message   || '',
+      context,
+      error,
+      timestamp: new Date().toISOString(),
+      pid:       process.pid,
+    };
+  }
+
+  _emit(entry) {
+    if (!this._channel) {
+      // No channel configured — fall back to raw console so nothing is lost
+      const prefix = `[${entry.level}] ${entry.tag}: ${entry.message}`;
+      if (entry.level >= 4) process.stderr.write(prefix + '\n');
+      else                  process.stdout.write(prefix + '\n');
+      return;
+    }
+
+    try {
+      this._channel.write(entry);
+    } catch (err) {
+      // Never crash the app because of a logging failure
+      process.stderr.write(`[millas logger] channel error: ${err.message}\n`);
+    }
+  }
+}
+
+// ─── TaggedLogger — returned by Log.tag() ─────────────────────────────────────
+
+class TaggedLogger {
+  constructor(logger, tag) {
+    this._logger = logger;
+    this._tag    = tag;
+  }
+
+  v(...args) { return this._logger._log(LEVELS.VERBOSE, this._tag, ...args); }
+  d(...args) { return this._logger._log(LEVELS.DEBUG,   this._tag, ...args); }
+  i(...args) { return this._logger._log(LEVELS.INFO,    this._tag, ...args); }
+  w(...args) { return this._logger._log(LEVELS.WARN,    this._tag, ...args); }
+  e(...args) { return this._logger._log(LEVELS.ERROR,   this._tag, ...args); }
+  wtf(...args) { return this._logger._log(LEVELS.WTF,  this._tag, ...args); }
+
+  info(...args)    { return this.i(...args); }
+  debug(...args)   { return this.d(...args); }
+  warn(...args)    { return this.w(...args); }
+  error(...args)   { return this.e(...args); }
+  verbose(...args) { return this.v(...args); }
+}
+
+module.exports = Logger;

package/src/logger/channels/ConsoleChannel.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * ConsoleChannel
+ *
+ * Writes log entries to process.stdout (levels < ERROR) or
+ * process.stderr (ERROR and WTF).
+ *
+ * Usage in config/logging.js:
+ *   new ConsoleChannel({ formatter: new PrettyFormatter() })
+ */
+class ConsoleChannel {
+  /**
+   * @param {object} options
+   * @param {object} options.formatter  — formatter instance (PrettyFormatter, JsonFormatter, …)
+   * @param {number} [options.minLevel] — minimum level to output (default: 0 = all)
+   */
+  constructor(options = {}) {
+    this.formatter = options.formatter;
+    this.minLevel  = options.minLevel ?? 0;
+  }
+
+  write(entry) {
+    if (entry.level < this.minLevel) return;
+
+    const output = this.formatter
+      ? this.formatter.format(entry)
+      : `[${entry.level}] ${entry.message}`;
+
+    // Route errors to stderr
+    if (entry.level >= 4) {
+      process.stderr.write(output + '\n');
+    } else {
+      process.stdout.write(output + '\n');
+    }
+  }
+}
+
+module.exports = ConsoleChannel;

package/src/logger/channels/FileChannel.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * FileChannel
+ *
+ * Writes log entries to daily rotating files.
+ *   storage/logs/millas-2026-03-15.log
+ *   storage/logs/millas-2026-03-16.log
+ *   …
+ *
+ * Uses Node's built-in fs — no external log-rotation library needed.
+ * Files are appended synchronously to avoid losing entries on crash.
+ *
+ * Usage in config/logging.js:
+ *   new FileChannel({
+ *     path:      'storage/logs',
+ *     prefix:    'millas',
+ *     formatter: new SimpleFormatter(),
+ *     minLevel:  LEVELS.INFO,
+ *     maxFiles:  30,   // keep 30 days of logs
+ *   })
+ */
+class FileChannel {
+  /**
+   * @param {object} options
+   * @param {string}  [options.path]       — directory path (default: storage/logs)
+   * @param {string}  [options.prefix]     — filename prefix (default: 'millas')
+   * @param {object}  [options.formatter]  — formatter instance
+   * @param {number}  [options.minLevel]   — minimum level (default: 0)
+   * @param {number}  [options.maxFiles]   — max daily files to retain (default: 30)
+   */
+  constructor(options = {}) {
+    this._dir       = path.resolve(process.cwd(), options.path || 'storage/logs');
+    this._prefix    = options.prefix    || 'millas';
+    this.formatter  = options.formatter;
+    this.minLevel   = options.minLevel  ?? 0;
+    this._maxFiles  = options.maxFiles  ?? 30;
+    this._lastDate  = null;
+    this._stream    = null;
+    this._ensuredDir = false;
+  }
+
+  write(entry) {
+    if (entry.level < this.minLevel) return;
+
+    try {
+      this._ensureDir();
+
+      const today = new Date().toISOString().slice(0, 10);
+      if (today !== this._lastDate) {
+        this._rotateStream(today);
+        this._pruneOldFiles();
+      }
+
+      const line = this.formatter
+        ? this.formatter.format(entry)
+        : `[${entry.timestamp}] [${entry.level}] ${entry.message}`;
+
+      fs.appendFileSync(this._currentPath, line + '\n', 'utf8');
+    } catch (err) {
+      // Never crash the app because of a logging failure
+      process.stderr.write(`[millas logger] FileChannel write error: ${err.message}\n`);
+    }
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────────
+
+  _ensureDir() {
+    if (this._ensuredDir) return;
+    fs.mkdirSync(this._dir, { recursive: true });
+    this._ensuredDir = true;
+  }
+
+  _rotateStream(date) {
+    this._lastDate    = date;
+    this._currentPath = path.join(this._dir, `${this._prefix}-${date}.log`);
+  }
+
+  _pruneOldFiles() {
+    try {
+      const files = fs.readdirSync(this._dir)
+        .filter(f => f.startsWith(this._prefix + '-') && f.endsWith('.log'))
+        .sort(); // ISO date prefix sorts chronologically
+
+      const toDelete = files.slice(0, Math.max(0, files.length - this._maxFiles));
+      for (const f of toDelete) {
+        try { fs.unlinkSync(path.join(this._dir, f)); } catch {}
+      }
+    } catch {}
+  }
+
+  /** Current log file path (useful for tooling). */
+  get currentFile() {
+    return this._currentPath || null;
+  }
+}
+
+module.exports = FileChannel;