​

Cache Key Registry

​

Objective

​

Files

• lib/cache-keys.ts
• lib/query-keys.ts

​

Rules

​

Root key names

• every root key name must come from CACHE_KEYS
• keys must be uppercase in the registry
• no hard-coded root key strings outside lib/cache-keys.ts and lib/query-keys.ts

export const CACHE_KEYS = {
  ACCOUNTS: 'accounts',
  MANUAL_ACCOUNTS: 'manual-accounts',
  HOLDINGS: 'holdings',
  NET_WORTH: 'net-worth',
  TRANSACTIONS: 'transactions',
  CHAT_SESSIONS: 'chat-sessions',
  USER_INFO: 'user-info',
} as const

​

Query key composition

• all query key arrays must be created in lib/query-keys.ts
• every user-scoped key must include userId at index [1]
• every domain should expose an .all key for prefix invalidation

import { CACHE_KEYS } from '@/lib/cache-keys'

export const globalKeys = {
  marketIndexes: {
    all: [CACHE_KEYS.MARKET_INDEXES] as const,
  },
  marketSummary: {
    all: [CACHE_KEYS.MARKET_SUMMARY] as const,
  },
} as const

export function userKeys(userId: string) {
  return {
    accounts: {
      all: [CACHE_KEYS.ACCOUNTS, userId] as const,
      list: () => [CACHE_KEYS.ACCOUNTS, userId, 'list'] as const,
    },
    holdings: {
      all: [CACHE_KEYS.HOLDINGS, userId] as const,
      list: () => [CACHE_KEYS.HOLDINGS, userId, 'list'] as const,
    },
    transactions: {
      all: [CACHE_KEYS.TRANSACTIONS, userId] as const,
      unified: () => [CACHE_KEYS.TRANSACTIONS, userId, 'unified'] as const,
    },
  } as const
}

​

Naming Guidelines

• use singular domain groups in the factory object when it reads well, but keep root strings aligned with existing cache language
• prefer list, detail, summary, stats, byId, byDate, unified as stable suffix conventions
• avoid inventing multiple suffix names for the same pattern

​

Migration Steps

1. Create CACHE_KEYS with every root query key currently in use.
2. Build globalKeys and userKeys(userId).
3. Replace local factories such as createQueryKeys.
4. Replace inline key arrays with factory helpers.
5. Leave no orphaned root key string arrays behind.

​

Review Checklist

• does the domain have an .all key?
• is userId at index [1] for user-scoped data?
• does the new factory preserve existing cache segmentation where needed?
• are there any inline arrays left in the touched files?