odac 0.9.0

package/docs/backend/04-routing/04-authentication-aware-routes.md

@@ -0,0 +1,48 @@
+## 🔐 Authentication-Aware Routes
+
+These methods let you define routes that require authentication. Only logged-in users can access these routes.
+
+#### `auth.page(path, controller)`
+Defines a page route that requires authentication.
+
+```javascript
+// Only authenticated users can access the dashboard
+Candy.Route.auth.page('/dashboard', 'dashboard.index');
+```
+
+#### `auth.page(path, viewConfig)`
+Defines a controller-less page route that requires authentication.
+
+```javascript
+// Only authenticated users can see this view
+Candy.Route.auth.page('/profile', {
+  skeleton: 'main',
+  head: 'profile.head',
+  content: 'profile',
+  script: 'profile'
+});
+```
+
+#### `auth.get(path, controller, options)`
+Defines a GET route that requires authentication.
+
+```javascript
+// API endpoint for authenticated users only
+Candy.Route.auth.get('/api/user/profile', 'api.user.profile');
+```
+
+#### `auth.post(path, controller, options)`
+Defines a POST route that requires authentication.
+
+```javascript
+// Only authenticated users can update their profile
+Candy.Route.auth.post('/api/user/update', 'api.user.update');
+```
+
+#### CSRF Token Protection
+By default, all POST and GET routes have CSRF token protection enabled. You can disable it with the `token` option:
+
+```javascript
+// Disable CSRF token check for this route
+Candy.Route.auth.post('/api/webhook', 'api.webhook', {token: false});
+```

package/docs/backend/04-routing/05-advanced-routing.md

@@ -0,0 +1,14 @@
+## 🛠️ Advanced Routing
+
+#### `set(type, path, controller, options)`
+This is the powerful base method that all other routing methods use internally. You can use it to create routes for any custom type.
+
+-   `type`: A string defining the route type (e.g., `page`, `post`, `#page` for authenticated pages, etc.).
+
+```javascript
+// This is equivalent to Candy.Route.post('/register', 'auth.register')
+Candy.Route.set('post', '/register', 'auth.register');
+
+// This creates an authenticated page route
+Candy.Route.set('#page', '/account', 'account.settings');
+```

package/docs/backend/04-routing/06-error-pages.md

@@ -0,0 +1,101 @@
+## 🚨 Error Pages
+
+CandyPack framework provides built-in error handling with customizable error pages for different HTTP status codes. You can define custom error pages to provide a better user experience when things go wrong.
+
+#### `error(statusCode, controller)`
+Maps HTTP error status codes to custom controller handlers. This allows you to create branded error pages instead of showing generic browser error messages.
+
+-   `statusCode`: The HTTP status code to handle (e.g., `404`, `500`).
+-   `controller`: The name of the controller file to handle this error.
+
+```javascript
+// Custom 404 Not Found page
+Candy.Route.error(404, 'errors/not-found');
+
+// Custom 500 Internal Server Error page
+Candy.Route.error(500, 'errors/server-error');
+
+// Custom 403 Forbidden page
+Candy.Route.error(403, 'errors/forbidden');
+```
+
+#### Common Error Status Codes
+
+- **404 Not Found**: Page or resource doesn't exist
+- **403 Forbidden**: Access denied to the resource
+- **500 Internal Server Error**: Server-side error occurred
+- **401 Unauthorized**: Authentication required
+- **400 Bad Request**: Invalid request format
+
+#### Error Controller Example
+
+Create error controllers in your `controller/errors/` directory:
+
+```javascript
+// controller/errors/not-found.js
+module.exports = function() {
+    Candy.response.status(404);
+    return Candy.view('errors/404', {
+        title: 'Page Not Found',
+        message: 'The page you are looking for could not be found.'
+    });
+};
+```
+
+```javascript
+// controller/errors/server-error.js
+module.exports = function() {
+    Candy.response.status(500);
+    return Candy.view('errors/500', {
+        title: 'Server Error',
+        message: 'Something went wrong on our end. Please try again later.'
+    });
+};
+```
+
+#### Error Views
+
+Create corresponding view templates in your `view/errors/` directory:
+
+```html
+<!-- view/errors/404.html -->
+<!DOCTYPE html>
+<html>
+<head>
+    <title>{{title}}</title>
+</head>
+<body>
+    <h1>404 - Page Not Found</h1>
+    <p>{{message}}</p>
+    <a href="/">Go back to homepage</a>
+</body>
+</html>
+```
+
+#### Default Error Handling
+
+If no custom error page is defined, CandyPack will fall back to its built-in error responses. It's recommended to at least define custom 404 and 500 error pages for a professional user experience.
+
+#### Error Context
+
+Error controllers receive the same Candy context as regular controllers, allowing you to:
+
+- Access request information (`Candy.request`)
+- Use database connections (`Candy.db`)
+- Render views with data (`Candy.view`)
+- Redirect users (`Candy.redirect`)
+- Log error details for debugging
+
+```javascript
+// controller/errors/server-error.js
+module.exports = function() {
+    // Log the error for debugging
+    console.error('Server error occurred:', Candy.request.url);
+    
+    Candy.response.status(500);
+    return Candy.view('errors/500', {
+        title: 'Oops! Something went wrong',
+        supportEmail: 'support@yoursite.com'
+    });
+};
+```

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

