odac 1.0.0 → 1.1.0

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

@@ -1,6 +1,6 @@
 ## 🚀 Development Server
 
-Odac provides a built-in development server that allows you to test your website locally without running the full Odac server infrastructure.
+ODAC provides a built-in development server that allows you to test your website locally without running the full ODAC server infrastructure.
 
 ### Quick Start
 
@@ -10,7 +10,7 @@ Navigate to your website directory and run one of these commands:
 # Using npm script
 npm start
 
-# Using Odac directly
+# Using ODAC directly
 odac framework run
 ```
 
@@ -24,7 +24,7 @@ You can specify a custom port by adding it as an argument:
 # Using npm script with custom port
 npm start 8080
 
-# Using Odac directly with custom port
+# Using ODAC directly with custom port
 odac framework run 8080
 ```
 
@@ -41,13 +41,13 @@ The development server (`npm start`) is designed for:
 
 **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:
+For production deployment with full ODAC server features, create your website using:
 
 ```bash
 odac web create
 ```
 
-This registers your website with the Odac server and provides:
+This registers your website with the ODAC server and provides:
 
 - **Automatic SSL** certificate management
 - **DNS handling** for your domain
@@ -57,7 +57,7 @@ This registers your website with the Odac server and provides:
 
 ### Package.json Scripts
 
-When you create a new website, Odac automatically generates a `package.json` with these useful scripts:
+When you create a new website, ODAC automatically generates a `package.json` with these useful scripts:
 
 ```json
 {
@@ -76,4 +76,4 @@ When you create a new website, Odac automatically generates a `package.json` wit
 - 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
+- All ODAC framework features are available in development mode

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

@@ -10,6 +10,7 @@ Let's take a look at a typical project layout:
     -   `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.

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

@@ -161,6 +161,15 @@ const nodeEnv = process.env.NODE_ENV
 }
 ```
 
+**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`.
+
+```json
+{
+  "debug": true
+}
+```
+
 Early Hints is a performance optimization feature that works automatically without any configuration. The server sends preliminary HTTP headers to the browser before the final response, allowing browsers to start preloading critical resources (CSS, JavaScript, fonts) earlier. This is completely zero-config - it detects resources from your HTML automatically and sends hints on subsequent requests.
 
 See individual documentation sections for detailed configuration options.

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

@@ -15,7 +15,7 @@ When you add a `mysql` object to your `config.json`, the system will automatical
 }
 ```
 
-Once this is configured, you can directly use `Odac.Mysql` commands to run queries.
+Once this is configured, you can directly use `Odac.DB` commands to run queries.
 
 ### Using Environment Variables
 

package/docs/backend/04-routing/02-controller-less-view-routes.md

@@ -3,18 +3,24 @@
 For simple pages that don't require complex logic in a controller, you can render a view directly from your route file by passing a view configuration object as the second parameter.
 
 #### `page(path, { ... })`
-This defines a page and immediately tells it which view components to render.
+This defines a page and immediately tells it which view components to render. You can also pass variables directly in the object, which will be available in your views.
 
 ```javascript
 Odac.Route.page("/users", {
+    // View Configuration
     skeleton: "dashboard",
     header: "dashboard.main",
     sidebar: "dashboard.main",
     footer: "dashboard.main",
-    content: "users"
+    content: "users",
+
+    // Page Variables
+    title: "User Management",
+    description: "Manage your platform users here"
 });
 ```
-This example tells Odac to render the `/users` page by assembling a view from multiple parts, likely using a main `dashboard` skeleton and filling it with different content blocks.
+
+This example tells Odac to render the `/users` page using the `dashboard` skeleton. Additionally, `title` and `description` are set as variables and can be accessed in your views using `<odac var="title" />`.
 
 **Page Identifier:** When using view objects, the page identifier (accessible via `Odac.page()` in frontend) is automatically set to the `content` or `all` value. In this example, the page identifier would be `"users"`, allowing you to run page-specific JavaScript:
 

package/docs/backend/04-routing/09-websocket.md

@@ -45,6 +45,35 @@ web/
 │   └── websocket.js    # WebSocket routes (recommended)
 ```
 
