te.js 1.3.0 → 2.0.0

package/server/endpoint.js

@@ -7,6 +7,9 @@ class Endpoint {
     this.path = '';
     this.middlewares = [];
     this.handler = null;
+    this.metadata = null;
+    /** Source group (e.g. target file id) for grouping in docs. Set by loader before register(). */
+    this.group = null;
   }
 
   setPath(base, path) {
@@ -37,6 +40,16 @@ class Endpoint {
     return this;
   }
 
+  setMetadata(metadata) {
+    this.metadata = metadata ?? null;
+    return this;
+  }
+
+  setGroup(group) {
+    this.group = group ?? null;
+    return this;
+  }
+
   getPath() {
     return this.path;
   }
@@ -48,6 +61,14 @@ class Endpoint {
   getHandler() {
     return this.handler;
   }
+
+  getMetadata() {
+    return this.metadata;
+  }
+
+  getGroup() {
+    return this.group;
+  }
 }
 
 export default Endpoint;

package/server/handler.js

@@ -1,87 +1,113 @@
-import { env } from 'tej-env';
-import TejLogger from 'tej-logger';
-import logHttpRequest from '../utils/request-logger.js';
-
-import Ammo from './ammo.js';
-import TejError from './error.js';
-import TargetRegistry from './targets/registry.js';
-
-const targetRegistry = new TargetRegistry();
-const errorLogger = new TejLogger('Tejas.Exception');
-
-/**
- * Executes the middleware and handler chain for a given target.
- *
- * @param {Object} target - The target endpoint object.
- * @param {Ammo} ammo - The Ammo instance containing request and response objects.
- * @returns {Promise<void>} A promise that resolves when the chain execution is complete.
- */
-const executeChain = async (target, ammo) => {
-  let i = 0;
-
-  const chain = targetRegistry.globalMiddlewares.concat(
-    target.getMiddlewares(),
-  );
-  chain.push(target.getHandler());
-
-  const next = async () => {
-    const middleware = chain[i];
-    i++;
-
-    const args =
-      middleware.length === 3 ? [ammo.req, ammo.res, next] : [ammo, next];
-
-    try {
-      await middleware(...args);
-    } catch (err) {
-      errorHandler(ammo, err);
-    }
-  };
-
-  await next();
-};
-
-/**
- * Handles errors by logging them and sending an appropriate response.
- *
- * @param {Ammo} ammo - The Ammo instance containing request and response objects.
- * @param {Error} err - The error object to handle.
- */
-const errorHandler = (ammo, err) => {
-  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
-
-  if (err instanceof TejError) return ammo.throw(err);
-  return ammo.throw(err);
-};
-
-/**
- * Main request handler function.
- *
- * @param {http.IncomingMessage} req - The HTTP request object.
- * @param {http.ServerResponse} res - The HTTP response object.
- * @returns {Promise<void>} A promise that resolves when the request handling is complete.
- */
-const handler = async (req, res) => {
-  const url = req.url.split('?')[0];
-  const target = targetRegistry.aim(url);
-  const ammo = new Ammo(req, res);
-
-  try {
-    if (target) {
-      await ammo.enhance();
-
-      if (env('LOG_HTTP_REQUESTS')) logHttpRequest(ammo);
-      await executeChain(target, ammo);
-    } else {
-      if (req.url === '/') {
-        ammo.defaultEntry();
-      } else {
-        errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
-      }
-    }
-  } catch (err) {
-    errorHandler(ammo, err);
-  }
-};
-
-export default handler;
+import { env } from 'tej-env';
+import TejLogger from 'tej-logger';
+import logHttpRequest from '../utils/request-logger.js';
+
+import Ammo from './ammo.js';
+import TejError from './error.js';
+import targetRegistry from './targets/registry.js';
+
+const errorLogger = new TejLogger('Tejas.Exception');
+
+/**
+ * Executes the middleware and handler chain for a given target.
+ *
+ * @param {Object} target - The target endpoint object.
+ * @param {Ammo} ammo - The Ammo instance containing request and response objects.
+ * @returns {Promise<void>} A promise that resolves when the chain execution is complete.
+ */
+const executeChain = async (target, ammo) => {
+  let i = 0;
+
+  const chain = targetRegistry.globalMiddlewares.concat(
+    target.getMiddlewares(),
+  );
+  chain.push(target.getHandler());
+
+  const next = async () => {
+    // Check if response has already been sent (e.g., by passport.authenticate redirect)
+    if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+      return;
+    }
+
+    const middleware = chain[i];
+    i++;
+
+    const args =
+      middleware.length === 3 ? [ammo.req, ammo.res, next] : [ammo, next];
+
+    try {
+      const result = await middleware(...args);
+      
+      // Check again after middleware execution (passport might have redirected)
+      if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+        return;
+      }
+      
+      // If middleware returned a promise that resolved, continue chain
+      if (result && typeof result.then === 'function') {
+        await result;
+        // Check one more time after promise resolution
+        if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+          return;
+        }
+      }
+    } catch (err) {
+      // Only handle error if response hasn't been sent
+      if (!ammo.res.headersSent && !ammo.res.writableEnded && !ammo.res.finished) {
+        errorHandler(ammo, err);
+      }
+    }
+  };
+
+  await next();
+};
+
+/**
+ * Handles errors by logging them and sending an appropriate response.
+ *
+ * @param {Ammo} ammo - The Ammo instance containing request and response objects.
+ * @param {Error} err - The error object to handle.
+ */
+const errorHandler = (ammo, err) => {
+  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
+
+  if (err instanceof TejError) return ammo.throw(err);
+  return ammo.throw(err);
+};
+
+/**
+ * Main request handler function.
+ *
+ * @param {http.IncomingMessage} req - The HTTP request object.
+ * @param {http.ServerResponse} res - The HTTP response object.
+ * @returns {Promise<void>} A promise that resolves when the request handling is complete.
+ */
+const handler = async (req, res) => {
+  const url = req.url.split('?')[0];
+  const match = targetRegistry.aim(url);
+  const ammo = new Ammo(req, res);
+
+  try {
+    if (match && match.target) {
+      await ammo.enhance();
+
+      // Add route parameters to ammo.payload
+      if (match.params && Object.keys(match.params).length > 0) {
+        Object.assign(ammo.payload, match.params);
+      }
+
+      if (env('LOG_HTTP_REQUESTS')) logHttpRequest(ammo);
+      await executeChain(match.target, ammo);
+    } else {
+      if (req.url === '/') {
+        ammo.defaultEntry();
+      } else {
+        errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
+      }
+    }
+  } catch (err) {
+    errorHandler(ammo, err);
+  }
+};
+
+export default handler;

