@seip/blue-bird 1.1.0 → 1.1.1

package/.env_example

@@ -13,7 +13,11 @@ DESCRIPTION="Description project"
 # Security Configuration
 JWT_SECRET="JWT_SECRET"
 
-# Redis Configuration
+# Cache Configuration
+# Options: "memory" (Fast in-memory RAM), "redis" (Distributed container cache), "none" (Disabled)
+CACHE_MODE="memory"
+
+# Redis Configuration (Used when CACHE_MODE="redis")
 REDIS_HOST="localhost"
 REDIS_PORT=6379
 REDIS_PASSWORD=""
@@ -21,16 +25,25 @@ REDIS_PASSWORD=""
 # PM2 Clustering Instances (integer or 'max')
 PM2_INSTANCES=1
 
-# Database Configuration (Used only for local development outside Docker)
-# MySQL
-DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
 
-# PostgreSQL (Uncomment to use PostgreSQL locally or DEV)
-# DATABASE_URL="postgresql://postgres:root@localhost:5432/blue_bird?schema=public"
+# Database Configuration
+# SQLite (Default - uses WAL mode and busy timeout automatically)
+DB_TYPE="sqlite"
+DB_FILE="database/blue_bird.db"
+DATABASE_URL="sqlite:database/blue_bird.db"
+
+# MySQL (Uncomment to use MySQL in Docker or locally)
+# DB_TYPE="mysql"
+# DB_NAME="blue_bird"
+# DB_USER="root"
+# DB_PASSWORD="root"
+# DB_PORT=3306
+# DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
 
-# Database / Docker Configuration
-DB_TYPE="mysql"
-DB_NAME="blue_bird"
-DB_USER="root"
-DB_PASSWORD="root"
-DB_PORT=3306
+# PostgreSQL (Uncomment to use PostgreSQL in Docker or locally)
+# DB_TYPE="postgres"
+# DB_NAME="blue_bird"
+# DB_USER="postgres"
+# DB_PASSWORD="root"
+# DB_PORT=5432
+# DATABASE_URL="postgresql://postgres:root@localhost:5432/blue_bird?schema=public"

package/AGENTS.md

@@ -47,11 +47,30 @@ routerApi.post("/users", validateUser.middleware(), (req, res) => {
 });
 ```
 
-## 5. Authentication (Auth)
+## 5. Authentication & Password Hashing (Auth & Hash)
+
+### Password Hashing (Hash)
+
+Blue Bird includes native password hashing using `node:crypto.scrypt` with random salt and timing-safe comparison (zero external npm dependencies required). It also seamlessly supports `bcrypt` when installed or verifying `$2a$/$2b$` hashes.
+
+```javascript
+import Hash from "@seip/blue-bird/core/hash.js";
+
+// Hash password with scrypt (default)
+const hash = await Hash.make("mySecretPassword");
+
+// Verify password
+const isValid = await Hash.verify("mySecretPassword", hash);
+
+// Hash with bcrypt (if 'bcrypt' package is installed)
+const bcryptHash = await Hash.make("mySecretPassword", { driver: "bcrypt" });
+```
+
+### JWT Handling (Auth)
 
 The system includes built-in JWT handling with AES-256-GCM encryption. The framework handles tokens via Cookies or the `Authorization` header.
 
-### Protecting Routes
+#### Protecting Routes
 
 Use `Auth.protect()` as a middleware to secure routes.
 
@@ -63,7 +82,7 @@ router.get("/profile", Auth.protect(), (req, res) => {
 });
 ```
 
-### Login and Logout
+#### Login and Logout
 
 The `Auth` class provides helpers to handle session management via cookies.
 
