From 5cad7d5be0adea3cb6039e435c2d73faa9141bb2 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Mon, 14 Sep 2026 16:07:54 +0530 Subject: [PATCH 1/5] feat(account): add a bounded-operation lifecycle primitive Extract the generation/capture/live()/abandon() guard duplicated across the website auth call sites into one shared primitive: createBoundedOperation in the framework-free core, plus useGenerationGuard and createLifecycleScope in the Vue subpath. Primitive and tests only; call-site migrations follow. Fixes FE-2192 --- packages/account/package.json | 1 + .../account/src/core/boundedOperation.test.ts | 68 +++++++++++++++++++ packages/account/src/core/boundedOperation.ts | 29 ++++++++ packages/account/src/vue/index.ts | 3 + .../account/src/vue/lifecycleScope.test.ts | 60 ++++++++++++++++ packages/account/src/vue/lifecycleScope.ts | 28 ++++++++ .../src/vue/useGenerationGuard.test.ts | 31 +++++++++ .../account/src/vue/useGenerationGuard.ts | 15 ++++ 8 files changed, 235 insertions(+) create mode 100644 packages/account/src/core/boundedOperation.test.ts create mode 100644 packages/account/src/core/boundedOperation.ts create mode 100644 packages/account/src/vue/lifecycleScope.test.ts create mode 100644 packages/account/src/vue/lifecycleScope.ts create mode 100644 packages/account/src/vue/useGenerationGuard.test.ts create mode 100644 packages/account/src/vue/useGenerationGuard.ts diff --git a/packages/account/package.json b/packages/account/package.json index ac85bafc778..c26c253c682 100644 --- a/packages/account/package.json +++ b/packages/account/package.json @@ -7,6 +7,7 @@ "license": "MIT", "type": "module", "exports": { + "./boundedOperation": "./src/core/boundedOperation.ts", "./session": "./src/core/session.ts", "./billing": "./src/core/billing/index.ts", "./firebase": "./src/firebase/index.ts", diff --git a/packages/account/src/core/boundedOperation.test.ts b/packages/account/src/core/boundedOperation.test.ts new file mode 100644 index 00000000000..dd9ff0daf7c --- /dev/null +++ b/packages/account/src/core/boundedOperation.test.ts @@ -0,0 +1,68 @@ +import { describe, expect, it } from 'vitest' + +import { createBoundedOperation } from './boundedOperation.js' + +describe('createBoundedOperation', () => { + it('captures a handle that is live until the operation is abandoned', () => { + const operation = createBoundedOperation() + const handle = operation.capture() + + expect(handle.live()).toBe(true) + operation.abandon() + expect( + handle.live(), + 'a captured attempt must not survive its own abandonment' + ).toBe(false) + }) + + it('invalidates every outstanding handle when abandoned, not only the latest', () => { + const operation = createBoundedOperation() + const first = operation.capture() + const second = operation.capture() + + operation.abandon() + + expect(first.live()).toBe(false) + expect( + second.live(), + 'one abandonment must drop all in-flight attempts, not just the newest' + ).toBe(false) + }) + + it('leaves an earlier handle live when a later capture supersedes nothing', () => { + const operation = createBoundedOperation() + const earlier = operation.capture() + operation.capture() + + expect( + earlier.live(), + 'capture alone is not invalidation; only abandon ends prior attempts' + ).toBe(true) + }) + + it('captures a fresh live handle after abandonment', () => { + const operation = createBoundedOperation() + operation.capture() + operation.abandon() + + const renewed = operation.capture() + + expect(renewed.live()).toBe(true) + }) + + it('discards a result that resolves after the operation was abandoned mid-flight', async () => { + const operation = createBoundedOperation() + const handle = operation.capture() + + const pendingRead = (async () => { + await Promise.resolve() + return handle.live() + })() + operation.abandon() + + expect( + await pendingRead, + 'work re-checked across an await must not publish once superseded' + ).toBe(false) + }) +}) diff --git a/packages/account/src/core/boundedOperation.ts b/packages/account/src/core/boundedOperation.ts new file mode 100644 index 00000000000..d5a8cb1f04e --- /dev/null +++ b/packages/account/src/core/boundedOperation.ts @@ -0,0 +1,29 @@ +/** + * A monotonic owner for work that outlives an await: each `capture()` snapshots + * the current generation and returns a handle whose `live()` stays true until + * `abandon()` bumps the generation. A flag flip, a reset, or teardown calls + * `abandon()`; the in-flight work re-checks `live()` after every await and drops + * its result once superseded, so a stale sign-in, mint, or fetch can never + * publish for an attempt that no longer owns the outcome. + */ +export interface OperationHandle { + live: () => boolean +} + +export interface BoundedOperation { + capture: () => OperationHandle + abandon: () => void +} + +export function createBoundedOperation(): BoundedOperation { + let generation = 0 + return { + capture() { + const captured = generation + return { live: () => captured === generation } + }, + abandon() { + generation += 1 + } + } +} diff --git a/packages/account/src/vue/index.ts b/packages/account/src/vue/index.ts index 083397f91be..f8ede68354c 100644 --- a/packages/account/src/vue/index.ts +++ b/packages/account/src/vue/index.ts @@ -2,6 +2,9 @@ export type { PasswordRulesCopy } from './PasswordRules.vue' export { default as PasswordRules } from './PasswordRules.vue' export { default as SocialAuthButtons } from './SocialAuthButtons.vue' export { default as TurnstileWidget } from './TurnstileWidget.vue' +export { createLifecycleScope } from './lifecycleScope' +export type { LifecycleScope } from './lifecycleScope' export type { RegionGateStatus } from './regionGate' export { useRegionGate } from './regionGate' export { useTurnstileGate } from './turnstileGate' +export { useGenerationGuard } from './useGenerationGuard' diff --git a/packages/account/src/vue/lifecycleScope.test.ts b/packages/account/src/vue/lifecycleScope.test.ts new file mode 100644 index 00000000000..28db5a85bc8 --- /dev/null +++ b/packages/account/src/vue/lifecycleScope.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it, vi } from 'vitest' +import { onScopeDispose, ref, watch } from 'vue' + +import { createLifecycleScope } from './lifecycleScope' + +describe('createLifecycleScope', () => { + it('runs the setup once and ignores a second start while running', () => { + const lifecycle = createLifecycleScope() + const setup = vi.fn() + + lifecycle.start(setup) + lifecycle.start(setup) + + expect( + setup, + 'a module singleton must install its listeners once, not per caller' + ).toHaveBeenCalledOnce() + }) + + it('disposes the running scope so its watchers stop', () => { + const lifecycle = createLifecycleScope() + const source = ref(0) + const seen: number[] = [] + lifecycle.start(() => { + watch(source, (value) => seen.push(value), { flush: 'sync' }) + }) + + source.value = 1 + lifecycle.stop() + source.value = 2 + + expect( + seen, + 'a disposed scope must not keep reacting to its sources' + ).toEqual([1]) + }) + + it('reopens the latch after stop so a failed install can be retried', () => { + const lifecycle = createLifecycleScope() + const setup = vi.fn() + + lifecycle.start(setup) + lifecycle.stop() + lifecycle.start(setup) + + expect(setup).toHaveBeenCalledTimes(2) + }) + + it('fires scope-disposal hooks registered by the setup on stop', () => { + const lifecycle = createLifecycleScope() + const disposed = vi.fn() + lifecycle.start(() => { + onScopeDispose(disposed) + }) + + lifecycle.stop() + + expect(disposed).toHaveBeenCalledOnce() + }) +}) diff --git a/packages/account/src/vue/lifecycleScope.ts b/packages/account/src/vue/lifecycleScope.ts new file mode 100644 index 00000000000..a26009c6195 --- /dev/null +++ b/packages/account/src/vue/lifecycleScope.ts @@ -0,0 +1,28 @@ +import { effectScope } from 'vue' +import type { EffectScope } from 'vue' + +/** + * A detached {@link effectScope} for a module singleton that must own its + * watchers' lifetime rather than borrow it from whichever component reaches it + * first. `start` installs the scope once; `stop` disposes it and reopens the + * latch, so a failed async install can tear down and let the next caller retry. + */ +export interface LifecycleScope { + start: (setup: () => void) => void + stop: () => void +} + +export function createLifecycleScope(): LifecycleScope { + let scope: EffectScope | undefined + return { + start(setup) { + if (scope || typeof window === 'undefined') return + scope = effectScope(true) + scope.run(setup) + }, + stop() { + scope?.stop() + scope = undefined + } + } +} diff --git a/packages/account/src/vue/useGenerationGuard.test.ts b/packages/account/src/vue/useGenerationGuard.test.ts new file mode 100644 index 00000000000..acc23c404ad --- /dev/null +++ b/packages/account/src/vue/useGenerationGuard.test.ts @@ -0,0 +1,31 @@ +import { describe, expect, it } from 'vitest' +import { effectScope } from 'vue' + +import { useGenerationGuard } from './useGenerationGuard' + +describe('useGenerationGuard', () => { + it('abandons every outstanding attempt when its owning scope is disposed', () => { + const scope = effectScope() + const guard = scope.run(() => useGenerationGuard())! + const handle = guard.capture() + + expect(handle.live()).toBe(true) + scope.stop() + + expect( + handle.live(), + 'teardown must invalidate in-flight work so a late resolve cannot act' + ).toBe(false) + }) + + it('still abandons attempts explicitly before teardown', () => { + const scope = effectScope() + const guard = scope.run(() => useGenerationGuard())! + const handle = guard.capture() + + guard.abandon() + + expect(handle.live()).toBe(false) + scope.stop() + }) +}) diff --git a/packages/account/src/vue/useGenerationGuard.ts b/packages/account/src/vue/useGenerationGuard.ts new file mode 100644 index 00000000000..13578b5a006 --- /dev/null +++ b/packages/account/src/vue/useGenerationGuard.ts @@ -0,0 +1,15 @@ +import { onScopeDispose } from 'vue' + +import { createBoundedOperation } from '../core/boundedOperation.js' +import type { BoundedOperation } from '../core/boundedOperation.js' + +/** + * A {@link createBoundedOperation} bound to the current Vue scope: when the + * component or effect scope disposes, every outstanding attempt is abandoned, + * so work resolving after teardown cannot act on an owner that is already gone. + */ +export function useGenerationGuard(): BoundedOperation { + const operation = createBoundedOperation() + onScopeDispose(operation.abandon) + return operation +} From 1abaf6f40d6c2df92a66e6a2d79c4c4cedfac02b Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Mon, 14 Sep 2026 18:34:44 +0530 Subject: [PATCH 2/5] test(account): honest lifecycle doc plus cycle and mid-await coverage --- .../account/src/core/boundedOperation.test.ts | 18 ++++++++++++++---- .../account/src/vue/lifecycleScope.test.ts | 7 +++++-- packages/account/src/vue/lifecycleScope.ts | 7 +++++-- .../account/src/vue/useGenerationGuard.test.ts | 17 +++++++++++++++++ 4 files changed, 41 insertions(+), 8 deletions(-) diff --git a/packages/account/src/core/boundedOperation.test.ts b/packages/account/src/core/boundedOperation.test.ts index dd9ff0daf7c..3cb5f209ee4 100644 --- a/packages/account/src/core/boundedOperation.test.ts +++ b/packages/account/src/core/boundedOperation.test.ts @@ -40,14 +40,24 @@ describe('createBoundedOperation', () => { ).toBe(true) }) - it('captures a fresh live handle after abandonment', () => { + it('keeps each prior cycle dead while the latest capture stays live', () => { const operation = createBoundedOperation() - operation.capture() + + const first = operation.capture() operation.abandon() + const second = operation.capture() + + expect(first.live()).toBe(false) + expect(second.live()).toBe(true) - const renewed = operation.capture() + operation.abandon() + const third = operation.capture() - expect(renewed.live()).toBe(true) + expect( + second.live(), + 'each abandonment must end its own cycle, not only the first' + ).toBe(false) + expect(third.live()).toBe(true) }) it('discards a result that resolves after the operation was abandoned mid-flight', async () => { diff --git a/packages/account/src/vue/lifecycleScope.test.ts b/packages/account/src/vue/lifecycleScope.test.ts index 28db5a85bc8..4cd96d71bd9 100644 --- a/packages/account/src/vue/lifecycleScope.test.ts +++ b/packages/account/src/vue/lifecycleScope.test.ts @@ -35,7 +35,7 @@ describe('createLifecycleScope', () => { ).toEqual([1]) }) - it('reopens the latch after stop so a failed install can be retried', () => { + it('restarts after an explicit stop', () => { const lifecycle = createLifecycleScope() const setup = vi.fn() @@ -43,7 +43,10 @@ describe('createLifecycleScope', () => { lifecycle.stop() lifecycle.start(setup) - expect(setup).toHaveBeenCalledTimes(2) + expect( + setup, + 'stop reopens the latch, so a later start must run setup again' + ).toHaveBeenCalledTimes(2) }) it('fires scope-disposal hooks registered by the setup on stop', () => { diff --git a/packages/account/src/vue/lifecycleScope.ts b/packages/account/src/vue/lifecycleScope.ts index a26009c6195..2d93da353ec 100644 --- a/packages/account/src/vue/lifecycleScope.ts +++ b/packages/account/src/vue/lifecycleScope.ts @@ -4,8 +4,11 @@ import type { EffectScope } from 'vue' /** * A detached {@link effectScope} for a module singleton that must own its * watchers' lifetime rather than borrow it from whichever component reaches it - * first. `start` installs the scope once; `stop` disposes it and reopens the - * latch, so a failed async install can tear down and let the next caller retry. + * first. `start` installs the scope once and latches; `stop` disposes it and + * reopens the latch so `start` may be called again. `start` is synchronous and + * detects no failure of its own — recovering from a failed install is the + * caller's responsibility: `.catch` the failure and call `stop` to reopen the + * latch before the next `start`. */ export interface LifecycleScope { start: (setup: () => void) => void diff --git a/packages/account/src/vue/useGenerationGuard.test.ts b/packages/account/src/vue/useGenerationGuard.test.ts index acc23c404ad..2e06528aaa4 100644 --- a/packages/account/src/vue/useGenerationGuard.test.ts +++ b/packages/account/src/vue/useGenerationGuard.test.ts @@ -18,6 +18,23 @@ describe('useGenerationGuard', () => { ).toBe(false) }) + it('invalidates a handle when its scope disposes mid-await', async () => { + const scope = effectScope() + const guard = scope.run(() => useGenerationGuard())! + const handle = guard.capture() + + const settled = (async () => { + await Promise.resolve() + return handle.live() + })() + scope.stop() + + expect( + await settled, + 'a continuation resuming after scope teardown must see a dead handle' + ).toBe(false) + }) + it('still abandons attempts explicitly before teardown', () => { const scope = effectScope() const guard = scope.run(() => useGenerationGuard())! From 75893fb8293fbf157ae3f27aff23a66a27562f75 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 15 Sep 2026 11:20:29 +0530 Subject: [PATCH 3/5] docs(account): document lifecycleScope SSR skip and failure ownership Spell out that start is a server no-op that does not latch, and that start returns void so a failing setup catches its own promise and calls stop. --- packages/account/src/vue/lifecycleScope.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/packages/account/src/vue/lifecycleScope.ts b/packages/account/src/vue/lifecycleScope.ts index 2d93da353ec..7f7aab36546 100644 --- a/packages/account/src/vue/lifecycleScope.ts +++ b/packages/account/src/vue/lifecycleScope.ts @@ -5,10 +5,14 @@ import type { EffectScope } from 'vue' * A detached {@link effectScope} for a module singleton that must own its * watchers' lifetime rather than borrow it from whichever component reaches it * first. `start` installs the scope once and latches; `stop` disposes it and - * reopens the latch so `start` may be called again. `start` is synchronous and - * detects no failure of its own — recovering from a failed install is the - * caller's responsibility: `.catch` the failure and call `stop` to reopen the - * latch before the next `start`. + * reopens the latch so `start` may be called again. + * + * On the server (`window` undefined) `start` is a no-op that does not latch, so + * the client's first `start` still installs. + * + * `start` is synchronous and returns void: it never surfaces a setup failure to + * its caller. A `setup` that can fail launches its own promise and catches it, + * calling `stop` from that handler to reopen the latch before a later `start`. */ export interface LifecycleScope { start: (setup: () => void) => void From 31888ed05863370f8f6d62e93d40d9727752d133 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 15 Sep 2026 14:14:46 +0530 Subject: [PATCH 4/5] fix(account): dispose the lifecycle scope when setup throws synchronously A synchronous throw from setup left the detached scope assigned, so the latch stayed shut (every later start returned early) and effects registered before the throw leaked. Dispose the scope, clear it, and rethrow so a failed install reopens the latch. --- .../account/src/vue/lifecycleScope.test.ts | 17 +++++++++++++++++ packages/account/src/vue/lifecycleScope.ts | 18 +++++++++++++----- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/packages/account/src/vue/lifecycleScope.test.ts b/packages/account/src/vue/lifecycleScope.test.ts index 4cd96d71bd9..1f249240bdb 100644 --- a/packages/account/src/vue/lifecycleScope.test.ts +++ b/packages/account/src/vue/lifecycleScope.test.ts @@ -49,6 +49,23 @@ describe('createLifecycleScope', () => { ).toHaveBeenCalledTimes(2) }) + it('reopens the latch when setup throws synchronously', () => { + const lifecycle = createLifecycleScope() + const good = vi.fn() + + expect(() => + lifecycle.start(() => { + throw new Error('install failed') + }) + ).toThrow('install failed') + lifecycle.start(good) + + expect( + good, + 'a synchronous install failure disposes its scope and reopens the latch, so the next start still installs' + ).toHaveBeenCalledOnce() + }) + it('fires scope-disposal hooks registered by the setup on stop', () => { const lifecycle = createLifecycleScope() const disposed = vi.fn() diff --git a/packages/account/src/vue/lifecycleScope.ts b/packages/account/src/vue/lifecycleScope.ts index 7f7aab36546..3de82344477 100644 --- a/packages/account/src/vue/lifecycleScope.ts +++ b/packages/account/src/vue/lifecycleScope.ts @@ -10,9 +10,10 @@ import type { EffectScope } from 'vue' * On the server (`window` undefined) `start` is a no-op that does not latch, so * the client's first `start` still installs. * - * `start` is synchronous and returns void: it never surfaces a setup failure to - * its caller. A `setup` that can fail launches its own promise and catches it, - * calling `stop` from that handler to reopen the latch before a later `start`. + * `start` is synchronous. A synchronous throw from `setup` disposes the scope, + * reopens the latch, and rethrows, so a failed install leaves no stuck latch or + * leaked effects. Async failures are the setup's own to catch: a `setup` that + * launches a promise catches it and calls `stop` from that handler. */ export interface LifecycleScope { start: (setup: () => void) => void @@ -24,8 +25,15 @@ export function createLifecycleScope(): LifecycleScope { return { start(setup) { if (scope || typeof window === 'undefined') return - scope = effectScope(true) - scope.run(setup) + const created = effectScope(true) + scope = created + try { + created.run(setup) + } catch (error) { + created.stop() + scope = undefined + throw error + } }, stop() { scope?.stop() From 215b7dbd9a295aa9b409be98852416011426a42e Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 15 Sep 2026 16:42:22 +0530 Subject: [PATCH 5/5] docs(account): note useGenerationGuard needs an active Vue scope Without a component or effectScope, onScopeDispose no-ops and the guard never auto-abandons; point module-scope callers at createBoundedOperation instead. --- packages/account/src/vue/useGenerationGuard.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/account/src/vue/useGenerationGuard.ts b/packages/account/src/vue/useGenerationGuard.ts index 13578b5a006..72c1776f948 100644 --- a/packages/account/src/vue/useGenerationGuard.ts +++ b/packages/account/src/vue/useGenerationGuard.ts @@ -7,6 +7,10 @@ import type { BoundedOperation } from '../core/boundedOperation.js' * A {@link createBoundedOperation} bound to the current Vue scope: when the * component or effect scope disposes, every outstanding attempt is abandoned, * so work resolving after teardown cannot act on an owner that is already gone. + * + * Call it from a component `setup` or an active `effectScope`. With no active + * scope `onScopeDispose` no-ops, so it never auto-abandons; use + * {@link createBoundedOperation} directly at module scope instead. */ export function useGenerationGuard(): BoundedOperation { const operation = createBoundedOperation()