# globalAtom

Signature
`globalAtom<T>(defaultValue: T, options: GlobalAtomOptions): GlobalAtom<T>`

valdres
Creates a cross-store singleton atom

A global atom is a single shared value that stays in sync across every store
that touches it — writing in one store is immediately visible from any other.
This is the mechanism behind Valdres' `@valdres/*` browser-API packages: each
wraps one global atom around a browser subscription, so any store in the app
sees the same `online` status, `geolocation` position, and so on.

`options.name` is required — it is the atom's global address. Re-using a name
that's already registered throws.

## Usage

```ts
import { globalAtom } from "valdres"

const onlineAtom = globalAtom(navigator.onLine, { name: "app/online" })
```

Same call shape as [`atom`](https://valdres.dev/valdres/atom) — the only difference is that
`options.name` is required instead of optional.

## The self-accessors

A global atom carries three extra methods beyond the ordinary atom surface,
for reading and writing it without a `Store` handle:

```ts
onlineAtom.getSelf()        // read the current value
onlineAtom.setSelf(false)   // write — fans out to every store
onlineAtom.resetSelf()      // restore the default value everywhere
```

These are what a browser-API package's `onMount` uses to push external events
(a `navigator.onLine` change, a geolocation update, …) into the shared value:

```ts
const onlineAtom = globalAtom(navigator.onLine, {
    name: "app/online",
    onMount: () => {
        const update = () => onlineAtom.setSelf(navigator.onLine)
        window.addEventListener("online", update)
        window.addEventListener("offline", update)
        return () => {
            window.removeEventListener("online", update)
            window.removeEventListener("offline", update)
        }
    },
})
```

`onMount` fires once, when the FIRST subscriber across ANY store attaches, and
its cleanup fires once, when the LAST subscriber across ALL stores detaches —
so the underlying browser subscription is shared, not duplicated per store.

## Parameters

`globalAtom` accepts the same options as [`atom`](https://valdres.dev/valdres/atom) (`schema`,
`schemaValidation`, `onSet`, `onMount`, `maxAge`, `mutable`,
`staleWhileRevalidate`, `staleIfError`) as `GlobalAtomOptions` — identical to
`AtomOptions`, except `name` is required instead of optional.

## See also

- [atom](https://valdres.dev/valdres/atom) — create a single, per-store atom
- [globalAtomFamily](https://valdres.dev/valdres/globalAtomFamily) — a keyed collection of global atoms