odac 1.4.13 → 1.4.14

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 ### 🛠️ Fixes & Improvements
 
+- **docs:** update frontend scripts documentation to include code obfuscation details and enhance clarity
+- **form:** add escapeHtmlPreservingTemplates method to handle template tokens
+- **route:** enhance error handling to support object responses in error method
+- **view:** use escapeHtmlPreservingTemplates consistently for form attributes
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 🛠️ Fixes & Improvements
+
 - **form:** enhance form handling with metadata and improved parsing logic
 - **form:** implement token rotation on successful form submissions
 - **view:** prevent script injection and handle escaped quotes in form configs

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

@@ -1,36 +1,92 @@
 ---
 name: frontend-scripts-typescript-skill
-description: ODAC frontend JS/TS pipeline guidelines for writing, bundling, and optimizing client-side scripts using esbuild.
+description: ODAC frontend JS/TS pipeline guidelines for writing, bundling, and optimizing client-side scripts using esbuild and code obfuscation.
 metadata:
-  tags: frontend, javascript, typescript, esbuild, bundling, minification, tree-shaking, scripts, assets
+  tags: frontend, javascript, typescript, esbuild, bundling, minification, tree-shaking, scripts, assets, obfuscation
 ---
 
 # Frontend Scripts & TypeScript Skill
 
-Zero-config frontend asset pipeline powered by esbuild for TypeScript transpilation, bundling, minification, and tree-shaking.
+ODAC provides a built-in, Zero-Config frontend asset pipeline powered by **esbuild** for TypeScript transpilation, bundling, minification, tree-shaking, and multi-level code obfuscation.
 
-## 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.
+## Core Rules & Conventions
 
-## Development vs Production
-- **`odac dev`**: Watch mode with source maps, no minification, instant rebuilds.
-- **`odac build`**: Full minification, tree-shaking, and dead code elimination.
+1.  **Entry Points**: Every `.ts`, `.js`, `.mts`, or `.mjs` file placed directly in `view/js/` represents a unique entry point and will compile into a separate bundle in `public/assets/js/{name}.js`.
+2.  **Partials Convention**: Files starting with an underscore (e.g., `_utils.ts`, `_api.ts`) are treated as private modules/partials. They are **ignored** as entry points and should only be used as shared imports.
+3.  **No TypeScript Enforcement**: TypeScript and plain JavaScript are supported equally out of the box.
+4.  **Import Resolution**: Use standard ES module `import`/`export` syntax. esbuild bundles all imported modules into a single optimized bundle, eliminating extra runtime network requests.
+5.  **Output Path**: Compiled output is saved statically under `public/assets/js/`.
+
+## Pipeline Modes
+
+*   **Development (`npm run dev` / `odac dev`)**: 
+    *   Watches all scripts in `view/js/` for instant sub-millisecond rebuilds.
+    *   Source maps are always enabled to facilitate easy debugging.
+    *   No minification or obfuscation is applied.
+*   **Production (`npm run build` / `odac build`)**:
+    *   Enables full bundling, minification, and tree-shaking.
+    *   Applies configured obfuscation levels.
+    *   Exports clean production-ready assets to `public/assets/js/`.
+
+## Configuration (`odac.json`)
+
+You can customize the pipeline behavior via the optional `js` key in the `odac.json` configuration file:
+
+```json
+{
+  "js": {
+    "target": "es2020",
+    "minify": true,
+    "sourcemap": false,
+    "bundle": true,
+    "obfuscate": false
+  }
+}
+```
+
+### Configuration Options
+
+| Option      | Default    | Description |
+|-------------|------------|-------------|
+| `target`    | `"es2020"` | JavaScript target version (`es2015`, `es2020`, `esnext`, etc.). |
+| `minify`    | `true`     | Enables minification (whitespace removal, variable shortening, dead code elimination) in production. |
+| `sourcemap` | `false`    | Generates source maps in production builds (always enabled in dev mode). |
+| `bundle`    | `true`     | Bundles all imported dependency modules into the output entry-point file. |
+| `obfuscate` | `false`    | Configures the level of production code obfuscation (`false`, `true`/`"low"`, `"medium"`, `"high"`). |
+
+---
+
+## Obfuscation Levels
+
+ODAC supports three distinct levels of code obfuscation in production mode (`odac build`). Obfuscation is disabled by default and is never applied during development.
+
+| Level | Behavior |
+|-------|----------|
+| `false` | **No Obfuscation**: Standard minification and tree-shaking only. |
+| `true` / `"low"` | **Low Mangling**: Mangles properties starting with `_` (private-by-convention). |
+| `"medium"` | **Medium Security**: Low level mangling + drops `debugger` statements + removes `console.debug` and `console.trace` calls. |
+| `"high"` | **Maximum Hardening**: Mangles all `_` and `$` prefixed properties + drops all `console.*` calls and `debugger` statements. |
+
+> [!WARNING]
+> **High Obfuscation Compatibility Warning:** 
+> The `"high"` obfuscation level mangles `$`-prefixed properties. This can break frontend code interacting with external libraries or frameworks that rely heavily on the `$` naming convention (e.g., jQuery). Start with `"low"` or `"medium"` and verify compatibility thoroughly before deploying with `"high"`.
+
+---
+
+## Example Directory Structure
 
