millas 0.2.24 → 0.2.25

package/README.md

@@ -89,6 +89,25 @@ class User extends Model {
 }
 ```
 
+## Configuration
+
+```js
+// config/app.js
+module.exports = {
+  name: 'My App',
+  env: process.env.NODE_ENV || 'development',
+  timezone: 'UTC',  // Scheduler timezone (cron timing)
+  
+  // ORM timezone behavior (Django-style)
+  useTz: true,  // true = treat DB timestamps as UTC (recommended)
+                // false = treat DB timestamps as local server time
+                // Column type stays TIMESTAMP (without timezone)
+                // Conversion happens in application layer
+  
+  allowedHosts: [],  // Django-style host validation
+};
+```
+
 ## Authentication
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "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/container/AppInitializer.js

@@ -73,6 +73,7 @@ class AppInitializer {
      */
     async bootKernel() {
         const cfg = this._config;
+        const basePath = cfg.basePath || process.cwd();
 
         const ExpressAdapter = require('../http/adapters/ExpressAdapter');
         const expressApp = express();
@@ -83,7 +84,6 @@ class AppInitializer {
         // Reads config/app.js for overrides. All protections are on by default:
         // security headers, CSRF, rate limiting, cookie defaults, allowed hosts.
         const SecurityBootstrap = require('../http/SecurityBootstrap');
-        const basePath          = cfg.basePath || process.cwd();
         const appConfig         = SecurityBootstrap.loadConfig(basePath + '/config/app');
         SecurityBootstrap.apply(this._adapter.nativeApp || expressApp, appConfig);
 

package/src/core/foundation.js

@@ -47,6 +47,7 @@ const UploadedFile     = require('../http/UploadedFile');
 // ── Serializer ────────────────────────────────────────────────────
 const { Serializer } = require('../serializer/Serializer');
 const {Str, FluentString} = require("../support/Str");
+const Time = require('../support/Time');
 
 module.exports = {
   // ── Millas HTTP layer ──────────────────────────────────────────
@@ -68,7 +69,7 @@ module.exports = {
   // Serializer
   Serializer,
   // Support
-  Str, FluentString,
+  Str, FluentString, Time,
   Log: require('../logger').Log,
   // Scheduler
   TaskScheduler: require('../scheduler').TaskScheduler,

package/src/core/timezone.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * core/timezone
+ *
+ * Timezone utilities for Millas.
+ *
+ * Usage:
+ *   const { Time } = require('millas/core/timezone');
+ *   const now = Time.now();
+ */
+
+const Time = require('../support/Time');
+
+module.exports = { Time };

package/src/logger/formatters/JsonFormatter.js

@@ -30,7 +30,7 @@ class JsonFormatter {
     const { level, tag, message, context, error, timestamp } = entry;
 
     const record = {
-      ts:    timestamp || new Date().toISOString(),
+      ts:    timestamp instanceof Date ? timestamp.toISOString() : (timestamp || new Date().toISOString()),
       level: LEVEL_NAMES[level] || String(level),
       ...this.extra,
     };

package/src/logger/formatters/PrettyFormatter.js

@@ -135,8 +135,9 @@ class PrettyFormatter {
 
   _timestamp() {
     const now = new Date();
-    if (this.tsFormat === 'iso') return now.toISOString();
-    return now.toISOString().replace('T', ' ').slice(0, 19);
+    const isoStr = now.toISOString();
+    if (this.tsFormat === 'iso') return isoStr;
+    return isoStr.replace('T', ' ').slice(0, 19);
   }
 }
 

package/src/logger/formatters/SimpleFormatter.js

@@ -26,7 +26,8 @@ class SimpleFormatter {
   format(entry) {
     const { level, tag, message, context, error, timestamp } = entry;
 
-    const ts      = (timestamp || new Date().toISOString()).replace('T', ' ').slice(0, 23);
+    const isoStr  = timestamp instanceof Date ? timestamp.toISOString() : (timestamp || new Date().toISOString());
+    const ts      = isoStr.replace('T', ' ').slice(0, 23);
     const lvlName = (LEVEL_NAMES[level] || String(level)).padEnd(7);
     const tagPart = tag ? `${tag}: ` : '';
 

package/src/orm/drivers/DatabaseManager.js

@@ -206,7 +206,21 @@ class DatabaseManager {
             'Run: npm install pg'
           );
         }
-        return knex({
+        
+        // Configure pg to parse timestamps as UTC
+        const types = require('pg').types;
+        const TIMESTAMP_OID = 1114; // timestamp without timezone
+        const TIMESTAMPTZ_OID = 1184; // timestamp with timezone
+        
+        // Override pg's default timestamp parser to always return UTC
+        types.setTypeParser(TIMESTAMP_OID, (val) => {
+          return val === null ? null : new Date(val + 'Z'); // Treat as UTC
+        });
+        types.setTypeParser(TIMESTAMPTZ_OID, (val) => {
+          return val === null ? null : new Date(val); // Already has timezone
+        });
+        
+        const pgConnection = knex({
           client:     'pg',
           connection: {
             host:     conf.host,
@@ -215,8 +229,15 @@ class DatabaseManager {
             user:     conf.username,
             password: conf.password,
           },
-          pool: { min: 2, max: 10 },
+          pool: { 
+            min: 2, 
+            max: 10,
+            afterCreate: (conn, done) => {
+              conn.query('SET timezone = "UTC";', (err) => done(err, conn));
+            },
+          },
         });
+        return pgConnection;
 
       default:
         throw new Error(`Unsupported database driver: "${conf.driver}"`);

package/src/orm/model/Model.js

@@ -967,6 +967,15 @@ class Model {
           const d = new Date(val.valueOf?.() ?? val);
           return isNaN(d.getTime()) ? null : d;
         }
+        // Django-style USE_TZ: if enabled, treat naive DB timestamps as UTC
+        if (this._isUseTzEnabled()) {
+          // Parse as UTC by appending 'Z' if no timezone info present
+          const str = String(val);
+          if (!str.includes('Z') && !str.includes('+') && !str.includes('-', 10)) {
+            const d = new Date(str + 'Z');
+            return isNaN(d.getTime()) ? null : d;
+          }
+        }
         const d = new Date(val);
         return isNaN(d.getTime()) ? null : d;
       }
@@ -1038,6 +1047,15 @@ class Model {
     } catch { return false; }
   }
 
+  static _isUseTzEnabled() {
+    try {
+      const appConfig = require(process.cwd() + '/config/app.js');
+      return appConfig.useTz !== false; // Default to true (Django-style)
+    } catch {
+      return true;
+    }
+  }
+
   /**
    * Insert a row and return the inserted primary key — dialect-aware.
    * SQLite: insert returns [lastId]

package/src/support/Time.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * Time
+ *
+ * Timezone utilities for Millas.
+ * Provides helpers for timezone conversion and formatting.
+ *
+ * Note: JavaScript's Date object is already timezone-aware (stores UTC internally),
+ * unlike Python's datetime which is naive by default. That's why Django needs
+ * timezone.now() but JavaScript doesn't - new Date() already returns UTC.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const { Time } = require('millas/core/timezone');
+ *
+ *   // Convert UTC to local timezone for display
+ *   const local = Time.localtime(new Date());
+ *
+ *   // Parse datetime string as UTC
+ *   const dt = Time.parse('2026-03-31 20:00:00');
+ *
+ *   // Format for display
+ *   const formatted = Time.format(new Date(), 'datetime');
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ *
+ *   // config/app.js
+ *   module.exports = {
+ *     timezone: 'UTC',        // Default timezone for display/scheduler
+ *     useTz: true,            // Store/read timestamps as UTC (recommended)
+ *   };
+ */
+class Time {
+  /**
+   * Convert a UTC datetime to the local timezone configured in config/app.js.
+   * Useful for displaying times to users in their expected timezone.
+   *
+   * @param {Date} dt - UTC datetime
+   * @returns {Date} datetime in local timezone
+   */
+  static localtime(dt) {
+    if (!(dt instanceof Date)) {
+      throw new TypeError('localtime() requires a Date object');
+    }
+
+    const timezone = this.getTimezone();
+    if (timezone === 'UTC') return dt;
+
+    // For non-UTC timezones, we need to calculate the offset
+    // This is a simplified implementation - for production use,
+    // consider using a library like date-fns-tz or luxon
+    try {
+      const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+      });
+
+      const parts = formatter.formatToParts(dt);
+      const values = {};
+      for (const part of parts) {
+        if (part.type !== 'literal') values[part.type] = part.value;
+      }
+
+      return new Date(
+        `${values.year}-${values.month}-${values.day}T${values.hour}:${values.minute}:${values.second}`
+      );
+    } catch (err) {
+      // Fallback if timezone is invalid
+      return dt;
+    }
+  }
+
+  /**
+   * Convert a naive datetime to timezone-aware datetime.
+   * If useTz=true, assumes the naive datetime is in UTC.
+   * If useTz=false, assumes the naive datetime is in local timezone.
+   *
+   * @param {Date} dt - naive datetime
+   * @returns {Date} timezone-aware datetime
+   */
+  static makeAware(dt) {
+    if (!(dt instanceof Date)) {
+      throw new TypeError('makeAware() requires a Date object');
+    }
+
+    // If already has timezone info (ISO string with Z or offset), return as-is
+    const isoStr = dt.toISOString();
+    if (isoStr.includes('Z') || isoStr.match(/[+-]\d{2}:\d{2}$/)) {
+      return dt;
+    }
+
+    // If useTz=true, treat as UTC
+    if (this.isUseTzEnabled()) {
+      // Parse as UTC by appending Z
+      const str = dt.toISOString().replace('Z', '');
+      return new Date(str + 'Z');
+    }
+
+    // If useTz=false, treat as local time
+    return dt;
+  }
+
+  /**
+   * Convert a timezone-aware datetime to naive datetime.
+   * Strips timezone information, keeping the same wall-clock time.
+   *
+   * @param {Date} dt - timezone-aware datetime
+   * @returns {Date} naive datetime
+   */
+  static makeNaive(dt) {
+    if (!(dt instanceof Date)) {
+      throw new TypeError('makeNaive() requires a Date object');
+    }
+
+    // Create a new Date with the same components but no timezone
+    const year = dt.getUTCFullYear();
+    const month = dt.getUTCMonth();
+    const day = dt.getUTCDate();
+    const hours = dt.getUTCHours();
+    const minutes = dt.getUTCMinutes();
+    const seconds = dt.getUTCSeconds();
+    const ms = dt.getUTCMilliseconds();
+
+    return new Date(year, month, day, hours, minutes, seconds, ms);
+  }
+
+  /**
+   * Get the configured timezone from config/app.js.
+   *
+   * @returns {string} timezone (e.g., 'UTC', 'Africa/Nairobi')
+   */
+  static getTimezone() {
+    try {
+      const appConfig = require(process.cwd() + '/config/app.js');
+      return appConfig.timezone || 'UTC';
+    } catch {
+      return 'UTC';
+    }
+  }
+
+  /**
+   * Check if USE_TZ is enabled (timezone awareness).
+   *
+   * @returns {boolean}
+   */
+  static isUseTzEnabled() {
+    try {
+      const appConfig = require(process.cwd() + '/config/app.js');
+      return appConfig.useTz !== false; // Default to true
+    } catch {
+      return true;
+    }
+  }
+
+  /**
+   * Format a datetime for display in the configured timezone.
+   *
+   * @param {Date} dt - datetime to format
+   * @param {string} format - format string (default: ISO)
+   * @returns {string} formatted datetime
+   */
+  static format(dt, format = 'iso') {
+    if (!(dt instanceof Date)) {
+      throw new TypeError('format() requires a Date object');
+    }
+
+    const local = this.localtime(dt);
+
+    switch (format) {
+      case 'iso':
+        return local.toISOString();
+      case 'date':
+        return local.toISOString().split('T')[0];
+      case 'time':
+        return local.toISOString().split('T')[1].split('.')[0];
+      case 'datetime':
+        return local.toISOString().replace('T', ' ').split('.')[0];
+      default:
+        return local.toISOString();
+    }
+  }
+
+  /**
+   * Parse a datetime string, treating it as UTC if useTz=true.
+   *
+   * @param {string} str - datetime string
+   * @returns {Date} parsed datetime
+   */
+  static parse(str) {
+    if (typeof str !== 'string') {
+      throw new TypeError('parse() requires a string');
+    }
+
+    // If already has timezone info, parse normally
+    if (str.includes('Z') || str.match(/[+-]\d{2}:\d{2}$/)) {
+      return new Date(str);
+    }
+
+    // If useTz=true, treat as UTC
+    if (this.isUseTzEnabled()) {
+      return new Date(str + 'Z');
+    }
+
+    // If useTz=false, parse as local time
+    return new Date(str);
+  }
+}
+
+module.exports = Time;