millas 0.2.11 → 0.2.12-beta

package/src/orm/query/QueryBuilder.js

@@ -2,6 +2,7 @@
 
 const LookupParser        = require('./LookupParser');
 const { AggregateExpression } = require('./Aggregates');
+const MillasLog           = require('../../logger/internal');
 
 /**
  * QueryBuilder
@@ -81,6 +82,21 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Bypass all global scopes for this query.
+   * Useful when you intentionally need an unfiltered view of the table.
+   *
+   *   User.withoutGlobalScope().get()   // skips tenant filter, active-only, etc.
+   */
+  withoutGlobalScope() {
+    // Re-build the base query directly from knex, bypassing _db() where
+    // globalScopes are applied.
+    const DatabaseManager = require('../drivers/DatabaseManager');
+    const db = DatabaseManager.connection(this._model.connection || null);
+    this._query = db(this._model.table);
+    return this;
+  }
+
   // ─── Scopes ───────────────────────────────────────────────────────────────
 
   /**
@@ -117,7 +133,38 @@ class QueryBuilder {
     return this;
   }
 
-  // ─── Aggregation ──────────────────────────────────────────────────────────
+  /**
+   * Eager-load a COUNT of related rows onto each result.
+   *
+   *   Post.withCount('comments').get()
+   *   // each post gets .comments_count
+   *
+   *   Post.withCount('comments', 'likes').get()
+   *   Post.withCount({ comments: q => q.where('approved', true) }).get()
+   */
+  withCount(...relations) {
+    for (const rel of relations.flat()) {
+      if (typeof rel === 'string') {
+        this._withs.push({ name: rel, constraint: null, aggregate: 'count' });
+      } else if (typeof rel === 'object') {
+        for (const [name, constraint] of Object.entries(rel)) {
+          this._withs.push({ name, constraint, aggregate: 'count' });
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Eager-load a SUM of a related column onto each result.
+   *
+   *   User.withSum('orders', 'amount').get()
+   *   // each user gets .orders_sum_amount
+   */
+  withSum(relation, column) {
+    this._withs.push({ name: relation, constraint: null, aggregate: 'sum', aggregateColumn: column });
+    return this;
+  }
 
   /**
    * Add per-row computed columns.
@@ -336,10 +383,18 @@ class QueryBuilder {
 
     const relations = this._model.relations || {};
 
-    for (const { name, constraint } of this._withs) {
+    for (const { name, constraint, aggregate, aggregateColumn } of this._withs) {
+
+      // ── withCount / withSum  ──────────────────────────────────────────────
+      if (aggregate) {
+        await this._eagerAggregate(instances, name, aggregate, aggregateColumn, constraint, relations);
+        continue;
+      }
+
+      // ── Normal eager load ─────────────────────────────────────────────────
       const rel = relations[name];
       if (!rel) {
-        process.stderr.write(`  [millas] Warning: relation "${name}" not defined on ${this._model.name}\n`);
+        MillasLog.w('ORM', `Relation "${name}" not defined on ${this._model.name} — skipping eager load`);
         continue;
       }
 
@@ -347,6 +402,89 @@ class QueryBuilder {
     }
   }
 
+  /**
+   * Load an aggregate (COUNT / SUM) of a relation onto each instance
+   * without pulling back full related rows.
+   */
+  async _eagerAggregate(instances, relName, aggFn, aggColumn, constraint, relations) {
+    const rel = relations[relName];
+    if (!rel) {
+      MillasLog.w('ORM', `Relation "${relName}" not defined on ${this._model.name} — cannot compute ${aggFn}`);
+      // Zero-fill the attribute
+      const attr = aggFn === 'sum'
+        ? `${relName}_sum_${aggColumn}`
+        : `${relName}_count`;
+      for (const i of instances) i[attr] = 0;
+      return;
+    }
+
+    const attrName = aggFn === 'sum'
+      ? `${relName}_sum_${aggColumn}`
+      : `${relName}_count`;
+
+    // We only support HasMany / BelongsToMany for aggregate loads for now.
+    // For those, the foreignKey / pivot info is on the rel object.
+    const HasMany       = require('../relations/HasMany');
+    const BelongsToMany = require('../relations/BelongsToMany');
+
+    const localKey  = rel._localKey   || this._model.primaryKey || 'id';
+    const keys      = [...new Set(instances.map(i => i[localKey]).filter(v => v != null))];
+
+    if (!keys.length) {
+      for (const i of instances) i[attrName] = 0;
+      return;
+    }
+
+    const related = rel._related;
+    let q;
+
+    if (rel instanceof HasMany) {
+      const fk = rel._foreignKey;
+      q = related._db()
+        .select(`${fk} as _owner_id`)
+        .whereIn(fk, keys);
+
+      if (aggFn === 'count') {
+        q = q.count(`${related.primaryKey || 'id'} as _agg_val`).groupBy(fk);
+      } else {
+        q = q.sum(`${aggColumn} as _agg_val`).groupBy(fk);
+      }
+
+    } else if (rel instanceof BelongsToMany) {
+      const pivot    = rel._pivotTable;
+      const fk       = rel._foreignPivotKey;
+      const rk       = rel._relatedPivotKey;
+      q = related._db()
+        .join(pivot, `${related.table}.${related.primaryKey || 'id'}`, '=', `${pivot}.${rk}`)
+        .select(`${pivot}.${fk} as _owner_id`)
+        .whereIn(`${pivot}.${fk}`, keys);
+
+      if (aggFn === 'count') {
+        q = q.count(`${related.table}.${related.primaryKey || 'id'} as _agg_val`).groupBy(`${pivot}.${fk}`);
+      } else {
+        q = q.sum(`${related.table}.${aggColumn} as _agg_val`).groupBy(`${pivot}.${fk}`);
+      }
+    } else {
+      // Unsupported relation type — zero-fill
+      for (const i of instances) i[attrName] = 0;
+      return;
+    }
+
+    if (constraint) {
+      const QB = require('./QueryBuilder');
+      const qb = new QB(q, related);
+      constraint(qb);
+      q = qb._query;
+    }
+
+    const rows = await q;
+    const map  = new Map(rows.map(r => [r._owner_id, Number(r._agg_val ?? 0)]));
+
+    for (const instance of instances) {
+      instance[attrName] = map.get(instance[localKey]) ?? 0;
+    }
+  }
+
   // ─── Internal where dispatcher ────────────────────────────────────────────
 
   _applyWhere(method, column, operatorOrValue, value) {

package/src/providers/LogServiceProvider.js

@@ -13,47 +13,117 @@ const {
   NullChannel,
   StackChannel,
 } = require('../logger/index');
+const MillasLog      = require('../logger/internal');
+const patchConsole   = require('../logger/patchConsole');
 
 /**
  * LogServiceProvider
  *
- * Reads config/logging.js and configures the Log singleton.
- * Also registers Log and Logger in the DI container.
+ * On boot:
+ *   1. Configures Log (app logger) from config/logging.js
+ *   2. Configures MillasLog (internal framework logger) from config.internal
+ *   3. Patches console.* to route through Log  (unless interceptConsole: false)
  *
- * Add to bootstrap/app.js:
- *   app.providers([LogServiceProvider, ...]);
+ * config/logging.js reference:
  *
- * The provider is intentionally ordered first so every other provider
- * can use Log during their boot() method.
+ *   module.exports = {
+ *     level:    'debug',
+ *     channels: [{ driver: 'console', format: 'pretty' }],
  *
- * config/logging.js is optional — sensible defaults apply if absent.
+ *     // Opt out of console patching:
+ *     interceptConsole: false,
+ *
+ *     // Framework-internal logs (ORM, migrations, admin):
+ *     internal: { level: 'warn' },
+ *   };
  */
 class LogServiceProvider extends ServiceProvider {
   register(container) {
-    container.instance('Log',    Log);
-    container.instance('Logger', Logger);
+    container.instance('Log',       Log);
+    container.instance('Logger',    Logger);
+    container.instance('MillasLog', MillasLog);
   }
 
-  async boot(container, app) {
+  /**
+   * beforeBoot — runs before any provider's register() call.
+   *
+   * We configure logging and patch console here so that:
+   *   - Every register() call in every provider already produces
+   *     formatted log output
+   *   - No provider boots without a working logger
+   *
+   * This is synchronous — no async allowed in beforeBoot.
+   * We load config synchronously and apply defaults eagerly.
+   */
+  beforeBoot(container) {
     let config = {};
     try {
       config = require(process.cwd() + '/config/logging');
     } catch {
-      // No config — use defaults already set in logger/index.js
-      return;
+      // No config file — defaults already applied in logger/index.js
     }
 
-    const channels = this._buildChannels(config);
+    // Store config on the instance so boot() can use it without re-reading
+    this._loggingConfig = config;
 
+    // ── Configure Log from config ─────────────────────────────────────────
+    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),
+      defaultTag: config.defaultTag || 'SystemOut',
+      channel:    channels.length === 1 ? channels[0] : new StackChannel(channels),
     });
 
-    Log.tag('Millas').i(`Logger configured — level: ${this._levelName(Log._minLevel)}, channels: ${channels.length}`);
+    // ── Configure MillasLog (internal framework logger) ───────────────────
+    this._configureMillasLog(config.internal);
+
+    // ── Patch console.* → Log.* ───────────────────────────────────────────
+      this._restoreConsole = patchConsole(Log, config.defaultTag || 'SystemOut');
+
+  }
+
+  async boot(container, app) {
+    const config  = this._loggingConfig || {};
+    const intercept = config.interceptConsole !== false;
+
+    // Store restore fn so tests can call container.make('console.restore')
+    if (this._restoreConsole) {
+      container.instance('console.restore', this._restoreConsole);
+    }
+
+    // Log.tag('Millas').i(
+    //   `Logger ready` +
+    //   ` — level: ${this._levelName(Log._minLevel)}` +
+    //   `, internal: ${this._levelName(MillasLog._minLevel)}` +
+    //   `, console: ${intercept ? 'intercepted' : 'native'}`
+    // );
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  _configureMillasLog(internalConfig) {
+    if (internalConfig === false) {
+      MillasLog.configure({ channel: new NullChannel() });
+    } else if (internalConfig && typeof internalConfig === 'object') {
+      if (internalConfig.channels) {
+        const internalChannels = this._buildChannels(internalConfig);
+        MillasLog.configure({
+          minLevel:   this._resolveLevel(internalConfig.level ?? internalConfig.minLevel),
+          defaultTag: 'Millas',
+          channel:    internalChannels.length === 1
+            ? internalChannels[0]
+            : new StackChannel(internalChannels),
+        });
+      } else {
+        const fmt   = this._buildFormatter(internalConfig.format || 'pretty', internalConfig);
+        const level = this._resolveLevel(internalConfig.level ?? internalConfig.minLevel);
+        MillasLog.configure({
+          minLevel:   level,
+          defaultTag: 'Millas',
+          channel:    new ConsoleChannel({ formatter: fmt, minLevel: level }),
+        });
+      }
+    }
   }
 
   // ─── Private ──────────────────────────────────────────────────────────────

package/src/providers/ProviderRegistry.js

@@ -53,9 +53,22 @@ class ProviderRegistry {
   }
 
   /**
-   * Run the full register → boot lifecycle.
+   * Run the full provider lifecycle in order:
+   *   Phase 0 — beforeBoot   (synchronous, no bindings yet — for global setup)
+   *   Phase 1 — register     (synchronous, bind into container)
+   *   Phase 2 — boot         (async-safe, all bindings exist)
    */
   async boot() {
+    // Phase 0: beforeBoot — runs before ANY register() call.
+    // Synchronous only. Used for global setup that must happen first
+    // (e.g. LogServiceProvider patches console here so all register()
+    // calls already produce formatted output).
+    for (const provider of this._providers) {
+      if (typeof provider.beforeBoot === 'function') {
+        provider.beforeBoot(this._container);
+      }
+    }
+
     // Phase 1: register all bindings
     for (const provider of this._providers) {
       if (typeof provider.register === 'function') {

package/src/providers/ServiceProvider.js

@@ -5,37 +5,69 @@
  *
  * Base class for all Millas service providers.
  *
- * Providers have two lifecycle hooks:
+ * ── Lifecycle hooks (called in this order) ─────────────────────────────────
+ *
+ *   beforeBoot(container)
+ *     Called FIRST — before any provider's register() runs.
+ *     Use for setup that must happen before everything else:
+ *       - Configuring logging (so register() calls get formatted output)
+ *       - Patching globals (console, process handlers)
+ *       - Reading config files that other providers depend on
+ *     The container exists but has NO bindings yet.
+ *     Must be synchronous — async is not supported here.
  *
  *   register(container)
- *     Called first. Bind things into the container.
- *     Do NOT use other bindings here — they may not exist yet.
+ *     Called after ALL beforeBoot() hooks have run.
+ *     Bind things into the container (singletons, factories, instances).
+ *     Do NOT resolve other bindings here — they may not exist yet.
+ *     Must be synchronous.
  *
  *   boot(container, app)
  *     Called after ALL providers have registered.
- *     Safe to resolve other bindings and set up routes,
- *     event listeners, middleware, etc.
+ *     Safe to resolve other bindings, set up routes, register
+ *     event listeners, mount middleware, etc.
+ *     Async-safe — await is fine here.
+ *
+ * ── Example ────────────────────────────────────────────────────────────────
  *
- * Usage:
  *   class AppServiceProvider extends ServiceProvider {
+ *     beforeBoot(container) {
+ *       // Runs before any register() — good for global setup
+ *     }
+ *
  *     register(container) {
  *       container.singleton('UserService', UserService);
  *     }
+ *
  *     async boot(container, app) {
- *       const logger = container.make('Logger');
- *       logger.info('AppServiceProvider booted');
+ *       const db = container.make('db');
+ *       await db.migrate();
  *     }
  *   }
  */
 class ServiceProvider {
+  /**
+   * Called before any provider's register() runs.
+   * Container exists but has no bindings yet.
+   * Must be synchronous.
+   *
+   * @param {import('./Container')} container
+   */
+  beforeBoot(container) {}
+
   /**
    * Register bindings into the container.
+   * Called after all beforeBoot() hooks have run.
+   * Must be synchronous.
+   *
    * @param {import('./Container')} container
    */
   register(container) {}
 
   /**
    * Bootstrap services after all providers have registered.
+   * Safe to resolve other bindings. Async-safe.
+   *
    * @param {import('./Container')} container
    * @param {import('express').Application} app
    */