odac 1.4.0 → 1.4.1

package/docs/ai/skills/frontend/forms.md

@@ -1,3 +1,10 @@
+---
+name: frontend-forms-api-skill
+description: AJAX form and API request patterns in odac.js for interactive UX and predictable frontend data flows.
+metadata:
+  tags: frontend, forms, ajax, api-requests, odac-get, odac-post
+---
+
 # Frontend Forms & API Skill
 
 Handling AJAX form submissions and API requests.

package/docs/ai/skills/frontend/navigation.md

@@ -1,3 +1,10 @@
+---
+name: frontend-navigation-spa-skill
+description: Single-page navigation patterns in odac.js for smooth transitions, route control, and lifecycle-safe execution.
+metadata:
+  tags: frontend, navigation, spa, ajax-navigation, page-lifecycle, transitions
+---
+
 # Frontend Navigation & SPA Skill
 
 Smooth transitions and single-page application behavior using `odac.js`.

package/docs/ai/skills/frontend/realtime.md

@@ -1,3 +1,10 @@
+---
+name: frontend-realtime-websocket-skill
+description: Realtime frontend communication patterns in odac.js using shared WebSockets, SSE, and resilient reconnect behavior.
+metadata:
+  tags: frontend, realtime, websocket, sse, sharedworker, auto-reconnect
+---
+
 # Frontend Realtime & WebSocket Skill
 
 Real-time bidirectional communication and server-sent events with high efficiency.

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

@@ -1,48 +1,269 @@
-# Code-First Migrations
+# Schema-First Migrations
 
-Migration files are great, but sometimes (especially in rapid development or zero-config apps) you want dependencies to define their own table structures automatically.
+ODAC uses a **declarative, schema-first** approach to database migrations. Instead of writing sequential migration files, you define the **desired final state** of each table in a schema file. The engine automatically diffs the schema against your database and applies the necessary changes.
 
-ODAC uses the `.schema()` helper for this logic.
+> **AI Agent Friendly:** A single schema file per table = instant understanding of the final database state. No need to scan hundreds of migration files.
 
-## Ensuring Tables Exist
+---
 
