te.js 1.3.1 → 2.0.1

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

@@ -0,0 +1,168 @@
+---
+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

@@ -0,0 +1,31 @@
+# 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/README.md

@@ -1,20 +1,187 @@
-<h1 align="center" id="title">te.js (WIP)</h1>
+<p align="center">
+  <img src="https://tejas-documentation.vercel.app/tejas-logo.svg" alt="Tejas Logo" width="200">
+</p>
 
-<p align="center"><img src="https://tejas-documentation.vercel.app/tejas-logo.svg" alt="project-image"></p>
+<h1 align="center">Tejas</h1>
 
-<p id="description">A Node Framework For Powerful Backend Services</p>
+<p align="center">
+  <strong>A Node.js Framework for Powerful Backend Services</strong>
+</p>
 
-<h3><a href="https://tejas-documentation.vercel.app" target="_blank">Documentation (WIP)</a></h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/te.js"><img src="https://img.shields.io/npm/v/te.js.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/te.js"><img src="https://img.shields.io/npm/dm/te.js.svg" alt="npm downloads"></a>
+  <a href="https://github.com/hirakchhatbar/te.js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/te.js.svg" alt="license"></a>
+</p>
 
-<h2>Planned Features</h2>
+<p align="center">
+  <a href="https://tejas-documentation.vercel.app">Documentation</a> •
+  <a href="#ai-assisted-setup-mcp">AI Setup (MCP)</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="./docs">Full Docs</a>
+</p>
 
+---
 
