wtf-games-break-timer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WTF Games
+
+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,54 @@
+# wtf-games-break-timer
+
+A small, framework-free JavaScript timer core for browser games, focus sessions, and screen breaks.
+
+It powers the free [Game Break Timer on WTF Games](https://wtfgames.io/game-break-timer/), where you can try the browser version without an account or download.
+
+## Install
+
+```bash
+npm install wtf-games-break-timer
+```
+
+## Usage
+
+```js
+const { GameBreakTimer, formatTime } = require("wtf-games-break-timer");
+
+const timer = new GameBreakTimer({
+  minutes: 20,
+  onTick: (seconds) => {
+    document.querySelector("#countdown").textContent = formatTime(seconds);
+  },
+  onComplete: () => {
+    document.querySelector("#message").textContent = "Time for a break";
+  }
+});
+
+timer.start();
+// timer.pause();
+// timer.reset();
+```
+
+The timer uses a wall-clock deadline, so it stays accurate when a browser throttles an inactive tab. No data is collected or sent by this package.
+
+## API
+
+- `new GameBreakTimer(options)` — create a timer. `minutes` defaults to `20`.
+- `timer.start()` — start or resume the countdown.
+- `timer.pause()` — pause the countdown.
+- `timer.reset()` — return to the initial duration.
+- `timer.setMinutes(minutes)` — change the duration while paused.
+- `timer.remainingSeconds` — current remaining time.
+- `timer.isRunning` — whether the timer is active.
+- `formatTime(seconds)` — format seconds as `mm:ss`.
+
+## Development
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "wtf-games-break-timer",
+  "version": "1.0.0",
+  "description": "A small, framework-free countdown timer core for browser games and focus breaks.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "game",
+    "games",
+    "timer",
+    "break",
+    "browser",
+    "productivity"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Asacura/wtf-games-break-timer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Asacura/wtf-games-break-timer/issues"
+  },
+  "homepage": "https://wtfgames.io/game-break-timer/"
+}

package/src/index.js

@@ -0,0 +1,114 @@
+class GameBreakTimer {
+  constructor({
+    minutes = 20,
+    onTick = () => {},
+    onComplete = () => {},
+    tickIntervalMs = 250,
+    now = () => Date.now(),
+    setIntervalFn = setInterval,
+    clearIntervalFn = clearInterval
+  } = {}) {
+    this.onTick = onTick;
+    this.onComplete = onComplete;
+    this.tickIntervalMs = tickIntervalMs;
+    this._now = now;
+    this._setInterval = setIntervalFn;
+    this._clearInterval = clearIntervalFn;
+    this._intervalId = null;
+    this._endAt = null;
+
+    this.setMinutes(minutes);
+  }
+
+  get isRunning() {
+    return this._intervalId !== null;
+  }
+
+  get remainingSeconds() {
+    return this._remainingSeconds;
+  }
+
+  setMinutes(minutes) {
+    if (this.isRunning) {
+      throw new Error("Pause the timer before changing its duration");
+    }
+
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+      throw new TypeError("minutes must be a positive number");
+    }
+
+    this._initialSeconds = Math.max(1, Math.round(minutes * 60));
+    this._remainingSeconds = this._initialSeconds;
+    this._emitTick();
+    return this;
+  }
+
+  start() {
+    if (this.isRunning) {
+      return this;
+    }
+
+    this._endAt = this._now() + this._remainingSeconds * 1000;
+    this._intervalId = this._setInterval(() => this._sync(), this.tickIntervalMs);
+    this._sync();
+    return this;
+  }
+
+  pause() {
+    if (!this.isRunning) {
+      return this;
+    }
+
+    this._sync();
+    this._stop();
+    return this;
+  }
+
+  reset() {
+    this._stop();
+    this._remainingSeconds = this._initialSeconds;
+    this._emitTick();
+    return this;
+  }
+
+  _sync() {
+    if (!this.isRunning) {
+      return;
+    }
+
+    const nextSeconds = Math.max(0, Math.ceil((this._endAt - this._now()) / 1000));
+    if (nextSeconds !== this._remainingSeconds) {
+      this._remainingSeconds = nextSeconds;
+      this._emitTick();
+    }
+
+    if (nextSeconds === 0) {
+      this._stop();
+      this.onComplete(this);
+    }
+  }
+
+  _stop() {
+    if (this._intervalId !== null) {
+      this._clearInterval(this._intervalId);
+      this._intervalId = null;
+    }
+    this._endAt = null;
+  }
+
+  _emitTick() {
+    this.onTick(this._remainingSeconds, this);
+  }
+}
+
+function formatTime(totalSeconds) {
+  const seconds = Math.max(0, Math.floor(totalSeconds));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${String(minutes).padStart(2, "0")}:${String(remainder).padStart(2, "0")}`;
+}
+
+module.exports = {
+  GameBreakTimer,
+  formatTime
+};