@withwiz/toolkit 0.1.0

package/dist/chunk-Y3OTJH2S.js

@@ -0,0 +1,473 @@
+// src/constants/error-codes.ts
+var HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503
+};
+var ERROR_CODES = {
+  // ============================================
+  // Validation Related (400xx)
+  // ============================================
+  VALIDATION_ERROR: {
+    code: 40001,
+    key: "VALIDATION_ERROR",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Invalid input values."
+  },
+  BAD_REQUEST: {
+    code: 40002,
+    key: "BAD_REQUEST",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Invalid request."
+  },
+  INVALID_INPUT: {
+    code: 40003,
+    key: "INVALID_INPUT",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Invalid input."
+  },
+  MISSING_REQUIRED_FIELD: {
+    code: 40004,
+    key: "MISSING_REQUIRED_FIELD",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Required field is missing."
+  },
+  INVALID_URL_FORMAT: {
+    code: 40005,
+    key: "INVALID_URL_FORMAT",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Invalid URL format."
+  },
+  INVALID_EMAIL_FORMAT: {
+    code: 40006,
+    key: "INVALID_EMAIL_FORMAT",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Invalid email format."
+  },
+  PASSWORD_TOO_WEAK: {
+    code: 40007,
+    key: "PASSWORD_TOO_WEAK",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Password is too weak."
+  },
+  INVALID_ALIAS_FORMAT: {
+    code: 40008,
+    key: "INVALID_ALIAS_FORMAT",
+    status: HTTP_STATUS.BAD_REQUEST,
+    message: "Alias can only contain English letters, numbers, -, and _."
+  },
+  // ============================================
+  // Authentication Related (401xx)
+  // ============================================
+  UNAUTHORIZED: {
+    code: 40101,
+    key: "UNAUTHORIZED",
+    status: HTTP_STATUS.UNAUTHORIZED,
+    message: "Authentication required."
+  },
+  INVALID_TOKEN: {
+    code: 40102,
+    key: "INVALID_TOKEN",
+    status: HTTP_STATUS.UNAUTHORIZED,
+    message: "Invalid token."
+  },
+  TOKEN_EXPIRED: {
+    code: 40103,
+    key: "TOKEN_EXPIRED",
+    status: HTTP_STATUS.UNAUTHORIZED,
+    message: "Token has expired."
+  },
+  INVALID_CREDENTIALS: {
+    code: 40106,
+    key: "INVALID_CREDENTIALS",
+    status: HTTP_STATUS.UNAUTHORIZED,
+    message: "Invalid email or password."
+  },
+  SESSION_EXPIRED: {
+    code: 40107,
+    key: "SESSION_EXPIRED",
+    status: HTTP_STATUS.UNAUTHORIZED,
+    message: "Session has expired."
+  },
+  // ============================================
+  // Permissions Related (403xx - 01~09)
+  // ============================================
+  FORBIDDEN: {
+    code: 40304,
+    key: "FORBIDDEN",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Access denied."
+  },
+  EMAIL_NOT_VERIFIED: {
+    code: 40305,
+    key: "EMAIL_NOT_VERIFIED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Email verification required."
+  },
+  ACCOUNT_DISABLED: {
+    code: 40308,
+    key: "ACCOUNT_DISABLED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Account is disabled."
+  },
+  ACCOUNT_LOCKED: {
+    code: 40309,
+    key: "ACCOUNT_LOCKED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Account is locked."
+  },
+  // ============================================
+  // Resource Not Found (404xx)
+  // ============================================
+  NOT_FOUND: {
+    code: 40401,
+    key: "NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "Requested resource not found."
+  },
+  USER_NOT_FOUND: {
+    code: 40402,
+    key: "USER_NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "User not found."
+  },
+  LINK_NOT_FOUND: {
+    code: 40403,
+    key: "LINK_NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "Link not found."
+  },
+  TAG_NOT_FOUND: {
+    code: 40408,
+    key: "TAG_NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "Tag not found."
+  },
+  FAVORITE_NOT_FOUND: {
+    code: 40409,
+    key: "FAVORITE_NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "Favorite not found."
+  },
+  GROUP_NOT_FOUND: {
+    code: 40410,
+    key: "GROUP_NOT_FOUND",
+    status: HTTP_STATUS.NOT_FOUND,
+    message: "Group not found."
+  },
+  // ============================================
+  // Conflict (409xx)
+  // ============================================
+  CONFLICT: {
+    code: 40904,
+    key: "CONFLICT",
+    status: HTTP_STATUS.CONFLICT,
+    message: "Resource conflict occurred."
+  },
+  DUPLICATE_RESOURCE: {
+    code: 40905,
+    key: "DUPLICATE_RESOURCE",
+    status: HTTP_STATUS.CONFLICT,
+    message: "Resource already exists."
+  },
+  EMAIL_ALREADY_EXISTS: {
+    code: 40906,
+    key: "EMAIL_ALREADY_EXISTS",
+    status: HTTP_STATUS.CONFLICT,
+    message: "Email is already registered."
+  },
+  ALIAS_ALREADY_EXISTS: {
+    code: 40907,
+    key: "ALIAS_ALREADY_EXISTS",
+    status: HTTP_STATUS.CONFLICT,
+    message: "Alias is already in use."
+  },
+  // ============================================
+  // Business Logic (422xx)
+  // ============================================
+  BUSINESS_RULE_VIOLATION: {
+    code: 42201,
+    key: "BUSINESS_RULE_VIOLATION",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Unable to process the request."
+  },
+  INVALID_OPERATION: {
+    code: 42202,
+    key: "INVALID_OPERATION",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Invalid operation."
+  },
+  QUOTA_EXCEEDED: {
+    code: 42203,
+    key: "QUOTA_EXCEEDED",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Usage quota exceeded."
+  },
+  LINK_EXPIRED: {
+    code: 42204,
+    key: "LINK_EXPIRED",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Link has expired."
+  },
+  LINK_INACTIVE: {
+    code: 42205,
+    key: "LINK_INACTIVE",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Link is inactive."
+  },
+  LINK_PASSWORD_REQUIRED: {
+    code: 42206,
+    key: "LINK_PASSWORD_REQUIRED",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Link password is required."
+  },
+  LINK_PASSWORD_INCORRECT: {
+    code: 42207,
+    key: "LINK_PASSWORD_INCORRECT",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Incorrect link password."
+  },
+  RESERVED_WORD_USED: {
+    code: 42208,
+    key: "RESERVED_WORD_USED",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Reserved words cannot be used as aliases."
+  },
+  ALREADY_FAVORITED: {
+    code: 42209,
+    key: "ALREADY_FAVORITED",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Already added to favorites."
+  },
+  CANNOT_DELETE_OWN_ACCOUNT: {
+    code: 42210,
+    key: "CANNOT_DELETE_OWN_ACCOUNT",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "You cannot delete your own account."
+  },
+  FILE_TOO_LARGE: {
+    code: 42211,
+    key: "FILE_TOO_LARGE",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "File size exceeds the limit."
+  },
+  UNSUPPORTED_FILE_TYPE: {
+    code: 42212,
+    key: "UNSUPPORTED_FILE_TYPE",
+    status: HTTP_STATUS.UNPROCESSABLE_ENTITY,
+    message: "Unsupported file type."
+  },
+  // ============================================
+  // Rate Limiting (429xx)
+  // ============================================
+  RATE_LIMIT_EXCEEDED: {
+    code: 42901,
+    key: "RATE_LIMIT_EXCEEDED",
+    status: HTTP_STATUS.TOO_MANY_REQUESTS,
+    message: "Too many requests. Please try again later."
+  },
+  DAILY_LIMIT_EXCEEDED: {
+    code: 42902,
+    key: "DAILY_LIMIT_EXCEEDED",
+    status: HTTP_STATUS.TOO_MANY_REQUESTS,
+    message: "Daily limit exceeded."
+  },
+  API_QUOTA_EXCEEDED: {
+    code: 42903,
+    key: "API_QUOTA_EXCEEDED",
+    status: HTTP_STATUS.TOO_MANY_REQUESTS,
+    message: "API quota exceeded."
+  },
+  // ============================================
+  // Server Errors (500xx)
+  // ============================================
+  INTERNAL_SERVER_ERROR: {
+    code: 50001,
+    key: "INTERNAL_SERVER_ERROR",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "Internal server error occurred."
+  },
+  SERVER_ERROR: {
+    code: 50002,
+    key: "SERVER_ERROR",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "A temporary error occurred."
+  },
+  DATABASE_ERROR: {
+    code: 50003,
+    key: "DATABASE_ERROR",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "An error occurred during data processing."
+  },
+  EMAIL_SEND_FAILED: {
+    code: 50006,
+    key: "EMAIL_SEND_FAILED",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "Failed to send email."
+  },
+  CACHE_ERROR: {
+    code: 50007,
+    key: "CACHE_ERROR",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "An error occurred during cache processing."
+  },
+  FILE_UPLOAD_FAILED: {
+    code: 50008,
+    key: "FILE_UPLOAD_FAILED",
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    message: "Failed to upload file."
+  },
+  // ============================================
+  // Service Unavailable (503xx)
+  // ============================================
+  EXTERNAL_SERVICE_ERROR: {
+    code: 50304,
+    key: "EXTERNAL_SERVICE_ERROR",
+    status: HTTP_STATUS.SERVICE_UNAVAILABLE,
+    message: "Unable to connect to external service."
+  },
+  SERVICE_UNAVAILABLE: {
+    code: 50305,
+    key: "SERVICE_UNAVAILABLE",
+    status: HTTP_STATUS.SERVICE_UNAVAILABLE,
+    message: "Service is temporarily unavailable."
+  },
+  // ============================================
+  // Security Related (403xx - 71~79)
+  // ============================================
+  ACCESS_BLOCKED: {
+    code: 40371,
+    key: "ACCESS_BLOCKED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Blocked due to security policy."
+  },
+  SECURITY_VALIDATION_FAILED: {
+    code: 40372,
+    key: "SECURITY_VALIDATION_FAILED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Security validation failed."
+  },
+  BLOCKED_URL: {
+    code: 40373,
+    key: "BLOCKED_URL",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Blocked URL."
+  },
+  SUSPICIOUS_ACTIVITY: {
+    code: 40374,
+    key: "SUSPICIOUS_ACTIVITY",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "Suspicious activity detected."
+  },
+  IP_BLOCKED: {
+    code: 40375,
+    key: "IP_BLOCKED",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "IP is blocked."
+  },
+  CORS_VIOLATION: {
+    code: 40376,
+    key: "CORS_VIOLATION",
+    status: HTTP_STATUS.FORBIDDEN,
+    message: "CORS policy violation."
+  }
+};
+function getErrorInfo(codeKey) {
+  return ERROR_CODES[codeKey];
+}
+function getErrorByCode(code) {
+  const entry = Object.values(ERROR_CODES).find((e) => e.code === code);
+  return entry || null;
+}
+function getHttpStatus(code) {
+  return Math.floor(code / 100);
+}
+function getErrorCategory(code) {
+  const httpStatus = getHttpStatus(code);
+  const subCode = code % 100;
+  switch (httpStatus) {
+    case 400:
+      return "validation";
+    case 401:
+      return "auth";
+    case 403:
+      return subCode >= 71 ? "security" : "permission";
+    case 404:
+      return "resource";
+    case 409:
+      return "conflict";
+    case 422:
+      return "business";
+    case 429:
+      return "rateLimit";
+    case 500:
+    case 503:
+      return "server";
+    default:
+      return "unknown";
+  }
+}
+function getDefaultErrorMessage(status) {
+  switch (status) {
+    case 400:
+      return "Invalid request.";
+    case 401:
+      return "Authentication required.";
+    case 403:
+      return "Access denied.";
+    case 404:
+      return "Requested resource not found.";
+    case 409:
+      return "Resource conflict occurred.";
+    case 422:
+      return "Unable to process request.";
+    case 429:
+      return "Too many requests.";
+    case 500:
+      return "Server error occurred.";
+    case 503:
+      return "Service temporarily unavailable.";
+    default:
+      return "An error occurred.";
+  }
+}
+function getLogLevel(status) {
+  if (status < 400) return "info";
+  if (status < 500) return "warn";
+  return "error";
+}
+function getAllErrorCodes() {
+  return Object.values(ERROR_CODES);
+}
+function getErrorCodesByCategory(category) {
+  return Object.values(ERROR_CODES).filter(
+    (e) => getErrorCategory(e.code) === category
+  );
+}
+function formatErrorMessage(code, customMessage) {
+  const errorInfo = getErrorByCode(code);
+  return customMessage || (errorInfo == null ? void 0 : errorInfo.message) || getDefaultErrorMessage(getHttpStatus(code));
+}
+
+export {
+  HTTP_STATUS,
+  ERROR_CODES,
+  getErrorInfo,
+  getErrorByCode,
+  getHttpStatus,
+  getErrorCategory,
+  getDefaultErrorMessage,
+  getLogLevel,
+  getAllErrorCodes,
+  getErrorCodesByCategory,
+  formatErrorMessage
+};

