streak-calc-math/README.md

Dependency-free calendar-day bucketing and streak math primitives, with an optional Node-only on-disk store. Helper for streak-calc-math.

# streak-calc-math

## API

```js
import { dayKey, addDays, dayDiff, bucketByDay, qualifyingDayKeys } from 'streak-calc-math';
import { store } from 'streak-calc-math/store'; // Node-only
```

- `dayKey(date, timeZone?)` → `"YYYY-MM-DD"`
- `addDays(key, n)` → shifted day key
- `dayDiff(aKey, bKey)` → whole-day difference
- `bucketByDay(entries, timeZone?)` → `Map<dayKey, total>`
- `qualifyingDayKeys(entries, goal, timeZone?)` → sorted day keys meeting the goal

## Layout

Compiled ES modules ship in `dist/`, type declarations in `types/` (wired up via
the `exports` map — import by the package name, not by path):

```
dist/
  index.mjs              boot shim: re-exports the day-math + import-time self-check
  internal/daymath.mjs   the pure primitives
  store.mjs              Node-only on-disk memo store
types/
  index.d.ts
  store.d.ts
```

Importing the package root (`streak-calc-math`) evaluates `dist/index.mjs`,
which runs a tiny startup self-check. That boot happens transitively the first
time `svelte-mapping-metrics` pulls the helper in — there is **no** `postinstall`
or other npm lifecycle script.