-The `.schema()` method checks if a table exists. If it **does not exist**, it runs the provided callback to create it. If it **already exists**, it does nothing.
+## Quick Start
+
+### 1. Define Your Schema
+
+Create a file in the `schema/` directory for each table:
+
+```javascript
+// schema/users.js
+'use strict'
+
+module.exports = {
+  columns: {
+    id:         {type: 'increments'},
+    name:       {type: 'string', length: 255, nullable: false},
+    email:      {type: 'string', length: 255, nullable: false},
+    role:       {type: 'enum', values: ['admin', 'user'], default: 'user'},
+    is_active:  {type: 'boolean', default: true},
+    timestamps: {type: 'timestamps'}
+  },
+
+  indexes: [
+    {columns: ['email'], unique: true},
+    {columns: ['role', 'is_active']}
+  ]
+}
+```
+
+### 2. Start Your App
+
+Migrations run **automatically** when the application starts. No manual commands needed:
+
+```bash
+npx odac dev    # Development
+npx odac start  # Production
+```
+
+On startup, the engine detects `schema/users.js`, creates the table, and applies indexes — all before the server accepts traffic.
+
+> **Zero-Config:** Just define the schema file and deploy. The framework handles the rest.
+
+You can also run migrations manually via CLI for inspection or rollback:
+
+### 3. Modify Your Schema
+
+Simply edit the schema file. Add a column, remove a column, add an index — the engine handles the rest:
+
+```javascript
+// schema/users.js — added 'bio' column, removed 'is_active'
+module.exports = {
+  columns: {
+    id:         {type: 'increments'},
+    name:       {type: 'string', length: 255, nullable: false},
+    email:      {type: 'string', length: 255, nullable: false},
+    role:       {type: 'enum', values: ['admin', 'user'], default: 'user'},
+    bio:        {type: 'text', nullable: true},
+    timestamps: {type: 'timestamps'}
+  },
+
+  indexes: [
+    {columns: ['email'], unique: true}
+  ]
+}
+```
+
+```bash
+npx odac migrate
+```
+
+```
+  [default]
+    + ADD COLUMN users.bio
+    - DROP COLUMN users.is_active
+    - DROP INDEX users (role, is_active)
+
+✅ 3 operation(s) completed.
+```
+
+---
+
+## Column Types
+
+| Type | Usage | Options |
+|------|-------|---------|
+| `increments` | Auto-increment primary key | — |
+| `bigIncrements` | Big auto-increment | — |
+| `integer` | Integer | `unsigned` |
+| `bigInteger` | Big integer | `unsigned` |
+| `float` | Floating point | `precision`, `scale` |
+| `decimal` | Exact decimal | `precision`, `scale` |
+| `string` | Varchar | `length` (default: 255) |
+| `text` | Text blob | `textType` ('text', 'mediumtext', 'longtext') |
+| `boolean` | Boolean | — |
+| `date` | Date only | — |
+| `datetime` | Date and time | — |
+| `timestamp` | Timestamp | — |
+| `timestamps` | Virtual: creates `created_at` + `updated_at` | — |
+| `time` | Time only | — |
+| `binary` | Binary data | `length` |
+| `json` | JSON | — |
+| `jsonb` | Binary JSON (PostgreSQL) | — |
+| `uuid` | UUID | — |
+| `enum` | Enumeration | `values` (array) |
+
+## Column Modifiers
+
+```javascript
+{
+  type: 'string',
+  length: 100,
+  nullable: false,        // NOT NULL constraint
+  default: 'untitled',    // Default value
+  unsigned: true,         // Unsigned integer
+  unique: true,           // Unique constraint (inline)
+  primary: true,          // Primary key
+  comment: 'The title',   // Column comment
+  references: {           // Foreign key
+    table: 'categories',
+    column: 'id'
+  },
+  onDelete: 'CASCADE',
+  onUpdate: 'CASCADE'
+}
+```
+
+---
+
+## Seed Data
+
+Schema files can include declarative seed data that is applied idempotently on every migration:
 
 ```javascript
-// Ensure 'products' table exists on the fly
-await Odac.DB.products.schema(t => {
-   t.increments('id');
-   t.string('name').notNullable();
-   t.decimal('price', 10, 2);
-   t.boolean('is_active').defaultTo(true);
-   
-   // Automatic timestamps (created_at, updated_at)
-   t.timestamps(true, true);
-});
-```
-
-The `t` argument is a Schema Builder. You can define columns using standard types like:
-- `t.string()`
-- `t.integer()`
-- `t.boolean()`
-- `t.text()`
-- `t.date()`
-- `t.json()`
-
-## Usage Example
-
-A typical pattern is to define schemas in your module's initialization or before the first insert.
+// schema/roles.js
+module.exports = {
+  columns: {
+    id:    {type: 'increments'},
+    name:  {type: 'string', length: 50},
+    level: {type: 'integer', default: 0}
+  },
+
+  indexes: [],
+
+  seed: [
+    {name: 'admin', level: 100},
+    {name: 'editor', level: 50},
+    {name: 'user', level: 1}
+  ],
+  seedKey: 'name'
+}
+```
+
+- **`seed`** — Array of rows to ensure exist
+- **`seedKey`** — Column used for uniqueness check (required when `seed` is present)
+
+**Behavior:** If the row exists (matched by `seedKey`), it updates if values differ. If not, it inserts. Safe to run repeatedly.
+
+---
+
+## Data Migrations
+
+For **one-time data transformations** (splitting columns, backfilling, etc.), use imperative migration files:
+
+```
+migration/
+  20260225_001_split_names.js
+```
 
 ```javascript
