npm - odac - Versions diffs - 1.0.0 → 1.1.0 - Mend

odac 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/.github/workflows/auto-pr-description.yml +3 -1
package/CHANGELOG.md +127 -0
package/README.md +39 -36
package/bin/odac.js +1 -31
package/client/odac.js +871 -994
package/docs/backend/01-overview/03-development-server.md +7 -7
package/docs/backend/02-structure/01-typical-project-layout.md +1 -0
package/docs/backend/03-config/00-configuration-overview.md +9 -0
package/docs/backend/03-config/01-database-connection.md +1 -1
package/docs/backend/04-routing/02-controller-less-view-routes.md +9 -3
package/docs/backend/04-routing/09-websocket.md +29 -0
package/docs/backend/05-controllers/02-your-trusty-odac-assistant.md +2 -0
package/docs/backend/05-controllers/03-controller-classes.md +27 -41
package/docs/backend/05-forms/01-custom-forms.md +103 -95
package/docs/backend/05-forms/02-automatic-database-insert.md +21 -21
package/docs/backend/07-views/02-rendering-a-view.md +1 -1
package/docs/backend/07-views/03-variables.md +5 -5
package/docs/backend/07-views/04-request-data.md +1 -1
package/docs/backend/07-views/08-backend-javascript.md +1 -1
package/docs/backend/08-database/01-getting-started.md +100 -0
package/docs/backend/08-database/02-basics.md +136 -0
package/docs/backend/08-database/03-advanced.md +84 -0
package/docs/backend/08-database/04-migrations.md +48 -0
package/docs/backend/09-validation/01-the-validator-service.md +1 -0
package/docs/backend/10-authentication/03-register.md +8 -1
package/docs/backend/10-authentication/04-odac-register-forms.md +46 -46
package/docs/backend/10-authentication/05-session-management.md +1 -1
package/docs/backend/10-authentication/06-odac-login-forms.md +48 -48
package/docs/backend/10-authentication/07-magic-links.md +134 -0
package/docs/backend/11-mail/01-the-mail-service.md +118 -28
package/docs/backend/12-streaming/01-streaming-overview.md +2 -2
package/docs/backend/13-utilities/01-odac-var.md +7 -7
package/docs/backend/13-utilities/02-ipc.md +73 -0
package/docs/frontend/01-overview/01-introduction.md +5 -1
package/docs/frontend/02-ajax-navigation/01-quick-start.md +1 -1
package/docs/index.json +16 -124
package/eslint.config.mjs +5 -47
package/package.json +9 -4
package/src/Auth.js +362 -104
package/src/Config.js +7 -2
package/src/Database.js +188 -0
package/src/Ipc.js +330 -0
package/src/Mail.js +408 -37
package/src/Odac.js +65 -9
package/src/Request.js +70 -48
package/src/Route/Cron.js +4 -1
package/src/Route/Internal.js +214 -11
package/src/Route/Middleware.js +7 -2
package/src/Route.js +106 -26
package/src/Server.js +80 -11
package/src/Storage.js +165 -0
package/src/Validator.js +94 -2
package/src/View/Form.js +193 -17
package/src/View.js +46 -1
package/src/WebSocket.js +18 -3
package/template/config.json +1 -1
package/template/route/www.js +12 -10
package/test/core/{Candy.test.js → Odac.test.js} +2 -2
package/docs/backend/08-database/01-database-connection.md +0 -99
package/docs/backend/08-database/02-using-mysql.md +0 -322
package/src/Mysql.js +0 -575

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

@@ -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/07-views/02-rendering-a-view.md CHANGED Viewed

@@ -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()

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/08-database/01-getting-started.md ADDED Viewed

@@ -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 `config.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
+```
+**config.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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -120,11 +120,18 @@ Make sure your `config.json` has the auth configuration:
   "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