+### Using Controllers
+
+You can also specify a connector file as a string. Odac will look for the file in `controller/ws/`.
+
+```javascript
+// route/websocket.js
+Odac.Route.ws('/chat', 'ChatController')
+```
+
+**File Structure:**
+```
+web/
+├── controller/
+│   └── ws/
+│       └── ChatController.js
+```
+
+**Controller File:**
+```javascript
+// controller/ws/ChatController.js
+module.exports = Odac => {
+  Odac.ws.send({type: 'welcome'})
+  
+  Odac.ws.on('message', data => {
+    // ...
+  })
+}
+```
+
 ## WebSocket Client API (Odac.ws)
 
 The WebSocket client is accessible via `Odac.ws` in your handler, providing a consistent API pattern with HTTP routes.

package/docs/backend/05-controllers/02-your-trusty-odac-assistant.md

@@ -14,6 +14,8 @@ Remember the `Odac` object? It's your best friend inside a controller. It's pass
 
 *   `Odac.return(data)`: Send back a response.
 *   `Odac.direct(url)`: Redirect the user to a new page.
+*   `Odac.set(key, value)`: Pass variables to your View template.
+*   `Odac.share(key, value)`: Share data directly with frontend JavaScript (`odac.data()`).
 *   `Odac.cookie(key, value)`: Set a browser cookie.
 *   `Odac.validator()`: Check user input easily.
 *   `Odac.setInterval(callback, delay)`: Schedule repeating tasks (auto-cleanup).

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

@@ -1,13 +1,15 @@
-## 🎓 Controller Classes
+## 🧩 Service Classes
 
-While simple function exports work great for basic controllers, you can also organize your code using classes. This is especially useful when you want to share logic between multiple methods or keep related functionality together.
+You can organize your business logic into reusable classes. This is especially useful when you want to share logic between multiple methods or keep related functionality together.
 
-#### Creating a Controller Class
+We recommend placing these files in the `class/` directory.
 
-A controller class receives the `Odac` object in its constructor, giving you access to all services throughout your class methods:
+#### 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:
 
 ```javascript
-// controller/User.js
+// class/User.js
 class User {
   constructor(Odac) {
     this.Odac = Odac
@@ -15,10 +17,10 @@ class User {
 
   async getProfile() {
     const user = await this.Odac.Auth.user()
-    return this.Odac.return({
+    return {
       success: true,
       user: user
-    })
+    }
   }
 
   async updateProfile() {
@@ -34,60 +36,44 @@ class User {
     const email = await this.Odac.request('email')
 
     // Update user in database
-    await this.Odac.Mysql.query('UPDATE users SET name = ?, email = ? WHERE id = ?', [
-      name,
-      email,
-      this.Odac.Auth.user().id
-    ])
+    await this.Odac.DB.users.where('id', this.Odac.Auth.user().id).update({
+        name: name,
+        email: email
+    })
 
-    return this.Odac.return({
+    return {
       success: true,
       message: 'Profile updated successfully'
-    })
+    }
   }
 }
 
 module.exports = User
 ```
 
-#### Using Controller Classes in Routes
+#### Naming Collisions
 
-Once you've created a controller class, you can use it in your routes just like any other controller:
+If your class name conflicts with a built-in Odac service (like `Mail`, `DB`, `Auth`), it will be automatically placed under `Odac.App` namespace to prevent errors.
 
-```javascript
-// route/www.js
-Odac.Route.buff = 'www'
+Example: `class/Mail.js` (conflicts with core Mail) -> `Odac.App.Mail`
 
-// Access class methods using dot notation
-Odac.Route.get('/profile', 'User.getProfile')
-Odac.Route.post('/profile/update', 'User.updateProfile')
-```
-
-#### Accessing Classes in Controllers
+#### Accessing Services in Controllers
 
-Controller classes are automatically instantiated for each request and attached to the `Odac` object. You can access them from any controller:
+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
+  // Access your User class via Odac.User
   const profile = await Odac.User.getProfile()
   
   return Odac.return(profile)
 }
 ```
 
-#### Benefits of Controller Classes
-
-- **Organization**: Group related methods together
-- **Reusability**: Share logic between different routes
-- **Maintainability**: Easier to manage complex controllers
-- **Context**: The `Odac` object is always available via `this.Odac`
-
-#### Class vs Function Controllers
-
-Both approaches work perfectly fine. Use what makes sense for your project:
-
-- **Functions**: Great for simple, single-purpose controllers
-- **Classes**: Better for complex logic with multiple related methods
+#### Benefits of Service Classes
 
-The framework automatically detects whether your export is a class or a function and handles it accordingly.
+- **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.

package/docs/backend/05-forms/01-custom-forms.md

@@ -5,10 +5,10 @@ Odac provides an automatic form system with built-in validation, CSRF protection
 ## Basic Usage
 
 ```html