package/server/target.js

@@ -3,8 +3,7 @@ import TejLogger from 'tej-logger';
 import isMiddlewareValid from './targets/middleware-validator.js';
 import Endpoint from './endpoint.js';
 
-import TargetRegistry from './targets/registry.js';
-const targetRegistry = new TargetRegistry();
+import targetRegistry from './targets/registry.js';
 
 const logger = new TejLogger('Target');
 
@@ -110,19 +109,61 @@ class Target {
    * );
    */
   register() {
-    let args = arguments;
-    if (!args) return;
+    const args = Array.from(arguments);
+    if (args.length < 2) {
+      logger.error('register(path, [...middlewares], handler) requires at least path and handler. Skipping.');
+      return;
+    }
 
     const path = args[0];
     const shoot = args[args.length - 1];
-    const middlewares = Array.from(args).slice(1, args.length - 1);
+
+    if (typeof path !== 'string') {
+      logger.error(`register() path must be a string, got ${typeof path}. Skipping.`);
+      return;
+    }
+    if (typeof shoot !== 'function') {
+      logger.error(`register() last argument (handler) must be a function, got ${typeof shoot}. Skipping.`);
+      return;
+    }
+
+    const second = args[1];
+    const isPlainObject = (v) =>
+      typeof v === 'object' &&
+      v !== null &&
+      !Array.isArray(v) &&
+      (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+    const isMetadataObject = isPlainObject(second);
+
+    let middlewares;
+    let metadata = null;
+    if (isMetadataObject && args.length >= 3) {
+      metadata = second;
+      middlewares = args.slice(2, -1);
+    } else {
+      middlewares = args.slice(1, -1);
+    }
 
     try {
       const endpoint = new Endpoint();
-      endpoint
-        .setPath(this.base, path)
-        .setMiddlewares(middlewares)
-        .setHandler(shoot);
+      endpoint.setPath(this.base, path);
+      if (!endpoint.getPath()) {
+        logger.error(`Invalid path for endpoint "${path}". Skipping.`);
+        return;
+      }
+      endpoint.setMiddlewares(middlewares);
+      endpoint.setHandler(shoot);
+      if (!endpoint.getHandler()) {
+        logger.error(`Invalid handler for endpoint "${path}". Skipping.`);
+        return;
+      }
+      if (metadata !== null) {
+        endpoint.setMetadata(metadata);
+      }
+      const group = targetRegistry.getCurrentSourceGroup();
+      if (group != null) {
+        endpoint.setGroup(group);
+      }
 
       targetRegistry.targets.push(endpoint);
     } catch (error) {

package/server/targets/registry.js

@@ -1,4 +1,5 @@
 import isMiddlewareValid from './middleware-validator.js';
+import { standardizePath } from './path-validator.js';
 
 class TargetRegistry {
   constructor() {
@@ -11,6 +12,16 @@ class TargetRegistry {
     // TODO - Add a default target
     this.targets = [];
     this.globalMiddlewares = [];
+    /** Current source group (target file id) set by loader before importing a target file. */
+    this._currentSourceGroup = null;
+  }
+
+  setCurrentSourceGroup(group) {
+    this._currentSourceGroup = group ?? null;
+  }
+
+  getCurrentSourceGroup() {
+    return this._currentSourceGroup;
   }
 
   addGlobalMiddleware() {
@@ -32,13 +43,107 @@ class TargetRegistry {
     }
   }
 
+  /**
+   * Matches an endpoint URL to a registered target, supporting parameterized routes.
+   *
+   * @param {string} endpoint - The endpoint URL to match
+   * @returns {Object|null} An object with `target` and `params`, or null if no match
+   */
   aim(endpoint) {
-    return this.targets.find((target) => {
-      return target.getPath() === endpoint;
+    const standardizedEndpoint = standardizePath(endpoint);
+
+    // First, try exact match (most specific)
+    const exactMatch = this.targets.find((target) => {
+      return target.getPath() === standardizedEndpoint;
     });
+
+    if (exactMatch) {
+      return { target: exactMatch, params: {} };
+    }
+
+    // Then, try parameterized route matching
+    for (const target of this.targets) {
+      const targetPath = target.getPath();
+      const params = this.matchParameterizedRoute(
+        targetPath,
+        standardizedEndpoint,
+      );
+
+      if (params !== null) {
+        return { target, params };
+      }
+    }
+
+    return null;
   }
 
-  getAllEndpoints(grouped) {
+  /**
+   * Matches a parameterized route pattern against an actual URL.
+   *
+   * @param {string} pattern - The route pattern (e.g., '/api/categories/:id')
+   * @param {string} url - The actual URL to match (e.g., '/api/categories/123')
+   * @returns {Object|null} An object with extracted parameters, or null if no match
+   */
+  matchParameterizedRoute(pattern, url) {
+    // Handle root path case
+    if (pattern === '/' && url === '/') {
+      return {};
+    }
+
+    // Split both pattern and URL into segments
+    const patternSegments = pattern.split('/').filter((s) => s.length > 0);
+    const urlSegments = url.split('/').filter((s) => s.length > 0);
+
+    // Must have same number of segments
+    if (patternSegments.length !== urlSegments.length) {
+      return null;
+    }
+
+    // If both are empty (root paths), they match
+    if (patternSegments.length === 0 && urlSegments.length === 0) {
+      return {};
+    }
+
+    const params = {};
+
+    // Match each segment
+    for (let i = 0; i < patternSegments.length; i++) {
+      const patternSegment = patternSegments[i];
+      const urlSegment = urlSegments[i];
+
+      // If it's a parameter (starts with :)
+      if (patternSegment.startsWith(':')) {
+        const paramName = patternSegment.slice(1); // Remove the ':'
+        params[paramName] = urlSegment;
+      } else if (patternSegment !== urlSegment) {
+        // If it's not a parameter and doesn't match, no match
+        return null;
+      }
+    }
+
+    return params;
+  }
+
+  /**
+   * Get all registered endpoints.
+   *
+   * @param {boolean|{ detailed?: boolean, grouped?: boolean }} [options] - If boolean, treated as grouped (backward compat).
+   *   If object: detailed=true returns full metadata per endpoint; grouped=true returns paths grouped by first segment.
+   * @returns {string[]|Object|Array<{ path: string, metadata: object|null, handler: function }>}
+   */
+  getAllEndpoints(options = {}) {
+    const grouped =
+      typeof options === 'boolean' ? options : (options && options.grouped);
+    const detailed =
+      typeof options === 'object' && options && options.detailed === true;
+
+    if (detailed) {
+      return this.targets.map((t) => ({
+        path: t.getPath(),
+        metadata: t.getMetadata(),
+        handler: t.getHandler(),
+      }));
+    }
     if (grouped) {
       return this.targets.reduce((acc, target) => {
         const group = target.getPath().split('/')[1];
@@ -46,10 +151,10 @@ class TargetRegistry {
         acc[group].push(target.getPath());
         return acc;
       }, {});
-    } else {
-      return this.targets.map((target) => target.getPath());
     }
+    return this.targets.map((target) => target.getPath());
   }
 }
 
-export default TargetRegistry;
+const targetRegistry = new TargetRegistry();
+export default targetRegistry;