te.js 2.0.1 → 2.0.3

package/.cursor/plans/tejas_framework_test_suite_5e3c6fad.plan.md

@@ -1,168 +0,0 @@
----
-name: Tejas Framework Test Suite
-overview: Create a comprehensive test suite using Vitest for all core features of the Tejas framework, including unit tests, integration tests, edge cases, and error scenarios.
-todos:
-  - id: setup-vitest
-    content: Set up Vitest configuration and install dependencies
-    status: completed
-  - id: test-helpers
-    content: Create test helper utilities and HTTP mocks
-    status: pending
-  - id: test-ammo
-    content: Write unit tests for Ammo class (fire, throw, redirect, shortcuts)
-    status: pending
-  - id: test-target-registry
-    content: Write tests for Target class and TargetRegistry route matching
-    status: pending
-  - id: test-body-parser
-    content: Write tests for body parser (JSON, URL-encoded, multipart)
-    status: pending
-  - id: test-rate-limiting
-    content: Write tests for all 3 rate limiting algorithms
-    status: pending
-  - id: test-file-uploader
-    content: Write tests for file upload middleware
-    status: pending
-  - id: test-configuration
-    content: Write tests for configuration loading and standardization
-    status: pending
-  - id: test-handler-integration
-    content: Write integration tests for request handler and middleware chain
-    status: pending
----
-
-# Tejas Framework Test Suite Plan
-
-Create comprehensive tests using Vitest for all core features of the Tejas framework, organized by module with unit, integration, and error scenario coverage.
-
-## Test Infrastructure Setup
-
-Install Vitest and configure for ES modules. Create test utilities and mocks for HTTP requests, database connections, and file system operations.**Files to create:**
-
-- `vitest.config.js` - Vitest configuration with ESM support
-- `tests/helpers/mock-http.js` - HTTP request/response mocks
-- `tests/helpers/test-utils.js` - Common test utilities
-
-## Core Module Tests
-
-### 1. Ammo Class ([server/ammo.js](server/ammo.js))
-
-Unit tests for the request/response handler:
-
-- HTTP method flag initialization (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
-- `fire()` response dispatch with various argument patterns (status only, data only, status+data, status+data+content-type)
-- `redirect()` with default and custom status codes
-- `throw()` error handling (TejError, Error instances, status codes, strings)
-- `notFound()`, `notAllowed()`, `unauthorized()` shortcuts
-- `enhance()` method populating request properties
-
-### 2. Target & Registry ([server/target.js](server/target.js), [server/targets/registry.js](server/targets/registry.js))
-
-Unit tests for routing:
-
-- Target constructor with base path
-- `midair()` middleware registration
-- `register()` endpoint registration with path + handler + optional middlewares
-- TargetRegistry singleton pattern
-- `aim()` exact path matching
-- `aim()` parameterized route matching (`/users/:id`, `/api/:category/:id`)
-- `getAllEndpoints()` listing (flat and grouped)
-
-### 3. Request Handler ([server/handler.js](server/handler.js))
-
-Integration tests for request processing:
-
-- Middleware chain execution order
-- Global + target + route middleware composition
-- Async middleware handling
-- Error propagation through chain
-- 404 handling for unmatched routes
-- Response already sent detection
-
-### 4. Body Parser ([server/ammo/body-parser.js](server/ammo/body-parser.js))
-
-Unit tests for request body parsing:
-
-- JSON body parsing (valid, invalid, empty)
-- URL-encoded body parsing
-- Multipart form data parsing with boundary extraction
-- Body size limit enforcement (413 errors)
-- Request timeout handling (408 errors)
-- Missing content-type handling
-
-### 5. Rate Limiting ([rate-limit/](rate-limit/))
-
-Unit tests for each algorithm:
-
-- **Fixed Window:** Counter increments, window reset, strict mode alignment
-- **Sliding Window:** Weighted counts, timestamp pruning, window transitions
-- **Token Bucket:** Token consumption, refill rate, burst handling
-- Storage interface (memory operations)
-- Rate limit header generation (standard, legacy, draft7, draft8)
-- `onRateLimited` callback
-
-### 6. File Uploader ([server/files/uploader.js](server/files/uploader.js))
-
-Unit tests for file handling:
-
-- Single file upload with `file()` middleware
-- Multiple file upload with `files()` middleware
-- File size validation (413 errors for oversized files)
-- File metadata extraction (extension, mimetype, path)
-- Non-multipart request passthrough
-- Directory creation
-
-### 7. Configuration ([utils/configuration.js](utils/configuration.js))
-
-Unit tests for config processing:
-
-- `loadConfigFile()` file reading and JSON parsing
-- `standardizeObj()` key uppercasing and flattening
-- Missing config file handling
-- Nested object flattening with underscores
-
-### 8. TejError ([server/error.js](server/error.js))
-
-Unit tests for custom error:
-
-- Constructor with code and message
-- Error inheritance
-- Name property
-
-### 9. Database Manager ([database/index.js](database/index.js))
-
-Unit tests (mocked connections):
-
-- Singleton pattern enforcement
-- Connection initialization tracking
-- `hasConnection()` status checking
-- `getConnection()` retrieval
-- Connection not found error
-
-## Test File Structure
-
-```javascript
-tests/
-  helpers/
-    mock-http.js
-    test-utils.js
-  unit/
-    ammo.test.js
-    target.test.js
-    registry.test.js
-    body-parser.test.js
-    rate-limit/
-      fixed-window.test.js
-      sliding-window.test.js
-      token-bucket.test.js
-    file-uploader.test.js
-    configuration.test.js
-    tej-error.test.js
-    database-manager.test.js
-  integration/
-    handler.test.js
-    middleware-chain.test.js
-    rate-limit-middleware.test.js
-
-
-```

package/.prettierignore

@@ -1,31 +0,0 @@
-# Dependencies
-node_modules/
-package-lock.json
-yarn.lock
-
-# Build output
-dist/
-build/
-*.min.js
-
-# Coverage directory
-coverage/
-
-# Cache directories
-.cache/
-.npm/
-
-# Logs
-logs/
-*.log
-npm-debug.log*
-
-# IDE specific files
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# System Files
-.DS_Store
-Thumbs.db

package/.prettierrc

@@ -1,5 +0,0 @@
-{
-  "singleQuote": true,
-  "printWidth": 80,
-  "semi": true
-}

package/example/API_OVERVIEW.md

@@ -1,77 +0,0 @@
-# API Documentation
-
-**Version:** 1.0.0
-
-## Project Summary
-
-This 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.
-
----
-
-## APIs Available
-
-### Users
-Manages 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.
-
-### Cache
-Provides 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.
-
-### System & Discovery
-Core 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.
-
----
-
-## Key Endpoints
-
-### Getting Started
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/` | Default landing entry point for the API. |
-| `GET` | `/health` | Health check — returns server status and current timestamp. |
-| `GET` | `/routes` | Route discovery — lists all registered endpoints grouped by source. |
-
-### User Management
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/users` | Retrieve a list of all users. |
-| `POST` | `/users` | Create a new user. |
-| `GET` | `/users/{id}` | Retrieve a specific user by ID. |
-| `PUT` | `/users/{id}` | Update an existing user by ID. |
-| `DELETE` | `/users/{id}` | Delete a user by ID. |
-| `GET` | `/users/{id}/updateProfileImage` | Upload or update a user's profile image. |
-| `GET` | `/users/{id}/uploadDocuments` | Bulk upload documents for a user. |
-
-### Cache Operations
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/cache` | Store a value in the cache with an optional TTL. |
-| `GET` | `/cache/{key}` | Retrieve a cached value by its key. |
-
----
-
-## Additional Notes
-
-### Data Storage
-- **User data** is maintained in-memory and is not persisted across server restarts (demonstration mode).
-- **Uploaded files** (profile images, documents) are stored on disk with configurable size limits.
-
-### Cache Availability
-All 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.
-
-### File Uploads
-- **Profile images**: Single-file upload tied to a specific user via `/users/{id}/updateProfileImage`.
-- **Bulk documents**: Multi-file upload supported via `/users/{id}/uploadDocuments`.
-
-File size limits are configurable at the application level.
-
----
-
-## Quick Start
-
-1. **Verify the API is running** — call `GET /health` and confirm a successful status response with a timestamp.
-2. **Explore available routes** — call `GET /routes` to discover all registered endpoints.
-3. **Create a user** — send a `POST` request to `/users` with the required user payload.
-4. **Store and retrieve cache entries** — use `POST /cache` to set a key-value pair, then `GET /cache/{key}` to retrieve it.

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 };