-<odac:form action="/contact/submit" method="POST">
-  <odac:field name="email" type="email" label="Email">
+<odac:form action="Contact.submit" method="POST">
+  <odac:input name="email" type="email" label="Email">
     <odac:validate rule="required|email" message="Valid email required"/>
-  </odac:field>
+  </odac:input>
   
   <odac:submit text="Send" loading="Sending..."/>
 </odac:form>
@@ -18,21 +18,23 @@ Odac provides an automatic form system with built-in validation, CSRF protection
 
 ### `<odac:form>`
 
-- `action` - Form submission URL (optional if using `table`)
+- `action` - Controller action `Controller.method` (optional if using `table`)
 - `method` - HTTP method (default: POST)
 - `table` - Database table name for automatic insert (optional)
 - `redirect` - Redirect URL after success (optional)
 - `success` - Success message (optional)
 - `class` - Additional CSS classes
 - `id` - Form ID attribute
+- `clear` - Set to `false` to disable auto-clearing inputs on success (optional)
 
 ```html
-<!-- With custom controller -->
-<odac:form action="/api/save" method="POST" class="my-form" id="contact-form">
+<!-- With custom controller action -->
+<!-- Executes 'submit' method in 'contact' controller -->
+<odac:form action="Contact.submit" method="POST" class="my-form" id="contact-form">
   <!-- fields here -->
 </odac:form>
 
-<!-- With automatic DB insert -->
+<!-- With automatic DB insert (no controller needed) -->
 <odac:form table="waitlist" redirect="/" success="Thank you for joining!">
   <!-- fields here -->
 </odac:form>
@@ -40,69 +42,69 @@ Odac provides an automatic form system with built-in validation, CSRF protection
 
 ## Field Types
 
-### `<odac:field>`
+### `<odac:input>`
 
 Supports all standard HTML input types:
 
 ```html
 <!-- Text input with multiple validations -->
-<odac:field name="username" type="text" label="Username" placeholder="Enter username">
+<odac:input name="username" type="text" label="Username" placeholder="Enter username">
   <odac:validate rule="required" message="Username is required"/>
   <odac:validate rule="minlen:3" message="Username must be at least 3 characters"/>
   <odac:validate rule="maxlen:20" message="Username cannot exceed 20 characters"/>
   <odac:validate rule="alphanumeric" message="Username can only contain letters and numbers"/>
-</odac:field>
+</odac:input>
 
 <!-- Email input -->
-<odac:field name="email" type="email" label="Email Address" placeholder="your@email.com">
+<odac:input name="email" type="email" label="Email Address" placeholder="your@email.com">
   <odac:validate rule="required" message="Email address is required"/>
   <odac:validate rule="email" message="Please enter a valid email address"/>
   <odac:validate rule="maxlen:100" message="Email is too long"/>
-</odac:field>
+</odac:input>
 
 <!-- Password input with strong validation -->
-<odac:field name="password" type="password" label="Password">
+<odac:input name="password" type="password" label="Password">
   <odac:validate rule="required" message="Password is required"/>
   <odac:validate rule="minlen:8" message="Password must be at least 8 characters long"/>
   <odac:validate rule="maxlen:50" message="Password is too long"/>
-</odac:field>
+</odac:input>
 
 <!-- Textarea with character limits -->
-<odac:field name="message" type="textarea" label="Your Message" placeholder="Tell us what you think...">
+<odac:input name="message" type="textarea" label="Your Message" placeholder="Tell us what you think...">
   <odac:validate rule="required" message="Please enter your message"/>
   <odac:validate rule="minlen:10" message="Message must be at least 10 characters"/>
   <odac:validate rule="maxlen:500" message="Message cannot exceed 500 characters"/>
-</odac:field>
+</odac:input>
 
 <!-- Checkbox for terms acceptance -->
-<odac:field name="agree" type="checkbox" label="I agree to the Terms of Service and Privacy Policy">
+<odac:input name="agree" type="checkbox" label="I agree to the Terms of Service and Privacy Policy">
   <odac:validate rule="accepted" message="You must accept the terms to continue"/>
