Repository navigation
feat(account): add a bounded-operation lifecycle primitive #17641
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
5cad7d5
1abaf6f
75893fb
31888ed
215b7db
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| 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('keeps each prior cycle dead while the latest capture stays live', () => { | ||
| const operation = createBoundedOperation() | ||
|
|
||
| const first = operation.capture() | ||
| operation.abandon() | ||
| const second = operation.capture() | ||
|
|
||
| expect(first.live()).toBe(false) | ||
| expect(second.live()).toBe(true) | ||
|
|
||
| operation.abandon() | ||
| const third = operation.capture() | ||
|
|
||
| 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 () => { | ||
| 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) | ||
| }) | ||
| }) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. question (non-blocking): Answering the Review Focus directly — I checked this semantic against the call sites that will adopt it, and it holds for two of the three cleanly:
The third is where I would like your read. Is a
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. On workshop-session-state, the old |
||
| return { live: () => captured === generation } | ||
| }, | ||
| abandon() { | ||
| generation += 1 | ||
| } | ||
| } | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| 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('restarts after an explicit stop', () => { | ||
| const lifecycle = createLifecycleScope() | ||
| const setup = vi.fn() | ||
|
|
||
| lifecycle.start(setup) | ||
| lifecycle.stop() | ||
| lifecycle.start(setup) | ||
|
|
||
| expect( | ||
| setup, | ||
| 'stop reopens the latch, so a later start must run setup again' | ||
| ).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() | ||
| lifecycle.start(() => { | ||
| onScopeDispose(disposed) | ||
| }) | ||
|
|
||
| lifecycle.stop() | ||
|
|
||
| expect(disposed).toHaveBeenCalledOnce() | ||
| }) | ||
| }) |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| 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 and latches; `stop` disposes it and | ||
| * 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. 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 | ||
| stop: () => void | ||
| } | ||
|
|
||
| export function createLifecycleScope(): LifecycleScope { | ||
| let scope: EffectScope | undefined | ||
| return { | ||
| start(setup) { | ||
| if (scope || typeof window === 'undefined') return | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. suggestion (non-blocking): This SSR skip is load-bearing but invisible from the contract. The JSDoc above says " It is also unexercised. Every suite in this repo inherits Could we add one sentence to the JSDoc (something like "in a non-browser environment
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Documented in the JSDoc: start is a server no-op (window undefined) that does not latch, so the client's first start still installs. |
||
| const created = effectScope(true) | ||
| scope = created | ||
| try { | ||
| created.run(setup) | ||
| } catch (error) { | ||
| created.stop() | ||
| scope = undefined | ||
| throw error | ||
| } | ||
| }, | ||
| stop() { | ||
| scope?.stop() | ||
| scope = undefined | ||
| } | ||
| } | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| 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) | ||
|
MaanilVerma marked this conversation as resolved.
Resolved
|
||
| }) | ||
|
|
||
| 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())! | ||
| const handle = guard.capture() | ||
|
|
||
| guard.abandon() | ||
|
|
||
| expect(handle.live()).toBe(false) | ||
| scope.stop() | ||
| }) | ||
| }) | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| 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. | ||
| * | ||
| * 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() | ||
| onScopeDispose(operation.abandon) | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. suggestion (non-blocking): worth saying in the doc block that this must be called from inside a component setup or an Vue's Every call site in this stack is inside a component, so nothing is broken today. A line in the JSDoc naming the requirement (or passing Vue's
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done in 16b423c. Added a JSDoc note that it must run inside a component |
||
| return operation | ||
| } | ||
Uh oh!
There was an error while loading. Please reload this page.