odac 1.1.0 → 1.2.0

package/client/odac.js

@@ -526,7 +526,10 @@ if (typeof window !== 'undefined') {
                     let errorEl = formElement.querySelector(`[odac-form-error="${name}"]`)
                     if (errorEl) {
                       errorEl.innerHTML = this.textToHtml(message)
-                      errorEl.style.cssText = 'display:block;color:#dc3545;font-size:0.875rem;margin-top:0.25rem'
+                      errorEl.style.display = 'block'
+                      if (!errorEl.style.color) errorEl.style.color = '#dc3545'
+                      if (!errorEl.style.fontSize) errorEl.style.fontSize = '0.875rem'
+                      if (!errorEl.style.marginTop) errorEl.style.marginTop = '0.25rem'
                     } else {
                       const inputEl = formElement.querySelector(`*[name="${name}"]`)
                       if (inputEl) {
@@ -545,7 +548,10 @@ if (typeof window !== 'undefined') {
                         const errorEl = document.createElement('div')
                         errorEl.setAttribute('odac-form-error', name)
                         errorEl.innerHTML = this.textToHtml(message)
-                        errorEl.style.cssText = 'display:block;color:#dc3545;background-color:#f8d7da;border:1px solid #f5c2c7;border-radius:0.375rem;padding:0.75rem 1rem;margin-bottom:1rem;font-size:0.875rem'
+                        errorEl.style.display = 'block'
+                        errorEl.style.color = '#dc3545'
+                        errorEl.style.fontSize = '0.875rem'
+                        errorEl.style.marginBottom = '1rem'
                         formElement.insertBefore(errorEl, formElement.firstChild)
                       }
                     }
@@ -956,8 +962,8 @@ if (typeof window !== 'undefined') {
             socket = new OdacWebSocket(wsUrl, protocols, options)
             socket.on('open', () => broadcast('open'))
             socket.on('message', data => broadcast('message', data))
-            socket.on('close', e => broadcast('close', e))
-            socket.on('error', e => broadcast('error', e))
+            socket.on('close', e => broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean}))
+            socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
           } else if (socket.connected) {
              // If already connected, notify the new port immediately
              port.postMessage({type: 'open'})

package/docs/backend/01-overview/03-development-server.md

@@ -1,79 +1,72 @@
-## 🚀 Development Server
+## 🚀 CLI Commands & Deployment
 
-ODAC provides a built-in development server that allows you to test your website locally without running the full ODAC server infrastructure.
+ODAC comes with a powerful CLI to manage your project's lifecycle, from development to production.
 
-### Quick Start
+### Development Mode (`dev`)
 
-Navigate to your website directory and run one of these commands:
+Start the development server with **hot-reloading** and **automatic Tailwind CSS compilation**:
 
 ```bash
 # Using npm script
-npm start
+npm run dev
 
 # Using ODAC directly
-odac framework run
+npx odac dev
 ```
 
-Both commands will start a local development server on port `1071` by default, and your website will be accessible at `http://127.0.0.1:1071`.
+**What it does:**
+- Starts the Node.js server (default port `1071`).
+- **Zero-Config Tailwind:** Automatically watches and compiles your classes.
+- **Watch Mode:** Recompiles CSS instantly when you change files.
 
-### Custom Port
+### Production Build (`build`)
 
-You can specify a custom port by adding it as an argument:
+Prepare your application for production deployment. This command compiles and modifies your assets for optimal performance.
 
 ```bash
-# Using npm script with custom port
-npm start 8080
+# Using npm script
+npm run build
 
-# Using ODAC directly with custom port
-odac framework run 8080
+# Using ODAC directly
+npx odac build
 ```
 
-This will start the server on your specified port (e.g., `http://127.0.0.1:8080`).
-
-### Development vs Production
+**What it does:**
+- **Compiles CSS:** Generates the final `public/assets/css/app.css`.
+- **Minification:** Compresses the CSS to reduce file size.
+- **One-off Run:** Runs once and exits. Does not start a server.
 
-The development server (`npm start`) is designed for:
+### Production Server (`start`)
 
-- **Local testing** and development only
-- **Quick iteration** without server setup
-- **Debugging** your application logic
-- **Testing on localhost** (127.0.0.1)
-
-**Important**: The development server does NOT provide DNS, SSL, or other production services.
-
-For production deployment with full ODAC server features, create your website using:
+Start the application in **production mode**. This is the command you should run on your server or hosting platform.
 
 ```bash
-odac web create
-```
+# Using npm script
+npm start
 
-This registers your website with the ODAC server and provides:
+# Using ODAC directly
+npx odac start
+```
 
-- **Automatic SSL** certificate management
-- **DNS handling** for your domain
-- **Multi-domain hosting** capabilities
-- **Process monitoring** and auto-restart
-- **Production optimizations** and security
+**What it does:**
+- Sets `NODE_ENV=production`.
+- Starts the Node.js server.
+- **No Overhead:** Does not run Tailwind watchers or dev tools. Simplicity and performance focused.
 
 ### Package.json Scripts
 
-When you create a new website, ODAC automatically generates a `package.json` with these useful scripts:
+When you create a new ODAC project, your `package.json` comes pre-configured with these scripts:
 
 ```json
 {
   "scripts": {
-    "start": "odac framework run",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "odac dev",
+    "build": "odac build",
+    "start": "odac start"
   }
 }
 ```
 
-- `npm start` - Starts the development server for local testing
-- `npm test` - Placeholder for your test suite
-
-### Tips
-
-- The development server automatically detects changes in your code
-- Use `Ctrl+C` to stop the development server
-- The server will show helpful error messages in the console
-- All ODAC framework features are available in development mode
+- `npm run dev` - Your daily development command.
+- `npm run build` - Run this before deploying (e.g., in CI/CD).
+- `npm start` - The command that runs your live website.

package/docs/backend/02-structure/01-typical-project-layout.md

@@ -2,37 +2,70 @@
 
 Let's take a look at a typical project layout:
 
--   `project_root/`
-    -   `config.json`: This is where you'll keep your app's secrets and settings, like database passwords or API keys.
-    -   `index.js`: The starting pistol for your web application! This file kicks off the Odac framework.
-    -   `package.json`: Contains project metadata and npm scripts for development. Automatically generated when creating a new website.
-    -   `public/`: All files placed in this folder are directly accessible from the outside. This is the perfect place for your images, stylesheets, and client-side JavaScript.
-    -   `route/`: This folder holds all your route definitions. The filename of the route file corresponds to the subdomain it serves.
-        -   `www.js`: Used for routes on your main domain (e.g., `www.example.com` or `example.com`).
-        -   `api.js`: Used for routes on a subdomain (e.g., `api.example.com`). When a request comes in for `api.example.com`, this is the route file that gets used. You can create files for any subdomain!
-    -   `class/`: A dedicated place for your business logic classes and reusable services (e.g., `User.js`, `Mailer.js`).
-    -   `controller/`: This is where the magic happens! Controllers contain the main logic for your application.
-        -   `page/`: We suggest putting controllers that show HTML pages in here.
-        -   `api/`: If you're building an API, it's a great idea to keep those controllers separate in their own folder.
-    -   `view/`: For all your HTML template files. This is what your users will see.
-
-### Development Commands
-
-Your `package.json` includes helpful npm scripts for development:
+```
+project/
+├── class/              # Business logic classes (request-scoped)
+│   ├── Payment.js
+│   └── User.js
+├── controller/         # HTTP request handlers
+│   ├── api/            # API endpoint controllers
+│   │   ├── auth.js
+│   │   └── users.js
+│   └── page/           # HTML page controllers
+│       ├── about.js
+│       └── home.js
+├── middleware/         # Route middleware functions
+│   └── auth.js
+├── public/             # Static assets (directly accessible)
+│   └── assets/
+│       ├── css/
+│       │   └── app.css # Auto-generated by Tailwind
+│       ├── img/
+│       └── js/
+├── route/              # Route definitions (subdomain-based)
+│   ├── api.js          # Routes for api.example.com
+│   └── www.js          # Routes for www.example.com
+├── storage/            # App storage (logs, cache, uploads)
+│   └── .cache/
+├── view/               # HTML templates
+│   ├── content/
+│   ├── css/            # (Optional) Custom Tailwind entry points
+│   ├── footer/
+│   ├── header/
+│   └── skeleton/
+├── .env                # Environment variables (secrets, API keys)
+├── odac.json           # App configuration
+└── package.json        # Project metadata & npm scripts
+```
 
-```bash
-# Start development server (default port 1071)
-npm start
+### 📁 Directory Breakdown
 
-# Start development server on custom port
-npm start 8080
-```
+| Directory | Purpose |
+|-----------|---------|
+| `class/` | Request-scoped service classes for business logic |
+| `controller/` | HTTP handlers that process requests and return responses |
+| `middleware/` | Functions that run before controllers (auth, logging, etc.) |
+| `route/` | Route definitions, one file per subdomain |
+| `view/` | HTML templates and partials |
+| `public/` | Static files served directly to browsers |
+| `storage/` | Runtime data (cache, logs, file uploads) |
 
-You can also use Odac commands directly:
+### CLI Commands
+
+Your `package.json` includes scripts to manage your project lifecycle:
 
 ```bash
-# Development server (local testing only)
-odac framework run [port]
+# STAGE 1: DEVELOPMENT
+# Starts dev server with hot-reload & automatic Tailwind CSS
+npm run dev
+
+# STAGE 2: BUILD
+# Compiles and optimizes assets (CSS) for production
+npm run build
+
+# STAGE 3: PRODUCTION
+# Starts the optimized server
+npm start
 ```
 
 **Note**: For production websites with DNS and SSL, use `odac web create` to register with Odac server.

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

@@ -1,10 +1,10 @@
 ## ⚙️ Configuration Overview
 
-Odac uses a simple and flexible configuration system based on `config.json` and optional `.env` files. You can choose the approach that best fits your needs.
+Odac uses a simple and flexible configuration system based on `odac.json` and optional `.env` files. You can choose the approach that best fits your needs.
 
 ### Configuration Files
 
-#### config.json (Required)
+#### odac.json (Required)
 The main configuration file located in your website's root directory. This file contains all your application settings in JSON format.
 
 ```json
@@ -46,7 +46,7 @@ Perfect for development or non-sensitive settings:
 ```
 
 #### 2. Environment Variables (Secure)
-Use `${VARIABLE}` syntax in `config.json` to reference `.env` values:
+Use `${VARIABLE}` syntax in `odac.json` to reference `.env` values:
 
 ```json
 {
@@ -101,7 +101,7 @@ const nodeEnv = process.env.NODE_ENV
 ### Best Practices
 
 **Development:**
-- Use direct values in `config.json` for quick setup
+- Use direct values in `odac.json` for quick setup
 - Keep development credentials simple
 
 **Production:**
@@ -111,7 +111,7 @@ const nodeEnv = process.env.NODE_ENV
 - Copy `.env.example` to `.env` and fill in production values
 
 **Version Control:**
-- Commit `config.json` with `${VARIABLE}` placeholders
+- Commit `odac.json` with `${VARIABLE}` placeholders
 - Commit `.env.example` with dummy values
 - Never commit `.env` with real credentials
 
@@ -176,7 +176,7 @@ See individual documentation sections for detailed configuration options.
 
 ### Example Setup
 
-**config.json** (committed to git):
+**odac.json** (committed to git):
 ```json
 {
   "request": {

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

@@ -1,6 +1,6 @@
 ## 🔌 Database Connection
 
-When you add a `mysql` object to your `config.json`, the system will automatically connect to your MySQL database. No separate connection setup is needed in your code.
+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.
 
 ### Basic Configuration
 
@@ -21,7 +21,7 @@ Once this is configured, you can directly use `Odac.DB` commands to run queries.
 
 For better security, especially in production, you can use environment variables for sensitive information:
 
-**config.json:**
+**odac.json:**
 ```json
 {
   "mysql": {

package/docs/backend/03-config/02-static-route-mapping-optional.md

@@ -1,6 +1,6 @@
 ## 🗺️ Static Route Mapping (Optional)
 
-Normally, all publicly served files should be in your `public` folder. However, if you need to expose a specific file from somewhere else on your server, you can use the optional `route` object in your `config.json`. This creates a direct mapping from a URL path to that file.
+Normally, all publicly served files should be in your `public` folder. However, if you need to expose a specific file from somewhere else on your server, you can use the optional `route` object in your `odac.json`. This creates a direct mapping from a URL path to that file.
 
 ```json
 "route": {

package/docs/backend/03-config/03-request-timeout.md

@@ -1,6 +1,6 @@
 ## ⏱️ Request Timeout
 
-You can configure the global timeout for incoming requests by adding a `request` object to your `config.json`.
+You can configure the global timeout for incoming requests by adding a `request` object to your `odac.json`.
 
 ```json
 "request": {

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

@@ -4,7 +4,7 @@ Odac supports environment variables through `.env` files, making it easy to mana
 
 ### Creating a .env File
 
-Create a `.env` file in your website's root directory (same location as `config.json`):
+Create a `.env` file in your website's root directory (same location as `odac.json`):
 
 ```bash
 # .env
@@ -37,7 +37,7 @@ FEATURE_BETA=true
 MAINTENANCE_MODE=false
 ```
 
-### Using in config.json
+### Using in odac.json
 
 Reference environment variables using `${VARIABLE_NAME}` syntax:
 
@@ -91,7 +91,7 @@ module.exports = function() {
 }
 ```
 
-#### 3. From Odac.Config (if defined in config.json)
+#### 3. From Odac.Config (if defined in odac.json)
 
 ```javascript
 module.exports = function() {
@@ -222,6 +222,6 @@ MAIL_FROM='noreply@example.com'
 
 - Environment variables are loaded when the application starts
 - Changes to `.env` require restarting the application
-- The `.env` file is **optional** - you can use direct values in `config.json` if preferred
+- The `.env` file is **optional** - you can use direct values in `odac.json` if preferred
 - Variables defined in `.env` are available throughout your entire application
 - If a variable is not found, `Odac.env()` returns the default value or `undefined`

package/docs/backend/03-config/05-early-hints.md

@@ -54,7 +54,7 @@ Same flow - hints are sent from the manifest immediately.
 
 ## Configuration (Optional)
 
-While Early Hints works automatically, you can customize it in `config.json`:
+While Early Hints works automatically, you can customize it in `odac.json`:
 
 ```json
 {
@@ -329,7 +329,7 @@ Reduce `maxResources` in config:
 
 ## Disabling Early Hints
 
-Removing the `earlyHints` configuration section from your `config.json` is equivalent to using the default settings, which has the feature enabled. To truly disable Early Hints, you must explicitly set `enabled: false` in your configuration:
+Removing the `earlyHints` configuration section from your `odac.json` is equivalent to using the default settings, which has the feature enabled. To truly disable Early Hints, you must explicitly set `enabled: false` in your configuration:
 
 ```json
 {

package/docs/backend/04-routing/03-api-and-data-routes.md

@@ -1,5 +1,22 @@
 ## 📦 API and Data Routes
 
+
+#### Class-Based Route Definition (Recommended)
+
+You can route requests to specific methods within a Controller Class using the `ClassName@methodName` syntax. This allows you to group related logic in a single file clearly.
+
+```javascript
+// Calls the 'index' method of the class exported in controller/User.js
+Odac.Route.get('/users', 'User@index');
+
+// Calls the 'store' method of the class exported in controller/User.js
+Odac.Route.post('/users', 'User@store');
+
+// You can also use dot notation for controllers in subdirectories
+// controller/Admin/Dashboard.js -> Admin.Dashboard
+Odac.Route.get('/admin', 'Admin.Dashboard@index');
+```
+
 #### `get(path, controller, options)`
 Defines a route that responds to `GET` requests. This is ideal for API endpoints that return data (like JSON).
 
@@ -18,3 +35,4 @@ Defines a route that responds to `POST` requests, typically used for form submis
 // A form that posts data to /login
 Odac.Route.post('/login', 'auth.login');
 ```
+

package/docs/backend/04-routing/07-cron-jobs.md

@@ -79,6 +79,9 @@ Odac.Route.cron('task')
 // Day (1-31)
 .day(15) // On the 15th of the month
 
+// At Specific Time (HH:MM)
+.at('14:30') // At 14:30 (Shorthand for .hour(14).minute(30))
+
 // Week day (0-6, 0=Sunday)
 .weekDay(1) // On Monday
 
@@ -114,6 +117,18 @@ Odac.Route.cron('periodic')
 
 // Every N years
 .everyYear(1) // Every year
+
+## Raw Cron Expression
+You can use standard UNIX cron expressions (Minute Hour Day Month WeekDay) using the `.raw()` method.
+Supported formats for each field: `*`, `*/n` (interval), `n` (exact match).
+
+```javascript
+// Run every 15 minutes
+Odac.Route.cron('quarter-task').raw('*\/15 * * * *')
+
+// Run at 14:30 on Mondays
+Odac.Route.cron('weekly-meeting').raw('30 14 * * 1')
+```
 ```
 
 ## Combination Usage
@@ -146,4 +161,5 @@ Odac.Route.cron('monthly-cleanup')
 - If the same job is defined multiple times, the last definition takes precedence
 - Controller files are re-required on each execution
 - Inline functions are stored in memory and executed directly
-- If a job fails, it stops but the system continues
+- If a job fails, it stops but the system continues
+- **CRITICAL:** Missing conditions act as wildcards (`*`). If you specify `.hour(14)` but omit `.minute()`, the task will run **every minute** between 14:00 and 14:59. Always specify smaller units (minute) to pin execution to a single point in time. Use `.at('14:00')` to safely set both hour and minute.

package/docs/backend/05-controllers/01-how-to-build-a-controller.md

@@ -1,8 +1,52 @@
 ## 🏗️ How to Build a Controller
 
-A controller is just a JavaScript module that exports a function. This function automatically gets the magical `Odac` context object we talked about in the overview.
+A controller is just a JavaScript module that exports a function or a Class. This function automatically gets the magical `Odac` context object we talked about in the overview.
 
-#### A Simple "Hello World" Controller
+#### Class-Based Controllers (Professional & Recommended)
+
+For professional applications, we **strongly recommend** using Class-Based Controllers. This approach allows you to group related actions (like all User-related or Product-related logic) into a single file in the `controller/` directory, keeping your project organized.
+
+**Example: `controller/User.js`**
+
+```javascript
+class User {
+  // Access this via 'User@index'
+  index(Odac) {
+    return Odac.View.make('user.list', {
+      title: 'User List'
+    })
+  }
+
+  // Access this via 'User@show'
+  show(Odac) {
+    const id = Odac.Request.input('id')
+    // Fetch user logic...
+    return Odac.return({ id: id, name: 'John Doe' })
+  }
+
+  // Access this via 'User@store'
+  store(Odac) {
+    // Save user logic...
+    return Odac.return({ success: true })
+  }
+}
+
+module.exports = User
+```
+
+When using this structure, you define your routes using the `ControllerName@MethodName` syntax:
+
+```javascript
+Odac.Route.get('/users', 'User@index')
+Odac.Route.get('/users/{id}', 'User@show')
+Odac.Route.post('/users', 'User@store')
+```
+
+The framework automatically instantiates your Controller class and calls the specified method with the `Odac` instance passed as an argument.
+
+#### specific Function Controllers (Basic)
+
+For very simple or single-purpose routes, you can export a single function.
 
 Check out this basic example from `controller/page/index.js`:
 
@@ -14,4 +58,5 @@ module.exports = function (Odac) {
 }
 ```
 
-This little guy is responsible for handling the homepage route (`/`). When it runs, it just sends a simple string back to the user's browser.
+This simple function is responsible for handling the homepage route (`/`). When it runs, it just sends a simple string back to the user's browser.
+

package/docs/backend/05-controllers/03-controller-classes.md

@@ -4,9 +4,28 @@ You can organize your business logic into reusable classes. This is especially u
 
 We recommend placing these files in the `class/` directory.
 
+### ❓ Service Class vs. Controller
+
+It is important not to confuse **Service Classes** with **Class-Based Controllers**.
+
+- **Controllers** (located in `controller/`):
+    - Handle HTTP requests (Input -> Process -> Response).
+    - Can be defined as Classes for better organization.
+    - Are mapped to specific Routes (e.g., via `Route.get()`).
+
+- **Service Classes** (located in `class/`):
+    - Contain reusable business logic (e.g., `User.calculateReputation()`, `Mail.sendWelcome()`).
+    - Are **not** directly mapped to routes.
+    - Can be used by *multiple* controllers or other services.
+    - Are **Request Scoped**: They are instantiated fresh for every request and attached to the request's `Odac` instance. They correspond to the life-cycle of the request.
+
+**Rule of Thumb:** If it talks to the browser/API client, it's a **Controller**. If it processes data behind the scenes, it's a **Service Class**.
+
 #### Creating a Service Class
 
-Any class file placed in the `class/` directory will be automatically loaded and available on the `Odac` object. The class receives the global `Odac` request instance in its constructor, giving you access to all request-scoped services:
+Any class file placed in the `class/` directory will be automatically detected. When a request comes in, Odac creates a **new instance** of your class and passes the current request's `Odac` object to the constructor.
+
+This means `this.Odac` inside your class gives you access to the specific request, response, authentication state, and database for *that specific user request*.
 
 ```javascript
 // class/User.js
@@ -15,6 +34,7 @@ class User {
     this.Odac = Odac
   }
 
+
   async getProfile() {
     const user = await this.Odac.Auth.user()
     return {
@@ -58,22 +78,22 @@ If your class name conflicts with a built-in Odac service (like `Mail`, `DB`, `A
 Example: `class/Mail.js` (conflicts with core Mail) -> `Odac.App.Mail`
 
 #### Accessing Services in Controllers
-
-Service classes are automatically instantiated for each request and attached to the `Odac` object using the file name. You can access them from any controller:
-
-```javascript
-// controller/get/profile.js
-module.exports = async function (Odac) {
-  // Access your User class via Odac.User
-  const profile = await Odac.User.getProfile()
-  
-  return Odac.return(profile)
-}
-```
-
-#### Benefits of Service Classes
-
-- **Organization**: Group related business logic together in `class/`
-- **Reusability**: Share logic between different controllers and routes
-- **Context**: The `Odac` object is injected, providing access to `Auth`, `DB`, `Request`, etc.
-- **Separation of Concerns**: Keep your Controllers lightweight by moving heavy logic to Services.
+ 
+ Since Service classes are attached to the `Odac` instance for each request, you can access them directly by their file name.
+ 
+ ```javascript
+ // controller/get/profile.js
+ module.exports = async function (Odac) {
+   // Odac.User is a fresh instance of the User class dedicated to this request
+   const profile = await Odac.User.getProfile()
+   
+   return Odac.return(profile)
+ }
+ ```
+ 
+ #### Benefits of Service Classes
+ 
+ - **Organization**: Group related business logic together in `class/`
+ - **Reusability**: Share logic between different controllers and routes
+ - **Context Awareness**: The `Odac` request object is injected automatically, so your services know about the current user and request.
+ - **Separation of Concerns**: Keep your Controllers lightweight by moving heavy logic to Services.

package/docs/backend/06-request-and-response/01-the-request-object-what-is-the-user-asking-for.md

@@ -94,3 +94,20 @@ module.exports = async function (Odac) {
   })
 }
 ```
+
+### Session Data
+
+You can store data in the current user's session using `Odac.session()`. This data persists across requests.
+
+```javascript
+module.exports = async function (Odac) {
+  // Set a session value
+  Odac.session('cart_id', 12345)
+  
+  // Get a session value
+  const cartId = Odac.session('cart_id')
+  
+  // Remove a session value
+  Odac.session('cart_id', null)
+}
+```