package/dist/chunk-YBSHN67U.js

@@ -0,0 +1,161 @@
+import {
+  getCacheManager,
+  getEffectiveCacheBackend
+} from "./chunk-AIHQBQ3E.js";
+import {
+  getCacheConfig,
+  getCacheTTL
+} from "./chunk-TXGNSECL.js";
+import {
+  isCacheEnabled
+} from "./chunk-I47QEDTX.js";
+import {
+  logger
+} from "./chunk-EZR55KV2.js";
+
+// src/cache/cache-wrapper.ts
+function getCacheBackendLabel() {
+  const backend = getEffectiveCacheBackend();
+  switch (backend) {
+    case "redis":
+      return "R";
+    case "memory":
+      return "M";
+    case "hybrid":
+      return "H";
+    default:
+      return "N";
+  }
+}
+var NULL_VALUE_WRAPPER = { __nullValue__: true };
+function isNullValueWrapper(value) {
+  return typeof value === "object" && value !== null && "__nullValue__" in value && value.__nullValue__ === true;
+}
+function wrapNullValue(value) {
+  return value === null ? NULL_VALUE_WRAPPER : value;
+}
+function unwrapNullValue(value) {
+  return isNullValueWrapper(value) ? null : value;
+}
+async function withCache(key, fetchFunction, options = {}) {
+  const startTime = Date.now();
+  const { ttl, prefix: inputPrefix } = options;
+  let cacheManagerPrefix;
+  let actualKey;
+  let fullKey;
+  if (inputPrefix !== void 0) {
+    cacheManagerPrefix = inputPrefix;
+    actualKey = key;
+    fullKey = `${inputPrefix}:${key}`;
+  } else {
+    const colonIndex = key.indexOf(":");
+    if (colonIndex > 0) {
+      cacheManagerPrefix = key.substring(0, colonIndex);
+      actualKey = key.substring(colonIndex + 1);
+      fullKey = key;
+    } else {
+      cacheManagerPrefix = "default";
+      actualKey = key;
+      fullKey = `default:${key}`;
+    }
+  }
+  const prefix = cacheManagerPrefix;
+  const cacheConfig = getCacheConfig[prefix];
+  const finalTTL = ttl || ((cacheConfig == null ? void 0 : cacheConfig.duration()) || getCacheTTL.default());
+  if (cacheConfig && !cacheConfig.enabled()) {
+    logger.debug(`withCache skipped due to cache disabled: ${fullKey}`, {
+      key: actualKey,
+      prefix,
+      fullKey,
+      cacheEnabled: cacheConfig.enabled()
+    });
+    return await fetchFunction();
+  }
+  if (!isCacheEnabled()) {
+    logger.debug(`withCache skipped due to global cache disabled: ${fullKey}`, {
+      key: actualKey,
+      prefix,
+      fullKey,
+      cacheEnabled: isCacheEnabled()
+    });
+    return await fetchFunction();
+  }
+  const cacheManager = getCacheManager(prefix);
+  logger.debug(`withCache started: ${fullKey}`, {
+    key: actualKey,
+    prefix,
+    fullKey,
+    ttl: `${finalTTL}s`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  try {
+    const cachedValue = await cacheManager.get(actualKey);
+    if (cachedValue !== null) {
+      const totalTime2 = Date.now() - startTime;
+      const backendLabel2 = getCacheBackendLabel();
+      const isNullCached = isNullValueWrapper(cachedValue);
+      const unwrappedValue = unwrapNullValue(cachedValue);
+      logger.info(`[${backendLabel2}] HIT ${fullKey} (${totalTime2}ms)${isNullCached ? " null" : ""}`);
+      return unwrappedValue;
+    }
+    logger.debug(`withCache [${getCacheBackendLabel()}] cache miss: ${fullKey}`, {
+      key: actualKey,
+      prefix,
+      fullKey,
+      ttl: `${finalTTL}s`
+    });
+    const freshValue = await fetchFunction();
+    const fetchTime = Date.now() - startTime;
+    const valueToStore = wrapNullValue(freshValue);
+    await cacheManager.set(actualKey, valueToStore, finalTTL);
+    const totalTime = Date.now() - startTime;
+    const isNullValue = freshValue === null;
+    const backendLabel = getCacheBackendLabel();
+    const valueSize = JSON.stringify(valueToStore).length;
+    logger.info(`[${backendLabel}] SET ${fullKey} (${fetchTime}ms, ${valueSize}B, ttl=${finalTTL}s)${isNullValue ? " null" : ""}`);
+    return freshValue;
+  } catch (error) {
+    const totalTime = Date.now() - startTime;
+    const errorMessage = error instanceof Error ? error.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958";
+    logger.error(`withCache execution failed: ${fullKey}`, {
+      key: actualKey,
+      prefix,
+      fullKey,
+      error: errorMessage,
+      totalTime: `${totalTime}ms`,
+      ttl: `${finalTTL}s`,
+      stack: error instanceof Error ? error.stack : void 0
+    });
+    logger.warn(`withCache error occurred, executing original function: ${fullKey}`, {
+      key: actualKey,
+      prefix,
+      fullKey,
+      error: errorMessage
+    });
+    return await fetchFunction();
+  }
+}
+var cacheMetrics = {
+  hits: 0,
+  misses: 0,
+  errors: 0,
+  totalRequests: 0,
+  averageResponseTime: 0,
+  get hitRate() {
+    const total = this.hits + this.misses;
+    return total > 0 ? this.hits / total * 100 : 0;
+  },
+  reset() {
+    this.hits = 0;
+    this.misses = 0;
+    this.errors = 0;
+    this.totalRequests = 0;
+    this.averageResponseTime = 0;
+  }
+};
+
+export {
+  getCacheBackendLabel,
+  withCache,
+  cacheMetrics
+};