te.js 2.0.0 → 2.0.3

package/example/README.md

@@ -1,155 +0,0 @@
-# te.js Example
-
-A comprehensive example demonstrating te.js framework features: routing, middleware, rate limiting, file uploads, services, and optional Redis caching.
-
-## Quick Start
-
-```bash
-npm install
-npm start
-```
-
-Server runs at `http://localhost:1403`
-
-## Project Structure
-
-```
-example/
-├── index.js              # App setup, global middleware, rate limit
-├── targets/              # Routes + handlers
-│   ├── index.target.js   # /, /health, /routes
-│   ├── users.target.js   # CRUD + file uploads (/users, /users/:id, …)
-│   └── cache.target.js   # Redis key-value (optional)
-└── services/             # Business logic
-    ├── user.service.js  # In-memory user CRUD
-    └── cache.service.js # Redis wrapper
-```
-
-## Endpoints
-
-### Index
-
-| Method | Path      | Description                          |
-| ------ | --------- | ------------------------------------ |
-| GET    | `/`       | Default HTML entry                   |
-| GET    | `/health` | Health check                         |
-| GET    | `/routes` | List all registered routes (grouped) |
-
-### Users
-
-| Method | Path                            | Description                       |
-| ------ | ------------------------------- | --------------------------------- |
-| GET    | `/users`                        | List all users                    |
-| POST   | `/users`                        | Create user (JSON body)           |
-| GET    | `/users/:id`                    | Get user by id                    |
-| PUT    | `/users/:id`                    | Update user                       |
-| DELETE | `/users/:id`                    | Delete user                       |
-| POST   | `/users/:id/updateProfileImage` | Single file (field: image)        |
-| POST   | `/users/:id/uploadDocuments`    | Multiple files (field: documents) |
-
-### Cache (requires Redis)
-
-| Method | Path          | Description                        |
-| ------ | ------------- | ---------------------------------- |
-| GET    | `/cache/:key` | Get value                          |
-| POST   | `/cache`      | Set value (body: key, value, ttl?) |
-
-## curl Examples
-
-```bash
-# Health check
-curl http://localhost:1403/health
-
-# List routes
-curl http://localhost:1403/routes
-
-# Users CRUD
-curl -X POST http://localhost:1403/users -H "Content-Type: application/json" -d '{"name":"John","email":"john@example.com"}'
-curl http://localhost:1403/users
-curl http://localhost:1403/users/1
-curl -X PUT http://localhost:1403/users/1 -H "Content-Type: application/json" -d '{"name":"Jane"}'
-curl -X DELETE http://localhost:1403/users/1
-
-# File upload (single)
-curl -X POST http://localhost:1403/users/1/updateProfileImage -F "image=@./photo.jpg"
-
-# File upload (multiple)
-curl -X POST http://localhost:1403/users/1/uploadDocuments -F "documents=@./doc1.pdf" -F "documents=@./doc2.pdf"
-
-# Cache (requires REDIS_URL)
-REDIS_URL=redis://localhost:6379 npm start
-curl -X POST http://localhost:1403/cache -H "Content-Type: application/json" -d '{"key":"foo","value":"bar","ttl":60}'
-curl http://localhost:1403/cache/foo
-```
-
-## Optional: Redis
-
-To enable cache endpoints:
-
-```bash
-npm run start:redis
-```
-
-Or set `REDIS_URL` before starting:
-
-```bash
-# Linux/macOS
-REDIS_URL=redis://localhost:6379 npm start
-
-# Windows (PowerShell)
-$env:REDIS_URL="redis://localhost:6379"; npm start
-```
-
-## Features Demonstrated
-
-- **Routing** — Flat targets, parameterized paths (`:id`)
-- **HTTP methods** — `ammo.GET`, `ammo.POST`, `ammo.notAllowed()`
-- **Body parsing** — JSON, multipart/form-data
-- **Error handling** — `TejError`, `ammo.notFound()`, `ammo.throw()`
-- **File uploads** — `TejFileUploader.file()`, `TejFileUploader.files()`
-- **Middleware** — Global (`app.midair`), target-level (`target.midair`)
-- **Rate limiting** — Memory store (60 req/min)
-- **Services** — Business logic in `services/`
-- **listAllEndpoints** — Route discovery at `/routes`
-
-## Documentation generation
-
-Generate OpenAPI docs and serve them at `/docs`:
-
-```bash
-npx tejas generate:docs
-```
-
-Then use `app.serveDocs({ specPath: './openapi.json' })` in `index.js` (already configured in this example).
-
-### Generate docs on push to production (inbuilt)
-
-To regenerate docs automatically when pushing to your production branch:
-
-1. **Configure** the production branch and (optionally) doc options in `tejas.config.json`:
-
-```json
-"docs": {
-  "dirTargets": "targets",
-  "output": "./openapi.json",
-  "productionBranch": "main"
-}
-```
-
-Set `LLM_API_KEY` (or `OPENAI_API_KEY`) in the environment for non-interactive generation.
-
-2. **Add a pre-push hook** (e.g. with Husky):
-
-```bash
-npx husky add .husky/pre-push "npx tejas docs:on-push"
-```
-
-When you push to `main` (or your configured branch), the framework will run `tejas generate:docs --ci` before the push completes, so `openapi.json` (and optionally `API_OVERVIEW.md`) stay in sync.
-
-For CI pipelines, run:
-
-```bash
-npx tejas generate:docs --ci
-```
-
-See [te.js documentation](https://tejas-documentation.vercel.app) for more.

package/example/index.js

@@ -1,29 +0,0 @@
-import Tejas from 'te.js';
-
-const app = new Tejas();
-
-// Global middleware: request logging
-app.midair((ammo, next) => {
-  console.log(`[${new Date().toISOString()}] ${ammo.method} ${ammo.path}`);
-  next();
-});
-
-// Rate limiting (memory store - no Redis required)
-app.withRateLimit({
-  maxRequests: 60,
-  timeWindowSeconds: 60,
-});
-
-// Serve API docs at /docs (requires openapi.json from `tejas generate:docs`)
-app.serveDocs({ specPath: './openapi.json' });
-
-// Optional: Redis for /cache endpoints. Set REDIS_URL to enable.
-const redisUrl = process.env.REDIS_URL;
-
-app.takeoff(
-  redisUrl
-    ? {
-        withRedis: { url: redisUrl },
-      }
-    : {},
-);

package/example/middlewares/auth.js

@@ -1,9 +0,0 @@
-const auth = (ammo, next) => {
-  if (ammo.headers.authorization === "Bearer 123") {
-    next();
-  } else {
-    return ammo.unauthorized();
-  }
-};
-
-export default auth;

package/example/middlewares/global.midair.js

@@ -1,6 +0,0 @@
-const globalMidair = async (ammo, next) => {
-  console.log('Global middleware');
-  await next();
-};
-
-export { globalMidair };

package/example/openapi.json

@@ -1,390 +0,0 @@
-{
-  "openapi": "3.0.3",
-  "info": {
-    "title": "API",
-    "version": "1.0.0",
-    "description": "# API Documentation\n\n**Version:** 1.0.0\n\n## Project Summary\n\nThis API provides a lightweight service combining user account management, a Redis-backed caching layer, and system introspection utilities. It supports full CRUD operations on user resources—including file uploads for profile images and bulk documents—offers key-value caching with optional TTL, and exposes health-check and route discovery endpoints for operational monitoring and API introspection. User data is maintained in-memory for demonstration purposes, and uploaded files are stored on disk with configurable size limits.\n\n---\n\n## APIs Available\n\n### Users\nManages user accounts with full CRUD operations: create, retrieve, update, and delete users. Additionally supports profile image uploads and bulk document uploads, with files stored on disk and configurable size limits.\n\n### Cache\nProvides a key-value caching layer backed by Redis. Store arbitrary values with an optional time-to-live (TTL) and retrieve them by key. A middleware guard ensures the Redis service is available before processing any cache request.\n\n### System & Discovery\nCore application utilities including a default landing endpoint, a health-check endpoint reporting server status with a current timestamp, and a route discovery endpoint that lists all registered endpoints grouped by source for API introspection.\n\n---\n\n## Key Endpoints\n\n### Getting Started\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/` | Default landing entry point for the API. |\n| `GET` | `/health` | Health check — returns server status and current timestamp. |\n| `GET` | `/routes` | Route discovery — lists all registered endpoints grouped by source. |\n\n### User Management\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/users` | Retrieve a list of all users. |\n| `POST` | `/users` | Create a new user. |\n| `GET` | `/users/{id}` | Retrieve a specific user by ID. |\n| `PUT` | `/users/{id}` | Update an existing user by ID. |\n| `DELETE` | `/users/{id}` | Delete a user by ID. |\n| `GET` | `/users/{id}/updateProfileImage` | Upload or update a user's profile image. |\n| `GET` | `/users/{id}/uploadDocuments` | Bulk upload documents for a user. |\n\n### Cache Operations\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/cache` | Store a value in the cache with an optional TTL. |\n| `GET` | `/cache/{key}` | Retrieve a cached value by its key. |\n\n---\n\n## Additional Notes\n\n### Data Storage\n- **User data** is maintained in-memory and is not persisted across server restarts (demonstration mode).\n- **Uploaded files** (profile images, documents) are stored on disk with configurable size limits.\n\n### Cache Availability\nAll cache endpoints are protected by a middleware guard that verifies the Redis service is reachable before processing requests. If Redis is unavailable, cache requests will be rejected before reaching the handler.\n\n### File Uploads\n- **Profile images**: Single-file upload tied to a specific user via `/users/{id}/updateProfileImage`.\n- **Bulk documents**: Multi-file upload supported via `/users/{id}/uploadDocuments`.\n\nFile size limits are configurable at the application level.\n\n---\n\n## Quick Start\n\n1. **Verify the API is running** — call `GET /health` and confirm a successful status response with a timestamp.\n2. **Explore available routes** — call `GET /routes` to discover all registered endpoints.\n3. **Create a user** — send a `POST` request to `/users` with the required user payload.\n4. **Store and retrieve cache entries** — use `POST /cache` to set a key-value pair, then `GET /cache/{key}` to retrieve it."
-  },
-  "tags": [
-    {
-      "name": "Users",
-      "description": "Manages user accounts with full CRUD operations including creation, retrieval, updating, and deletion. Also supports profile image uploads and bulk document uploads, storing files on disk with configurable size limits. User data is maintained in-memory for demonstration purposes."
-    },
-    {
-      "name": "Cache",
-      "description": "Provides a key-value caching layer backed by Redis. Consumers can store arbitrary values with an optional time-to-live and retrieve them by key. A middleware guard ensures the Redis-backed cache service is available before processing any request."
-    },
-    {
-      "name": "System & Discovery",
-      "description": "Provides core application utilities: a default landing entry point, a health-check endpoint that reports server status with a current timestamp, and a route discovery endpoint that lists all registered endpoints grouped by their source, enabling API introspection."
-    }
-  ],
-  "paths": {
-    "/cache/{key}": {
-      "get": {
-        "summary": "Get cached value by key",
-        "description": "Retrieves a cached value from Redis by its key. Requires the cache service (Redis) to be available.",
-        "parameters": [
-          {
-            "name": "key",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: key",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Cached value found and returned successfully"
-          },
-          "404": {
-            "description": "No cached value found for the given key"
-          },
-          "405": {
-            "description": "Method not allowed (non-GET request made to this endpoint)"
-          },
-          "503": {
-            "description": "Cache service unavailable. Redis is not configured or reachable."
-          }
-        },
-        "tags": [
-          "Cache"
-        ]
-      }
-    },
-    "/cache": {
-      "post": {
-        "summary": "Store a value in the cache",
-        "description": "Sets a key-value pair in the Redis cache with an optional TTL (time-to-live) in seconds. Requires the cache service (Redis) to be available.",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "The cache key under which to store the value"
-                  },
-                  "value": {
-                    "type": "any",
-                    "description": "The value to cache; can be any type but must not be undefined"
-                  },
-                  "ttl": {
-                    "type": "integer",
-                    "description": "Time-to-live in seconds for the cached entry; if omitted, the entry does not expire automatically"
-                  }
-                },
-                "required": [
-                  "key",
-                  "value"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "201": {
-            "description": "Value cached successfully. Returns an object with a confirmation message and the cache key."
-          },
-          "400": {
-            "description": "Validation error: 'key' and 'value' are required fields"
-          },
-          "405": {
-            "description": "Method not allowed. Only POST is accepted on this endpoint."
-          },
-          "503": {
-            "description": "Cache service unavailable. Redis is not configured or not reachable (REDIS_URL not set)."
-          }
-        },
-        "tags": [
-          "Cache"
-        ]
-      }
-    },
-    "/": {
-      "get": {
-        "summary": "Submit data to the default entry endpoint",
-        "description": "Handles POST requests to the root endpoint by returning the default entry response. No specific body processing is performed.\n\nAccepts any HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.",
-        "responses": {
-          "200": {
-            "description": "Default entry content returned successfully"
-          }
-        },
-        "tags": [
-          "System & Discovery"
-        ]
-      }
-    },
-    "/health": {
-      "get": {
-        "summary": "Post health check request",
-        "description": "Accepts a POST request and returns the current health status and timestamp. No request body is required; any provided body is ignored.\n\nAccepts any HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.",
-        "responses": {
-          "200": {
-            "description": "Service is healthy. Returns an object with `status` ('ok') and `timestamp` (ISO 8601 string)."
-          }
-        },
-        "tags": [
-          "System & Discovery"
-        ]
-      }
-    },
-    "/routes": {
-      "get": {
-        "summary": "Create or trigger route listing via POST",
-        "description": "Returns the same grouped listing of all registered endpoints. The handler does not differentiate by HTTP method, so POST behaves identically to GET.\n\nAccepts any HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.",
-        "responses": {
-          "200": {
-            "description": "A grouped object of all registered endpoints and their supported methods"
-          }
-        },
-        "tags": [
-          "System & Discovery"
-        ]
-      }
-    },
-    "/users": {
-      "get": {
-        "summary": "List all users",
-        "description": "Returns an array of all users currently stored in the system.",
-        "responses": {
-          "200": {
-            "description": "An array of user objects. Returns an empty array if no users exist."
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      },
-      "post": {
-        "summary": "Create a new user",
-        "description": "Creates a new user with the provided name and email. Returns the newly created user object with a generated id and createdAt timestamp.",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "name": {
-                    "type": "string"
-                  },
-                  "email": {
-                    "type": "string",
-                    "format": "email"
-                  }
-                },
-                "required": [
-                  "name",
-                  "email"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "201": {
-            "description": "User created successfully. Returns the new user object including id, name, email, and createdAt fields."
-          },
-          "400": {
-            "description": "Validation error. Both name and email are required."
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      }
-    },
-    "/users/{id}": {
-      "get": {
-        "summary": "Get user by id",
-        "description": "Retrieves a single user by their unique identifier.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: id",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "User object returned successfully"
-          },
-          "404": {
-            "description": "User not found"
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      },
-      "put": {
-        "summary": "Update user",
-        "description": "Updates an existing user's name and/or email by their unique identifier.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: id",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "name": {
-                    "type": "string"
-                  },
-                  "email": {
-                    "type": "string",
-                    "format": "email"
-                  }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "User updated successfully"
-          },
-          "404": {
-            "description": "User not found"
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      },
-      "delete": {
-        "summary": "Delete user",
-        "description": "Deletes a user by their unique identifier.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: id",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "responses": {
-          "204": {
-            "description": "User deleted successfully"
-          },
-          "404": {
-            "description": "User not found"
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      }
-    },
-    "/users/{id}/updateProfileImage": {
-      "get": {
-        "summary": "Upload a profile image for a user",
-        "description": "Uploads a single profile image file for the specified user. Uses multipart/form-data with a file field named 'image'. Maximum file size is 5MB. Files are stored in 'public/uploads'.\n\nAccepts any HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: id",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "image": {
-                    "type": "file",
-                    "description": "The profile image file to upload (max 5MB)"
-                  }
-                },
-                "required": [
-                  "image"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Profile image uploaded successfully. Returns a message and the uploaded file metadata."
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      }
-    },
-    "/users/{id}/uploadDocuments": {
-      "get": {
-        "summary": "Upload documents for a user",
-        "description": "Uploads multiple document files for the user identified by :id. Files are processed by the TejFileUploader middleware with a max file size of 5MB each and stored in 'public/uploads'.\n\nAccepts any HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "Path parameter: id",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "documents": {
-                    "type": "array",
-                    "description": "Array of document files to upload. Field name must be 'documents'. Each file must not exceed 5MB."
-                  }
-                },
-                "required": [
-                  "documents"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Documents uploaded successfully. Returns a message indicating the number of documents uploaded and an array of file metadata."
-          }
-        },
-        "tags": [
-          "Users"
-        ]
-      }
-    }
-  }
-}

package/example/package.json

@@ -1,23 +0,0 @@
-{
-  "name": "example",
-  "version": "1.0.0",
-  "description": "Comprehensive te.js example - routing, middleware, file uploads, services",
-  "main": "index.js",
-  "type": "module",
-  "scripts": {
-    "start": "node index.js",
-    "start:redis": "node start-redis.js",
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "prettify": "prettier --write --ignore-unknown"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "dependencies": {
-    "cors": "^2.8.5",
-    "mongoose": "^8.3.1",
-    "redis": "^4.7.0",
-    "te.js": "file:..",
-    "tej-env": "^1.0.2"
-  }
-}

package/example/services/cache.service.js

@@ -1,25 +0,0 @@
-/**
- * Cache service - Redis wrapper for key-value storage.
- * Requires Redis connection via app.takeoff({ withRedis: { url } }).
- */
-
-import dbManager from 'te.js/database/index.js';
-
-export function isAvailable() {
-  const { exists } = dbManager.hasConnection('redis', {});
-  return exists;
-}
-
-export async function get(key) {
-  const redis = dbManager.getConnection('redis');
-  return redis.get(key);
-}
-
-export async function set(key, value, ttlSeconds) {
-  const redis = dbManager.getConnection('redis');
-  if (ttlSeconds) {
-    await redis.setEx(key, ttlSeconds, String(value));
-  } else {
-    await redis.set(key, String(value));
-  }
-}

package/example/services/user.service.js

@@ -1,42 +0,0 @@
-/**
- * User service - in-memory CRUD for demo purposes.
- * Demonstrates business logic extraction from route handlers.
- */
-
-const store = [];
-let nextId = 1;
-
-export default {
-  list() {
-    return [...store];
-  },
-
-  getById(id) {
-    return store.find((u) => String(u.id) === String(id));
-  },
-
-  create({ name, email }) {
-    if (!name || !email) {
-      return null;
-    }
-    const user = { id: nextId++, name, email, createdAt: new Date().toISOString() };
-    store.push(user);
-    return user;
-  },
-
-  update(id, { name, email }) {
-    const user = this.getById(id);
-    if (!user) return null;
-    if (name !== undefined) user.name = name;
-    if (email !== undefined) user.email = email;
-    user.updatedAt = new Date().toISOString();
-    return user;
-  },
-
-  delete(id) {
-    const index = store.findIndex((u) => String(u.id) === String(id));
-    if (index === -1) return false;
-    store.splice(index, 1);
-    return true;
-  },
-};