keytask-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Georg Schilin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,409 @@
+![logo](https://raw.githubusercontent.com/voodoofugu/keytask/refs/heads/main/src/assets/banner-logo.png)
+
+<h2></h2>
+
+### Table of contents
+
+- [About](#about)
+- [Installation](#installation)
+- [API](#api)
+- [Common patterns](#common-patterns)
+- [License](#license)
+
+<h2></h2>
+
+### 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.
+
+<h2></h2>
+
+### Installation
+
+```bash
+npm install keytask-core
+```
+
+```ts
+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.
+
+<h2></h2>
+
+### API
+
+<ul><div>
+
+###### **— GLOBAL —**
+
+<details><summary><b><code>setTask</code></b>: <em>schedule latest one-shot work by timeout or RAF</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+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.
+
+<br />
+
+<b>Description:</b><em><br />
+Schedules one task and returns its key.<br />
+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.<br />
+✦ A single key can only reference one active task within the same manager instance.
+</em><br />
+
+<b>Return:</b><br />
+Returns the passed key, or an automatically generated key when `key` is omitted.
+
+```ts
+const key = setTask(callback, "raf");
+
+cancelTask(key);
+```
+
+<b>Example:</b>
+
+```ts
+setTask(
+  () => {
+    doSomething();
+  },
+  "raf",
+  "my-key",
+);
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+<details><summary><b><code>setLockTask</code></b>: <em>run now, then lock repeated calls</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+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.
+
+<br />
+
+<b>Description:</b><em><br />
+Runs the callback immediately, then blocks repeated calls with the same key until the timeout ends or the next RAF unlocks it.<br />
+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.<br />
+✦ A single key can only reference one active task within the same manager instance.
+</em><br />
+
+<b>Return:</b><br />
+Returns the passed key, or an automatically generated key when `key` is omitted.
+
+```ts
+const key = setLockTask(callback, "raf");
+
+cancelTask(key);
+```
+
+<b>Example:</b>
+
+```ts
+setLockTask(
+  () => {
+    doSomething();
+  },
+  "raf",
+  "my-key",
+);
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+<details><summary><b><code>setThrottleTask</code></b>: <em>run now, then keep the latest repeated call while throttled</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+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.
+
+<br />
+
+<b>Description:</b><em><br />
+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.<br />
+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.<br />
+✦ A single key can only reference one active task within the same manager instance.
+</em><br />
+
+<b>Return:</b><br />
+Returns the passed key, or an automatically generated key when `key` is omitted.
+
+```ts
+const key = setThrottleTask(callback, "raf");
+
+cancelTask(key);
+```
+
+<b>Example:</b>
+
+```ts
+setThrottleTask(
+  () => {
+    doSomething();
+  },
+  "raf",
+  "my-key",
+);
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+<details><summary><b><code>setLoopTask</code></b>: <em>run repeated work by timeout or RAF</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+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.
+
+<br />
+
+<b>Description:</b><em><br />
+Starts repeated work and returns its key.<br />
+The callback receives a 1-based tick count, current time and delta since the previous tick. Return <code>false</code> to stop the loop.<br />
+✦ A single key can only reference one active task within the same manager instance.
+</em><br />
+
+<b>Return:</b><br />
+Returns the passed key, or an automatically generated key when `key` is omitted.
+
+```ts
+const key = setLoopTask(callback, "raf");
+
+cancelTask(key);
+```
+
+<b>Example:</b>
+
+```ts
+setLoopTask(
+  (tick, time, delta) => {
+    doSomething();
+
+    if (tick > 10) return false; // exit
+  },
+  "raf",
+  "my-key",
+);
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+<details><summary><b><code>cancelTask</code></b>: <em>cancel tasks</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+cancelTask("key");
+cancelTask(["key1", "key2"]);
+cancelTask(); // clear all tasks
+```
+
+<b>Description:</b><em><br />
+Cancels one, several, or all tasks in the global manager.
+</em><br />
+
+</div></ul></details>
+
+<h2></h2>
+
+<details><summary><b><code>hasTask</code></b>: <em>check tasks</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+hasTask("key");
+```
+
+<b>Description:</b><em><br />
+Check pending tasks, active locks, active throttles or active loops.<br />
+Returns <code>true</code> when the key belongs to any active task state in the global manager.
+</em><br />
+
+<b>Example:</b>
+
+```ts
+if (hasTask("render")) {
+  cancelTask("render");
+}
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+###### **— LOCAL —**
+
+<details><summary><b><code>createTaskManager</code></b>: <em>create isolated task state</em></summary><br /><ul><div>
+
+<b>Usage:</b><br />
+
+```ts
+const tasks = createTaskManager();
+```
+
+The returned manager has the same task methods as the global API, plus `clear()`.
+
+<b>Description:</b><em><br />
+Creates a local manager with its own one-shot tasks, locks, throttles and loops.<br />
+Use it for components, scenes, entities or modules that need isolated cleanup. Calling <code>clear()</code> cancels everything inside that local manager without touching the global manager.
+</em>
+
+<b>Example:</b>
+
+```ts
+const sceneTasks = createTaskManager();
+
+sceneTasks.setLoopTask(callback, "raf", "my-raf-key");
+sceneTasks.setTask(callback, 1000, "my-timeout-key");
+
+function destroyScene() {
+  sceneTasks.clear();
+}
+```
+
+</div></ul></details>
+
+<h2></h2>
+
+</div></ul>
+
+<h2></h2>
+
+### Common patterns
+
+<details><summary><b>Render batching</b>: <em>keep only the latest render request for the next frame</em></summary><br />
+
+```ts
+setTask(
+  () => {
+    render();
+  },
+  "raf",
+  "render",
+);
+```
+
+</details>
+
+<details><summary><b>Debounced work</b>: <em>reuse the same key so only the latest delayed callback runs</em></summary><br />
+
+```ts
+setTask(
+  () => {
+    saveDraft();
+  },
+  300,
+  "save-draft",
+);
+```
+
+</details>
+
+<details><summary><b>Input cooldown</b>: <em>run once, then ignore repeated calls while locked</em></summary><br />
+
+```ts
+setLockTask(
+  () => {
+    submitInput();
+  },
+  150,
+  "input",
+);
+```
+
+</details>
+
+<details><summary><b>Latest trailing update</b>: <em>run now, then preserve the latest update during the throttle window</em></summary><br />
+
+```ts
+setThrottleTask(
+  () => {
+    syncPointerState();
+  },
+  "raf",
+  "pointer",
+);
+```
+
+</details>
+
+<details><summary><b>Animation loop</b>: <em>run repeated work until the callback stops it</em></summary><br />
+
+```ts
+setLoopTask(
+  (tick, time, delta) => {
+    update(delta);
+
+    if (tick > 10) return false;
+  },
+  "raf",
+  "loop",
+);
+```
+
+</details>
+
+<details><summary><b>Local cleanup</b>: <em>isolate task state and clear it on teardown</em></summary><br />
+
+```ts
+const tasks = createTaskManager();
+
+tasks.setLoopTask(updateScene, "raf", "loop");
+tasks.setTask(removeHint, 1000, "hint");
+
+function destroy() {
+  tasks.clear();
+}
+```
+
+</details>
+
+<h2></h2>
+
+### License
+
+- [MIT](./LICENSE)

package/dist/cjs/index.cjs

@@ -0,0 +1 @@
+"use strict";const e=()=>"undefined"!=typeof performance&&performance.now?performance.now():Date.now();let t=0,a=!1;const n=()=>"key_"+t++,r=()=>"function"!=typeof globalThis.requestAnimationFrame||"function"!=typeof globalThis.cancelAnimationFrame?(a||(a=!0),{requestAnimationFrame:t=>globalThis.setTimeout(()=>t(e()),16),cancelAnimationFrame:e=>globalThis.clearTimeout(e)}):{requestAnimationFrame:e=>globalThis.requestAnimationFrame(e),cancelAnimationFrame:e=>globalThis.cancelAnimationFrame(e)};function l(){const t=[],a=new Map,l=new Map,i=new Map,s=new Set,o=new Map,c=new Map;let m=null,u=null;const d=()=>{null!==m&&(clearTimeout(m),m=null)},f=()=>{null!==u&&(r().cancelAnimationFrame(u),u=null)},k=()=>{if(d(),0===t.length)return;const a=t[0],n=Math.max(0,a.runAt-e());m=setTimeout(()=>{m=null;const a=e(),n=[];for(;t.length&&t[0].runAt<=a;){const e=t.shift();s.has(e.key)||n.push(e)}n.forEach(e=>{s.add(e.key);try{e.callback()}finally{s.delete(e.key)}}),k()},n)},h=e=>{const t=l.get(e);t&&(null!==t.timerId&&("raf"===t.timer?r().cancelAnimationFrame(t.timerId):clearTimeout(t.timerId)),l.delete(e))},T=(e,t)=>{const a=l.get(e);if(!a||s.has(e))return;a.timerId=null,a.tick+=1;const n=(a.tick,t-a.lastTime);let r;a.lastTime=t,s.add(e);try{r=a.callback(a.tick,t,n)}finally{s.delete(e)}!1!==r&&l.has(e)?y(a):l.delete(e)},y=t=>{if(!l.has(t.key))return;if("raf"===t.timer)return void(t.timerId=r().requestAnimationFrame(e=>T(t.key,e)));const a=Math.max(0,t.timer);t.timerId=setTimeout(()=>T(t.key,e()),a)},A=(e,t)=>{s.add(e);try{t()}finally{s.delete(e)}},p=e=>{const t=i.get(e);if(!t)return;t.timerId=null;const a=t.trailing;t.trailing=null,a?(A(e,a),i.has(e)&&g(t)):i.delete(e)},g=e=>{if(!i.has(e.key))return;if("raf"===e.timer)return void(e.timerId=r().requestAnimationFrame(()=>p(e.key)));const t=Math.max(0,e.timer);e.timerId=setTimeout(()=>p(e.key),t)},F=e=>{const t=i.get(e);t&&(null!==t.timerId&&("raf"===t.timer?r().cancelAnimationFrame(t.timerId):clearTimeout(t.timerId)),i.delete(e))},I=()=>{d(),f(),t.splice(0,t.length),a.clear(),s.clear(),o.forEach(e=>clearTimeout(e)),o.clear(),c.forEach(e=>r().cancelAnimationFrame(e)),c.clear(),Array.from(l.keys()).forEach(h),Array.from(i.keys()).forEach(F)},x=e=>s.has(e)||o.has(e)||c.has(e)||a.has(e)||l.has(e)||i.has(e)||t.some(t=>t.key===e),M=e=>{s.delete(e);const n=o.get(e);void 0!==n&&(clearTimeout(n),o.delete(e));const l=c.get(e);void 0!==l&&(r().cancelAnimationFrame(l),c.delete(e)),(e=>{a.delete(e),0===a.size&&f();const n=t.filter(t=>t.key!==e);t.splice(0,t.length,...n)})(e),h(e),F(e)};return{setTask:(l,i,o)=>{const c=(null!=o?o:n())+"";if(void 0!==o&&M(c),"raf"===i)return a.set(c,l),null===u&&(u=r().requestAnimationFrame(()=>{u=null;const e=Array.from(a.entries());a.clear(),e.forEach(([e,t])=>{if(!s.has(e)){s.add(e);try{t()}finally{s.delete(e)}}})})),c;const m=Math.max(0,i),d={key:c,runAt:e()+m,callback:l};return function(e,t){let a=0,n=e.length;for(;n>a;){const r=a+n>>1;e[r].runAt<t.runAt?a=r+1:n=r}e.splice(a,0,t)}(t,d),k(),c},setLockTask:(e,t,a)=>{const l=(null!=a?a:n())+"";if(x(l))return l;s.add(l);try{e()}finally{if("raf"===t){const e=r().requestAnimationFrame(()=>{s.delete(l),c.delete(l)});c.set(l,e)}else{const e=setTimeout(()=>{s.delete(l),o.delete(l)},Math.max(0,t));o.set(l,e)}}return l},setThrottleTask:(e,t,a)=>{const r=(null!=a?a:n())+"",l=i.get(r);if(l)return l.trailing=e,r;void 0!==a&&M(r);const s={key:r,timer:t,trailing:null,timerId:null};return i.set(r,s),A(r,e),i.has(r)&&g(s),r},setLoopTask:(t,a,r)=>{const i=(null!=r?r:n())+"";void 0!==r&&M(i);const s={key:i,callback:t,timer:a,tick:0,lastTime:e(),timerId:null};return l.set(i,s),y(s),i},cancelTask:e=>{void 0!==e?((Array.isArray(e)?e:[e]).forEach(e=>M(e+"")),k()):I()},hasTask:e=>x(e+""),clear:I}}const i=l(),s=i.setTask,o=i.setLockTask,c=i.setThrottleTask,m=i.setLoopTask,u=i.cancelTask,d=i.hasTask;exports.cancelTask=u,exports.createTaskManager=l,exports.hasTask=d,exports.setLockTask=o,exports.setLoopTask=m,exports.setTask=s,exports.setThrottleTask=c;

package/dist/esm/index.js

@@ -0,0 +1 @@
+const e=()=>"undefined"!=typeof performance&&performance.now?performance.now():Date.now();let t=0,a=!1;const n=()=>"key_"+t++,r=()=>"function"!=typeof globalThis.requestAnimationFrame||"function"!=typeof globalThis.cancelAnimationFrame?(a||(a=!0),{requestAnimationFrame:t=>globalThis.setTimeout(()=>t(e()),16),cancelAnimationFrame:e=>globalThis.clearTimeout(e)}):{requestAnimationFrame:e=>globalThis.requestAnimationFrame(e),cancelAnimationFrame:e=>globalThis.cancelAnimationFrame(e)};function l(){const t=[],a=new Map,l=new Map,i=new Map,o=new Set,s=new Map,c=new Map;let m=null,u=null;const d=()=>{null!==m&&(clearTimeout(m),m=null)},f=()=>{null!==u&&(r().cancelAnimationFrame(u),u=null)},h=()=>{if(d(),0===t.length)return;const a=t[0],n=Math.max(0,a.runAt-e());m=setTimeout(()=>{m=null;const a=e(),n=[];for(;t.length&&t[0].runAt<=a;){const e=t.shift();o.has(e.key)||n.push(e)}n.forEach(e=>{o.add(e.key);try{e.callback()}finally{o.delete(e.key)}}),h()},n)},k=e=>{const t=l.get(e);t&&(null!==t.timerId&&("raf"===t.timer?r().cancelAnimationFrame(t.timerId):clearTimeout(t.timerId)),l.delete(e))},y=(e,t)=>{const a=l.get(e);if(!a||o.has(e))return;a.timerId=null,a.tick+=1;const n=(a.tick,t-a.lastTime);let r;a.lastTime=t,o.add(e);try{r=a.callback(a.tick,t,n)}finally{o.delete(e)}!1!==r&&l.has(e)?T(a):l.delete(e)},T=t=>{if(!l.has(t.key))return;if("raf"===t.timer)return void(t.timerId=r().requestAnimationFrame(e=>y(t.key,e)));const a=Math.max(0,t.timer);t.timerId=setTimeout(()=>y(t.key,e()),a)},A=(e,t)=>{o.add(e);try{t()}finally{o.delete(e)}},g=e=>{const t=i.get(e);if(!t)return;t.timerId=null;const a=t.trailing;t.trailing=null,a?(A(e,a),i.has(e)&&p(t)):i.delete(e)},p=e=>{if(!i.has(e.key))return;if("raf"===e.timer)return void(e.timerId=r().requestAnimationFrame(()=>g(e.key)));const t=Math.max(0,e.timer);e.timerId=setTimeout(()=>g(e.key),t)},F=e=>{const t=i.get(e);t&&(null!==t.timerId&&("raf"===t.timer?r().cancelAnimationFrame(t.timerId):clearTimeout(t.timerId)),i.delete(e))},I=()=>{d(),f(),t.splice(0,t.length),a.clear(),o.clear(),s.forEach(e=>clearTimeout(e)),s.clear(),c.forEach(e=>r().cancelAnimationFrame(e)),c.clear(),Array.from(l.keys()).forEach(k),Array.from(i.keys()).forEach(F)},b=e=>o.has(e)||s.has(e)||c.has(e)||a.has(e)||l.has(e)||i.has(e)||t.some(t=>t.key===e),M=e=>{o.delete(e);const n=s.get(e);void 0!==n&&(clearTimeout(n),s.delete(e));const l=c.get(e);void 0!==l&&(r().cancelAnimationFrame(l),c.delete(e)),(e=>{a.delete(e),0===a.size&&f();const n=t.filter(t=>t.key!==e);t.splice(0,t.length,...n)})(e),k(e),F(e)};return{setTask:(l,i,s)=>{const c=(null!=s?s:n())+"";if(void 0!==s&&M(c),"raf"===i)return a.set(c,l),null===u&&(u=r().requestAnimationFrame(()=>{u=null;const e=Array.from(a.entries());a.clear(),e.forEach(([e,t])=>{if(!o.has(e)){o.add(e);try{t()}finally{o.delete(e)}}})})),c;const m=Math.max(0,i),d={key:c,runAt:e()+m,callback:l};return function(e,t){let a=0,n=e.length;for(;n>a;){const r=a+n>>1;e[r].runAt<t.runAt?a=r+1:n=r}e.splice(a,0,t)}(t,d),h(),c},setLockTask:(e,t,a)=>{const l=(null!=a?a:n())+"";if(b(l))return l;o.add(l);try{e()}finally{if("raf"===t){const e=r().requestAnimationFrame(()=>{o.delete(l),c.delete(l)});c.set(l,e)}else{const e=setTimeout(()=>{o.delete(l),s.delete(l)},Math.max(0,t));s.set(l,e)}}return l},setThrottleTask:(e,t,a)=>{const r=(null!=a?a:n())+"",l=i.get(r);if(l)return l.trailing=e,r;void 0!==a&&M(r);const o={key:r,timer:t,trailing:null,timerId:null};return i.set(r,o),A(r,e),i.has(r)&&p(o),r},setLoopTask:(t,a,r)=>{const i=(null!=r?r:n())+"";void 0!==r&&M(i);const o={key:i,callback:t,timer:a,tick:0,lastTime:e(),timerId:null};return l.set(i,o),T(o),i},cancelTask:e=>{void 0!==e?((Array.isArray(e)?e:[e]).forEach(e=>M(e+"")),h()):I()},hasTask:e=>b(e+""),clear:I}}const i=l(),o=i.setTask,s=i.setLockTask,c=i.setThrottleTask,m=i.setLoopTask,u=i.cancelTask,d=i.hasTask;export{u as cancelTask,l as createTaskManager,d as hasTask,s as setLockTask,m as setLoopTask,o as setTask,c as setThrottleTask};

package/dist/types/helpers/getNow.d.ts

@@ -0,0 +1,2 @@
+declare const getNow: () => number;
+export default getNow;

package/dist/types/helpers/taskManager.d.ts

@@ -0,0 +1,105 @@
+import type { CancelTaskData, LoopTaskCallback, TaskCallback, TaskKey, TaskManager, TaskTimer } from "../types/types";
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***createTaskManager***:
+ * create isolated task state.
+ * @description
+ * Use it for components, scenes, entities or modules that need independent cleanup.
+ * @example
+ * ```ts
+ * const tasks = createTaskManager();
+ *
+ * tasks.setLoopTask(callback, "raf", "my-raf-key");
+ * tasks.setTask(callback, 1000, "my-timeout-key");
+ *
+ * tasks.clear();
+ * ```
+ */
+declare function createTaskManager(): TaskManager;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***setTask***:
+ * schedule latest one-shot work by timeout or RAF.
+ * @description
+ * If the same `key` is used again, the previous task state is replaced.
+ * @returns the passed key, or an automatically generated key when `key` is omitted.
+ * @example
+ * ```ts
+ * setTask(() => {
+ *   doSomething();
+ * }, "raf", "my-key");
+ * ```
+ */
+declare const setTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***setLockTask***:
+ * run work immediately, then lock repeated calls by key.
+ * @description
+ * The first call wins. Calls with a key that already belongs to a task state are ignored until that key becomes free.
+ * @returns the passed key, or an automatically generated key when `key` is omitted.
+ * @example
+ * ```ts
+ * setLockTask(() => {
+ *   doSomething();
+ * }, "raf", "my-key");
+ * ```
+ */
+declare const setLockTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***setThrottleTask***:
+ * run work immediately, then keep the latest repeated call while throttled.
+ * @description
+ * The first call runs immediately. Calls with the same `key` during the throttle window save only the latest callback, which runs when the window opens again.
+ * @returns the passed key, or an automatically generated key when `key` is omitted.
+ * @example
+ * ```ts
+ * setThrottleTask(() => {
+ *   doSomething();
+ * }, "raf", "my-key");
+ * ```
+ */
+declare const setThrottleTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***setLoopTask***:
+ * run repeated work by timeout or RAF.
+ * @description
+ * If the same `key` is used again, the previous task state is cancelled and replaced. Return `false` from callback to stop the loop.
+ * @returns the passed key, or an automatically generated key when `key` is omitted.
+ * @example
+ * ```ts
+ * setLoopTask((tick, time, delta) => {
+ *   doSomething();
+ *
+ *   if (tick > 10) return false;
+ * }, "raf", "my-key");
+ * ```
+ */
+declare const setLoopTask: (callback: LoopTaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***cancelTask***:
+ * cancel one task, several tasks or all tasks in the global manager.
+ * @example
+ * ```ts
+ * cancelTask("my-key");
+ * cancelTask(["key1", "key2"]);
+ * cancelTask();
+ * ```
+ */
+declare const cancelTask: (taskData?: CancelTaskData) => void;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***hasTask***:
+ * check whether a key belongs to any active task state.
+ * @example
+ * ```ts
+ * if (hasTask("my-key")) {
+ *   cancelTask("my-key");
+ * }
+ * ```
+ */
+declare const hasTask: (key: TaskKey) => boolean;
+export { cancelTask, createTaskManager, hasTask, setLockTask, setLoopTask, setTask, setThrottleTask, };

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { cancelTask, createTaskManager, hasTask, setLockTask, setLoopTask, setTask, setThrottleTask, } from "./helpers/taskManager";
+export type { CancelTaskData, LoopTaskCallback, TaskCallback, TaskKey, TaskManager, TaskTimer, } from "./types/types";

package/dist/types/types/types.d.ts

@@ -0,0 +1,195 @@
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***TaskKey***:
+ * shared task key used by `setTask`, `setLockTask`, `setThrottleTask`, `setLoopTask`, `cancelTask` and `hasTask`.
+ * @description
+ * `TaskKey` is intentionally a string. One key can belong to only one active task state inside a manager. Readable keys make scheduling calls easier to scan, especially when `timer` can be a number.
+ * @example
+ * ```ts
+ * setTask(callback, "raf", "my-key");
+ * setThrottleTask(callback, 150, "my-key");
+ * ```
+ */
+type TaskKey = string;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***TaskTimer***:
+ * scheduler used by task primitives.
+ * @description
+ * - `number`: *timeout delay in milliseconds*
+ * - `"raf"`: *run on `requestAnimationFrame`*
+ * @note
+ * `0` is a real `setTimeout(..., 0)` delay. Use `"raf"` explicitly for frame scheduling. RAF mode uses `requestAnimationFrame` / `cancelAnimationFrame` when available and falls back to `setTimeout(..., 16)` with a console warning when those APIs are missing.
+ * @example
+ * ```ts
+ * setTask(callback, 300, "my-key");
+ * setTask(callback, "raf", "my-key");
+ * ```
+ */
+type TaskTimer = number | "raf";
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***TaskCallback***:
+ * one-shot callback used by `setTask`, `setLockTask` and `setThrottleTask`.
+ * @example
+ * ```ts
+ * const callback: TaskCallback = () => {
+ *   doSomething();
+ * };
+ * ```
+ */
+type TaskCallback = () => void;
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***LoopTaskCallback***:
+ * repeated callback used by `setLoopTask`.
+ * @param tick 1-based loop iteration count.
+ * @param time current time from `performance.now()` / RAF timestamp.
+ * @param delta time passed since the previous loop tick.
+ * @returns `false` to stop the loop.
+ * @example
+ * ```ts
+ * setLoopTask((tick, time, delta) => {
+ *   doSomething();
+ *
+ *   if (tick > 10) return false;
+ * }, "raf", "my-key");
+ * ```
+ */
+type LoopTaskCallback = (tick: number, time: number, delta: number) => boolean | void;
+type Task = {
+    key: string;
+    callback: TaskCallback;
+    runAt: number;
+};
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***CancelTaskData***:
+ * input accepted by `cancelTask`.
+ * @description
+ * - `TaskKey`: *cancel one task by key*
+ * - `TaskKey[]`: *cancel several tasks by key*
+ * - `undefined`: *cancel everything in the manager*
+ * @example
+ * ```ts
+ * cancelTask("my-key");
+ * cancelTask(["key1", "key2"]);
+ * cancelTask();
+ * ```
+ */
+type CancelTaskData = TaskKey | TaskKey[];
+/**---
+ * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+ * ### ***TaskManager***:
+ * isolated key-based task manager.
+ * @description
+ * Use `createTaskManager()` when a component, scene, entity or module needs its own task state and cleanup.
+ * @example
+ * ```ts
+ * const tasks = createTaskManager();
+ *
+ * tasks.setLoopTask(callback, "raf", "my-raf-key");
+ * tasks.setTask(callback, 1000, "my-timeout-key");
+ *
+ * tasks.clear();
+ * ```
+ */
+type TaskManager = {
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***setTask***:
+     * schedule latest one-shot work by timeout or RAF.
+     * @description
+     * If the same `key` is used again, the previous task state is replaced.
+     * @returns the passed key, or an automatically generated key when `key` is omitted.
+     * @example
+     * ```ts
+     * manager.setTask(() => {
+     *   doSomething();
+     * }, "raf", "my-key");
+     * ```
+     */
+    setTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***setLockTask***:
+     * run work immediately, then lock repeated calls by key.
+     * @description
+     * The first call wins. Calls with a key that already belongs to a task state are ignored until that key becomes free.
+     * @returns the passed key, or an automatically generated key when `key` is omitted.
+     * @example
+     * ```ts
+     * manager.setLockTask(() => {
+     *   doSomething();
+     * }, "raf", "my-key");
+     * ```
+     */
+    setLockTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***setThrottleTask***:
+     * run work immediately, then keep the latest repeated call while throttled.
+     * @description
+     * The first call runs immediately. Calls with the same `key` during the throttle window save only the latest callback, which runs when the window opens again.
+     * @returns the passed key, or an automatically generated key when `key` is omitted.
+     * @example
+     * ```ts
+     * manager.setThrottleTask(() => {
+     *   doSomething();
+     * }, "raf", "my-key");
+     * ```
+     */
+    setThrottleTask: (callback: TaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***setLoopTask***:
+     * run repeated work by timeout or RAF.
+     * @description
+     * If the same `key` is used again, the previous task state is cancelled and replaced. Return `false` from callback to stop the loop.
+     * @returns the passed key, or an automatically generated key when `key` is omitted.
+     * @example
+     * ```ts
+     * manager.setLoopTask((tick, time, delta) => {
+     *   doSomething();
+     *
+     *   if (tick > 10) return false;
+     * }, "raf", "my-key");
+     * ```
+     */
+    setLoopTask: (callback: LoopTaskCallback, timer: TaskTimer, key?: TaskKey) => string;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***cancelTask***:
+     * cancel one task, several tasks or all tasks in the manager.
+     * @example
+     * ```ts
+     * manager.cancelTask("my-key");
+     * manager.cancelTask(["key1", "key2"]);
+     * manager.cancelTask();
+     * ```
+     */
+    cancelTask: (taskData?: CancelTaskData) => void;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***hasTask***:
+     * check whether a key belongs to any active task state.
+     * @example
+     * ```ts
+     * if (manager.hasTask("my-key")) {
+     *   manager.cancelTask("my-key");
+     * }
+     * ```
+     */
+    hasTask: (key: TaskKey) => boolean;
+    /**---
+     * ## ![logo](https://github.com/voodoofugu/keytask/raw/main/src/assets/keytask-logo.png)
+     * ### ***clear***:
+     * cancel every pending one-shot task, active lock, active throttle and active loop in this manager.
+     * @example
+     * ```ts
+     * tasks.clear();
+     * ```
+     */
+    clear: () => void;
+};
+export type { CancelTaskData, LoopTaskCallback, Task, TaskCallback, TaskKey, TaskManager, TaskTimer, };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "keytask-core",
+  "version": "1.0.0",
+  "description": "A tiny key-based task controller for timeout and RAF work.",
+  "author": "Georg Schilin",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voodoofugu/keytask.git"
+  },
+  "homepage": "https://github.com/voodoofugu/keytask#readme",
+  "keywords": [
+    "keytask",
+    "task",
+    "keyed",
+    "timer",
+    "timeout",
+    "raf",
+    "animation",
+    "game-loop",
+    "throttle",
+    "scheduler"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}