odac 1.4.1 → 1.4.2

package/docs/backend/08-database/02-basics.md

@@ -118,19 +118,59 @@ await Odac.DB.users.where('id', 1).delete();
 
 ODAC includes a built-in helper for generating robust, unique string IDs (NanoID) without needing external packages. Secure, URL-friendly, and collision-resistant.
 
+### Automatic Generation (Recommended)
+
+When you define a column as `type: 'nanoid'` in your schema file, ODAC **automatically generates** the ID on every `insert()` — no manual code needed.
+
+**Schema definition:**
 ```javascript
-// Generate a standard 21-character ID (e.g., "V1StGXR8_Z5jdHi6B-myT")
-const id = Odac.DB.nanoid();
+// schema/posts.js
+module.exports = {
+  columns: {
+    id: { type: 'nanoid', primary: true },
+    title: { type: 'string', length: 255 }
+  }
+}
+```
 
-// Generate a custom length ID
-const shortId = Odac.DB.nanoid(10);
+**Usage — just insert, the ID is auto-generated:**
+```javascript
+await Odac.DB.posts.insert({ title: 'My First Post' });
+// → { id: 'V1StGXR8Z5jdHi6BmyTa', title: 'My First Post' }
 ```
 
-This is particularly useful when inserting records into tables that use string-based Primary Keys instead of auto-increment integers.
+This works for single inserts and bulk inserts. If you provide an `id` explicitly, the auto-generation is skipped.
 
 ```javascript
-await Odac.DB.posts.insert({
-    id: Odac.DB.nanoid(),
-    title: 'My First Post'
-});
+// Bulk insert — each row gets its own unique nanoid
+await Odac.DB.posts.insert([
+    { title: 'Post A' },
+    { title: 'Post B' }
+]);
+
+// Explicit ID — auto-generation is skipped
+await Odac.DB.posts.insert({ id: 'my-custom-id', title: 'Custom' });
+```
+
+You can also customize the ID length:
+```javascript
+// schema/codes.js
+module.exports = {
+  columns: {
+    code: { type: 'nanoid', length: 8, primary: true },
+    label: { type: 'string' }
+  }
+}
+```
+
+### Manual Generation
+
+You can also generate NanoIDs manually when needed:
+
+```javascript
+// Generate a standard 21-character ID
+const id = Odac.DB.nanoid();
+
+// Generate a custom length ID
+const shortId = Odac.DB.nanoid(10);
 ```

package/docs/backend/08-database/04-migrations.md

@@ -91,6 +91,7 @@ npx odac migrate
 |------|-------|---------|
 | `increments` | Auto-increment primary key | — |
 | `bigIncrements` | Big auto-increment | — |
+| `nanoid` | NanoID string key (auto-generated on insert) | `length` (default: 21) |
 | `integer` | Integer | `unsigned` |
 | `bigInteger` | Big integer | `unsigned` |
 | `float` | Floating point | `precision`, `scale` |

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.1",
+  "version": "1.4.2",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/Auth.js