-## 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)
+├── app.ts          → compiled to public/assets/js/app.js (Entry Point)
+├── admin.ts        → compiled to public/assets/js/admin.js (Entry Point)
+├── _api.ts         (Shared API Module — Import only, not compiled on its own)
+└── _utils.ts       (Shared Utility Module — Import only, not compiled on its own)
 ```
 
 ## HTML Integration
+
+Inject compiled scripts into your skeleton or layout templates using regular script tags:
+
 ```html
 <script src="/assets/js/app.js"></script>
 ```

package/package.json

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

package/src/Request.js

@@ -50,12 +50,18 @@ class OdacRequest {
   async abort(code) {
     this.status(code)
     let result = {401: 'Unauthorized', 404: 'Not Found', 408: 'Request Timeout'}[code] ?? null
-    if (
-      this.#odac.Route?.routes?.[this.route]?.error &&
-      this.#odac.Route.routes[this.route].error[code] &&
-      typeof this.#odac.Route.routes[this.route].error[code].cache === 'function'
-    )
-      result = await this.#odac.Route.routes[this.route].error[code].cache(this.#odac)
+    const errorRoute = this.#odac.Route?.routes?.[this.route]?.error?.[code]
+    if (errorRoute && typeof errorRoute.cache === 'function') {
+      try {
+        const handlerResult = await errorRoute.cache(this.#odac)
+        // If the handler returned nothing, assume it configured the view via Odac.View.set()
+        // and let Route.request() continue to View.print() like normal pages.
+        if (handlerResult === undefined) return
+        result = handlerResult
+      } catch (e) {
+        console.error(JSON.stringify({level: 'ERROR', message: `Error in custom error handler for ${code}`, error: e.message}))
+      }
+    }
     this.end(result)
   }
 

package/src/Route.js

@@ -858,6 +858,13 @@ class Route {
   }
 
   error(code, file) {
+    if (typeof file === 'object' && file !== null && !Array.isArray(file)) {
+      this.set('error', code, _odac => {
+        _odac.set(file)
+        _odac.View.set(file)
+      })
+      return
+    }
     this.set('error', code, file)
   }
 

package/src/View/Form.js

@@ -58,6 +58,30 @@ class Form {
     return String(value).replace(/[&<>"']/g, ch => map[ch])
   }
 
+  // Like escapeHtml but leaves {{ ... }} / {!! ... !!} template tokens intact
+  // so they survive into the view engine's {{ }} pass. Escaping inside the
+  // tokens would corrupt the JS expression (e.g. ' -> &#39;) and produce
+  // "Unexpected token '&'" at render time.
+  static escapeHtmlPreservingTemplates(value) {
+    if (value === null || value === undefined) return ''
+    const str = String(value)
+    const regex = /\{\{[\s\S]*?\}\}|\{!![\s\S]*?!!\}/g
+    let result = ''
+    let lastIndex = 0
+    let match
+    while ((match = regex.exec(str)) !== null) {
+      if (match.index > lastIndex) {
+        result += this.escapeHtml(str.substring(lastIndex, match.index))
+      }
+      result += match[0]
+      lastIndex = regex.lastIndex
+    }
+    if (lastIndex < str.length) {
+      result += this.escapeHtml(str.substring(lastIndex))
+    }
+    return result
+  }
+
   static parse(content, Odac) {
     for (const type of this.FORM_TYPES) {
       content = this.parseFormType(content, Odac, type)
@@ -484,16 +508,18 @@ class Form {
     let html = ''
     const escapedName = this.escapeHtml(field.name)
     const escapedType = this.escapeHtml(field.type)
-    const escapedPlaceholder = this.escapeHtml(field.placeholder)
+    const escapedPlaceholder = this.escapeHtmlPreservingTemplates(field.placeholder)
 
     if (field.label && field.type !== 'checkbox') {
-      const fieldId = this.escapeHtml(field.id || `odac-${field.name}`)
-      html += `<label for="${fieldId}">${this.escapeHtml(field.label)}</label>\n`
+      const fieldId = this.escapeHtmlPreservingTemplates(field.id || `odac-${field.name}`)
+      html += `<label for="${fieldId}">${this.escapeHtmlPreservingTemplates(field.label)}</label>\n`
     }
 
-    const classAttr = field.class ? ` class="${this.escapeHtml(field.class)}"` : ''
-    const idAttr = field.id ? ` id="${this.escapeHtml(field.id)}"` : ` id="${this.escapeHtml(`odac-${field.name}`)}"`
-    const valueAttr = field.value !== null ? ` value="${this.escapeHtml(field.value)}"` : ''
+    const classAttr = field.class ? ` class="${this.escapeHtmlPreservingTemplates(field.class)}"` : ''
+    const idAttr = field.id
+      ? ` id="${this.escapeHtmlPreservingTemplates(field.id)}"`
+      : ` id="${this.escapeHtmlPreservingTemplates(`odac-${field.name}`)}"`
+    const valueAttr = field.value !== null ? ` value="${this.escapeHtmlPreservingTemplates(field.value)}"` : ''
 
     if (field.type === 'checkbox') {
       const attrs = this.buildHtml5Attributes(field)
@@ -501,14 +527,14 @@ class Form {
       if (field.label) {
         html += `<label>\n`
         html += `  <input type="checkbox"${idAttr} name="${escapedName}" value="1"${classAttr}${checkedAttr}${attrs}>\n`
-        html += `  ${this.escapeHtml(field.label)}\n`
+        html += `  ${this.escapeHtmlPreservingTemplates(field.label)}\n`
         html += `</label>\n`
       } else {
         html += `<input type="checkbox"${idAttr} name="${escapedName}" value="1"${classAttr}${checkedAttr}${attrs}>\n`
       }
     } else if (field.type === 'textarea') {
       const attrs = this.buildHtml5Attributes(field)
-      html += `<textarea${idAttr} name="${escapedName}" placeholder="${escapedPlaceholder}"${classAttr}${attrs}>${this.escapeHtml(
+      html += `<textarea${idAttr} name="${escapedName}" placeholder="${escapedPlaceholder}"${classAttr}${attrs}>${this.escapeHtmlPreservingTemplates(
         field.value || ''
       )}</textarea>\n`
     } else {
@@ -524,7 +550,7 @@ class Form {
     for (const key in field.extraAttributes) {
       const val = field.extraAttributes[key]
       if (val === '') attrs += ` ${key}`
-      else attrs += ` ${key}="${this.escapeHtml(val)}"`
+      else attrs += ` ${key}="${this.escapeHtmlPreservingTemplates(val)}"`
     }
     return attrs
   }