@wheeparam/library 0.0.1

package/dist/client/index.d.cts

@@ -0,0 +1,179 @@
+import { AxiosInstance } from 'axios';
+
+/**
+ * @packageDocumentation
+ * Axios Client (Client-only)
+ *
+ * 공통 요구사항:
+ * - accessToken이 있으면 Authorization 헤더에 첨부
+ * - 401 발생 시 refreshToken으로 토큰 재발급을 시도하고, 원래 요청을 재시도
+ * - refresh 중복 호출 방지(큐 방식)
+ *
+ * 단순화 정책:
+ * - refresh URL만 옵션으로 받아 내부에서 fetch로 토큰 재발급을 수행한다.
+ * - 토큰 저장은 "localStorage" 또는 "cookie" 2가지 모드만 지원한다.
+ *
+ * ⚠️ 이 모듈은 브라우저 전용이다(window/localStorage 사용 가능).
+ * Next.js에서는 반드시 Client Component 또는 클라이언트 전용 모듈에서 import 해야 한다.
+ */
+
+/**
+ * 토큰 저장 방식
+ * - localStorage: accessToken/refreshToken을 localStorage에 저장
+ * - cookie: 토큰을 쿠키 기반으로 운용(클라 저장 최소화)
+ */
+type TokenStorageMode = "localStorage" | "cookie";
+/**
+ * refresh 요청/응답 타입
+ */
+type RefreshRequestBody = {
+    refreshToken: string;
+};
+type RefreshResponseBody = {
+    accessToken: string;
+    refreshToken: string;
+};
+/**
+ * createAxiosClient 옵션
+ */
+type CreateAxiosClientOptions = {
+    /**
+     * axios baseURL (선택)
+     */
+    baseURL?: string;
+    /**
+     * 요청 타임아웃(ms)
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * 쿠키 전송 여부
+     * - cookie 모드에서는 거의 필수
+     * @default true
+     */
+    withCredentials?: boolean;
+    /**
+     * 토큰 재발급(Refresh) API URL
+     * @example "/api/authorize/token"
+     */
+    refreshUrl: string;
+    /**
+     * 토큰 저장 방식
+     * @default "localStorage"
+     */
+    storage?: TokenStorageMode;
+    /**
+     * localStorage 키 이름(선택)
+     * @default { accessTokenKey: "accessToken", refreshTokenKey: "refreshToken" }
+     */
+    storageKeys?: {
+        accessTokenKey?: string;
+        refreshTokenKey?: string;
+    };
+    /**
+     * 로그인 상태 변화 콜백(선택)
+     * - 프로젝트의 auth context/ref/store 업데이트에 사용
+     */
+    onAuthStateChange?: (status: "authenticated" | "unauthenticated") => void;
+    /**
+     * 일반 에러 표시 콜백(선택)
+     * - Swal/toast 등 프로젝트 스타일로 구현
+     */
+    onError?: (message: string, error: unknown) => void;
+    /**
+     * API 에러 메시지 추출 커스터마이즈(선택)
+     * - null 반환 시 내부 기본 로직 사용
+     */
+    getErrorMessage?: (error: unknown) => string | null;
+};
+/**
+ * createAxiosClient 반환값
+ */
+type AxiosClient = {
+    /**
+     * 구성 완료된 axios instance
+     */
+    axios: AxiosInstance;
+    /**
+     * 토큰 설정(로그인 성공 등)
+     * - localStorage 모드: localStorage에 저장
+     * - cookie 모드: 기본 구현은 refreshToken만 저장(필요 시)
+     */
+    setToken: (data: Partial<RefreshResponseBody>) => void;
+    /**
+     * 토큰 조회
+     */
+    getToken: () => {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    /**
+     * 토큰 제거(로그아웃)
+     */
+    clearToken: () => void;
+};
+/**
+ * 공용 axios 클라이언트를 생성한다.
+ *
+ * 토큰 자동 첨부 + 401 발생 시 refresh 후 재요청을 처리한다.
+ *
+ * @example 기본 사용법 (Next.js Client Component)
+ * ```ts
+ * "use client";
+ *
+ * import Swal from "sweetalert2";
+ * import nl2br from "@/utils/common";
+ * import { authContextRef } from "@/components/providers/auth-provider";
+ * import { createAxiosClient } from "@your-scope/toolkit/client";
+ *
+ * export const { axios, setToken, clearToken, getToken } = createAxiosClient({
+ *   refreshUrl: "/api/authorize/token",
+ *   storage: "localStorage",
+ *
+ *   onAuthStateChange: (status) => {
+ *     authContextRef.setLoginStatus?.(status);
+ *   },
+ *
+ *   onError: (message) => {
+ *     Swal.fire({
+ *       title: "오류 발생",
+ *       html: nl2br(message),
+ *       backdrop: false,
+ *       confirmButtonText: "확인",
+ *     });
+ *   },
+ * });
+ *
+ * export default axios;
+ * ```
+ *
+ * @example 로그인 성공 후 토큰 저장
+ * ```ts
+ * import { setToken } from "@/lib/axios";
+ *
+ * async function login(id: string, pw: string) {
+ *   const res = await fetch("/api/login", {
+ *     method: "POST",
+ *     body: JSON.stringify({ id, pw })
+ *   }).then(r => r.json());
+ *
+ *   setToken({
+ *     accessToken: res.accessToken,
+ *     refreshToken: res.refreshToken
+ *   });
+ * }
+ * ```
+ *
+ * @example 로그아웃 처리
+ * ```ts
+ * import { clearToken } from "@/lib/axios";
+ *
+ * function logout() {
+ *   clearToken();
+ *   location.href = "/login";
+ * }
+ * ```
+ */
+declare function createAxiosClient(options: CreateAxiosClientOptions): AxiosClient;
+
+export { type AxiosClient, type CreateAxiosClientOptions, type RefreshRequestBody, type RefreshResponseBody, type TokenStorageMode, createAxiosClient };

package/dist/client/index.d.ts

@@ -0,0 +1,179 @@
+import { AxiosInstance } from 'axios';
+
+/**
+ * @packageDocumentation
+ * Axios Client (Client-only)
+ *
+ * 공통 요구사항:
+ * - accessToken이 있으면 Authorization 헤더에 첨부
+ * - 401 발생 시 refreshToken으로 토큰 재발급을 시도하고, 원래 요청을 재시도
+ * - refresh 중복 호출 방지(큐 방식)
+ *
+ * 단순화 정책:
+ * - refresh URL만 옵션으로 받아 내부에서 fetch로 토큰 재발급을 수행한다.
+ * - 토큰 저장은 "localStorage" 또는 "cookie" 2가지 모드만 지원한다.
+ *
+ * ⚠️ 이 모듈은 브라우저 전용이다(window/localStorage 사용 가능).
+ * Next.js에서는 반드시 Client Component 또는 클라이언트 전용 모듈에서 import 해야 한다.
+ */
+
+/**
+ * 토큰 저장 방식
+ * - localStorage: accessToken/refreshToken을 localStorage에 저장
+ * - cookie: 토큰을 쿠키 기반으로 운용(클라 저장 최소화)
+ */
+type TokenStorageMode = "localStorage" | "cookie";
+/**
+ * refresh 요청/응답 타입
+ */
+type RefreshRequestBody = {
+    refreshToken: string;
+};
+type RefreshResponseBody = {
+    accessToken: string;
+    refreshToken: string;
+};
+/**
+ * createAxiosClient 옵션
+ */
+type CreateAxiosClientOptions = {
+    /**
+     * axios baseURL (선택)
+     */
+    baseURL?: string;
+    /**
+     * 요청 타임아웃(ms)
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * 쿠키 전송 여부
+     * - cookie 모드에서는 거의 필수
+     * @default true
+     */
+    withCredentials?: boolean;
+    /**
+     * 토큰 재발급(Refresh) API URL
+     * @example "/api/authorize/token"
+     */
+    refreshUrl: string;
+    /**
+     * 토큰 저장 방식
+     * @default "localStorage"
+     */
+    storage?: TokenStorageMode;
+    /**
+     * localStorage 키 이름(선택)
+     * @default { accessTokenKey: "accessToken", refreshTokenKey: "refreshToken" }
+     */
+    storageKeys?: {
+        accessTokenKey?: string;
+        refreshTokenKey?: string;
+    };
+    /**
+     * 로그인 상태 변화 콜백(선택)
+     * - 프로젝트의 auth context/ref/store 업데이트에 사용
+     */
+    onAuthStateChange?: (status: "authenticated" | "unauthenticated") => void;
+    /**
+     * 일반 에러 표시 콜백(선택)
+     * - Swal/toast 등 프로젝트 스타일로 구현
+     */
+    onError?: (message: string, error: unknown) => void;
+    /**
+     * API 에러 메시지 추출 커스터마이즈(선택)
+     * - null 반환 시 내부 기본 로직 사용
+     */
+    getErrorMessage?: (error: unknown) => string | null;
+};
+/**
+ * createAxiosClient 반환값
+ */
+type AxiosClient = {
+    /**
+     * 구성 완료된 axios instance
+     */
+    axios: AxiosInstance;
+    /**
+     * 토큰 설정(로그인 성공 등)
+     * - localStorage 모드: localStorage에 저장
+     * - cookie 모드: 기본 구현은 refreshToken만 저장(필요 시)
+     */
+    setToken: (data: Partial<RefreshResponseBody>) => void;
+    /**
+     * 토큰 조회
+     */
+    getToken: () => {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    /**
+     * 토큰 제거(로그아웃)
+     */
+    clearToken: () => void;
+};
+/**
+ * 공용 axios 클라이언트를 생성한다.
+ *
+ * 토큰 자동 첨부 + 401 발생 시 refresh 후 재요청을 처리한다.
+ *
+ * @example 기본 사용법 (Next.js Client Component)
+ * ```ts
+ * "use client";
+ *
+ * import Swal from "sweetalert2";
+ * import nl2br from "@/utils/common";
+ * import { authContextRef } from "@/components/providers/auth-provider";
+ * import { createAxiosClient } from "@your-scope/toolkit/client";
+ *
+ * export const { axios, setToken, clearToken, getToken } = createAxiosClient({
+ *   refreshUrl: "/api/authorize/token",
+ *   storage: "localStorage",
+ *
+ *   onAuthStateChange: (status) => {
+ *     authContextRef.setLoginStatus?.(status);
+ *   },
+ *
+ *   onError: (message) => {
+ *     Swal.fire({
+ *       title: "오류 발생",
+ *       html: nl2br(message),
+ *       backdrop: false,
+ *       confirmButtonText: "확인",
+ *     });
+ *   },
+ * });
+ *
+ * export default axios;
+ * ```
+ *
+ * @example 로그인 성공 후 토큰 저장
+ * ```ts
+ * import { setToken } from "@/lib/axios";
+ *
+ * async function login(id: string, pw: string) {
+ *   const res = await fetch("/api/login", {
+ *     method: "POST",
+ *     body: JSON.stringify({ id, pw })
+ *   }).then(r => r.json());
+ *
+ *   setToken({
+ *     accessToken: res.accessToken,
+ *     refreshToken: res.refreshToken
+ *   });
+ * }
+ * ```
+ *
+ * @example 로그아웃 처리
+ * ```ts
+ * import { clearToken } from "@/lib/axios";
+ *
+ * function logout() {
+ *   clearToken();
+ *   location.href = "/login";
+ * }
+ * ```
+ */
+declare function createAxiosClient(options: CreateAxiosClientOptions): AxiosClient;
+
+export { type AxiosClient, type CreateAxiosClientOptions, type RefreshRequestBody, type RefreshResponseBody, type TokenStorageMode, createAxiosClient };

package/dist/client/index.js

@@ -0,0 +1,168 @@
+// src/client/axios.ts
+import axios from "axios";
+function createLocalStorageTokenAccess(keys) {
+  const accessTokenKey = keys?.accessTokenKey ?? "accessToken";
+  const refreshTokenKey = keys?.refreshTokenKey ?? "refreshToken";
+  return {
+    get() {
+      return {
+        accessToken: window.localStorage.getItem(accessTokenKey),
+        refreshToken: window.localStorage.getItem(refreshTokenKey)
+      };
+    },
+    set(data) {
+      if (data.accessToken !== void 0) {
+        window.localStorage.setItem(accessTokenKey, data.accessToken ?? "");
+      }
+      if (data.refreshToken !== void 0) {
+        window.localStorage.setItem(refreshTokenKey, data.refreshToken ?? "");
+      }
+    },
+    clear() {
+      window.localStorage.removeItem(accessTokenKey);
+      window.localStorage.removeItem(refreshTokenKey);
+    }
+  };
+}
+function createCookieModeTokenAccess(keys) {
+  const refreshTokenKey = keys?.refreshTokenKey ?? "refreshToken";
+  return {
+    get() {
+      return {
+        accessToken: null,
+        // 쿠키 기반이면 JS에서 accessToken을 직접 읽지 않는 전제를 둔다.
+        refreshToken: window.localStorage.getItem(refreshTokenKey)
+      };
+    },
+    set(data) {
+      if (data.refreshToken !== void 0) {
+        window.localStorage.setItem(refreshTokenKey, data.refreshToken ?? "");
+      }
+    },
+    clear() {
+      window.localStorage.removeItem(refreshTokenKey);
+    }
+  };
+}
+function createAxiosClient(options) {
+  const {
+    baseURL,
+    timeout = 1e4,
+    withCredentials = true,
+    refreshUrl,
+    storage = "localStorage",
+    storageKeys,
+    onAuthStateChange,
+    onError,
+    getErrorMessage
+  } = options;
+  const instance = axios.create({ baseURL, timeout, withCredentials });
+  const tokenAccess = storage === "localStorage" ? createLocalStorageTokenAccess(storageKeys) : createCookieModeTokenAccess({ refreshTokenKey: storageKeys?.refreshTokenKey });
+  let isRefreshing = false;
+  let subscribers = [];
+  const notifySubscribers = (token) => {
+    subscribers.forEach((cb) => cb(token));
+    subscribers = [];
+  };
+  const clearAuth = () => {
+    tokenAccess.clear();
+    onAuthStateChange?.("unauthenticated");
+  };
+  const requestRefresh = async (refreshToken) => {
+    const res = await fetch(refreshUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken }),
+      credentials: withCredentials ? "include" : "same-origin"
+    });
+    if (!res.ok) {
+      throw new Error("Token refresh failed");
+    }
+    return await res.json();
+  };
+  instance.interceptors.request.use(
+    (config) => {
+      const { accessToken } = tokenAccess.get();
+      if (accessToken) {
+        config.headers = config.headers ?? {};
+        config.headers.Authorization = `Bearer ${accessToken}`;
+      }
+      return config;
+    },
+    (e) => Promise.reject(e)
+  );
+  instance.interceptors.response.use(
+    (res) => res,
+    async (error) => {
+      const response = error.response;
+      const status = response?.status;
+      const originalRequest = error.config ?? {};
+      if (status !== 401) {
+        let message = getErrorMessage?.(error) ?? response?.data?.error ?? "";
+        if (!message && typeof status === "number") {
+          switch (status) {
+            case 0:
+              message = "REST API \uC11C\uBC84\uC5D0 \uC811\uADFC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4\n\uC11C\uBC84 \uAD00\uB9AC\uC790\uC5D0\uAC8C \uBB38\uC758\uD558\uC138\uC694";
+              break;
+            case 400:
+              message = "\uC798\uBABB\uB41C \uC694\uCCAD\uC785\uB2C8\uB2E4.";
+              break;
+            case 404:
+              message = "[404] REST API \uC694\uCCAD\uC5D0 \uC2E4\uD328\uD558\uC600\uC2B5\uB2C8\uB2E4";
+              break;
+            case 500:
+              message = "\uC11C\uBC84\uC5D0\uC11C \uCC98\uB9AC \uC911 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD558\uC600\uC2B5\uB2C8\uB2E4.";
+              break;
+          }
+        }
+        if (message) onError?.(message, error);
+        return Promise.reject(error);
+      }
+      if (originalRequest._retry) {
+        clearAuth();
+        return Promise.reject(error);
+      }
+      originalRequest._retry = true;
+      const { refreshToken } = tokenAccess.get();
+      if (!refreshToken) {
+        clearAuth();
+        return Promise.reject(error);
+      }
+      if (isRefreshing) {
+        return new Promise((resolve, reject) => {
+          subscribers.push((newToken) => {
+            if (!newToken) return reject(error);
+            originalRequest.headers = originalRequest.headers ?? {};
+            originalRequest.headers.Authorization = `Bearer ${newToken}`;
+            resolve(instance(originalRequest));
+          });
+        });
+      }
+      isRefreshing = true;
+      try {
+        const newTokens = await requestRefresh(refreshToken);
+        tokenAccess.set(newTokens);
+        onAuthStateChange?.("authenticated");
+        isRefreshing = false;
+        notifySubscribers(newTokens.accessToken);
+        originalRequest.headers = originalRequest.headers ?? {};
+        originalRequest.headers.Authorization = `Bearer ${newTokens.accessToken}`;
+        return instance(originalRequest);
+      } catch (e) {
+        isRefreshing = false;
+        notifySubscribers(null);
+        clearAuth();
+        return Promise.reject(error);
+      }
+    }
+  );
+  return {
+    axios: instance,
+    setToken: (data) => tokenAccess.set(data),
+    getToken: () => tokenAccess.get(),
+    clearToken: () => clearAuth()
+  };
+}
+export {
+  createAxiosClient
+};