@@ -71,25 +90,50 @@ The `Auth` class provides helpers to handle session management via cookies.
 router.post("/login", async (req, res) => {
   const user = { id: 1, name: "John" };
   await Auth.login(res, user);
-  res.json({ message: "Logged in" });
+  res.ok(user, "Logged in");
 });
 
 router.post("/logout", async (req, res) => {
   await Auth.logout(res);
-  res.json({ message: "Logged out" });
+  res.ok(null, "Logged out");
 });
 ```
 
-## 6. Performance Caching (Cache)
+## 6. HTTP Response Helpers & Health Check
 
-If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON or HTML payload.
+Blue Bird decorates the Express `res` object with standardized helper methods:
+
+```javascript
+// Success responses
+res.ok(data, "Success message");            // HTTP 200 { status: "success", message, data }
+res.created(data, "Created successfully");  // HTTP 201 { status: "success", message, data }
+res.paginate(items, pagination, "Fetched"); // HTTP 200 { status: "success", message, data, pagination }
+
+// Error responses
+res.badRequest("Invalid input", errors);    // HTTP 400 { status: "error", message, errors }
+res.unauthorized("Authentication required");// HTTP 401 { status: "error", message }
+res.forbidden("Access denied");             // HTTP 403 { status: "error", message }
+res.notFound("Resource not found");         // HTTP 404 { status: "error", message }
+res.serverError("Internal failure", err);   // HTTP 500 { status: "error", message }
+```
+
+### Built-in Health Endpoint
+
+Every Blue Bird application provides a native `/api/health` endpoint out of the box returning system uptime, timestamp, environment, and memory consumption.
+
+## 7. Performance Caching (Cache)
+
+Configure caching via `CACHE_MODE` in `.env`:
+- `CACHE_MODE="memory"`: Fast local RAM cache inside Node.js (default when Redis is not used). Zero network overhead.
+- `CACHE_MODE="redis"`: Distributed cache across containers with automatic fallback to memory if Redis is unavailable.
+- `CACHE_MODE="none"`: Caching disabled.
 
 ```javascript
 import Cache from "@seip/blue-bird/core/cache.js";
 
 // Express route middleware caching
 router.get("/stats", Cache.middleware(60), (req, res) => {
-  res.json({ ok: true });
+  res.ok({ usersCount: 150 });
 });
 
 // Programmatic cache manipulation
@@ -100,9 +144,22 @@ const cachedData = await Cache.get("custom_key");
 await Cache.delete("/api/public/config");
 ```
 
-The Cache module integrates with Redis when `REDIS_HOST` is configured in the environment. If Redis is unavailable or fails, it transparently falls back to an in-memory cache system without interrupting requests.
+## 8. On-Demand Modules & CLI Add
+
+To keep `node_modules` lightweight, optional modules load dynamically on-demand. Install them easily via:
+
+```bash
+npx blue-bird add upload      # Installs multer for file uploads
+npx blue-bird add ws          # Installs ws for WebSockets
+npx blue-bird add redis       # Installs redis for caching/sessions
+npx blue-bird add sqlite      # Installs better-sqlite3
+npx blue-bird add mysql       # Installs mysql2
+npx blue-bird add postgres    # Installs pg
+npx blue-bird add bcrypt      # Installs bcrypt
+npx blue-bird add swagger     # Installs swagger-ui-express
+```
 
-## 7. Security (Helmet)
+## 9. Security (Helmet)
 
 Helmet is **not applied globally** by default. Apply it per-router where needed:
 
@@ -113,65 +170,80 @@ const apiRouter = new Router("/api");
 apiRouter.use(App.helmet());
 ```
 
-## 8. Docker Compose CLI
 
-Blue Bird features a built-in Docker Compose CLI wrapper (`core/cli/docker.js`) to deploy and manage containerized development databases and production stacks across MySQL, PostgreSQL, or no-database (`none`) architectures.
+## 10. Docker Compose CLI
+
+Blue Bird features a built-in Docker Compose CLI wrapper (`core/cli/docker.js`) to deploy and manage containerized development databases and production stacks across SQLite (default), MySQL, PostgreSQL, or no-database (`none`) architectures.
 
 Production deployments always use Docker for orchestration, running:
 - Nginx: Serves static files directly from `frontend/` (stripping `.html` extensions) and blocks common scanner requests (`.env`, `.git`, etc.) with fallback to Express for APIs.
 - Node.js App: Managed via PM2 in cluster mode using `PM2_INSTANCES` configuration (defaults to `1`, can be set to `max`).
