feat(query-key): create new API Query Key composable (useApiQueryKey)

[piggggggggy]

Skip Review (optional)

• Minor changes that don't affect the functionality (e.g. style, chore, ci, test, docs)
• Previously reviewed in feature branch, further review is not mandatory
• Self-merge allowed for solo developers or urgent changes

Description (optional)

• Create New API Query Key composable (useAPIQueryKey)
• Rearrange query dir architecture

src/query/
├── query-key/
│   ├── _composable/
│   │   └── use-app-context-query-key.ts
│   ├── _helpers/
│   │   └── immutable-query-key-helper.ts
│   ├── _types/
│   │   └── query-key-type.ts
│   └── use-service-query-key.ts
├── clients.ts

Summary of Changes - 2025.03.27

1. deps → contextKey
   • Renamed: deps has been renamed to contextKey for clarity.
   • Position in Query Key Structure: Moved from the end to between verb and params
   → New order: [..., verb, contextKey, params]
   • Type Updated: From fixed object type to a more flexible type
   → Now accepts string, string[], or object

2. params
   • Return Type Updated: Changed from ComputedRef to Readonly
   • Simplified Transformation Logic: Removed unnecessary wrapping and unwrapping (i.e., toValue → computed)
   • Preserved Reactivity Input: Still accepts reactive values (ref, computed, getter, or object)
   • Reactive Behavior: The returned params is non-reactive but always reflects the latest value of the reactive input.

3. partial() → withSuffix()
   • Renamed: partial() method has been renamed to withSuffix()
   → Emphasizes the action (suffixing the key) and intent (key extension)
   • Purpose: Designed for imperative cache control or when additional dynamic context is required at runtime
   → Helps prevent manual key modification like [...key, id], and provides a safer, more consistent API.

4. useAPIQueryKey → useServiceQueryKey
   • Composable Name Changed: Renamed to better reflect its purpose and scope
   → Designed for generating service-level query keys

5. Documentation and Tests Updated
   • Adjusted all usage examples, types, and test cases accordingly.
   • Expanded documentation to clearly explain the purpose and behavior of contextKey, withSuffix, and params.

6. Global queryClient Usage
   • Added guidance on how to use queryClient with service-specific references and key structures.

---

1. deps -> contextKey
   • 네이밍 변경 : deps -> contextKey
   • Key Architecture 위치 변경 -> verb 뒤, params 앞
   • […, {verb}, {contextKey}, {params}]
   • 타입 변경 : object 고정 -> 열린 타입

2. params
   • return 방식 변경 : ComputedRef -> Readonly
   • 열린 타입을 (Maybe 객체) ComputedRef로 변환하기 위해 들어갔던 불필요한 변환과정을 제거하고, 입력의 반응성은 살리되, Return되는 params의 반응성을 벗기고 Readonly 타입으로 반환되도록 작업했습니다.
   • 반환되는 params는 반응성이 없지만, 주입된 반응성에 의해 값은 유동적으로 반영됩니다.

3. partial 메서드 -> withSuffix 메서드
   • 네이밍 변경 : queryKey에 일부를 더한다는 의미를 가진 withSuffix 행동 + 의미 를 조합했읍니다
   • 명령형 캐시 제어가 필요한 경우 혹은 런타임에 추가 동적 컨텍스트가 필요할 때 사용하기 위한 메서드입니다. (키의 수동적 수정([…key, data_table_id])을 막고, 런타임 확장이 필요할 때 사용을 권장)

4. useAPIQueryKey -> useServiceQueryKey composable 네이밍 수정

5. doc 및 test 수정

6. global queryClient (service/reference) 설명 반영

Things to Talk About (optional)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

5 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
console	⬜️ Ignored (Inspect)	Visit Preview		Mar 28, 2025 7:19am
dashboard	⬜️ Ignored (Inspect)	Visit Preview		Mar 28, 2025 7:19am
feature-service-account-budget	⬜️ Ignored (Inspect)	Visit Preview		Mar 28, 2025 7:19am
service-account-budget	⬜️ Ignored (Inspect)	Visit Preview		Mar 28, 2025 7:19am
web-storybook	⬜️ Ignored (Inspect)	Visit Preview		Mar 28, 2025 7:19am

[github-actions]

🎉 @WANZARGEN and @seungyeoneeee have been randomly selected as the reviewers! Please review. 🙏

[WANZARGEN]

LGTM!

[WANZARGEN]

Except in cases where reactive is used for a specific purpose—such as managing state separately in a store—wrapping a computed value with reactive doesn’t seem necessary or meaningful.

---

store와 같이 상태를 별도로 관리해야 할 특별한 이유로 reactive를 사용하는 경우를 제외하면, computed를 reactive로 감싸는 것은 불필요하거나 큰 의미가 없어 보입니다.