package/dist/index.cjs

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  matchRoute: () => matchRoute,
+  routeResponse: () => routeResponse
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/route.ts
+async function matchRoute(path, slug) {
+  const pathSegments = path.split("/").filter(Boolean);
+  const isDynamic = (segment) => segment.startsWith("[") && segment.endsWith("]");
+  if (pathSegments.length !== slug.length) return null;
+  const params = {};
+  for (let i = 0; i < pathSegments.length; i++) {
+    if (isDynamic(pathSegments[i])) {
+      const key = pathSegments[i].slice(1, -1);
+      params[key] = slug[i];
+    } else if (pathSegments[i] !== slug[i]) {
+      return null;
+    }
+  }
+  return { params };
+}
+async function routeResponse(slug, routes, request) {
+  for (const route of routes) {
+    const matched = await matchRoute(route.path, slug);
+    if (matched) {
+      return route.handler(request, matched.params);
+    }
+  }
+  return Response.json({ error: "Not Found" }, { status: 404 });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  matchRoute,
+  routeResponse
+});

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+type ApiParams = Record<string, string>;
+type RouteHandler = (request: Request, params: ApiParams) => Promise<Response>;
+type Routes = {
+    path: string;
+    handler: RouteHandler;
+};
+type ApiProps = {
+    params: Promise<{
+        slug?: string[];
+    }>;
+};
+type ListResponse<T> = {
+    result: T[];
+    totalCount: number;
+};
+type RowResponse<T> = {
+    result: T;
+};
+type ApiResult<T> = {
+    result: T;
+};
+type ApiErrorResponse = {
+    error: string;
+};
+
+declare function matchRoute(path: string, slug: string[]): Promise<{
+    params: Record<string, string>;
+} | null>;
+declare function routeResponse(slug: string[], routes: Routes[], request: Request): Promise<Response>;
+
+export { type ApiErrorResponse, type ApiParams, type ApiProps, type ApiResult, type ListResponse, type RouteHandler, type Routes, type RowResponse, matchRoute, routeResponse };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+type ApiParams = Record<string, string>;
+type RouteHandler = (request: Request, params: ApiParams) => Promise<Response>;
+type Routes = {
+    path: string;
+    handler: RouteHandler;
+};
+type ApiProps = {
+    params: Promise<{
+        slug?: string[];
+    }>;
+};
+type ListResponse<T> = {
+    result: T[];
+    totalCount: number;
+};
+type RowResponse<T> = {
+    result: T;
+};
+type ApiResult<T> = {
+    result: T;
+};
+type ApiErrorResponse = {
+    error: string;
+};
+
+declare function matchRoute(path: string, slug: string[]): Promise<{
+    params: Record<string, string>;
+} | null>;
+declare function routeResponse(slug: string[], routes: Routes[], request: Request): Promise<Response>;
+
+export { type ApiErrorResponse, type ApiParams, type ApiProps, type ApiResult, type ListResponse, type RouteHandler, type Routes, type RowResponse, matchRoute, routeResponse };

package/dist/index.js

@@ -0,0 +1,29 @@
+// src/route.ts
+async function matchRoute(path, slug) {
+  const pathSegments = path.split("/").filter(Boolean);
+  const isDynamic = (segment) => segment.startsWith("[") && segment.endsWith("]");
+  if (pathSegments.length !== slug.length) return null;
+  const params = {};
+  for (let i = 0; i < pathSegments.length; i++) {
+    if (isDynamic(pathSegments[i])) {
+      const key = pathSegments[i].slice(1, -1);
+      params[key] = slug[i];
+    } else if (pathSegments[i] !== slug[i]) {
+      return null;
+    }
+  }
+  return { params };
+}
+async function routeResponse(slug, routes, request) {
+  for (const route of routes) {
+    const matched = await matchRoute(route.path, slug);
+    if (matched) {
+      return route.handler(request, matched.params);
+    }
+  }
+  return Response.json({ error: "Not Found" }, { status: 404 });
+}
+export {
+  matchRoute,
+  routeResponse
+};