-- Database: MySQL (`mysql:8.0`) or PostgreSQL (`postgres:18-alpine`), dynamically detected via `getDbType()` reading `DB_TYPE` / `DATABASE_URL` from `.env`.
+- Database: SQLite (default, embedded in app with volume `./database`), MySQL (`mysql:8.0`), or PostgreSQL (`postgres:18-alpine`), dynamically detected via `getDbType()` reading `DB_TYPE` / `DATABASE_URL` from `.env`.
 - Redis: Memory caching and session store.
 
 ```bash
 # Manage containers using blue-bird CLI
 npx blue-bird docker dev            # Starts development database & redis containers. Run npm run dev manually.
-npx blue-bird docker start          # Starts production app stack (DB, redis, app, nginx)
-npx blue-bird docker start db       # Starts configured database container only (postgres or mysql)
+npx blue-bird docker start          # Starts production app stack (DB/SQLite, redis, app, nginx)
+npx blue-bird docker start db       # Starts configured database container (or Redis if SQLite is used)
 npx blue-bird docker start redis    # Starts Redis container only
-npx blue-bird docker start dbs      # Starts both database containers (configured DB + Redis)
+npx blue-bird docker start dbs      # Starts database containers (configured DB + Redis)
 npx blue-bird docker stop           # Stops all running containers
 npx blue-bird docker build          # Builds/rebuilds application image
 npx blue-bird docker ps             # Shows status of active containers
 npx blue-bird docker logs           # Tails Node.js app container logs
-npx blue-bird docker logs db        # Tails configured database container logs
+npx blue-bird docker logs db        # Tails database container logs (or app logs if SQLite is used)
 npx blue-bird docker pm2 [args]     # Runs PM2 commands inside the app container (e.g. status, monit)
-npx blue-bird docker db             # Runs interactive shell inside container (psql for Postgres, mysql for MySQL)
+npx blue-bird docker db             # Inspects active database (SQLite query/tables, psql for Postgres, mysql for MySQL)
+npx blue-bird docker sqlite         # Inspects SQLite tables or runs query on configured .db file
 npx blue-bird docker psql           # Runs interactive PostgreSQL client terminal inside container
 npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside container
 npx blue-bird docker redis          # Runs interactive Redis client terminal inside container
+npx blue-bird docker export         # Exports database backup (.db file for SQLite or .sql dump) into backups/
+npx blue-bird docker import         # Restores database backup (.db or .sql) from backups/
 npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
 ```
 
 The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments by configuring `DATABASE_URL` inside `.env`.
 
-## 9. AI Development Guidelines
+## 11. AI Development Guidelines
 
 1. **Frontend**: Static files are stored in `frontend/` (e.g. `frontend/css`, `frontend/js`). HTML files will be served without the `.html` extension (e.g. `login.html` is accessible as `/login`).
 2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
 3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
 4. **No inline comments**: Only use JSDoc for documentation.
 
-## 10. Database Module (database.js)
+## 12. Database Module (database.js)
+
+Blue Bird provides a unified wrapper class (`core/database.js`) supporting **SQLite (`better-sqlite3`)**, **MySQL (`mysql2/promise`)**, and **PostgreSQL (`pg`)**. It features connection pooling/reconnection, automatic retries on startup, query formatting, and built-in Redis query caching:
 
-Blue Bird provides a unified wrapper class (`core/database.js`) supporting **MySQL (`mysql2/promise`)** and **PostgreSQL (`pg`)**. It features connection pooling, automatic retries on startup, query formatting, and built-in Redis query caching:
 
