Skip to content

Open source personal finance application

feat: realtime cross-device sync via Convex subscriptions

Ilya Komichevafc318230c82
diff --git a/app/components/app/useInitApp.ts b/app/components/app/useInitApp.ts
index 25b30c68..a867fd6d 100644
--- a/app/components/app/useInitApp.ts
+++ b/app/components/app/useInitApp.ts
@@ -16,6 +16,7 @@ import { userSettingsSchema } from '~/components/user/types'
import { useUserStore } from '~/components/user/useUserStore'
import { useWalletsStore } from '~/components/wallets/useWalletsStore'
import { hasAuthCookie } from '~/composables/useAuthCookie'
+import { startAllRealtime } from '~/composables/useRealtimeSync'
import { blockPersist, unblockPersist } from '~/composables/useStoreSync'
import { createLogger } from '~/utils/logger'
@@ -122,6 +123,9 @@ export function useInitApp() {
])
await replayOfflineQueue()
+ // Subscriptions must start AFTER initial sync so `since` is meaningful
+ // and AFTER replay so our own replayed ops are in inFlightOps first.
+ startAllRealtime().catch(e => createLogger('app').error('startAllRealtime failed', e))
}
catch (e) {
createLogger('app').error('loadDataFromDB failed', e)
diff --git a/app/components/categories/useCategoriesStore.ts b/app/components/categories/useCategoriesStore.ts
index 71c73d8b..1bd68974 100644
--- a/app/components/categories/useCategoriesStore.ts
+++ b/app/components/categories/useCategoriesStore.ts
@@ -9,7 +9,7 @@ import { useDemo } from '~/components/demo/useDemo'
import { STORAGE_KEYS } from '~/components/offline/storageKeys'
import { TrnType } from '~/components/trns/types'
import { useTrnsStore } from '~/components/trns/useTrnsStore'
-import { createDebouncedPersist, handleMutationResult, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
+import { createDebouncedPersist, handleMutationResult, isInFlight, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
import { createLogger } from '~/utils/logger'
const adjustment: CategoryItem = {
@@ -31,6 +31,7 @@ const transfer: CategoryItem = {
}
type CategoriesStore = {
+ applyRealtimePatch: (patch: { deletedIds: string[], docs: { [k: string]: unknown, _creationTime: number, _id: string, userId: string }[], serverTime: number, truncated: boolean }) => number | null
categoriesForBeParent: ComputedRef<CategoryId[]>
categoriesIdsForTrnValues: ComputedRef<CategoryId[]>
categoriesRootIds: ComputedRef<CategoryId[]>
@@ -44,6 +45,7 @@ type CategoriesStore = {
initCategories: () => void
isTransactible: (categoryId: CategoryId) => boolean
items: import('vue').ShallowRef<Categories>
+ lastSyncedAt: import('vue').Ref<number>
recentCategoriesIds: ComputedRef<CategoryId[]>
saveCategory: (params: AddCategoryParams) => Promise<RemapInfo | void> | void
setCategories: (values: Categories | null) => void
@@ -150,6 +152,8 @@ export const useCategoriesStore = defineStore('categories', (): CategoriesStore
const debouncedPersist = createDebouncedPersist<Categories>(STORAGE_KEYS.categories)
+ const lastSyncedAt = ref(0)
+
async function initCategories() {
try {
const { api, client } = useConvexClientWithApi()
@@ -160,12 +164,62 @@ export const useCategoriesStore = defineStore('categories', (): CategoriesStore
data = await mergeOfflineOps(data, 'categories') as Categories
setCategories(data)
+ lastSyncedAt.value = Date.now()
}
catch (e) {
logger.error('init failed', e)
}
}
+ type ConvexCategoryDoc = { [key: string]: unknown, _creationTime: number, _id: string, userId: string }
+
+ function applyRealtimePatch(patch: { deletedIds: string[], docs: ConvexCategoryDoc[], serverTime: number, truncated: boolean }): number | null {
+ if (patch.truncated) {
+ logger.log('realtime delta truncated — running initCategories')
+ initCategories()
+ return null
+ }
+
+ const current = items.value
+ const updated: Categories = { ...current }
+ let changed = false
+
+ for (const doc of patch.docs) {
+ if (isInFlight(doc._id))
+ continue
+ const existing = updated[doc._id]
+ const existingUpdatedAt = existing?.updatedAt
+ const docUpdatedAt = typeof doc.updatedAt === 'number' ? doc.updatedAt : 0
+ if (existing && typeof existingUpdatedAt === 'number' && existingUpdatedAt >= docUpdatedAt)
+ continue
+ const { _creationTime: _ct, _id, userId: _u, ...rest } = doc
+ updated[_id] = rest as unknown as CategoryItem
+ changed = true
+ }
+
+ for (const id of patch.deletedIds) {
+ if (isInFlight(id) || id === 'transfer' || id === 'adjustment')
+ continue
+ if (id in updated) {
+ delete updated[id]
+ changed = true
+ }
+ }
+
+ if (changed) {
+ // setCategories re-adds synthetic transfer/adjustment entries.
+ const userItems: Categories = {}
+ for (const id of Object.keys(updated)) {
+ if (id !== 'transfer' && id !== 'adjustment')
+ userItems[id] = updated[id]!
+ }
+ setCategories(userItems)
+ logger.log(`realtime: ${patch.docs.length} docs, ${patch.deletedIds.length} deletes`)
+ }
+ lastSyncedAt.value = patch.serverTime
+ return patch.serverTime
+ }
+
function setCategories(values: Categories | null) {
const categories = values ? { ...values, adjustment, transfer } : { adjustment, transfer }
items.value = categories
@@ -295,6 +349,7 @@ export const useCategoriesStore = defineStore('categories', (): CategoriesStore
}
return {
+ applyRealtimePatch,
categoriesForBeParent,
categoriesIdsForTrnValues,
categoriesRootIds,
@@ -308,6 +363,7 @@ export const useCategoriesStore = defineStore('categories', (): CategoriesStore
initCategories,
isTransactible,
items,
+ lastSyncedAt,
recentCategoriesIds,
saveCategory,
setCategories,
diff --git a/app/components/trns/useTrnsStore.test.ts b/app/components/trns/useTrnsStore.test.ts
index 791a3696..2855fb67 100644
--- a/app/components/trns/useTrnsStore.test.ts
+++ b/app/components/trns/useTrnsStore.test.ts
@@ -473,4 +473,96 @@ describe('useTrnsStore', () => {
expect(store.computeTrnItem('trn1')).toBeNull()
})
})
+
+ describe('applyRealtimePatch', () => {
+ it('adds new docs from delta', async () => {
+ const store = useTrnsStore()
+ store.items = {}
+
+ await store.applyRealtimePatch({
+ deletedIds: [],
+ docs: [{
+ _creationTime: 0,
+ _id: 't1',
+ amount: 100,
+ categoryId: 'food',
+ date: 1,
+ type: 0,
+ updatedAt: 10,
+ userId: 'u',
+ walletId: 'wallet1',
+ }],
+ serverTime: 100,
+ truncated: false,
+ })
+
+ expect(store.items?.t1).toMatchObject({ amount: 100, updatedAt: 10 })
+ })
+
+ it('skips docs with stale updatedAt', async () => {
+ const store = useTrnsStore()
+ store.items = { t1: makeTrn({ amount: 200, updatedAt: 50 }) }
+
+ await store.applyRealtimePatch({
+ deletedIds: [],
+ docs: [{
+ _creationTime: 0,
+ _id: 't1',
+ amount: 999,
+ categoryId: 'food',
+ date: 1,
+ type: 0,
+ updatedAt: 20,
+ userId: 'u',
+ walletId: 'wallet1',
+ }],
+ serverTime: 100,
+ truncated: false,
+ })
+
+ expect(store.items?.t1?.amount).toBe(200)
+ })
+
+ it('removes docs in deletedIds', async () => {
+ const store = useTrnsStore()
+ store.items = { t1: makeTrn(), t2: makeTrn() }
+
+ await store.applyRealtimePatch({
+ deletedIds: ['t1'],
+ docs: [],
+ serverTime: 100,
+ truncated: false,
+ })
+
+ expect(store.items?.t1).toBeUndefined()
+ expect(store.items?.t2).toBeDefined()
+ })
+
+ it('skips docs whose id is in inFlightOps (self-echo)', async () => {
+ const { trackInFlight, untrackInFlight } = await import('~/composables/useStoreSync')
+ const store = useTrnsStore()
+ store.items = {}
+
+ trackInFlight('t1')
+ await store.applyRealtimePatch({
+ deletedIds: [],
+ docs: [{
+ _creationTime: 0,
+ _id: 't1',
+ amount: 100,
+ categoryId: 'food',
+ date: 1,
+ type: 0,
+ updatedAt: 10,
+ userId: 'u',
+ walletId: 'wallet1',
+ }],
+ serverTime: 100,
+ truncated: false,
+ })
+ untrackInFlight('t1')
+
+ expect(store.items?.t1).toBeUndefined()
+ })
+ })
})
diff --git a/app/components/trns/useTrnsStore.ts b/app/components/trns/useTrnsStore.ts
index 97f694fd..12375f57 100644
--- a/app/components/trns/useTrnsStore.ts
+++ b/app/components/trns/useTrnsStore.ts
@@ -15,7 +15,7 @@ import { STORAGE_KEYS } from '~/components/offline/storageKeys'
import { filterTrnsIds } from '~/components/trns/getTrns'
import { TrnType } from '~/components/trns/types'
import { useWalletsStore } from '~/components/wallets/useWalletsStore'
-import { createDebouncedPersist, handleMutationResult, isPersistBlocked, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
+import { createDebouncedPersist, handleMutationResult, isInFlight, isPersistBlocked, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
import { createLogger } from '~/utils/logger'
/** Shape returned by Convex paginated queries (has _id, _creationTime, userId + entity fields). */
@@ -196,6 +196,60 @@ export const useTrnsStore = defineStore('trns', () => {
logger.log(`delta sync: ${changedTrns.length} changed`)
}
+ /**
+ * Apply a realtime delta patch from a server subscription. Returns the
+ * new `since` timestamp for the next subscription window, or null when
+ * caller should fall back to a fullSync (truncated or no items).
+ */
+ async function applyRealtimePatch(patch: { deletedIds: string[], docs: ConvexTrnDoc[], serverTime: number, truncated: boolean }): Promise<number | null> {
+ if (patch.truncated) {
+ logger.log('realtime delta truncated — running fullSync')
+ await fullSync()
+ return null
+ }
+
+ const current = items.value ?? {}
+ const updated: Trns = { ...current }
+ let changed = false
+
+ for (const doc of patch.docs) {
+ if (isInFlight(doc._id))
+ continue
+ const existing = updated[doc._id]
+ if (existing && typeof existing.updatedAt === 'number' && existing.updatedAt >= (doc.updatedAt as number))
+ continue
+ const { _creationTime: _ct, _id, userId: _u, ...rest } = doc
+ updated[_id] = rest as unknown as Trns[string]
+ changed = true
+ }
+
+ for (const id of patch.deletedIds) {
+ if (isInFlight(id))
+ continue
+ if (id in updated) {
+ delete updated[id]
+ changed = true
+ }
+ }
+
+ if (changed) {
+ setTrns(Object.keys(updated).length > 0 ? updated : null)
+ logger.log(`realtime: ${patch.docs.length} docs, ${patch.deletedIds.length} deletes`)
+ }
+
+ const syncMeta: TrnsSyncMeta = {
+ idsHash: '',
+ lastSyncedAt: patch.serverTime,
+ }
+ const existingMeta = await localforage.getItem<TrnsSyncMeta>(STORAGE_KEYS.trnsSyncMeta)
+ if (existingMeta)
+ syncMeta.idsHash = existingMeta.idsHash
+ if (!isPersistBlocked())
+ await localforage.setItem(STORAGE_KEYS.trnsSyncMeta, syncMeta)
+
+ return patch.serverTime
+ }
+
async function initTrns() {
try {
const syncMeta = await localforage.getItem<TrnsSyncMeta>(STORAGE_KEYS.trnsSyncMeta)
@@ -380,6 +434,7 @@ export const useTrnsStore = defineStore('trns', () => {
}
return {
+ applyRealtimePatch,
computeTrnItem,
deleteTrn,
getRange,
diff --git a/app/components/user/useUserStore.ts b/app/components/user/useUserStore.ts
index e0a56482..e30d5501 100644
--- a/app/components/user/useUserStore.ts
+++ b/app/components/user/useUserStore.ts
@@ -13,6 +13,7 @@ import { useTrnsStore } from '~/components/trns/useTrnsStore'
import { userSettingsSchema } from '~/components/user/types'
import { useWalletsStore } from '~/components/wallets/useWalletsStore'
import { clearAuthCookie, hasAuthCookie, setSessionInitialized } from '~/composables/useAuthCookie'
+import { stopAllRealtime } from '~/composables/useRealtimeSync'
import { blockPersist, handleMutationResult, isPersistBlocked } from '~/composables/useStoreSync'
import { createLogger } from '~/utils/logger'
@@ -153,6 +154,23 @@ export const useUserStore = defineStore('user', () => {
})
}
+ function applyRealtimeSettings(settings: unknown): void {
+ if (!settings)
+ return
+ const parsed = userSettingsSchema.safeParse(settings)
+ if (!parsed.success)
+ return
+ if (parsed.data.baseCurrency !== baseCurrency.value) {
+ baseCurrency.value = parsed.data.baseCurrency
+ persistUserSettings()
+ }
+ if (parsed.data.locale && parsed.data.locale !== locale.value) {
+ locale.value = parsed.data.locale
+ useNuxtApp().$i18n.setLocale(parsed.data.locale)
+ persistUserSettings()
+ }
+ }
+
async function initUserSettings() {
try {
const { api, client } = useConvexClientWithApi()
@@ -193,6 +211,7 @@ export const useUserStore = defineStore('user', () => {
async function signOut() {
isSigningOut.value = true
+ stopAllRealtime()
if (isDemo.value) {
await localforage.clear()
@@ -261,6 +280,7 @@ export const useUserStore = defineStore('user', () => {
}
return {
+ applyRealtimeSettings,
baseCurrency,
currentUser,
initUserSettings,
diff --git a/app/components/wallets/useWalletsStore.ts b/app/components/wallets/useWalletsStore.ts
index baf68f9b..3166eda1 100644
--- a/app/components/wallets/useWalletsStore.ts
+++ b/app/components/wallets/useWalletsStore.ts
@@ -14,7 +14,7 @@ import { STORAGE_KEYS } from '~/components/offline/storageKeys'
import { TrnType } from '~/components/trns/types'
import { useTrnsStore } from '~/components/trns/useTrnsStore'
import { useUserStore } from '~/components/user/useUserStore'
-import { createDebouncedPersist, handleMutationResult, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
+import { createDebouncedPersist, handleMutationResult, isInFlight, mergeOfflineOps, pushDeleteOp, pushSaveOp } from '~/composables/useStoreSync'
import { createLogger } from '~/utils/logger'
const logger = createLogger('wallets')
@@ -26,6 +26,8 @@ export const useWalletsStore = defineStore('wallets', () => {
const items = shallowRef<Wallets | null>(null)
const hasItems = computed(() => Object.keys(items.value ?? {}).length > 0)
+ /** In-memory only — survives for the app session. Reset on each initWallets. */
+ const lastSyncedAt = ref(0)
async function initWallets() {
try {
@@ -37,12 +39,56 @@ export const useWalletsStore = defineStore('wallets', () => {
data = await mergeOfflineOps(data, 'wallets')
setWallets(data)
+ lastSyncedAt.value = Date.now()
}
catch (e) {
logger.error('init failed', e)
}
}
+ type ConvexWalletDoc = { [key: string]: unknown, _creationTime: number, _id: string, userId: string }
+
+ function applyRealtimePatch(patch: { deletedIds: string[], docs: ConvexWalletDoc[], serverTime: number, truncated: boolean }): number | null {
+ if (patch.truncated) {
+ logger.log('realtime delta truncated — running initWallets')
+ initWallets()
+ return null
+ }
+
+ const current = items.value ?? {}
+ const updated: Wallets = { ...current }
+ let changed = false
+
+ for (const doc of patch.docs) {
+ if (isInFlight(doc._id))
+ continue
+ const existing = updated[doc._id]
+ const existingUpdatedAt = existing?.updatedAt
+ const docUpdatedAt = typeof doc.updatedAt === 'number' ? doc.updatedAt : 0
+ if (existing && typeof existingUpdatedAt === 'number' && existingUpdatedAt >= docUpdatedAt)
+ continue
+ const { _creationTime: _ct, _id, userId: _u, ...rest } = doc
+ updated[_id] = rest as unknown as WalletItem
+ changed = true
+ }
+
+ for (const id of patch.deletedIds) {
+ if (isInFlight(id))
+ continue
+ if (id in updated) {
+ delete updated[id]
+ changed = true
+ }
+ }
+
+ if (changed) {
+ setWallets(updated)
+ logger.log(`realtime: ${patch.docs.length} docs, ${patch.deletedIds.length} deletes`)
+ }
+ lastSyncedAt.value = patch.serverTime
+ return patch.serverTime
+ }
+
const debouncedPersist = createDebouncedPersist<Wallets | null>(STORAGE_KEYS.wallets)
function setWallets(values: Wallets | null) {
@@ -239,12 +285,14 @@ export const useWalletsStore = defineStore('wallets', () => {
}
return {
+ applyRealtimePatch,
currenciesUsed,
deleteWallet,
hasItems,
initWallets,
items,
itemsComputed,
+ lastSyncedAt,
recentWalletIds,
saveWallet,
saveWalletsOrder,
diff --git a/app/composables/useRealtimeSync.ts b/app/composables/useRealtimeSync.ts
new file mode 100644
index 00000000..43ee076a
--- /dev/null
+++ b/app/composables/useRealtimeSync.ts
@@ -0,0 +1,127 @@
+import type { FunctionReference } from 'convex/server'
+
+import localforage from 'localforage'
+
+import { useCategoriesStore } from '~/components/categories/useCategoriesStore'
+import { STORAGE_KEYS } from '~/components/offline/storageKeys'
+import { useTrnsStore } from '~/components/trns/useTrnsStore'
+import { useUserStore } from '~/components/user/useUserStore'
+import { useWalletsStore } from '~/components/wallets/useWalletsStore'
+import { createLogger } from '~/utils/logger'
+
+const logger = createLogger('realtime')
+
+export type RealtimeDelta<TDoc> = {
+ deletedIds: string[]
+ docs: TDoc[]
+ serverTime: number
+ truncated: boolean
+}
+
+export type SubscriptionHandle = {
+ label: string
+ stop: () => void
+}
+
+type ConvexOnUpdateClient = {
+ onUpdate: <T>(query: FunctionReference<'query'>, args: Record<string, unknown>, cb: (value: T) => void) => () => void
+}
+
+/**
+ * Subscribe to a delta query. Convex keeps the subscription reactive — it
+ * re-runs the query on the server whenever the dependent tables change and
+ * pushes the updated result to `applyPatch`. No manual re-subscribe needed.
+ *
+ * `applyPatch` is expected to be idempotent (skip already-applied docs via
+ * `updatedAt` monotonic check) because the server result accumulates all
+ * changes since `initialSince`. A `truncated` flag signals the caller should
+ * fall back to a fullSync; returning `null` from applyPatch stops the sub.
+ */
+export function subscribeDelta<TDoc>(opts: {
+ applyPatch: (patch: RealtimeDelta<TDoc>) => Promise<number | null> | number | null
+ client: ConvexOnUpdateClient
+ initialSince: number
+ label: string
+ query: FunctionReference<'query'>
+}): SubscriptionHandle {
+ let stopped = false
+
+ const stopInner = opts.client.onUpdate(opts.query, { since: opts.initialSince }, async (value: RealtimeDelta<TDoc> | null) => {
+ if (!value || stopped)
+ return
+ if (value.truncated)
+ logger.warn(`${opts.label}: truncated delta, caller should fullSync`)
+ const next = await opts.applyPatch(value)
+ if (next === null)
+ stop()
+ })
+
+ function stop(): void {
+ stopped = true
+ stopInner()
+ }
+
+ return { label: opts.label, stop }
+}
+
+let _handles: SubscriptionHandle[] = []
+
+export function stopAllRealtime(): void {
+ for (const h of _handles) {
+ try {
+ h.stop()
+ }
+ catch (e) {
+ logger.warn(`stop ${h.label} failed`, e)
+ }
+ }
+ if (_handles.length > 0)
+ logger.log(`stopped ${_handles.length} subscriptions`)
+ _handles = []
+}
+
+export async function startAllRealtime(): Promise<void> {
+ stopAllRealtime()
+
+ const { api, client } = useConvexClientWithApi()
+ const onUpdateClient = client as unknown as ConvexOnUpdateClient
+
+ const trnsStore = useTrnsStore()
+ const walletsStore = useWalletsStore()
+ const categoriesStore = useCategoriesStore()
+ const userStore = useUserStore()
+
+ const trnsMeta = await localforage.getItem<{ lastSyncedAt: number }>(STORAGE_KEYS.trnsSyncMeta)
+ const trnsSince = trnsMeta?.lastSyncedAt ?? Date.now()
+
+ _handles.push(subscribeDelta({
+ applyPatch: patch => trnsStore.applyRealtimePatch(patch as never),
+ client: onUpdateClient,
+ initialSince: trnsSince,
+ label: 'trns',
+ query: api.trns.deltaRealtime,
+ }))
+
+ _handles.push(subscribeDelta({
+ applyPatch: patch => walletsStore.applyRealtimePatch(patch as never),
+ client: onUpdateClient,
+ initialSince: walletsStore.lastSyncedAt || Date.now(),
+ label: 'wallets',
+ query: api.wallets.deltaRealtime,
+ }))
+
+ _handles.push(subscribeDelta({
+ applyPatch: patch => categoriesStore.applyRealtimePatch(patch as never),
+ client: onUpdateClient,
+ initialSince: categoriesStore.lastSyncedAt || Date.now(),
+ label: 'categories',
+ query: api.categories.deltaRealtime,
+ }))
+
+ const stopSettings = onUpdateClient.onUpdate(api.user.get, {}, (settings) => {
+ userStore.applyRealtimeSettings(settings)
+ })
+ _handles.push({ label: 'userSettings', stop: stopSettings })
+
+ logger.log(`started ${_handles.length} subscriptions`)
+}
diff --git a/app/composables/useStoreSync.test.ts b/app/composables/useStoreSync.test.ts
index 384351a8..33f7463e 100644
--- a/app/composables/useStoreSync.test.ts
+++ b/app/composables/useStoreSync.test.ts
@@ -249,3 +249,52 @@ describe('pushDeleteOp', () => {
expect(pushOfflineOpMock).not.toHaveBeenCalled()
})
})
+
+describe('inFlightOps tracking', () => {
+ it('trackInFlight adds id and isInFlight returns true', async () => {
+ const { isInFlight, trackInFlight, untrackInFlight } = await import('~/composables/useStoreSync')
+
+ trackInFlight('w1')
+ expect(isInFlight('w1')).toBe(true)
+ untrackInFlight('w1')
+ expect(isInFlight('w1')).toBe(false)
+ })
+
+ it('handleMutationResult tracks id during mutation and untracks after resolve', async () => {
+ const { handleMutationResult, isInFlight } = await import('~/composables/useStoreSync')
+
+ let resolveMutation: (v: unknown) => void
+ const mutation = new Promise((r) => {
+ resolveMutation = r
+ })
+
+ const promise = handleMutationResult({
+ action: 'update',
+ entity: 'wallets',
+ errorMessage: 'x',
+ id: 'w-tracked',
+ mutation,
+ })
+
+ expect(isInFlight('w-tracked')).toBe(true)
+ resolveMutation!(undefined)
+ await promise
+ expect(isInFlight('w-tracked')).toBe(false)
+ })
+
+ it('handleMutationResult untracks id after rejection', async () => {
+ const { handleMutationResult, isInFlight } = await import('~/composables/useStoreSync')
+
+ const mutation = Promise.reject(new Error('fail'))
+
+ await handleMutationResult({
+ action: 'update',
+ entity: 'wallets',
+ errorMessage: 'x',
+ id: 'w-fail',
+ mutation,
+ })
+
+ expect(isInFlight('w-fail')).toBe(false)
+ })
+})
diff --git a/app/composables/useStoreSync.ts b/app/composables/useStoreSync.ts
index e321887e..d8c01cb3 100644
--- a/app/composables/useStoreSync.ts
+++ b/app/composables/useStoreSync.ts
@@ -27,6 +27,23 @@ export function isPersistBlocked(): boolean {
return _persistBlocked
}
+// Tracks ids of mutations currently being confirmed by the server. Used by
+// the realtime-sync layer to suppress self-echo: subscription updates whose
+// id is in-flight are skipped so the origin device doesn't apply its own change twice.
+const _inFlightOps = new Set<string>()
+
+export function trackInFlight(id: string): void {
+ _inFlightOps.add(id)
+}
+
+export function untrackInFlight(id: string): void {
+ _inFlightOps.delete(id)
+}
+
+export function isInFlight(id: string): boolean {
+ return _inFlightOps.has(id)
+}
+
export function createDebouncedPersist<T>(storageKey: string) {
return debounce((values: T) => {
if (_persistBlocked)
@@ -112,6 +129,11 @@ export function handleMutationResult<T>(opts: {
}): Promise<RemapInfo | void> {
const ids = Array.isArray(opts.id) ? opts.id : [opts.id]
+ // Track ids as in-flight so that the subscription's own echo (for update/delete
+ // this is the convex id already; for create the local id won't match, but the
+ // post-mutation remap handles that path).
+ for (const id of ids) trackInFlight(id)
+
return opts.mutation
.then(async (result): Promise<RemapInfo | void> => {
logger.log(`confirmed ${opts.action}: ${ids.length > 1 ? `${ids.length} items` : ids[0]}`)
@@ -131,6 +153,10 @@ export function handleMutationResult<T>(opts: {
if (!_persistBlocked)
localforage.setItem(STORAGE_KEYS[opts.entity], remapped)
logger.log(`remapped ID: ${opts.id} → ${convexId}`)
+ // Track convex id briefly so that a subscription echo arriving just
+ // after remap is still suppressed.
+ trackInFlight(convexId)
+ setTimeout(untrackInFlight, 2000, convexId)
return { convexId, localId: opts.id }
}
}
@@ -139,6 +165,9 @@ export function handleMutationResult<T>(opts: {
logger.error(`${opts.action} failed: ${ids.length > 1 ? `${ids.length} items` : ids[0]}`, e)
showErrorToast(opts.errorMessage)
})
+ .finally(() => {
+ for (const id of ids) untrackInFlight(id)
+ })
}
let _toast: ReturnType<typeof useToast> | null = null
diff --git a/convex/_generated/api.d.ts b/convex/_generated/api.d.ts
index 2d593398..7ec7eb87 100644
--- a/convex/_generated/api.d.ts
+++ b/convex/_generated/api.d.ts
@@ -15,6 +15,7 @@ import type * as http from "../http.js";
import type * as migrate from "../migrate.js";
import type * as rates from "../rates.js";
import type * as shared from "../shared.js";
+import type * as tombstones from "../tombstones.js";
import type * as trns from "../trns.js";
import type * as trnsHash from "../trnsHash.js";
import type * as user from "../user.js";
@@ -35,6 +36,7 @@ declare const fullApi: ApiFromModules<{
migrate: typeof migrate;
rates: typeof rates;
shared: typeof shared;
+ tombstones: typeof tombstones;
trns: typeof trns;
trnsHash: typeof trnsHash;
user: typeof user;
diff --git a/convex/categories.ts b/convex/categories.ts
index d85f8a8a..9bfcbee4 100644
--- a/convex/categories.ts
+++ b/convex/categories.ts
@@ -6,6 +6,7 @@ import type { MutationCtx } from './_generated/server'
import { internal } from './_generated/api'
import { action, internalMutation, internalQuery, mutation, query } from './_generated/server'
import { getAuthUser, getOwnEntity, requireAuthUser, validateStringLength } from './shared'
+import { emitTombstone, emitTombstones } from './tombstones'
import { toggleTrnsHash } from './trnsHash'
async function validateParentId(ctx: MutationCtx, parentId: Id<'categories'> | 0, userId: string, selfId?: Id<'categories'>) {
@@ -76,6 +77,36 @@ export const list = query({
},
})
+const REALTIME_DELTA_LIMIT = 500
+
+export const deltaRealtime = query({
+ args: { since: v.number() },
+ handler: async (ctx, { since }) => {
+ const user = await getAuthUser(ctx)
+ if (!user)
+ return null
+ const serverTime = Date.now()
+ const docsPlusOne = await ctx.db
+ .query('categories')
+ .withIndex('by_user_updatedAt', q =>
+ q.eq('userId', user._id).gt('updatedAt', since))
+ .take(REALTIME_DELTA_LIMIT + 1)
+ const truncated = docsPlusOne.length > REALTIME_DELTA_LIMIT
+ const docs = truncated ? docsPlusOne.slice(0, REALTIME_DELTA_LIMIT) : docsPlusOne
+ const tombstones = await ctx.db
+ .query('tombstones')
+ .withIndex('by_user_entity_deletedAt', q =>
+ q.eq('userId', user._id).eq('entity', 'categories').gt('deletedAt', since))
+ .take(REALTIME_DELTA_LIMIT)
+ return {
+ deletedIds: tombstones.map(t => t.entityId),
+ docs,
+ serverTime,
+ truncated,
+ }
+ },
+})
+
export const create = mutation({
args: {
color: v.string(),
@@ -163,8 +194,10 @@ export const removeTrnsByCategoryPage = internalMutation({
deletedIds.push(trn._id)
}
- if (deletedIds.length)
+ if (deletedIds.length) {
await toggleTrnsHash(ctx, userId, deletedIds)
+ await emitTombstones(ctx, userId, 'trns', deletedIds)
+ }
return { continueCursor: page.continueCursor, isDone: page.isDone }
},
@@ -180,6 +213,7 @@ export const removeCategoryFinalize = internalMutation({
if (!category || category.userId !== userId)
return
await ctx.db.delete(categoryId)
+ await emitTombstone(ctx, userId, 'categories', categoryId)
},
})
diff --git a/convex/crons.ts b/convex/crons.ts
index 84b8771b..d3ab7369 100644
--- a/convex/crons.ts
+++ b/convex/crons.ts
@@ -10,4 +10,10 @@ crons.daily(
internal.rates.fetchAndSaveRates,
)
+crons.daily(
+ 'purge old tombstones',
+ { hourUTC: 4, minuteUTC: 0 },
+ internal.tombstones.purgeOld,
+)
+
export default crons
diff --git a/convex/schema.ts b/convex/schema.ts
index 12e87764..ef744166 100644
--- a/convex/schema.ts
+++ b/convex/schema.ts
@@ -16,7 +16,8 @@ export default defineSchema({
})
.index('by_user', ['userId'])
.index('by_user_name_parent', ['userId', 'name', 'parentId'])
- .index('by_user_parent', ['userId', 'parentId']),
+ .index('by_user_parent', ['userId', 'parentId'])
+ .index('by_user_updatedAt', ['userId', 'updatedAt']),
rates: defineTable({
date: v.string(),
@@ -32,6 +33,15 @@ export default defineSchema({
userId: v.string(),
}).index('by_user', ['userId']),
+ tombstones: defineTable({
+ deletedAt: v.number(),
+ entity: v.union(v.literal('trns'), v.literal('wallets'), v.literal('categories')),
+ entityId: v.string(),
+ userId: v.string(),
+ })
+ .index('by_user_entity_deletedAt', ['userId', 'entity', 'deletedAt'])
+ .index('by_user_deletedAt', ['userId', 'deletedAt']),
+
trns: defineTable({
amount: v.optional(v.number()),
categoryId: v.optional(v.union(v.id('categories'), v.literal('transfer'), v.literal('adjustment'))),
@@ -77,5 +87,7 @@ export default defineSchema({
type: walletTypeValidator,
updatedAt: v.optional(v.number()),
userId: v.string(),
- }).index('by_user', ['userId']),
+ })
+ .index('by_user', ['userId'])
+ .index('by_user_updatedAt', ['userId', 'updatedAt']),
})
diff --git a/convex/tombstones.ts b/convex/tombstones.ts
new file mode 100644
index 00000000..3e5d4213
--- /dev/null
+++ b/convex/tombstones.ts
@@ -0,0 +1,76 @@
+import { v } from 'convex/values'
+
+import type { MutationCtx } from './_generated/server'
+
+import { internal } from './_generated/api'
+import { internalAction, internalMutation } from './_generated/server'
+
+export type TombstoneEntity = 'categories' | 'trns' | 'wallets'
+
+const RETAIN_MS = 30 * 24 * 60 * 60 * 1000
+
+export const purgeOldPage = internalMutation({
+ args: { cursor: v.union(v.string(), v.null()), cutoff: v.number() },
+ handler: async (ctx, { cursor, cutoff }) => {
+ const page = await ctx.db
+ .query('tombstones')
+ .withIndex('by_user_deletedAt')
+ .paginate({ cursor, numItems: 500 })
+
+ let removed = 0
+ for (const t of page.page) {
+ if (t.deletedAt < cutoff) {
+ await ctx.db.delete(t._id)
+ removed++
+ }
+ }
+ return { continueCursor: page.continueCursor, isDone: page.isDone, removed }
+ },
+})
+
+export const purgeOld = internalAction({
+ args: {},
+ handler: async (ctx) => {
+ const cutoff = Date.now() - RETAIN_MS
+ let cursor: string | null = null
+ let isDone = false
+ let total = 0
+ while (!isDone) {
+ const result: { continueCursor: string, isDone: boolean, removed: number } = await ctx.runMutation(
+ internal.tombstones.purgeOldPage,
+ { cursor, cutoff },
+ )
+ total += result.removed
+ cursor = result.continueCursor
+ isDone = result.isDone
+ }
+ return { removed: total }
+ },
+})
+
+export async function emitTombstone(
+ ctx: MutationCtx,
+ userId: string,
+ entity: TombstoneEntity,
+ entityId: string,
+): Promise<void> {
+ await ctx.db.insert('tombstones', {
+ deletedAt: Date.now(),
+ entity,
+ entityId,
+ userId,
+ })
+}
+
+export async function emitTombstones(
+ ctx: MutationCtx,
+ userId: string,
+ entity: TombstoneEntity,
+ entityIds: string[],
+): Promise<void> {
+ if (entityIds.length === 0)
+ return
+ const deletedAt = Date.now()
+ for (const entityId of entityIds)
+ await ctx.db.insert('tombstones', { deletedAt, entity, entityId, userId })
+}
diff --git a/convex/trns.ts b/convex/trns.ts
index 538fbb12..6bdc92cf 100644
--- a/convex/trns.ts
+++ b/convex/trns.ts
@@ -7,6 +7,7 @@ import type { MutationCtx } from './_generated/server'
import { internal } from './_generated/api'
import { mutation, query } from './_generated/server'
import { AMOUNT_MAX, DATE_MAX, DATE_MIN, getAuthUser, getOwnEntity, requireAuthUser, TrnType, validateNumberRange, validateStringLength } from './shared'
+import { emitTombstone } from './tombstones'
import { fnv1aNum, toggleTrnHash } from './trnsHash'
async function validateTrnFields(ctx: MutationCtx, args: Record<string, any>, userId: string) {
@@ -67,6 +68,36 @@ export const delta = query({
},
})
+const REALTIME_DELTA_LIMIT = 500
+
+export const deltaRealtime = query({
+ args: { since: v.number() },
+ handler: async (ctx, { since }) => {
+ const user = await getAuthUser(ctx)
+ if (!user)
+ return null
+ const serverTime = Date.now()
+ const docsPlusOne = await ctx.db
+ .query('trns')
+ .withIndex('by_user_updatedAt', q =>
+ q.eq('userId', user._id).gt('updatedAt', since))
+ .take(REALTIME_DELTA_LIMIT + 1)
+ const truncated = docsPlusOne.length > REALTIME_DELTA_LIMIT
+ const docs = truncated ? docsPlusOne.slice(0, REALTIME_DELTA_LIMIT) : docsPlusOne
+ const tombstones = await ctx.db
+ .query('tombstones')
+ .withIndex('by_user_entity_deletedAt', q =>
+ q.eq('userId', user._id).eq('entity', 'trns').gt('deletedAt', since))
+ .take(REALTIME_DELTA_LIMIT)
+ return {
+ deletedIds: tombstones.map(t => t.entityId),
+ docs,
+ serverTime,
+ truncated,
+ }
+ },
+})
+
export const ensureSyncMeta = mutation({
args: {},
handler: async (ctx) => {
@@ -212,7 +243,9 @@ export const remove = mutation({
handler: async (ctx, { id }) => {
const user = await requireAuthUser(ctx)
const deleted = await removeUserTrn(ctx, id, user._id)
- if (deleted)
+ if (deleted) {
await toggleTrnHash(ctx, user._id, id)
+ await emitTombstone(ctx, user._id, 'trns', id)
+ }
},
})
diff --git a/convex/wallets.ts b/convex/wallets.ts
index bbc30b1b..a2265883 100644
--- a/convex/wallets.ts
+++ b/convex/wallets.ts
@@ -3,6 +3,7 @@ import { v } from 'convex/values'
import { internal } from './_generated/api'
import { action, internalMutation, mutation, query } from './_generated/server'
import { CREDIT_LIMIT_MAX, getAuthUser, getOwnEntity, requireAuthUser, validateNumberRange, validateStringLength } from './shared'
+import { emitTombstone, emitTombstones } from './tombstones'
import { toggleTrnsHash } from './trnsHash'
import { walletTypeValidator } from './validators'
@@ -19,6 +20,36 @@ export const list = query({
},
})
+const REALTIME_DELTA_LIMIT = 500
+
+export const deltaRealtime = query({
+ args: { since: v.number() },
+ handler: async (ctx, { since }) => {
+ const user = await getAuthUser(ctx)
+ if (!user)
+ return null
+ const serverTime = Date.now()
+ const docsPlusOne = await ctx.db
+ .query('wallets')
+ .withIndex('by_user_updatedAt', q =>
+ q.eq('userId', user._id).gt('updatedAt', since))
+ .take(REALTIME_DELTA_LIMIT + 1)
+ const truncated = docsPlusOne.length > REALTIME_DELTA_LIMIT
+ const docs = truncated ? docsPlusOne.slice(0, REALTIME_DELTA_LIMIT) : docsPlusOne
+ const tombstones = await ctx.db
+ .query('tombstones')
+ .withIndex('by_user_entity_deletedAt', q =>
+ q.eq('userId', user._id).eq('entity', 'wallets').gt('deletedAt', since))
+ .take(REALTIME_DELTA_LIMIT)
+ return {
+ deletedIds: tombstones.map(t => t.entityId),
+ docs,
+ serverTime,
+ truncated,
+ }
+ },
+})
+
export const create = mutation({
args: {
color: v.string(),
@@ -130,8 +161,10 @@ export const removeTrnsByWalletPage = internalMutation({
deletedIds.push(trn._id)
}
- if (deletedIds.length)
+ if (deletedIds.length) {
await toggleTrnsHash(ctx, userId, deletedIds)
+ await emitTombstones(ctx, userId, 'trns', deletedIds)
+ }
return { continueCursor: page.continueCursor, isDone: page.isDone }
},
@@ -144,8 +177,10 @@ export const removeWalletFinalize = internalMutation({
},
handler: async (ctx, { userId, walletId }) => {
const wallet = await ctx.db.get(walletId)
- if (wallet && wallet.userId === userId)
+ if (wallet && wallet.userId === userId) {
await ctx.db.delete(walletId)
+ await emitTombstone(ctx, userId, 'wallets', walletId)
+ }
},
})
diff --git a/package.json b/package.json
index 25bbb2e1..676505ef 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "@ilkome/finapp",
"type": "module",
- "version": "7.7.0",
+ "version": "7.8.0",
"packageManager": "[email protected]",
"description": "Finapp helps you easily track and manage personal finances.",
"author": "Ilya Komichev @ilkome",