@seip/blue-bird 1.0.1 → 1.1.0

package/.env_example

@@ -6,6 +6,7 @@ APP_URL="http://localhost"
 VERSION="1.0.0"
 
 # Docker / Swagger Config
+COMPOSE_PROJECT_NAME="blue-bird"
 TITLE="Blue-Bird"
 DESCRIPTION="Description project"
 

package/AGENTS.md

@@ -6,7 +6,7 @@ This document serves as the primary manual for any AI Agent interacting with the
 
 Blue Bird is a performance-first API framework built on **Express**. It saves developers from repetitive configuration, validation, security, JWT authentication, and database environment configuration out of the box, delegating all static frontend rendering to Nginx.
 
-- **Entrypoint (`index.js`)**: Initializes the server using `App` from `core/app.js` and registers the routes.
+- **Entrypoint (`backend/index.js`)**: Initializes the server using `App` from `core/app.js` and registers the routes.
 - **Backend (`backend/`)**: Application routes and logic (e.g. `backend/routes/`).
 - **Frontend (`frontend/`)**: Static assets (HTML, CSS, JS). Handled directly by Nginx in production, bypassing Express.
 - **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
@@ -87,9 +87,17 @@ If an Express route involves heavy processing or database queries, utilize the `
 ```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 });
 });
+
+// Programmatic cache manipulation
+await Cache.set("custom_key", { data: "value" }, 120);
+const cachedData = await Cache.get("custom_key");
+
+// Invalidate route cache manually (e.g. after updating DB)
+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.

package/README.md

@@ -222,6 +222,20 @@ router.get("/stats", Cache.middleware(60), (req, res) => {
 });
 ```
 
+#### Programmatic Cache Manipulation & Invalidation
+
+```javascript
+// Get / Set keys programmatically
+await Cache.set("custom_key", { data: "value" }, 120);
+const cachedData = await Cache.get("custom_key");
+
+// Manually invalidate route cache (e.g. after updating DB)
+await Cache.delete("/api/public/config");
+
+// Clear all cache entries
+await Cache.clear();
+```
+
 #### Custom Database & Data Caching with `getRedisClient()`
 
 ```javascript

package/core/cache.js

@@ -162,6 +162,137 @@ class Cache {
       next();
     };
   }