-- **Dynamic Initialization:** When `npx blue-bird` (`core/cli/init.js`) runs, it prompts the developer for the database type (`none`, `mysql`, `postgres`). It then intelligently copies the correct `docker-compose.yml` template (`docker-compose.mysql.yml`, `docker-compose.postgres.yml`, or `docker-compose.none.yml`) and configures `.env` with `DB_TYPE` and `DATABASE_URL`.
-- **Parameter Placeholders:** When using `pg` for PostgreSQL with `connection.query()`, `?` placeholders are automatically translated to `$1, $2, ...` under the hood.
+- **Dynamic Initialization:** When `npx blue-bird` (`core/cli/init.js`) runs, it prompts the developer for the database type (`sqlite` [default], `mysql`, `postgres`, `none`). It then intelligently copies the correct `docker-compose.yml` template (`docker-compose.sqlite.yml`, `docker-compose.mysql.yml`, `docker-compose.postgres.yml`, or `docker-compose.none.yml`) and configures `.env` with `DB_TYPE`, `DB_FILE`, and `DATABASE_URL`.
+- **SQLite Concurrency & WAL:** SQLite automatically runs with `PRAGMA journal_mode = WAL;`, `PRAGMA busy_timeout = 5000;`, `PRAGMA synchronous = NORMAL;`, and `PRAGMA foreign_keys = ON;` to eliminate "database is locked" errors and ensure high concurrency with readers and writers.
+- **Parameter Placeholders:** Supports `?` placeholders across all drivers (automatically translated to `$1, $2, ...` under the hood for PostgreSQL).
 
 ```javascript
 import { Database, DB_TYPE } from "@seip/blue-bird/core/database.js";
 
 const connection = new Database(20);
 
-// Basic SELECT query returning single row (Supports both MySQL and PostgreSQL)
+// Basic SELECT query returning single row (Supports SQLite, MySQL, and PostgreSQL)
 const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
 
 // Query caching in Redis (stores results in Redis for 60 seconds)
 const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
 
-// INSERT query returns insertId directly (or row ID/rowCount in Postgres)
+// INSERT query returns insertId directly (or row ID in SQLite / Postgres)
 const newUserId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+
+// Pagination helper
+const page = await connection.paginate("SELECT * FROM users ORDER BY id ASC", [], { page: 1, limit: 10 });
+
+// Safe Transactions
+await connection.transaction(async (tx) => {
+  const id = await tx.query("INSERT INTO users (name) VALUES (?)", ["Bob"]);
+  await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [id]);
+});
 ```
 
 ## 11. Nginx Static Asset Caching

package/README.md