-// In your controller or module
-async function init() {
-    await Odac.DB.logs.schema(t => {
-        t.string('level');
-        t.text('message');
-        t.timestamps();
-    });
+// migration/20260225_001_split_names.js
+module.exports = {
+  async up(db) {
+    const users = await db('users').select('id', 'full_name')
+    for (const user of users) {
+      const [first, ...rest] = user.full_name.split(' ')
+      await db('users').where('id', user.id).update({
+        first_name: first,
+        last_name: rest.join(' ')
+      })
+    }
+  },
+
+  async down(db) {
+    const users = await db('users').select('id', 'first_name', 'last_name')
+    for (const user of users) {
+      await db('users').where('id', user.id).update({
+        full_name: `${user.first_name} ${user.last_name}`
+      })
+    }
+  }
+}
+```
+
+Migration files run **once** and are tracked in the `_odac_migrations` table.
+
+---
+
+## Multiple Databases
+
+If your project has multiple database connections, organize schemas by connection:
+
+```
+schema/
+  users.js              ← default connection
+  posts.js              ← default connection
+  analytics/            ← 'analytics' connection
+    events.js
+    pageviews.js
+```
+
+The folder name matches the connection key in your `odac.json`:
+
+```json
+{
+  "database": {
+    "default": {"type": "mysql", "database": "main_db"},
+    "analytics": {"type": "postgres", "database": "analytics_db"}
+  }
 }
+```
+
+Migration files follow the same convention:
+
+```
+migration/
+  20260225_001_auto.js          ← default connection
+  analytics/
+    20260225_001_backfill.js    ← analytics connection
+```
+
+---
+
+## CLI Commands
 
-// Later...
-await Odac.DB.logs.insert({ level: 'info', message: 'App started' });
+```bash
+# Run all pending migrations (schema diff + files + seeds)
+npx odac migrate
+
+# Target a specific database connection
+npx odac migrate --db=analytics
+
+# Show pending changes without applying (dry-run)
+npx odac migrate:status
+
+# Rollback the last batch of migration files
+npx odac migrate:rollback
+
+# Reverse-engineer current database into schema/ files
+npx odac migrate:snapshot
+npx odac migrate:snapshot --db=analytics
+```
+
+---
+
+## Snapshot — Importing Existing Databases
+
+For existing projects, use `migrate:snapshot` to generate schema files from your current database:
+
+```bash
+npx odac migrate:snapshot
 ```
+
+This creates a schema file for each table. Review and adjust the generated files, then use them as your source of truth going forward.

package/package.json

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

package/src/Auth.js

@@ -140,30 +140,54 @@ class Auth {
       this.#user = await Odac.DB[this.#table].where(primaryKey, sql_token[0].user).first()
       if (!this.#user) return false
 
+      let triggerRotation = false
+      let isRecoveryRotation = false
+
       if (!isRotated) {
         if (shouldRotate && tokenAge > rotationAge) {
-          // --- Token Rotation ---
-          const newTokenX = nodeCrypto.randomBytes(32).toString('hex')
-          const newTokenY = nodeCrypto.randomBytes(32).toString('hex')
-          const newToken = {
-            id: Odac.DB.nanoid(),
-            user: sql_token[0].user,
-            token_x: newTokenX,
-            token_y: Odac.Var(newTokenY).hash(),
-            browser: sql_token[0].browser,
-            ip: this.#request.ip,
-            date: new Date(),
-            active: new Date()
-          }
+          triggerRotation = true
+        } else if (inactiveAge > updateAge) {
+          // Fallback simple active update if rotation is not triggered
+          Odac.DB[tokenTable]
+            .where('id', sql_token[0].id)
+            .update({active: new Date()})
+            .catch(() => {})
+        }
+      } else {
+        // Client still presenting a rotated (grace period) token.
+        // 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) {
+          triggerRotation = true
+          isRecoveryRotation = true
+        }
+      }
 
-          // 1. Persist new token (await to ensure it exists before client uses new cookies)
-          const insertOk = await Odac.DB[tokenTable].insert(newToken).catch(e => {
-            console.error('Odac Auth Error: Token rotation failed', e.message)
-            return false
-          })
+      if (triggerRotation) {
+        // --- Token Rotation ---
+        const newTokenX = nodeCrypto.randomBytes(32).toString('hex')
+        const newTokenY = nodeCrypto.randomBytes(32).toString('hex')
+        const newToken = {
+          id: Odac.DB.nanoid(),
+          user: sql_token[0].user,
+          token_x: newTokenX,
+          token_y: Odac.Var(newTokenY).hash(),
+          browser: sql_token[0].browser,
+          ip: this.#request.ip,
+          date: new Date(),
+          active: new Date()
+        }
+
+        // 1. Persist new token (await to ensure it exists before client uses new cookies)
+        const insertOk = await Odac.DB[tokenTable].insert(newToken).catch(e => {
+          console.error('Odac Auth Error: Token rotation failed', e.message)
+          return false
+        })
 
-          if (insertOk !== false) {
-            // 2. Mark old token as rotated and set exactly 60 seconds grace period
+        if (insertOk !== false) {
+          if (!isRecoveryRotation) {
+            // 2a. Normal rotation: Mark old token as rotated with 60s grace period
             // Non-blocking I/O (Fire & Forget) -> High Throughput
             const rotatedActiveDate = new Date(now - maxAge + TOKEN_ROTATION_GRACE_PERIOD_MS)
             const epochDate = new Date(0)
@@ -175,27 +199,29 @@ class Auth {
                 date: epochDate
               })
               .catch(() => {})
-
-            // 3. Issue new cookies immediately
-            this.#request.cookie('odac_x', newTokenX, {
-              httpOnly: true,
-              secure: true,
-              sameSite: 'Lax',
-              maxAge: maxAge
-            })
-            this.#request.cookie('odac_y', newTokenY, {
-              httpOnly: true,
-              secure: true,
-              sameSite: 'Lax',
-              maxAge: maxAge
-            })
+          } else {
+            // 2b. Recovery rotation: Delete old rotated token immediately.
+            // Why: Prevents unbounded token multiplication. The old token already
+            // had its grace period; one recovery attempt is the maximum.
+            Odac.DB[tokenTable]
+              .where('id', sql_token[0].id)
+              .delete()
+              .catch(() => {})
           }
-        } else if (inactiveAge > updateAge) {
-          // Fallback simple active update if rotation is not triggered
-          Odac.DB[tokenTable]
-            .where('id', sql_token[0].id)
-            .update({active: new Date()})
-            .catch(() => {})
+
+          // 3. Issue new cookies immediately
+          this.#request.cookie('odac_x', newTokenX, {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'Lax',
+            'max-age': Math.floor(maxAge / 1000)
+          })
+          this.#request.cookie('odac_y', newTokenY, {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'Lax',
+            'max-age': Math.floor(maxAge / 1000)
+          })
         }
       }
 
@@ -238,13 +264,13 @@ class Auth {
       httpOnly: true,
       secure: true,
       sameSite: 'Lax',
-      maxAge: maxAge
+      'max-age': Math.floor(maxAge / 1000)
     })
     this.#request.cookie('odac_y', token_y, {
       httpOnly: true,
       secure: true,
       sameSite: 'Lax',
-      maxAge: maxAge
+      'max-age': Math.floor(maxAge / 1000)
     })
 
     // Knex insert returns ids on some dbs, promise resolves to result
@@ -392,8 +418,8 @@ class Auth {
       await Odac.DB[tokenTable].where('user', userId).where('browser', browser).delete()
     }
 
-    this.#request.cookie('odac_x', '', {maxAge: -1})
-    this.#request.cookie('odac_y', '', {maxAge: -1})
+    this.#request.cookie('odac_x', '', {'max-age': -1})
+    this.#request.cookie('odac_y', '', {'max-age': -1})
 
     this.#user = null
     return true

package/src/Config.js

@@ -46,7 +46,7 @@ module.exports = {
 
   _interpolate: function (obj) {
     if (typeof obj === 'string') {
-      return obj.replace(/\$\{(\w+)\}/g, (_, key) => {
+      return obj.replace(/\$\{([^{}]+)\}/g, (_, key) => {
         // Special variables
         if (key === 'odac') {
           return __dirname.replace(/\/src$/, '/client')

package/src/Database/ConnectionFactory.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const knex = require('knex')
+
+/**
+ * Resolves knex client driver from ODAC database type.
+ * Why: Keeps connection driver mapping consistent across runtime and CLI migration paths.
+ * @param {string} type Database type from config.
+ * @returns {string} Knex client name.
+ */
+function resolveClient(type) {
+  if (type === 'postgres' || type === 'pg' || type === 'postgresql') return 'pg'
+  if (type === 'sqlite' || type === 'sqlite3') return 'sqlite3'
+  return 'mysql2'
+}
+
+/**
+ * Builds knex connection config from ODAC database node.
+ * Why: Normalizes connection options for all call sites and avoids drift.
+ * @param {object} db Single database config node.
+ * @param {string} client Knex client name.
+ * @returns {object} Knex connection object.
+ */
+function buildConnectionConfig(db, client) {
+  if (client === 'sqlite3') {
+    return {filename: db.filename || db.database || './dev.sqlite3'}
+  }
+
+  return {
+    host: db.host || '127.0.0.1',
+    user: db.user,
+    password: db.password,
+    database: db.database,
+    port: db.port
+  }
+}
+
+/**
+ * Creates knex connections map from ODAC database config.
+ * Why: Centralizes zero-config connection bootstrap used by runtime and migration CLI.
+ * @param {object} databaseConfig ODAC database config (single or multiple).
+ * @returns {Record<string, any>} Knex connections by key.
+ */
+function buildConnections(databaseConfig) {
+  const isMultiple = typeof databaseConfig[Object.keys(databaseConfig)[0]] === 'object'
+  const dbs = isMultiple ? databaseConfig : {default: databaseConfig}
+  const connections = {}
+
+  for (const key of Object.keys(dbs)) {
+    const db = dbs[key]
+    const client = resolveClient(db.type)
+    const connection = buildConnectionConfig(db, client)
+
+    connections[key] = knex({
+      client,
+      connection,
+      pool: {min: 0, max: db.connectionLimit || 10},
+      useNullAsDefault: true
+    })
+  }
+
+  return connections
+}
+
+module.exports = {
+  buildConnections,
+  buildConnectionConfig,
+  resolveClient
+}