# timer-node

> A timestamp-based timer that enables recording elapsed time and formatting the result.

Latest version **5.0.9** (published 2025-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install timer-node
pnpm add timer-node
yarn add timer-node
bun add timer-node
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.9 |
| Published | 2025-01-26 |
| First published | 2018-10-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Eyas Ranjous |
| Maintainers | eyas-ranjous |
| Keywords | timer, timer.js, node timer, js timer |

## Links

- npm: https://www.npmjs.com/package/timer-node
- Repository: https://github.com/eyas-ranjous/timer-node
- Homepage: https://github.com/eyas-ranjous/timer-node#readme
- Issues: https://github.com/eyas-ranjous/timer-node/issues
- npm.io page: https://npm.io/package/timer-node

## Recent versions

- 5.0.9 (latest) — 2025-01-26
- 5.0.8 — 2025-01-25
- 5.0.7 — 2022-12-11
- 5.0.6 — 2022-06-20
- 5.0.5 — 2021-06-14
- 5.0.4 — 2021-05-03
- 5.0.3 — 2021-04-17
- 5.0.2 — 2021-03-25
- 5.0.1 — 2021-03-24
- 5.0.0 — 2021-03-23
- 4.1.0 — 2021-03-13
- 4.0.0 — 2021-02-26
- 3.1.0 — 2021-02-06
- 3.0.0 — 2020-07-07
- 2.0.0 — 2020-04-14
- … 4 more at https://npm.io/package/timer-node/versions

## README

# timer-node

[![npm](https://img.shields.io/npm/v/timer-node.svg)](https://www.npmjs.com/package/timer-node)
[![npm](https://img.shields.io/npm/dm/timer-node.svg)](https://www.npmjs.com/package/timer-node)

A **lightweight** JavaScript library for measuring elapsed time in Node.js or the browser without using `setInterval` or `setTimeout`. It also has type definitions for TypeScript.

## Installation

```bash
npm install timer-node
```

## API
### Import

```javascript
// JS
const { Timer } = require('timer-node');

// TS
import { Timer, TimerOptions, Time } from 'timer-node';
```

### Timer Class

A timestamp-based timer that can be started, paused, resumed, and stopped. It calculates durations based on system time.

#### Constructor

```ts
new Timer(options?: TimerOptions)
```

- `options`: An optional configuration object with:
  - `label?: string` – A label for this timer.
  - `startTimestamp?: number` – Start time (if you want to initialize from the past).
  - `endTimestamp?: number` – End time (if already stopped).
  - `currentStartTimestamp?: number` – Most recent resume time.
  - `pauseCount?: number` – Number of times paused.
  - `accumulatedMs?: number` – Accumulated milliseconds from previous runs.

#### Common Methods

- **start()**: Starts (or restarts) the timer.
- **pause()**: Pauses the timer (if running).
- **resume()**: Resumes the timer (if paused).
- **stop()**: Stops the timer.
- **clear()**: Clears all timer data, resetting it to an unstarted state.
- **isStarted() / isPaused() / isRunning() / isStopped()**: Check the timer state.
- **ms()**: Returns the elapsed time in milliseconds.
- **time()**: Returns an object of time fractions (`d`, `h`, `m`, `s`, `ms`).
- **pauseMs() / pauseTime()**: Similar to `ms()` / `time()`, but for paused duration.
- **pauseCount()**: Returns how many times the timer has been paused.
- **format(template?: string)**: Formats the elapsed time using placeholders (`%label`, `%d`, `%h`, `%m`, `%s`, `%ms`).
- **serialize()**: Returns a JSON string representing the timer state.

#### Static Methods

- **Timer.deserialize(serializedTimer: string): Timer**\
  Re-creates a timer from a serialized string generated by `.serialize()`.

- **Timer.benchmark(fn: () => any): Timer**\
  Measures the synchronous execution time of `fn`. Returns a stopped `Timer`.

---

### Time Object

Any method returning an object breakdown of time uses the following shape:

```ts
interface Time {
  d: number;  // days
  h: number;  // hours
  m: number;  // minutes
  s: number;  // seconds
  ms: number; // milliseconds
}
```

## Example

```js
const { Timer } = require('timer-node');

const timer = new Timer({ label: 'demo' });
timer.start();

// ... some operations ...

timer.pause();
console.log('Paused at', timer.ms(), 'ms');
timer.resume();

// ... more operations ...

timer.stop();
console.log('Total elapsed:', timer.time());
// e.g. { d: 0, h: 0, m: 1, s: 12, ms: 345 }
```

## License

This library is licensed under the MIT License. See [LICENSE](https://github.com/eyas-ranjous/timer-node/blob/master/LICENSE) for details.

---
_Source: https://npm.io/package/timer-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._