✨ Features

• Centralized — every timer lives in one registry, keyed by a name you choose. No more lost setInterval IDs scattered across your codebase.
• Dynamic — restart any task with a new interval without keeping a reference to its callback.
• Immediate — optionally fire the callback once on registration, before the first tick.
• One-call cleanup — clear a single task or all of them at once, perfect for component unmounting or app shutdown.
• Tiny & universal — zero dependencies, ~1 kB minified+gzip, ships ESM + CJS, runs in browsers and Node.js, TypeScript types included.

📦 Installation

# npm
npm install timertasks

# pnpm
pnpm add timertasks

# yarn
yarn add timertasks

Works out of the box with both module systems via exports conditions:

// ESM
import { setTimedTask, clearAllTimedTask } from 'timertasks';

// CommonJS
const { setTimedTask, clearAllTimedTask } = require('timertasks');

🚀 Usage

import {
  setTimedTask,
  restartTimedTask,
  clearTimedTask,
  clearAllTimedTask,
} from 'timertasks';

// 1. Register and start a task that logs every second
setTimedTask(
  'heartbeat',
  () => console.log('Task is running...'),
  1000,
  { immediate: true }, // fires once right away, then every 1000ms
);

// 2. Switch it to a faster interval — no callback reference needed
restartTimedTask('heartbeat', 500);

// 3. Stop one task
clearTimedTask('heartbeat');

// 4. Stop everything (e.g. on app shutdown)
clearAllTimedTask();

A typical cleanup pattern in React:

useEffect(() => {
  setTimedTask('poll', fetchMetrics, 5_000, { immediate: true });
  return () => clearTimedTask('poll');
}, []);

📖 API Reference

setTimedTask(name, callback, time, options?)

Registers and starts an interval task.

| Parameter | Type | Description | | ------------------- | ---------------------- | ----------------------------------------------- | | name | string | Unique identifier for the task | | callback | () => void | Function to execute on each tick | | time | number | Interval in milliseconds | | options.immediate | boolean (optional) | If true, executes callback once immediately |

[!NOTE] Registering with a name that already exists overwrites the registry entry. Clear the previous task first (clearTimedTask(name)) before re-registering the same name.

restartTimedTask(name, newTime)

Stops the task and starts it again with a new interval, reusing the registered callback. No-op if name is not registered.

clearTimedTask(name)

Stops the task and removes it from the registry. No-op if name is not registered.

clearAllTimedTask()

Stops and removes every registered task.

timerTaskMap

The internal Map<string, [timerId, callback]> registry, exported for introspection (e.g. checking whether a task is registered via timerTaskMap.has(name)).

🛠️ Development

pnpm install        # install dependencies
pnpm run dev        # watch mode
pnpm run build      # build ESM + CJS to dist/
pnpm run test       # run the test suite (Rstest)
pnpm run typecheck  # TypeScript checking for src/ and tests/
pnpm run lint       # lint with Rslint

🤝 Contributing

Issues and pull requests are welcome at MissGwen/timertasks.

📜 Changelog

See CHANGELOG.md for release notes.

📄 License

MIT © MissGwen