+
+  /**
+   * Retrieves cached value by key.
+   * @param {string} key - Cache key.
+   * @returns {Promise<any|null>} Cached payload or null.
+   */
+  static async get(key) {
+    key = key.trim();
+    if (!key) return null;
+
+    if (redisHost && !redisClient) {
+      await initRedis().catch(() => { });
+    }
+
+    if (isRedisConnected && redisClient) {
+      try {
+        const cachedData = await redisClient.get(key);
+        if (cachedData) {
+          try {
+            const cached = JSON.parse(cachedData);
+            return cached && typeof cached === "object" && "data" in cached ? cached.data : cached;
+          } catch {
+            return cachedData;
+          }
+        }
+        return null;
+      } catch (err) {
+        isRedisConnected = false;
+      }
+    }
+
+    if (CACHE[key]) {
+      if (CACHE[key].expiry > Date.now()) {
+        const cached = CACHE[key];
+        return cached.data !== undefined ? cached.data : cached;
+      }
+      delete CACHE[key];
+    }
+
+    return null;
+  }
+
+  /**
+   * Sets data into cache with a specified TTL in seconds.
+   * @param {string} key - Cache key.
+   * @param {any} value - Data to cache.
+   * @param {number} [seconds=60] - Expiry time in seconds.
+   * @returns {Promise<boolean>} True if set successfully.
+   */
+  static async set(key, value, seconds = 60) {
+    key = key.trim();
+    if (!key) return false;
+
+    if (redisHost && !redisClient) {
+      await initRedis().catch(() => { });
+    }
+
+    const cacheObject = {
+      type: typeof value === "string" ? "html" : "json",
+      data: value,
+      expiry: Date.now() + seconds * 1000,
+    };
+
+    if (isRedisConnected && redisClient) {
+      try {
+        await redisClient.set(key, JSON.stringify(cacheObject), {
+          EX: seconds,
+        });
+      } catch (err) {
+        CACHE[key] = cacheObject;
+      }
+    } else {
+      CACHE[key] = cacheObject;
+    }
+
+    return true;
+  }
+
+  /**
+   * Deletes one or more entries from cache.
+   * @param {string|string[]} keys - Single key or array of keys to delete.
+   * @returns {Promise<boolean>} True if deleted.
+   */
+  static async delete(keys) {
+    if (!keys) return false;
+    const keyList = Array.isArray(keys) ? keys : [keys];
+
+    if (redisHost && !redisClient) {
+      await initRedis().catch(() => { });
+    }
+
+    for (const key of keyList) {
+      delete CACHE[key];
+      if (isRedisConnected && redisClient) {
+        try {
+          await redisClient.del(key);
+        } catch (err) {
+          isRedisConnected = false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Alias for delete.
+   * @param {string|string[]} keys - Single key or array of keys to delete.
+   * @returns {Promise<boolean>} True if deleted.
+   */
+  static async del(keys) {
+    return this.delete(keys);
+  }
+
+  /**
+   * Flushes all cached data in memory (and Redis if connected).
+   * @returns {Promise<boolean>} True if flushed.
+   */
+  static async clear() {
+    for (const key in CACHE) {
+      delete CACHE[key];
+    }
+    if (isRedisConnected && redisClient) {
+      try {
+        await redisClient.flushDb();
+      } catch (err) {
+        isRedisConnected = false;
+      }
+    }
+    return true;
+  }
 }
 
 /**

package/core/cli/docker.js

@@ -145,25 +145,25 @@ async function startCommand(service) {
 /**
  * Handles the 'dev' CLI command.
  */
-async function devCommand() {
-  checkComposeFile();
-  const dbType = getDbType();
-  console.log(chalk.cyan("Starting development environment (Database + Redis)..."));
-
-  const containers = ["redis"];
-  if (dbType !== "none") {
-    containers.unshift(dbType);
-  }
-
-  const code = await runCmd("docker", ["compose", "up", "-d", ...containers]);
-  if (code === 0) {
-    console.log(chalk.green("Development containers started."));
-    console.log(chalk.cyan("View live logs with: npx blue-bird docker logs db"));
-    console.log(chalk.yellow("Now execute: npm run dev"));
-  } else {
-    console.error(chalk.red("Error starting development environment."));
-    process.exit(1);
-  }
+async function devCommand() {
+  checkComposeFile();
+  const dbType = getDbType();
+  console.log(chalk.cyan("Starting development environment (Database + Redis)..."));
+
+  const containers = ["redis"];
+  if (dbType !== "none") {
+    containers.unshift(dbType);
+  }
+
+  const code = await runCmd("docker", ["compose", "up", "-d", ...containers]);
+  if (code === 0) {
+    console.log(chalk.green("Development containers started."));
+    console.log(chalk.cyan("View live logs with: npx blue-bird docker logs db"));
+    console.log(chalk.yellow("Now execute: npm run dev"));
+  } else {
+    console.error(chalk.red("Error starting development environment."));
+    process.exit(1);
+  }
 }
 
 /**

package/core/cli/init.js

@@ -103,8 +103,6 @@ class ProjectInit {
       "docker",
       ".env_example",
       "AGENTS.md",
-      "index.js",
-      ".gitignore"
     ];
 
     try {
@@ -128,6 +126,24 @@ class ProjectInit {
         }
       });
 
+      const gitignoreContent = `node_modules\nlogs\n.env\npackage-lock.json\n*.db\ntest/\n\nbackups/*.sql\n`;
+      const gitignoreDest = path.join(this.appDir, ".gitignore");
+      const gitignoreSrc = path.join(this.sourceDir, ".gitignore");
+
+      if (!fs.existsSync(gitignoreDest)) {
+        if (fs.existsSync(gitignoreSrc)) {
+          fs.copyFileSync(gitignoreSrc, gitignoreDest);
+          console.log(chalk.green("[OK] Copied .gitignore to root."));
+        } else {
+          fs.writeFileSync(gitignoreDest, gitignoreContent, "utf-8");
+          console.log(chalk.green("[OK] Created .gitignore file."));
+        }
+      } else {
+        console.log(
+          chalk.yellow("[SKIP] .gitignore already exists, skipping."),
+        );
+      }
+
       const composeTemplateName =
         dbType === "postgres"
           ? "docker-compose.postgres.yml"
@@ -166,8 +182,15 @@ class ProjectInit {
         let envContent = fs.readFileSync(envExamplePath, "utf-8");
 
         const jwtSecret = crypto.randomBytes(32).toString("hex");
+        const composeProjectName =
+          title
+            .toLowerCase()
+            .trim()
+            .replace(/\s+/g, "-")
+            .replace(/[^a-z0-9_-]/g, "") || "blue-bird";
 
         const updates = {
+          COMPOSE_PROJECT_NAME: composeProjectName,
           TITLE: title,
           PORT: port,
           APP_URL: appUrl,
@@ -190,10 +213,14 @@ class ProjectInit {
         }
 
         const lines = envContent.split(/\r?\n/);
+        let foundComposeProjectName = false;
         const updatedLines = lines.map((line) => {
           const match = line.match(/^([A-Z_]+)=(.+)/);
           if (match) {
             const key = match[1];
+            if (key === "COMPOSE_PROJECT_NAME") {
+              foundComposeProjectName = true;
+            }
             if (updates[key] !== undefined) {
               const value = updates[key];
               if (typeof value === "string" && !value.startsWith('"')) {
@@ -204,6 +231,21 @@ class ProjectInit {
           }
           return line;
         });
+
+        if (!foundComposeProjectName && updates.COMPOSE_PROJECT_NAME) {
+          const titleIdx = updatedLines.findIndex((l) => l.startsWith("TITLE="));
+          if (titleIdx !== -1) {
+            updatedLines.splice(
+              titleIdx,
+              0,
+              `COMPOSE_PROJECT_NAME="${updates.COMPOSE_PROJECT_NAME}"`,
+            );
+          } else {
+            updatedLines.push(
+              `COMPOSE_PROJECT_NAME="${updates.COMPOSE_PROJECT_NAME}"`,
+            );
+          }
+        }
         envContent = updatedLines.join("\n");
 
         fs.writeFileSync(envPath, envContent, "utf-8");

package/core/index.d.ts

@@ -1,132 +1,137 @@
-import { Router as ExpressRouter, Request, Response, NextFunction } from "express";
-
-declare global {
-  namespace Express {
-    interface Response {
-      /**
-       * Sends a standardized JSON success response.
-       * @param data Data payload to return.
-       * @param message Success message.
-       * @param statusCode HTTP status code (default: 200).
-       */
-      success(data?: any, message?: string, statusCode?: number): Response;
-
-      /**
-       * Sends a standardized JSON error response.
-       * @param message Error message.
-       * @param statusCode HTTP status code (default: 400).
-       * @param errors Array or object of detailed errors.
-       */
-      error(message?: string, statusCode?: number, errors?: any): Response;
-
-      /**
-       * Sends a standardized paginated JSON response.
-       * @param data Array of records for current page.
-       * @param pagination Object containing page, limit, and total count.
-       * @param message Success message.
-       */
-      paginate(
-        data?: any[],
-        pagination?: { page?: number; limit?: number; total?: number },
-        message?: string
-      ): Response;
-    }
-  }
-}
-
-export class AppError extends Error {
-  statusCode: number;
-  errors: any;
-  isOperational: boolean;
-
-  constructor(message: string, statusCode?: number, errors?: any);
-}
-
-export class App {
-  constructor(options?: {
-    routes?: any[];
-    cors?: any;
-    middlewares?: any[];
-    port?: number | string;
-    host?: string;
-    logger?: boolean;
-    notFound?: boolean;
-    json?: boolean;
-    urlencoded?: boolean;
-    static?: { path: string; options?: any };
-    cookieParser?: boolean;
-    rateLimit?: boolean | any;
-    swagger?: boolean | any;
-    compression?: boolean;
-  });
-
-  use(record: any): void;
-  set(key: string, value: any): void;
-  websocket(
-    options?:
-      | ((ws: any, req: any) => void)
-      | { path?: string; auth?: boolean }
-  ): WebSocketManager;
-  run(): void;
-
-  static helmet(options?: any): any;
-}
-
-export class WebSocketManager {
-  constructor(server: any, options?: { path?: string; auth?: boolean });
-  onConnection(handler: (ws: any, req: any) => void): void;
-  join(room: string, ws: any): void;
-  leave(room: string, ws: any): void;
-  broadcast(data: any, room?: string | null): void;
-}
-
-export class Router {
-  constructor(path?: string, options?: { seo?: boolean; languages?: string[] });
-
-  use(...middleware: any[]): void;
-  get(path: string | RegExp, ...callback: any[]): void;
-  post(path: string | RegExp, ...callback: any[]): void;
-  put(path: string | RegExp, ...callback: any[]): void;
-  delete(path: string | RegExp, ...callback: any[]): void;
-  patch(path: string | RegExp, ...callback: any[]): void;
-  options(path: string | RegExp, ...callback: any[]): void;
-  getRouter(): ExpressRouter;
-  getPath(): string;
-}
-
-export class Validator {
-  constructor(schema: Record<string, any>, lang?: string);
-  middleware(): (req: Request, res: Response, next: NextFunction) => void;
-  validate(data: Record<string, any>): { valid: boolean; errors: any[] };
-}
-
-export class Auth {
-  static encrypt(payload: any, secret: string): string;
-  static decrypt(data: string, secret: string): any;
-  static generateToken(payload: any, secret?: string, expiresIn?: string | number): string;
-  static verifyToken(token: string, secret?: string): any;
-  static protect(options?: { redirect?: string | null; key?: string; cookieKey?: string }): (req: Request, res: Response, next: NextFunction) => Promise<any>;
-  static login(res: Response, data: any, key?: string, options?: { expiresIn?: string | number; cookie?: any }): Promise<string>;
-  static logout(res: Response, key?: string, options?: any, req?: Request): Promise<boolean>;
-}
-
-export class Cache {
-  static middleware(seconds?: number): (req: Request, res: Response, next: NextFunction) => Promise<any>;
-}
-
-export function getRedisClient(): any;
-
-export class Database {
-  constructor(connectionLimit?: number, queueLimit?: number, config?: any);
-  init(retries?: number): Promise<boolean>;
-  query(sql: string, params?: any[], options?: any): Promise<any>;
-  paginate(
-    sql: string,
-    params?: any[],
-    options?: { page?: number; limit?: number; cache?: number }
-  ): Promise<{ data: any[]; total: number; page: number; limit: number; totalPages: number }>;
-  transaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
-  executeTransaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
-}
-
-export default App;
+import { Router as ExpressRouter, Request, Response, NextFunction } from "express";
+
+declare global {
+  namespace Express {
+    interface Response {
+      /**
+       * Sends a standardized JSON success response.
+       * @param data Data payload to return.
+       * @param message Success message.
+       * @param statusCode HTTP status code (default: 200).
+       */
+      success(data?: any, message?: string, statusCode?: number): Response;
+
+      /**
+       * Sends a standardized JSON error response.
+       * @param message Error message.
+       * @param statusCode HTTP status code (default: 400).
+       * @param errors Array or object of detailed errors.
+       */
+      error(message?: string, statusCode?: number, errors?: any): Response;
+
+      /**
+       * Sends a standardized paginated JSON response.
+       * @param data Array of records for current page.
+       * @param pagination Object containing page, limit, and total count.
+       * @param message Success message.
+       */
+      paginate(
+        data?: any[],
+        pagination?: { page?: number; limit?: number; total?: number },
+        message?: string
+      ): Response;
+    }
+  }
+}
+
+export class AppError extends Error {
+  statusCode: number;
+  errors: any;
+  isOperational: boolean;
+
+  constructor(message: string, statusCode?: number, errors?: any);
+}
+
+export class App {
+  constructor(options?: {
+    routes?: any[];
+    cors?: any;
+    middlewares?: any[];
+    port?: number | string;
+    host?: string;
+    logger?: boolean;
+    notFound?: boolean;
+    json?: boolean;
+    urlencoded?: boolean;
+    static?: { path: string; options?: any };
+    cookieParser?: boolean;
+    rateLimit?: boolean | any;
+    swagger?: boolean | any;
+    compression?: boolean;
+  });
+
+  use(record: any): void;
+  set(key: string, value: any): void;
+  websocket(
+    options?:
+      | ((ws: any, req: any) => void)
+      | { path?: string; auth?: boolean }
+  ): WebSocketManager;
+  run(): void;
+
+  static helmet(options?: any): any;
+}
+
+export class WebSocketManager {
+  constructor(server: any, options?: { path?: string; auth?: boolean });
+  onConnection(handler: (ws: any, req: any) => void): void;
+  join(room: string, ws: any): void;
+  leave(room: string, ws: any): void;
+  broadcast(data: any, room?: string | null): void;
+}
+
+export class Router {
+  constructor(path?: string, options?: { seo?: boolean; languages?: string[] });
+
+  use(...middleware: any[]): void;
+  get(path: string | RegExp, ...callback: any[]): void;
+  post(path: string | RegExp, ...callback: any[]): void;
+  put(path: string | RegExp, ...callback: any[]): void;
+  delete(path: string | RegExp, ...callback: any[]): void;
+  patch(path: string | RegExp, ...callback: any[]): void;
+  options(path: string | RegExp, ...callback: any[]): void;
+  getRouter(): ExpressRouter;
+  getPath(): string;
+}
+
+export class Validator {
+  constructor(schema: Record<string, any>, lang?: string);
+  middleware(): (req: Request, res: Response, next: NextFunction) => void;
+  validate(data: Record<string, any>): { valid: boolean; errors: any[] };
+}
+
+export class Auth {
+  static encrypt(payload: any, secret: string): string;
+  static decrypt(data: string, secret: string): any;
+  static generateToken(payload: any, secret?: string, expiresIn?: string | number): string;
+  static verifyToken(token: string, secret?: string): any;
+  static protect(options?: { redirect?: string | null; key?: string; cookieKey?: string }): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+  static login(res: Response, data: any, key?: string, options?: { expiresIn?: string | number; cookie?: any }): Promise<string>;
+  static logout(res: Response, key?: string, options?: any, req?: Request): Promise<boolean>;
+}
+
+export class Cache {
+  static middleware(seconds?: number): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+  static get(key: string): Promise<any | null>;
+  static set(key: string, value: any, seconds?: number): Promise<boolean>;
+  static delete(keys: string | string[]): Promise<boolean>;
+  static del(keys: string | string[]): Promise<boolean>;
+  static clear(): Promise<boolean>;
+}
+
+export function getRedisClient(): any;
+
+export class Database {
+  constructor(connectionLimit?: number, queueLimit?: number, config?: any);
+  init(retries?: number): Promise<boolean>;
+  query(sql: string, params?: any[], options?: any): Promise<any>;
+  paginate(
+    sql: string,
+    params?: any[],
+    options?: { page?: number; limit?: number; cache?: number }
+  ): Promise<{ data: any[]; total: number; page: number; limit: number; totalPages: number }>;
+  transaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+  executeTransaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+}
+
+export default App;