@@ -0,0 +1,149 @@
+# Cron Jobs
+
+The CandyPack framework provides a built-in cron system for running automated tasks. This system checks every minute and executes jobs based on specified conditions.
+
+## Basic Usage
+
+Use the `Candy.Route.cron()` method to define cron jobs:
+
+```javascript
+// With controller file
+Candy.Route.cron('backup').everyDay(1) // Runs every day
+
+// With direct function
+Candy.Route.cron(() => {
+  console.log('Task executed!')
+}).everyHour(2) // Runs every 2 hours
+```
+
+## Controller Files
+
+Controller files for cron jobs are created in the `controller/cron/` directory:
+
+```javascript
+// controller/cron/backup.js
+module.exports = () => {
+  console.log('Backup process started')
+  // Backup code...
+}
+```
+
+For module-based organization:
+
+```javascript
+// controller/admin/cron/cleanup.js
+module.exports = () => {
+  console.log('Cleanup process')
+}
+
+// Usage
+Candy.Route.cron('admin.cleanup').everyDay(1)
+```
+
+## Direct Function Usage
+
+You can also define cron jobs with inline functions:
+
+```javascript
+// Simple inline function
+Candy.Route.cron(() => console.log('Simple task running')).everyMinute(5)
+
+// Async function
+Candy.Route.cron(async () => {
+  const data = await fetchSomeData()
+  console.log('Async task completed', data)
+}).everyHour(1)
+
+// Function with parameters
+const cleanupTask = (directory) => {
+  console.log(`Cleaning up ${directory}`)
+  // Cleanup logic...
+}
+
+Candy.Route.cron(() => cleanupTask('/tmp')).everyDay(1)
+```
+
+## Time Conditions
+
+### Specific Time Values
+
+```javascript
+Candy.Route.cron('task')
+
+// Minute (0-59)
+.minute(30) // At 30th minute
+
+// Hour (0-23)
+.hour(14) // At 14:00
+
+// Day (1-31)
+.day(15) // On the 15th of the month
+
+// Week day (0-6, 0=Sunday)
+.weekDay(1) // On Monday
+
+// Month (1-12)
+.month(6) // In June
+
+// Year
+.year(2024) // In 2024
+
+// Year day (1-365)
+.yearDay(100) // On the 100th day of the year
+```
+
+### Periodic Execution
+
+```javascript
+Candy.Route.cron('periodic')
+
+// Every N minutes
+.everyMinute(5) // Every 5 minutes
+
+// Every N hours
+.everyHour(3) // Every 3 hours
+
+// Every N days
+.everyDay(2) // Every 2 days
+
+// Every N weeks
+.everyWeekDay(1) // Every week
+
+// Every N months
+.everyMonth(2) // Every 2 months
+
+// Every N years
+.everyYear(1) // Every year
+```
+
+## Combination Usage
+
+You can combine multiple conditions:
+
+```javascript
+// Every day at 14:30
+Candy.Route.cron('daily-report')
+  .hour(14)
+  .minute(30)
+
+// Mondays at 09:00
+Candy.Route.cron('weekly-task')
+  .weekDay(1)
+  .hour(9)
+  .minute(0)
+
+// First day of every month at midnight
+Candy.Route.cron('monthly-cleanup')
+  .day(1)
+  .hour(0)
+  .minute(0)
+```
+
+## Important Notes
+
+- The cron system checks every minute
+- Jobs run at the first suitable time after their last update
+- 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

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

