https://github.com/eagle-head/timekeeper-countdown
Lightweight countdown engine that powers the Timekeeper packages. Pure TypeScript.
https://github.com/eagle-head/timekeeper-countdown
countdown javascript timer typescript
Last synced: 8 days ago
JSON representation
Lightweight countdown engine that powers the Timekeeper packages. Pure TypeScript.
- Host: GitHub
- URL: https://github.com/eagle-head/timekeeper-countdown
- Owner: eagle-head
- License: mit
- Created: 2024-09-06T00:24:03.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-04T20:58:59.000Z (4 months ago)
- Last Synced: 2026-06-14T03:13:12.146Z (20 days ago)
- Topics: countdown, javascript, timer, typescript
- Language: TypeScript
- Homepage: https://eagle-head.github.io/timekeeper-countdown/
- Size: 850 KB
- Stars: 18
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# Timekeeper Countdown ⏳
[](https://www.npmjs.com/package/@timekeeper-countdown/react)
[](https://www.npmjs.com/package/@timekeeper-countdown/core)
[](https://github.com/eagle-head/timekeeper-countdown/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
Welcome to the monorepo for **Timekeeper Countdown**. The current public release ships the React hook package; the shared countdown engine lives alongside it and powers the hook as well as future adapters.
## Why Timekeeper?
Most countdown libraries either lock you into a framework or sacrifice precision for simplicity. Timekeeper ships a **zero-dependency engine** that any framework can wrap, plus a React hook that uses it today.
- **Wall-clock precision** — tracks elapsed time via `performance.now`, not tick counting. Pausing and resuming never drifts.
- **Snapshot-driven API** — every tick delivers an immutable snapshot with pre-calculated `parts` (hours, minutes, seconds) and boolean helpers (`isRunning`, `isPaused`). No manual math.
- **Testable by design** — `@timekeeper-countdown/core/testing-utils` ships a fake time provider so you can unit-test countdown logic without `setTimeout` hacks.
- **Framework-agnostic core** — the engine has zero runtime dependencies. React today, Angular/Vue/Svelte adapters coming.
## Packages
| Package | Description | Status |
| --- | --- | --- |
| `@timekeeper-countdown/react` | React hook (`useCountdown`) that exposes the snapshot-driven timer API. | Stable / Published |
| `@timekeeper-countdown/core` | Countdown engine, formatting helpers, testing utilities. Powers the React hook and future framework adapters. | Stable / Published |
Planned adapters (Angular, Vue, Svelte, vanilla) will reuse the same engine; documentation and APIs will expand as each becomes available.
## Docs
The `docs/` folder contains the [VitePress](https://vitepress.dev/)-powered documentation site. Run the dev server locally:
```bash
npm run docs:dev
```
Or build for production with `npm run docs:build`. The site is deployed to GitHub Pages via CI.
Useful entry points:
- `docs/getting-started.md` – install & render your first React timer.
- `docs/react-integration.md` – hook API and usage patterns.
- `docs/roadmap.md` – status and plans for additional adapters.
## Development
Install dependencies once at the workspace root:
```bash
npm install
```
Key scripts:
```bash
npm run build # Build all packages with tsup
npm run test # Run Vitest across workspaces
npm run lint # Lint via ESLint 9
npm run typecheck # TypeScript --noEmit for every workspace
```
Each package also exposes the same scripts via `npm run --workspace <name>` for focused work (e.g., `@timekeeper-countdown/react`).
### Package Builds
Both packages ship ESM bundles built through `tsup`. The React package publishes the hook, exports TypeScript definitions, and declares `react` / `react-dom` as peer dependencies. The core package provides the engine and shared utilities.
### Tests
Vitest powers the unit test suites in both packages. React tests use `@testing-library/react` with fake timers supplied by the testing utilities. When iterating on a single package, use `npm run test --workspace @timekeeper-countdown/react` (or `core`).
## Contributing
We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) to get started.
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
## License
MIT © [Eduardo Kohn](https://www.linkedin.com/in/eduardo-kohn-56817b195/)