Interval2 & Timeout2

A cancellable interval and timeout library for Node.js that allows you to create intervals and timeouts that can be easily started, paused, and renewed. This library provides enhanced control over timing execution, making it suitable for various timing-related tasks in your applications.

Installation

# Using npm
npm install @bemedev/interval2

# Using bun
bun add @bemedev/interval2

# Using pnpm
pnpm add @bemedev/interval2

# Using yarn
yarn add @bemedev/interval2

Package Exports

This package provides multiple export subpaths configured in package.json:

| Export Subpath | Import Path | Description | | -------------- | ----------------------------- | ------------------------------------------------------------------------------- | | . | @bemedev/interval2 | Main entry point re-exporting core createInterval & createTimeout utilities | | ./interval | @bemedev/interval2/interval | Interval exports (createInterval, createInterval2, Interval2) | | ./timeout | @bemedev/interval2/timeout | Timeout exports (createTimeout, createTimeout2, Timeout2) | | ./timer | @bemedev/interval2/timer | Abstract base class Timer2 | | ./types | @bemedev/interval2/types | All TypeScript type definitions | | ./helpers | @bemedev/interval2/helpers | Re-exports sleep utilities from @bemedev/sleep |

Usage

Interval2

import { createInterval } from '@bemedev/interval2';

const interval = createInterval({
  id: 'my-interval',
  interval: 1000,
  callback: () => {
    console.log('Interval executed');
  },
});

// Start the interval
interval.start();

// Pause the interval
interval.pause();

// Renew the interval with new settings
const renewed = interval.renew({ interval: 2000 });

// Dispose the interval
interval.dispose();

Timeout2

import { createTimeout } from '@bemedev/interval2';

const timeout = createTimeout({
  id: 'my-timeout',
  callback: () => {
    console.log('Timeout executed');
  },
  timeout: 2000, // 2 seconds
});

// Start the timeout
timeout.start();

// Pause the timeout (preserves remaining time)
timeout.pause();

// Resume the timeout with remaining duration
timeout.resume();

// Dispose the timeout completely
timeout.dispose();

Detailed API Reference

1. Interval2 (createInterval / createInterval2 / create)

Factory function createInterval(options: IntervalParams) instantiates a cancellable interval timer instance.

Configuration Options (IntervalParams)

• id (string, mandatory): Unique string identifier for the interval instance.
• callback (Cb, mandatory): Execution callback function (() => void).
• interval (number, optional): Duration in milliseconds between ticks (defaults to 100).
• exact (boolean, optional): Flag for exact timing calculation (defaults to false).
• maxTicks (number, optional): Maximum tick count limit before automatic pause (defaults to 10000).
• pauser (PauserListener, optional): Custom predicate function (state, ticks) => boolean returning true to pause.

Instance Methods & Properties

• start(): Starts or resumes the interval timer. Transitions state to 'active'. Returns current TimerState.
• pause(): Pauses the active interval timer. Transitions state to 'paused'. Returns current TimerState.
• resume(): Alias for start(). Resumes the paused interval. Returns current TimerState.
• renew(params: RenewIntervalParams): Returns a new Interval2 instance with updated/merged configuration options (id is required, remaining options default to existing instance parameters).
• subscribe(listener: IntervalListener): Registers a state/tick listener (state: TimerState, ticks: number) => any. Returns an unsubscribe cleanup function () => boolean.
• **dispose() / [Symbol.dispose]() / [Symbol.asyncDispose](): Clears active timer handles, resets timing state, sets state = 'disposed', and removes all subscribers.
• get state(): Returns current lifecycle state ('idle' | 'active' | 'paused' | 'disposed').
• get interval(): Returns configured interval duration in milliseconds.
• get exact(): Returns true if exact timing calculation is enabled.
• get ticks(): Returns total executed tick count.
• get maxTicks(): Returns maximum allowed tick limit before auto-pausing.
• get pauser(): Returns custom pauser predicate listener if defined.
• get subscribed(): Returns true if active subscribers exist.

2. Timeout2 (createTimeout / createTimeout2 / create)

Factory function createTimeout(options: TimeoutParams) instantiates a cancellable timeout timer instance.

Configuration Options (TimeoutParams)