@@ -143,9 +143,22 @@ class Auth {
       let triggerRotation = false
       let isRecoveryRotation = false
 
+      // WebSocket connections (res === null) cannot deliver Set-Cookie headers.
+      // Rotating a token during a WS upgrade would invalidate the browser's cookies
+      // with no way to deliver replacements, causing silent logout on the next HTTP request.
+      const canDeliverCookies = !!this.#request.res
+
       if (!isRotated) {
         if (shouldRotate && tokenAge > rotationAge) {
-          triggerRotation = true
+          if (canDeliverCookies) {
+            triggerRotation = true
+          } else {
+            // WebSocket: Can't deliver rotated cookies, refresh active timestamp instead
+            Odac.DB[tokenTable]
+              .where('id', sql_token[0].id)
+              .update({active: new Date()})
+              .catch(() => {})
+          }
         } else if (inactiveAge > updateAge) {
           // Fallback simple active update if rotation is not triggered
           Odac.DB[tokenTable]
@@ -158,7 +171,7 @@ class Auth {
         // This means the previous rotation response was lost (network hiccup, page navigation, etc.)
         // Give the client one more chance by re-issuing new credentials.
         const timeSinceRotation = inactiveAge - maxAge + TOKEN_ROTATION_GRACE_PERIOD_MS
-        if (timeSinceRotation > 5000) {
+        if (timeSinceRotation > 5000 && canDeliverCookies) {
           triggerRotation = true
           isRecoveryRotation = true
         }

package/src/Database/ConnectionFactory.js

@@ -57,6 +57,7 @@ function buildConnections(databaseConfig) {
       pool: {min: 0, max: db.connectionLimit || 10},
       useNullAsDefault: true
     })
+    connections[key]._odacConnectionKey = key
   }
 
   return connections

package/src/Database/Migration.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const nanoid = require('./nanoid')
 
 /**
  * ODAC Migration Engine — "Schema-First with Auto-Diff"
@@ -213,7 +214,8 @@ class Migration {
 
     for (const [colName, colDef] of Object.entries(columns)) {
       if (!colDef.unique) continue
-      if (colDef.type === 'timestamps' || colDef.type === 'increments' || colDef.type === 'bigIncrements') continue
+      if (colDef.type === 'timestamps' || colDef.type === 'increments' || colDef.type === 'bigIncrements' || colDef.type === 'nanoid')
+        continue
 
       const implicitIdx = {columns: [colName], unique: true}
       const sig = this._indexSignature(implicitIdx)
@@ -678,6 +680,8 @@ class Migration {
         return table.json(colName)
       case 'jsonb':
         return table.jsonb(colName)
+      case 'nanoid':
+        return table.string(colName, def.length || 21)
       case 'uuid':
         return table.uuid(colName)
       case 'enum':
@@ -905,6 +909,9 @@ class Migration {
         const existing = await knex(tableName).where(seedKey, keyValue).first()
 
         if (!existing) {
+          // Auto-generate nanoid for columns with type 'nanoid' that are missing from seed data
+          this._fillNanoidColumns(preparedRow, schema)
+
           if (!dryRun) {
             await knex(tableName).insert(preparedRow)
           }
@@ -1198,6 +1205,24 @@ class Migration {
       table.index(['connection', 'type'])
     })
   }
+
+  /**
+   * Populates missing nanoid columns in a data row before insertion.
+   * Why: Zero-config DX — developers should not manually call nanoid() for every insert.
+   * When a schema defines a column as type 'nanoid', the framework auto-generates
+   * the value if the caller did not provide one.
+   * @param {object} row - Data row to mutate in-place
+   * @param {object} schema - Table schema definition
+   */
+  _fillNanoidColumns(row, schema) {
+    const columns = schema.columns || {}
+
+    for (const [colName, colDef] of Object.entries(columns)) {
+      if (colDef.type === 'nanoid' && !row[colName]) {
+        row[colName] = nanoid(colDef.length || 21)
+      }
+    }
+  }
 }
 
 module.exports = new Migration()

package/src/Database/nanoid.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const nodeCrypto = require('node:crypto')
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+
+/**
+ * Generates a cryptographically secure, URL-safe alphanumeric NanoID.
+ * Why: Centralized implementation shared by Database.js and Migration.js
+ * to avoid code duplication. Uses rejection sampling on crypto.randomBytes
+ * for uniform distribution across a 62-character alphabet.
+ * @param {number} size - Desired ID length (default: 21)
+ * @returns {string} URL-safe alphanumeric ID
+ */
+function nanoid(size = 21) {
+  let id = ''
+  while (id.length < size) {
+    const bytes = nodeCrypto.randomBytes(size + 5)
+    for (let i = 0; i < bytes.length; i++) {
+      const byte = bytes[i] & 63
+      if (byte < 62) {
+        id += ALPHABET[byte]
+        if (id.length === size) break
+      }
+    }
+  }
+  return id
+}
+
+module.exports = nanoid

package/src/Database.js

@@ -1,9 +1,12 @@
 'use strict'
 const {buildConnections} = require('./Database/ConnectionFactory')
+const nanoid = require('./Database/nanoid')
 
 class DatabaseManager {
   constructor() {
     this.connections = {}
+    /** @type {Object<string, Object<string, Array<{column: string, size: number}>>>} connectionKey -> tableName -> nanoid columns */
+    this._nanoidColumns = {}
   }
 
   async init() {
@@ -24,6 +27,10 @@ class DatabaseManager {
     // Auto-migrate: sync schema/ files with the database on every startup.
     // Why: Zero-config philosophy — deploy and forget. The app always starts with the correct DB state.
     await this._autoMigrate()
+
+    // Cache nanoid column metadata from schema files for insert-time auto-generation.
+    // Runs on ALL processes (primary + workers) since every process may insert data.
+    this._loadNanoidMeta()
   }
 
   /**
@@ -54,21 +61,92 @@ class DatabaseManager {
     }
   }
 
+  /**
+   * Gracefully destroys all active database connections.
+   * Called during shutdown to release connection pools and prevent resource leaks.
+   */
+  async close() {
+    const entries = Object.entries(this.connections)
+    if (entries.length === 0) return
+
+    await Promise.allSettled(
+      entries.map(([name, knex]) =>
+        knex.destroy().catch(err => {
+          console.error(`\x1b[31m[Database]\x1b[0m Failed to close '${name}' connection:`, err.message)
+        })
+      )
+    )
+    this.connections = {}
+  }
+
   nanoid(size = 21) {
-    const nodeCrypto = require('crypto')
-    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
-    let id = ''
-    while (id.length < size) {
-      const bytes = nodeCrypto.randomBytes(size + 5)
-      for (let i = 0; i < bytes.length; i++) {
-        const byte = bytes[i] & 63
-        if (byte < 62) {
-          id += alphabet[byte]
-          if (id.length === size) break
+    return nanoid(size)
+  }
+
+  /**
+   * Scans schema/ directory and caches which columns are type 'nanoid' per table.
+   * Why: The insert() proxy needs O(1) lookup to auto-generate IDs at runtime.
+   * Lightweight — only reads file metadata, no DB introspection.
+   */
+  _loadNanoidMeta() {
+    const fs = require('node:fs')
+    const path = require('node:path')
+    const Module = require('node:module')
+
+    if (!global.__dir) return
+    const schemaDir = path.join(global.__dir, 'schema')
+    if (!fs.existsSync(schemaDir)) return
+
+    const loadDir = (dir, connectionKey) => {
+      if (!this._nanoidColumns[connectionKey]) {
+        this._nanoidColumns[connectionKey] = {}
+      }
+
+      const files = fs.readdirSync(dir).filter(f => f.endsWith('.js') && fs.statSync(path.join(dir, f)).isFile())
+
+      for (const file of files) {
+        const filePath = path.join(dir, file)
+        const tableName = path.basename(file, '.js')
+
+        try {
+          const source = fs.readFileSync(filePath, 'utf8')
+          const m = new Module(filePath)
+          m.filename = filePath
+          m.paths = Module._nodeModulePaths(path.dirname(filePath))
+          m._compile(source, filePath)
+          const schema = m.exports
+
+          if (!schema?.columns) continue
+
+          const nanoidCols = []
+          for (const [colName, colDef] of Object.entries(schema.columns)) {
+            if (colDef.type === 'nanoid') {
+              nanoidCols.push({column: colName, size: colDef.length || 21})
+            }
+          }
+
+          if (nanoidCols.length > 0) {
+            this._nanoidColumns[connectionKey][tableName] = nanoidCols
+          }
+        } catch (e) {
+          // Schema file parse error — skip silently, Migration will report it
+          if (global.Odac?.Config?.debug) {
+            console.warn(`\x1b[33m[ODAC NanoID Meta]\x1b[0m Failed to parse schema ${filePath}:`, e.message)
+          }
         }
       }
     }
-    return id
+
+    // Root-level files (default connection)
+    loadDir(schemaDir, 'default')
+
+    // Subdirectories (named connections)
+    const entries = fs.readdirSync(schemaDir, {withFileTypes: true})
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        loadDir(path.join(schemaDir, entry.name), entry.name)
+      }
+    }
   }
 }
 
@@ -104,6 +182,28 @@ const tableProxyHandler = {
       return originalCount.apply(this, args)
     }
 
+    // Odac DX Improvement: Auto-generate NanoID for columns defined as type 'nanoid' in schema.
+    // Why: Zero-config ID generation — no manual Odac.DB.nanoid() calls needed.
+    const connectionKey = knexInstance._odacConnectionKey || 'default'
+    const nanoidCols = manager._nanoidColumns[connectionKey]?.[prop]
+    if (nanoidCols) {
+      const originalInsert = qb.insert
+      qb.insert = function (data, ...args) {
+        if (Array.isArray(data)) {
+          for (const row of data) {
+            for (const {column, size} of nanoidCols) {
+              if (!row[column]) row[column] = manager.nanoid(size)
+            }
+          }
+        } else if (data && typeof data === 'object') {
+          for (const {column, size} of nanoidCols) {
+            if (!data[column]) data[column] = manager.nanoid(size)
+          }
+        }
+        return originalInsert.call(this, data, ...args)
+      }
+    }
+
     const originalThen = qb.then
     qb.then = function (resolve, reject) {
       if (this._odacIsCount) {
@@ -152,7 +252,10 @@ const rootProxy = new Proxy(manager, {
   get(target, prop) {
     // Access to internal manager methods
     if (prop === 'init') return target.init.bind(target)
+    if (prop === 'close') return target.close.bind(target)
     if (prop === 'connections') return target.connections
+    if (prop === '_nanoidColumns') return target._nanoidColumns
+    if (prop === '_loadNanoidMeta') return target._loadNanoidMeta.bind(target)
 
     // Access to specific database connection: Odac.DB.analytics
     if (target.connections[prop]) {
@@ -182,6 +285,14 @@ const rootProxy = new Proxy(manager, {
     }
 
     return undefined
+  },
+
+  set(target, prop, value) {
+    if (prop === 'connections' || prop === '_nanoidColumns') {
+      target[prop] = value
+      return true
+    }
+    return false
   }
 })
 

package/src/Ipc.js

@@ -269,6 +269,43 @@ class Ipc extends EventEmitter {
     interval.unref()
   }
 
+  /**
+   * Tears down IPC resources. For Redis driver, disconnects clients.
+   * For memory driver, clears stores and removes cluster listeners.
+   */
+  async close() {
+    if (this.config.driver === 'redis') {
+      if (this.subRedis) {
+        await this.subRedis.quit().catch(() => {})
+        this.subRedis = null
+      }
+      if (this.redis) {
+        await this.redis.quit().catch(() => {})
+        this.redis = null
+      }
+    } else if (cluster.isPrimary) {
+      if (global.__odac_ipc_message_handler) {
+        cluster.removeListener('message', global.__odac_ipc_message_handler)
+        global.__odac_ipc_message_handler = null
+      }
+      if (global.__odac_ipc_exit_handler) {
+        cluster.removeListener('exit', global.__odac_ipc_exit_handler)
+        global.__odac_ipc_exit_handler = null
+      }
+      if (this._memoryStore) this._memoryStore.clear()
+      if (this._memorySubs) this._memorySubs.clear()
+    } else {
+      // Worker: reject all pending requests so they don't hang
+      for (const req of this._requests.values()) {
+        clearTimeout(req.timeout)
+        req.reject(new Error('IPC shutting down'))
+      }
+      this._requests.clear()
+      this._subs.clear()
+    }
+    this.initialized = false
+  }
+
   _handlePrimaryMessage(worker, msg) {
     const {type, id, key, value, ttl, channel, message} = msg
     const action = type.replace('ipc:', '')

package/src/Odac.js

@@ -149,7 +149,7 @@ module.exports = {
           return hash ? _odac.Token.check(hash) : _odac.Token.generate()
         }
         _odac.validator = function () {
-          return new (require('./Validator.js'))(_odac.Request)
+          return new (require('./Validator.js'))(_odac.Request, _odac)
         }
         _odac.write = function (value) {
           return _odac.Request.write(value)

package/src/Route/Cron.js

@@ -12,6 +12,17 @@ class Cron {
     }
   }
 
+  /**
+   * Stops the cron scheduler. Called during graceful shutdown to prevent
+   * new cron jobs from firing while the process is terminating.
+   */
+  stop() {
+    if (this.#interval) {
+      clearInterval(this.#interval)
+      this.#interval = null
+    }
+  }
+
   check() {
     const now = new Date()
     const minute = now.getMinutes()

package/src/Route.js

@@ -806,6 +806,14 @@ class Route {
     return Cron.job(controller)
   }
 
+  /**
+   * Stops the cron scheduler during graceful shutdown.
+   * Prevents new cron jobs from spawning while the process is terminating.
+   */
+  stopCron() {
+    Cron.stop()
+  }
+
   ws(path, handler, options = {}) {
     this.setWs('ws', path, handler, options)
     return this

package/src/Server.js

@@ -33,36 +33,73 @@ module.exports = {
         }
       })
 
-      // Graceful shutdown handler for primary
-      const gracefulShutdown = signal => {
+      /**
+       * GRACEFUL SHUTDOWN — PRIMARY PROCESS
+       * ────────────────────────────────────
+       * Shutdown order (deterministic, sequential):
+       *   1. Stop accepting new work       → Cron, session GC
+       *   2. Drain active workers           → send 'shutdown', disconnect, wait
+       *   3. Release shared resources       → IPC, Database, Storage
+       *   4. Exit 0
+       *
+       * A 30-second hard timeout protects against hung workers or I/O.
+       */
+      const gracefulShutdown = async signal => {
         if (isShuttingDown) return
         isShuttingDown = true
 
         console.log(`\n\x1b[33m[Shutdown]\x1b[0m ${signal} received, shutting down gracefully...`)
 
-        // Disconnect all workers
-        for (const id in cluster.workers) {
-          cluster.workers[id].send('shutdown')
-          cluster.workers[id].disconnect()
-        }
+        // Force exit safety net — must be set immediately
+        const forceTimer = setTimeout(() => {
+          console.error('\x1b[31m[Shutdown]\x1b[0m Timeout! Forcing exit...')
+          process.exit(1)
+        }, 30000)
+        forceTimer.unref()
 
-        let workersAlive = Object.keys(cluster.workers).length
+        // Phase 1: Stop schedulers so no new work is queued
+        Odac.Route.stopCron()
+        Odac.Storage.stopSessionGC()
 
-        cluster.on('exit', () => {
-          workersAlive--
-          if (workersAlive === 0) {
-            console.log('\x1b[32m[Shutdown]\x1b[0m All workers stopped.')
-            Odac.Storage.close()
-            console.log('\x1b[32m[Shutdown]\x1b[0m Storage closed. Goodbye!')
-            process.exit(0)
+        // Phase 2: Gracefully drain all workers
+        await new Promise(resolve => {
+          const workerIds = Object.keys(cluster.workers)
+          let workersAlive = workerIds.length
+
+          if (workersAlive === 0) return resolve()
+
+          cluster.on('exit', () => {
+            workersAlive--
+            if (workersAlive <= 0) resolve()
+          })
+
+          for (const id of workerIds) {
+            const worker = cluster.workers[id]
+            if (worker) {
+              worker.send('shutdown')
+              worker.disconnect()
+            }
           }
         })
 
-        // Force exit after 30 seconds
-        setTimeout(() => {
-          console.error('\x1b[31m[Shutdown]\x1b[0m Timeout! Forcing exit...')
-          process.exit(1)
-        }, 30000)
+        console.log('\x1b[32m[Shutdown]\x1b[0m All workers stopped.')
+
+        // Phase 3: Release shared resources (order matters: IPC → DB → Storage)
+        try {
+          await Odac.Ipc.close()
+        } catch (e) {
+          console.error(`\x1b[31m[Shutdown]\x1b[0m Error closing IPC: ${e.message}`)
+        }
+        try {
+          await Odac.Database.close()
+        } catch (e) {
+          console.error(`\x1b[31m[Shutdown]\x1b[0m Error closing Database: ${e.message}`)
+        }
+        Odac.Storage.close()
+
+        console.log('\x1b[32m[Shutdown]\x1b[0m Resources released. Goodbye!')
+        clearTimeout(forceTimer)
+        process.exit(0)
       }
 
       process.on('SIGTERM', () => gracefulShutdown('SIGTERM'))
@@ -113,11 +150,28 @@ module.exports = {
 
       server.listen(port)
 
-      // Graceful shutdown handler for worker
-      process.on('message', msg => {
+      /**
+       * GRACEFUL SHUTDOWN — WORKER PROCESS
+       * ──────────────────────────────────
+       * 1. Stop accepting new connections  (server.close)
+       * 2. Release worker-scoped resources (IPC pending requests, DB pools)
+       * 3. Exit 0
+       */
+      process.on('message', async msg => {
         if (msg === 'shutdown') {
           console.log(`\x1b[36m[Worker ${process.pid}]\x1b[0m Closing server...`)
-          server.close(() => {
+
+          server.close(async () => {
+            try {
+              await Odac.Ipc.close()
+            } catch {
+              /* best-effort */
+            }
+            try {
+              await Odac.Database.close()
+            } catch {
+              /* best-effort */
+            }
             console.log(`\x1b[36m[Worker ${process.pid}]\x1b[0m Server closed.`)
             process.exit(0)
           })

package/src/Storage.js

@@ -5,6 +5,7 @@ class OdacStorage {
   constructor() {
     this.db = null
     this.ready = false
+    this.gcInterval = null
   }
 
   init() {
@@ -72,10 +73,14 @@ class OdacStorage {
       return null
     }
 
+    if (this.gcInterval) {
+      clearInterval(this.gcInterval)
+    }
+
     const BATCH_THRESHOLD = 10000
     const BATCH_SIZE = 1000
 
-    return setInterval(() => {
+    this.gcInterval = setInterval(() => {
       try {
         // Count sessions to decide mode
         let sessionCount = 0
@@ -94,6 +99,15 @@ class OdacStorage {
         console.error('\x1b[31m[Storage GC Error]\x1b[0m', error.message)
       }
     }, intervalMs)
+
+    return this.gcInterval
+  }
+
+  stopSessionGC() {
+    if (this.gcInterval) {
+      clearInterval(this.gcInterval)
+      this.gcInterval = null
+    }
   }
 
   // Simple mode: Load all sessions at once (fast for small datasets)