odac 1.0.1 → 1.2.0

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

@@ -1,24 +1,46 @@
-## 🎓 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:
+### ❓ 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 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
-// controller/User.js
+// class/User.js
 class User {
   constructor(Odac) {
     this.Odac = Odac
   }
 
+
   async getProfile() {
     const user = await this.Odac.Auth.user()
-    return this.Odac.return({
+    return {
       success: true,
       user: user
-    })
+    }
   }
 
   async updateProfile() {
@@ -34,60 +56,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
-
-Once you've created a controller class, you can use it in your routes just like any other controller:
-
-```javascript
-// route/www.js
-Odac.Route.buff = 'www'
-
-// Access class methods using dot notation
-Odac.Route.get('/profile', 'User.getProfile')
-Odac.Route.post('/profile/update', 'User.updateProfile')
-```
-
-#### Accessing Classes in Controllers
-
-Controller classes are automatically instantiated for each request and attached to the `Odac` object. You can access them from any controller:
-
-```javascript
-module.exports = async function (Odac) {
-  // Access your User class
-  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
-
-The framework automatically detects whether your export is a class or a function and handles it accordingly.
+#### Naming Collisions
+
+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.
+
+Example: `class/Mail.js` (conflicts with core Mail) -> `Odac.App.Mail`
+
+#### Accessing Services in Controllers
+ 
+ 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/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

package/docs/backend/05-forms/02-automatic-database-insert.md

@@ -6,9 +6,9 @@ Forms can automatically insert data into your database without writing any contr
 
 ```html
 <odac:form table="waitlist">
-  <odac:field name="email" type="email" label="Email">
+  <odac:input name="email" type="email" label="Email">
     <odac:validate rule="required|email|unique"/>
-  </odac:field>
+  </odac:input>
   
   <odac:submit text="Join"/>
 </odac:form>
@@ -45,13 +45,13 @@ CREATE TABLE `waitlist` (
   <h1>Join Our Waitlist</h1>
   
   <odac:form table="waitlist" redirect="/" success="Thank you for joining!">
-    <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|unique" message="Please enter a valid email"/>
-    </odac:field>
+    </odac:input>
     
-    <odac:field name="name" type="text" label="Name" placeholder="Your name">
+    <odac:input name="name" type="text" label="Name" placeholder="Your name">
       <odac:validate rule="required|minlen:2" message="Name is required"/>
-    </odac:field>
+    </odac:input>
     
     <odac:set name="created_at" compute="now"/>
     <odac:set name="ip" compute="ip"/>
@@ -110,9 +110,9 @@ Custom success message to display.
 Use `unique` rule to prevent duplicate entries:
 
 ```html
-<odac:field name="email" type="email">
+<odac:input name="email" type="email">
   <odac:validate rule="required|email|unique" message="This email is already registered"/>
-</odac:field>
+</odac:input>
 ```
 
 The system will:
@@ -163,9 +163,9 @@ Only set if field is empty:
 
 ```html
 <odac:form table="newsletter" success="Thanks for subscribing!">
-  <odac:field name="email" type="email">
+  <odac:input name="email" type="email">
     <odac:validate rule="required|email|unique"/>
-  </odac:field>
+  </odac:input>
   
   <odac:set name="subscribed_at" compute="now"/>
   <odac:set name="status" value="active"/>
@@ -178,13 +178,13 @@ Only set if field is empty:
 
 ```html
 <odac:form table="feedback" redirect="/" success="Thank you for your feedback!">
-  <odac:field name="rating" type="number" label="Rating (1-5)">
+  <odac:input name="rating" type="number" label="Rating (1-5)">
     <odac:validate rule="required|min:1|max:5"/>
-  </odac:field>
+  </odac:input>
   
-  <odac:field name="comment" type="textarea" label="Comment">
+  <odac:input name="comment" type="textarea" label="Comment">
     <odac:validate rule="required|minlen:10"/>
-  </odac:field>
+  </odac:input>
   
   <odac:set name="created_at" compute="now"/>
   <odac:set name="ip" compute="ip"/>
@@ -197,17 +197,17 @@ Only set if field is empty:
 
 ```html
 <odac:form table="beta_requests" success="You're on the list!">
-  <odac:field name="email" type="email">
+  <odac:input name="email" type="email">
     <odac:validate rule="required|email|unique"/>
-  </odac:field>
+  </odac:input>
   
-  <odac:field name="company" type="text">
+  <odac:input name="company" type="text">
     <odac:validate rule="required"/>
-  </odac:field>
+  </odac:input>
   
-  <odac:field name="use_case" type="textarea">
+  <odac:input name="use_case" type="textarea">
     <odac:validate rule="required|minlen:20"/>
-  </odac:field>
+  </odac:input>
   
   <odac:set name="requested_at" compute="now"/>
   <odac:set name="status" value="pending"/>
@@ -270,7 +270,7 @@ Odac.Route.post('/contact/submit', async Odac => {
   await sendEmail(Odac.formData.email, 'Thank you!')
   
   // Manually insert to database if needed
-  await Odac.Mysql.query('INSERT INTO contacts SET ?', Odac.formData)
+  await Odac.DB.contacts.insert(Odac.formData)
   
   return Odac.return({
     result: {success: true, message: 'Message sent!'}

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)
+}
+```

package/docs/backend/07-views/02-rendering-a-view.md

@@ -118,7 +118,7 @@ Create a separate view part for the `<head>` section:
 ```javascript
 module.exports = async function (Odac) {
   const productId = Odac.Request.get('id')
-  const product = await Odac.Mysql.table('products')
+  const product = await Odac.DB.table('products')
     .where('id', productId)
     .first()