odac 1.4.10 → 1.4.12

package/docs/backend/06-request-and-response/03-proxy-cache.md

@@ -0,0 +1,77 @@
+## 🚀 Proxy Cache
+
+`Odac.cache()` lets you tell the ODAC Proxy to cache the current page's HTML response, so repeat visitors get a near-instant response without hitting your application server at all.
+
+> **ODAC Ecosystem Only:** This feature works exclusively within the ODAC ecosystem. It relies on the `X-ODAC-Cache` header that only the ODAC Proxy understands and acts upon.
+
+### Basic Usage
+
+Call `Odac.cache(seconds)` at the top of your controller with a TTL (time-to-live) in seconds:
+
+```javascript
+module.exports = function (Odac) {
+  Odac.cache(3600) // Cache this page for 1 hour
+
+  Odac.set('title', 'About Us')
+  Odac.View.skeleton('main').set('content', 'about')
+}
+```
+
+That's it. The ODAC Proxy handles the rest.
+
+### How It Works
+
+When `Odac.cache(seconds)` is called, ODAC sets two response headers:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `X-ODAC-Cache` | `3600` | Tells the ODAC Proxy to cache this response for the given TTL |
+| `Cache-Control` | `public, max-age=3600` | Standard browser/CDN cache directive |
+
+The ODAC Proxy intercepts the response, stores it, and serves it directly on subsequent requests — bypassing your application entirely until the TTL expires.
+
+### Smart Cache Invalidation
+
+The ODAC Proxy is intelligent about cache invalidation. You don't need to manually clear the cache in most cases:
+
+- **Content changes:** If the underlying page content changes (e.g. a file is updated or a deployment happens), the Proxy detects this and automatically invalidates the cache on the next request.
+- **Dynamic content detection:** If the Proxy detects that a response contains dynamic or user-specific content, it cancels the cache for that response automatically.
+
+### When to Use It
+
+`Odac.cache()` is designed for pages where the HTML output is **identical for all visitors**:
+
+✅ **Good candidates:**
+- Marketing and landing pages
+- Blog posts and articles
+- Documentation pages
+- Product listing pages (without personalization)
+- Static "About", "Contact", "FAQ" pages
+
+❌ **Do not use on:**
+- Pages with user-specific content (dashboards, profiles, account pages)
+- Pages that display session data or authentication state
+- Pages with per-user pricing, recommendations, or notifications
+- Any page where the HTML output differs between users
+
+> Even though the ODAC Proxy can detect dynamic content and cancel caching, you should not rely on this as a safety net. If a page is user-specific, simply don't call `Odac.cache()`.
+
+### TTL Reference
+
+| Scenario | Recommended TTL |
+|----------|----------------|
+| Frequently updated content (news, blog) | `300` – `900` (5–15 min) |
+| Semi-static content (docs, product pages) | `3600` – `86400` (1–24 hrs) |
+| Fully static pages (about, landing) | `86400` – `604800` (1–7 days) |
+
+### Error Handling
+
+`Odac.cache()` throws a `TypeError` if the argument is not a positive integer:
+
+```javascript
+Odac.cache(3600)    // ✅ Valid
+Odac.cache(0)       // ❌ TypeError
+Odac.cache(-1)      // ❌ TypeError
+Odac.cache('3600')  // ❌ TypeError
+Odac.cache(3.5)     // ❌ TypeError
+```

package/docs/backend/07-views/12-scripts-and-typescript.md

