odac 1.4.10 → 1.4.12

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+### 📚 Documentation
+
+- refactor database configuration to a unified structure and document multi-connection support
+
+### 🛠️ Fixes & Improvements
+
+- **mail:** add line wrapping for email content to comply with SMTP standards
+- **mail:** use 990-char wrap for HTML, 76 for text; trim migration defaults
+- **route:** hot-reload cron fix
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ✨ What's New
+
+- add esbuild-powered JS/TS frontend pipeline
+- **cache:** add proxy cache support with Odac.cache() method
+
+### 🛠️ Fixes & Improvements
+
+- **frontend:** enforce pipeline .js output, handle watcher rejections and skip esbuild directory scans
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### 🛠️ Fixes & Improvements
 
 - **cache:** preserve Knex chain for insert operations during invalidation

package/bin/odac.js

@@ -141,6 +141,195 @@ function getTailwindConfigs() {
   return configs
 }
 
+/**
+ * Resolves JS/TS entry points from 'view/js' and returns esbuild-compatible configs.
+ * Supports multiple entry points: each .js/.ts/.mjs/.mts file in view/js/ becomes a separate bundle.
+ * Why: Mirrors the Tailwind CSS pipeline pattern for zero-config frontend asset compilation.
+ * @returns {Array<{ input: string, output: string, name: string }>}
+ */
+function getJsConfigs() {
+  const jsDir = path.join(process.cwd(), 'view/js')
+  const outputDir = path.join(process.cwd(), 'public/assets/js')
+  const configs = []
+
+  if (!fs.existsSync(jsDir) || !fs.lstatSync(jsDir).isDirectory()) return configs
+
+  const validExtensions = ['.ts', '.js', '.mts', '.mjs']
+  const files = fs.readdirSync(jsDir).filter(file => {
+    const fullPath = path.join(jsDir, file)
+    if (!fs.lstatSync(fullPath).isFile()) return false
+    const ext = path.extname(file).toLowerCase()
+    return validExtensions.includes(ext) && !file.startsWith('_')
+  })
+
+  fs.mkdirSync(outputDir, {recursive: true})
+
+  for (const file of files) {
+    const input = path.join(jsDir, file)
+    const baseName = path.basename(file, path.extname(file))
+    const output = path.join(outputDir, `${baseName}.js`)
+
+    configs.push({input, output, name: file})
+  }
+
+  return configs
+}
+
+/**
+ * Reads the project's odac.json and returns the js pipeline configuration.
+ * Merges user config with sensible defaults for zero-config operation.
+ * @returns {{ target: string, minify: boolean, sourcemap: boolean, bundle: boolean, obfuscate: boolean|string }}
+ */
+function getJsPipelineOptions() {
+  const configPath = path.join(process.cwd(), 'odac.json')
+  const defaults = {
+    target: 'es2020',
+    minify: true,
+    sourcemap: false,
+    bundle: true,
+    obfuscate: false
+  }
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+      if (config.js && typeof config.js === 'object') {
+        return {...defaults, ...config.js}
+      }
+    }
+  } catch {
+    // Config read failure is non-fatal; use defaults
+  }
+
+  return defaults
+}
+
+/**
+ * Resolves esbuild mangle/obfuscation options based on the obfuscate config level.
+ * Why: Provides lightweight code obfuscation without external dependencies by leveraging
+ * esbuild's built-in property mangling and identifier minification capabilities.
+ *
+ * Levels:
+ * - false (default): No obfuscation, only standard minification.
+ * - true / "low": Mangles properties starting with _ (private-by-convention).
+ * - "medium": Mangles _ properties + top-level names + applies aggressive mangling.
+ * - "high": Maximum obfuscation — mangles all properties matching common patterns,
+ *           drops console/debugger, and rewrites identifiers aggressively.
+ *
+ * @param {boolean|string} level Obfuscation level
+ * @returns {object} esbuild-compatible options to spread into the build config
+ */
+function getObfuscationOptions(level) {
+  if (!level) return {}
+
+  const normalized = level === true ? 'low' : String(level).toLowerCase()
+
+  if (normalized === 'low') {
+    return {
+      mangleProps: /^_/
+    }
+  }
+
+  if (normalized === 'medium') {
+    return {
+      mangleProps: /^_/,
+      drop: ['debugger'],
+      pure: ['console.debug', 'console.trace']
+    }
+  }
+
+  if (normalized === 'high') {
+    return {
+      mangleProps: /^[_$]/,
+      drop: ['debugger', 'console'],
+      legalComments: 'none',
+      keepNames: false
+    }
+  }
+
+  return {}
+}
+
+/**
+ * Builds JS/TS entry points using esbuild.
+ * Why: Provides TypeScript transpilation, bundling, minification, and tree-shaking in a single pass.
+ * @param {Array<{ input: string, output: string, name: string }>} configs Entry point configurations
+ * @param {{ target: string, minify: boolean, sourcemap: boolean, bundle: boolean }} options Build options
+ * @param {boolean} [production=false] Whether to enable production optimizations
+ * @returns {Promise<boolean>} True if all builds succeeded
+ */
+async function buildJs(configs, options, production = false) {
+  if (configs.length === 0) return true
+
+  const esbuild = require('esbuild')
+  const obfuscation = production ? getObfuscationOptions(options.obfuscate) : {}
+  let hasError = false
+
+  const buildPromises = configs.map(async ({input, output, name}) => {
+    try {
+      await esbuild.build({
+        entryPoints: [input],
+        outfile: output,
+        bundle: options.bundle,
+        minify: production ? true : options.minify,
+        sourcemap: options.sourcemap,
+        target: options.target,
+        platform: 'browser',
+        format: 'iife',
+        treeShaking: true,
+        legalComments: 'none',
+        logLevel: 'warning',
+        ...obfuscation
+      })
+    } catch (err) {
+      console.error(`❌ \x1b[31m[ODAC Script Error]\x1b[0m Build failed for ${name}:`, err.message)
+      hasError = true
+    }
+  })
+
+  await Promise.all(buildPromises)
+  return !hasError
+}
+
+/**
+ * Starts esbuild watch contexts for JS/TS entry points.
+ * Why: Provides instant rebuilds during development, matching the Tailwind CSS watcher pattern.
+ * @param {Array<{ input: string, output: string, name: string }>} configs Entry point configurations
+ * @param {{ target: string, minify: boolean, sourcemap: boolean, bundle: boolean }} options Build options
+ * @returns {Promise<Array<{ dispose: Function }>>} Array of esbuild watch contexts for cleanup
+ */
+async function watchJs(configs, options) {
+  if (configs.length === 0) return []
+
+  const esbuild = require('esbuild')
+  const contexts = []
+
+  for (const {input, output, name} of configs) {
+    try {
+      const ctx = await esbuild.context({
+        entryPoints: [input],
+        outfile: output,
+        bundle: options.bundle,
+        minify: false,
+        sourcemap: true,
+        target: options.target,
+        platform: 'browser',
+        format: 'iife',
+        treeShaking: false,
+        legalComments: 'none',
+        logLevel: 'warning'
+      })
+
+      await ctx.watch()
+      contexts.push(ctx)
+    } catch (err) {
+      console.error(`❌ \x1b[31m[ODAC Script Error]\x1b[0m Watch failed for ${name}:`, err.message)
+    }
+  }
+
+  return contexts
+}
+
 /**
  * Manages the AI Agent skills synchronization.
  * @param {string} targetDir The directory to sync skills into.
@@ -529,6 +718,31 @@ async function run() {
       process.on('SIGINT', cleanup)
       process.on('SIGTERM', cleanup)
       process.on('exit', cleanup)
+
+      // JS/TS Pipeline — esbuild watch mode
+      const jsConfigs = getJsConfigs()
+      if (jsConfigs.length > 0) {
+        const jsOptions = getJsPipelineOptions()
+        const jsNames = jsConfigs.map(c => c.name).join(', ')
+        console.log(`📦 \x1b[36mODAC Scripts:\x1b[0m Watching for changes (${jsNames})`)
+
+        watchJs(jsConfigs, jsOptions)
+          .then(contexts => {
+            const jsCleanup = () => {
+              contexts.forEach(ctx => {
+                try {
+                  ctx.dispose()
+                } catch {}
+              })
+            }
+            process.on('SIGINT', jsCleanup)
+            process.on('SIGTERM', jsCleanup)
+            process.on('exit', jsCleanup)
+          })
+          .catch(err => {
+            console.error(`❌ \x1b[31m[ODAC Script Error]\x1b[0m Failed to initialize JS watcher:`, err.message)
+          })
+      }
     }
 
     require('../index.js')
@@ -554,7 +768,22 @@ async function run() {
     if (hasError) {
       process.exit(1)
     } else {
-      console.log('✅ All builds completed successfully!')
+      console.log('✅ All CSS builds completed successfully!')
+    }
+
+    // JS/TS Pipeline — production build with minification and tree-shaking
+    const jsConfigs = getJsConfigs()
+    if (jsConfigs.length > 0) {
+      const jsOptions = getJsPipelineOptions()
+      const jsNames = jsConfigs.map(c => c.name).join(', ')
+      console.log(`📦 Compiling scripts (${jsNames})...`)
+
+      const jsSuccess = await buildJs(jsConfigs, jsOptions, true)
+      if (!jsSuccess) {
+        process.exit(1)
+      } else {
+        console.log('✅ All script builds completed successfully!')
+      }
     }
   } else if (command === 'start') {
     process.env.NODE_ENV = 'production'

package/docs/ai/skills/SKILL.md

@@ -20,16 +20,17 @@ Read the specific rule files based on whether you are working on the Backend or
 - [backend/cron.md](backend/cron.md) - Scheduled background tasks and automation
 - [backend/database.md](backend/database.md) - Query Builder, Write-Behind Cache, and DB best practices
 - [backend/forms.md](backend/forms.md) - Form processing and Validation logic
+- [backend/image-processing.md](backend/image-processing.md) - High-performance server-side image manipulation
 - [backend/ipc.md](backend/ipc.md) - Inter-Process Communication and state sharing
 - [backend/mail.md](backend/mail.md) - Transactional email sending
 - [backend/migrations.md](backend/migrations.md) - Schema-first, auto-run, cluster-safe DB migrations
+- [backend/odac-var.md](backend/odac-var.md) - Odac.Var (Fluent String Manipulation, Hashing, Encryption)
 - [backend/request_response.md](backend/request_response.md) - Handling Odac.Request and Odac.Response
 - [backend/routing.md](backend/routing.md) - Route definitions, Middlewares, and Error Pages
 - [backend/storage.md](backend/storage.md) - Persistent key-value storage (LMDB)
 - [backend/streaming.md](backend/streaming.md) - Server-Sent Events (SSE) and Streaming API
 - [backend/structure.md](backend/structure.md) - Project organization and Service Classes
 - [backend/translations.md](backend/translations.md) - Multi-language support (i18n)
-- [backend/odac-var.md](backend/odac-var.md) - Odac.Var (Fluent String Manipulation, Hashing, Encryption)
 - [backend/utilities.md](backend/utilities.md) - Flow Control (abort, direct, session)
 - [backend/validation.md](backend/validation.md) - Input sanitization and security checks
 - [backend/views.md](backend/views.md) - Template syntax, skeletons, and server-side JS
@@ -39,3 +40,4 @@ Read the specific rule files based on whether you are working on the Backend or
 - [frontend/forms.md](frontend/forms.md) - AJAX form handling and API requests
 - [frontend/navigation.md](frontend/navigation.md) - AJAX Navigation (SPA) behavior
 - [frontend/realtime.md](frontend/realtime.md) - WebSocket Hubs and EventSource usage
+- [frontend/scripts.md](frontend/scripts.md) - esbuild-powered JS/TS frontend pipeline

package/docs/ai/skills/backend/config.md

@@ -30,10 +30,30 @@ const apiKey = Odac.env('API_KEY');
 ### 2. odac.json Structure
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "${DB_HOST}",
     "password": "${DB_PASSWORD}"
   },
   "debug": true
 }
 ```
+
+### 3. Multiple Databases
+```json
+{
+  "database": {
+    "default": {
+      "type": "mysql",
+      "database": "main_app"
+    },
+    "analytics": {
+      "type": "postgres",
+      "host": "analytics.local",
+      "database": "events"
+    }
+  }
+}
+```
+
+Access via: `Odac.DB.analytics.tableName`

package/docs/ai/skills/backend/database.md

@@ -16,6 +16,46 @@ High-performance database operations using the ODAC Query Builder, Read-Through
 4.  **Read Caching**: Use `cache()` for frequently-read, rarely-changed data.
 5.  **Write Coalescing**: Use `buffer` for high-frequency writes to avoid DB saturation.
 
+## Database Configuration (`odac.json`)
+
+ODAC connects to databases automatically based on the `database` key in `odac.json`.
+
+### 1. Single Connection
+```json
+{
+  "database": {
+    "type": "mysql",
+    "host": "${DB_HOST}",
+    "user": "${DB_USER}",
+    "password": "${DB_PASSWORD}",
+    "database": "myapp"
+  }
+}
+```
+
+### 2. Multiple Connections
+Define named objects. The one named `default` (or the first one) is used by default.
+```json
+{
+  "database": {
+    "default": {
+      "type": "mysql",
+      "database": "app_db"
+    },
+    "analytics": {
+      "type": "postgres",
+      "host": "remote-stats.db",
+      "database": "events"
+    }
+  }
+}
+```
+
+Access named connections via: `Odac.DB.analytics.tableName`
+
+### 3. Environment Variables
+Always use `${VAR_NAME}` for sensitive credentials. Map them in `.env`.
+
 ## Query Builder Patterns
 ```javascript
 const user = await Odac.DB.users

package/docs/ai/skills/backend/request_response.md

@@ -2,7 +2,7 @@
 name: backend-request-response-skill
 description: ODAC request parsing and response composition patterns for consistent, secure, and predictable API behavior.
 metadata:
-  tags: backend, request, response, headers, status-codes, json, api
+  tags: backend, request, response, headers, status-codes, json, api, cache, proxy
 ---
 
 # Backend Request & Response Skill
@@ -40,3 +40,23 @@ module.exports = function(Odac) {
   return "Raw text response";
 };
 ```
+
+### 3. Proxy Cache Control
+Enable ODAC Proxy caching for static or semi-static page responses. Sets `X-ODAC-Cache` and `Cache-Control` headers automatically.
+
+**ODAC Ecosystem Only** — requires the ODAC Proxy. Has no effect in standalone deployments.
+
+```javascript
+module.exports = function(Odac) {
+  Odac.cache(3600) // Cache for 1 hour
+  Odac.View.skeleton('main').set('content', 'about')
+}
+```
+
+**Rules:**
+- `Odac.cache(seconds)` — positive integer only. Throws `TypeError` otherwise.
+- Overrides any previously set `Cache-Control` header for the request.
+- **ODAC Proxy is smart:** automatically invalidates cache when content changes or dynamic content is detected.
+- **Despite smart invalidation, never use on:** user-specific pages (dashboards, profiles, account pages), pages with session data, auth state, or per-user content. Do not rely on auto-detection as a safety net.
+
+**Good candidates:** marketing pages, blog posts, docs, product listings (no personalization), static pages (about, FAQ, contact).

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

@@ -0,0 +1,36 @@
+---
+name: frontend-scripts-typescript-skill
+description: ODAC frontend JS/TS pipeline guidelines for writing, bundling, and optimizing client-side scripts using esbuild.
+metadata:
+  tags: frontend, javascript, typescript, esbuild, bundling, minification, tree-shaking, scripts, assets
+---
+
+# Frontend Scripts & TypeScript Skill
+
+Zero-config frontend asset pipeline powered by esbuild for TypeScript transpilation, bundling, minification, and tree-shaking.
+
+## Core Rules
+1.  **Entry Points**: Place `.ts`, `.js`, `.mts`, or `.mjs` files in `view/js/`. Each becomes a separate bundle.
+2.  **Partials Convention**: Files starting with `_` (e.g., `_utils.ts`) are ignored as entry points — use them as shared imports only.
+3.  **Output Path**: Compiled files go to `public/assets/js/{name}.js`.
+4.  **No TypeScript Enforcement**: Both TypeScript and plain JavaScript are supported equally.
+5.  **Import Resolution**: Use standard ES module `import`/`export` between files. esbuild bundles everything into a single output per entry point.
+6.  **Configuration**: Optional `js` key in `odac.json` for `target`, `minify`, `sourcemap`, and `bundle` settings.
+
+## Development vs Production
+- **`odac dev`**: Watch mode with source maps, no minification, instant rebuilds.
+- **`odac build`**: Full minification, tree-shaking, and dead code elimination.
+
+## Example Structure
+```
+view/js/
+├── app.ts          → public/assets/js/app.js
+├── admin.ts        → public/assets/js/admin.js
+├── _api.ts         (shared module, not compiled)
+└── _utils.ts       (shared module, not compiled)
+```
+
+## HTML Integration
+```html
+<script src="/assets/js/app.js"></script>
+```

package/docs/backend/03-config/00-configuration-overview.md

@@ -12,7 +12,8 @@ The main configuration file located in your website's root directory. This file
   "request": {
     "timeout": 30000
   },
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "secret123",
@@ -38,7 +39,8 @@ Perfect for development or non-sensitive settings:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "password": "dev123"
   }
@@ -50,7 +52,8 @@ Use `${VARIABLE}` syntax in `odac.json` to reference `.env` values:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "${MYSQL_HOST}",
     "password": "${MYSQL_PASSWORD}"
   }
@@ -68,7 +71,8 @@ Combine both methods - use direct values for non-sensitive data and environment
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "${MYSQL_PASSWORD}",
@@ -88,7 +92,7 @@ You can access configuration values in three ways:
 
 ```javascript
 // 1. From Odac.Config (recommended for structured config)
-const dbHost = Odac.Config.mysql.host
+const dbHost = Odac.Config.database.host
 
 // 2. Using Odac.env() helper
 const apiKey = Odac.env('API_KEY')
@@ -130,6 +134,7 @@ const nodeEnv = process.env.NODE_ENV
 ```json
 {
   "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "${MYSQL_PASSWORD}",
@@ -161,6 +166,19 @@ const nodeEnv = process.env.NODE_ENV
 }
 ```
 
+**Scripts (JS/TS Pipeline):**
+```json
+{
+  "js": {
+    "target": "es2020",
+    "minify": true,
+    "sourcemap": false,
+    "bundle": true,
+    "obfuscate": false
+  }
+}
+```
+
 **Debug Mode:**
 Enable verbose logging for development. This helps in troubleshooting by inspecting detailed logs for system actions like sending emails (e.g., SMTP connection details, server responses). Default is `false`.
 
@@ -182,7 +200,8 @@ See individual documentation sections for detailed configuration options.
   "request": {
     "timeout": 30000
   },
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "${MYSQL_HOST}",
     "user": "${MYSQL_USER}",
     "password": "${MYSQL_PASSWORD}",

package/docs/backend/03-config/01-database-connection.md

@@ -1,12 +1,13 @@
 ## 🔌 Database Connection
 
-When you add a `mysql` object to your `odac.json`, the system will automatically connect to your MySQL database. No separate connection setup is needed in your code.
+When you add a `database` object to your `odac.json`, the system will automatically connect to your database. No separate connection setup is needed in your code.
 
 ### Basic Configuration
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "your_user",
     "password": "your_password",
@@ -24,7 +25,8 @@ For better security, especially in production, you can use environment variables
 **odac.json:**
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "${MYSQL_HOST}",
     "user": "${MYSQL_USER}",
     "password": "${MYSQL_PASSWORD}",
@@ -48,7 +50,8 @@ You can also mix direct values with environment variables:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "localhost",
     "user": "root",
     "password": "${MYSQL_PASSWORD}",
@@ -58,3 +61,37 @@ You can also mix direct values with environment variables:
 ```
 
 This way, non-sensitive values are directly in the config while passwords remain in the `.env` file.
+
+### Multiple Database Connections
+
+ODAC supports multiple simultaneous database connections. You can define them as named objects within the `database` configuration:
+
+```json
+{
+  "database": {
+    "default": {
+      "type": "mysql",
+      "host": "localhost",
+      "database": "app_db"
+    },
+    "analytics": {
+      "type": "postgres",
+      "host": "remote-stats.db",
+      "database": "events"
+    }
+  }
+}
+```
+
+#### Usage in Code
+
+To use a specific connection, access it by its name via `Odac.DB`:
+
+```javascript
+// Uses 'default' connection
+const users = await Odac.DB.users.select('*')
+
+// Uses 'analytics' connection
+const events = await Odac.DB.analytics.pageviews.select('*')
+```
+

package/docs/backend/03-config/04-environment-variables.md

@@ -43,7 +43,8 @@ Reference environment variables using `${VARIABLE_NAME}` syntax:
 
 ```json
 {
-  "mysql": {
+  "database": {
+    "type": "mysql",
     "host": "${MYSQL_HOST}",
     "user": "${MYSQL_USER}",
     "password": "${MYSQL_PASSWORD}",
@@ -95,7 +96,7 @@ module.exports = function() {
 
 ```javascript
 module.exports = function() {
-  const dbHost = Odac.Config.mysql.host
+  const dbHost = Odac.Config.database.host
   const apiKey = Odac.Config.api.stripe.key
 }
 ```