odac 0.9.0

package/docs/backend/13-utilities/01-candy-var.md

@@ -0,0 +1,504 @@
+## 🔧 Candy.Var - String Manipulation & Validation
+
+`Candy.Var` is a powerful utility class for string manipulation, validation, encryption, and formatting. It provides a chainable, fluent interface for common string operations.
+
+### Basic Usage
+
+```javascript
+// Create a Var instance
+const result = Candy.Var('hello world').slug()
+// Returns: 'hello-world'
+
+// Chain multiple operations
+const email = Candy.Var('  USER@EXAMPLE.COM  ').trim().toLowerCase()
+```
+
+### String Validation
+
+Check if a string matches specific patterns:
+
+#### is() - Single Validation
+
+```javascript
+// Email validation
+Candy.Var('user@example.com').is('email')  // true
+Candy.Var('invalid-email').is('email')     // false
+
+// Numeric validation
+Candy.Var('12345').is('numeric')           // true
+Candy.Var('abc123').is('numeric')          // false
+
+// Multiple conditions (AND logic)
+Candy.Var('abc123').is('alphanumeric')     // true
+```
+
+#### isAny() - Multiple Validation (OR logic)
+
+```javascript
+// Check if value matches ANY of the conditions
+Candy.Var('user@example.com').isAny('email', 'domain')  // true
+Candy.Var('example.com').isAny('email', 'domain')       // true
+```
+
+#### Available Validation Types
+
+```javascript
+'alpha'              // Only letters (A-Z, a-z)
+'alphaspace'         // Letters and spaces
+'alphanumeric'       // Letters and numbers
+'alphanumericspace'  // Letters, numbers, and spaces
+'bcrypt'             // BCrypt hash format
+'date'               // Valid date string
+'domain'             // Valid domain name (example.com)
+'email'              // Valid email address
+'float'              // Floating point number
+'host'               // IP address
+'ip'                 // IP address
+'json'               // Valid JSON string
+'mac'                // MAC address
+'md5'                // MD5 hash
+'numeric'            // Numbers only
+'url'                // Valid URL
+'emoji'              // Contains emoji
+'xss'                // XSS-safe (no HTML tags)
+```
+
+#### Practical Examples
+
+```javascript
+// Controller validation
+module.exports = async function(Candy) {
+  const email = Candy.Request.post('email')
+  
+  if (!Candy.Var(email).is('email')) {
+    return Candy.return({
+      success: false,
+      message: 'Invalid email address'
+    })
+  }
+  
+  // Continue with valid email
+}
+```
+
+### String Checking
+
+#### contains() - Check if string contains values
+
+```javascript
+// Single value
+Candy.Var('hello world').contains('world')  // true
+Candy.Var('hello world').contains('foo')    // false
+
+// Multiple values (AND logic - must contain all)
+Candy.Var('hello world').contains('hello', 'world')  // true
+Candy.Var('hello world').contains('hello', 'foo')    // false
+```
+
+#### containsAny() - Check if string contains any value
+
+```javascript
+// Check if contains ANY of the values (OR logic)
+Candy.Var('hello world').containsAny('foo', 'world')  // true
+Candy.Var('hello world').containsAny('foo', 'bar')    // false
+```
+
+#### isBegin() - Check if string starts with value
+
+```javascript
+Candy.Var('hello world').isBegin('hello')  // true
+Candy.Var('hello world').isBegin('world')  // false
+
+// Multiple options
+Candy.Var('https://example.com').isBegin('http://', 'https://')  // true
+```
+
+#### isEnd() - Check if string ends with value
+
+```javascript
+Candy.Var('hello world').isEnd('world')  // true
+Candy.Var('hello world').isEnd('hello')  // false
+
+// Multiple options
+Candy.Var('image.jpg').isEnd('.jpg', '.png', '.gif')  // true
+```
+
+### String Manipulation
+
+#### replace() - Replace text
+
+```javascript
+// Simple replacement
+Candy.Var('hello world').replace('world', 'universe')
+// Returns: 'hello universe'
+
+// Multiple replacements with object
+Candy.Var('Hello {{name}}, welcome to {{site}}').replace({
+  '{{name}}': 'John',
+  '{{site}}': 'CandyPack'
+})
+// Returns: 'Hello John, welcome to CandyPack'
+
+// Works with arrays/objects recursively
+const data = {
+  title: 'Welcome {{name}}',
+  message: 'Hello {{name}}'
+}
+Candy.Var(data).replace({'{{name}}': 'John'})
+// Returns: { title: 'Welcome John', message: 'Hello John' }
+```
+
+#### clear() - Remove specific strings
+
+```javascript
+Candy.Var('hello-world-test').clear('-')
+// Returns: 'helloworldtest'
+
+// Remove multiple strings
+Candy.Var('a1b2c3').clear('1', '2', '3')
+// Returns: 'abc'
+```
+
+#### slug() - Create URL-friendly slug
+
+```javascript
+Candy.Var('Hello World!').slug()
+// Returns: 'hello-world'
+
+Candy.Var('Product Name 2024').slug()
+// Returns: 'product-name-2024'
+
+// Custom separator
+Candy.Var('Hello World').slug('_')
+// Returns: 'hello_world'
+```
+
+#### format() - Format string with pattern
+
+```javascript
+// ? = single character, * = rest of string
+Candy.Var('1234567890').format('(???) ???-????')
+// Returns: '(123) 456-7890'
+
+Candy.Var('TR1234567890').format('?? *')
+// Returns: 'TR 1234567890'
+```
+
+#### html() - Escape HTML
+
+```javascript
+Candy.Var('<script>alert("xss")</script>').html()
+// Returns: '&lt;script&gt;alert("xss")&lt;/script&gt;'
+```
+
+### Encryption & Hashing
+
+#### hash() - BCrypt password hashing
+
+```javascript
+// Hash a password
+const hashedPassword = Candy.Var('mypassword').hash()
+// Returns: '$2b$10$...' (BCrypt hash)
+
+// Custom salt rounds
+const hashedPassword = Candy.Var('mypassword').hash(12)
+```
+
+#### hashCheck() - Verify BCrypt hash
+
+```javascript
+const hashedPassword = '$2b$10$...'
+const isValid = Candy.Var(hashedPassword).hashCheck('mypassword')
+// Returns: true or false
+```
+
+#### md5() - MD5 hash
+
+```javascript
+Candy.Var('hello').md5()
+// Returns: '5d41402abc4b2a76b9719d911017c592'
+```
+
+#### encrypt() - AES-256 encryption
+
+```javascript
+// Uses key from Candy.Config.encrypt.key
+const encrypted = Candy.Var('secret data').encrypt()
+
+// Custom encryption key
+const encrypted = Candy.Var('secret data').encrypt('my-32-character-encryption-key')
+```
+
+#### decrypt() - AES-256 decryption
+
+```javascript
+// Uses key from Candy.Config.encrypt.key
+const decrypted = Candy.Var(encryptedData).decrypt()
+
+// Custom decryption key
+const decrypted = Candy.Var(encryptedData).decrypt('my-32-character-encryption-key')
+```
+
+### Date Formatting
+
+#### date() - Format date strings
+
+```javascript
+const timestamp = '2024-03-15 14:30:45'
+
+Candy.Var(timestamp).date('Y-m-d')
+// Returns: '2024-03-15'
+
+Candy.Var(timestamp).date('d/m/Y')
+// Returns: '15/03/2024'
+
+Candy.Var(timestamp).date('H:i:s')
+// Returns: '14:30:45'
+
+Candy.Var(timestamp).date('Y-m-d H:i')
+// Returns: '2024-03-15 14:30'
+```
+
+**Format tokens:**
+- `Y` - 4-digit year (2024)
+- `y` - 2-digit year (24)
+- `m` - Month with leading zero (01-12)
+- `d` - Day with leading zero (01-31)
+- `H` - Hour with leading zero (00-23)
+- `i` - Minute with leading zero (00-59)
+- `s` - Second with leading zero (00-59)
+
+### File Operations
+
+#### save() - Save string to file
+
+```javascript
+// Save content to file
+Candy.Var('Hello World').save('/path/to/file.txt')
+
+// Automatically creates directories if needed
+Candy.Var(jsonData).save('/path/to/nested/dir/data.json')
+```
+
+### Practical Examples
+
+#### User Registration with Validation
+
+```javascript
+module.exports = async function(Candy) {
+  const email = Candy.Request.post('email')
+  const password = Candy.Request.post('password')
+  const username = Candy.Request.post('username')
+  
+  // Validate email
+  if (!Candy.Var(email).is('email')) {
+    return Candy.return({
+      success: false,
+      message: 'Invalid email address'
+    })
+  }
+  
+  // Validate username (alphanumeric only)
+  if (!Candy.Var(username).is('alphanumeric')) {
+    return Candy.return({
+      success: false,
+      message: 'Username must be alphanumeric'
+    })
+  }
+  
+  // Hash password
+  const hashedPassword = Candy.Var(password).hash()
+  
+  // Create slug for profile URL
+  const profileSlug = Candy.Var(username).slug()
+  
+  // Save user
+  await Candy.Mysql.table('users').insert({
+    email: email,
+    username: username,
+    password: hashedPassword,
+    slug: profileSlug
+  })
+  
+  return Candy.return({success: true})
+}
+```
+
+#### Login with Password Verification
+
+```javascript
+module.exports = async function(Candy) {
+  const email = Candy.Request.post('email')
+  const password = Candy.Request.post('password')
+  
+  // Find user
+  const user = await Candy.Mysql.table('users')
+    .where('email', email)
+    .first()
+  
+  if (!user) {
+    return Candy.return({
+      success: false,
+      message: 'User not found'
+    })
+  }
+  
+  // Verify password
+  const isValid = Candy.Var(user.password).hashCheck(password)
+  
+  if (!isValid) {
+    return Candy.return({
+      success: false,
+      message: 'Invalid password'
+    })
+  }
+  
+  // Login successful
+  Candy.Auth.login(user.id)
+  return Candy.return({success: true})
+}
+```
+
+#### URL Slug Generation
+
+```javascript
+module.exports = async function(Candy) {
+  const title = Candy.Request.post('title')
+  
+  // Create URL-friendly slug
+  const slug = Candy.Var(title).slug()
+  
+  // Check if slug exists
+  const exists = await Candy.Mysql.table('posts')
+    .where('slug', slug)
+    .first()
+  
+  if (exists) {
+    // Add timestamp to make unique
+    const uniqueSlug = `${slug}-${Date.now()}`
+    await Candy.Mysql.table('posts').insert({
+      title: title,
+      slug: uniqueSlug
+    })
+  } else {
+    await Candy.Mysql.table('posts').insert({
+      title: title,
+      slug: slug
+    })
+  }
+  
+  return Candy.return({success: true})
+}
+```
+
+#### Template Variable Replacement
+
+```javascript
+module.exports = async function(Candy) {
+  const user = await Candy.Auth.user()
+  
+  // Email template
+  const template = `
+    Hello {{name}},
+    
+    Your account {{email}} has been verified.
+    You can now access your dashboard at {{url}}.
+    
+    Thanks,
+    {{site}}
+  `
+  
+  // Replace variables
+  const emailContent = Candy.Var(template).replace({
+    '{{name}}': user.name,
+    '{{email}}': user.email,
+    '{{url}}': 'https://example.com/dashboard',
+    '{{site}}': 'CandyPack'
+  })
+  
+  // Send email
+  await Candy.Mail.send({
+    to: user.email,
+    subject: 'Account Verified',
+    body: emailContent
+  })
+  
+  return Candy.return({success: true})
+}
+```
+
+#### Phone Number Formatting
+
+```javascript
+module.exports = async function(Candy) {
+  const phone = Candy.Request.post('phone')
+  
+  // Remove all non-numeric characters
+  const cleanPhone = Candy.Var(phone).clear('-', ' ', '(', ')', '+')
+  
+  // Validate it's numeric
+  if (!Candy.Var(cleanPhone).is('numeric')) {
+    return Candy.return({
+      success: false,
+      message: 'Invalid phone number'
+    })
+  }
+  
+  // Format for display
+  const formattedPhone = Candy.Var(cleanPhone).format('(???) ???-????')
+  
+  return Candy.return({
+    success: true,
+    phone: formattedPhone
+  })
+}
+```
+
+#### Data Encryption for Storage
+
+```javascript
+module.exports = async function(Candy) {
+  const creditCard = Candy.Request.post('credit_card')
+  
+  // Encrypt sensitive data
+  const encryptedCard = Candy.Var(creditCard).encrypt()
+  
+  // Save encrypted data
+  await Candy.Mysql.table('payments').insert({
+    user_id: Candy.Auth.id(),
+    card: encryptedCard
+  })
+  
+  return Candy.return({success: true})
+}
+
+// Later, to retrieve and decrypt
+module.exports = async function(Candy) {
+  const payment = await Candy.Mysql.table('payments')
+    .where('user_id', Candy.Auth.id())
+    .first()
+  
+  // Decrypt data
+  const creditCard = Candy.Var(payment.card).decrypt()
+  
+  return Candy.return({
+    card: creditCard
+  })
+}
+```
+
+### Best Practices
+
+1. **Always validate user input** before processing
+2. **Use hash() for passwords**, never store plain text
+3. **Use encrypt() for sensitive data** like credit cards, SSNs
+4. **Create slugs for URLs** to make them SEO-friendly
+5. **Sanitize HTML** with html() to prevent XSS attacks
+6. **Use isBegin/isEnd** for protocol or file extension checks
+
+### Notes
+
+- `Candy.Var()` returns the processed string value, not a Var instance (except for chaining)
+- Encryption uses AES-256-CBC with a fixed IV
+- BCrypt hashing is one-way and cannot be decrypted
+- Date formatting works with any valid JavaScript date string

