From 0c7d5dd2aa3b606be3a86f4c83fdfadb650c5a8a Mon Sep 17 00:00:00 2001 From: JCEEE <0xjceee@proton.me> Date: Wed, 29 Jul 2026 10:07:29 +0100 Subject: [PATCH] add optimistic update ff --- AGENTS.md | 26 +++++++++++++++---- .../src/routes/[fam]/[username]/+page.svelte | 8 +++--- .../[fam]/[username]/bonuses/+page.svelte | 8 ++++-- .../[fam]/[username]/chores/+page.svelte | 20 +++++++++----- .../[fam]/[username]/rewards/+page.svelte | 2 +- 5 files changed, 46 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cddbb45..6d6b254 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,13 +105,29 @@ $effect(() => { let items = $state(famStore.initialized ? famStore.items : (data.items || [])); ``` -**Form action callbacks must call `famStore.applyRecord()`:** -```ts -// In use:enhance callback: -famStore.applyRecord('collection_name', record, 'create' | 'update' | 'delete'); +## Update Patterns + +Two patterns based on who's acting: + +| Pattern | Who | Frequency | Sensitivity | Optimistic? | Auth | +|---------|-----|-----------|-------------|-------------|------| +| Direct `fetch` + `memberApi` | Member | High (chore toggles) | None | Yes (instant UI, reconcile on response) | `x-device-token` header | +| Form action | Admin | Low (CRUD) | High (settings, members) | No — form is server-side, wait for round trip | httpOnly `session` cookie | + +**Member direct fetch** — optimistic UI via local state mutation, reconciled on response: +```svelte +let completions = $state(data.completions) +async function toggle(chore) { + // optimistic update + completions = [...completions, { id: 'optimistic-...', ... }] + try { + await memberApi.toggleCompletion(token, famId, chore.id, date) + // reconcile — remove optimistic, keep server truth + } catch { /* revert */ } +} ``` -The `famStore` has reactive `$state` properties and an `applyRecord()` method designed for instant UI feedback from form actions. Calling `applyRecord()` mutates the store directly — the UI updates immediately without waiting for PB SSE. The SSE subscription is a backup for multi-user sync only. Do NOT add `$effect` watchers to bridge the gap between form actions and reactive state. +**Admin form actions** — no optimistic `applyRecord` needed in `use:enhance` callbacks. The form action is a server round trip, and PB SSE pushes the change back through `famStore.handleRealtime()` within milliseconds. The famStore + SSE subscription is the single source of truth for cross-user sync. Do NOT add `$effect` watchers to bridge the gap between form actions and reactive state. ## UI Component Conventions diff --git a/frontend/src/routes/[fam]/[username]/+page.svelte b/frontend/src/routes/[fam]/[username]/+page.svelte index b83869f..ed0937b 100644 --- a/frontend/src/routes/[fam]/[username]/+page.svelte +++ b/frontend/src/routes/[fam]/[username]/+page.svelte @@ -380,7 +380,7 @@ import type { AssignedChore, Completion, ChoreTemplate, BonusConfig, Reward } fr {#each todays as c}
  • ✅ {choreNameFor(c.assignedChoreId)} -
    { return async (args) => handleResult(args, (d) => { if (d.revoked) famStore.applyRecord('completions', { id: d.id }, 'delete'); }); }} class="revoke-form"> + { return async (args) => handleResult(args, famStore.fam?.featureFlags?.optimisticUpdates ? (d) => { if (d.revoked) famStore.applyRecord('completions', { id: d.id }, 'delete'); } : undefined); }} class="revoke-form">
    @@ -405,7 +405,7 @@ import type { AssignedChore, Completion, ChoreTemplate, BonusConfig, Reward } fr {val} {#if targeted} -
    { return async (args: any) => handleResult(args, (d: any) => { if (d.records) { d.records.forEach((r: any) => famStore.applyRecord('rewards', r, 'create')); } }); }}> + { return async (args: any) => handleResult(args, famStore.fam?.featureFlags?.optimisticUpdates ? (d: any) => { if (d.records) d.records.forEach((r: any) => famStore.applyRecord('rewards', r, 'create')); } : undefined); }}>
    @@ -414,7 +414,7 @@ import type { AssignedChore, Completion, ChoreTemplate, BonusConfig, Reward } fr
    {:else} -
    { return async (args: any) => handleResult(args, (d: any) => { if (d.records) { d.records.forEach((r: any) => famStore.applyRecord('rewards', r, 'create')); } }); }}> + { return async (args: any) => handleResult(args, famStore.fam?.featureFlags?.optimisticUpdates ? (d: any) => { if (d.records) d.records.forEach((r: any) => famStore.applyRecord('rewards', r, 'create')); } : undefined); }}>
    diff --git a/frontend/src/routes/[fam]/[username]/bonuses/+page.svelte b/frontend/src/routes/[fam]/[username]/bonuses/+page.svelte index 1fd9cec..8c8e994 100644 --- a/frontend/src/routes/[fam]/[username]/bonuses/+page.svelte +++ b/frontend/src/routes/[fam]/[username]/bonuses/+page.svelte @@ -176,7 +176,9 @@ import type { const rec = result.data?.record; if (rec) { configs = [rec as BonusConfig, ...configs]; - famStore.applyRecord('bonus_configs', rec, 'create'); + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('bonus_configs', rec, 'create'); + } } showCreateModal = false; } @@ -189,7 +191,9 @@ import type { const updated = { ...editingConfig, ...editVals, rewardValue: editVals.rewardValue }; const idx = configs.findIndex((c) => c.id === editingConfig!.id); if (idx !== -1) configs[idx] = updated as BonusConfig; - famStore.applyRecord('bonus_configs', updated, 'update'); + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('bonus_configs', updated, 'update'); + } showEditModal = false; editingConfig = null; } diff --git a/frontend/src/routes/[fam]/[username]/chores/+page.svelte b/frontend/src/routes/[fam]/[username]/chores/+page.svelte index f1af52c..e27b354 100644 --- a/frontend/src/routes/[fam]/[username]/chores/+page.svelte +++ b/frontend/src/routes/[fam]/[username]/chores/+page.svelte @@ -81,7 +81,9 @@ const body = await res.json() if (body.record) { assigned = [body.record as AssignedChore, ...assigned] - famStore.applyRecord('assigned_chores', body.record, 'create') + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('assigned_chores', body.record, 'create') + } } } } @@ -121,7 +123,9 @@ const rec = result.data?.record if (rec) { templates = [rec as ChoreTemplate, ...templates] - famStore.applyRecord('chore_templates', rec, 'create') + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('chore_templates', rec, 'create') + } } } } @@ -139,7 +143,9 @@ value: editValue, customName: editCustomName || undefined, } as AssignedChore - famStore.applyRecord('assigned_chores', assigned[idx], 'update') + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('assigned_chores', assigned[idx], 'update') + } } } closeEdit() @@ -165,7 +171,9 @@ ? { ...a, frequency: editTplFreq, type: editTplType, value: editTplValue } : a ) as AssignedChore[] - famStore.applyRecord('chore_templates', templates[idx], 'update') + if (famStore.fam?.featureFlags?.optimisticUpdates) { + famStore.applyRecord('chore_templates', templates[idx], 'update') + } closeEditTemplate() } } @@ -203,7 +211,7 @@
    - { return async ({ result, formData }) => { if (result.type === 'success') { const id = formData.get('id'); templates = templates.filter((t) => t.id !== id) as ChoreTemplate[]; const rec = result.data.record; if (rec) famStore.applyRecord('chore_templates', { ...rec, id }, 'delete'); } }; }}> + { return async ({ result, formData }) => { if (result.type === 'success') { const id = formData.get('id'); templates = templates.filter((t) => t.id !== id) as ChoreTemplate[]; if (famStore.fam?.featureFlags?.optimisticUpdates) { const rec = result.data.record; if (rec) famStore.applyRecord('chore_templates', { ...rec, id }, 'delete'); } } }; }}> @@ -235,7 +243,7 @@ {a.type}
    {a.type === 'money' ? `£${Number(a.value).toFixed(2)}` : a.value}
    -
    e.stopPropagation()} use:enhance={() => { return async ({ result }) => { if (result.type === 'success') { const id = result.data.record?.id; if (id) { assigned = assigned.filter((x) => x.id !== id) as AssignedChore[]; famStore.applyRecord('assigned_chores', { id }, 'delete'); } } }; }}> + e.stopPropagation()} use:enhance={() => { return async ({ result }) => { if (result.type === 'success') { const id = result.data.record?.id; if (id) { assigned = assigned.filter((x) => x.id !== id) as AssignedChore[]; if (famStore.fam?.featureFlags?.optimisticUpdates) { famStore.applyRecord('assigned_chores', { id }, 'delete'); } } } }; }}>
    diff --git a/frontend/src/routes/[fam]/[username]/rewards/+page.svelte b/frontend/src/routes/[fam]/[username]/rewards/+page.svelte index 147373d..32697e5 100644 --- a/frontend/src/routes/[fam]/[username]/rewards/+page.svelte +++ b/frontend/src/routes/[fam]/[username]/rewards/+page.svelte @@ -96,7 +96,7 @@ {#if outstanding} -
    { return async (args: any) => { const d = args.result.data || {}; if (d.error) showToast(d.error); else if (args.result.type === 'success') { if (d.record) famStore.applyRecord('rewards', d.record, 'update'); fire(); } }; }}> + { return async (args: any) => { const d = args.result.data || {}; if (d.error) showToast(d.error); else if (args.result.type === 'success') { if (d.record && famStore.fam?.featureFlags?.optimisticUpdates) famStore.applyRecord('rewards', d.record, 'update'); fire(); } }; }}>