Options

StopwatchOptions is the second constructor argument to Stopwatch. Adapters fold the same fields (plus clock) into one options object and forward them into new Stopwatch(clock, options).

type StopwatchOptions = {
  precisionMs?: number
}

new Stopwatch(clock?, options?: StopwatchOptions)

Export StopwatchOptions from @watchstop/core. Normative behavior for each field lives on this page; Stopwatch covers construction, methods, and the tick loop.

clock is not part of StopwatchOptions. Pass it as the first constructor argument, or as clock on an adapter options object. Timer and mock clock knobs stay on Timer (intervalMs) and Testing (frameDelay).

precisionMs

• Use a finite number > 0 (for example 1000 for whole-second UI). Invalid values throw (RangeError).
• Omit when subscribers need sub-bucket updates (smooth UI, or anything that must react on every tick).
• Set when the UI (or other listeners) only care about a coarser bucket — fewer subscriber wakes while ticks still run at clock cadence.

import { Stopwatch, createMockClock } from '@watchstop/core'

const everyTick = new Stopwatch(createMockClock())
const wholeSeconds = new Stopwatch(createMockClock(), { precisionMs: 1000 })

Framework adapters that show elapsed re-render on each notify. Omitting precisionMs under createBrowserClock means roughly 60 updates per second; { precisionMs: 1000 } moves updates toward once per second. Keep fine-grained reads in the smallest possible component when you still need them.

Adapter stopwatch (shared instance)

Not part of core StopwatchOptions. Framework adapters accept an optional stopwatch on their options object to borrow an existing Stopwatch:

• Bind get / subscribe / controls to that instance
• Do not construct a second stopwatch
• Do not call destroy() on teardown

clock and precisionMs apply only when the adapter constructs (owned mode). They are mutually exclusive with stopwatch (TypeScript discriminant).

See framework pages and issue #6.

Related work

Not documented here until shipped:

• Visibility-aware suspend — candidate future StopwatchOptions or Browser default
• Shared scheduler — mostly “pass one shared clock”; Architecture + Stopwatch when chosen

Parent tracking: notification cost.