-*   Robust exception handling so that your app never dies even if you forget to catch it.
-*   Offers a powerful and flexible routing system that enables method-free and clean URL structures.
-*   Fully compatible with Express middlewares as well as the ability to build te.js middlewares.
-*   Built-in logger to log all the requests responses and errors to help you debug your application.
-*   Built-in GUI to manage your application environment variables view logs and run schedulers.
-*   Real-time insights into the performance health and usage of your application with built-in monitoring.
-*   Built in alerts via Email SMS or Slack to notify you of any exceptions and malformed requests.
-*   Highly configurable caching options to cache responses at different levels to improve performance.
-*   Protect your API from abuse and control the rate of requests that clients can make to your API.
+## What is Tejas?
+
+Tejas (meaning "radiance" in Hindi) is a modern, lightweight Node.js framework designed for building robust backend services. It offers an intuitive API with aviation-inspired naming conventions, making your code both expressive and enjoyable to write.
+
+```javascript
+import Tejas, { Target } from 'te.js';
+
+const app = new Tejas();
+const api = new Target('/api');
+
+api.register('/hello/:name', (ammo) => {
+  ammo.fire({ message: `Hello, ${ammo.payload.name}!` });
+});
+
+app.takeoff();
+```
+
+## Features
+
+- **AI-Native (MCP)** — Ship with an MCP server so AI assistants can scaffold projects, generate routes, and write correct code with full framework knowledge
+- **Simple Routing** — Clean, method-agnostic URL structures with parameterized routes
+- **Express Compatible** — Use existing Express middleware alongside Tejas middleware
+- **Zero-Config Error Handling** — No try-catch needed! Tejas catches all errors automatically
+- **Built-in Rate Limiting** — Three algorithms (Token Bucket, Sliding Window, Fixed Window) with memory or Redis storage
+- **Database Ready** — First-class Redis and MongoDB support with auto-install of drivers
+- **File Uploads** — Easy file handling with size limits and type validation
+- **Auto-Documentation** — Generate OpenAPI specs from your code with LLM-powered analysis (`tejas generate:docs`)
+- **Interactive API Docs** — Serve a Scalar API reference UI with `app.serveDocs()`
+- **Auto-Discovery** — Automatic route registration from `.target.js` files
+- **Request Logging** — Built-in HTTP request and exception logging
+
+## AI-Assisted Setup (MCP)
+
+> **Recommended** — The best way to get started with Tejas in the age of AI.
+
+The [Tejas MCP server](https://www.npmjs.com/package/tejas-mcp) gives your IDE's AI assistant full knowledge of the framework — documentation, code examples, and purpose-built tools to scaffold projects and generate correct code. No more hallucinated APIs.
+
+**Cursor** — add this to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tejas": {
+      "command": "npx",
+      "args": ["-y", "tejas-mcp"]
+    }
+  }
+}
+```
+
+**Other MCP-compatible IDEs** — run `npx tejas-mcp` as the server command (stdio transport, no config needed).
+
+Once connected, prompt your AI with things like *"Scaffold a new te.js project called my-api"* or *"Create a REST API with user CRUD routes"* — the assistant will generate framework-correct code using real te.js patterns.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install te.js
+```
+
+### Create Your App
+
+```javascript
+// index.js
+import Tejas from 'te.js';
+
+const app = new Tejas({ port: 3000 });
+app.takeoff();
+```
+
+### Define Routes
+
+```javascript
+// targets/user.target.js
+import { Target } from 'te.js';
+
+const users = new Target('/users');
+
+users.register('/', (ammo) => {
+  if (ammo.GET) {
+    ammo.fire([{ id: 1, name: 'John' }]);
+  } else if (ammo.POST) {
+    const { name, email } = ammo.payload;
+    ammo.fire(201, { id: 2, name, email });
+  } else {
+    ammo.notAllowed();
+  }
+});
+
+users.register('/:id', (ammo) => {
+  const { id } = ammo.payload;
+  ammo.fire({ id, name: 'John Doe' });
+});
+```
+
+### Run
+
+```bash
+node index.js
+# Server running at http://localhost:3000
+```
+
+## Core Concepts
+
+| Tejas Term  | Purpose                  | Express Equivalent |
+| ----------- | ------------------------ | ------------------ |
+| `Tejas`     | Application instance     | `express()`        |
+| `Target`    | Route group/router       | `Router()`         |
+| `Ammo`      | Request/response context | `req` + `res`      |
+| `fire()`    | Send response            | `res.send()`       |
+| `midair()`  | Register middleware      | `use()`            |
+| `takeoff()` | Start server             | `listen()`         |
+
+## CLI
+
+```bash
+tejas fly [file]             # Start the server
+tejas generate:docs [--ci]   # Generate OpenAPI docs (interactive or CI mode)
+tejas docs:on-push           # Auto-generate docs when pushing to production branch
+```
+
+## API Documentation
+
+Generate and serve interactive API docs:
+
+```bash
+npx tejas generate:docs
+```
+
+```javascript
+app.serveDocs({ specPath: './openapi.json' });
+app.takeoff();
+// Visit http://localhost:1403/docs
+```
+
+## Documentation
+
+For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-documentation.vercel.app](https://tejas-documentation.vercel.app).
+
+- [Getting Started](./docs/getting-started.md) — Installation and quick start
+- [Configuration](./docs/configuration.md) — All configuration options
+- [Routing](./docs/routing.md) — Target-based routing system
+- [Ammo](./docs/ammo.md) — Request/response handling
+- [Middleware](./docs/middleware.md) — Global, target, and route middleware
+- [Error Handling](./docs/error-handling.md) — Zero-config error handling
+- [Database](./docs/database.md) — Redis and MongoDB integration
+- [Rate Limiting](./docs/rate-limiting.md) — API protection
+- [File Uploads](./docs/file-uploads.md) — File handling
+- [CLI Reference](./docs/cli.md) — Command-line interface
+- [Auto-Documentation](./docs/auto-docs.md) — OpenAPI generation
+- [API Reference](./docs/api-reference.md) — Complete API docs
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+ISC © [Hirak Chhatbar](https://github.com/hirakchhatbar)

package/auto-docs/analysis/handler-analyzer.js

@@ -0,0 +1,58 @@
+/**
+ * Handler analyzer for auto-documentation.
+ * Detects HTTP methods and extracts basic info from handler source via handler.toString().
+ * Used when endpoint metadata does not declare `methods`; otherwise explicit metadata wins.
+ */
+
+const ALL_METHODS = [
+  'GET',
+  'POST',
+  'PUT',
+  'DELETE',
+  'PATCH',
+  'HEAD',
+  'OPTIONS',
+];
+
+/**
+ * Detects which HTTP methods the handler checks (e.g. ammo.GET, ammo.POST).
+ * Matches property access patterns like `.GET`, `ammo.GET`, avoiding false positives
+ * in strings or unrelated identifiers.
+ *
+ * When no method checks are found, the endpoint is treated as method-agnostic
+ * and accepts ALL methods (te.js default behavior).
+ *
+ * @param {Function} handler - The endpoint handler function
+ * @returns {string[]} Detected method names, or ALL_METHODS if none detected
+ */
+function detectMethods(handler) {
+  if (typeof handler !== 'function') return [...ALL_METHODS];
+
+  const src = handler.toString();
+  const detected = [];
+
+  for (const m of ALL_METHODS) {
+    // Match property access patterns like .GET, ammo.GET, avoiding
+    // false positives in strings or unrelated identifiers
+    const pattern = new RegExp(`\\.${m}\\b`);
+    if (pattern.test(src)) detected.push(m);
+  }
+
+  return detected.length > 0 ? detected : [...ALL_METHODS];
+}
+
+/**
+ * Analyzes a handler and returns basic info for documentation (e.g. OpenAPI).
+ * Explicit metadata from register() should override these results when present.
+ *
+ * @param {Function} handler - The endpoint handler function
+ * @returns {{ methods: string[] }} Analyzed info (methods; more fields can be added later)
+ */
+function analyzeHandler(handler) {
+  return {
+    methods: detectMethods(handler),
+  };
+}
+
+export { ALL_METHODS, detectMethods, analyzeHandler };
+export default analyzeHandler;

package/auto-docs/analysis/source-resolver.js

@@ -0,0 +1,101 @@
+/**
+ * Resolves downstream dependency sources for level-2 documentation (handler + deps context).
+ * Reads a target file, extracts relative imports, and returns their source code.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DEPENDENCY_CONTEXT_MAX_CHARS } from '../constants.js';
+
+/** Match ES module imports: import x from './...' or import { x } from '../...' or import '...' */
+const IMPORT_REGEX = /import\s+(?:(?:\{[^}]*\}|\w+)(?:\s*,\s*(?:\{[^}]*\}|\w+))*\s+from\s+)?['"]([^'"]+)['"]/g;
+
+/**
+ * Extract import specifiers that are relative paths (./ or ../).
+ * @param {string} source - File source code
+ * @returns {string[]} Relative paths (e.g. ['../services/user.service.js'])
+ */
+function extractRelativeImports(source) {
+  const out = [];
+  let match;
+  IMPORT_REGEX.lastIndex = 0;
+  while ((match = IMPORT_REGEX.exec(source)) !== null) {
+    const spec = match[1];
+    if (spec.startsWith('./') || spec.startsWith('../')) {
+      out.push(spec);
+    }
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Resolve target file path from groupId and DIR_TARGETS.
+ * @param {string} groupId - e.g. 'users' or 'subdir/users'
+ * @param {string} dirTargets - e.g. 'targets'
+ * @returns {string} Absolute path to the target file
+ */
+function resolveTargetFilePath(groupId, dirTargets = 'targets') {
+  const baseDir = path.join(process.cwd(), dirTargets);
+  const relative = groupId.replace(/\//g, path.sep) + '.target.js';
+  return path.join(baseDir, relative);
+}
+
+/**
+ * Read a target file and all its relative-import dependencies (one level deep).
+ * @param {string} groupId - Source group id (e.g. 'users')
+ * @param {string} [dirTargets] - DIR_TARGETS (default from process.env or 'targets')
+ * @returns {Promise<Map<string, string>>} Map of absolute file path -> source code
+ */
+export async function resolveDependencySources(groupId, dirTargets = process.env.DIR_TARGETS || 'targets') {
+  const targetPath = resolveTargetFilePath(groupId, dirTargets);
+  const result = new Map();
+
+  let targetSource;
+  try {
+    targetSource = await readFile(targetPath, 'utf8');
+  } catch {
+    return result;
+  }
+
+  result.set(targetPath, targetSource);
+  const targetDir = path.dirname(targetPath);
+  const relativeImports = extractRelativeImports(targetSource);
+
+  for (const rel of relativeImports) {
+    const resolvedPath = path.resolve(targetDir, rel);
+    try {
+      const code = await readFile(resolvedPath, 'utf8');
+      result.set(resolvedPath, code);
+    } catch {
+      // Skip missing or unreadable files
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format resolved dependency sources as a single string for LLM context.
+ * @param {Map<string, string>} sources - Map of file path -> source
+ * @param {string} [targetPath] - Path to the target file (excluded from "dependencies" label)
+ * @param {number} [maxChars] - Max total characters to include (default: DEPENDENCY_CONTEXT_MAX_CHARS)
+ * @returns {string}
+ */
+export function formatDependencyContext(sources, targetPath, maxChars = DEPENDENCY_CONTEXT_MAX_CHARS) {
+  if (!sources || sources.size === 0) return '';
+  const lines = [];
+  let total = 0;
+  for (const [filePath, code] of sources) {
+    const label = filePath === targetPath ? 'Target' : path.relative(process.cwd(), filePath);
+    const block = `\n// --- ${label} ---\n${code}`;
+    if (total + block.length > maxChars) {
+      lines.push(block.slice(0, maxChars - total) + '\n// ... (truncated)');
+      break;
+    }
+    lines.push(block);
+    total += block.length;
+  }
+  return lines.join('\n');
+}
+
+export { extractRelativeImports, resolveTargetFilePath };

package/auto-docs/constants.js

@@ -0,0 +1,37 @@
+/**
+ * Shared constants for auto-documentation.
+ * Centralizes OpenAPI version, method keys, and token/character limits.
+ */
+
+/** OpenAPI 3.0 version string */
+export const OPENAPI_VERSION = '3.0.3';
+
+/** Lowercase HTTP method names (for method-keyed LLM response detection and OpenAPI operation keys). */
+export const METHOD_KEYS = new Set(['get', 'put', 'post', 'delete', 'patch', 'head', 'options']);
+
+/** When an endpoint accepts all HTTP methods, document it once under this key. */
+export const METHOD_AGNOSTIC_OPERATION_KEY = 'get';
+
+/** Max handler source length by level (chars; tokens roughly scale). Level 1 = moderate, 2 = high. */
+export const HANDLER_SOURCE_MAX_LENGTH_BY_LEVEL = { 1: 2800, 2: 6000 };
+
+/** Default max chars for dependency context in formatDependencyContext and level-2 prompts. */
+export const DEPENDENCY_CONTEXT_MAX_CHARS = 6000;
+
+/** Max handler source chars in single-endpoint enhance prompts (no deps). */
+export const PROMPT_HANDLER_SLICE = 3000;
+
+/** Max handler source chars in single-endpoint enhance prompts (with deps). */
+export const PROMPT_HANDLER_SLICE_WITH_DEPS = 4000;
+
+/** Max dependency source chars included in enhance/summarize prompts. */
+export const PROMPT_DEPENDENCY_SLICE = 5000;
+
+/** Max total code chars in group-summary prompt when no dependency context. */
+export const PROMPT_GROUP_CODE_LIMIT = 4000;
+
+/** Max total code chars in group-summary prompt when dependency context is present. */
+export const PROMPT_GROUP_CODE_LIMIT_WITH_DEPS = 6000;
+
+/** Max handler source chars per endpoint in group-summary code snippets. */
+export const PROMPT_GROUP_SNIPPET_CHARS = 800;