refactor: improve query key type (service/reference)

Signed-off-by: samuel.park <[email protected]>

Author: piggggggggy

apps/web/src/api-clients/_common/composables/use-api-query-key.ts

@@ -1,12 +1,11 @@
 import type { ComputedRef } from 'vue';
 import { computed } from 'vue';
 
-import { SERVICE_PREFIX } from '@/api-clients/_common/constants/query-key-constant';
 import type {
     ResourceName, ServiceName, ServiceQueryKey, Verb,
 } from '@/api-clients/_common/types/query-key-type';
-import type { QueryKeyBaseParams } from '@/query/_composables/use-query-key-base';
-import { useQueryKeyBase } from '@/query/_composables/use-query-key-base';
+import type { QueryKeyContextParams } from '@/query/_composables/use-query-key-context';
+import { useQueryKeyContext } from '@/query/_composables/use-query-key-context';
 
 /**
  * Generates a computed query key for API requests, incorporating global parameters.
@@ -15,29 +14,36 @@ import { useQueryKeyBase } from '@/query/_composables/use-query-key-base';
  * @param resource - The resource name, specifying the target API resource (e.g., 'public-data-table').
  * @param verb - The API action verb, defining the type of request (e.g., 'get', 'list', 'update').
  * @param queryKeyOptions - Optional query key options to merge with default params
- * @returns A computed reference to the query key array, structured as `[SERVICE_PREFIX, service, resource, verb, { globalParams }]`.
+ * @returns A computed reference to the query key array, structured as `[QueryContext, service, resource, verb]`
  *
  * ### Example Usage:
  * ```ts
- *  const queryKey = useAPIQueryKey('dashboard', 'public-data-table', 'get');
+ * // Basic usage
+ * const queryKey = useAPIQueryKey('dashboard', 'public-data-table', 'get');
+ *
+ * // With additional params
+ * const queryKey = useAPIQueryKey('dashboard', 'public-data-table', 'get', {
+ *   workspaceId: 'custom-id',
+ *   isAdminMode: true
+ * });
  * ```
+ *
  * The generated query key ensures:
- * - **Type safety**: Prevents invalid API calls by enforcing a valid `service/resource/verb` combination.
- * - **Auto-completion**: Provides intelligent suggestions based on predefined API structure.
- * - **Cache management**: Enables precise cache invalidation and data synchronization.
+ * - **Type safety**: Prevents invalid API calls by enforcing a valid `service/resource/verb` combination
+ * - **Auto-completion**: Provides intelligent suggestions based on predefined API structure
+ * - **Cache management**: Enables precise cache invalidation and data synchronization
  */
 
 export const useAPIQueryKey = <S extends ServiceName, R extends ResourceName<S>, V extends Verb<S, R>>(
     service: S,
     resource: R,
     verb: V,
-    queryKeyOptions?: Partial<QueryKeyBaseParams>,
+    queryKeyOptions?: Partial<QueryKeyContextParams>,
 ): ComputedRef<ServiceQueryKey<S, R, V>> => {
-    const queryKeyBase = useQueryKeyBase(queryKeyOptions);
+    const queryKeyContext = useQueryKeyContext({ ...queryKeyOptions, context: 'service' });
 
     return computed(() => [
-        ...queryKeyBase.value,
-        SERVICE_PREFIX,
+        queryKeyContext.value,
         service,
         resource,
         verb,

apps/web/src/api-clients/_common/helpers/service-query-invalidation-helper.ts

@@ -1,15 +1,17 @@
-import { SERVICE_PREFIX } from '@/api-clients/_common/constants/query-key-constant';
 import { queryClient } from '@/query';
+import type { QueryContext } from '@/query/_types/query-key-type';
 
-
-
-
-export const invalidateServiceQuery = (mode?: 'ADMIN' | 'WORKSPACE') => {
-    queryClient.invalidateQueries({
+/**
+ * Invalidates all service queries based on the specified mode.
+ *
+ * @param mode - Optional mode filter ('ADMIN' | 'WORKSPACE')
+ */
+export const invalidateServiceQuery = async (mode?: 'admin' | 'workspace') => {
+    await queryClient.invalidateQueries({
         predicate: (query) => {
-            const [queryMode,,, queryType] = query.queryKey;
-            if (queryType !== SERVICE_PREFIX) return false;
-            if (mode && mode !== queryMode) return false;
+            const [queryContext] = query.queryKey as [QueryContext, ...unknown[]];
+            if (!queryContext || queryContext.context !== 'service') return false;
+            if (mode && mode !== queryContext.mode) return false;
             return true;
         },
     });

apps/web/src/api-clients/_common/types/query-key-type.ts

@@ -1,6 +1,5 @@
 import type { API_DOC } from '@/api-clients/_common/constants/api-doc';
-import type { SERVICE_PREFIX } from '@/api-clients/_common/constants/query-key-constant';
-import type { QueryKeyBase } from '@/query/_types/query-key-type';
+import type { QueryContext } from '@/query/_types/query-key-type';
 
 
 
@@ -12,8 +11,7 @@ export type ResourceName<S extends ServiceName> = keyof (typeof API_DOC)[S];
 export type Verb<S extends ServiceName, R extends ResourceName<S>> = Extract<(typeof API_DOC)[S][R], string[]>[number] | string;
 
 export type ServiceQueryKey<S extends ServiceName, R extends ResourceName<S>, V extends Verb<S, R>> = [
-    ...QueryKeyBase,
-    typeof SERVICE_PREFIX,
+    QueryContext,
     S,
     R,
     V,

apps/web/src/query/_composables/use-query-key-base.ts apps/web/src/query/_composables/use-query-key-context.ts

@@ -1,7 +1,7 @@
 import type { ComputedRef } from 'vue';
 import { computed, reactive } from 'vue';
 
-import type { QueryKeyBase } from '@/query/_types/query-key-type';
+import type { QueryContext } from '@/query/_types/query-key-type';
 
 import { useAppContextStore } from '@/store/app-context/app-context-store';
 import { useUserWorkspaceStore } from '@/store/app-context/workspace/user-workspace-store';
@@ -11,13 +11,10 @@ import { useUserWorkspaceStore } from '@/store/app-context/workspace/user-worksp
  * Interface for global query parameters used across API requests.
  * These parameters are automatically included in API and reference query keys.
  */
-export interface QueryKeyBaseParams {
-    /** Flag indicating whether admin mode is enabled */
+export interface QueryKeyContextParams {
     isAdminMode?: boolean;
-    /** Current workspace ID from the workspace context */
     workspaceId?: string;
-    /** Additional parameters that might be added */
-    [key: string]: any;
+    context: 'service' | 'reference';
 }
 
 /**
@@ -26,24 +23,28 @@ export interface QueryKeyBaseParams {
  * that are commonly used across different API queries.
  *
  * @param queryKeyOptions - Optional query key options to merge with default params
- * @returns A computed reference containing the combined global query parameters as an ordered array
+ * @returns A computed reference containing the combined global query parameters as a QueryContext object
  *
  * ### Example Usage:
  * ```ts
- * const queryKeyBase = useQueryKeyBase();
- * // Access params (now returns array)
- * const [mode, workspaceId, others] = queryKeyBase.value;
+ * const queryContext = useQueryKeyContext({ context: 'service' });
+ * // Access params
+ * const { mode, workspaceId, context } = queryContext.value;
  *
  * // With additional params
- * const params = useQueryKeyBase({ customParam: 'value' });
+ * const params = useQueryKeyContext({
+ *   context: 'service',
+ *   isAdminMode: true,
+ *   workspaceId: 'custom-id'
+ * });
  * ```
  *
  * ### Features:
- * - **Ordered Parameters**: Guarantees consistent parameter order: [mode, workspaceId, others]
+ * - **Structured Context**: Returns a QueryContext object with mode, workspaceId, and context
  * - **Reactive State**: Automatically updates when workspace or admin mode changes
- * - **Parameter Merging**: Allows adding custom parameters in the others object
+ * - **Type Safety**: Ensures context is always provided with valid values
  */
-export const useQueryKeyBase = (queryKeyOptions?: Partial<QueryKeyBaseParams>): ComputedRef<QueryKeyBase> => {
+export const useQueryKeyContext = (queryKeyOptions: QueryKeyContextParams): ComputedRef<QueryContext> => {
     const appContextStore = useAppContextStore();
     const userWorkspaceStore = useUserWorkspaceStore();
 
@@ -52,15 +53,17 @@ export const useQueryKeyBase = (queryKeyOptions?: Partial<QueryKeyBaseParams>):
         currentWorkspaceId: computed<string|undefined>(() => userWorkspaceStore.getters.currentWorkspaceId),
     });
 
-    return computed<QueryKeyBase>(() => {
-        const { isAdminMode, workspaceId: _workspaceId, ...otherParams } = queryKeyOptions || {};
-        const mode = (isAdminMode || _state.isAdminMode) ? 'ADMIN' : 'WORKSPACE';
+    return computed<QueryContext>(() => {
+        const {
+            isAdminMode, workspaceId: _workspaceId, context,
+        } = queryKeyOptions || {};
+        const mode = (isAdminMode || _state.isAdminMode) ? 'admin' : 'workspace';
         const workspaceId = _workspaceId || _state.currentWorkspaceId;
 
-        return [
+        return {
             mode,
             workspaceId,
-            Object.keys(otherParams).length > 0 ? otherParams : undefined,
-        ];
+            context,
+        };
     });
 };

apps/web/src/query/_types/query-key-type.ts

@@ -1,9 +1,9 @@
 
-export type QueryKeyBase = [
-    mode: 'ADMIN' | 'WORKSPACE',
+export interface QueryContext {
+    mode: 'admin' | 'workspace',
     workspaceId: string | undefined,
-    others: Record<string, any> | undefined,
-];
+    context: 'service' | 'reference',
+}
 
 
 

apps/web/src/query/reference/_composables/use-reference-query-key.ts

@@ -1,9 +1,8 @@
 import type { ComputedRef } from 'vue';
 import { computed } from 'vue';
 
-import type { QueryKeyBaseParams } from '@/query/_composables/use-query-key-base';
-import { useQueryKeyBase } from '@/query/_composables/use-query-key-base';
-import { getReferencePrimaryQueryKey } from '@/query/reference/_helper/reference-query-key-helper';
+import type { QueryKeyContextParams } from '@/query/_composables/use-query-key-context';
+import { useQueryKeyContext } from '@/query/_composables/use-query-key-context';
 import type { ReferenceQueryKey } from '@/query/reference/_types/reference-query-key-type';
 import type { ReferenceResourceType } from '@/query/reference/_types/reference-resource-type';
 
@@ -16,15 +15,18 @@ import type { ReferenceResourceType } from '@/query/reference/_types/reference-r
  *
  * @param resourceType - The type of reference resource (e.g., 'public-dashboard', 'project')
  * @param queryKeyOptions - Optional query key options to merge with default params
- * @returns A computed reference to the query key array, structured as `[REFERENCE_PREFIX, ...referencePrimaryKey, { globalParams }]`
+ * @returns A computed reference to the query key array, structured as `[QueryContext, resourceType]`
  *
  * ### Example Usage:
  * ```ts
  * // Basic usage
  * const referenceKey = useReferenceQueryKey('public-dashboard');
  *
  * // With additional params
- * const referenceKey = useReferenceQueryKey('public-dashboard', { workspaceId: 'custom-id' });
+ * const referenceKey = useReferenceQueryKey('public-dashboard', {
+ *   workspaceId: 'custom-id',
+ *   context: 'reference'
+ * });
  * ```
  *
  * ### Features:
@@ -34,12 +36,12 @@ import type { ReferenceResourceType } from '@/query/reference/_types/reference-r
  */
 export const useReferenceQueryKey = (
     resourceType: ReferenceResourceType,
-    queryKeyOptions?: Partial<QueryKeyBaseParams>,
+    queryKeyOptions?: Partial<QueryKeyContextParams>,
 ): ComputedRef<ReferenceQueryKey> => {
-    const queryKeyBase = useQueryKeyBase(queryKeyOptions);
+    const queryKeyContext = useQueryKeyContext({ ...queryKeyOptions, context: 'reference' });
 
     return computed(() => [
-        ...queryKeyBase.value,
-        ...getReferencePrimaryQueryKey(resourceType),
+        queryKeyContext.value,
+        resourceType,
     ]);
 };

apps/web/src/query/reference/_constant/query-key-constant.ts

@@ -1,13 +1,17 @@
 import { queryClient } from '@/query';
-import { REFERENCE_PREFIX } from '@/query/reference/_constant/query-key-constant';
+import type { QueryContext } from '@/query/_types/query-key-type';
 
-
-export const invalidateReferenceQuery = (mode?: 'ADMIN' | 'WORKSPACE') => {
-    queryClient.invalidateQueries({
+/**
+ * Invalidates all reference queries based on the specified mode.
+ *
+ * @param mode - Optional mode filter ('ADMIN' | 'WORKSPACE')
+ */
+export const invalidateReferenceQuery = async (mode?: 'admin' | 'workspace') => {
+    await queryClient.invalidateQueries({
         predicate: (query) => {
-            const [queryMode,,, queryType] = query.queryKey;
-            if (queryType !== REFERENCE_PREFIX) return false;
-            if (mode && mode !== queryMode) return false;
+            const [queryContext] = query.queryKey as [QueryContext, ...unknown[]];
+            if (!queryContext || queryContext.context !== 'reference') return false;
+            if (mode && mode !== queryContext.mode) return false;
             return true;
         },
     });

apps/web/src/query/reference/_helper/reference-query-invalidation-helper.ts

@@ -1,16 +1,8 @@
-import type { QueryKeyBase } from '@/query/_types/query-key-type';
-import { REFERENCE_PREFIX } from '@/query/reference/_constant/query-key-constant';
+import type { QueryContext } from '@/query/_types/query-key-type';
 import type { ReferenceResourceType } from '@/query/reference/_types/reference-resource-type';
 
 
 export type ReferenceQueryKey = [
-    ...QueryKeyBase,
-    typeof REFERENCE_PREFIX,
+    QueryContext,
     ReferenceResourceType
 ];
-
-// 명시적인 반환 타입 정의
-export const getReferencePrimaryQueryKey = (resourceType: ReferenceResourceType): [typeof REFERENCE_PREFIX, ReferenceResourceType] => [
-    REFERENCE_PREFIX,
-    resourceType,
-];