-</odac:field>
+</odac:input>
 
 <!-- Number input with range -->
-<odac:field name="age" type="number" label="Your Age">
+<odac:input name="age" type="number" label="Your Age">
   <odac:validate rule="required" message="Age is required"/>
   <odac:validate rule="min:18" message="You must be at least 18 years old"/>
   <odac:validate rule="max:120" message="Please enter a valid age"/>
-</odac:field>
+</odac:input>
 
 <!-- Phone number -->
-<odac:field name="phone" type="text" label="Phone Number" placeholder="+1 (555) 123-4567">
+<odac:input name="phone" type="text" label="Phone Number" placeholder="+1 (555) 123-4567">
   <odac:validate rule="required" message="Phone number is required"/>
   <odac:validate rule="minlen:10" message="Phone number must be at least 10 digits"/>
-</odac:field>
+</odac:input>
 
 <!-- URL input -->
-<odac:field name="website" type="url" label="Website" placeholder="https://example.com">
+<odac:input name="website" type="url" label="Website" placeholder="https://example.com">
   <odac:validate rule="url" message="Please enter a valid URL"/>
-</odac:field>
+</odac:input>
 
 <!-- Name with alpha validation -->
-<odac:field name="full_name" type="text" label="Full Name" placeholder="John Doe">
+<odac:input name="full_name" type="text" label="Full Name" placeholder="John Doe">
   <odac:validate rule="required" message="Full name is required"/>
   <odac:validate rule="minlen:2" message="Name must be at least 2 characters"/>
   <odac:validate rule="maxlen:50" message="Name is too long"/>
-</odac:field>
+</odac:input>
 ```
 
 ### Field Attributes
@@ -121,9 +123,9 @@ Supports all standard HTML input types:
 Add validation rules to fields:
 
 ```html
-<odac:field name="username" type="text">
+<odac:input name="username" type="text">
   <odac:validate rule="required|minlen:3|maxlen:20" message="Username must be 3-20 characters"/>
-</odac:field>
+</odac:input>
 ```
 
 ### Available Rules
@@ -202,59 +204,64 @@ Automatically set field values without user input:
 <odac:submit text="Save" loading="Saving..." class="btn btn-primary" id="save-btn"/>
 ```
 
-## Controller Handler
+## Controller Handler (Server Actions)
+ 
+Handle form submission directly in your controller. The action is defined as `ControllerName.methodName`.
 
-Handle form submission in your controller:
+**View:**
+```html
+<odac:form action="Contact.submit">
+    ...
+</odac:form>
+```
+
+**Controller (controller/Contact.js):**
 
 ```javascript
-module.exports = {
-  submit: Odac => {
-    // Access validated form data
-    const data = Odac.formData
-    
-    // data contains all field values
-    console.log(data.email, data.message)
-    
-    // Process the data (save to database, send email, etc.)
-    
-    // Return success response
-    return Odac.return({
-      result: {
-        success: true,
-        message: 'Form submitted successfully!',
-        redirect: '/thank-you' // Optional redirect
-      }
-    })
+module.exports = class Contact {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async submit(form) {
+    // 1. Access validated clean data
+    const { email, message } = form.data
+
+    // 2. Perform your logic
+    // await this.Odac.Mail().send(email, message)
+
+    // 3. Return success easily
+    return form.success('Message sent successfully!', '/thank-you')
   }
 }
 ```
 
 ### Error Handling
 
-Return validation errors:
+Return errors using the helper method:
 
 ```javascript
-module.exports = {
-  submit: Odac => {
-    const data = Odac.formData
+module.exports = class Contact {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async submit(form) {
+    const { email } = form.data
     
-    // Custom validation
-    if (data.email.includes('spam')) {
-      return Odac.return({
-        result: {success: false},
-        errors: {
-          email: 'This email is not allowed'
-        }
-      })
+    // Custom backend validation
+    if (email.includes('spam')) {
+      // Returns field-specific error
+      return form.error('email', 'Spam is not allowed!')
     }
     
-    return Odac.return({
-      result: {success: true, message: 'Success!'}
-    })
+    return form.success('Success!')
   }
 }
 ```
 
+**Note:** No route definition is needed for the action! The form system handles the routing securely.
+
 ## Automatic Database Insert
 
 Forms can automatically insert data into database without writing a controller:
