@tsln/timers 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateo Murphy
+
+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,53 @@
+# @tsln/timers
+
+`setTimeout`, `setInterval` and their `clear` counterparts for `[v8]` scripts, which have none,
+built on Max's `Task`.
+
+```ts
+import timers = require("./vendor/timers");
+
+const id = timers.setTimeout(redraw, 50);
+timers.clearTimeout(id);
+
+const tick = timers.setInterval(poll, 500, "arg");
+timers.clearInterval(tick);
+
+function notifydeleted() {
+  timers.clearAll(); // or the Tasks outlive the script
+}
+```
+
+They behave as they do anywhere else, give or take Max's scheduler: a Task runs in the
+low-priority queue, so a delay is a minimum rather than a promise, and 0 means "next tick".
+Both kinds share their ids, so `clearTimeout` clears an interval too, as in a browser. Extra
+arguments are passed to the callback, and are kept in a closure rather than handed to the Task,
+which would turn objects into null.
+
+## As globals
+
+A bundled npm package looks for the timers as globals. `install()` provides them, leaving alone
+any that already exist:
+
+```ts
+timers.install();
+import thing = require("./vendor/thing");
+```
+
+## Install
+
+```sh
+npm install --save-dev @tsln/timers
+```
+
+Max's `require()` searches Max's file path and knows nothing of `node_modules`, so the package's
+single CommonJS file, `dist/index.js`, has to be copied or bundled to somewhere Max can find it
+(the `max-msp` repository bundles it to `js/vendor/timers.js` with esbuild), with a declaration
+file next to it for the types:
+
+```ts
+// src/vendor/timers.d.ts
+import timers = require("@tsln/timers");
+export = timers;
+```
+
+The package depends on `@tsln/max-types` for `Task`.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="@tsln/max-types" preserve="true" />
+type Callback<A extends unknown[]> = (...args: A) => void;
+declare function setTimeout<A extends unknown[]>(fn: Callback<A>, ms?: number, ...args: A): number;
+declare function setInterval<A extends unknown[]>(fn: Callback<A>, ms?: number, ...args: A): number;
+/** Clears either kind of timer, as in a browser, where the two share their ids. */
+declare function clearTimeout(id?: number): void;
+/** Stops everything still waiting. Worth calling from notifydeleted(), or Tasks outlive the script. */
+declare function clearAll(): void;
+/**
+ * Makes the timers global, for code that expects to find them there. Whatever is already
+ * defined is left alone, so this does nothing under node or in a Max that grows its own.
+ */
+declare function install(): void;
+declare const _default: {
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    setInterval: typeof setInterval;
+    clearInterval: typeof clearTimeout;
+    clearAll: typeof clearAll;
+    install: typeof install;
+};
+export = _default;

package/dist/index.js

@@ -0,0 +1,61 @@
+"use strict";
+
+// src/index.ts
+var pending = {};
+var last = 0;
+function delay(ms) {
+  return Math.max(0, Number(ms) || 0);
+}
+function release(id) {
+  const task = pending[id];
+  if (!task) {
+    return;
+  }
+  delete pending[id];
+  task.cancel();
+  task.freepeer();
+}
+function setTimeout(fn, ms, ...args) {
+  const id = ++last;
+  const task = new Task(() => {
+    release(id);
+    fn(...args);
+  });
+  pending[id] = task;
+  task.schedule(delay(ms));
+  return id;
+}
+function setInterval(fn, ms, ...args) {
+  const id = ++last;
+  const wait = Math.max(1, delay(ms));
+  const task = new Task(() => {
+    task.schedule(wait);
+    fn(...args);
+  });
+  pending[id] = task;
+  task.schedule(wait);
+  return id;
+}
+function clearTimeout(id) {
+  release(id);
+}
+function clearAll() {
+  Object.keys(pending).forEach(release);
+}
+function install() {
+  const target = globalThis;
+  const globals = { setTimeout, clearTimeout, setInterval, clearInterval: clearTimeout };
+  for (const [name, fn] of Object.entries(globals)) {
+    if (typeof target[name] !== "function") {
+      target[name] = fn;
+    }
+  }
+}
+module.exports = {
+  setTimeout,
+  clearTimeout,
+  setInterval,
+  clearInterval: clearTimeout,
+  clearAll,
+  install
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tsln/timers",
+  "version": "0.0.0",
+  "description": "setTimeout, setInterval and their clear counterparts for Max [v8] scripts, built on Task, with an install() that makes them globals for bundled packages",
+  "license": "MIT",
+  "author": "Mateo Murphy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsln-lab/max-packages.git",
+    "directory": "packages/timers"
+  },
+  "keywords": [
+    "max",
+    "msp",
+    "max-msp",
+    "max-for-live",
+    "v8",
+    "settimeout",
+    "setinterval",
+    "timers",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tsln/max-types": "^0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --format=cjs --platform=neutral --target=es2022 --outfile=dist/index.js --log-level=warning",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node tests/timers.test.cjs"
+  }
+}