te.js 1.3.1 → 2.0.1

package/docs/file-uploads.md

@@ -0,0 +1,334 @@
+# File Uploads
+
+Tejas provides a built-in `TejFileUploader` class for handling file uploads with ease.
+
+## Quick Start
+
+```javascript
+import { Target, TejFileUploader } from 'te.js';
+
+const upload = new TejFileUploader({
+  destination: 'uploads/',
+  maxFileSize: 5 * 1024 * 1024 // 5MB
+});
+
+const target = new Target('/files');
+
+target.register('/upload', upload.file('avatar'), (ammo) => {
+  ammo.fire({ file: ammo.payload.avatar });
+});
+```
+
+## Configuration
+
+```javascript
+const upload = new TejFileUploader({
+  destination: 'public/uploads', // Where to save files
+  name: 'custom-name',           // Optional: custom filename
+  maxFileSize: 10 * 1024 * 1024  // Max file size in bytes (10MB)
+});
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `destination` | string | Directory to save uploaded files |
+| `name` | string | Optional custom filename |
+| `maxFileSize` | number | Maximum file size in bytes |
+
+## Single File Upload
+
+Use `upload.file()` for single file uploads:
+
+```javascript
+// Expects a file field named 'avatar'
+target.register('/avatar', upload.file('avatar'), (ammo) => {
+  const file = ammo.payload.avatar;
+  
+  ammo.fire({
+    filename: file.filename,
+    path: file.path.relative,
+    mimetype: file.mimetype,
+    size: file.size
+  });
+});
+```
+
+### File Object Structure
+
+When a file is uploaded, `ammo.payload[fieldName]` contains:
+
+```javascript
+{
+  filename: 'photo.jpg',          // Original filename
+  extension: 'jpg',               // File extension
+  path: {
+    absolute: '/var/www/uploads/photo.jpg',  // Absolute path on disk
+    relative: '\\uploads\\photo.jpg'         // Relative to cwd
+  },
+  mimetype: 'image/jpeg',         // MIME type
+  size: {                         // From the filesize library
+    value: 245,                   // Numeric value
+    symbol: 'KB'                  // Unit (B, KB, MB, etc.)
+  }
+}
+```
+
+The `size` object is produced by the [filesize](https://www.npmjs.com/package/filesize) library. Use `${size.value} ${size.symbol}` for display (e.g. "245 KB").
+
+## Multiple File Upload
+
+Use `upload.files()` for multiple files:
+
+```javascript
+// Expects files in 'photos' and 'documents' fields
+target.register('/documents', upload.files('photos', 'documents'), (ammo) => {
+  const { photos, documents } = ammo.payload;
+  
+  ammo.fire({
+    photos: photos || [],        // Array of file objects
+    documents: documents || []   // Array of file objects
+  });
+});
+```
+
+### Multiple Files Response
+
+Each field contains an array of file objects:
+
+```javascript
+{
+  photos: [
+    { filename: 'photo1.jpg', path: {...}, mimetype: 'image/jpeg', size: {...} },
+    { filename: 'photo2.jpg', path: {...}, mimetype: 'image/jpeg', size: {...} }
+  ],
+  documents: [
+    { filename: 'doc.pdf', path: {...}, mimetype: 'application/pdf', size: {...} }
+  ]
+}
+```
+
+## Mixed Fields (Files + Data)
+
+File uploads can include regular form fields:
+
+```javascript
+target.register('/profile', upload.file('avatar'), (ammo) => {
+  const { avatar, name, bio } = ammo.payload;
+  
+  ammo.fire({
+    name,           // Regular form field
+    bio,            // Regular form field
+    avatar: avatar  // File object
+  });
+});
+```
+
+## File Size Limits
+
+When a file exceeds `maxFileSize`, a `413 Payload Too Large` error is thrown automatically. The error message includes the human-readable limit (e.g. "File size exceeds 2 MB"):
+
+```javascript
+const upload = new TejFileUploader({
+  destination: 'uploads/',
+  maxFileSize: 2 * 1024 * 1024 // 2MB limit
+});
+
+target.register('/upload', upload.file('file'), (ammo) => {
+  // If file > 2MB, this handler never runs
+  // Client receives: 413 "File size exceeds 2 MB"
+  ammo.fire({ success: true });
+});
+```
+
+Note that the overall request body is also subject to the global `body.max_size` limit (default 10 MB). See [Configuration](./configuration.md).
+
+## Client-Side Examples
+
+### HTML Form
+
+```html
+<form action="/files/upload" method="POST" enctype="multipart/form-data">
+  <input type="file" name="avatar" />
+  <input type="text" name="username" />
+  <button type="submit">Upload</button>
+</form>
+```
+
+### JavaScript (Fetch)
+
+```javascript
+const formData = new FormData();
+formData.append('avatar', fileInput.files[0]);
+formData.append('username', 'john');
+
+const response = await fetch('/files/upload', {
+  method: 'POST',
+  body: formData
+});
+```
+
+### JavaScript (Multiple Files)
+
+```javascript
+const formData = new FormData();
+
+// Add multiple files to same field
+for (const file of fileInput.files) {
+  formData.append('photos', file);
+}
+
+const response = await fetch('/files/documents', {
+  method: 'POST',
+  body: formData
+});
+```
+
+## Complete Example
+
+```javascript
+import { Target, TejFileUploader, TejError } from 'te.js';
+import fs from 'fs';
+import path from 'path';
+
+const target = new Target('/api/files');
+
+// Configure uploader
+const imageUpload = new TejFileUploader({
+  destination: 'public/images',
+  maxFileSize: 5 * 1024 * 1024 // 5MB
+});
+
+const documentUpload = new TejFileUploader({
+  destination: 'private/documents',
+  maxFileSize: 20 * 1024 * 1024 // 20MB
+});
+
+// Upload profile image
+target.register('/profile-image', imageUpload.file('image'), (ammo) => {
+  if (!ammo.POST) return ammo.notAllowed();
+  
+  const { image } = ammo.payload;
+  
+  if (!image) {
+    throw new TejError(400, 'No image provided');
+  }
+  
+  // Validate image type
+  if (!image.mimetype.startsWith('image/')) {
+    // Delete uploaded file
+    fs.unlinkSync(image.path.absolute);
+    throw new TejError(400, 'File must be an image');
+  }
+  
+  ammo.fire({
+    message: 'Profile image uploaded',
+    url: `/images/${image.filename}`
+  });
+});
+
+// Upload multiple documents
+target.register('/documents', documentUpload.files('files'), (ammo) => {
+  if (!ammo.POST) return ammo.notAllowed();
+  
+  const { files } = ammo.payload;
+  
+  if (!files || files.length === 0) {
+    throw new TejError(400, 'No files provided');
+  }
+  
+  ammo.fire({
+    message: `${files.length} files uploaded`,
+    files: files.map(f => ({
+      name: f.filename,
+      size: `${f.size.value} ${f.size.symbol}`
+    }))
+  });
+});
+
+// Delete a file
+target.register('/delete/:filename', (ammo) => {
+  if (!ammo.DELETE) return ammo.notAllowed();
+  
+  const { filename } = ammo.payload;
+  const filepath = path.join('public/images', filename);
+  
+  if (!fs.existsSync(filepath)) {
+    throw new TejError(404, 'File not found');
+  }
+  
+  fs.unlinkSync(filepath);
+  ammo.fire({ message: 'File deleted' });
+});
+```
+
+## Validation Middleware
+
+Create reusable validation middleware:
+
+```javascript
+// middleware/validate-image.js
+import { TejError } from 'te.js';
+import fs from 'fs';
+
+const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+
+export const validateImage = (fieldName) => (ammo, next) => {
+  const file = ammo.payload[fieldName];
+  
+  if (!file) {
+    throw new TejError(400, `${fieldName} is required`);
+  }
+  
+  if (!allowedTypes.includes(file.mimetype)) {
+    fs.unlinkSync(file.path.absolute);
+    throw new TejError(400, 'Only JPEG, PNG, GIF, and WebP images are allowed');
+  }
+  
+  next();
+};
+
+// Usage
+target.register('/avatar',
+  upload.file('avatar'),
+  validateImage('avatar'),
+  (ammo) => {
+    ammo.fire({ success: true });
+  }
+);
+```
+
+## Serving Uploaded Files
+
+Tejas doesn't include a static file server, but you can serve files manually:
+
+```javascript
+import fs from 'fs';
+import path from 'path';
+import mime from 'mime';
+
+target.register('/images/:filename', (ammo) => {
+  const { filename } = ammo.payload;
+  const filepath = path.join('public/images', filename);
+  
+  if (!fs.existsSync(filepath)) {
+    return ammo.notFound();
+  }
+  
+  const file = fs.readFileSync(filepath);
+  const contentType = mime.getType(filepath) || 'application/octet-stream';
+  
+  ammo.fire(200, file, contentType);
+});
+```
+
+## Best Practices
+
+1. **Validate file types** — Don't trust client-reported MIME types
+2. **Set size limits** — Prevent disk exhaustion attacks
+3. **Use unique filenames** — Avoid overwrites with UUID or timestamps
+4. **Store outside web root** — For sensitive files, store in private directories
+5. **Clean up on errors** — Delete uploaded files if validation fails
+6. **Scan for malware** — For production systems, integrate virus scanning
+

package/docs/getting-started.md

@@ -0,0 +1,215 @@
+# Getting Started with Tejas
+
+Tejas is a lightweight Node.js framework for building powerful backend services. It features an intuitive API with aviation-inspired naming conventions.
+
+## Why Tejas?
+
+- **AI-Native** — MCP server gives your AI assistant full framework knowledge for correct code generation
+- **Zero-Config Error Handling** — No try-catch needed! Tejas catches all errors automatically
+- **Clean, Readable Code** — Aviation-inspired naming makes code self-documenting
+- **Express Compatible** — Use your existing Express middleware
+- **Built-in Features** — Rate limiting, file uploads, database connections out of the box
+
+## AI-Assisted Setup (MCP) — Recommended
+
+The fastest way to start building with Tejas is through your AI assistant. The **Tejas MCP server** (`tejas-mcp`) gives AI tools full access to framework documentation, validated code examples, and purpose-built tools that scaffold projects and generate correct te.js code.
+
+### Setup
+
+**Cursor** — create or edit `.cursor/mcp.json` in your workspace:
+
+```json
+{
+  "mcpServers": {
+    "tejas": {
+      "command": "npx",
+      "args": ["-y", "tejas-mcp"]
+    }
+  }
+}
+```
+
+**Other MCP-compatible IDEs** — run `npx tejas-mcp` as the stdio server command. No API keys required.
+
+### What you can do
+
+Once connected, prompt your assistant naturally:
+
+- *"Scaffold a new te.js project called my-api on port 5000"*
+- *"Create a REST API with user CRUD routes using te.js"*
+- *"Add a /health endpoint that returns system uptime"*
+
+The MCP server provides these tools: `scaffold_project`, `generate_target`, `generate_app_entry`, `generate_config`, `get_documentation`, and `search_docs`.
+
+---
+
+## Prerequisites
+
+- Node.js 18.x or higher
+- npm or yarn
+
+## Installation
+
+```bash
+npm install te.js
+```
+
+## Quick Start
+
+### 1. Create Your Application
+
+Create an `index.js` file:
+
+```javascript
+import Tejas from 'te.js';
+
+const app = new Tejas();
+
+app.takeoff();
+```
+
+### 2. Create Your First Route
+
+Create a `targets` directory and add `hello.target.js`:
+
+```javascript
+import { Target } from 'te.js';
+
+const target = new Target('/hello');
+
+target.register('/', (ammo) => {
+  ammo.fire({ message: 'Hello, World!' });
+});
+
+target.register('/greet/:name', (ammo) => {
+  const { name } = ammo.payload;
+  ammo.fire({ message: `Hello, ${name}!` });
+});
+```
+
+### 3. Run Your Application
+
+```bash
+node index.js
+```
+
+Your server is now running on `http://localhost:1403`
+
+## Core Concepts
+
+### Terminology
+
+Tejas uses aviation-inspired naming:
+
+| Term | Express Equivalent | Description |
+|------|-------------------|-------------|
+| `Tejas` | `express()` | Main application instance |
+| `Target` | `Router` | Route grouping |
+| `Ammo` | `req` + `res` | Request/response wrapper |
+| `fire()` | `res.send()` | Send response |
+| `throw()` | Error response | Send error |
+| `midair()` | `use()` | Register middleware |
+| `takeoff()` | `listen()` | Start server |
+
+### Basic Structure
+
+```
+my-app/
+├── index.js              # Application entry point
+├── tejas.config.json     # Optional configuration
+├── .env                  # Environment variables
+├── targets/              # Route definitions (auto-discovered)
+│   ├── user.target.js
+│   ├── auth.target.js
+│   └── api/
+│       └── v1.target.js
+├── services/             # Business logic
+│   └── user.service.js
+└── middleware/            # Custom middleware
+    └── auth.js
+```
+
+## Automatic Error Handling
+
+One of Tejas's most powerful features is that **you don't need to write any error handling code**. The framework catches all errors automatically:
+
+```javascript
+// ✅ No try-catch needed — if anything throws, Tejas handles it
+target.register('/data', async (ammo) => {
+  const data = await riskyDatabaseCall();
+  const processed = await anotherAsyncOperation(data);
+  ammo.fire(processed);
+});
+```
+
+Your application never crashes from unhandled exceptions, and clients always receive proper error responses. Learn more in [Error Handling](./error-handling.md).
+
+## Next Steps
+
+- [Configuration](./configuration.md) — All configuration options and sources
+- [Routing](./routing.md) — Deep dive into the Target-based routing system
+- [Ammo](./ammo.md) — Master request/response handling
+- [Middleware](./middleware.md) — Global, target, and route-level middleware
+- [Database](./database.md) — Connect to MongoDB or Redis
+- [Error Handling](./error-handling.md) — Zero-config error handling
+- [CLI Reference](./cli.md) — `tejas fly` and doc generation commands
+- [Auto-Documentation](./auto-docs.md) — Generate OpenAPI specs from your code
+
+## Example Application
+
+Here's a more complete example:
+
+```javascript
+import Tejas from 'te.js';
+
+const app = new Tejas({
+  port: 3000,
+  log: {
+    http_requests: true,
+    exceptions: true
+  }
+});
+
+// Global middleware
+app.midair((ammo, next) => {
+  console.log(`${ammo.method} ${ammo.path}`);
+  next();
+});
+
+// Rate limiting (in-memory)
+app.withRateLimit({
+  maxRequests: 100,
+  timeWindowSeconds: 60
+});
+
+// Start with optional Redis
+app.takeoff({
+  withRedis: { url: 'redis://localhost:6379' }
+});
+```
+
+```javascript
+// targets/api.target.js
+import { Target } from 'te.js';
+
+const api = new Target('/api');
+
+// GET /api/status
+api.register('/status', (ammo) => {
+  if (ammo.GET) {
+    ammo.fire({ status: 'operational', timestamp: Date.now() });
+  } else {
+    ammo.notAllowed();
+  }
+});
+
+// POST /api/echo
+api.register('/echo', (ammo) => {
+  if (ammo.POST) {
+    ammo.fire(ammo.payload);
+  } else {
+    ammo.notAllowed();
+  }
+});
+```
+