coding-os 0.3.2__py3-none-any.whl

core/skills/state-management/references/tanstack-query-recipes.md

@@ -0,0 +1,301 @@
+# TanStack Query — Recipe Book
+
+Patterns that come up over and over in real apps. Each one is something you'll grep for at 11pm.
+
+## Query Key Conventions
+
+Hierarchical, sortable, predictable. Use the **factory pattern** for type-safety.
+
+```typescript
+// mobile/src/delivery/queries/keys.ts
+export const queryKeys = {
+  lessons: {
+    all:          ['lessons'] as const,
+    lists:        () => [...queryKeys.lessons.all, 'list'] as const,
+    list:         (filters: LessonFilters) => [...queryKeys.lessons.lists(), filters] as const,
+    details:      () => [...queryKeys.lessons.all, 'detail'] as const,
+    detail:       (id: LessonID) => [...queryKeys.lessons.details(), id] as const,
+    completion:   (id: LessonID) => [...queryKeys.lessons.detail(id), 'completion'] as const,
+  },
+  user: {
+    all:     ['user'] as const,
+    me:      () => [...queryKeys.user.all, 'me'] as const,
+    profile: (id: UserID) => [...queryKeys.user.all, id, 'profile'] as const,
+  },
+} as const;
+
+// Usage:
+useQuery({ queryKey: queryKeys.lessons.detail(id), queryFn: () => ... });
+
+// Invalidate all lesson queries:
+queryClient.invalidateQueries({ queryKey: queryKeys.lessons.all });
+
+// Invalidate just lists (not details):
+queryClient.invalidateQueries({ queryKey: queryKeys.lessons.lists() });
+```
+
+## `staleTime` vs `gcTime`
+
+- **`staleTime`** — how long the data is considered fresh. Within this window, refetch on remount is skipped.
+- **`gcTime`** — how long unused query data lives in the cache before garbage collection.
+
+| Type of data | `staleTime` | `gcTime` |
+|---|---|---|
+| User profile (rarely changes) | 5 min | 24 h |
+| Lesson list | 30 sec | 24 h |
+| Real-time chat messages | 0 (always stale → refetch) | 1 h |
+| Static config (feature flags) | 5 min | 24 h |
+| Search results | 0 | 5 min (low value) |
+
+## Infinite Queries (Cursor Pagination)
+
+```typescript
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+export function useLessons(filter: LessonFilter) {
+  return useInfiniteQuery({
+    queryKey: queryKeys.lessons.list(filter),
+    queryFn: ({ pageParam }) => listLessons.execute({ filter, cursor: pageParam }),
+    initialPageParam: null as string | null,
+    getNextPageParam: (lastPage) => lastPage.next_cursor,  // null = no more
+    staleTime: 30_000,
+  });
+}
+
+// In the screen:
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useLessons(filter);
+const items = data?.pages.flatMap((p) => p.data) ?? [];
+
+<FlashList
+  data={items}
+  estimatedItemSize={88}
+  onEndReached={() => hasNextPage && !isFetchingNextPage && fetchNextPage()}
+  onEndReachedThreshold={0.5}
+/>
+```
+
+## Prefetch on Navigation
+
+```typescript
+// On the list screen, prefetch the detail when the user touches a row.
+const onPressLesson = (lesson: Lesson) => {
+  queryClient.prefetchQuery({
+    queryKey: queryKeys.lessons.detail(lesson.id),
+    queryFn: () => getLesson.execute({ lessonId: lesson.id }),
+    staleTime: 60_000,
+  });
+  navigation.navigate('Lesson', { lessonId: lesson.id });
+};
+```
+
+When the detail screen mounts, the data is already there — no spinner.
+
+## Dependent Queries
+
+Query B needs the result of Query A. Use `enabled`.
+
+```typescript
+const { data: user } = useQuery({ queryKey: queryKeys.user.me(), queryFn: fetchMe });
+const { data: lessons } = useQuery({
+  queryKey: queryKeys.lessons.list({ userId: user?.id }),
+  queryFn: () => listLessons.execute({ userId: user!.id }),
+  enabled: !!user?.id,
+});
+```
+
+## `useMutation` Flow with Cache Updates
+
+```typescript
+const completeLesson = useMutation({
+  mutationFn: (input: { lessonId: LessonID }) => completeLessonUseCase.execute(input),
+
+  // Optimistic UI: snapshot, write the optimistic value.
+  onMutate: async ({ lessonId }) => {
+    await queryClient.cancelQueries({ queryKey: queryKeys.lessons.detail(lessonId) });
+    const prev = queryClient.getQueryData<Lesson>(queryKeys.lessons.detail(lessonId));
+    queryClient.setQueryData<Lesson>(queryKeys.lessons.detail(lessonId), (old) =>
+      old ? { ...old, state: 'completed' } : old
+    );
+    return { prev };
+  },
+
+  // Rollback on failure.
+  onError: (_err, { lessonId }, ctx) => {
+    if (ctx?.prev) queryClient.setQueryData(queryKeys.lessons.detail(lessonId), ctx.prev);
+  },
+
+  // Always sync with server truth.
+  onSettled: (_data, _err, { lessonId }) => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.lessons.detail(lessonId) });
+    queryClient.invalidateQueries({ queryKey: queryKeys.lessons.lists() });
+  },
+});
+```
+
+## Polling
+
+```typescript
+const { data } = useQuery({
+  queryKey: ['order', orderId],
+  queryFn: () => getOrder.execute({ orderId }),
+  refetchInterval: (query) => {
+    const order = query.state.data;
+    if (!order) return 5_000;
+    if (order.status === 'paid' || order.status === 'failed') return false;  // stop polling
+    return 3_000;
+  },
+});
+```
+
+The `refetchInterval` callback gets the current query state — return `false` to stop.
+
+## Suspense Mode (Optional)
+
+For React 19 / RN 0.76+ with Suspense support, opt in per query:
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+
+function Lesson({ id }: { id: LessonID }) {
+  // No isLoading; component suspends until data is ready.
+  const { data } = useSuspenseQuery({ queryKey: queryKeys.lessons.detail(id), queryFn: ... });
+  return <Text>{data.title}</Text>;
+}
+
+// In the parent:
+<Suspense fallback={<CenteredSpinner />}>
+  <Lesson id={lessonId} />
+</Suspense>
+<ErrorBoundary fallback={<ErrorState />}>
+  ...
+</ErrorBoundary>
+```
+
+Cleaner code, but you give up granular per-query loading UI. Use selectively.
+
+## Network-Aware Behavior
+
+```typescript
+// Disable retries when offline (avoids futile attempts):
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      networkMode: 'offlineFirst',   // serve cache when offline
+      retry: 3,
+    },
+    mutations: {
+      networkMode: 'offlineFirst',   // queue mutation when offline (paired with retry)
+    },
+  },
+});
+```
+
+For full offline-first with a sync queue, see `mobile-fundamentals` offline section.
+
+## Persistence Across App Launches
+
+```typescript
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import { MMKV } from 'react-native-mmkv';
+
+const mmkv = new MMKV({ id: 'tanstack-query' });
+const persister = createSyncStoragePersister({
+  storage: {
+    getItem: (k) => mmkv.getString(k) ?? null,
+    setItem: (k, v) => mmkv.set(k, v),
+    removeItem: (k) => mmkv.delete(k),
+  },
+});
+
+<PersistQueryClientProvider client={queryClient} persistOptions={{
+  persister,
+  maxAge: 24 * 3600_000,
+  buster: APP_VERSION,           // bust on app update
+  dehydrateOptions: {
+    shouldDehydrateQuery: (q) => q.state.status === 'success' && q.queryKey[0] !== 'auth',
+  },
+}}>
+  <RootNavigator />
+</PersistQueryClientProvider>
+```
+
+Don't persist auth state via TanStack — keep it in memory + Keychain.
+
+## Selectors (Render Optimization)
+
+```typescript
+// Re-renders only when `title` changes, not the whole lesson.
+const title = useQuery({
+  queryKey: queryKeys.lessons.detail(id),
+  queryFn: () => getLesson.execute({ lessonId: id }),
+  select: (lesson) => lesson.title,
+});
+```
+
+The `select` runs on every fetch but only re-renders the component when the SELECTED value's identity changes. Memoize complex selectors with `useCallback`.
+
+## Cancel In-Flight on Unmount
+
+Default behavior — TanStack cancels stale queries when the component unmounts. To make this work with your `queryFn`, propagate the abort signal:
+
+```typescript
+useQuery({
+  queryKey: ['big-doc', id],
+  queryFn: ({ signal }) => fetch(`/docs/${id}`, { signal }).then((r) => r.json()),
+});
+```
+
+Pass `signal` to `axios`, `fetch`, your API client. Saves bandwidth and prevents stale state-set on unmounted components.
+
+## Error Boundaries
+
+Pair with React's `ErrorBoundary` (or `react-error-boundary`):
+
+```typescript
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+import { ErrorBoundary } from 'react-error-boundary';
+
+<QueryErrorResetBoundary>
+  {({ reset }) => (
+    <ErrorBoundary
+      onReset={reset}
+      fallbackRender={({ resetErrorBoundary }) => (
+        <View>
+          <Text>Something went wrong</Text>
+          <Button title="Retry" onPress={resetErrorBoundary} />
+        </View>
+      )}
+    >
+      <Lesson id={lessonId} />
+    </ErrorBoundary>
+  )}
+</QueryErrorResetBoundary>
+```
+
+Set `throwOnError: true` on queries that should propagate to the boundary instead of returning `error` state.
+
+## Devtools (RN)
+
+```bash
+yarn add -D @tanstack/react-query-devtools react-native-flipper
+```
+
+Plug into Flipper or use the standalone DevTools webview. Indispensable for debugging cache state.
+
+## Anti-Patterns
+
+1. **Mixing query data with Zustand** — pick one home for each piece of data.
+2. **`refetchOnMount: 'always'`** + short staleTime — every screen mount = network call.
+3. **Stringly-typed query keys** (`['lesson-' + id]`) — defeats invalidation patterns.
+4. **`enabled: !!data && !!otherData && condition3`** — extract to a `useMemo` boolean.
+5. **`queryFn` defined inline (new ref every render)** — TanStack handles this OK but it's confusing; use named functions.
+6. **`useQuery` with no `queryKey`** — won't compile; runtime if dynamic.
+7. **`onSuccess` doing navigation** — race conditions; do navigation in the component effect or via mutation callback.
+8. **Shoehorning subscriptions (WebSocket) into `useQuery`** — use a custom hook that updates `queryClient.setQueryData` from the socket; keep `useQuery` as the read interface.
+
+## Source Material
+
+- TanStack Query v5 docs — primary source.
+- TkDodo's blog (Dominik Dorfmeister, TanStack maintainer): <https://tkdodo.eu/blog/all>
+- Mark Erikson — *Why I Prefer React Query Over Redux for Server State*.

core/skills/state-management/references/zustand-recipes.md

@@ -0,0 +1,364 @@
+# Zustand — Recipe Book
+
+Patterns for global UI state. Cross-platform (React + RN); examples target RN with MMKV persistence.
+
+## Minimum Store
+
+```typescript
+// mobile/src/delivery/state/themeStore.ts
+import { create } from 'zustand';
+
+interface ThemeState {
+  mode: 'light' | 'dark' | 'system';
+  setMode: (mode: ThemeState['mode']) => void;
+}
+
+export const useThemeStore = create<ThemeState>()((set) => ({
+  mode: 'system',
+  setMode: (mode) => set({ mode }),
+}));
+```
+
+That's it. No provider, no boilerplate. Use anywhere:
+
+```typescript
+const mode = useThemeStore((s) => s.mode);
+const setMode = useThemeStore((s) => s.setMode);
+```
+
+## Selector Discipline
+
+The single biggest performance lever. Always select; never grab the whole store.
+
+```typescript
+// BAD — re-renders on ANY state change.
+const store = useThemeStore();
+
+// GOOD — re-renders only when `mode` changes.
+const mode = useThemeStore((s) => s.mode);
+
+// Multi-slice — call useStore twice; it does shallow equality per call.
+const mode = useThemeStore((s) => s.mode);
+const accent = useThemeStore((s) => s.accent);
+
+// Or use `useShallow` for object slices:
+import { useShallow } from 'zustand/react/shallow';
+const { mode, accent } = useThemeStore(useShallow((s) => ({ mode: s.mode, accent: s.accent })));
+```
+
+## Persistence (MMKV in RN)
+
+```typescript
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import { MMKV } from 'react-native-mmkv';
+
+const mmkv = new MMKV({ id: 'app' });
+const mmkvStorage = {
+  getItem:    (key: string) => mmkv.getString(key) ?? null,
+  setItem:    (key: string, value: string) => { mmkv.set(key, value); },
+  removeItem: (key: string) => { mmkv.delete(key); },
+};
+
+interface SettingsState {
+  notifications: { lessons: boolean; social: boolean };
+  hapticEnabled: boolean;
+  toggleLessons: () => void;
+  toggleSocial: () => void;
+  setHaptic: (on: boolean) => void;
+}
+
+export const useSettingsStore = create<SettingsState>()(
+  persist(
+    (set) => ({
+      notifications: { lessons: true, social: false },
+      hapticEnabled: true,
+      toggleLessons: () => set((s) => ({
+        notifications: { ...s.notifications, lessons: !s.notifications.lessons },
+      })),
+      toggleSocial: () => set((s) => ({
+        notifications: { ...s.notifications, social: !s.notifications.social },
+      })),
+      setHaptic: (on) => set({ hapticEnabled: on }),
+    }),
+    {
+      name: 'settings-store',
+      version: 1,
+      storage: createJSONStorage(() => mmkvStorage),
+      // Only persist what the user expects restored:
+      partialize: (state) => ({
+        notifications: state.notifications,
+        hapticEnabled: state.hapticEnabled,
+      }),
+      // On bumped version: migrate or wipe.
+      migrate: (persisted: any, prevVersion) => {
+        if (prevVersion < 1) {
+          return { ...persisted, hapticEnabled: persisted.haptic ?? true };
+        }
+        return persisted;
+      },
+    }
+  )
+);
+```
+
+Web equivalent: replace MMKV with `localStorage` (`createJSONStorage(() => localStorage)`).
+
+### What NEVER to Persist
+
+- **Auth tokens** — Keychain only.
+- **PII** — encrypt at rest if persisted.
+- **Server data** — TanStack Query has its own persistence.
+- **Transient UI state** — toast queue, modal-open flags.
+
+## Async Actions
+
+Async logic in actions is fine — Zustand doesn't care about returns being promises.
+
+```typescript
+interface AuthState {
+  user: User | null;
+  status: 'idle' | 'loading' | 'authenticated' | 'error';
+  error: string | null;
+  signIn: (email: string, password: string) => Promise<void>;
+  signOut: () => Promise<void>;
+}
+
+export const useAuthStore = create<AuthState>()((set, get) => ({
+  user: null,
+  status: 'idle',
+  error: null,
+
+  signIn: async (email, password) => {
+    set({ status: 'loading', error: null });
+    try {
+      const user = await signInUseCase.execute({ email, password });
+      set({ user, status: 'authenticated' });
+    } catch (e) {
+      set({ status: 'error', error: e.message });
+      throw e;
+    }
+  },
+
+  signOut: async () => {
+    await signOutUseCase.execute();
+    set({ user: null, status: 'idle', error: null });
+  },
+}));
+```
+
+⚠️ But beware: at this point you're rebuilding TanStack Query. For server-state patterns (loading states, retries, dedupe, cache), use TanStack Query. Use Zustand for auth-status flag + user pointer; keep the actual user data flowing through `useQuery({ queryKey: ['user', 'me'] })`.
+
+## Computed Values
+
+For derived state that's used in multiple places, compute INSIDE the selector:
+
+```typescript
+// Don't add `isAuthenticated: boolean` to the store — derive it.
+const isAuthenticated = useAuthStore((s) => s.status === 'authenticated' && s.user !== null);
+```
+
+For expensive derivations, memoize in the consumer:
+
+```typescript
+const messages = useMessagesStore((s) => s.messages);
+const sortedMessages = useMemo(() => {
+  return [...messages].sort((a, b) => b.createdAt - a.createdAt);
+}, [messages]);
+```
+
+For derived state used in a SELECTOR, use `zustand/middleware/computed` (from third-party libs) or just pre-compute in the action:
+
+```typescript
+const useCartStore = create((set) => ({
+  items: [],
+  total: 0,
+  add: (item) => set((s) => {
+    const items = [...s.items, item];
+    return { items, total: items.reduce((sum, i) => sum + i.price, 0) };
+  }),
+}));
+```
+
+The pre-compute pattern keeps `total` always-fresh without a separate selector.
+
+## Subscribing Outside React
+
+```typescript
+import { useThemeStore } from './themeStore';
+
+// One-shot read:
+const currentMode = useThemeStore.getState().mode;
+
+// Subscribe to changes (e.g., in a non-React module like an analytics SDK):
+const unsub = useThemeStore.subscribe(
+  (state) => state.mode,
+  (mode, prevMode) => {
+    if (mode !== prevMode) analytics.track('theme_changed', { mode });
+  }
+);
+// unsub() to stop.
+```
+
+Never call `useThemeStore.getState()` inside a component — bypasses subscription. Use the hook.
+
+## Slicing Big Stores
+
+Once a store grows past ~150 LOC, split into slices:
+
+```typescript
+// mobile/src/delivery/state/slices/themeSlice.ts
+import type { StateCreator } from 'zustand';
+
+export interface ThemeSlice {
+  mode: 'light' | 'dark' | 'system';
+  setMode: (m: ThemeSlice['mode']) => void;
+}
+
+export const createThemeSlice: StateCreator<ThemeSlice & SettingsSlice, [], [], ThemeSlice> =
+  (set) => ({
+    mode: 'system',
+    setMode: (mode) => set({ mode }),
+  });
+```
+
+```typescript
+// mobile/src/delivery/state/slices/settingsSlice.ts
+export interface SettingsSlice {
+  hapticEnabled: boolean;
+  setHaptic: (on: boolean) => void;
+}
+
+export const createSettingsSlice: StateCreator<ThemeSlice & SettingsSlice, [], [], SettingsSlice> =
+  (set) => ({
+    hapticEnabled: true,
+    setHaptic: (on) => set({ hapticEnabled: on }),
+  });
+```
+
+```typescript
+// mobile/src/delivery/state/userPrefsStore.ts
+import { create } from 'zustand';
+import { createThemeSlice, type ThemeSlice } from './slices/themeSlice';
+import { createSettingsSlice, type SettingsSlice } from './slices/settingsSlice';
+
+export const useUserPrefsStore = create<ThemeSlice & SettingsSlice>()((...a) => ({
+  ...createThemeSlice(...a),
+  ...createSettingsSlice(...a),
+}));
+```
+
+For most apps, prefer **multiple small stores** over one big sliced store. Coupling stores together via slices makes them harder to refactor.
+
+## Resetting State (Logout)
+
+```typescript
+const initialState = {
+  user: null,
+  status: 'idle' as const,
+  error: null,
+};
+
+export const useAuthStore = create<AuthState>()((set) => ({
+  ...initialState,
+  signIn: ...,
+  signOut: () => set(initialState),
+}));
+```
+
+For wiping ALL stores on logout (auth, prefs, cart, draft):
+
+```typescript
+// mobile/src/delivery/state/resetAllStores.ts
+import { useAuthStore } from './authStore';
+import { useCartStore } from './cartStore';
+import { useDraftStore } from './draftStore';
+
+export function resetAllStoresOnLogout() {
+  useAuthStore.getState().reset?.();
+  useCartStore.getState().reset?.();
+  useDraftStore.getState().reset?.();
+}
+```
+
+Each store exposes a `reset` method. Call from the logout flow + on user-switch.
+
+## Subscribing to Selectors
+
+```typescript
+import { create } from 'zustand';
+import { subscribeWithSelector } from 'zustand/middleware';
+
+const useStore = create<State>()(
+  subscribeWithSelector((set) => ({
+    count: 0,
+    increment: () => set((s) => ({ count: s.count + 1 })),
+  }))
+);
+
+// Subscribe to changes of a specific slice:
+const unsub = useStore.subscribe(
+  (s) => s.count,
+  (count) => console.log('count changed', count),
+  { equalityFn: Object.is }
+);
+```
+
+Useful for: bridging to non-React code (background sync triggers, analytics).
+
+## Devtools
+
+```typescript
+import { devtools } from 'zustand/middleware';
+
+export const useStore = create<State>()(
+  devtools((set) => ({ ... }), { name: 'AppStore' })
+);
+```
+
+Hooks into Redux DevTools Extension. RN: pair with Flipper.
+
+## Testing Stores
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { useAuthStore } from './authStore';
+
+describe('authStore', () => {
+  beforeEach(() => useAuthStore.getState().signOut());
+
+  it('signs in successfully', async () => {
+    await useAuthStore.getState().signIn('user@example.com', 'pw');
+    const state = useAuthStore.getState();
+    expect(state.user).toEqual(expect.objectContaining({ email: 'user@example.com' }));
+    expect(state.status).toBe('authenticated');
+  });
+});
+```
+
+For component tests that depend on store state, set state directly:
+
+```typescript
+beforeEach(() => {
+  useAuthStore.setState({ user: { id: 'usr_1', email: 'a@b.com' }, status: 'authenticated' });
+});
+```
+
+## Anti-Patterns
+
+1. **One mega-store** — violates separation of concerns; every change re-renders everything.
+2. **Async fetch in store action** that duplicates a use case — call the use case from the store action, don't reimplement.
+3. **Mutating state directly** — Zustand uses Object.assign internally; mutation breaks referential equality.
+4. **`useStore()` (no selector)** — re-renders on every change.
+5. **`getState()` in render** — bypasses subscription.
+6. **Subscribing in render** — `useEffect` for subscriptions.
+7. **Persisting auth tokens** — Keychain, never JSON.
+8. **No store version** — schema change = corrupt persisted state on user devices.
+9. **Async actions that do navigation** — couples store to router; pass a callback or use events.
+10. **Storing functions in state** — they don't serialize; `partialize` strips them; behavior surprising.
+
+## Source Material
+
+- Zustand README — primary source: <https://github.com/pmndrs/zustand>
+- TkDodo — *Working with Zustand*.
+- React Native MMKV docs — for the storage adapter.