docs: add TanStack Query migration continuation guide
This document provides context for continuing the migration in future PRs: - Remaining work (Party component mutations, resource class removal) - Patterns and best practices for infinite queries, debounced search, mutations - Known issues and file locations - Reference implementations Co-Authored-By: Justin Edmund <justin@jedmund.com>
This commit is contained in:
Devin AI
parent
908fc5a44a
commit
a9a03d3aa7
1 changed files with 217 additions and 0 deletions
217
TANSTACK_QUERY_MIGRATION_CONTINUATION.md
Normal file
217
TANSTACK_QUERY_MIGRATION_CONTINUATION.md
Normal file
|
|
@ -0,0 +1,217 @@
|
||||||
|
# TanStack Query Migration - Continuation Guide
|
||||||
|
|
||||||
|
This document provides context for continuing the TanStack Query v6 migration in hensei-web.
|
||||||
|
|
||||||
|
## Migration Status
|
||||||
|
|
||||||
|
### Completed (PR #441 - merged)
|
||||||
|
- Query options factories: `party.queries.ts`, `job.queries.ts`, `user.queries.ts`, `search.queries.ts`
|
||||||
|
- Mutation configurations: `party.mutations.ts`, `grid.mutations.ts`, `job.mutations.ts`
|
||||||
|
- SSR utilities: `withInitialData`, `prefetchQuery`, `prefetchInfiniteQuery`
|
||||||
|
- Example components: `JobSelectionSidebar.svelte`, `teams/[id]/+page.svelte`
|
||||||
|
|
||||||
|
### Completed (PR #442 - pending merge)
|
||||||
|
- `JobSkillSelectionSidebar.svelte` - Job skill search with infinite scroll
|
||||||
|
- `SearchContent.svelte` - Search modal for weapons/characters/summons
|
||||||
|
- `[username]/+page.svelte` - User profile page with teams/favorites tabs
|
||||||
|
- `teams/explore/+page.svelte` - Public teams listing
|
||||||
|
|
||||||
|
### Remaining Work
|
||||||
|
|
||||||
|
#### Follow-Up Prompt 5: Party Component Mutations
|
||||||
|
**Priority: High**
|
||||||
|
**Complexity: Large**
|
||||||
|
|
||||||
|
The `Party.svelte` component (1535 lines) needs to be migrated to use TanStack Query mutations instead of direct service calls.
|
||||||
|
|
||||||
|
**Files to modify:**
|
||||||
|
- `src/lib/components/party/Party.svelte`
|
||||||
|
|
||||||
|
**Current state:** Uses `PartyService`, `GridService`, `ConflictService`, and direct `partyAdapter` calls.
|
||||||
|
|
||||||
|
**Target state:** Use mutation hooks from:
|
||||||
|
- `src/lib/api/mutations/party.mutations.ts` - `useUpdateParty`, `useDeleteParty`, `useRemixParty`, `useFavoriteParty`, `useUnfavoriteParty`, `useRegeneratePreview`
|
||||||
|
- `src/lib/api/mutations/grid.mutations.ts` - `useCreateGridWeapon`, `useUpdateGridWeapon`, `useDeleteGridWeapon`, etc.
|
||||||
|
- `src/lib/api/mutations/job.mutations.ts` - `useUpdatePartyJob`, `useUpdatePartyJobSkills`, `useRemovePartyJobSkill`, `useUpdatePartyAccessory`
|
||||||
|
|
||||||
|
**Recommended sub-tasks:**
|
||||||
|
1. **5a: Party metadata mutations** - name, description, visibility using `useUpdateParty`
|
||||||
|
2. **5b: Grid weapon mutations** - add/update/delete weapons using grid mutations
|
||||||
|
3. **5c: Grid character mutations** - add/update/delete characters using grid mutations
|
||||||
|
4. **5d: Grid summon mutations** - add/update/delete summons using grid mutations
|
||||||
|
5. **5e: Job and skill mutations** - job selection, skill management using job mutations
|
||||||
|
|
||||||
|
**Key functions to migrate in Party.svelte:**
|
||||||
|
- `updatePartyDetails()` - replace `partyService.update()` with `useUpdateParty().mutate()`
|
||||||
|
- `toggleFavorite()` - replace `partyService.favorite()/unfavorite()` with `useFavoriteParty()/useUnfavoriteParty()`
|
||||||
|
- `remixParty()` - replace `partyService.remix()` with `useRemixParty()`
|
||||||
|
- `deleteParty()` - replace `partyService.delete()` with `useDeleteParty()`
|
||||||
|
- `handleSelectJob()` - replace `partyAdapter.updateJob()` with `useUpdatePartyJob()`
|
||||||
|
- `handleSelectJobSkill()` - replace `partyAdapter.updateJobSkills()` with `useUpdatePartyJobSkills()`
|
||||||
|
- Drag-drop operations - replace `gridService.moveWeapon/Character/Summon()` with appropriate mutations
|
||||||
|
|
||||||
|
#### Follow-Up Prompt 6: Remove Deprecated Resource Classes
|
||||||
|
**Priority: Low**
|
||||||
|
**Complexity: Small**
|
||||||
|
**Prerequisite:** All components migrated away from resource classes
|
||||||
|
|
||||||
|
**Files to delete:**
|
||||||
|
- `src/lib/api/adapters/resources/search.resource.svelte.ts`
|
||||||
|
- `src/lib/api/adapters/resources/party.resource.svelte.ts`
|
||||||
|
- `src/lib/api/adapters/resources/job.resource.svelte.ts`
|
||||||
|
- `src/lib/api/adapters/resources/infiniteScroll.resource.svelte.ts`
|
||||||
|
|
||||||
|
**Steps:**
|
||||||
|
1. Search for any remaining imports: `grep -r "from.*resources/" src/`
|
||||||
|
2. Migrate any remaining usages
|
||||||
|
3. Delete the resource files
|
||||||
|
4. Update any barrel exports (index.ts files)
|
||||||
|
5. Run build to verify no import errors
|
||||||
|
|
||||||
|
**Current blockers:** `InfiniteScroll.svelte` still imports `InfiniteScrollResource` type
|
||||||
|
|
||||||
|
## Patterns and Best Practices
|
||||||
|
|
||||||
|
### Infinite Query Pattern
|
||||||
|
```typescript
|
||||||
|
import { createInfiniteQuery } from '@tanstack/svelte-query'
|
||||||
|
import { IsInViewport } from 'runed'
|
||||||
|
|
||||||
|
// Create the query with thunk for reactivity
|
||||||
|
const query = createInfiniteQuery(() => ({
|
||||||
|
...queryOptions.list(filters),
|
||||||
|
initialData: serverData ? {
|
||||||
|
pages: [{ results: serverData.items, page: 1, totalPages: serverData.totalPages }],
|
||||||
|
pageParams: [1]
|
||||||
|
} : undefined,
|
||||||
|
initialDataUpdatedAt: 0
|
||||||
|
}))
|
||||||
|
|
||||||
|
// Flatten and deduplicate results
|
||||||
|
const rawResults = $derived(query.data?.pages.flatMap((page) => page.results) ?? [])
|
||||||
|
const items = $derived(Array.from(new Map(rawResults.map((item) => [item.id, item])).values()))
|
||||||
|
|
||||||
|
// Infinite scroll with IsInViewport
|
||||||
|
let sentinelEl = $state<HTMLElement>()
|
||||||
|
const inViewport = new IsInViewport(() => sentinelEl, { rootMargin: '200px' })
|
||||||
|
|
||||||
|
$effect(() => {
|
||||||
|
if (inViewport.current && query.hasNextPage && !query.isFetchingNextPage && !query.isLoading) {
|
||||||
|
query.fetchNextPage()
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Debounced Search Pattern
|
||||||
|
```typescript
|
||||||
|
let searchQuery = $state('')
|
||||||
|
let debouncedSearchQuery = $state('')
|
||||||
|
let debounceTimer: ReturnType<typeof setTimeout> | undefined
|
||||||
|
|
||||||
|
$effect(() => {
|
||||||
|
const query = searchQuery
|
||||||
|
if (debounceTimer) clearTimeout(debounceTimer)
|
||||||
|
debounceTimer = setTimeout(() => {
|
||||||
|
debouncedSearchQuery = query
|
||||||
|
}, 300)
|
||||||
|
return () => { if (debounceTimer) clearTimeout(debounceTimer) }
|
||||||
|
})
|
||||||
|
|
||||||
|
// Use debouncedSearchQuery in the query, not searchQuery
|
||||||
|
const query = createInfiniteQuery(() => queryOptions.search(debouncedSearchQuery))
|
||||||
|
```
|
||||||
|
|
||||||
|
### Type Assertions for Conditional Queries
|
||||||
|
When a query can return different types based on conditions, use type assertions:
|
||||||
|
```typescript
|
||||||
|
const query = createInfiniteQuery(() => {
|
||||||
|
if (condition) {
|
||||||
|
return queryOptionsA()
|
||||||
|
}
|
||||||
|
return queryOptionsB() as unknown as ReturnType<typeof queryOptionsA>
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mutation Pattern
|
||||||
|
```typescript
|
||||||
|
import { useUpdateParty } from '$lib/api/mutations/party.mutations'
|
||||||
|
|
||||||
|
const updatePartyMutation = useUpdateParty()
|
||||||
|
|
||||||
|
function handleSave() {
|
||||||
|
updatePartyMutation.mutate(
|
||||||
|
{ partyId, updates },
|
||||||
|
{
|
||||||
|
onSuccess: () => { /* handle success */ },
|
||||||
|
onError: (error) => { /* handle error */ }
|
||||||
|
}
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Use mutation state for UI
|
||||||
|
{#if updatePartyMutation.isPending}
|
||||||
|
<span>Saving...</span>
|
||||||
|
{/if}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Known Issues
|
||||||
|
|
||||||
|
### Pre-existing Build Errors
|
||||||
|
The build has pre-existing errors unrelated to TanStack Query migration:
|
||||||
|
- `Cannot find module '$lib/paraglide/server'` in `hooks.server.ts`
|
||||||
|
- `Cannot find module '$lib/paraglide/runtime'` in `hooks.ts`
|
||||||
|
- `Cannot find module '$lib/paraglide/messages'` in various components
|
||||||
|
|
||||||
|
These are paraglide i18n setup issues and should be ignored when checking for migration-related errors.
|
||||||
|
|
||||||
|
### Duplicate Key Error Fix
|
||||||
|
When using infinite queries, the API may return duplicate items across pages. Always deduplicate:
|
||||||
|
```typescript
|
||||||
|
const rawResults = $derived(query.data?.pages.flatMap((page) => page.results) ?? [])
|
||||||
|
const items = $derived(Array.from(new Map(rawResults.map((item) => [item.id, item])).values()))
|
||||||
|
```
|
||||||
|
|
||||||
|
## File Locations
|
||||||
|
|
||||||
|
### Query Options Factories
|
||||||
|
- `src/lib/api/queries/party.queries.ts`
|
||||||
|
- `src/lib/api/queries/job.queries.ts`
|
||||||
|
- `src/lib/api/queries/user.queries.ts`
|
||||||
|
- `src/lib/api/queries/search.queries.ts`
|
||||||
|
|
||||||
|
### Mutation Hooks
|
||||||
|
- `src/lib/api/mutations/party.mutations.ts`
|
||||||
|
- `src/lib/api/mutations/grid.mutations.ts`
|
||||||
|
- `src/lib/api/mutations/job.mutations.ts`
|
||||||
|
|
||||||
|
### SSR Utilities
|
||||||
|
- `src/lib/query/ssr.ts`
|
||||||
|
|
||||||
|
### Reference Implementations
|
||||||
|
- `src/lib/components/sidebar/JobSelectionSidebar.svelte` - Simple infinite query
|
||||||
|
- `src/lib/components/sidebar/JobSkillSelectionSidebar.svelte` - Infinite query with search
|
||||||
|
- `src/lib/components/sidebar/SearchContent.svelte` - Infinite query with filters and deduplication
|
||||||
|
- `src/routes/teams/[id]/+page.svelte` - SSR with initialData
|
||||||
|
- `src/routes/[username]/+page.svelte` - Conditional queries (teams vs favorites)
|
||||||
|
- `src/routes/teams/explore/+page.svelte` - Simple infinite scroll page
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run TypeScript check
|
||||||
|
pnpm run check
|
||||||
|
|
||||||
|
# Run development server
|
||||||
|
pnpm run dev
|
||||||
|
|
||||||
|
# Check for resource class imports
|
||||||
|
grep -r "from.*resources/" src/
|
||||||
|
|
||||||
|
# Check for createInfiniteScrollResource usage
|
||||||
|
grep -r "createInfiniteScrollResource" src/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Branch Information
|
||||||
|
|
||||||
|
- Base branch: `svelte-main`
|
||||||
|
- PR #442 branch: `devin/1764405731-tanstack-query-migration-phase2`
|
||||||
Loading…
Reference in a new issue