express-version-api 1.0.1 → 2.0.4

package/dist/index.cjs

@@ -0,0 +1,708 @@
+'use strict';
+
+/* express-version-api - MIT License - https://github.com/Braian-Quintian/express-version-api */
+
+// src/types.ts
+var VersioningError = class _VersioningError extends Error {
+  code;
+  requestedVersion;
+  availableVersions;
+  statusCode;
+  constructor(details, statusCode = 422) {
+    super(details.message);
+    this.name = "VersioningError";
+    this.code = details.code;
+    this.requestedVersion = details.requestedVersion;
+    this.availableVersions = details.availableVersions;
+    this.statusCode = statusCode;
+    Error.captureStackTrace(this, _VersioningError);
+  }
+  /**
+   * Converts the error to a JSON-serializable object.
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...this.requestedVersion !== void 0 && { requestedVersion: this.requestedVersion },
+      ...this.availableVersions !== void 0 && { availableVersions: this.availableVersions }
+    };
+  }
+};
+
+// src/errors.ts
+function createMissingVersionError(statusCode = 422, message = "API version is required") {
+  return new VersioningError(
+    {
+      code: "MISSING_VERSION",
+      message
+    },
+    statusCode
+  );
+}
+function createVersionNotFoundError(requestedVersion, availableVersions, statusCode = 422) {
+  return new VersioningError(
+    {
+      code: "VERSION_NOT_FOUND",
+      message: `No handler found for API version '${requestedVersion}'`,
+      requestedVersion,
+      availableVersions
+    },
+    statusCode
+  );
+}
+function createInvalidVersionFormatError(version, statusCode = 400) {
+  return new VersioningError(
+    {
+      code: "INVALID_VERSION_FORMAT",
+      message: `Invalid version format: '${version}'`,
+      requestedVersion: version
+    },
+    statusCode
+  );
+}
+function createInvalidHandlerError(key, reason) {
+  return new VersioningError(
+    {
+      code: "INVALID_HANDLER",
+      message: `Invalid handler for version '${key}': ${reason}`
+    },
+    500
+  );
+}
+function createInvalidConfigurationError(reason) {
+  return new VersioningError(
+    {
+      code: "INVALID_CONFIGURATION",
+      message: `Invalid configuration: ${reason}`
+    },
+    500
+  );
+}
+function isVersioningError(error) {
+  return error instanceof VersioningError;
+}
+function hasErrorCode(error, code) {
+  return isVersioningError(error) && error.code === code;
+}
+
+// src/config.ts
+var DEFAULT_CONFIG = {
+  extraction: {
+    sources: ["header", "query"],
+    header: {
+      name: "accept-version"
+    },
+    query: {
+      name: "v"
+    },
+    path: {
+      pattern: /\/v(\d+(?:\.\d+)?(?:\.\d+)?)\//
+    },
+    custom: void 0
+  },
+  errorResponse: {
+    missingVersionStatus: 422,
+    versionNotFoundStatus: 422,
+    missingVersionMessage: "API version is required",
+    versionNotFoundMessage: "No handler found for the requested API version",
+    includeRequestedVersion: true,
+    onError: void 0
+  },
+  fallbackStrategy: "default",
+  defaultHandler: void 0,
+  validateHandlers: true,
+  attachVersionInfo: true,
+  requireVersion: true
+};
+function resolveConfig(options) {
+  if (!options) {
+    return DEFAULT_CONFIG;
+  }
+  if (options.fallbackStrategy !== void 0) {
+    const validStrategies = /* @__PURE__ */ new Set(["latest", "none", "default"]);
+    if (!validStrategies.has(options.fallbackStrategy)) {
+      throw createInvalidConfigurationError(
+        `Invalid fallback strategy: '${options.fallbackStrategy}'. Valid strategies: latest, none, default`
+      );
+    }
+  }
+  if (options.extraction?.sources) {
+    const validSources = /* @__PURE__ */ new Set(["header", "query", "path", "custom"]);
+    for (const source of options.extraction.sources) {
+      if (!validSources.has(source)) {
+        throw createInvalidConfigurationError(
+          `Invalid version source: '${source}'. Valid sources: header, query, path, custom`
+        );
+      }
+    }
+    if (options.extraction.sources.includes("custom") && !options.extraction.custom) {
+      throw createInvalidConfigurationError(
+        "Custom extractor function is required when 'custom' source is used"
+      );
+    }
+  }
+  if (options.extraction?.path?.pattern && !(options.extraction.path.pattern instanceof RegExp)) {
+    throw createInvalidConfigurationError("Path pattern must be a RegExp instance");
+  }
+  if (options.errorResponse?.missingVersionStatus !== void 0) {
+    const status = options.errorResponse.missingVersionStatus;
+    if (!Number.isInteger(status) || status < 100 || status > 599) {
+      throw createInvalidConfigurationError(
+        "missingVersionStatus must be a valid HTTP status code (100-599)"
+      );
+    }
+  }
+  if (options.errorResponse?.versionNotFoundStatus !== void 0) {
+    const status = options.errorResponse.versionNotFoundStatus;
+    if (!Number.isInteger(status) || status < 100 || status > 599) {
+      throw createInvalidConfigurationError(
+        "versionNotFoundStatus must be a valid HTTP status code (100-599)"
+      );
+    }
+  }
+  return {
+    extraction: {
+      sources: options.extraction?.sources ?? DEFAULT_CONFIG.extraction.sources,
+      header: {
+        name: options.extraction?.header?.name ?? DEFAULT_CONFIG.extraction.header.name
+      },
+      query: {
+        name: options.extraction?.query?.name ?? DEFAULT_CONFIG.extraction.query.name
+      },
+      path: {
+        pattern: options.extraction?.path?.pattern ?? DEFAULT_CONFIG.extraction.path.pattern
+      },
+      custom: options.extraction?.custom
+    },
+    errorResponse: {
+      missingVersionStatus: options.errorResponse?.missingVersionStatus ?? DEFAULT_CONFIG.errorResponse.missingVersionStatus,
+      versionNotFoundStatus: options.errorResponse?.versionNotFoundStatus ?? DEFAULT_CONFIG.errorResponse.versionNotFoundStatus,
+      missingVersionMessage: options.errorResponse?.missingVersionMessage ?? DEFAULT_CONFIG.errorResponse.missingVersionMessage,
+      versionNotFoundMessage: options.errorResponse?.versionNotFoundMessage ?? DEFAULT_CONFIG.errorResponse.versionNotFoundMessage,
+      includeRequestedVersion: options.errorResponse?.includeRequestedVersion ?? DEFAULT_CONFIG.errorResponse.includeRequestedVersion,
+      onError: options.errorResponse?.onError
+    },
+    fallbackStrategy: options.fallbackStrategy ?? DEFAULT_CONFIG.fallbackStrategy,
+    defaultHandler: options.defaultHandler ?? DEFAULT_CONFIG.defaultHandler,
+    validateHandlers: options.validateHandlers ?? DEFAULT_CONFIG.validateHandlers,
+    attachVersionInfo: options.attachVersionInfo ?? DEFAULT_CONFIG.attachVersionInfo,
+    requireVersion: options.requireVersion ?? DEFAULT_CONFIG.requireVersion
+  };
+}
+function freezeConfig(config) {
+  return Object.freeze({
+    ...config,
+    extraction: Object.freeze({
+      ...config.extraction,
+      sources: Object.freeze([...config.extraction.sources]),
+      header: Object.freeze({ ...config.extraction.header }),
+      query: Object.freeze({ ...config.extraction.query }),
+      path: Object.freeze({ ...config.extraction.path })
+    }),
+    errorResponse: Object.freeze({ ...config.errorResponse })
+  });
+}
+
+// src/version-extractor.ts
+function extractFromHeader(req, headerName) {
+  const value = req.headers[headerName.toLowerCase()];
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  if (Array.isArray(value) && value.length > 0 && value[0]) {
+    return value[0].trim();
+  }
+  return void 0;
+}
+function extractFromQuery(req, paramName) {
+  const value = req.query[paramName];
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  return void 0;
+}
+function extractFromPath(req, pattern) {
+  const path = req.path || req.url;
+  const isStatefulPattern = pattern.global || pattern.sticky;
+  if (isStatefulPattern) {
+    pattern.lastIndex = 0;
+  }
+  const match = pattern.exec(path);
+  if (isStatefulPattern) {
+    pattern.lastIndex = 0;
+  }
+  if (match?.[1]) {
+    return match[1].trim();
+  }
+  return void 0;
+}
+function extractFromRequest(req) {
+  if (typeof req.version === "string" && req.version.trim().length > 0) {
+    return req.version.trim();
+  }
+  return void 0;
+}
+function createVersionExtractor(config) {
+  const { sources, header, query, path, custom } = config.extraction;
+  return (req) => {
+    const requestVersion = extractFromRequest(req);
+    if (requestVersion) {
+      return { version: requestVersion, source: "custom" };
+    }
+    for (const source of sources) {
+      let version;
+      switch (source) {
+        case "header":
+          version = extractFromHeader(req, header.name);
+          break;
+        case "query":
+          version = extractFromQuery(req, query.name);
+          break;
+        case "path":
+          version = extractFromPath(req, path.pattern);
+          break;
+        case "custom":
+          version = custom?.(req);
+          break;
+      }
+      if (version) {
+        return { version, source };
+      }
+    }
+    return void 0;
+  };
+}
+
+// src/version-parser.ts
+var VERSION_REGEX = /^(\^|~)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+function getSpecifiedComponentCount(rawRange) {
+  const withoutPrefix = rawRange.replace(/^[\^~]/, "");
+  const count = withoutPrefix.split(".").length;
+  if (count <= 1) {
+    return 1;
+  }
+  if (count === 2) {
+    return 2;
+  }
+  return 3;
+}
+function parseVersion(version) {
+  const trimmed = version.trim();
+  const match = VERSION_REGEX.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const [, , majorStr, minorStr, patchStr] = match;
+  const major = parseInt(majorStr ?? "0", 10);
+  const minor = parseInt(minorStr ?? "0", 10);
+  const patch = parseInt(patchStr ?? "0", 10);
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+    return null;
+  }
+  if (major < 0 || minor < 0 || patch < 0) {
+    return null;
+  }
+  return {
+    major,
+    minor,
+    patch,
+    raw: trimmed
+  };
+}
+function parseVersionRange(range) {
+  const trimmed = range.trim();
+  const match = VERSION_REGEX.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const [, prefix, majorStr, minorStr, patchStr] = match;
+  const major = parseInt(majorStr ?? "0", 10);
+  const minor = parseInt(minorStr ?? "0", 10);
+  const patch = parseInt(patchStr ?? "0", 10);
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+    return null;
+  }
+  let type;
+  if (prefix === "^") {
+    type = "caret";
+  } else if (prefix === "~") {
+    type = "tilde";
+  } else {
+    type = "exact";
+  }
+  return {
+    type,
+    version: { major, minor, patch, raw: trimmed.replace(/^[\^~]/, "") },
+    raw: trimmed
+  };
+}
+function versionSatisfies(clientVersion, range) {
+  const { major: cMajor, minor: cMinor, patch: cPatch } = clientVersion;
+  const { major: rMajor, minor: rMinor, patch: rPatch } = range.version;
+  switch (range.type) {
+    case "caret": {
+      if (cMajor !== rMajor) {
+        return false;
+      }
+      if (rMajor > 0) {
+        if (cMinor < rMinor) {
+          return false;
+        }
+        if (cMinor === rMinor && cPatch < rPatch) {
+          return false;
+        }
+        return true;
+      }
+      if (rMinor > 0) {
+        return cMinor === rMinor && cPatch >= rPatch;
+      }
+      const componentCount = getSpecifiedComponentCount(range.raw);
+      if (componentCount === 1) {
+        return true;
+      }
+      if (componentCount === 2) {
+        return cMinor === 0;
+      }
+      return cMinor === 0 && cPatch === rPatch;
+    }
+    case "tilde": {
+      if (cMajor !== rMajor || cMinor !== rMinor) {
+        return false;
+      }
+      return cPatch >= rPatch;
+    }
+    case "exact": {
+      return cMajor === rMajor && cMinor === rMinor && cPatch === rPatch;
+    }
+  }
+}
+function compareVersions(a, b) {
+  if (a.major !== b.major) {
+    return a.major > b.major ? 1 : -1;
+  }
+  if (a.minor !== b.minor) {
+    return a.minor > b.minor ? 1 : -1;
+  }
+  if (a.patch !== b.patch) {
+    return a.patch > b.patch ? 1 : -1;
+  }
+  return 0;
+}
+function findLatestVersion(versions) {
+  if (versions.length === 0) {
+    return null;
+  }
+  let latest = null;
+  let latestRaw = "";
+  for (const version of versions) {
+    const range = parseVersionRange(version);
+    if (!range) {
+      continue;
+    }
+    if (!latest || compareVersions(range.version, latest) > 0) {
+      latest = range.version;
+      latestRaw = range.version.raw;
+    }
+  }
+  return latestRaw || null;
+}
+function isValidVersion(version) {
+  return parseVersion(version) !== null;
+}
+function isValidVersionRange(range) {
+  return parseVersionRange(range) !== null;
+}
+function normalizeVersion(version) {
+  const range = parseVersionRange(version);
+  if (!range) {
+    return null;
+  }
+  const { major, minor, patch } = range.version;
+  return `${major.toString()}.${minor.toString()}.${patch.toString()}`;
+}
+
+// src/handler-compiler.ts
+function calculatePriority(handler) {
+  const { range } = handler;
+  const { major, minor, patch } = range.version;
+  const versionValue = major * 1e6 + minor * 1e3 + patch;
+  switch (range.type) {
+    case "exact":
+      return 1e9 + versionValue;
+    case "tilde":
+      return 5e8 + versionValue;
+    case "caret":
+      return versionValue;
+  }
+}
+function compileHandlers(handlers, validate = true) {
+  const compiled = [];
+  for (const [key, handler] of Object.entries(handlers)) {
+    if (validate && typeof handler !== "function") {
+      throw createInvalidHandlerError(key, "handler must be a function");
+    }
+    const range = parseVersionRange(key);
+    if (!range) {
+      if (validate) {
+        throw createInvalidHandlerError(
+          key,
+          'invalid version format. Expected: "1.0.0", "^1.0", "~1.2", etc.'
+        );
+      }
+      continue;
+    }
+    const compiledHandler = {
+      key,
+      range,
+      handler,
+      priority: 0
+      // Will be calculated after
+    };
+    compiledHandler.priority = calculatePriority(compiledHandler);
+    compiled.push(compiledHandler);
+  }
+  compiled.sort((a, b) => b.priority - a.priority);
+  return compiled;
+}
+function findMatchingHandler(clientVersion, compiledHandlers) {
+  for (const handler of compiledHandlers) {
+    if (versionSatisfies(clientVersion, handler.range)) {
+      return handler;
+    }
+  }
+  return void 0;
+}
+function findLatestHandler(compiledHandlers) {
+  if (compiledHandlers.length === 0) {
+    return void 0;
+  }
+  let latest;
+  for (const handler of compiledHandlers) {
+    if (!latest || compareVersions(handler.range.version, latest.range.version) > 0) {
+      latest = handler;
+    }
+  }
+  return latest;
+}
+function getAvailableVersions(compiledHandlers) {
+  return compiledHandlers.map((h) => h.key);
+}
+
+// src/middleware.ts
+function sendErrorResponse(error, req, res, next, config) {
+  if (config.errorResponse.onError) {
+    const handled = config.errorResponse.onError(error, req, res, next);
+    if (handled === true) {
+      return;
+    }
+  }
+  const response = {
+    error: error.code,
+    message: error.message
+  };
+  if (config.errorResponse.includeRequestedVersion && error.requestedVersion) {
+    response["requestedVersion"] = error.requestedVersion;
+  }
+  if (error.availableVersions && error.availableVersions.length > 0) {
+    response["availableVersions"] = error.availableVersions;
+  }
+  res.status(error.statusCode).json(response);
+}
+function getVersionNotFoundMessage(version, config) {
+  const message = config.errorResponse.versionNotFoundMessage;
+  if (typeof message === "function") {
+    return message(version);
+  }
+  return message;
+}
+function getMissingVersionMessage(config) {
+  return config.errorResponse.missingVersionMessage;
+}
+function versioningMiddleware(handlers, options) {
+  if (Array.isArray(handlers)) {
+    throw createInvalidConfigurationError("'handlers' must be a non-null, non-array object");
+  }
+  const config = freezeConfig(resolveConfig(options));
+  const compiledHandlers = compileHandlers(handlers, config.validateHandlers);
+  if (compiledHandlers.length === 0) {
+    throw createInvalidConfigurationError(
+      "No valid handlers provided. At least one handler is required."
+    );
+  }
+  const extractVersion = createVersionExtractor(config);
+  const availableVersions = getAvailableVersions(compiledHandlers);
+  return (req, res, next) => {
+    const extraction = extractVersion(req);
+    if (!extraction) {
+      if (!config.requireVersion) {
+        handleFallback(
+          void 0,
+          void 0,
+          compiledHandlers,
+          config,
+          availableVersions,
+          req,
+          res,
+          next
+        );
+        return;
+      }
+      const error = createMissingVersionError(
+        config.errorResponse.missingVersionStatus,
+        getMissingVersionMessage(config)
+      );
+      sendErrorResponse(error, req, res, next, config);
+      return;
+    }
+    const { version: versionString, source } = extraction;
+    const clientVersion = parseVersion(versionString);
+    if (!clientVersion) {
+      const error = createInvalidVersionFormatError(versionString);
+      sendErrorResponse(error, req, res, next, config);
+      return;
+    }
+    const matchedHandler = findMatchingHandler(clientVersion, compiledHandlers);
+    if (matchedHandler) {
+      if (config.attachVersionInfo) {
+        req.versionInfo = {
+          requested: versionString,
+          matched: matchedHandler.key,
+          source
+        };
+      }
+      executeHandler(matchedHandler, req, res, next);
+      return;
+    }
+    handleFallback(
+      versionString,
+      source,
+      compiledHandlers,
+      config,
+      availableVersions,
+      req,
+      res,
+      next
+    );
+  };
+}
+function handleFallback(requestedVersion, requestedSource, compiledHandlers, config, availableVersions, req, res, next) {
+  switch (config.fallbackStrategy) {
+    case "none": {
+      const error = createVersionNotFoundError(
+        requestedVersion ?? "unknown",
+        availableVersions,
+        config.errorResponse.versionNotFoundStatus
+      );
+      error.message = getVersionNotFoundMessage(requestedVersion ?? "unknown", config);
+      sendErrorResponse(error, req, res, next, config);
+      break;
+    }
+    case "latest": {
+      const latestHandler = findLatestHandler(compiledHandlers);
+      if (latestHandler) {
+        if (config.attachVersionInfo && requestedVersion) {
+          req.versionInfo = {
+            requested: requestedVersion,
+            matched: latestHandler.key,
+            source: requestedSource ?? "custom"
+          };
+        }
+        executeHandler(latestHandler, req, res, next);
+      } else {
+        const error = createVersionNotFoundError(
+          requestedVersion ?? "unknown",
+          availableVersions,
+          config.errorResponse.versionNotFoundStatus
+        );
+        sendErrorResponse(error, req, res, next, config);
+      }
+      break;
+    }
+    case "default": {
+      if (config.defaultHandler) {
+        if (config.attachVersionInfo && requestedVersion) {
+          req.versionInfo = {
+            requested: requestedVersion,
+            matched: "default",
+            source: requestedSource ?? "custom"
+          };
+        }
+        executeRequestHandler(config.defaultHandler, req, res, next);
+      } else {
+        const latestHandler = findLatestHandler(compiledHandlers);
+        if (latestHandler) {
+          if (config.attachVersionInfo && requestedVersion) {
+            req.versionInfo = {
+              requested: requestedVersion,
+              matched: latestHandler.key,
+              source: requestedSource ?? "custom"
+            };
+          }
+          executeHandler(latestHandler, req, res, next);
+        } else {
+          const error = createVersionNotFoundError(
+            requestedVersion ?? "unknown",
+            availableVersions,
+            config.errorResponse.versionNotFoundStatus
+          );
+          sendErrorResponse(error, req, res, next, config);
+        }
+      }
+      break;
+    }
+    default: {
+      const error = createInvalidConfigurationError(
+        "Unsupported fallback strategy. Valid strategies: latest, none, default"
+      );
+      sendErrorResponse(error, req, res, next, config);
+      break;
+    }
+  }
+}
+function executeHandler(handler, req, res, next) {
+  try {
+    const result = handler.handler(req, res, next);
+    if (result instanceof Promise) {
+      result.catch((error) => {
+        next(error);
+      });
+    }
+  } catch (error) {
+    next(error);
+  }
+}
+function executeRequestHandler(handler, req, res, next) {
+  try {
+    const result = handler(req, res, next);
+    if (result instanceof Promise) {
+      void result.catch((error) => {
+        next(error);
+      });
+    }
+  } catch (error) {
+    next(error);
+  }
+}
+
+exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+exports.VersioningError = VersioningError;
+exports.compareVersions = compareVersions;
+exports.createInvalidConfigurationError = createInvalidConfigurationError;
+exports.createInvalidHandlerError = createInvalidHandlerError;
+exports.createInvalidVersionFormatError = createInvalidVersionFormatError;
+exports.createMissingVersionError = createMissingVersionError;
+exports.createVersionNotFoundError = createVersionNotFoundError;
+exports.findLatestVersion = findLatestVersion;
+exports.hasErrorCode = hasErrorCode;
+exports.isValidVersion = isValidVersion;
+exports.isValidVersionRange = isValidVersionRange;
+exports.isVersioningError = isVersioningError;
+exports.normalizeVersion = normalizeVersion;
+exports.parseVersion = parseVersion;
+exports.parseVersionRange = parseVersionRange;
+exports.versionSatisfies = versionSatisfies;
+exports.versioningMiddleware = versioningMiddleware;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map