@@ -0,0 +1,156 @@
+# 📦 Scripts & TypeScript
+
+ODAC comes with built-in, **Zero-Config** support for frontend JavaScript and TypeScript. Write your scripts in `view/js/`, and ODAC handles transpilation, bundling, minification, and tree-shaking automatically — just like the Tailwind CSS pipeline.
+
+## How it Works
+
+The framework uses [esbuild](https://esbuild.github.io/) under the hood for blazing-fast builds:
+
+1.  **Development (`npm run dev`)**:
+    *   ODAC watches all `.ts`, `.js`, `.mts`, and `.mjs` files in `view/js/`.
+    *   Changes trigger instant rebuilds (sub-millisecond).
+    *   Source maps are enabled for easy debugging.
+
+2.  **Production (`npm run build`)**:
+    *   All entry points are bundled, minified, and tree-shaken.
+    *   Output goes to `public/assets/js/{name}.js`.
+
+3.  **Serving (`npm start`)**:
+    *   The compiled JS files are served statically. No runtime overhead.
+
+## Quick Start
+
+Create a file at **`view/js/app.ts`** (or `app.js` for plain JavaScript):
+
+```typescript
+// view/js/app.ts
+interface User {
+  id: number
+  name: string
+}
+
+const greet = (user: User): string => {
+  return `Hello, ${user.name}!`
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  console.log(greet({ id: 1, name: 'World' }))
+})
+```
+
+That's it. Run `npm run dev` and ODAC compiles it to `public/assets/js/app.js`.
+
+## Entry Points & Imports
+
+Each file in `view/js/` becomes a separate entry point (bundle). You can use standard ES module imports between files:
+
+```
+view/js/
+├── app.ts          → public/assets/js/app.js
+├── admin.ts        → public/assets/js/admin.js
+├── _utils.ts       (ignored — partial/import only)
+└── _api.ts         (ignored — partial/import only)
+```
+
+> **Convention:** Files starting with `_` (underscore) are **not** compiled as entry points. Use them as shared modules that get imported by your entry points.
+
+```typescript
+// view/js/_api.ts (shared module — not compiled on its own)
+export const fetchUsers = async (): Promise<unknown> => {
+  const res = await fetch('/api/users')
+  return res.json()
+}
+```
+
+```typescript
+// view/js/admin.ts (entry point — compiled to admin.js)
+import { fetchUsers } from './_api'
+
+document.addEventListener('DOMContentLoaded', async () => {
+  const users = await fetchUsers()
+  console.log(users)
+})
+```
+
+esbuild bundles the imported code into the final output — no extra network requests.
+
+## TypeScript or JavaScript — Your Choice
+
+ODAC doesn't force TypeScript on you. Both work equally well:
+
+| Extension | Behavior |
+|-----------|----------|
+| `.ts`     | TypeScript with full type-checking support |
+| `.js`     | Plain JavaScript, passed through as-is |
+| `.mts`    | TypeScript with ES module syntax |
+| `.mjs`    | JavaScript with ES module syntax |
+
+## HTML Integration
+
+In your skeleton or layout files, reference the compiled output:
+
+```html
+<script src="/assets/js/app.js"></script>
+```
+
+The default project template already includes this in `skeleton/main.html`.
+
+## Configuration (Optional)
+
+ODAC works with zero configuration, but you can customize the JS pipeline in `odac.json`:
+
+```json
+{
+  "js": {
+    "target": "es2020",
+    "minify": true,
+    "sourcemap": false,
+    "bundle": true,
+    "obfuscate": false
+  }
+}
+```
+
+| Option      | Default    | Description |
+|-------------|------------|-------------|
+| `target`    | `"es2020"` | JavaScript target version (`es2015`, `es2020`, `esnext`, etc.) |
+| `minify`    | `true`     | Enable minification in production builds |
+| `sourcemap` | `false`    | Generate source maps in production (always enabled in dev) |
+| `bundle`    | `true`     | Bundle imported modules into a single file |
+| `obfuscate` | `false`    | Code obfuscation level (`false`, `true`/`"low"`, `"medium"`, `"high"`) |
+
+## Obfuscation
+
+ODAC supports three levels of code obfuscation for production builds. Obfuscation is disabled by default and only applied during `odac build` — development mode is never obfuscated.
+
+### Levels
+
+| Level    | What it does |
+|----------|-------------|
+| `false`  | No obfuscation. Standard minification only. |
+| `true` / `"low"` | Mangles properties starting with `_` (private-by-convention). |
+| `"medium"` | Low + drops `debugger` statements + removes `console.debug` and `console.trace`. |
+| `"high"` | Maximum — mangles `_` and `$` prefixed properties, drops all `console.*` calls and `debugger` statements. |
+
+### Example
+
+```json
+{
+  "js": {
+    "obfuscate": "medium"
+  }
+}
+```
+
+> **Tip:** Start with `"low"` or `"medium"`. The `"high"` level mangles `$`-prefixed properties which may break code that interacts with external libraries using `$` conventions (e.g., jQuery, some frameworks). Test thoroughly before deploying with `"high"`.
+
+## What You Get
+
+- **TypeScript Support** — Write type-safe frontend code without any setup
+- **Bundling** — `import`/`export` between files, everything merged into one output
+- **Minification** — Whitespace removal, variable shortening, dead code elimination
+- **Tree-Shaking** — Unused exports are automatically removed
+- **Obfuscation** — Optional property mangling and console stripping (3 levels)
+- **Source Maps** — Enabled in development for easy debugging
+- **Multiple Entry Points** — Separate bundles for different pages/sections
+- **Sub-millisecond Rebuilds** — esbuild's native speed keeps your dev loop instant

package/docs/backend/08-database/01-getting-started.md

@@ -66,6 +66,17 @@ You can configure multiple database connections. The connection named `default`
 }
 ```
 
+To use a named connection in your code, simply access it through `Odac.DB`:
+
+```javascript
+// Primary database (default)
+const users = await Odac.DB.users.where('active', true)
+
+// Analytics database
+const logs = await Odac.DB.analytics.events.insert({ type: 'login' })
+```
+
+
 ---
 
 ## Environment Variables

package/docs/backend/10-authentication/04-odac-register-forms.md

@@ -8,7 +8,8 @@ The `<odac:register>` component provides a zero-configuration way to create secu
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",
@@ -54,7 +55,8 @@ If you want to customize table names or primary key:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",
@@ -468,11 +470,12 @@ This provides instant feedback to users before form submission.
 
 ### Required Configuration
 
-Only MySQL configuration is required:
+Only database configuration is required:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",

package/docs/backend/10-authentication/06-odac-login-forms.md

@@ -8,7 +8,8 @@ The `<odac:login>` component provides a zero-configuration way to create secure
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",
@@ -47,7 +48,8 @@ If you want to customize table names or primary key:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",
@@ -428,11 +430,12 @@ input._odac_error {
 
 ### Required Configuration
 
-Only MySQL configuration is required:
+Only database configuration is required:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "",

package/docs/index.json

@@ -165,6 +165,10 @@
         {
           "file": "02-sending-a-response-replying-to-the-user.md",
           "title": "Response Object"
+        },
+        {
+          "file": "03-proxy-cache.md",
+          "title": "Proxy Cache"
         }
       ]
     },
@@ -215,6 +219,10 @@
         {
           "file": "10-styling-and-tailwind.md",
           "title": "Styling & Tailwind CSS"
+        },
+        {
+          "file": "12-scripts-and-typescript.md",
+          "title": "Scripts & TypeScript"
         }
       ]
     },

package/eslint.config.mjs

@@ -38,7 +38,7 @@ export default defineConfig([
   },
   {
     files: ['template/**/*.js'],
-    ignores: ['template/public/**/*.js'],
+    ignores: ['template/public/**/*.js', 'template/view/js/**/*.js'],
     languageOptions: {
       globals: {
         ...globals.node,
@@ -56,6 +56,25 @@ export default defineConfig([
       'prettier/prettier': 'error'
     }
   },
+  {
+    files: ['template/view/js/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        Odac: 'readonly'
+      },
+      sourceType: 'script'
+    },
+    plugins: {
+      js,
+      prettier: prettierPlugin
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error'
+    }
+  },
   {
     files: ['template/public/**/*.js'],
     languageOptions: {

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.10",
+  "version": "1.4.12",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@tailwindcss/cli": "^4.1.18",
+    "esbuild": "^0.25.12",
     "knex": "^3.1.0",
     "lmdb": "^3.4.4",
     "tailwindcss": "^4.1.18"

package/src/Config.js

@@ -27,6 +27,13 @@ module.exports = {
     driver: 'memory',
     redis: 'default'
   },
+  js: {
+    target: 'es2020',
+    minify: true,
+    sourcemap: false,
+    bundle: true,
+    obfuscate: false
+  },
   debug: process.env.NODE_ENV !== 'production',
 
   init: function () {

package/src/Database/Migration.js

@@ -681,7 +681,7 @@ class Migration {
    */
   async _createTable(knex, tableName, schema) {
     await knex.schema.createTable(tableName, table => {
-      this._buildColumns(table, schema.columns)
+      this._buildColumns(knex, table, schema.columns)
       this._buildIndexes(table, schema.indexes)
     })
   }
@@ -716,13 +716,13 @@ class Migration {
         for (const op of batchOps) {
           switch (op.type) {
             case 'add_column':
-              this._addColumn(table, op.column, op.definition)
+              this._addColumn(knex, table, op.column, op.definition)
               break
             case 'drop_column':
               table.dropColumn(op.column)
               break
             case 'alter_column':
-              this._alterColumn(table, op.column, op.definition, op.currentNullable)
+              this._alterColumn(knex, table, op.column, op.definition, op.currentNullable)
               break
           }
         }
@@ -739,8 +739,9 @@ class Migration {
 
       // Apply default value change if specified
       if (op.definition.default !== undefined) {
-        if (op.definition.default === 'now()') {
-          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT now()`, [tableName, op.column])
+        const lower = String(op.definition.default).toLowerCase().trim()
+        if (lower === 'now()' || lower === 'current_timestamp' || lower === 'current_timestamp()') {
+          await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT ${lower}`, [tableName, op.column])
         } else {
           await knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? SET DEFAULT ?`, [tableName, op.column, op.definition.default])
         }
