@oscarpalmer/timer 0.19.0 → 0.21.0

package/README.md

@@ -8,8 +8,6 @@ A better solution for timeout- and interval-based timers.
 
 Timer is available on _npm_ as [`@oscarpalmer/timer`](https://www.npmjs.com/package/@oscarpalmer/timer) to be bundled with your awesome projects.
 
-If you don't need to bundle things, you can use the CDN-version and include a script in your proejcts right away, thanks to [jsDelivr](https://www.jsdelivr.com/package/npm/@oscarpalmer/timer) and  [UNPKG](https://unpkg.com/@oscarpalmer/timer).
-
 ## Getting started
 
 This is fairly lightweight package, so hopefully you'll be up and running in seconds :blush:
@@ -21,65 +19,62 @@ The timers can be called with nice helper methods, which also auto-starts the ti
 ```typescript
 import {repeat, wait} from '@oscarpalmer/timer';
 
-let waited = wait(callback, time);
-let repeated = repeat(callback, time, count);
+const waited = wait(waitedCallback);
+const repeated = repeat(repeatedCallback, 10);
 ```
 
-Or they can be created using class syntax, but without being auto-started:
+Or they can be created using the `new`-keyword, but without being auto-started:
 
 ```typescript
-import {Repeated, Waited} from '@oscarpalmer/timer';
+import {Timer} from '@oscarpalmer/timer';
 
-waited = new Waited(callback, time);
-repeated = new Repeated(callback, time, count);
+const waited = new Timer(waitedCallback);
+const repeated = new Timer(repeatedCallback, 10);
 ```
 
-### CDN & IIFE
-
-If you're using Timer by including the file suffixed with `.iife.js` – or one of the CDN-versions mentioned above – you won't have to import any of the classes or methods.
+## Parameters
 
-Instead, just include a `script`-tag in your HTML linking to Timer and you can access Timer in other scripts, as below:
+When creating a _Timer_, either with the new `new`-keyword or using the functions, you can configure the timer with a few parameters:
 
-```javascript
-// With auto-start
-var waited = Timer.wait(callback, time);
-var repeated = Timer.repeat(callback, time, count);
-
-// With manual start
-waited = new Timer.Waited(callback, time);
-repeated = new Timer.Repeated(callback, time, count);
-```
+|Parameter|Description|
+|--------:|:----------|
+|`callback`|Callback function to be invoked for each run that are __required__ for all timers.<br>For more information on callbacks, please read [the callbacks section](#callbacks).|
+|`count`|How many times the timer should run.<br>If no value is provided, it will default to `1` when using the `new`-keyword and the `wait`-method, but throws an error for the `repeat`-method.|
+|`time`|How many milliseconds between each invokations of the provided callback.<br>Defaults to `0`, which is not really _0_ milliseconds, but close enough :wink:|
+|`after`|A callback to run after the timer finishes, both when cancelled and completed.<br>If _count_ is greater than `1` and _after_ __is not__ `undefined`, a function is expected.|
 
-## Methods
+## Methods and properties
 
-Both the nice helper methods and the class syntax create similar objects – `Waited` and `Repeated` – which share methods:
+An instance of _Timer_ also has a few helpful methods and properties:
 
-|Method|Description|
-|-----:|:----------|
-|`start()`|Starts the timer: necessary when creating a timer using the class syntax _(e.g. `new Waited...`)_, but helpful when the timer needs to be started at other times, as well|
-|`stop()`|Stops the timer|
-|`restart()`|Restarts the timer|
+|Name|Type|Description|
+|---:|----|:----------|
+|`active`|_Property_|A `boolean` value to check if the timer is running|
+|`finished`|_Property_|A `boolean` value to check if the timer was able to finish|
+|`start()`|_Method_|Starts the timer.<br>Necessary when creating a timer using the class syntax _(e.g. `new Waited...`)_, but helpful when the timer needs to be started at other times, as well.|
+|`stop()`|_Method_|Stops the timer|
+|`restart()`|_Method_|Restarts the timer|
 
 ## Callbacks
 
-Callbacks for waited timers do not receive any arguments, but callbacks for repeated ones do:
+Callbacks for both waited and repeated timers receive one parameter:
 
 ```typescript
-repeat(index => {
+function callback(index) {
 	// 'index' is the current step
 	// starts at 0, goes up to a maximum of count - 1
 	// for this example: 0 → 9
-}, 0, 10);
+};
 ```
 
-When you create a repeated timer, you can also provide a fourth parameter to act as a callback to run when the timer stops, as below:
+When you create a repeated timer, you can also provide a callback to run when the timer stops, as below:
 
 ```typescript
 function after(finished: boolean) {
 	// Let's do something fun!
 }
 
-repeat(() => {}, 0, 10, after);
+repeat(() => {}, 10, after);
 ```
 
 The `finished`-parameter for the `after`-function can be used to determine if the timer was stopped manually, or if it was able to finish its work.

package/dist/timer.js

@@ -1,162 +1,292 @@
-/**
- * @callback AfterCallback
- * @param {boolean} finished Did the timer finish?
- * @returns {void}
- */
-/**
- * @callback RepeatedCallback
- * @param {number} index The index of the current iteration
- * @returns {void}
- */
-const callbacks = new WeakMap();
-const configuration = new WeakMap();
-const state = new WeakMap();
-const milliseconds = Math.round(1000 / 60);
-function run(timed) {
-	const timedConfiguration = configuration.get(timed);
-	const timedCallbacks = callbacks.get(timed);
-	const timedState = state.get(timed);
-	timedState.active = true;
-	timedState.finished = false;
-	const isRepeated = timed instanceof Repeated;
-	let index = 0;
-	let start;
-	function step(timestamp) {
-		if (!timedState.active) {
-			return;
-		}
-		start ?? (start = timestamp);
-		const elapsed = timestamp - start;
-		const elapsedMinimum = elapsed - milliseconds;
-		const elapsedMaximum = elapsed + milliseconds;
-		if (
-			elapsedMinimum < timedConfiguration.time &&
-			timedConfiguration.time < elapsedMaximum
-		) {
-			if (timedState.active) {
-				timedCallbacks.default(isRepeated ? index : undefined);
-			}
-			index += 1;
-			if (isRepeated && index < timedConfiguration.count) {
-				start = undefined;
-			} else {
-				timedState.finished = true;
-				timed.stop();
-				return;
-			}
-		}
-		timedState.frame = globalThis.requestAnimationFrame(step);
-	}
-	timedState.frame = globalThis.requestAnimationFrame(step);
-}
-class Timed {
-	get active() {
-		return state.get(this)?.active ?? false;
-	}
-	get finished() {
-		return !this.active && (state.get(this)?.finished ?? false);
-	}
-	/**
-	 * @param {Callback} callback
-	 * @param {number} time
-	 * @param {number} count
-	 * @param {AfterCallback=} afterCallback
-	 */
-	constructor(callback, time, count, afterCallback) {
-		const isRepeated = this instanceof Repeated;
-		const type = isRepeated ? 'repeated' : 'waited';
-		if (typeof callback !== 'function') {
-			throw new TypeError(`A ${type} timer must have a callback function`);
-		}
-		if (typeof time !== 'number' || time < 0) {
-			throw new TypeError(
-				`A ${type} timer must have a non-negative number as its time`,
-			);
-		}
-		if (isRepeated && (typeof count !== 'number' || count < 2)) {
-			throw new TypeError(
-				'A repeated timer must have a number above 1 as its repeat count',
-			);
-		}
-		if (
-			isRepeated &&
-			afterCallback !== undefined &&
-			typeof afterCallback !== 'function'
-		) {
-			throw new TypeError(
-				"A repeated timer's after-callback must be a function",
-			);
-		}
-		callbacks.set(this, {
-			after: afterCallback,
-			default: callback,
-		});
-		configuration.set(this, {count, time});
-		state.set(this, {
-			active: false,
-			finished: false,
-		});
-	}
-	restart() {
-		this.stop();
-		run(this);
-		return this;
-	}
-	start() {
-		if (!this.active) {
-			run(this);
-		}
-		return this;
-	}
-	stop() {
-		const timedCallbacks = callbacks.get(this);
-		const timedState = state.get(this);
-		timedState.active = false;
-		if (timedState.frame === undefined) {
-			return this;
-		}
-		globalThis.cancelAnimationFrame(timedState.frame);
-		timedCallbacks.after?.(this.finished);
-		timedState.frame = undefined;
-		return this;
-	}
-}
-/**
- * A timer that waits and runs repeatedly
- */
-class Repeated extends Timed {}
-/**
- * A timer that waits and runs once
- */
-class Waited extends Timed {
-	/**
-	 * Creates a new waited timer
-	 * @param {() => void} callback
-	 * @param {number} time
-	 */
-	constructor(callback, time) {
-		super(callback, time, 1);
-	}
-}
-/**
- * Creates and starts a new repeated timer
- * @param {RepeatedCallback} callback
- * @param {number} time
- * @param {number} count
- * @param {AfterCallback=} afterCallback
- * @return {Repeated}
- */
-function repeat(callback, time, count, afterCallback) {
-	return new Repeated(callback, time, count, afterCallback).start();
-}
-/**
- * Creates and starts a new waited timer
- * @param {() => void} callback
- * @param {number} time
- * @return {Waited}
- */
-function wait(callback, time) {
-	return new Waited(callback, time).start();
+// node_modules/@oscarpalmer/atoms/dist/js/function.mjs
+function noop() {
 }
 
-export {Repeated, Waited, repeat, wait};
+// src/constants.ts
+var activeTimers = new Set;
+var hiddenTimers = new Set;
+var milliseconds = 1000 / 60;
+
+// src/global.ts
+if (globalThis._oscarpalmer_timers == null) {
+  Object.defineProperty(globalThis, "_oscarpalmer_timers", {
+    get() {
+      return globalThis._oscarpalmer_timer_debug ? [...activeTimers] : [];
+    }
+  });
+}
+
+// src/functions.ts
+function getOptions(options, isRepeated) {
+  return {
+    afterCallback: options.afterCallback,
+    count: getValueOrDefault(options.count, isRepeated ? Number.POSITIVE_INFINITY : 1),
+    errorCallback: options.errorCallback,
+    interval: getValueOrDefault(options.interval, milliseconds, milliseconds),
+    timeout: getValueOrDefault(options.timeout, isRepeated ? Number.POSITIVE_INFINITY : 30000)
+  };
+}
+function getValueOrDefault(value, defaultValue, minimum) {
+  return typeof value === "number" && value > (minimum ?? 0) ? value : defaultValue;
+}
+function work(type, timer, state, options) {
+  if (["continue", "start"].includes(type) && state.active || ["pause", "stop"].includes(type) && !state.active) {
+    return timer;
+  }
+  const { count, interval, timeout } = options;
+  const { isRepeated, minimum } = state;
+  if (["pause", "restart", "stop"].includes(type)) {
+    const isStop = type === "stop";
+    activeTimers.delete(timer);
+    cancelAnimationFrame(state.frame);
+    if (isStop) {
+      options.afterCallback?.(false);
+    }
+    state.active = false;
+    state.frame = undefined;
+    state.paused = !isStop;
+    if (isStop) {
+      state.elapsed = undefined;
+      state.index = undefined;
+    }
+    return type === "restart" ? work("start", timer, state, options) : timer;
+  }
+  state.active = true;
+  state.paused = false;
+  const elapsed = type === "continue" ? +(state.elapsed ?? 0) : 0;
+  let index = type === "continue" ? +(state.index ?? 0) : 0;
+  state.elapsed = elapsed;
+  state.index = index;
+  const total = (count === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : (count - index) * (interval > 0 ? interval : milliseconds)) - elapsed;
+  let current;
+  let start;
+  function finish(finished, error) {
+    activeTimers.delete(timer);
+    state.active = false;
+    state.elapsed = undefined;
+    state.frame = undefined;
+    state.index = undefined;
+    if (error) {
+      options.errorCallback?.();
+    }
+    options.afterCallback?.(finished);
+  }
+  function step(timestamp) {
+    if (!state.active) {
+      return;
+    }
+    current ??= timestamp;
+    start ??= timestamp;
+    const time = timestamp - current;
+    state.elapsed = elapsed + (current - start);
+    const finished = time - elapsed >= total;
+    if (timestamp - start >= timeout - elapsed) {
+      finish(finished, !finished);
+      return;
+    }
+    if (finished || time >= minimum) {
+      if (state.active) {
+        state.callback(isRepeated ? index : undefined);
+      }
+      index += 1;
+      state.index = index;
+      if (!finished && index < count) {
+        current = null;
+      } else {
+        finish(true, false);
+        return;
+      }
+    }
+    state.frame = requestAnimationFrame(step);
+  }
+  activeTimers.add(timer);
+  state.frame = requestAnimationFrame(step);
+  return timer;
+}
+
+// src/timer.ts
+function repeat(callback, options) {
+  return timer("repeat", callback, options ?? {}, true);
+}
+function timer(type, callback, partial, start) {
+  const isRepeated = type === "repeat";
+  const options = getOptions(partial, isRepeated);
+  const instance = new Timer(type, {
+    callback,
+    isRepeated,
+    active: false,
+    minimum: options.interval - options.interval % milliseconds / 2,
+    paused: false,
+    trace: new TimerTrace
+  }, options);
+  if (start) {
+    instance.start();
+  }
+  return instance;
+}
+function wait(callback, options) {
+  return timer("wait", callback, options == null || typeof options === "number" ? {
+    interval: options
+  } : options, true);
+}
+
+class BasicTimer {
+  constructor(type, state) {
+    this.$timer = type;
+    this.state = state;
+  }
+}
+
+class Timer extends BasicTimer {
+  get active() {
+    return this.state.active;
+  }
+  get paused() {
+    return this.state.paused;
+  }
+  get trace() {
+    return globalThis._oscarpalmer_timer_debug ? this.state.trace : undefined;
+  }
+  constructor(type, state, options) {
+    super(type, state);
+    this.options = options;
+  }
+  continue() {
+    return work("continue", this, this.state, this.options);
+  }
+  pause() {
+    return work("pause", this, this.state, this.options);
+  }
+  restart() {
+    return work("restart", this, this.state, this.options);
+  }
+  start() {
+    return work("start", this, this.state, this.options);
+  }
+  stop() {
+    return work("stop", this, this.state, this.options);
+  }
+}
+
+class TimerTrace extends Error {
+  constructor() {
+    super();
+    this.name = "TimerTrace";
+  }
+}
+
+// src/index.ts
+function delay(time, timeout) {
+  return new Promise((resolve, reject) => {
+    wait(resolve ?? noop, {
+      timeout,
+      errorCallback: reject ?? noop,
+      interval: time
+    });
+  });
+}
+
+// src/is.ts
+function is(pattern, value) {
+  return pattern.test(value?.$timer);
+}
+function isRepeated(value) {
+  return is(/^repeat$/, value);
+}
+function isTimer(value) {
+  return is(/^repeat|wait$/, value);
+}
+function isWaited(value) {
+  return is(/^wait$/, value);
+}
+function isWhen(value) {
+  return is(/^when$/, value) && typeof value.then === "function";
+}
+// src/when.ts
+function when(condition, options) {
+  const repeated = timer("repeat", () => {
+    if (condition()) {
+      repeated.stop();
+      state.resolver?.();
+    }
+  }, {
+    afterCallback() {
+      if (!repeated.paused) {
+        if (condition()) {
+          state.resolver?.();
+        } else {
+          state.rejecter?.();
+        }
+      }
+    },
+    errorCallback() {
+      state.rejecter?.();
+    },
+    count: options?.count,
+    interval: options?.interval,
+    timeout: options?.timeout
+  }, false);
+  const state = {};
+  state.promise = new Promise((resolve, reject) => {
+    state.resolver = resolve;
+    state.rejecter = reject;
+  });
+  state.timer = repeated;
+  return new When(state);
+}
+
+class When extends BasicTimer {
+  get active() {
+    return this.state.timer.active;
+  }
+  get paused() {
+    return this.state.timer.paused;
+  }
+  constructor(state) {
+    super("when", state);
+  }
+  continue() {
+    this.state.timer.continue();
+    return this;
+  }
+  pause() {
+    this.state.timer.pause();
+    return this;
+  }
+  stop() {
+    if (this.state.timer.active) {
+      this.state.timer.stop();
+      this.state.rejecter?.();
+    }
+    return this;
+  }
+  then(resolve, reject) {
+    this.state.timer.start();
+    return this.state.promise.then(resolve ?? noop, reject ?? noop);
+  }
+}
+
+// src/index.ts
+document.addEventListener("visibilitychange", () => {
+  if (document.hidden) {
+    for (const timer4 of activeTimers) {
+      hiddenTimers.add(timer4);
+      timer4.pause();
+    }
+  } else {
+    for (const timer4 of hiddenTimers) {
+      timer4.continue();
+    }
+    hiddenTimers.clear();
+  }
+});
+export {
+  when,
+  wait,
+  repeat,
+  isWhen,
+  isWaited,
+  isTimer,
+  isRepeated,
+  delay
+};

package/dist/timer.mjs

@@ -0,0 +1,40 @@
+// src/index.ts
+import {noop} from "@oscarpalmer/atoms/function";
+import {activeTimers, hiddenTimers} from "./constants";
+import"./global";
+import {wait} from "./timer";
+function delay(time, timeout) {
+  return new Promise((resolve, reject) => {
+    wait(resolve ?? noop, {
+      timeout,
+      errorCallback: reject ?? noop,
+      interval: time
+    });
+  });
+}
+import {isRepeated, isTimer, isWaited, isWhen} from "./is";
+import {repeat, wait as wait2} from "./timer";
+import {when} from "./when";
+document.addEventListener("visibilitychange", () => {
+  if (document.hidden) {
+    for (const timer2 of activeTimers) {
+      hiddenTimers.add(timer2);
+      timer2.pause();
+    }
+  } else {
+    for (const timer2 of hiddenTimers) {
+      timer2.continue();
+    }
+    hiddenTimers.clear();
+  }
+});
+export {
+  when,
+  wait2 as wait,
+  repeat,
+  isWhen,
+  isWaited,
+  isTimer,
+  isRepeated,
+  delay
+};

package/package.json

@@ -3,66 +3,48 @@
 		"name": "Oscar Palmér",
 		"url": "https://oscarpalmer.se"
 	},
-	"browser": "dist/timer.iife.js",
+	"dependencies": {
+		"@oscarpalmer/atoms": "0.69.0"
+	},
 	"description": "A better solution for timeout- and interval-based timers.",
 	"devDependencies": {
-		"@happy-dom/global-registrator": "^11.0",
-		"@rollup/plugin-typescript": "^11.1",
-		"bun": "^1.0",
-		"prettier": "^3.0",
-		"rollup": "^3.29",
-		"typescript": "^5.2",
-		"xo": "^0.56"
+		"@biomejs/biome": "^1.8.3",
+		"@happy-dom/global-registrator": "^14.12.3",
+		"@types/bun": "^1.1.6",
+		"bun": "^1.1.21",
+		"dts-bundle-generator": "9.5.1",
+		"typescript": "^5.5.4"
+	},
+	"exports": {
+		".": {
+			"types": "./types/index.d.cts",
+			"bun": "./src/index.ts",
+			"import": "./dist/timer.mjs",
+			"require": "./dist/timer.js"
+		}
 	},
-	"files": [
-		"dist",
-		"src",
-		"types"
-	],
-	"jsdelivr": "dist/timer.iife.js",
-	"keywords": [
-		"timer",
-		"setTimeout",
-		"setInterval",
-		"requestAnimationFrame"
-	],
+	"files": ["dist", "src", "types"],
+	"keywords": ["timer", "setTimeout", "setInterval", "requestAnimationFrame"],
 	"license": "MIT",
-	"main": "dist/timer.iife.js",
-	"module": "dist/timer.js",
+	"main": "dist/timer.js",
+	"module": "dist/timer.mjs",
 	"name": "@oscarpalmer/timer",
-	"prettier": {
-		"arrowParens": "avoid",
-		"bracketSpacing": false,
-		"singleQuote": true,
-		"switchIndent": true,
-		"trailingComma": "all",
-		"useTabs": true
-	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/oscarpalmer/timer.git"
 	},
 	"scripts": {
-		"build": "npm run build:esm && npm run build:iife",
-		"build:esm": "rollup -c",
-		"build:iife": "rollup -c --environment ROLLUP_FORMAT:iife",
-		"test": "bun test --coverage",
-		"types": "tsc ./src/index.ts --outdir ./types --declaration --emitDeclarationOnly",
-		"watch": "rollup -c -w",
-		"xo": "xo ./src/*.ts --env browser"
+		"build": "bun run clean && bun run build:cjs && bun run build:esm && bun run types",
+		"build:cjs": "bun build ./src/index.ts --outfile ./dist/timer.js",
+		"build:esm": "bun build ./src/index.ts --external '*' --outfile ./dist/timer.mjs",
+		"clean": "rm -rf ./dist && rm -rf ./types && rm -f ./tsconfig.tsbuildinfo",
+		"test": "bun test",
+		"types": "bun run types:cjs && bun run types:esm",
+		"types:cjs": "bunx dts-bundle-generator --out-file ./types/index.d.cts --external-inlines '@oscarpalmer/atoms' --no-check --silent ./src/index.ts",
+		"types:esm": "bunx tsc -p ./tsconfig.json",
+		"watch": "bun build ./src/index.ts --outfile ./dist/timer.js --watch"
 	},
 	"type": "module",
-	"types": "src/index.d.ts",
-	"unpkg": "dist/timer.iife.js",
-	"version": "0.19.0",
-	"xo": {
-		"envs": [
-			"browser"
-		],
-		"prettier": true,
-		"rules": {
-			"import/extensions": "off",
-			"import/no-cycle": "off"
-		}
-	}
-}
+	"types": "types/index.d.cts",
+	"version": "0.21.0"
+}