Table of contents

• About
• Installation
• API
• Common patterns
• License

About

keytask is a tiny TypeScript library for key-based control of timing-sensitive work.

It is designed for render-heavy UI, scroll libraries, animation systems and games: places where you need to schedule, replace, lock, loop and cancel work without scattering raw setTimeout, requestAnimationFrame and cleanup state across the codebase.

It is not an animation engine. It does not provide easing, tweens, timelines, physics or rendering. It only controls when work is allowed to run.

The core idea is simple - the same task key always describes the same unit of work.

Installation

npm install keytask-core

import { setTask } from "keytask-core";

✦ Note:

• Supports both ESM (import) and CommonJS (require) builds.
• Supports one shared global manager and isolated local managers.
• Written in TypeScript and ships declaration files.
• No runtime dependencies.
• RAF mode uses requestAnimationFrame / cancelAnimationFrame when available and falls back to setTimeout(..., 16) with a console warning when those APIs are missing.

API

— GLOBAL —

Usage:

setTask(callback, timer, key?);

• callback - work to run once.
• timer - timeout in milliseconds or "raf".
• key - optional string key, reusing the same key replaces the previous task state.

Description: Schedules one task and returns its key. This is useful for "latest wins" work: scroll-end handlers, delayed cleanup, render batching, or any task where only the newest pending callback should survive. ✦ A single key can only reference one active task within the same manager instance.

Return: Returns the passed key, or an automatically generated key when key is omitted.

const key = setTask(callback, "raf");

cancelTask(key);

Example:

setTask(
  () => {
    doSomething();
  },
  "raf",
  "my-key",
);

Usage:

setLockTask(callback, timer, key?);

• callback - work to run immediately.
• timer - lock duration in milliseconds or "raf" for a frame lock.
• key - optional string key, calls are ignored while the key already belongs to any task state.

Description: Runs the callback immediately, then blocks repeated calls with the same key until the timeout ends or the next RAF unlocks it. This is useful for "first wins" work: frame locks, cooldowns, input guards, or preventing repeated calls from doing too much work in the same frame/window. ✦ A single key can only reference one active task within the same manager instance.

Return: Returns the passed key, or an automatically generated key when key is omitted.

const key = setLockTask(callback, "raf");

cancelTask(key);

Example:

setLockTask(
  () => {
    doSomething();
  },
  "raf",
  "my-key",
);

Usage:

setThrottleTask(callback, timer, key?);

• callback - work to run immediately, or save as the latest trailing call while throttled.
• timer - throttle window in milliseconds or "raf" for a frame throttle.
• key - optional string key, repeated calls with the same key keep only the latest trailing callback.

Description: Runs the first callback immediately. While the key is throttled, repeated calls do not run immediately. Instead, only the latest callback is saved and runs when the throttle window opens again. This is useful for "first now, latest later" work: pointer updates, resize updates, scroll sync, render requests or other cases where dropping the final update would be incorrect. ✦ A single key can only reference one active task within the same manager instance.

Return: Returns the passed key, or an automatically generated key when key is omitted.

const key = setThrottleTask(callback, "raf");

cancelTask(key);

Example:

setThrottleTask(
  () => {
    doSomething();
  },
  "raf",
  "my-key",
);

Usage:

setLoopTask(callback, timer, key?);

• callback - repeated work. Receives tick, time, and delta.
• timer - interval in milliseconds or "raf" for an animation-frame loop.
• key - optional string key, reusing the same key replaces the previous task state.

Description: Starts repeated work and returns its key. The callback receives a 1-based tick count, current time and delta since the previous tick. Return false to stop the loop. ✦ A single key can only reference one active task within the same manager instance.

Return: Returns the passed key, or an automatically generated key when key is omitted.

const key = setLoopTask(callback, "raf");

cancelTask(key);

Example:

setLoopTask(
  (tick, time, delta) => {
    doSomething();

    if (tick > 10) return false; // exit
  },
  "raf",
  "my-key",
);

Usage:

cancelTask("key");
cancelTask(["key1", "key2"]);
cancelTask(); // clear all tasks

Description: Cancels one, several, or all tasks in the global manager.

Usage:

hasTask("key");

Description: Check pending tasks, active locks, active throttles or active loops. Returns true when the key belongs to any active task state in the global manager.

Example:

if (hasTask("render")) {
  cancelTask("render");
}

— LOCAL —

Usage:

const tasks = createTaskManager();

The returned manager has the same task methods as the global API, plus clear().

Description: Creates a local manager with its own one-shot tasks, locks, throttles and loops. Use it for components, scenes, entities or modules that need isolated cleanup. Calling clear() cancels everything inside that local manager without touching the global manager.

Example:

const sceneTasks = createTaskManager();

sceneTasks.setLoopTask(callback, "raf", "my-raf-key");
sceneTasks.setTask(callback, 1000, "my-timeout-key");

function destroyScene() {
  sceneTasks.clear();
}

Common patterns

setTask(
  () => {
    render();
  },
  "raf",
  "render",
);

setTask(
  () => {
    saveDraft();
  },
  300,
  "save-draft",
);

setLockTask(
  () => {
    submitInput();
  },
  150,
  "input",
);

setThrottleTask(
  () => {
    syncPointerState();
  },
  "raf",
  "pointer",
);

setLoopTask(
  (tick, time, delta) => {
    update(delta);

    if (tick > 10) return false;
  },
  "raf",
  "loop",
);

const tasks = createTaskManager();

tasks.setLoopTask(updateScene, "raf", "loop");
tasks.setTask(removeHint, 1000, "hint");

function destroy() {
  tasks.clear();
}

License

• MIT