@@ -915,7 +916,27 @@ class Migration {
    * @param {object} table - Knex TableBuilder instance
    * @param {object} columns - Column definition map
    */
-  _buildColumns(table, columns) {
+  /**
+   * Resolves a column default value, wrapping special SQL keywords in knex.raw().
+   * Why: Knex.defaultTo() quotes string values by default. For keywords like
+   * CURRENT_TIMESTAMP, this results in 'CURRENT_TIMESTAMP' which MySQL rejects.
+   * Wrapping in knex.raw() ensures the keyword is emitted without quotes.
+   * @param {object} knex - Knex instance
+   * @param {*} value - Raw default value from schema
+   * @returns {*} Resolved value (possibly knex.raw)
+   */
+  _resolveDefault(knex, value) {
+    if (typeof value !== 'string') return value
+
+    const lower = value.toLowerCase().trim()
+    if (lower === 'current_timestamp' || lower === 'current_timestamp()' || lower === 'now()') {
+      return knex.raw(value)
+    }
+
+    return value
+  }
+
+  _buildColumns(knex, table, columns) {
     if (!columns) return
 
     for (const [colName, def] of Object.entries(columns)) {
@@ -930,7 +951,7 @@ class Migration {
       if (def.nullable === false) col.notNullable()
       else if (def.nullable === true) col.nullable()
 
-      if (def.default !== undefined) col.defaultTo(def.default)
+      if (def.default !== undefined) col.defaultTo(this._resolveDefault(knex, def.default))
       if (def.unsigned) col.unsigned()
       // Column-level unique is handled via _normalizeSchema → _buildIndexes.
       // Applying it here as well would create duplicate constraints.
@@ -1019,14 +1040,14 @@ class Migration {
    * @param {string} colName - Column name
    * @param {object} def - Column definition
    */
-  _addColumn(table, colName, def) {
+  _addColumn(knex, table, colName, def) {
     const col = this._createColumnBuilder(table, colName, def)
     if (!col) return
 
     if (def.nullable === false) col.notNullable()
     else col.nullable()
 
-    if (def.default !== undefined) col.defaultTo(def.default)
+    if (def.default !== undefined) col.defaultTo(this._resolveDefault(knex, def.default))
     if (def.unsigned) col.unsigned()
     if (def.references) col.references(def.references.column).inTable(def.references.table)
     if (def.onDelete) col.onDelete(def.onDelete)
@@ -1039,7 +1060,7 @@ class Migration {
    * @param {string} colName - Column name
    * @param {object} def - Column definition
    */
-  _alterColumn(table, colName, def, currentNullable) {
+  _alterColumn(knex, table, colName, def, currentNullable) {
     const col = this._createColumnBuilder(table, colName, def)
     if (!col) return
 
@@ -1052,7 +1073,7 @@ class Migration {
     else if (currentNullable === false) col.notNullable()
     else if (currentNullable === true) col.nullable()
 
-    if (def.default !== undefined) col.defaultTo(def.default)
+    if (def.default !== undefined) col.defaultTo(this._resolveDefault(knex, def.default))
 
     col.alter()
   }

package/src/Mail.js

@@ -317,6 +317,62 @@ class Mail {
     return '=?UTF-8?B?' + Buffer.from(text).toString('base64') + '?='
   }
 
+  #wrapLines(content, limit = 76) {
+    if (!content) return ''
+    const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+    const out = []
+    for (const line of normalized.split('\n')) {
+      if (Buffer.byteLength(line, 'utf8') <= limit) {
+        out.push(line)
+        continue
+      }
+      let buf = ''
+      let bufBytes = 0
+      const flush = () => {
+        if (buf.length) out.push(buf)
+        buf = ''
+        bufBytes = 0
+      }
+      for (const word of line.split(/(\s+)/)) {
+        if (!word) continue
+        const wordBytes = Buffer.byteLength(word, 'utf8')
+        if (bufBytes + wordBytes <= limit) {
+          buf += word
+          bufBytes += wordBytes
+          continue
+        }
+        if (buf.length && /^\s+$/.test(word)) {
+          flush()
+          continue
+        }
+        if (buf.length) flush()
+        if (wordBytes <= limit) {
+          buf = word
+          bufBytes = wordBytes
+          continue
+        }
+        let chunk = ''
+        let chunkBytes = 0
+        for (const ch of word) {
+          const chBytes = Buffer.byteLength(ch, 'utf8')
+          if (chunkBytes + chBytes > limit) {
+            out.push(chunk)
+            chunk = ''
+            chunkBytes = 0
+          }
+          chunk += ch
+          chunkBytes += chBytes
+        }
+        if (chunk.length) {
+          buf = chunk
+          bufBytes = chunkBytes
+        }
+      }
+      flush()
+    }
+    return out.join('\r\n')
+  }
+
   #stripHtml(html) {
     if (!html) return ''
 
@@ -376,6 +432,11 @@ class Mail {
             }
           }
 
+          // RFC 5321 §4.5.3.1.6: SMTP lines must be ≤1000 octets including CRLF.
+          // Wrap to 990 chars for HTML and 76 for text to prevent SMTP rejection.
+          htmlContent = this.#wrapLines(htmlContent, 990)
+          textContent = this.#wrapLines(textContent)
+
           if (!this.#header['From']) this.#header['From'] = `${this.#encode(this.#from.name)} <${this.#from.email}>`
           if (!this.#header['To']) {
             const t = this.#to.value[0]

package/src/Odac.js

@@ -156,6 +156,9 @@ module.exports = {
         _odac.write = function (value) {
           return _odac.Request.write(value)
         }
+        _odac.cache = function (seconds) {
+          return _odac.Request.cache(seconds)
+        }
         _odac.stream = function (input) {
           _odac.Request.clearTimeout()
           return new (require('./Stream'))(_odac.Request.req, _odac.Request.res, input, _odac)

package/src/Request.js

@@ -310,6 +310,27 @@ class OdacRequest {
     }
   }
 
+  // - SET PROXY CACHE
+  /**
+   * Enables ODAC Proxy caching for the current response.
+   * Sets the X-ODAC-Cache header with the specified TTL (in seconds)
+   * and updates Cache-Control to allow proxy caching.
+   *
+   * Why: Allows controllers to declaratively opt-in to proxy-level
+   * caching for static or semi-static HTML responses, offloading
+   * repeated rendering from the application server.
+   *
+   * @param {number} seconds - Cache TTL in seconds (must be a positive integer)
+   * @throws {TypeError} If seconds is not a positive integer
+   */
+  cache(seconds) {
+    if (!Number.isInteger(seconds) || seconds < 1) {
+      throw new TypeError('Odac.cache() requires a positive integer (seconds)')
+    }
+    this.header('X-ODAC-Cache', seconds)
+    this.header('Cache-Control', `public, max-age=${seconds}`)
+  }
+
   // - HTTP CODE
   status(code) {
     this.#status = code

package/src/Route/Cron.js

@@ -104,6 +104,15 @@ class Cron {
     }
   }
 
+  /**
+   * Removes all cron jobs registered from a given route file.
+   * Called before hot-reloading a route file to prevent duplicate cron registrations.
+   */
+  clear(route) {
+    if (!route) return
+    this.#jobs = this.#jobs.filter(job => job.route !== route)
+  }
+
   job(controller) {
     let path
     if (typeof controller !== 'function') {
@@ -114,6 +123,7 @@ class Cron {
       }
     }
     this.#jobs.push({
+      route: global.Odac?.Route?.buff || null,
       controller: typeof controller === 'function' ? null : controller,
       lastRun: null,
       condition: [],

package/src/Route.js

@@ -452,6 +452,7 @@ class Route {
 
         if (!routes2[Odac.Route.buff] || routes2[Odac.Route.buff] < mtime - 1000) {
           delete require.cache[require.resolve(filePath)]
+          Cron.clear(Odac.Route.buff)
           routes2[Odac.Route.buff] = mtime
           const routeModule = require(filePath)
           if (typeof routeModule === 'function') {