@@ -59,10 +59,11 @@ npx blue-bird
 ```
 
 When run, the interactive CLI prompts for your preferred infrastructure configuration:
-- Database Selection: Choose between `none`, `mysql`, or `postgres`.
-- Credentials: Set your database name, user, password, and port (`3306` or `5432`).
+- Database Selection: Choose between `sqlite` (default), `mysql`, `postgres`, or `none`.
+- Credentials / Path: Set your SQLite database path (default `database/blue_bird.db`), or MySQL/PostgreSQL host, port, user, and password.
+
+The CLI intelligently copies the appropriate Docker configuration (`docker/docker-compose.sqlite.yml`, `docker/docker-compose.mysql.yml`, `docker/docker-compose.postgres.yml`, or `docker/docker-compose.none.yml`) to your project root as `docker-compose.yml`. It also writes the environment settings (`DB_TYPE`, `DB_FILE`, `DATABASE_URL`) to `.env` and installs the required database packages (`better-sqlite3`, `mysql2`, or `pg`) automatically.
 
-The CLI intelligently copies the appropriate Docker configuration (`docker/docker-compose.mysql.yml`, `docker/docker-compose.postgres.yml`, or `docker/docker-compose.none.yml`) to your project root as `docker-compose.yml`. It also writes the environment settings (`DB_TYPE`, `DATABASE_URL`) to `.env` and installs the required database packages (`mysql2` or `pg`) automatically.
 
 ### 3. Run Development Server / Modo Desarrollo
 
@@ -162,18 +163,37 @@ routerApi.post("/users", validateUser.middleware(), (req, res) => {
 
 ---
 
-### 4. JWT Authentication & Redis Sessions (`Auth`)
+### 4. Authentication & Password Hashing (`Auth` & `Hash`)
+
+#### Password Hashing (`Hash`)
+
+Blue Bird includes high-performance password hashing using `node:crypto.scrypt` with random salt and timing-safe comparison out of the box (zero npm dependencies). It also supports `bcrypt` if installed or when verifying `$2a$/$2b$` hashes.
+
+```javascript
+import Hash from "@seip/blue-bird/core/hash.js";
+
+// 1. Hash password with scrypt (default)
+const hash = await Hash.make("mySecretPassword");
+
+// 2. Verify password (timing-safe comparison)
+const isValid = await Hash.verify("mySecretPassword", hash);
+
+// 3. Hash with bcrypt (if 'bcrypt' package is installed)
+const bcryptHash = await Hash.make("mySecretPassword", { driver: "bcrypt", rounds: 10 });
+```
+
+#### JWT Authentication & Sessions (`Auth`)
 
 Secure user authentication with AES-256-GCM encrypted tokens. Transmitted via HTTP-Only cookies or `Authorization` headers, with optional Redis session storage and invalidation.
 
-#### Protecting Routes
+##### Protecting Routes
 
 ```javascript
 import Auth from "@seip/blue-bird/core/auth.js";
 
 // 1. Secure API endpoint (returns 401 JSON on failure)
 router.get("/profile", Auth.protect(), (req, res) => {
-  res.json({ user: req.user });
+  res.ok({ user: req.user });
 });
 
 // 2. Secure web page (redirects to /login on failure)