• id (string, mandatory): Unique string identifier for the timeout instance.
• callback (Cb, mandatory): Execution callback function (() => void).
• timeout (number, optional): Duration in milliseconds before timeout triggers (defaults to 1000).

Instance Methods & Properties

• start(): Starts fresh or resumes the timeout timer. Uses remaining time if resuming from pause. Transitions state to 'active'. Returns current TimerState.
• pause(): Pauses the active timeout timer and calculates remaining time. Transitions state to 'paused'. Returns current TimerState.
• resume(): Resumes the paused timeout using remaining time (calls start()). Returns current TimerState.
• renew(params: RenewTimeoutParams): Returns a new Timeout2 instance with updated/merged configuration options (id is required, remaining options default to existing instance parameters).
• subscribe(listener: TimeoutListener): Registers a state listener (state: TimerState) => any. Returns an unsubscribe cleanup function () => boolean.
• **dispose() / [Symbol.dispose]() / [Symbol.asyncDispose](): Clears active timeout handle, resets remaining duration, sets state = 'disposed', and removes all subscribers.
• get state(): Returns current lifecycle state ('idle' | 'active' | 'paused' | 'disposed').
• get timeout(): Returns configured timeout duration in milliseconds.
• get subscribed(): Returns true if active subscribers exist.

Features

• Interval2: Repeating execution with start, pause, and dispose capabilities
• Timeout2: Single execution with pause, resume, and stop capabilities
• Start, pause and dispose intervals and timeouts
• Renew intervals and timeouts with new settings
• State management ('idle', 'active', 'paused', 'disposed')
• Resource management with Symbol.dispose support
• 100% test coverage
• Integration with CI/CD pipeline
• TypeScript support
• Improved performance for timing execution

Licence

MIT

CHANGE_LOG

Version [1.2.1] - 07/08/2026 --> 01:08

• Add Detailed API Reference section and Package Exports table to README.md
• Update dependencies including rolldown ^1.2.3

Version [1.2.0] - 07/08/2026 --> 00:35

• Update JSDoc documentation across all TypeScript modules following standard guidelines
• Update test scripts in package.json for monorepo workspace compatibility

Version [1.1.4] - 30/07/2026 --> 14:41

• refactor: Extract testInterval helper from interval.ts into interval.fixtures.ts

Version [1.1.3] - 30/07/2026 --> 14:37

• refactor(tsconfig): Standardize tsconfig configuration across monorepo packages

Version [1.1.2] - 30/07/2026 --> 14:34

• fix(package): Exclude lib/node_modules directory from published package files

Version [1.1.1] - 30/07/2026 --> 14:30

• chore(deps): Add tslib dependency

Version [1.1.0] - 30/07/2026 --> 14:02

• refactor: Reorganize codebase into a pnpm monorepo structure
• feat(workspace): Add pnpm monorepo workspace configuration
• update(deps): Add @bemedev/sleep dependency to @bemedev/interval2
• update(ci): Update GitHub Actions workflow for NPM publishing from monorepo package

Version [1.0.1] - 26/05/2026 --> 15:08

• Clean up rolldown configuration by removing empty plugins array

Version [1.0.0] - 26/05/2026 --> 14:57

• Replace Rollup with Rolldown for improved build performance
• Migrate from ESLint + Prettier to OxLint + OxFmt for faster linting
• Add Node.js library development container configuration
• Enhance CI process with improved timing and reporting

Version [0.1.3] --> 02:20

• fix: Remove all console.log

Version [0.1.2] --> 01:50

• feat(timeout): Add new Timeout2 class with pause and stop capabilities
• feat(types): Add TimeoutParams type for timeout configuration

Version [0.1.1] --> 15:10

• Remove console.log

Version [0.1.0] --> 15:00

• ✨ First version of library
• Added basic interval functionality
• Implemented start and stop methods
• Included error handling for invalid intervals
• Provided documentation for usage
• Added unit tests for core features
• Integrated with CI/CD pipeline
• Improved performance for interval execution
• Fixed bugs related to interval overlap
• Enhanced logging for debugging purposes
• Updated dependencies to latest versions

Author

chlbri ([email protected])

My github

Links

• Documentation