odac 1.0.1 → 1.2.0

package/docs/backend/07-views/03-variables.md

@@ -141,7 +141,7 @@ You have full access to the `Odac` object within templates:
 module.exports = async function(Odac) {
   // Fetch user from database
   const userId = Odac.Request.get('id')
-  const user = await Odac.Mysql.table('users')
+  const user = await Odac.DB.users
     .where('id', userId)
     .first()
   
@@ -179,7 +179,7 @@ module.exports = async function(Odac) {
 // Controller: controller/product.js
 module.exports = async function(Odac) {
   const productId = Odac.Request.get('id')
-  const product = await Odac.Mysql.table('products')
+  const product = await Odac.DB.products
     .where('id', productId)
     .first()
   
@@ -221,7 +221,7 @@ module.exports = async function(Odac) {
 ```javascript
 // Controller: controller/products.js
 module.exports = async function(Odac) {
-  const products = await Odac.Mysql.table('products')
+  const products = await Odac.DB.products
     .where('active', true)
     .get()
   
@@ -259,7 +259,7 @@ module.exports = async function(Odac) {
 **Good:**
 ```javascript
 // Controller
-const user = await Odac.Mysql.table('users').first()
+const user = await Odac.DB.users.first()
 const isAdmin = user.role === 'admin'
 
 Odac.set({
@@ -284,7 +284,7 @@ Always handle cases where data might not exist:
 // Controller
 module.exports = async function(Odac) {
   const productId = Odac.Request.get('id')
-  const product = await Odac.Mysql.table('products')
+  const product = await Odac.DB.products
     .where('id', productId)
     .first()
   

package/docs/backend/07-views/04-request-data.md

@@ -69,7 +69,7 @@ module.exports = async function(Odac) {
   const validatedPage = Math.max(1, page)
   
   // Fetch results
-  const results = await Odac.Mysql.table('products')
+  const results = await Odac.DB.products
     .where('name', 'like', `%${validatedQuery}%`)
     .limit(20)
     .offset((validatedPage - 1) * 20)

package/docs/backend/07-views/08-backend-javascript.md

@@ -379,7 +379,7 @@ You can use multiple `<script:odac>` blocks in the same view:
 ```html
 <script:odac>
   // Don't do this - should be in controller
-  const users = await Odac.Mysql.query('SELECT * FROM users');
+  const users = await Odac.DB.users.get();
   const apiData = await fetch('https://api.example.com/data');
 </script:odac>
 ```

package/docs/backend/07-views/10-styling-and-tailwind.md

@@ -0,0 +1,93 @@
+# 🎨 Styling & Tailwind CSS
+
+Odac comes with built-in, **Zero-Config** support for Tailwind CSS v4. This means you can start building beautiful, modern interfaces right out of the box without messing with configuration files or build pipelines.
+
+## How it Works
+
+The framework adopts a "Convention over Configuration" approach:
+
+1.  **Development (`npm run dev`)**:
+    *   The framework automatically watches your HTML, JS, and View files.
+    *   It compiles your CSS classes using the high-performance Rust-based Tailwind CLI.
+    *   Changes are reflected instantly.
+
+2.  **Production (`npm run build`)**:
+    *   The framework scans your project, builds the final CSS, and minifies it.
+    *   The output is saved to `public/assets/css/app.css`.
+
+3.  **Serving (`npm start`)**:
+    *   The compiled CSS file is served statically. No background processes, no overhead.
+
+## Customizing CSS
+
+By default, Odac manages everything for you internally. However, if you need to add custom CSS, fonts, or Tailwind configuration (like `@theme`), you can do so easily.
+
+### The Source File
+
+Simply create a file at **`view/css/app.css`**.
+
+If this file exists, Odac will use it as the **source** (input) for Tailwind.
+
+**Example `view/css/app.css`:**
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --font-display: "Satoshi", "sans-serif";
+  --color-brand: #ff5733;
+}
+
+/* Your custom CSS rules */
+.hero-gradient {
+  background: linear-gradient(to right, var(--color-brand), #ff0000);
+}
+```
+
+### The Output File
+
+The compiled CSS is always output to:
+**`public/assets/css/app.css`**
+
+> **⚠️ Important:** Never edit `public/assets/css/app.css` manually. It is a generated file and will be overwritten by Odac during build or development. Always edit `view/css/app.css` instead.
+
+## HTML Integration
+
+In your layout files (e.g., `view/head/main.html`), simply link to the compiled asset:
+
+```html
+<link rel="stylesheet" href="/assets/css/app.css" />
+```
+
+This is already set up for you in the default project template.
+
+## Multiple CSS Files
+
+Odac supports multiple CSS entry points. If your application has distinct sections (e.g., a Landing Page, a Dashboard, and an Admin Panel) that require separate stylesheets, you can organize them easily.
+
+### How to use
+
+Any `.css` file you place in the **`view/css/`** directory will be automatically detected, watched, and compiled by Odac.
+
+**Input:**
+*   `view/css/app.css`
+*   `view/css/admin.css`
+*   `view/css/landing.css`
+
+**Output (Compiled):**
+*   `public/assets/css/app.css`
+*   `public/assets/css/admin.css`
+*   `public/assets/css/landing.css`
+
+You can then link each specific stylesheet in its respective layout file:
+
+```html
+<!-- In Admin Layout -->
+<link rel="stylesheet" href="/assets/css/admin.css" />
+```
+
+## Using Tailwind v4
+
+Tailwind v4 is radically simpler. You generally don't need a `tailwind.config.js` file anymore. You can define your theme directly in CSS using the `@theme` block as shown above.
+
+However, Odac respects standard Tailwind behavior. If you absolutely need a config file for plugins or legacy reasons, you can create one, and the Tailwind CLI will detect it. But for 99% of use cases, the Zero-Config approach is cleaner and faster.

package/docs/backend/08-database/01-getting-started.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+ODAC supports multiple database connections including **MySQL**, **PostgreSQL** (beta), and **SQLite**. It uses a robust and secure connection pooling mechanism.
+
+## Configuration
+
+Add your database credentials to `odac.json`.
+
+Supported configuration options:
+
+- `host` - Database server hostname (default: `localhost`)
+- `user` - Database username
+- `password` - Database password
+- `database` - Database name
+- `port` - Database port
+- `type` - Database type (`mysql`, `postgres`, `sqlite`)
+- `filename` - Database file path (only for `sqlite`, default: `./dev.sqlite3`)
+
+### Single Connection (MySQL Default)
+
+```json
+{
+  "database": {
+    "type": "mysql",
+    "host": "localhost",
+    "user": "root",
+    "password": "password",
+    "database": "odac_app"
+  }
+}
+```
+
+### PostgreSQL
+
+```json
+{
+  "database": {
+    "type": "postgres",
+    "host": "localhost",
+    "user": "postgres",
+    "password": "password",
+    "database": "odac_app",
+    "port": 5432
+  }
+}
+```
+
+### Multiple Databases
+
+You can configure multiple database connections. The connection named `default` (or the first one) is used automatically.
+
+```json
+{
+  "database": {
+    "default": {
+      "type": "mysql",
+      "host": "localhost",
+      "database": "main_db"
+    },
+    "analytics": {
+      "type": "postgres",
+      "host": "analytics.example.com",
+      "database": "analytics_db"
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+For security, **always** use environment variables for sensitive data.
+
+**.env file:**
+```
+DB_HOST=localhost
+DB_USER=myuser
+DB_PASSWORD=mypassword
+```
+
+**odac.json:**
+```json
+{
+  "database": {
+    "type": "mysql",
+    "host": "${DB_HOST}",
+    "user": "${DB_USER}",
+    "password": "${DB_PASSWORD}"
+  }
+}
+```
+
+---
+
+## Automatic Connection
+
+The connection is established automatically when your application starts. You don't need to write any connection code.
+
+**Next Step:** Check out [Query Basics](./02-basics.md) to start using your database.

package/docs/backend/08-database/02-basics.md

@@ -0,0 +1,136 @@
+# Query Basics
+
+ODAC features a powerful, efficient, and "magic" Query Builder. It allows you to interact with your database using simple, chainable methods without writing raw SQL.
+
+## Accessing Tables
+
+You can access any table directly as a property of `Odac.DB`.
+
+```javascript
+// Access the 'users' table
+const query = Odac.DB.users;
+```
+
+If you have multiple database connections defined in your config:
+
+```javascript
+// Access 'visits' table on 'analytics' connection
+const visits = Odac.DB.analytics.visits;
+```
+
+---
+
+## Retrieving Data (Select)
+
+### Fetch All Rows
+
+```javascript
+const users = await Odac.DB.users.select();
+```
+
+### Fetch a Single Row
+
+Use `.first()` to get a single object instead of an array.
+
+```javascript
+const user = await Odac.DB.users.where('id', 1).first();
+```
+
+### Filtering (Where)
+
+```javascript
+// Simple equals
+const users = await Odac.DB.users.where('email', 'john@example.com').select();
+
+// Comparison operators
+const products = await Odac.DB.products.where('price', '>', 100).select();
+const activeUsers = await Odac.DB.users.where('status', '!=', 'banned').select();
+
+// OR statements
+const staff = await Odac.DB.users
+  .where('role', 'admin')
+  .orWhere('role', 'editor')
+  .select();
+```
+
+### Ordering and Limiting
+
+```javascript
+const latestPosts = await Odac.DB.posts
+  .orderBy('created_at', 'desc')
+  .limit(5);
+```
+
+### Counting Rows
+
+ODAC simplifies counting rows. Unlike standard Knex behavior which might return objects or strings, `count()` directly returns a `Number` for simple queries.
+
+```javascript
+const totalUsers = await Odac.DB.users.count(); // Returns: 150 (Number)
+
+const activeAdmins = await Odac.DB.users
+    .where('role', 'admin')
+    .where('active', true)
+    .count(); // Returns: 5 (Number)
+```
+
+---
+
+## Inserting Data
+
+```javascript
+// Insert a single record
+await Odac.DB.users.insert({
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Insert multiple records
+await Odac.DB.tags.insert([
+  { name: 'javascript' },
+  { name: 'nodejs' }
+]);
+```
+
+---
+
+## Updating Data
+
+```javascript
+await Odac.DB.users
+  .where('id', 1)
+  .update({
+    status: 'active',
+    last_login: new Date()
+  });
+```
+
+---
+
+## Deleting Data
+
+await Odac.DB.users.where('id', 1).delete();
+```
+
+---
+
+## ID Generation (NanoID)
+
+ODAC includes a built-in helper for generating robust, unique string IDs (NanoID) without needing external packages. Secure, URL-friendly, and collision-resistant.
+
+```javascript
+// Generate a standard 21-character ID (e.g., "V1StGXR8_Z5jdHi6B-myT")
+const id = Odac.DB.nanoid();
+
+// Generate a custom length ID
+const shortId = Odac.DB.nanoid(10);
+```
+
+This is particularly useful when inserting records into tables that use string-based Primary Keys instead of auto-increment integers.
+
+```javascript
+await Odac.DB.posts.insert({
+    id: Odac.DB.nanoid(),
+    title: 'My First Post'
+});
+```

package/docs/backend/08-database/03-advanced.md

@@ -0,0 +1,84 @@
+# Advanced Queries
+
+For complex applications, ODAC provides advanced query capabilities like nested constraints, joins, transactions, and raw SQL execution.
+
+## Nested Where Clauses
+
+To create complex `AND / OR` logic (like parenthesis in SQL), use a callback function with `.where()` or `.andWhere()`.
+
+**Example:**
+`SELECT * FROM users WHERE status = 'active' AND (role = 'admin' OR role = 'editor')`
+
+**ODAC Code:**
+```javascript
+await Odac.DB.users
+  .where('status', 'active')
+  .andWhere(builder => {
+    builder.where('role', 'admin').orWhere('role', 'editor');
+  })
+  .select();
+```
+
+---
+
+## Joins
+
+You can join multiple tables using `.join()`, `.leftJoin()`, etc.
+
+```javascript
+const posts = await Odac.DB.posts
+  .join('users', 'posts.user_id', '=', 'users.id')
+  .select('posts.title', 'users.name as author');
+```
+
+---
+
+## Transactions
+
+Transactions allow you to ensure multiple database operations succeed or fail together.
+
+```javascript
+await Odac.DB.transaction(async (trx) => {
+  
+  const [userId] = await trx('users').insert({ name: 'Alice' });
+  
+  await trx('accounts').insert({ user_id: userId, balance: 100 });
+
+  // If anything throws an error here, both inserts are rolled back.
+});
+```
+
+> **Note:** Use `Odac.DB.connectionName.transaction(...)` for non-default connections.
+
+---
+
+## Raw Queries & Values
+
+### Raw SQL Execution
+If you need to execute a completely raw SQL query:
+
+```javascript
+const result = await Odac.DB.run('SELECT email FROM users WHERE id = ?', [1]);
+```
+
+### Raw Values in Updates
+Sometimes you need to call SQL functions (like `NOW()` or `COUNT()`) inside an update or insert.
+
+```javascript
+await Odac.DB.users.where('id', 1).update({
+  updated_at: Odac.DB.raw('NOW()'),
+  visits: Odac.DB.raw('visits + 1')
+});
+```
+
+---
+
+## Safe Table Access
+
+If your table name conflicts with a reserved ODAC method (e.g., `transaction`, `schema`, `run`), use the `.table()` method to access it safely.
+
+```javascript
+// Access a table named 'transaction'
+const logs = await Odac.DB.table('transaction').select();
+```
+

package/docs/backend/08-database/04-migrations.md

@@ -0,0 +1,48 @@
+# Code-First Migrations
+
+Migration files are great, but sometimes (especially in rapid development or zero-config apps) you want dependencies to define their own table structures automatically.
+
+ODAC uses the `.schema()` helper for this logic.
+
+## Ensuring Tables Exist
+
+The `.schema()` method checks if a table exists. If it **does not exist**, it runs the provided callback to create it. If it **already exists**, it does nothing.
+
+```javascript
+// Ensure 'products' table exists on the fly
+await Odac.DB.products.schema(t => {
+   t.increments('id');
+   t.string('name').notNullable();
+   t.decimal('price', 10, 2);
+   t.boolean('is_active').defaultTo(true);
+   
+   // Automatic timestamps (created_at, updated_at)
+   t.timestamps(true, true);
+});
+```
+
+The `t` argument is a Schema Builder. You can define columns using standard types like:
+- `t.string()`
+- `t.integer()`
+- `t.boolean()`
+- `t.text()`
+- `t.date()`
+- `t.json()`
+
+## Usage Example
+
+A typical pattern is to define schemas in your module's initialization or before the first insert.
+
+```javascript
+// In your controller or module
+async function init() {
+    await Odac.DB.logs.schema(t => {
+        t.string('level');
+        t.text('message');
+        t.timestamps();
+    });
+}
+
+// Later...
+await Odac.DB.logs.insert({ level: 'info', message: 'App started' });
+```

package/docs/backend/09-validation/01-the-validator-service.md

@@ -70,6 +70,7 @@ if (await validator.error()) {
 - `in:substring` - Must contain substring
 - `notin:substring` - Must not contain substring
 - `regex:pattern` - Must match regex pattern
+- `!disposable` - Block disposable/temporary email providers (List is automatically updated daily)
 
 **Security:**
 - `xss` - Check for HTML tags (XSS protection)

package/docs/backend/10-authentication/03-register.md

@@ -113,18 +113,25 @@ module.exports = async function (Odac) {
 
 ## Configuration
 
-Make sure your `config.json` has the auth configuration:
+Make sure your `odac.json` has the auth configuration:
 
 ```json
 {
   "auth": {
     "table": "users",
     "key": "id",
-    "token": "user_tokens"
+    "token": "user_tokens",
+    "idType": "nanoid" // Options: "nanoid" (default, string) or "int" (auto-increment)
   }
 }
 ```
 
+### ID Generation Strategy
+ODAC automatically detects your preferred ID strategy:
+1.  **NanoID (Default)**: Generates secure, URL-friendly 21-character string IDs. Recommended for modern apps.
+2.  **Auto-Increment**: If your database table uses `INTEGER` or `SERIAL` primary keys, ODAC detects this and lets the database handle ID generation.
+3.  **Manual Override**: You can force a specific behavior using the `idType` config setting.
+
 ## Security Notes
 
 - Passwords are automatically hashed with bcrypt before storage