@@ -182,20 +202,20 @@ router.get("/dashboard", Auth.protect({ redirect: "/login", key: "user", cookieK
 });
 ```
 
-#### Authentication Sessions & Utilities
+##### Authentication Sessions & Utilities
 
 ```javascript
 // Login & Sync Session state in Redis (if active)
 router.post("/login", async (req, res) => {
   const user = { id: 1, name: "John Doe", role: "admin" };
   await Auth.login(res, user, "auth", { expiresIn: "7d" });
-  res.json({ message: "Logged in successfully" });
+  res.ok(user, "Logged in successfully");
 });
 
 // Logout & Delete Session from Redis
 router.post("/logout", async (req, res) => {
   await Auth.logout(res, "auth", {}, req);
-  res.json({ message: "Logged out" });
+  res.ok(null, "Logged out");
 });
 
 // Manual Encrypted JWT Tokens & AES-256-GCM Encryption
@@ -207,9 +227,36 @@ const decrypted = Auth.decrypt(encrypted, process.env.JWT_SECRET);
 
 ---
 
-### 5. Performance Cache & Redis Client (`Cache`)
+### 5. HTTP Response Helpers & Health Check
+
+Blue Bird enhances Express' `res` object with standardized helper methods:
+
+```javascript
+// Standard Success Responses
+res.ok(data, "Success");                      // HTTP 200 { status: "success", message, data }
+res.created(newItem, "Item created");         // HTTP 201 { status: "success", message, data }
+res.paginate(items, pagination, "Fetched");   // HTTP 200 { status: "success", message, data, pagination }
+
+// Standard Error Responses
+res.badRequest("Invalid input", errors);      // HTTP 400 { status: "error", message, errors }
+res.unauthorized("Authentication required");  // HTTP 401 { status: "error", message }
+res.forbidden("Access denied");               // HTTP 403 { status: "error", message }
+res.notFound("Resource not found");           // HTTP 404 { status: "error", message }
+res.serverError("Internal failure", err);     // HTTP 500 { status: "error", message }
+```
+
+#### Health Check Endpoint (`/api/health`)
+
+Every application includes an automatic `/api/health` route returning server status, uptime, environment, and memory consumption.
+
+---
+
+### 6. Performance Cache & Modes (`Cache`)
 
-Applies route-level response caching for JSON payloads (`res.json`) and HTML output (`res.send`). Automatically uses Redis when `REDIS_HOST` is configured, and transparently degrades to an in-memory cache if Redis is unavailable or offline.
+Configured via `CACHE_MODE` in `.env`:
+- `CACHE_MODE="memory"`: Fast local RAM cache inside Node.js with automated TTL cleanup (default when Redis is not used). Zero network overhead.
+- `CACHE_MODE="redis"`: Distributed cache across Docker containers with automatic fallback to memory if Redis is unavailable.
+- `CACHE_MODE="none"`: Caching disabled.
 
 #### Route Caching Middleware
 
@@ -218,7 +265,7 @@ import Cache, { getRedisClient } from "@seip/blue-bird/core/cache.js";
 
 // Cache endpoint for 60 seconds (sets X-Blue-Bird-Cache: HIT/MISS headers)
 router.get("/stats", Cache.middleware(60), (req, res) => {
-  res.json({ usersOnline: 42 });
+  res.ok({ usersOnline: 42 });
 });
 ```
 
@@ -236,6 +283,7 @@ await Cache.delete("/api/public/config");
 await Cache.clear();
 ```
 
+
 #### Custom Database & Data Caching with `getRedisClient()`
 
 ```javascript
@@ -274,20 +322,29 @@ webRouter.use(App.helmet());
 
 ### 7. Database wrapper (`Database`)
 
-Blue Bird provides a unified, multi-database client wrapper (`core/database.js`) supporting **MySQL** and **PostgreSQL** with automated connection retry loops, query formatting utilities, and Redis query caching.
+Blue Bird provides a unified, multi-database client wrapper (`core/database.js`) supporting **SQLite** (default), **MySQL**, and **PostgreSQL** with automated connection retry loops, query formatting utilities, and Redis query caching.
 
 #### Driver Support
+- **Native SQLite (`better-sqlite3`) [Default]**: Embedded, ultra-fast zero-latency database. Automatically applies `PRAGMA journal_mode = WAL;`, `PRAGMA busy_timeout = 5000;`, `PRAGMA synchronous = NORMAL;`, and `PRAGMA foreign_keys = ON;` to eliminate locking errors and support concurrent reader and writer operations.
 - **Native MySQL (`mysql2/promise`)**: High-performance connection pool for MySQL 8.0+.
-- **Native PostgreSQL (`pg`)**: Connection pool for PostgreSQL 18+. When running standard queries with `connection.query(sql, params)`, the wrapper automatically converts `?` parameter placeholders into PostgreSQL `$1, $2, ...` syntax, allowing unified SQL query writing across both database engines.
+- **Native PostgreSQL (`pg`)**: Connection pool for PostgreSQL 18+. When running standard queries with `connection.query(sql, params)`, the wrapper automatically converts `?` parameter placeholders into PostgreSQL `$1, $2, ...` syntax, allowing unified SQL query writing across all database engines.
 - **No Database (`none`)**: If no database is configured, the wrapper is disabled gracefully without crashing the server.
 
 #### Standalone & Remote Database Configuration
-You can connect to any local or remote database instance (outside Docker, such as Supabase, Neon, AWS RDS, or local services) simply by defining the `DATABASE_URL` in your `.env` file:
+You can connect to any local or remote database instance (outside Docker, such as Supabase, Neon, AWS RDS, local SQLite files, or MySQL/Postgres services) simply by defining the `DATABASE_URL` or `DB_FILE` in your `.env` file:
 
 ```env
-DB_TYPE="postgres"
-DATABASE_URL="postgresql://postgres:password@localhost:5432/blue_bird?schema=public"
-# OR for MySQL:
+# SQLite (Default)
+DB_TYPE="sqlite"
+DB_FILE="database/blue_bird.db"
+DATABASE_URL="sqlite:database/blue_bird.db"
+
+# PostgreSQL (Remote or local)
+# DB_TYPE="postgres"
+# DATABASE_URL="postgresql://postgres:password@localhost:5432/blue_bird?schema=public"
+
+# MySQL (Remote or local)
+# DB_TYPE="mysql"
 # DATABASE_URL="mysql://root:password@localhost:3306/blue_bird"
 ```
 
@@ -296,16 +353,16 @@ DATABASE_URL="postgresql://postgres:password@localhost:5432/blue_bird?schema=pub
 ```javascript
 import { Database, DB_TYPE } from "@seip/blue-bird/core/database.js";
 
-// Instantiate the database connection pool with a connection limit (e.g., 20)
+// Instantiate the database connection pool or SQLite instance
 const connection = new Database(20);
 
-// 1. Basic SELECT query returning single row (Works for both MySQL and PostgreSQL using ? placeholders)
+// 1. Basic SELECT query returning single row (Works for SQLite, MySQL, and PostgreSQL using ? placeholders)
 const user = await connection.query("SELECT * FROM users WHERE email = ?", ["test@example.com"], "return_row");
 
 // 2. Fetch rows with 60 seconds Redis caching enabled
 const stats = await connection.query("SELECT COUNT(*) as count FROM access_logs", [], { cache: 60 });
 
-// 3. INSERT query (returns insertId for MySQL, or inserted row ID / rowCount for PostgreSQL)
+// 3. INSERT query (returns insertId / lastInsertRowid across SQLite, MySQL, and PostgreSQL)
 const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["John"]);
 
 // 4. Automatic SQL Query Pagination (Runs count query + LIMIT/OFFSET calculation)