package/docs/frontend/01-overview/01-introduction.md

@@ -0,0 +1,146 @@
+# Frontend Javascript Framework: candy.js
+
+`candy.js` is a lightweight frontend JavaScript framework designed to simplify interactions with the backend, handle forms, and manage page-specific logic within the CandyPack ecosystem. It provides a set of tools for event handling, AJAX requests, and more, all accessible through the global `Candy` object.
+
+## The Global `Candy` Object
+
+After including `candy.js` in your page, you will have access to a global `Candy` object. This object is the main entry point for all the features of the framework.
+
+## Core Concepts
+
+### Actions
+
+Actions are the fundamental building block of `candy.js`. An action is a collection of event handlers and lifecycle callbacks that define the behavior of a page or a component.
+
+### Pages
+
+`candy.js` has a concept of "pages", which allows you to scope your JavaScript to a specific page. The current page identifier is determined by the backend based on:
+- **Controller name** when using controller files (e.g., `'user'` for `controller/page/user.js`)
+- **View name** when using view objects (e.g., `'dashboard'` from `{content: 'dashboard'}`)
+- This identifier is accessible via `Candy.page()` and stored in `data-candy-page` attribute on the `<html>` element.
+
+### Lifecycle Events
+
+`candy.js` provides several lifecycle events that you can hook into:
+-   `start`: Fired once when the script is initialized.
+-   `load`: Fired on every page load, after the DOM is ready.
+-   `page`: Fired on a specific page, after the DOM is ready.
+-   `interval`: Fired repeatedly at a specified interval.
+
+## Event Handling with `Candy.action()`
+
+The `Candy.action()` method is the most important method in the framework. It allows you to register event handlers and lifecycle callbacks.
+
+```javascript
+Candy.action({
+    // Fired once on DOMContentLoaded
+    start: function() {
+        console.log('Candy.js started!');
+    },
+
+    // Fired on every page load
+    load: function() {
+        console.log('Page loaded!');
+    },
+
+    // Fired only on the 'home' page
+    page: {
+        home: function() {
+            console.log('Welcome to the home page!');
+        }
+    },
+
+    // Fired every 2 seconds on the 'dashboard' page
+    interval: {
+        myInterval: {
+            interval: 2000,
+            page: 'dashboard',
+            function: function() {
+                console.log('Dashboard is refreshing...');
+            }
+        }
+    },
+
+    // Event handlers
+    click: {
+        '#my-button': function() {
+            alert('Button clicked!');
+        }
+    },
+
+    // You can also define functions and reference them
+    fn: {
+        myFunction: function() {
+            alert('This is my function!');
+        }
+    },
+
+    // And then use them in your event handlers
+    mouseover: {
+        '#my-element': 'fn.myFunction'
+    }
+});
+```
+
+## Working with Forms using `Candy.form()`
+
+`Candy.form()` simplifies AJAX form submissions. It handles serialization, validation feedback, success messages, and file uploads automatically.
+
+```javascript
+// Basic usage
+Candy.form('#my-form', function(data) {
+    // This callback is executed on success
+    console.log('Form submitted successfully!', data);
+});
+
+// With options
+Candy.form({
+    form: '#my-form',
+    messages: ['success', 'error'], // Show both success and error messages
+    loading: function(percent) {
+        console.log('Upload progress:', percent + '%');
+    }
+}, function(data) {
+    // Success callback
+    if (data.result.success) {
+        window.location.href = '/thank-you';
+    }
+});
+```
+To display validation errors, you can add elements with the `candy-form-error` attribute to your form. The value of the attribute should be the `name` of the input field.
+
+```html
+<input type="text" name="email">
+<span candy-form-error="email"></span>
+```
+
+## Making AJAX requests with `Candy.get()`
+
+For simple GET requests, you can use the `Candy.get()` method.
+
+```javascript
+Candy.get('/api/users', function(data) {
+    console.log('Users:', data);
+});
+```
+
+## Managing CSRF tokens with `Candy.token()`
+
+`candy.js` automatically manages CSRF tokens for you. The `Candy.token()` method will return a valid token for your requests. The `Candy.form()` and `Candy.get()` methods use this automatically, so you usually don't need to call it yourself.
+
+## Other Utility Functions
+
+-   **`Candy.client()`**: Returns a unique client identifier from a cookie.
+-   **`Candy.data()`**: Returns data from the `candy_data` cookie, which is set by the backend. This data includes the current page and the initial CSRF token.
+-   **`Candy.page()`**: Returns the identifier of the current page. This is the controller name (e.g., `'user'`) or view name (e.g., `'dashboard'`) set by the backend. Use this to conditionally run code for specific pages.
+-   **`Candy.storage()`**: A wrapper for `localStorage`.
+    ```javascript
+    // Set a value
+    Candy.storage('my-key', 'my-value');
+
+    // Get a value
+    let value = Candy.storage('my-key');
+
+    // Remove a value
+    Candy.storage('my-key', null);
+    ```