te.js 2.1.6 → 2.2.1

package/README.md

@@ -41,7 +41,6 @@ api.register('/hello/:name', (ammo) => {
 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
@@ -50,14 +49,12 @@ app.takeoff();
 - **Zero-Config Error Handling** — No try-catch needed! Tejas catches all errors automatically. Opt in to have an LLM determine error code and message when you don't specify them (see [Error Handling](./docs/error-handling.md))
 - **Built-in Rate Limiting** — Three algorithms (Token Bucket, Sliding Window, Fixed Window) with memory or Redis storage
 - **Method Safety & CORS** — Opt-in method restriction per route (`register(path, { methods }, handler)` or `ammo.only('GET')`), global allowed-methods filter, and `app.withCORS()` for cross-origin requests
-- **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.
@@ -79,8 +76,7 @@ The [Tejas MCP server](https://www.npmjs.com/package/tejas-mcp) gives your IDE's
 
 **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.
-
+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
 
@@ -132,7 +128,6 @@ node index.js
 # Server running at http://localhost:3000
 ```
 
-
 ## Core Concepts
 
 | Tejas Term  | Purpose                  | Express Equivalent |
@@ -144,7 +139,6 @@ node index.js
 | `midair()`  | Register middleware      | `use()`            |
 | `takeoff()` | Start server             | `listen()`         |
 
-
 ## CLI
 
 ```bash
@@ -153,7 +147,6 @@ 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:
@@ -168,7 +161,6 @@ 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).
@@ -179,19 +171,16 @@ For comprehensive documentation, see the [docs folder](./docs) or visit [tejas-d
 - [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.test.js

@@ -0,0 +1,106 @@
+/**
+ * Unit tests for auto-docs handler-analyzer (detectMethods, analyzeHandler).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  detectMethods,
+  analyzeHandler,
+  ALL_METHODS,
+} from './handler-analyzer.js';
+
+describe('handler-analyzer', () => {
+  describe('detectMethods', () => {
+    it('returns all methods when handler is not a function', () => {
+      expect(detectMethods(null)).toEqual(ALL_METHODS);
+      expect(detectMethods(undefined)).toEqual(ALL_METHODS);
+    });
+
+    it('detects GET when handler uses ammo.GET', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200, {});
+      };
+      expect(detectMethods(handler)).toContain('GET');
+    });
+
+    it('detects POST and GET when handler checks both', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200, {});
+        if (ammo.POST) ammo.fire(201, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('POST');
+    });
+
+    it('returns all methods when no method checks found (method-agnostic)', () => {
+      const handler = () => {};
+      expect(detectMethods(handler)).toEqual(ALL_METHODS);
+    });
+
+    it('detects GET and HEAD when handler uses ammo.only("GET")', () => {
+      const handler = (ammo) => {
+        ammo.only('GET');
+        ammo.fire({ status: 'ok' });
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+      expect(detected).toHaveLength(2);
+    });
+
+    it('detects POST and PUT when handler uses ammo.only("POST", "PUT")', () => {
+      const handler = (ammo) => {
+        ammo.only('POST', 'PUT');
+        ammo.fire(200, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('POST');
+      expect(detected).toContain('PUT');
+      expect(detected).toHaveLength(2);
+    });
+
+    it('detects from ammo.only with double-quoted methods', () => {
+      const handler = (ammo) => {
+        ammo.only('GET');
+        ammo.fire(200);
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+    });
+
+    it('detects from .only with no space after comma', () => {
+      const handler = (ammo) => {
+        ammo.only('GET', 'POST');
+        ammo.fire(200);
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+      expect(detected).toContain('POST');
+      expect(detected).toHaveLength(3);
+    });
+
+    it('prefers ammo.only over property access when both present', () => {
+      const handler = (ammo) => {
+        ammo.only('POST');
+        if (ammo.GET) ammo.fire(200);
+        ammo.fire(201, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toEqual(['POST']);
+    });
+  });
+
+  describe('analyzeHandler', () => {
+    it('returns object with methods array', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200);
+      };
+      const result = analyzeHandler(handler);
+      expect(result).toHaveProperty('methods');
+      expect(Array.isArray(result.methods)).toBe(true);
+      expect(result.methods).toContain('GET');
+    });
+  });
+});

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

@@ -0,0 +1,58 @@
+/**
+ * Unit tests for auto-docs source-resolver (extractRelativeImports, resolveTargetFilePath, formatDependencyContext).
+ */
+import { describe, it, expect } from 'vitest';
+import path from 'node:path';
+import {
+  extractRelativeImports,
+  resolveTargetFilePath,
+  formatDependencyContext,
+} from './source-resolver.js';
+
+describe('source-resolver', () => {
+  describe('extractRelativeImports', () => {
+    it('extracts relative import paths', () => {
+      const source = `import x from './foo.js';\nimport { y } from '../bar.js';`;
+      const imports = extractRelativeImports(source);
+      expect(imports).toContain('./foo.js');
+      expect(imports).toContain('../bar.js');
+    });
+    it('ignores absolute or node imports', () => {
+      const source = `import path from 'path';\nimport x from './local.js';`;
+      const imports = extractRelativeImports(source);
+      expect(imports).toEqual(['./local.js']);
+    });
+    it('returns unique paths', () => {
+      const source = `import a from './foo.js';\nimport b from './foo.js';`;
+      expect(extractRelativeImports(source)).toHaveLength(1);
+    });
+  });
+
+  describe('resolveTargetFilePath', () => {
+    it('joins dirTargets with groupId and .target.js', () => {
+      const resolved = resolveTargetFilePath('users', 'targets');
+      expect(resolved).toMatch(/targets[\\/]users\.target\.js$/);
+    });
+    it('converts groupId slashes to path sep', () => {
+      const resolved = resolveTargetFilePath('subdir/users', 'targets');
+      expect(resolved).toMatch(/subdir[\\/]users\.target\.js$/);
+    });
+  });
+
+  describe('formatDependencyContext', () => {
+    it('returns empty string for empty sources', () => {
+      expect(formatDependencyContext(new Map(), null)).toBe('');
+    });
+    it('formats map of path -> source with labels', () => {
+      const sources = new Map([
+        ['/cwd/targets/users.target.js', 'const x = 1;'],
+        ['/cwd/services/user.js', 'const y = 2;'],
+      ]);
+      const targetPath = '/cwd/targets/users.target.js';
+      const out = formatDependencyContext(sources, targetPath, 1000);
+      expect(out).toContain('Target');
+      expect(out).toContain('const x = 1;');
+      expect(out).toContain('const y = 2;');
+    });
+  });
+});

package/auto-docs/constants.js

@@ -7,13 +7,24 @@
 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']);
+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 };
+export const HANDLER_SOURCE_MAX_LENGTH_BY_LEVEL = Object.freeze({
+  1: 2800,
+  2: 6000,
+});
 
 /** Default max chars for dependency context in formatDependencyContext and level-2 prompts. */
 export const DEPENDENCY_CONTEXT_MAX_CHARS = 6000;

package/auto-docs/openapi/generator.js

@@ -39,7 +39,7 @@ async function generateOpenAPISpec(registry, options = {}) {
     logger = null,
   } = options;
   const targets = registry?.targets ?? [];
-  const paths = {};
+  const paths = Object.create(null);
   const groupEndpoints = new Map();
   const dependencyContextByGroup = new Map();
 
@@ -71,10 +71,12 @@ async function generateOpenAPISpec(registry, options = {}) {
   );
   applyTagDisplayNames(paths, tagDescriptions);
 
-  const tags = Array.from(tagDescriptions.entries()).map(([, { name, description }]) => ({
-    name,
-    ...(description && { description }),
-  }));
+  const tags = Array.from(tagDescriptions.entries()).map(
+    ([, { name, description }]) => ({
+      name,
+      ...(description && { description }),
+    }),
+  );
 
   const spec = {
     openapi: OPENAPI_VERSION,

package/auto-docs/openapi/generator.test.js

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for auto-docs openapi/generator pure functions.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  toOpenAPIPath,
+  getPathParameters,
+  getQueryParameters,
+  buildSchemaFromMetadata,
+  buildResponses,
+  buildOperation,
+  mergeMetadata,
+} from './generator.js';
+
+describe('openapi-generator', () => {
+  describe('toOpenAPIPath', () => {
+    it('converts :param to {param}', () => {
+      expect(toOpenAPIPath('/users/:id')).toBe('/users/{id}');
+    });
+    it('converts multiple params', () => {
+      expect(toOpenAPIPath('/users/:userId/posts/:postId')).toBe(
+        '/users/{userId}/posts/{postId}',
+      );
+    });
+    it('returns / for empty or non-string', () => {
+      expect(toOpenAPIPath('')).toBe('/');
+      expect(toOpenAPIPath(null)).toBe('/');
+    });
+  });
+
+  describe('getPathParameters', () => {
+    it('extracts path params from te.js path', () => {
+      const params = getPathParameters('/users/:id');
+      expect(params).toHaveLength(1);
+      expect(params[0]).toMatchObject({
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      });
+    });
+    it('returns empty array for path without params', () => {
+      expect(getPathParameters('/users')).toEqual([]);
+    });
+  });
+
+  describe('getQueryParameters', () => {
+    it('builds query params from metadata', () => {
+      const queryMeta = {
+        limit: { type: 'integer', required: false },
+        q: { type: 'string', required: true },
+      };
+      const params = getQueryParameters(queryMeta);
+      expect(params).toHaveLength(2);
+      expect(params.find((p) => p.name === 'limit')).toMatchObject({
+        in: 'query',
+        required: false,
+      });
+      expect(params.find((p) => p.name === 'q')).toMatchObject({
+        in: 'query',
+        required: true,
+      });
+    });
+    it('returns empty array for invalid meta', () => {
+      expect(getQueryParameters(null)).toEqual([]);
+    });
+  });
+
+  describe('buildSchemaFromMetadata', () => {
+    it('builds OpenAPI schema from field meta', () => {
+      const meta = {
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email', required: true },
+      };
+      const schema = buildSchemaFromMetadata(meta);
+      expect(schema.type).toBe('object');
+      expect(schema.properties.name.type).toBe('string');
+      expect(schema.properties.email.format).toBe('email');
+      expect(schema.required).toContain('email');
+    });
+  });
+
+  describe('buildResponses', () => {
+    it('returns 200 Success when responseMeta empty', () => {
+      const r = buildResponses(null);
+      expect(r['200']).toEqual({ description: 'Success' });
+    });
+    it('builds responses from metadata', () => {
+      const meta = {
+        200: { description: 'OK' },
+        201: { description: 'Created' },
+      };
+      const r = buildResponses(meta);
+      expect(r['200'].description).toBe('OK');
+      expect(r['201'].description).toBe('Created');
+    });
+  });
+
+  describe('buildOperation', () => {
+    it('builds operation with summary and responses', () => {
+      const meta = {
+        summary: 'Get user',
+        response: { 200: { description: 'OK' } },
+      };
+      const pathParams = [];
+      const op = buildOperation('get', meta, pathParams);
+      expect(op.summary).toBe('Get user');
+      expect(op.responses['200'].description).toBe('OK');
+    });
+  });
+
+  describe('mergeMetadata', () => {
+    it('prefers explicit when preferEnhanced false', () => {
+      const explicit = { summary: 'A', description: 'B' };
+      const enhanced = { summary: 'C', description: 'D' };
+      const merged = mergeMetadata(explicit, enhanced, {
+        preferEnhanced: false,
+      });
+      expect(merged.summary).toBe('A');
+      expect(merged.description).toBe('B');
+    });
+    it('prefers enhanced when preferEnhanced true', () => {
+      const explicit = { summary: 'A' };
+      const enhanced = { summary: 'C', description: 'D' };
+      const merged = mergeMetadata(explicit, enhanced, {
+        preferEnhanced: true,
+      });
+      expect(merged.summary).toBe('C');
+      expect(merged.description).toBe('D');
+    });
+  });
+});

package/auto-docs/openapi/spec-builders.js

@@ -16,7 +16,12 @@ export function isMethodKeyed(obj) {
   for (const key of Object.keys(obj)) {
     if (METHOD_KEYS.has(key.toLowerCase())) {
       const val = obj[key];
-      if (val && typeof val === 'object' && (val.summary != null || val.response != null)) return true;
+      if (
+        val &&
+        typeof val === 'object' &&
+        (val.summary != null || val.response != null)
+      )
+        return true;
     }
   }
   return false;
@@ -82,7 +87,7 @@ export function getQueryParameters(queryMeta) {
  */
 export function buildSchemaFromMetadata(meta) {
   if (!meta || typeof meta !== 'object') return {};
-  const properties = {};
+  const properties = Object.create(null);
   const required = [];
   for (const [key, value] of Object.entries(meta)) {
     if (value && typeof value === 'object' && value.type) {
@@ -91,7 +96,8 @@ export function buildSchemaFromMetadata(meta) {
         ...(value.description && { description: value.description }),
         ...(value.format && { format: value.format }),
       };
-      if (value.required === true || value.required === 'true') required.push(key);
+      if (value.required === true || value.required === 'true')
+        required.push(key);
     }
   }
   if (Object.keys(properties).length === 0) return {};
@@ -108,7 +114,8 @@ export function buildSchemaFromMetadata(meta) {
  * @returns {object|undefined} OpenAPI requestBody or undefined
  */
 export function buildRequestBody(requestMeta) {
-  if (!requestMeta?.body || typeof requestMeta.body !== 'object') return undefined;
+  if (!requestMeta?.body || typeof requestMeta.body !== 'object')
+    return undefined;
   const schema = buildSchemaFromMetadata(requestMeta.body);
   if (!schema || Object.keys(schema).length === 0) return undefined;
   return {
@@ -127,7 +134,7 @@ export function buildRequestBody(requestMeta) {
  * @returns {object} OpenAPI responses
  */
 export function buildResponses(responseMeta) {
-  const responses = {};
+  const responses = Object.create(null);
   if (!responseMeta || typeof responseMeta !== 'object') {
     responses['200'] = { description: 'Success' };
     return responses;
@@ -139,9 +146,10 @@ export function buildResponses(responseMeta) {
       ...(spec.schema && {
         content: {
           'application/json': {
-            schema: typeof spec.schema === 'object' && spec.schema.type
-              ? spec.schema
-              : { type: 'object' },
+            schema:
+              typeof spec.schema === 'object' && spec.schema.type
+                ? spec.schema
+                : { type: 'object' },
           },
         },
       }),
@@ -159,7 +167,8 @@ export function buildResponses(responseMeta) {
  * @returns {boolean}
  */
 export function isMethodAgnostic(methods) {
-  if (!Array.isArray(methods) || methods.length !== ALL_METHODS.length) return false;
+  if (!Array.isArray(methods) || methods.length !== ALL_METHODS.length)
+    return false;
   const set = new Set(methods.map((m) => m.toUpperCase()));
   return ALL_METHODS.every((m) => set.has(m));
 }
@@ -190,7 +199,10 @@ export function buildOperation(method, meta, pathParams, options = {}) {
   };
   const methodUpper = method.toUpperCase();
   const body = buildRequestBody(meta.request);
-  if (body && (methodAgnostic || (methodUpper !== 'GET' && methodUpper !== 'HEAD'))) {
+  if (
+    body &&
+    (methodAgnostic || (methodUpper !== 'GET' && methodUpper !== 'HEAD'))
+  ) {
     op.requestBody = body;
   }
   op.responses = buildResponses(meta.response);
@@ -207,17 +219,17 @@ export function buildOperation(method, meta, pathParams, options = {}) {
 export function mergeMetadata(explicit, enhanced, options = {}) {
   const preferEnhanced = options.preferEnhanced === true;
   const summary = preferEnhanced
-    ? (enhanced?.summary ?? explicit?.summary ?? '')
-    : (explicit?.summary ?? enhanced?.summary ?? '');
+    ? enhanced?.summary ?? explicit?.summary ?? ''
+    : explicit?.summary ?? enhanced?.summary ?? '';
   const description = preferEnhanced
-    ? (enhanced?.description ?? explicit?.description ?? '')
-    : (explicit?.description ?? enhanced?.description ?? '');
+    ? enhanced?.description ?? explicit?.description ?? ''
+    : explicit?.description ?? enhanced?.description ?? '';
   const request = preferEnhanced
-    ? (enhanced?.request ?? explicit?.request)
-    : (explicit?.request ?? enhanced?.request);
+    ? enhanced?.request ?? explicit?.request
+    : explicit?.request ?? enhanced?.request;
   const response = preferEnhanced
-    ? (enhanced?.response ?? explicit?.response)
-    : (explicit?.response ?? enhanced?.response);
+    ? enhanced?.response ?? explicit?.response
+    : explicit?.response ?? enhanced?.response;
   return {
     summary: summary || 'Endpoint',
     description: description || undefined,
@@ -234,7 +246,15 @@ export function mergeMetadata(explicit, enhanced, options = {}) {
  * @returns {object}
  */
 export function mergeMethodAgnosticMeta(metaByMethod, methods, fallbackMeta) {
-  const preferredOrder = ['post', 'put', 'patch', 'get', 'delete', 'head', 'options'];
+  const preferredOrder = [
+    'post',
+    'put',
+    'patch',
+    'get',
+    'delete',
+    'head',
+    'options',
+  ];
   for (const k of preferredOrder) {
     const m = metaByMethod.get(k);
     if (m && (m.summary || m.description)) return m;