@@ -0,0 +1,17 @@
+## 🏗️ How to Build a Controller
+
+A controller is just a JavaScript module that exports a function. This function automatically gets the magical `Candy` context object we talked about in the overview.
+
+#### A Simple "Hello World" Controller
+
+Check out this basic example from `controller/page/index.js`:
+
+```javascript
+// This function is our controller!
+module.exports = function (Candy) {
+  // It simply returns a string.
+  return 'Welcome to my awesome CandyPack server!'
+}
+```
+
+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.

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

@@ -0,0 +1,20 @@
+## 🤝 Your trusty `Candy` Assistant
+
+Remember the `Candy` object? It's your best friend inside a controller. It's passed to your controller function and gives you all the tools you need for the current request.
+
+#### Awesome Services at Your Fingertips
+
+*   `Candy.Request`: Info about the user's request.
+*   `Candy.View`: Renders your HTML pages.
+*   `Candy.Auth`: Manages user logins.
+*   `Candy.Token`: Protects your forms.
+*   `Candy.Lang`: Helps with different languages.
+
+#### Handy Helper Functions
+
+*   `Candy.return(data)`: Send back a response.
+*   `Candy.direct(url)`: Redirect the user to a new page.
+*   `Candy.cookie(key, value)`: Set a browser cookie.
+*   `Candy.validator()`: Check user input easily.
+
+With controllers and the `Candy` object, you have everything you need to start building powerful application logic!

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

@@ -0,0 +1,93 @@
+## 🎓 Controller 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.
+
+#### Creating a Controller Class
+
+A controller class receives the `Candy` object in its constructor, giving you access to all services throughout your class methods:
+
+```javascript
+// controller/User.js
+class User {
+  constructor(Candy) {
+    this.Candy = Candy
+  }
+
+  async getProfile() {
+    const user = await this.Candy.Auth.user()
+    return this.Candy.return({
+      success: true,
+      user: user
+    })
+  }
+
+  async updateProfile() {
+    const validator = this.Candy.validator()
+    validator.post('name').required().min(3)
+    validator.post('email').required().email()
+
+    if (await validator.error()) {
+      return validator.result()
+    }
+
+    const name = await this.Candy.request('name')
+    const email = await this.Candy.request('email')
+
+    // Update user in database
+    await this.Candy.Mysql.query('UPDATE users SET name = ?, email = ? WHERE id = ?', [
+      name,
+      email,
+      this.Candy.Auth.user().id
+    ])
+
+    return this.Candy.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
+Candy.Route.buff = 'www'
+
+// Access class methods using dot notation
+Candy.Route.get('/profile', 'User.getProfile')
+Candy.Route.post('/profile/update', 'User.updateProfile')
+```
+
+#### Accessing Classes in Controllers
+
+Controller classes are automatically instantiated for each request and attached to the `Candy` object. You can access them from any controller:
+
+```javascript
+module.exports = async function (Candy) {
+  // Access your User class
+  const profile = await Candy.User.getProfile()
+  
+  return Candy.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 `Candy` object is always available via `this.Candy`
+
+#### 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.