@blastlabs/utils 1.19.0 → 1.21.0

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './form';
 export * from './string';
 export * from './number';
 export * from './mock';
+export * from './routes';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,QAAQ,CAAC;AAYvB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -15,3 +15,4 @@ export * from './mock';
 // export * from './array';
 // Object utilities (placeholder for future)
 // export * from './object';
+export * from './routes';

package/dist/routes/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 인증 관련 라우트 경로
+ */
+export declare const AUTH_ROUTES: {
+    readonly ROOT: "/auth";
+    readonly LOGIN: string;
+    readonly REGISTER: string;
+    readonly FORGOT_PASSWORD: string;
+    readonly RESET_PASSWORD: string;
+    readonly VERIFY_EMAIL: string;
+    readonly VERIFY_OTP: string;
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/routes/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,eAAO,MAAM,WAAW;;;;;;;;CAQd,CAAC"}

package/dist/routes/auth.js

@@ -0,0 +1,14 @@
+/**
+ * 인증 관련 라우트 경로
+ */
+import { createRoute } from './utils/helpers';
+const AUTH_BASE = '/auth';
+export const AUTH_ROUTES = {
+    ROOT: AUTH_BASE,
+    LOGIN: createRoute(AUTH_BASE, '/login'),
+    REGISTER: createRoute(AUTH_BASE, '/register'),
+    FORGOT_PASSWORD: createRoute(AUTH_BASE, '/forgot-password'),
+    RESET_PASSWORD: createRoute(AUTH_BASE, '/reset-password'),
+    VERIFY_EMAIL: createRoute(AUTH_BASE, '/verify-email'),
+    VERIFY_OTP: createRoute(AUTH_BASE, '/verify-otp'),
+};

package/dist/routes/base.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 기본 라우트 경로
+ */
+export declare const BASE_ROUTES: {
+    readonly HOME: "/";
+};
+//# sourceMappingURL=base.d.ts.map

package/dist/routes/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/routes/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,WAAW;;CAEd,CAAC"}

package/dist/routes/base.js

@@ -0,0 +1,6 @@
+/**
+ * 기본 라우트 경로
+ */
+export const BASE_ROUTES = {
+    HOME: '/',
+};

package/dist/routes/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 애플리케이션 라우트 경로 상수
+ * Next.js App Router 기준으로 작성되었습니다.
+ *
+ * 사용 예시:
+ * - ROUTE_PATH.HOME
+ * - ROUTE_PATH.AUTH.LOGIN
+ * - withParam(ROUTE_PATH.USERS.DETAIL, { id: '123' })
+ */
+/**
+ * 라우트 경로 상수 객체
+ */
+export declare const ROUTE_PATH: {
+    readonly AUTH: {
+        readonly ROOT: "/auth";
+        readonly LOGIN: string;
+        readonly REGISTER: string;
+        readonly FORGOT_PASSWORD: string;
+        readonly RESET_PASSWORD: string;
+        readonly VERIFY_EMAIL: string;
+        readonly VERIFY_OTP: string;
+    };
+    readonly POST: {
+        readonly ROOT: "/post";
+        readonly LIST: "/post";
+        readonly CREATE: string;
+        readonly DETAIL: string;
+    };
+    readonly HOME: "/";
+};
+export { withParam, withQuery } from './utils/helpers';
+export type { RoutePath } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;CAIb,CAAC;AAGX,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGvD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/routes/index.js

@@ -0,0 +1,22 @@
+/**
+ * 애플리케이션 라우트 경로 상수
+ * Next.js App Router 기준으로 작성되었습니다.
+ *
+ * 사용 예시:
+ * - ROUTE_PATH.HOME
+ * - ROUTE_PATH.AUTH.LOGIN
+ * - withParam(ROUTE_PATH.USERS.DETAIL, { id: '123' })
+ */
+import { BASE_ROUTES } from './base';
+import { AUTH_ROUTES } from './auth';
+import { POST_ROUTES } from './post';
+/**
+ * 라우트 경로 상수 객체
+ */
+export const ROUTE_PATH = {
+    ...BASE_ROUTES,
+    AUTH: AUTH_ROUTES,
+    POST: POST_ROUTES,
+};
+// 유틸리티 함수 재내보내기
+export { withParam, withQuery } from './utils/helpers';

package/dist/routes/post.d.ts

@@ -0,0 +1,7 @@
+export declare const POST_ROUTES: {
+    readonly ROOT: "/post";
+    readonly LIST: "/post";
+    readonly CREATE: string;
+    readonly DETAIL: string;
+};
+//# sourceMappingURL=post.d.ts.map

package/dist/routes/post.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post.d.ts","sourceRoot":"","sources":["../../src/routes/post.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW;;;;;CAKd,CAAC"}

package/dist/routes/post.js

@@ -0,0 +1,8 @@
+import { createRoute } from './utils/helpers';
+const POST_BASE = '/post';
+export const POST_ROUTES = {
+    ROOT: POST_BASE,
+    LIST: POST_BASE,
+    CREATE: createRoute(POST_BASE, '/create'),
+    DETAIL: createRoute(POST_BASE, '/[id]'),
+};

package/dist/routes/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 라우트 경로 관련 타입 정의
+ */
+import type { ROUTE_PATH } from './index';
+/**
+ * 라우트 경로 타입
+ */
+export type RoutePath = typeof ROUTE_PATH;
+//# sourceMappingURL=types.d.ts.map

package/dist/routes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routes/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC"}

package/dist/routes/types.js

@@ -0,0 +1,4 @@
+/**
+ * 라우트 경로 관련 타입 정의
+ */
+export {};

package/dist/routes/users.example.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 사용자 관련 라우트 경로 예시
+ *
+ * 새로운 도메인 라우트를 추가할 때 이 파일을 참고하세요.
+ *
+ * 사용 방법:
+ * 1. 이 파일을 users.ts로 이름 변경
+ * 2. routes/index.ts에서 import하여 ROUTE_PATH에 추가
+ */
+export declare const USERS_ROUTES: {
+    readonly ROOT: "/users";
+    readonly LIST: "/users";
+    readonly DETAIL: string;
+    readonly CREATE: string;
+    readonly EDIT: string;
+    readonly SETTINGS: string;
+    readonly PROFILE: string;
+};
+//# sourceMappingURL=users.example.d.ts.map

package/dist/routes/users.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.example.d.ts","sourceRoot":"","sources":["../../src/routes/users.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC"}

package/dist/routes/users.example.js

@@ -0,0 +1,20 @@
+/**
+ * 사용자 관련 라우트 경로 예시
+ *
+ * 새로운 도메인 라우트를 추가할 때 이 파일을 참고하세요.
+ *
+ * 사용 방법:
+ * 1. 이 파일을 users.ts로 이름 변경
+ * 2. routes/index.ts에서 import하여 ROUTE_PATH에 추가
+ */
+import { createRoute } from './utils/helpers';
+const USERS_BASE = '/users';
+export const USERS_ROUTES = {
+    ROOT: USERS_BASE,
+    LIST: USERS_BASE,
+    DETAIL: createRoute(USERS_BASE, '/[id]'),
+    CREATE: createRoute(USERS_BASE, '/create'),
+    EDIT: createRoute(USERS_BASE, '/[id]/edit'),
+    SETTINGS: createRoute(USERS_BASE, '/[id]/settings'),
+    PROFILE: createRoute(USERS_BASE, '/profile'),
+};

package/dist/routes/utils/helpers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로 (예: '/users/[id]')
+ * @param params - 파라미터 객체 (예: { id: '123' })
+ * @returns 실제 경로 (예: '/users/123')
+ *
+ * @example
+ * ```ts
+ * const userPath = withParam('/users/[id]', { id: '123' });
+ * // '/users/123'
+ * ```
+ */
+export declare function withParam<T extends string>(path: T, params: Record<string, string | number>): string;
+/**
+ * 쿼리 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로
+ * @param query - 쿼리 파라미터 객체
+ * @returns 쿼리 파라미터가 포함된 경로
+ *
+ * @example
+ * ```ts
+ * const searchPath = withQuery('/search', { q: 'test', page: 1 });
+ * // '/search?q=test&page=1'
+ * ```
+ */
+export declare function withQuery(path: string, query: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * 라우트 경로를 생성하는 헬퍼 함수
+ * @param base - 기본 경로
+ * @param path - 추가 경로
+ * @returns 합쳐진 경로
+ *
+ * @example
+ * ```ts
+ * const route = createRoute('/auth', '/login');
+ * // '/auth/login'
+ * ```
+ */
+export declare function createRoute(base: string, path: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/routes/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/utils/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,MAAM,CAMR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,GAClE,MAAM,CASR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/routes/utils/helpers.js

@@ -0,0 +1,59 @@
+/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로 (예: '/users/[id]')
+ * @param params - 파라미터 객체 (예: { id: '123' })
+ * @returns 실제 경로 (예: '/users/123')
+ *
+ * @example
+ * ```ts
+ * const userPath = withParam('/users/[id]', { id: '123' });
+ * // '/users/123'
+ * ```
+ */
+export function withParam(path, params) {
+    let result = path;
+    for (const [key, value] of Object.entries(params)) {
+        result = result.replace(`[${key}]`, String(value));
+    }
+    return result;
+}
+/**
+ * 쿼리 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로
+ * @param query - 쿼리 파라미터 객체
+ * @returns 쿼리 파라미터가 포함된 경로
+ *
+ * @example
+ * ```ts
+ * const searchPath = withQuery('/search', { q: 'test', page: 1 });
+ * // '/search?q=test&page=1'
+ * ```
+ */
+export function withQuery(path, query) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== null && value !== undefined) {
+            searchParams.append(key, String(value));
+        }
+    }
+    const queryString = searchParams.toString();
+    return queryString ? `${path}?${queryString}` : path;
+}
+/**
+ * 라우트 경로를 생성하는 헬퍼 함수
+ * @param base - 기본 경로
+ * @param path - 추가 경로
+ * @returns 합쳐진 경로
+ *
+ * @example
+ * ```ts
+ * const route = createRoute('/auth', '/login');
+ * // '/auth/login'
+ * ```
+ */
+export function createRoute(base, path) {
+    return `${base}${path.startsWith('/') ? path : `/${path}`}`;
+}

