null/BillTracker
null
/
BillTracker
1
0
Fork 0
Code Issues 4 Pull Requests Packages Projects Releases 1 Wiki Activity

docs(history): TS migration Phase A/B + 'what TypeScript caught' achievements 

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
null 2026-07-04 21:13:37 -05:00
parent ea531f06c7
commit bb3e9f551c
1 changed files with 14 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
HISTORY.md
View File

@ -9,6 +9,20 @@
- **[Client] Typed the API client (`client/api.js` → `api.ts`) — the fetch layer's infrastructure** — the central request layer is now TypeScript: a generic `_fetch<T>` and `get`/`post`/`put`/`patch`/`del<T>` helpers, an `ApiError` interface carrying the server's `status`/`code`/`details`/`data`, a `QueryParams` type for the query-string builder, and `File`-typed upload helpers. Endpoint **response** shapes are typed incrementally — most methods resolve to `Promise<unknown>` for now (callers narrow), with the handful already consumed by typed `.ts` files given real shapes: `quickPay` → `PaymentRecord` (`id`), `togglePaid` → `TogglePaidResult` (`paymentId?`), `settings` → a settings map. Doing so immediately surfaced a **latent narrowing bug** in `usePaymentActions`: the un-pay Undo closure read `result.paymentId` (now typed `number | undefined`) inside a deferred async callback where TS correctly re-widens the `if`-narrowed value — fixed by capturing the id in a const. The 16 files that imported `@/api.js` with an explicit extension were normalized to `@/api` so Vite/TS resolve the `.ts`. Verified end-to-end: typecheck + lint + build + 48 client tests, and the **17/17 e2e probe** (every page renders, all API paths respond) confirms the central-module rename is runtime-safe. - **[Client] Typed the API client (`client/api.js` → `api.ts`) — the fetch layer's infrastructure** — the central request layer is now TypeScript: a generic `_fetch<T>` and `get`/`post`/`put`/`patch`/`del<T>` helpers, an `ApiError` interface carrying the server's `status`/`code`/`details`/`data`, a `QueryParams` type for the query-string builder, and `File`-typed upload helpers. Endpoint **response** shapes are typed incrementally — most methods resolve to `Promise<unknown>` for now (callers narrow), with the handful already consumed by typed `.ts` files given real shapes: `quickPay` → `PaymentRecord` (`id`), `togglePaid` → `TogglePaidResult` (`paymentId?`), `settings` → a settings map. Doing so immediately surfaced a **latent narrowing bug** in `usePaymentActions`: the un-pay Undo closure read `result.paymentId` (now typed `number | undefined`) inside a deferred async callback where TS correctly re-widens the `if`-narrowed value — fixed by capturing the id in a const. The 16 files that imported `@/api.js` with an explicit extension were normalized to `@/api` so Vite/TS resolve the `.ts`. Verified end-to-end: typecheck + lint + build + 48 client tests, and the **17/17 e2e probe** (every page renders, all API paths respond) confirms the central-module rename is runtime-safe.
- **[Client] Typed the React Query hooks (`hooks/useQueries.js` → `.ts`) — and it caught dead config** — the shared `useTracker`/`useBills`/`useSummary`/`useSpending*`/`useSnowball*`/`useBankLedger`/etc. hooks are now TypeScript (typed params + `QueryParams`-typed query builders, exported from `api.ts`). Converting surfaced that three hooks passed **`cacheTime`** to `useQuery` — an option **React Query v5 renamed to `gcTime` and silently ignores** (so those caches were being GC'd at the 5-min default, not the intended 30 min / 2 hr). TypeScript rejected the unknown property; renamed to `gcTime` so the intended cache-retention actually takes effect (memory-retention only — no fetch/correctness change). Query result data is `unknown` until the endpoint response shapes are typed. Verified: typecheck + lint + build + 48 tests + 17/17 e2e probe. - **[Client] Typed the React Query hooks (`hooks/useQueries.js` → `.ts`) — and it caught dead config** — the shared `useTracker`/`useBills`/`useSummary`/`useSpending*`/`useSnowball*`/`useBankLedger`/etc. hooks are now TypeScript (typed params + `QueryParams`-typed query builders, exported from `api.ts`). Converting surfaced that three hooks passed **`cacheTime`** to `useQuery` — an option **React Query v5 renamed to `gcTime` and silently ignores** (so those caches were being GC'd at the 5-min default, not the intended 30 min / 2 hr). TypeScript rejected the unknown property; renamed to `gcTime` so the intended cache-retention actually takes effect (memory-retention only — no fetch/correctness change). Query result data is `unknown` until the endpoint response shapes are typed. Verified: typecheck + lint + build + 48 tests + 17/17 e2e probe.
- **[Client] Phase A — typed the API response shapes with branded money** — new `client/types.ts` domain module: every money field branded (`Dollars` for bill/payment/tracker/summary amounts; **`Cents` for raw bank-transaction amounts, which stay cents on the wire** — the complement that keeps `formatCentsUSD` and `formatUSD` from being swapped). Reverse-engineered from the server serializers: `TrackerResponse` (summary/bank_tracking/cashflow/rows), `Bill`, `Payment`, `Category`, `DriftBill`, `AutopaySuggestion`, `AmountSuggestion`, `AutopayStats`, `BankTransaction`, `TimelineBill`. `api.tracker/bills/payments/categories/…` now return these, so the brand flows from the fetch layer into `trackerUtils` (row money upgraded from `number` → `Dollars`; `paymentSummary` re-brands via `asDollars`).
- **[Client] Phase B — converting components/pages `.jsx` → `.tsx` (in progress, ~80/129 files)** — done: **all 22 `ui/*` primitives** + `ThemeContext`; the **entire `components/tracker/` dir** (18 files — the home page) where `fmt(row.expected_amount)` now type-checks against `Dollars`; the **entire `components/bill-modal/` dir + `BillModal.tsx`** (the 1092-line add/edit form reached from 9 entry points); the **app shell** (`App`/`main`/`useAuth`/`Layout`/`Sidebar`/routing; `index.html` entry → `main.tsx`); app-wide commons (`ErrorBoundary` class, `PageTransition`, `StatusBadge`, `MarkdownText`, `SummaryCard`, `ReleaseNotesDialog`); the `snowball/` + `transactions/` dirs; and several pages. **A required infra fix:** Tailwind's `content` glob was `./client/**/*.{js,jsx}` — it never scanned `.tsx`, so any class used *only* in a converted file generated **no CSS** (the release-notes dialog's `left-[50%] top-[50%]` centering vanished → modal rendered off-screen). typecheck/build/48-tests all passed; only the **e2e probe** caught it. Fixed to `{js,jsx,ts,tsx}`. Remaining: ~20 pages + `data/`/admin dirs + a few loose components — all mechanical.
### 🏆 What the TypeScript migration caught (real defects, not just types)
- **The cents/dollars bug class is now unrepresentable** — the whole point of the branded `Dollars`/`Cents` types: a typed caller **physically cannot** format cents as dollars (the 100×-too-big bug, cf. QA-B9-01) or pass a bank-transaction amount to `formatUSD`. A bare number at a `fmt()` boundary is a compile error.
- **Dead React Query v5 config** — three hooks passed `cacheTime`, silently ignored since the v5 `gcTime` rename; caches were GC'd at the 5-min default instead of the intended 30 min / 2 hr. Fixed.
- **A latent narrowing bug** — the un-pay Undo closure in `usePaymentActions` read `result.paymentId` inside a deferred async callback where TS correctly re-widens the `if`-narrowed value; captured the id in a const.
- **A dead prop** — `App` passed `mainContentId` to `TrackerPage`, which takes no params. Removed.
- **A `never`-typed context** — `createContext(null)` made `useContext`'s post-guard return `never`, so `setTheme` (and the auth context methods) were uncallable. Typed the context value.
- **A CSS build gap invisible to typecheck/build/tests** — the Tailwind `.tsx` glob omission above; the **e2e probe** was the only gate that caught it, reinforcing that a passing build ≠ runtime-safe for a `.tsx` rename touching many files.
- **Dead code with broken calls** — `PrivacyAdminCard` was imported nowhere yet called non-existent `api.privacySettings`/`setPrivacySettings` (the geolocation toggle actually lives on `/profile/settings`). Deleted rather than converted.
### 🧪 Money-service test coverage ### 🧪 Money-service test coverage
- **[Tests] Covered two untested money-critical services** — the manual-vs-bank payment source-of-truth (`paymentAccountingService`) and the analytics month-window math (`analyticsService`) had no dedicated tests. Added `tests/paymentAccountingService.test.js` (bank-backed predicate, the accounting-active SQL fragment, and the core invariant: a bank payment overrides a provisional manual payment so it isn't double-counted, restores the balance, and the manual payment counts again with its balance re-applied when the override is removed) and `tests/analyticsService.test.js` (month key/label/addMonths/monthEndDate/buildMonths with year-boundary + leap-year edges, and `validateSummaryQuery` defaults/range errors). (Tracker X2) - **[Tests] Covered two untested money-critical services** — the manual-vs-bank payment source-of-truth (`paymentAccountingService`) and the analytics month-window math (`analyticsService`) had no dedicated tests. Added `tests/paymentAccountingService.test.js` (bank-backed predicate, the accounting-active SQL fragment, and the core invariant: a bank payment overrides a provisional manual payment so it isn't double-counted, restores the balance, and the manual payment counts again with its balance re-applied when the override is removed) and `tests/analyticsService.test.js` (month key/label/addMonths/monthEndDate/buildMonths with year-boundary + leap-year edges, and `validateSummaryQuery` defaults/range errors). (Tracker X2)