te.js 1.3.0 → 2.0.0

package/te.js

@@ -1,137 +1,363 @@
-import { createServer } from 'node:http';
-
-import { env, setEnv } from 'tej-env';
-import TejLogger from 'tej-logger';
-import database from './database/index.js';
-
-import TargetRegistry from './server/targets/registry.js';
-
-import { loadConfigFile, standardizeObj } from './utils/configuration.js';
-
-import targetHandler from './server/handler.js';
-import { findTargetFiles } from './utils/auto-register.js';
-import { pathToFileURL } from 'node:url';
-import { log } from 'node:console';
-
-const logger = new TejLogger('Tejas');
-const targetRegistry = new TargetRegistry();
-
-class Tejas {
-  /*
-   * Constructor for Tejas
-   * @param {Object} args - Arguments for Tejas
-   * @param {Number} args.port - Port to run Tejas on
-   * @param {Boolean} args.log.http_requests - Whether to log incoming HTTP requests
-   * @param {Boolean} args.log.exceptions - Whether to log exceptions
-   * @param {String} args.db.type - Database type. It can be 'mongodb', 'mysql', 'postgres', 'sqlite'
-   * @param {String} args.db.uri - Connection URI string for the database
-   */
-  constructor(args) {
-    if (Tejas.instance) return Tejas.instance;
-    Tejas.instance = this;
-
-    this.generateConfiguration(args);
-    this.registerTargetsDir();
-  }
-
-  /*
-   * Connect to a database
-   * @param {Object}
-   * @param {String} args.db - Database type. It can be 'mongodb', 'mysql', 'postgres', 'sqlite'
-   * @param {String} args.uri - Connection URI string for the database
-   * @param {Object} args.options - Options for the database connection
-   */
-  connectDatabase(args) {
-    const db = env('DB_TYPE');
-    const uri = env('DB_URI');
-
-    if (!db) return;
-    if (!uri) {
-      logger.error(
-        `Tejas could not connect to ${db} as it couldn't find a connection URI. See our documentation for more information.`,
-        false,
-      );
-      return;
-    }
-
-    const connect = database[db];
-    if (!connect) {
-      logger.error(
-        `Tejas could not connect to ${db} as it is not supported. See our documentation for more information.`,
-        false,
-      );
-      return;
-    }
-
-    connect(uri, {}, (error) => {
-      if (error) {
-        logger.error(
-          `Tejas could not connect to ${db}. Error: ${error}`,
-          false,
-        );
-        return;
-      }
-
-      logger.info(`Tejas connected to ${db} successfully.`);
-    });
-  }
-
-  generateConfiguration(options) {
-    const configVars = standardizeObj(loadConfigFile());
-    const envVars = standardizeObj(process.env);
-    const userVars = standardizeObj(options);
-
-    const config = { ...configVars, ...envVars, ...userVars };
-    for (const key in config) {
-      if (config.hasOwnProperty(key)) {
-        setEnv(key, config[key]);
-      }
-    }
-
-    // Load defaults
-    if (!env('PORT')) setEnv('PORT', 1403);
-  }
-
-  midair() {
-    if (!arguments) return;
-    targetRegistry.addGlobalMiddleware(...arguments);
-  }
-
-  registerTargetsDir() {
-    findTargetFiles()
-      .then((targetFiles) => {
-        if (targetFiles) {
-          for (const file of targetFiles) {
-            import(pathToFileURL(`${file.parentPath}/${file.name}`));
-          }
-        }
-      })
-      .catch((err) => {
-        logger.error(
-          `Tejas could not register target files. Error: ${err}`,
-          false,
-        );
-      });
-  }
-
-  takeoff() {
-    this.engine = createServer(targetHandler);
-    this.engine.listen(env('PORT'), () => {
-      logger.info(`Took off from port ${env('PORT')}`);
-      this.connectDatabase();
-    });
-  }
-}
-
-const listAllEndpoints = (grouped = false) => {
-  return targetRegistry.getAllEndpoints(grouped);
-};
-
-export { default as Target } from './server/target.js';
-export { default as TejFileUploader } from './server/files/uploader.js';
-export { default as TejError } from './server/error.js';
-export { listAllEndpoints };
-export default Tejas;
-
-// TODO Ability to register a target (route) from tejas instance
-// TODO tejas as CLI tool
+import { createServer } from 'node:http';
+import { env, setEnv } from 'tej-env';
+import TejLogger from 'tej-logger';
+import rateLimiter from './rate-limit/index.js';
+
+import targetRegistry from './server/targets/registry.js';
+import dbManager from './database/index.js';
+
+import { loadConfigFile, standardizeObj } from './utils/configuration.js';
+
+import targetHandler from './server/handler.js';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readFile } from 'node:fs/promises';
+import { findTargetFiles } from './utils/auto-register.js';
+import { registerDocRoutes } from './auto-docs/ui/docs-ui.js';
+
+const logger = new TejLogger('Tejas');
+
+/**
+ * Main Tejas Framework Class
+ *
+ * @class
+ * @description
+ * Tejas is a Node.js framework for building powerful backend services.
+ * It provides features like routing, middleware support, database connections,
+ * and automatic target (route) registration.
+ */
+class Tejas {
+  /**
+   * Creates a new Tejas instance with the specified configuration
+   *
+   * @param {Object} [args] - Configuration options for Tejas
+   * @param {number} [args.port] - Port number to run the server on (defaults to 1403)
+   * @param {Object} [args.log] - Logging configuration
+   * @param {boolean} [args.log.http_requests] - Whether to log incoming HTTP requests
+   * @param {boolean} [args.log.exceptions] - Whether to log exceptions
+   * @param {Object} [args.db] - Database configuration options
+   * @param {Object} [args.withRedis] - Redis connection configuration
+   * @param {boolean} [args.withRedis.isCluster=false] - Whether to use Redis Cluster
+   * @param {Object} [args.withRedis.socket] - Redis socket connection options
+   * @param {string} [args.withRedis.socket.host] - Redis server hostname
+   * @param {number} [args.withRedis.socket.port] - Redis server port
+   * @param {boolean} [args.withRedis.socket.tls] - Whether to use TLS for connection
+   * @param {string} [args.withRedis.url] - Redis connection URL (alternative to socket config)
+   */
+  constructor(args) {
+    if (Tejas.instance) return Tejas.instance;
+    Tejas.instance = this;
+
+    this.options = args || {};
+
+    this.generateConfiguration();
+    this.registerTargetsDir();
+  }
+
+  /**
+   * Generates and loads configuration from multiple sources
+   *
+   * @private
+   * @description
+   * Loads and merges configuration from:
+   * 1. tejas.config.json file (lowest priority)
+   * 2. Environment variables
+   * 3. Constructor options (highest priority)
+   *
+   * All configuration keys are standardized to uppercase and flattened.
+   * Sets default values for required configuration if not provided.
+   */
+  generateConfiguration() {
+    const configVars = standardizeObj(loadConfigFile());
+    const envVars = standardizeObj(process.env);
+    const userVars = standardizeObj(this.options);
+
+    const config = { ...configVars, ...envVars, ...userVars };
+
+    for (const key in config) {
+      if (config.hasOwnProperty(key)) {
+        setEnv(key, config[key]);
+      }
+    }
+
+    // Set default values for required configuration if not provided
+    if (!env('PORT')) setEnv('PORT', 1403);
+    if (!env('BODY_MAX_SIZE')) setEnv('BODY_MAX_SIZE', 10 * 1024 * 1024); // 10MB default
+    if (!env('BODY_TIMEOUT')) setEnv('BODY_TIMEOUT', 30000); // 30 seconds default
+  }
+
+  /**
+   * Registers global middleware functions
+   *
+   * @param {...Function} arguments - Middleware functions to register globally
+   * @description
+   * Middleware functions are executed in order for all incoming requests.
+   * Each middleware should have the signature (ammo, next) or (req, res, next).
+   *
+   * @example
+   * app.midair(
+   *   (ammo, next) => {
+   *     console.log('Request received');
+   *     next();
+   *   },
+   *   authenticationMiddleware
+   * );
+   */
+  midair() {
+    if (arguments.length === 0) return;
+    targetRegistry.addGlobalMiddleware(...arguments);
+  }
+
+  /**
+   * Automatically registers target files from the configured directory
+   *
+   * @private
+   * @description
+   * Searches for and registers all files ending in 'target.js' from the
+   * directory specified by DIR_TARGETS environment variable.
+   * Target files define routes and their handlers.
+   *
+   * @throws {Error} If target files cannot be registered
+   */
+  registerTargetsDir() {
+    const baseDir = path.join(process.cwd(), process.env.DIR_TARGETS || '');
+    findTargetFiles()
+      .then((targetFiles) => {
+        if (!targetFiles?.length) return;
+        (async () => {
+          for (const file of targetFiles) {
+            const parentPath = file.path || '';
+            const fullPath = path.isAbsolute(parentPath)
+              ? path.join(parentPath, file.name)
+              : path.join(baseDir, parentPath, file.name);
+            const relativePath = path.relative(baseDir, fullPath);
+            const groupId = relativePath
+              .replace(/\.target\.js$/i, '')
+              .replace(/\\/g, '/')
+              || 'index';
+            targetRegistry.setCurrentSourceGroup(groupId);
+            try {
+              await import(pathToFileURL(fullPath).href);
+            } finally {
+              targetRegistry.setCurrentSourceGroup(null);
+            }
+          }
+        })().catch((err) => {
+          logger.error(
+            `Tejas could not register target files. Error: ${err}`,
+            false,
+          );
+        });
+      })
+      .catch((err) => {
+        logger.error(
+          `Tejas could not register target files. Error: ${err}`,
+          false,
+        );
+      });
+  }
+
+  /**
+   * Starts the Tejas server
+   *
+   * @param {Object} [options] - Server configuration options
+   * @param {Object} [options.withRedis] - Redis connection options
+   * @param {Object} [options.withMongo] - MongoDB connection options (https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/)
+   * @description
+   * Creates and starts an HTTP server on the configured port.
+   * Optionally initializes Redis and/or MongoDB connections if configuration is provided.
+   * For Redis, accepts cluster flag and all connection options supported by node-redis package.
+   * For MongoDB, accepts all connection options supported by the official MongoDB Node.js driver.
+   *
+   * @example
+   * const app = new Tejas();
+   *
+   * // Start server with Redis and MongoDB
+   * app.takeoff({
+   *   withRedis: {
+   *     url: 'redis://alice:foobared@awesome.redis.server:6380',
+   *     isCluster: false
+   *   },
+   *   withMongo: { url: 'mongodb://localhost:27017/mydatabase' }
+   * });
+   *
+   * // Start server with only Redis using defaults
+   * app.takeoff({
+   *   withRedis: { url: 'redis://localhost:6379' }
+   * });
+   *
+   * // Start server without databases
+   * app.takeoff(); // Server starts on default port 1403
+   */
+  takeoff({ withRedis, withMongo } = {}) {
+    this.engine = createServer(targetHandler);
+    this.engine.listen(env('PORT'), async () => {
+      logger.info(`Took off from port ${env('PORT')}`);
+
+      if (withRedis) await this.withRedis(withRedis);
+      if (withMongo) await this.withMongo(withMongo);
+    });
+
+    this.engine.on('error', (err) => {
+      logger.error(`Server error: ${err}`);
+    });
+  }
+
+  /**
+   * Initializes a Redis connection
+   *
+   * @param {Object} [config] - Redis connection configuration
+   * @param {boolean} [config.isCluster=false] - Whether to use Redis Cluster
+   * @param {Object} [config.socket] - Redis socket connection options
+   * @param {string} [config.socket.host] - Redis server hostname
+   * @param {number} [config.socket.port] - Redis server port
+   * @param {boolean} [config.socket.tls] - Whether to use TLS for connection
+   * @param {string} [config.url] - Redis connection URL (alternative to socket config)
+   * @returns {Promise<Tejas>} Returns a Promise that resolves to this instance for chaining
+   *
+   * @example
+   * // Initialize Redis with URL
+   * await app.withRedis({
+   *   url: 'redis://localhost:6379'
+   * }).withRateLimit({
+   *   maxRequests: 100,
+   *   store: 'redis'
+   * });
+   *
+   * @example
+   * // Initialize Redis with socket options
+   * await app.withRedis({
+   *   socket: {
+   *     host: 'localhost',
+   *     port: 6379
+   *   }
+   * });
+   */
+  async withRedis(config) {
+    if (config) {
+      await dbManager.initializeConnection('redis', config);
+    } else {
+      logger.warn(
+        'No Redis configuration provided. Skipping Redis connection.',
+      );
+    }
+
+    return this;
+  }
+
+  /**
+   * Initializes a MongoDB connection
+   *
+   * @param {Object} [config] - MongoDB connection configuration
+   * @param {string} [config.uri] - MongoDB connection URI
+   * @param {Object} [config.options] - Additional MongoDB connection options
+   * @returns {Tejas} Returns a Promise that resolves to this instance for chaining
+   *
+   * @example
+   * // Initialize MongoDB with URI
+   * await app.withMongo({
+   *   uri: 'mongodb://localhost:27017/myapp'
+   * });
+   *
+   * @example
+   * // Initialize MongoDB with options
+   * await app.withMongo({
+   *   uri: 'mongodb://localhost:27017/myapp',
+   *   options: {
+   *     useNewUrlParser: true,
+   *     useUnifiedTopology: true
+   *   }
+   * });
+   *
+   * @example
+   * // Chain database connections
+   * await app
+   *   .withMongo({
+   *     uri: 'mongodb://localhost:27017/myapp'
+   *   })
+   *   .withRedis({
+   *     url: 'redis://localhost:6379'
+   *   })
+   *   .withRateLimit({
+   *     maxRequests: 100,
+   *     store: 'redis'
+   *   });
+   */
+  withMongo(config) {
+    if (config) {
+      dbManager.initializeConnection('mongodb', config);
+    } else {
+      logger.warn(
+        'No MongoDB configuration provided. Skipping MongoDB connection.',
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Adds global rate limiting to all endpoints
+   *
+   * @param {Object} config - Rate limiting configuration
+   * @param {number} [config.maxRequests=60] - Maximum number of requests allowed in the time window
+   * @param {number} [config.timeWindowSeconds=60] - Time window in seconds
+   * @param {string} [config.algorithm='sliding-window'] - Rate-limiting algorithm ('token-bucket', 'sliding-window', or 'fixed-window')
+   * @param {Object} [config.algorithmOptions] - Algorithm-specific options
+   * @param {Object} [config.redis] - Redis configuration for distributed rate limiting
+   * @param {Function} [config.keyGenerator] - Function to generate unique identifiers (defaults to IP-based)
+   * @param {Object} [config.headerFormat] - Rate limit header format configuration
+   * @returns {Tejas} The Tejas instance for chaining
+   *
+   */
+  withRateLimit(config) {
+    if (!config) {
+      logger.warn(
+        'No rate limit configuration provided. Skipping rate limit setup.',
+      );
+      return this;
+    }
+
+    this.midair(rateLimiter(config));
+    return this;
+  }
+
+  /**
+   * Serves the API documentation at GET /docs and GET /docs/openapi.json from a pre-generated spec file.
+   * Generate the spec with `tejas generate:docs`, then call this to serve it on your app.
+   * Uses Scalar API Reference; default layout is 'classic' so the test request appears on the same page (not in a dialog).
+   *
+   * @param {Object} [config] - Configuration
+   * @param {string} [config.specPath='./openapi.json'] - Path to the OpenAPI spec JSON file (relative to process.cwd())
+   * @param {object} [config.scalarConfig] - Optional Scalar API Reference config (e.g. { layout: 'modern' } for dialog try-it)
+   * @returns {Tejas} The Tejas instance for chaining
+   *
+   * @example
+   * app.serveDocs({ specPath: './openapi.json' });
+   * app.serveDocs({ specPath: './openapi.json', scalarConfig: { layout: 'modern' } });
+   * app.takeoff();
+   */
+  serveDocs(config = {}) {
+    const specPath = path.resolve(process.cwd(), config.specPath || './openapi.json');
+    const { scalarConfig } = config;
+    const getSpec = async () => {
+      const content = await readFile(specPath, 'utf8');
+      return JSON.parse(content);
+    };
+    registerDocRoutes({ getSpec, specUrl: '/docs/openapi.json', scalarConfig }, targetRegistry);
+    return this;
+  }
+
+}
+
+const listAllEndpoints = (grouped = false) => {
+  return targetRegistry.getAllEndpoints(grouped);
+};
+
+export { default as Target } from './server/target.js';
+export { default as TejFileUploader } from './server/files/uploader.js';
+export { default as TejError } from './server/error.js';
+export { listAllEndpoints };
+
+export default Tejas;
+
+// TODO Ability to register a target (route) from tejas instance
+// TODO tejas as CLI tool

package/tests/auto-docs/handler-analyzer.test.js

@@ -0,0 +1,44 @@
+/**
+ * Unit tests for auto-docs handler-analyzer (detectMethods, analyzeHandler).
+ */
+import { describe, it, expect } from 'vitest';
+import { detectMethods, analyzeHandler, ALL_METHODS } from '../../auto-docs/analysis/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);
+    });
+  });
+
+  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/tests/auto-docs/openapi-generator.test.js

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for auto-docs openapi/generator pure functions.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  toOpenAPIPath,
+  getPathParameters,
+  getQueryParameters,
+  buildSchemaFromMetadata,
+  buildResponses,
+  buildOperation,
+  mergeMetadata,
+} from '../../auto-docs/openapi/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');
+    });
+  });
+});