package/dist/routes/utils/helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=helpers.test.d.ts.map

package/dist/routes/utils/helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.test.d.ts","sourceRoot":"","sources":["../../../src/routes/utils/helpers.test.ts"],"names":[],"mappings":""}

package/dist/routes/utils/helpers.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { withParam, withQuery, createRoute } from './helpers';
+describe('routes/utils/helpers', () => {
+    describe('withParam', () => {
+        it('should replace single parameter', () => {
+            expect(withParam('/users/[id]', { id: '123' })).toBe('/users/123');
+            expect(withParam('/posts/[postId]', { postId: '456' })).toBe('/posts/456');
+        });
+        it('should replace multiple parameters', () => {
+            expect(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: '456',
+                commentId: '789',
+            })).toBe('/posts/456/comments/789');
+            expect(withParam('/users/[userId]/posts/[postId]/comments/[commentId]', {
+                userId: '1',
+                postId: '2',
+                commentId: '3',
+            })).toBe('/users/1/posts/2/comments/3');
+        });
+        it('should handle parameters in any order', () => {
+            const path = '/posts/[postId]/comments/[commentId]';
+            // 순서대로
+            expect(withParam(path, { postId: '456', commentId: '789' })).toBe('/posts/456/comments/789');
+            // 반대 순서
+            expect(withParam(path, { commentId: '789', postId: '456' })).toBe('/posts/456/comments/789');
+        });
+        it('should handle nested key names safely', () => {
+            // id가 postId의 부분 문자열이지만 정확한 일치만 바꿈
+            expect(withParam('/posts/[id]/comments/[postId]', { id: '123', postId: '456' })).toBe('/posts/123/comments/456');
+            expect(withParam('/posts/[id]/comments/[postId]', { postId: '456', id: '123' })).toBe('/posts/123/comments/456');
+        });
+        it('should replace only first occurrence (using replace, not replaceAll)', () => {
+            // 현재 구현은 replace()를 사용하므로 첫 번째 매칭만 바뀝니다
+            expect(withParam('/[id]/[id]/[id]', { id: '123' })).toBe('/123/[id]/[id]');
+        });
+        it('should handle numeric values', () => {
+            expect(withParam('/users/[id]', { id: 123 })).toBe('/users/123');
+            expect(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: 1,
+                commentId: 2,
+            })).toBe('/posts/1/comments/2');
+        });
+        it('should leave unmatched parameters as is', () => {
+            expect(withParam('/users/[id]', { userId: '123' })).toBe('/users/[id]');
+            expect(withParam('/posts/[postId]/comments/[commentId]', { id: '123' })).toBe('/posts/[postId]/comments/[commentId]');
+        });
+        it('should handle values with brackets correctly', () => {
+            // 값에 [id]가 있어도 이미 처리된 패턴은 다시 바뀌지 않음
+            expect(withParam('/[placeholder]/[actual]', { placeholder: 'fixed', actual: '[id]' })).toBe('/fixed/[id]');
+        });
+    });
+    describe('withQuery', () => {
+        it('should add single query parameter', () => {
+            expect(withQuery('/search', { q: 'test' })).toBe('/search?q=test');
+            expect(withQuery('/users', { page: 1 })).toBe('/users?page=1');
+        });
+        it('should add multiple query parameters', () => {
+            expect(withQuery('/search', { q: 'test', page: 1 })).toBe('/search?q=test&page=1');
+            expect(withQuery('/filter', { category: 'tech', sort: 'asc', limit: 10 })).toBe('/filter?category=tech&sort=asc&limit=10');
+        });
+        it('should handle numeric values', () => {
+            expect(withQuery('/users', { page: 1, limit: 20 })).toBe('/users?page=1&limit=20');
+        });
+        it('should handle boolean values', () => {
+            expect(withQuery('/posts', { featured: true, archived: false })).toBe('/posts?featured=true&archived=false');
+        });
+        it('should filter out null and undefined values', () => {
+            expect(withQuery('/search', { q: 'test', page: null, limit: undefined })).toBe('/search?q=test');
+            expect(withQuery('/users', { id: undefined })).toBe('/users');
+        });
+        it('should handle empty object', () => {
+            expect(withQuery('/users', {})).toBe('/users');
+        });
+        it('should append query string (does not merge with existing query)', () => {
+            // 현재 구현은 기존 쿼리 스트링을 병합하지 않고 뒤에 붙입니다
+            expect(withQuery('/search?existing=1', { new: 'value' })).toBe('/search?existing=1?new=value');
+        });
+        it('should combine withParam and withQuery', () => {
+            const path = withQuery(withParam('/users/[id]', { id: '123' }), { tab: 'profile' });
+            expect(path).toBe('/users/123?tab=profile');
+            const path2 = withQuery(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: '456',
+                commentId: '789',
+            }), { sort: 'asc', page: 1 });
+            expect(path2).toBe('/posts/456/comments/789?sort=asc&page=1');
+        });
+    });
+    describe('createRoute', () => {
+        it('should combine base and path', () => {
+            expect(createRoute('/auth', '/login')).toBe('/auth/login');
+            expect(createRoute('/users', '/create')).toBe('/users/create');
+        });
+        it('should handle path without leading slash', () => {
+            expect(createRoute('/auth', 'login')).toBe('/auth/login');
+            expect(createRoute('/users', 'create')).toBe('/users/create');
+        });
+        it('should handle base with trailing slash', () => {
+            expect(createRoute('/auth/', '/login')).toBe('/auth//login');
+            expect(createRoute('/auth/', 'login')).toBe('/auth//login');
+        });
+        it('should handle multiple levels', () => {
+            expect(createRoute('/api/v1', '/users')).toBe('/api/v1/users');
+            expect(createRoute('/admin', '/settings/profile')).toBe('/admin/settings/profile');
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/rules/naming-convention.md

@@ -21,34 +21,15 @@ paths:
 user-profile/
 use-user-data/
 button-group.tsx
+user-card.tsx
+login-form.tsx
 
 ❌ bad
 UserProfile/
 useUserData/
 buttonGroup.tsx
-```
-
-### 예외: React 컴포넌트
-
-**컴포넌트 파일은 `PascalCase` 사용**
-
-```
-components/
-  ✅ ButtonGroup.tsx
-  ✅ UserProfile.tsx
-  ✅ FormInput.tsx
-
-  ❌ button-group.tsx
-  ❌ user-profile.tsx
-```
-
-**단, 폴더는 `kebab-case`**
-
-```
-components/
-  button-group/
-    ButtonGroup.tsx
-    ButtonGroup.test.tsx
+UserCard.tsx
+LoginForm.tsx
 ```
 
 ### Hooks
@@ -85,8 +66,8 @@ model/
 **대상 파일명 + `.test.` + 확장자**
 
 ```
-ButtonGroup.tsx → ButtonGroup.test.tsx
-useUserData.ts → useUserData.test.ts
+button-group.tsx → button-group.test.tsx
+use-user-data.ts → use-user-data.test.ts
 api.ts → api.test.ts
 ```
 
@@ -106,19 +87,20 @@ src/
 │       │   ├── use-user-query.ts
 │       │   └── user.test.ts
 │       └── ui/
-│           ├── UserCard.tsx      # PascalCase
-│           └── UserCard.test.tsx
+│           ├── user-card.tsx
+│           └── user-card.test.tsx
 ├── features/
 │   └── auth-login/               # kebab-case
 │       ├── model/
 │       ├── api/
 │       └── ui/
-│           └── LoginForm.tsx     # PascalCase
+│           ├── login-form.tsx
+│           └── login-form.test.tsx
 ├── shared/
 │   └── ui/
 │       └── button/               # kebab-case
-│           ├── Button.tsx        # PascalCase
-│           └── Button.test.tsx
+│           ├── button.tsx
+│           └── button.test.tsx
 ```
 
 ## 변수/함수 네이밍
@@ -206,7 +188,7 @@ enum userRole {
 
 ## 중요
 
-- **Always** use kebab-case for files and folders
-- **Always** use PascalCase for component files
+- **Always** use kebab-case for all files and folders (including components)
 - **Always** use camelCase for variables and functions
-- **Always** use UPPER_SNAKE_CASE for constants
+- **Always** use UPPER_SNAKE_CASE for constants
+- **Always** use PascalCase for types, interfaces, enums, and React component exports