@koa/router 14.0.0 → 15.0.0

package/dist/layer.mjs

@@ -0,0 +1,436 @@
+// src/layer.ts
+import { parse as parseUrl, format as formatUrl } from "url";
+
+// src/utils/path-to-regexp-wrapper.ts
+import { pathToRegexp, compile, parse } from "path-to-regexp";
+function compilePathToRegexp(path, options = {}) {
+  const normalizedOptions = { ...options };
+  if ("strict" in normalizedOptions && !("trailing" in normalizedOptions)) {
+    normalizedOptions.trailing = normalizedOptions.strict !== true;
+    delete normalizedOptions.strict;
+  }
+  delete normalizedOptions.pathAsRegExp;
+  delete normalizedOptions.ignoreCaptures;
+  delete normalizedOptions.prefix;
+  const { regexp, keys } = pathToRegexp(path, normalizedOptions);
+  return { regexp, keys };
+}
+function compilePath(path, options = {}) {
+  return compile(path, options);
+}
+function parsePath(path, options) {
+  return parse(path, options);
+}
+function normalizeLayerOptionsToPathToRegexp(options = {}) {
+  const normalized = {
+    sensitive: options.sensitive,
+    end: options.end,
+    strict: options.strict,
+    trailing: options.trailing
+  };
+  if ("strict" in normalized && !("trailing" in normalized)) {
+    normalized.trailing = normalized.strict !== true;
+    delete normalized.strict;
+  }
+  for (const key of Object.keys(normalized)) {
+    if (normalized[key] === void 0) {
+      delete normalized[key];
+    }
+  }
+  return normalized;
+}
+
+// src/layer.ts
+function safeDecodeURIComponent(text) {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+}
+var Layer = class {
+  opts;
+  name;
+  methods;
+  paramNames;
+  stack;
+  path;
+  regexp;
+  /**
+   * Initialize a new routing Layer with given `method`, `path`, and `middleware`.
+   *
+   * @param path - Path string or regular expression
+   * @param methods - Array of HTTP verbs
+   * @param middleware - Layer callback/middleware or series of
+   * @param opts - Layer options
+   * @private
+   */
+  constructor(path, methods, middleware, options = {}) {
+    this.opts = options;
+    this.name = this.opts.name || void 0;
+    this.methods = this._normalizeHttpMethods(methods);
+    this.stack = this._normalizeAndValidateMiddleware(
+      middleware,
+      methods,
+      path
+    );
+    this.path = path;
+    this.paramNames = [];
+    this._configurePathMatching();
+  }
+  /**
+   * Normalize HTTP methods and add automatic HEAD support for GET
+   * @private
+   */
+  _normalizeHttpMethods(methods) {
+    const normalizedMethods = [];
+    for (const method of methods) {
+      const upperMethod = method.toUpperCase();
+      normalizedMethods.push(upperMethod);
+      if (upperMethod === "GET") {
+        normalizedMethods.unshift("HEAD");
+      }
+    }
+    return normalizedMethods;
+  }
+  /**
+   * Normalize middleware to array and validate all are functions
+   * @private
+   */
+  _normalizeAndValidateMiddleware(middleware, methods, path) {
+    const middlewareArray = Array.isArray(middleware) ? middleware : [middleware];
+    for (const middlewareFunction of middlewareArray) {
+      const middlewareType = typeof middlewareFunction;
+      if (middlewareType !== "function") {
+        const routeIdentifier = this.opts.name || path;
+        throw new Error(
+          `${methods.toString()} \`${routeIdentifier}\`: \`middleware\` must be a function, not \`${middlewareType}\``
+        );
+      }
+    }
+    return middlewareArray;
+  }
+  /**
+   * Configure path matching regexp and parameters
+   * @private
+   */
+  _configurePathMatching() {
+    if (this.opts.pathAsRegExp === true) {
+      this.regexp = this.path instanceof RegExp ? this.path : new RegExp(this.path);
+    } else if (this.path) {
+      this._configurePathToRegexp();
+    }
+  }
+  /**
+   * Configure path-to-regexp for string paths
+   * @private
+   */
+  _configurePathToRegexp() {
+    const options = normalizeLayerOptionsToPathToRegexp(this.opts);
+    const { regexp, keys } = compilePathToRegexp(this.path, options);
+    this.regexp = regexp;
+    this.paramNames = keys;
+  }
+  /**
+   * Returns whether request `path` matches route.
+   *
+   * @param path - Request path
+   * @returns Whether path matches
+   * @private
+   */
+  match(path) {
+    return this.regexp.test(path);
+  }
+  /**
+   * Returns map of URL parameters for given `path` and `paramNames`.
+   *
+   * @param _path - Request path (not used, kept for API compatibility)
+   * @param captures - Captured values from regexp
+   * @param existingParams - Existing params to merge with
+   * @returns Parameter map
+   * @private
+   */
+  params(_path, captures, existingParameters = {}) {
+    const parameterValues = { ...existingParameters };
+    for (const [captureIndex, capturedValue] of captures.entries()) {
+      const parameterDefinition = this.paramNames[captureIndex];
+      if (parameterDefinition && capturedValue && capturedValue.length > 0) {
+        const parameterName = parameterDefinition.name;
+        parameterValues[parameterName] = safeDecodeURIComponent(capturedValue);
+      }
+    }
+    return parameterValues;
+  }
+  /**
+   * Returns array of regexp url path captures.
+   *
+   * @param path - Request path
+   * @returns Array of captured values
+   * @private
+   */
+  captures(path) {
+    if (this.opts.ignoreCaptures) {
+      return [];
+    }
+    const match = path.match(this.regexp);
+    return match ? match.slice(1) : [];
+  }
+  /**
+   * Generate URL for route using given `params`.
+   *
+   * @example
+   *
+   * ```javascript
+   * const route = new Layer('/users/:id', ['GET'], fn);
+   *
+   * route.url({ id: 123 }); // => "/users/123"
+   * ```
+   *
+   * @param args - URL parameters (various formats supported)
+   * @returns Generated URL
+   * @private
+   */
+  url(...arguments_) {
+    const { params, options } = this._parseUrlArguments(arguments_);
+    const cleanPath = this.path.replaceAll("(.*)", "");
+    const pathCompiler = compilePath(cleanPath, {
+      encode: encodeURIComponent,
+      ...options
+    });
+    const parameterReplacements = this._buildParamReplacements(
+      params,
+      cleanPath
+    );
+    const generatedUrl = pathCompiler(parameterReplacements);
+    if (options && options.query) {
+      return this._addQueryString(generatedUrl, options.query);
+    }
+    return generatedUrl;
+  }
+  /**
+   * Parse url() arguments into params and options
+   * Supports multiple call signatures:
+   * - url({ id: 1 })
+   * - url(1, 2, 3)
+   * - url({ query: {...} })
+   * - url({ id: 1 }, { query: {...} })
+   * @private
+   */
+  _parseUrlArguments(allArguments) {
+    let parameters = allArguments[0];
+    let options = allArguments[1];
+    if (typeof parameters !== "object") {
+      const argumentsList = [...allArguments];
+      const lastArgument = argumentsList.at(-1);
+      if (typeof lastArgument === "object") {
+        options = lastArgument;
+        parameters = argumentsList.slice(0, -1);
+      } else {
+        parameters = argumentsList;
+      }
+    } else if (parameters && parameters.query && !options) {
+      options = parameters;
+      parameters = {};
+    }
+    return { params: parameters, options };
+  }
+  /**
+   * Build parameter replacements for URL generation
+   * @private
+   */
+  _buildParamReplacements(parameters, cleanPath) {
+    const { tokens } = parsePath(cleanPath);
+    const hasNamedParameters = tokens.some(
+      (token) => "name" in token && token.name
+    );
+    const parameterReplacements = {};
+    if (Array.isArray(parameters)) {
+      let parameterIndex = 0;
+      for (const token of tokens) {
+        if ("name" in token && token.name) {
+          parameterReplacements[token.name] = String(
+            parameters[parameterIndex++]
+          );
+        }
+      }
+    } else if (hasNamedParameters && typeof parameters === "object" && !parameters.query) {
+      for (const [parameterName, parameterValue] of Object.entries(
+        parameters
+      )) {
+        parameterReplacements[parameterName] = String(parameterValue);
+      }
+    }
+    return parameterReplacements;
+  }
+  /**
+   * Add query string to URL
+   * @private
+   */
+  _addQueryString(baseUrl, query) {
+    const parsedUrl = parseUrl(baseUrl);
+    if (typeof query === "string") {
+      parsedUrl.search = query;
+    } else {
+      parsedUrl.search = void 0;
+      parsedUrl.query = query;
+    }
+    return formatUrl(parsedUrl);
+  }
+  /**
+   * Run validations on route named parameters.
+   *
+   * @example
+   *
+   * ```javascript
+   * router
+   *   .param('user', function (id, ctx, next) {
+   *     ctx.user = users[id];
+   *     if (!ctx.user) return ctx.status = 404;
+   *     next();
+   *   })
+   *   .get('/users/:user', function (ctx, next) {
+   *     ctx.body = ctx.user;
+   *   });
+   * ```
+   *
+   * @param paramName - Parameter name
+   * @param paramHandler - Middleware function
+   * @returns This layer instance
+   * @private
+   */
+  param(parameterName, parameterHandler) {
+    const middlewareStack = this.stack;
+    const routeParameterNames = this.paramNames;
+    const parameterMiddleware = this._createParamMiddleware(
+      parameterName,
+      parameterHandler
+    );
+    const parameterNamesList = routeParameterNames.map(
+      (parameterDefinition) => parameterDefinition.name
+    );
+    const parameterPosition = parameterNamesList.indexOf(parameterName);
+    if (parameterPosition !== -1) {
+      this._insertParamMiddleware(
+        middlewareStack,
+        parameterMiddleware,
+        parameterNamesList,
+        parameterPosition
+      );
+    }
+    return this;
+  }
+  /**
+   * Create param middleware with deduplication tracking
+   * @private
+   */
+  _createParamMiddleware(parameterName, parameterHandler) {
+    const middleware = function(context, next) {
+      if (!context._matchedParams) {
+        context._matchedParams = /* @__PURE__ */ new WeakMap();
+      }
+      if (context._matchedParams.has(parameterHandler)) {
+        return next();
+      }
+      context._matchedParams.set(parameterHandler, true);
+      return parameterHandler.call(
+        this,
+        context.params[parameterName],
+        context,
+        next
+      );
+    };
+    middleware.param = parameterName;
+    middleware._originalFn = parameterHandler;
+    return middleware;
+  }
+  /**
+   * Insert param middleware at the correct position in the stack
+   * @private
+   */
+  _insertParamMiddleware(middlewareStack, parameterMiddleware, parameterNamesList, currentParameterPosition) {
+    middlewareStack.some((existingMiddleware, stackIndex) => {
+      if (!existingMiddleware.param) {
+        middlewareStack.splice(stackIndex, 0, parameterMiddleware);
+        return true;
+      }
+      const existingParameterPosition = parameterNamesList.indexOf(
+        existingMiddleware.param
+      );
+      if (existingParameterPosition > currentParameterPosition) {
+        middlewareStack.splice(stackIndex, 0, parameterMiddleware);
+        return true;
+      }
+      return false;
+    });
+  }
+  /**
+   * Prefix route path.
+   *
+   * @param prefixPath - Prefix to prepend
+   * @returns This layer instance
+   * @private
+   */
+  setPrefix(prefixPath) {
+    if (!this.path) {
+      return this;
+    }
+    if (this.path instanceof RegExp) {
+      return this;
+    }
+    this.path = this._applyPrefix(prefixPath);
+    this._reconfigurePathMatching(prefixPath);
+    return this;
+  }
+  /**
+   * Apply prefix to the current path
+   * @private
+   */
+  _applyPrefix(prefixPath) {
+    const isRootPath = this.path === "/";
+    const isStrictMode = this.opts.strict === true;
+    const prefixHasParameters = prefixPath.includes(":");
+    const pathIsRawRegex = this.opts.pathAsRegExp === true && typeof this.path === "string";
+    if (prefixHasParameters && pathIsRawRegex) {
+      const currentPath = this.path;
+      if (currentPath === String.raw`(?:\/|$)` || currentPath === String.raw`(?:\/|$)`) {
+        this.path = "{/*rest}";
+        this.opts.pathAsRegExp = false;
+      }
+    }
+    if (isRootPath && !isStrictMode) {
+      return prefixPath;
+    }
+    return `${prefixPath}${this.path}`;
+  }
+  /**
+   * Reconfigure path matching after prefix is applied
+   * @private
+   */
+  _reconfigurePathMatching(prefixPath) {
+    const treatAsRegExp = this.opts.pathAsRegExp === true;
+    const prefixHasParameters = prefixPath && prefixPath.includes(":");
+    if (prefixHasParameters && treatAsRegExp) {
+      const options = normalizeLayerOptionsToPathToRegexp(this.opts);
+      const { regexp, keys } = compilePathToRegexp(
+        this.path,
+        options
+      );
+      this.regexp = regexp;
+      this.paramNames = keys;
+      this.opts.pathAsRegExp = false;
+    } else if (treatAsRegExp) {
+      this.regexp = this.path instanceof RegExp ? this.path : new RegExp(this.path);
+    } else {
+      const options = normalizeLayerOptionsToPathToRegexp(this.opts);
+      const { regexp, keys } = compilePathToRegexp(
+        this.path,
+        options
+      );
+      this.regexp = regexp;
+      this.paramNames = keys;
+    }
+  }
+};
+export {
+  Layer as default
+};

package/dist/router.d.mts

@@ -0,0 +1,3 @@
+import 'koa';
+export { R as default } from './layer.mjs';
+import 'path-to-regexp';

package/dist/router.d.ts

@@ -0,0 +1,3 @@
+import 'koa';
+export { R as default } from './layer.js';
+import 'path-to-regexp';