@@ -315,10 +372,10 @@ const paginated = await connection.paginate(
   { page: 1, limit: 10, cache: 60 }
 );
 
-// 5. Atomic Database Transactions with Automatic Commit & Rollback
+// 5. Atomic Database Transactions with Automatic Commit & Rollback (uses BEGIN IMMEDIATE for SQLite)
 const txUserId = await connection.transaction(async (tx) => {
   const userId = await tx.query("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@example.com"]);
-  await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [userId]);
+  await tx.query("INSERT INTO profiles (user_id) VALUES (?, ?)", [userId]);
   return userId;
 });
 ```

package/core/app.js

@@ -135,6 +135,34 @@ class App {
         });
       };
 
+      res.ok = (data = null, message = "Success") => {
+        return res.success(data, message, 200);
+      };
+
+      res.created = (data = null, message = "Created") => {
+        return res.success(data, message, 201);
+      };
+
+      res.badRequest = (message = "Bad Request", errors = []) => {
+        return res.error(message, 400, errors);
+      };
+
+      res.unauthorized = (message = "Unauthorized") => {
+        return res.error(message, 401);
+      };
+
+      res.forbidden = (message = "Forbidden") => {
+        return res.error(message, 403);
+      };
+
+      res.notFound = (message = "Not Found") => {
+        return res.error(message, 404);
+      };
+
+      res.serverError = (message = "Internal Server Error", errors = []) => {
+        return res.error(message, 500, errors);
+      };
+
       res.paginate = (data = [], pagination = {}, message = "Success") => {
         const page = Number(pagination.page) || 1;
         const limit = Number(pagination.limit) || data.length;
@@ -157,6 +185,20 @@ class App {
       next();
     });
 
+    this.app.get("/api/health", (req, res) => {
+      return res.json({
+        status: "ok",
+        timestamp: new Date().toISOString(),
+        uptime: Math.floor(process.uptime()),
+        environment: props.debug ? "development" : "production",
+        memory: {
+          rss: `${Math.round(process.memoryUsage().rss / 1024 / 1024)}MB`,
+          heapUsed: `${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}MB`,
+        },
+      });
+    });
+
+
     if (this.static.path || props.debug)
       this.app.use(
         express.static(path.join(__dirname, this.static.path || "frontend"), {