# ntimer

> Event firing, repeatable, cancellable, auto-start capable timer for nodejs

Latest version **0.5.3** (published 2016-05-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install ntimer
pnpm add ntimer
yarn add ntimer
bun add ntimer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2016-05-12 |
| First published | 2016-05-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Venkat Peri |
| Maintainers | venkatperi |
| Keywords | auto, cancel, event, eventemitter, nodejs, start, timer |

## Links

- npm: https://www.npmjs.com/package/ntimer
- Repository: https://github.com/venkatperi/ntimer
- Homepage: https://github.com/venkatperi/ntimer#readme
- Issues: https://github.com/venkatperi/ntimer/issues
- npm.io page: https://npm.io/package/ntimer

## Dependencies (2)

- [error](https://npm.io/package/error.md) ^7.0.2
- [millisecond](https://npm.io/package/millisecond.md) ^0.1.2

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 0.5.3 (latest) — 2016-05-12
- 0.5.2 — 2016-05-12
- 0.5.1 — 2016-05-12
- 0.4.0 — 2016-05-12
- 0.3.3 — 2016-05-12
- 0.3.2 — 2016-05-12
- 0.3.1 — 2016-05-12
- 0.2.3 — 2016-05-11

## README

# ntimer
An event firing, repeatable, cancellable timer for `nodejs`.

[![Build Status](https://travis-ci.org/venkatperi/ntimer.svg?branch=master)](https://travis-ci.org/venkatperi/ntimer)
[![npm version](https://badge.fury.io/js/ntimer.svg)](https://badge.fury.io/js/ntimer)

# Installation

Install with npm

```shell
npm install ntimer --save
```

# Examples
### Just a Timer

```coffeescript
ntimer = require 'ntimer'

# Creates an manual-start timer which fires after 2000ms
ntimer('foo', '2s')
.on "done", -> # do something
.start()
```

### Auto Start

```coffeescript
# Creates an auto-start timer which fires after 200ms
# Must attach a 'timer' event listener to enable auto start
ntimer.auto('foo', 200)
.on "timer", -> # do something
```

### Cancel Timer

```coffeescript
# starts a second timer when the first starts which cancels 
# the first timer before the first timer ends.
ntimer.auto('foo', '5s')
.on "start", -> setTimeout ( => @cancel()), 500
.on "done", -> # do something
.on "cancel", -> # why, oh why?
```
### Repeat

```coffeescript
# Create an infinitely repeating timer whch fires every 500ms.
ntimer.repeat('foo', '500ms')
.on "timer", (name, count) -> # do something
.on "done", -> # never called
.on "cancel", -> # called if timer is cancelled
.start()
```
### Limited Repeat

```coffeescript
# Create a timer which fires every 500ms for five times.
ntimer.autoRepeat('foo', '500ms', 5)
.on "timer", (name, count) -> # do something
.on "done", -> # fired after the fifth 'timer' event
```

# API

## Create Timer

### ntimer(name, timeout)

### ntimer.auto(name, timeout)

Creates a single shot, restartable timer. `ntimer.auto` creates an auto starting timer.

* **name** `{String}` is returned as the first argument of events.
* **timeout** can be a `{Number}` in `milliseconds` or a `{String}` e.g. `'5s'` or `'2ms'` . See [format](https://github.com/unshiftio/millisecond). 

```coffeescript
ntimer('foo', 500)  # Single shot, manual start, 500ms timer.
```

> **Note:** An auto-starting timer will start **only** when it has a event listener for the `trigger` event.

```coffeescript
t = ntimer.auto('foo', 500)  # Create an auto start timer, 500ms

# The auto-start timer will start only after this listener is attached
t.on 'trigger', -> # do something
```

### ntimer.repeat(name, timeout[, maxRepeat])

### ntimer.autoRepeat(name, timeout[, maxRepeat])

Creates a repeating timer. `ntimer.auto` creates an auto starting version.

* **name** `{String}` is returned as the first argument of events.
* **timeout** can be a `{Number}` in `milliseconds` or a `{String}`. See [format](https://github.com/unshiftio/millisecond). 
* **maxRepeat** an optional `{Number}` specifies the maximum repeat count. 
```coffeescript
ntimer.repeat('foo', 500)  # Single shot, 500ms timer.
ntimer('foo', '2s')  # Single shot, 2 second timer.
```

## Properties

### timer.count

The `{Number}` of times the repeating timer has already fired.

### timer.running

`{Boolean}` indicating whether the timer is currently running.

## Methods

### timer.start()

Start a timer. No-op if already started. Returns the timer object for chaining.

### timer.cancel()
Cancels a running timer. No-op if not started or already stopped/cancelled. Returns the timer object for chaining.

## Events

### on("start", cb(name))

Fired when the timer is started (or restarted) with the **name** of the timer.

### on("cancel", cb(name))

Fired when the timer is cancelled with the **name** of the timer.

### on("done", cb(name))

Fired when the timer is done (not cancelled) with the **name** of the timer.

### on("timer", cb(name, count))

Fired for each `timeout` interval,  once for single shot timers, or repeatedly for repeating timers, with the **name** of the timer and the the **count** of the times the timer has triggered so far.

## ntimer.Timer Class
`ntimer` exports the Timer class.

## String Formats for Time

Uses the [millisecond](https://github.com/unshiftio/millisecond) module. The following formats are acceptable:

- x milliseconds
- x millisecond
- x msecs
- x msec
- x ms
- x seconds
- x second
- x secs
- x sec
- x s
- x minutes
- x minute
- x mins
- x min
- x m
- x hours
- x hour
- x hrs
- x hr
- x h
- x days
- x day
- x d
- x weeks
- x week
- x wks
- x wk
- x w
- x years
- x year
- x yrs
- x yr
- x y


The space after the number is optional so you can also write `1ms` instead of `1 ms`.

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