@@ -263,13 +270,13 @@ Forms can automatically insert data into database without writing a controller:
 
 ```html
 <odac:form table="waitlist" redirect="/" success="Thank you for joining!">
-  <odac:field name="email" type="email" label="Email">
+  <odac:input name="email" type="email" label="Email">
     <odac:validate rule="required|email|unique" message="Valid email required"/>
-  </odac:field>
+  </odac:input>
   
-  <odac:field name="name" type="text" label="Name">
+  <odac:input name="name" type="text" label="Name">
     <odac:validate rule="required|minlen:2" message="Name required"/>
-  </odac:field>
+  </odac:input>
   
   <odac:set name="created_at" compute="now"/>
   <odac:set name="ip" compute="ip"/>
@@ -312,22 +319,22 @@ That's it! No controller needed. The form will:
 <div class="contact-page">
   <h1>Contact Us</h1>
   
-  <odac:form action="/contact/submit" method="POST" class="contact-form">
-    <odac:field name="name" type="text" label="Your Name" placeholder="Enter your name">
+  <odac:form action="Contact.submit" method="POST" class="contact-form">
+    <odac:input name="name" type="text" label="Your Name" placeholder="Enter your name">
       <odac:validate rule="required|minlen:3" message="Name must be at least 3 characters"/>
-    </odac:field>
+    </odac:input>
     
-    <odac:field name="email" type="email" label="Email" placeholder="your@email.com">
+    <odac:input name="email" type="email" label="Email" placeholder="your@email.com">
       <odac:validate rule="required|email" message="Please enter a valid email"/>
-    </odac:field>
+    </odac:input>
     
-    <odac:field name="subject" type="text" label="Subject" placeholder="What is this about?">
+    <odac:input name="subject" type="text" label="Subject" placeholder="What is this about?">
       <odac:validate rule="required|minlen:5" message="Subject must be at least 5 characters"/>
-    </odac:field>
+    </odac:input>
     
-    <odac:field name="message" type="textarea" label="Message" placeholder="Your message...">
+    <odac:input name="message" type="textarea" label="Message" placeholder="Your message...">
       <odac:validate rule="required|minlen:10" message="Message must be at least 10 characters"/>
-    </odac:field>
+    </odac:input>
     
     <odac:submit text="Send Message" loading="Sending..." class="btn btn-primary"/>
   </odac:form>
@@ -337,29 +344,29 @@ That's it! No controller needed. The form will:
 ### Controller (controller/contact.js)
 
 ```javascript
-module.exports = {
-  index: Odac => {
-    Odac.View.skeleton('default')
-    Odac.View.set({content: 'contact'})
-    Odac.View.print()
-  },
-
-  submit: Odac => {
-    const data = Odac.formData
+module.exports = class Contact {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async index() {
+    this.Odac.View.skeleton('default')
+    this.Odac.View.set({content: 'contact'})
+    this.Odac.View.print()
+  }
+
+  async submit(form) {
+    // Get validated data from form helper
+    const { name, email, subject, message } = form.data
     
     // Save to database
-    // await Odac.Mysql.query('INSERT INTO contacts SET ?', data)
+    // Save to database
+    // await this.Odac.DB.contacts.insert({ name, email, subject, message })
     
     // Send email notification
-    // await Odac.Mail().to('admin@example.com').subject('New Contact').send(data.message)
+    // await this.Odac.Mail().to('admin@example.com').subject('New Contact').send(message)
     
-    return Odac.return({
-      result: {
-        success: true,
-        message: 'Thank you! We will get back to you soon.',
-        redirect: '/'
-      }
-    })
+    return form.success('Thank you! We will get back to you soon.', '/')
   }
 }
 ```
@@ -368,7 +375,7 @@ module.exports = {
 
 ```javascript
 Odac.Route.page('/contact', 'contact')
-Odac.Route.post('/contact/submit', 'contact.submit')
+// Note: No route needed for contact.submit action!
 ```
 
 ## Features
@@ -380,6 +387,7 @@ Odac.Route.post('/contact/submit', 'contact.submit')
 - **Loading States** - Automatic button state management
 - **Error Display** - Automatic error message rendering
 - **Success Messages** - Built-in success message handling
+- **Auto-Clear** - Clears inputs on success (disable with `clear="false"`)
 - **Redirect Support** - Optional redirect after successful submission
 
 ## Security