@mainframework/timer 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# @mainframework/timer
+
+Countdown and count-up timers for the browser, backed by a shared Web Worker. Timers tick off the main thread so your UI stays responsive.
+
+## Important: client-side only
+
+This library is a **browser-only, client-side** package. It depends on `window`, `Worker`, and `window.location`.
+
+- **Do not use** in Node.js, Express, or other server-side runtimes.
+- **Not for SSR timer execution.** You may import it in SSR frameworks (e.g. Next.js), but timers only run after client hydration. On the server, `useTimer` returns the initial `durationSeconds` in `"down"` mode and `0` in `"up"` mode; it does not tick.
+- `createWorker()` returns `null` when `window` is undefined, so imports are safe in isomorphic bundles — the timer simply does not run until the browser.
+
+## Requirements
+
+- A modern browser with Web Worker support
+- An ESM-capable bundler that resolves worker URLs via `import.meta.url` (Vite, webpack 5, etc.)
+- React >= 19 (only when using `@mainframework/timer/react`)
+
+This package is **not** a drop-in for plain `<script>` tags without a bundler.
+
+## Installation
+
+```bash
+npm install @mainframework/timer
+```
+
+```bash
+yarn add @mainframework/timer
+```
+
+React is an optional peer dependency. Install React separately if you use the hook entry:
+
+```bash
+npm install react
+```
+
+## React usage
+
+Import `useTimer` from the React entry point. The React entry ships with a `"use client"` directive, so it works in Next.js App Router without an extra directive on your component.
+
+```tsx
+import { useTimer } from "@mainframework/timer/react";
+
+export function Countdown() {
+  const secondsLeft = useTimer(60);
+  return <span>{secondsLeft}s</span>;
+}
+
+export function Stopwatch() {
+  const secondsElapsed = useTimer(0, undefined, "up");
+  return <span>{secondsElapsed}s</span>;
+}
+```
+
+### `useTimer(durationSeconds, routeKey?, mode?)`
+
+| Parameter         | Type             | Description                                                                    |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `durationSeconds` | `number`         | For `"down"`: countdown length. For `"up"`: ignored (pass `0`).                |
+| `routeKey`        | `string?`        | Optional. Defaults to `window.location.pathname`. Scopes the timer to a route. |
+| `mode`            | `"down" \| "up"` | Optional. Default `"down"`.                                                    |
+
+Returns seconds remaining in `"down"` mode, or seconds elapsed in `"up"` mode. Emits ticks every second until the countdown reaches zero (`"down"` only).
+
+## Vanilla JS usage
+
+The main entry exports low-level utilities. You register timers, listen for messages, and unregister yourself.
+
+### Countdown
+
+```js
+import { createWorker, getDefaultRouteKey } from "@mainframework/timer";
+
+const worker = createWorker();
+if (!worker) throw new Error("Timer requires a browser environment");
+
+const timerId = crypto.randomUUID();
+const routeKey = getDefaultRouteKey();
+
+worker.onmessage = (e) => {
+  const msg = e.data;
+  if (msg.id !== timerId) return;
+  if (msg.type === "tick" && msg.mode === "down") console.log(msg.secondsLeft);
+  if (msg.type === "expired") console.log("done");
+};
+
+worker.postMessage({
+  type: "register",
+  routeKey,
+  id: timerId,
+  mode: "down",
+  durationSeconds: 60,
+});
+
+// cleanup when done
+worker.postMessage({ type: "unregister", routeKey, id: timerId });
+```
+
+### Count-up
+
+```js
+worker.onmessage = (e) => {
+  const msg = e.data;
+  if (msg.id !== timerId) return;
+  if (msg.type === "tick" && msg.mode === "up") console.log(msg.secondsElapsed);
+};
+
+worker.postMessage({
+  type: "register",
+  routeKey,
+  id: timerId,
+  mode: "up",
+});
+```
+
+### Route management (SPAs)
+
+When navigating between routes, notify the worker of the active route to purge timers from inactive routes:
+
+```js
+worker.postMessage({ type: "route", activeRoute: "/dashboard" });
+```
+
+The `useTimer` hook does not send route messages today; use this directly when managing timers with `createWorker`.
+
+## API reference
+
+### `@mainframework/timer`
+
+| Export                       | Description                                                              |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `createWorker()`             | Returns the singleton `Worker`, or `null` outside a browser environment. |
+| `getDefaultRouteKey()`       | Returns `window.location.pathname`, or `""` on the server.               |
+| `TimerMode`                  | Type: `"down" \| "up"`.                                                  |
+| `TimerWorkerIncomingMessage` | Type for main thread → worker messages.                                  |
+| `TimerWorkerMessage`         | Type for worker → main thread messages.                                  |
+
+### `@mainframework/timer/react`
+
+| Export                                        | Description                                                            |
+| --------------------------------------------- | ---------------------------------------------------------------------- |
+| `useTimer(durationSeconds, routeKey?, mode?)` | React hook returning seconds remaining (`"down"`) or elapsed (`"up"`). |
+
+### Worker message protocol
+
+**Main thread → worker (`TimerWorkerIncomingMessage`):**
+
+| Type         | Payload                                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `register`   | `{ routeKey, id, mode, durationSeconds? }` — `durationSeconds` required for `"down"`, omitted for `"up"` |
+| `unregister` | `{ routeKey, id }`                                                                                       |
+| `route`      | `{ activeRoute }`                                                                                        |
+
+**Worker → main thread (`TimerWorkerMessage`):**
+
+| Type          | Payload                              |
+| ------------- | ------------------------------------ |
+| `tick` (down) | `{ id, mode: "down", secondsLeft }`  |
+| `tick` (up)   | `{ id, mode: "up", secondsElapsed }` |
+| `expired`     | `{ id }` — countdown only            |
+
+## License
+
+MIT — see [package.json](./package.json).
+
+- Repository: [github.com/TerrySlack/mainframework-timer](https://github.com/TerrySlack/mainframework-timer)
+- Issues: [github.com/TerrySlack/mainframework-timer/issues](https://github.com/TerrySlack/mainframework-timer/issues)

package/dist/react.js

@@ -0,0 +1,2 @@
+"use client";import{useId as e,useRef as t,useState as o,useEffect as n}from"react";import{createWorker as r,getDefaultRouteKey as s}from"./vanilla/index.js";const d=r(),c=new Map;d&&!d.onmessage&&(d.onmessage=e=>{const t=e.data;t?.id&&c.get(t.id)?.(t)});const i=(r,i,u="down")=>{const a=e(),p=t(null),[m,y]=o("down"===u?r:0),g=t(i??s());if(d){c.set(a,e=>{"tick"===e.type&&"down"===e.mode&&y(e.secondsLeft),"tick"===e.type&&"up"===e.mode&&y(e.secondsElapsed),"expired"===e.type&&y(0)});const e=p.current;e&&e.durationSeconds===r&&e.routeKey===g.current&&e.mode===u||(p.current={durationSeconds:r,routeKey:g.current,mode:u},d.postMessage({type:"register",routeKey:g.current,id:a,mode:u,durationSeconds:r}))}return n(()=>()=>{c.delete(a),d?.postMessage({type:"unregister",routeKey:i??s(),id:a})},[a,i]),m};export{i as useTimer};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sources":["../src/hooks/useTimer.ts"],"sourcesContent":["import { useEffect, useId, useRef, useState } from \"react\";\r\n\r\nimport { createWorker } from \"../worker/createWorker\";\r\nimport { getDefaultRouteKey } from \"../utils/routes\";\r\nimport type { TimerMode, TimerWorkerMessage } from \"../types\";\r\n\r\nconst worker = createWorker();\r\n// One shared dispatcher so every hook instance gets its own messages\r\nconst listeners = new Map<string, (msg: TimerWorkerMessage) => void>();\r\n\r\nif (worker && !worker.onmessage) {\r\n  worker.onmessage = (e: MessageEvent<TimerWorkerMessage>): void => {\r\n    const msg = e.data;\r\n    if (!msg?.id) return;\r\n    listeners.get(msg.id)?.(msg);\r\n  };\r\n}\r\n\r\n/**\r\n * Drives a timer via the shared worker.\r\n * mode \"down\": durationSeconds counts down to 0. Returns seconds remaining.\r\n * mode \"up\": durationSeconds is ignored. Returns seconds elapsed since mount/registration.\r\n */\r\nexport const useTimer = (durationSeconds: number, routeKey?: string, mode: TimerMode = \"down\"): number => {\r\n  const id = useId();\r\n  const lastRegister = useRef<{ durationSeconds: number; routeKey: string; mode: TimerMode } | null>(null);\r\n  const [value, setValue] = useState(mode === \"down\" ? durationSeconds : 0);\r\n  const keyRef = useRef<string>(routeKey ?? getDefaultRouteKey());\r\n\r\n  if (worker) {\r\n    listeners.set(id, (msg: TimerWorkerMessage): void => {\r\n      if (msg.type === \"tick\" && msg.mode === \"down\") setValue(msg.secondsLeft);\r\n      if (msg.type === \"tick\" && msg.mode === \"up\") setValue(msg.secondsElapsed);\r\n      if (msg.type === \"expired\") setValue(0);\r\n    });\r\n\r\n    const prev = lastRegister.current;\r\n    if (!prev || prev.durationSeconds !== durationSeconds || prev.routeKey !== keyRef.current || prev.mode !== mode) {\r\n      lastRegister.current = { durationSeconds, routeKey: keyRef.current, mode };\r\n      worker.postMessage({\r\n        type: \"register\",\r\n        routeKey: keyRef.current,\r\n        id,\r\n        mode,\r\n        durationSeconds,\r\n      });\r\n    }\r\n  }\r\n\r\n  useEffect(() => {\r\n    return () => {\r\n      listeners.delete(id);\r\n      worker?.postMessage({\r\n        type: \"unregister\",\r\n        routeKey: routeKey ?? getDefaultRouteKey(),\r\n        id,\r\n      });\r\n    };\r\n  }, [id, routeKey]);\r\n\r\n  return value;\r\n};\r\n"],"names":["worker","createWorker","listeners","Map","onmessage","e","msg","data","id","get","useTimer","durationSeconds","routeKey","mode","useId","lastRegister","useRef","value","setValue","useState","keyRef","getDefaultRouteKey","set","type","secondsLeft","secondsElapsed","prev","current","postMessage","useEffect","delete"],"mappings":"8JAMA,MAAMA,EAASC,IAETC,EAAY,IAAIC,IAElBH,IAAWA,EAAOI,YACpBJ,EAAOI,UAAaC,IAClB,MAAMC,EAAMD,EAAEE,KACTD,GAAKE,IACVN,EAAUO,IAAIH,EAAIE,GAAlBN,GAAwBI,KASrB,MAAMI,EAAW,CAACC,EAAyBC,EAAmBC,EAAkB,UACrF,MAAML,EAAKM,IACLC,EAAeC,EAA8E,OAC5FC,EAAOC,GAAYC,EAAkB,SAATN,EAAkBF,EAAkB,GACjES,EAASJ,EAAeJ,GAAYS,KAE1C,GAAIrB,EAAQ,CACVE,EAAUoB,IAAId,EAAKF,IACA,SAAbA,EAAIiB,MAAgC,SAAbjB,EAAIO,MAAiBK,EAASZ,EAAIkB,aAC5C,SAAblB,EAAIiB,MAAgC,OAAbjB,EAAIO,MAAeK,EAASZ,EAAImB,gBAC1C,YAAbnB,EAAIiB,MAAoBL,EAAS,KAGvC,MAAMQ,EAAOX,EAAaY,QACrBD,GAAQA,EAAKf,kBAAoBA,GAAmBe,EAAKd,WAAaQ,EAAOO,SAAWD,EAAKb,OAASA,IACzGE,EAAaY,QAAU,CAAEhB,kBAAiBC,SAAUQ,EAAOO,QAASd,QACpEb,EAAO4B,YAAY,CACjBL,KAAM,WACNX,SAAUQ,EAAOO,QACjBnB,KACAK,OACAF,oBAGN,CAaA,OAXAkB,EAAU,IACD,KACL3B,EAAU4B,OAAOtB,GACjBR,GAAQ4B,YAAY,CAClBL,KAAM,aACNX,SAAUA,GAAYS,IACtBb,QAGH,CAACA,EAAII,IAEDK"}

package/dist/types/hooks/useTimer.d.ts

@@ -0,0 +1,8 @@
+import type { TimerMode } from "../types";
+/**
+ * Drives a timer via the shared worker.
+ * mode "down": durationSeconds counts down to 0. Returns seconds remaining.
+ * mode "up": durationSeconds is ignored. Returns seconds elapsed since mount/registration.
+ */
+export declare const useTimer: (durationSeconds: number, routeKey?: string, mode?: TimerMode) => number;
+//# sourceMappingURL=useTimer.d.ts.map

package/dist/types/hooks/useTimer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTimer.d.ts","sourceRoot":"","sources":["../../../src/hooks/useTimer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAsB,MAAM,UAAU,CAAC;AAc9D;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,iBAAiB,MAAM,EAAE,WAAW,MAAM,EAAE,OAAM,SAAkB,KAAG,MAsC/F,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { createWorker } from "./worker/createWorker";
+export { getDefaultRouteKey } from "./utils/routes";
+export type { TimerMode, TimerWorkerMessage, TimerWorkerIncomingMessage } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/react.d.ts

@@ -0,0 +1,2 @@
+export { useTimer } from "./hooks/useTimer";
+//# sourceMappingURL=react.d.ts.map

package/dist/types/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

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

@@ -0,0 +1,50 @@
+/** Direction a timer counts */
+export type TimerMode = "down" | "up";
+/** Internal worker row state */
+export interface TimerRow {
+    mode: TimerMode;
+    /** countdown: the epoch ms it ends at. count-up: the epoch ms it started at. */
+    anchorEpochMs: number;
+    lastEmittedSecond: number;
+}
+/** Per-route bucket: timer id → row */
+export interface RouteTimerState {
+    timerCount: number;
+    timers: Map<string, TimerRow>;
+}
+/** Full worker store: routeKey → route bucket */
+export interface TimerStore {
+    timerCount: number;
+    timers: Map<string, RouteTimerState>;
+}
+/** Worker → main thread */
+export type TimerWorkerMessage = {
+    type: "tick";
+    id: string;
+    mode: "down";
+    secondsLeft: number;
+} | {
+    type: "tick";
+    id: string;
+    mode: "up";
+    secondsElapsed: number;
+} | {
+    type: "expired";
+    id: string;
+};
+/** Main thread → worker */
+export type TimerWorkerIncomingMessage = {
+    type: "route";
+    activeRoute: string;
+} | {
+    type: "register";
+    routeKey: string;
+    id: string;
+    mode: TimerMode;
+    durationSeconds?: number;
+} | {
+    type: "unregister";
+    routeKey: string;
+    id: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAEtC,gCAAgC;AAChC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACtC;AAED,2BAA2B;AAC3B,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC,2BAA2B;AAC3B,MAAM,MAAM,0BAA0B,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/types/utils/routes.d.ts

@@ -0,0 +1,3 @@
+/** Convenience default — current pathname. Callers can supply their own routeKey instead. */
+export declare const getDefaultRouteKey: () => string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/types/utils/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/utils/routes.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,QAAO,MACyB,CAAC"}

package/dist/types/worker/createWorker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lazily creates and returns the singleton timer worker. Safe to call in
+ * SSR contexts — returns null until called in a browser environment.
+ *
+ * This is the only piece of shared plumbing: creating the worker instance.
+ * Registering timers, listening for ticks, and filtering messages by id
+ * is left to the caller — the hook does its own, a vanilla JS consumer
+ * does its own, directly against the returned Worker.
+ *
+ * NOTE (bundler dependency): `new URL("../worker/timer.worker.js", import.meta.url)`
+ * requires the consuming app's bundler to resolve worker files this way
+ * (webpack 5, Vite, Next all do). If you need this package to work in
+ * bundler-agnostic environments, swap this for a Blob-constructed worker
+ * built from the worker source as a string instead.
+ */
+export declare const createWorker: () => Worker | null;
+//# sourceMappingURL=createWorker.d.ts.map

package/dist/types/worker/createWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWorker.d.ts","sourceRoot":"","sources":["../../../src/worker/createWorker.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAQxC,CAAC"}

package/dist/types/worker/timer.worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timer.worker.d.ts.map

package/dist/types/worker/timer.worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.worker.d.ts","sourceRoot":"","sources":["../../../src/worker/timer.worker.ts"],"names":[],"mappings":""}

package/dist/vanilla/index.js

@@ -0,0 +1,2 @@
+let e=null;const n=()=>"undefined"==typeof window?null:(e||(e=new Worker(new URL("../worker/timer.worker.js",import.meta.url),{type:"module"})),e),o=()=>"undefined"==typeof window?"":window.location.pathname;export{n as createWorker,o as getDefaultRouteKey};
+//# sourceMappingURL=index.js.map

package/dist/vanilla/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/worker/createWorker.ts","../../src/utils/routes.ts"],"sourcesContent":["let worker: Worker | null = null;\r\n\r\n/**\r\n * Lazily creates and returns the singleton timer worker. Safe to call in\r\n * SSR contexts — returns null until called in a browser environment.\r\n *\r\n * This is the only piece of shared plumbing: creating the worker instance.\r\n * Registering timers, listening for ticks, and filtering messages by id\r\n * is left to the caller — the hook does its own, a vanilla JS consumer\r\n * does its own, directly against the returned Worker.\r\n *\r\n * NOTE (bundler dependency): `new URL(\"../worker/timer.worker.js\", import.meta.url)`\r\n * requires the consuming app's bundler to resolve worker files this way\r\n * (webpack 5, Vite, Next all do). If you need this package to work in\r\n * bundler-agnostic environments, swap this for a Blob-constructed worker\r\n * built from the worker source as a string instead.\r\n */\r\nexport const createWorker = (): Worker | null => {\r\n  if (typeof window === \"undefined\") return null;\r\n  if (!worker) {\r\n    worker = new Worker(new URL(\"../worker/timer.worker.js\", import.meta.url), {\r\n      type: \"module\",\r\n    });\r\n  }\r\n  return worker;\r\n};\r\n","/** Convenience default — current pathname. Callers can supply their own routeKey instead. */\r\nexport const getDefaultRouteKey = (): string =>\r\n  typeof window === \"undefined\" ? \"\" : window.location.pathname;\r\n"],"names":["worker","createWorker","window","Worker","URL","url","type","getDefaultRouteKey","location","pathname"],"mappings":"AAAA,IAAIA,EAAwB,KAiBrB,MAAMC,EAAe,IACJ,oBAAXC,OAA+B,MACrCF,IACHA,EAAS,IAAIG,OAAO,IAAIC,IAAI,wCAAyCC,KAAM,CACzEC,KAAM,YAGHN,GCvBIO,EAAqB,IACd,oBAAXL,OAAyB,GAAKA,OAAOM,SAASC"}

package/dist/worker/timer.worker.js

@@ -0,0 +1,2 @@
+const e={store:{timerCount:0,timers:new Map}};let t=null,o=null;const s=(t,o)=>{const s=e.store.timers.get(t);s&&s.timers.has(o)&&(s.timers.delete(o),s.timerCount--,e.store.timerCount--,0===s.timerCount&&e.store.timers.delete(t))},r=()=>{0===e.store.timerCount&&null!==t&&(clearInterval(t),t=null)},n=()=>{const t=Date.now();for(const[o,r]of e.store.timers)for(const[e,n]of r.timers)if("down"===n.mode){const r=Math.max(0,Math.ceil((n.anchorEpochMs-t)/1e3));if(0===r){0!==n.lastEmittedSecond&&(n.lastEmittedSecond=0,self.postMessage({type:"expired",id:e}),s(o,e));continue}r!==n.lastEmittedSecond&&(n.lastEmittedSecond=r,self.postMessage({type:"tick",id:e,mode:"down",secondsLeft:r}))}else{const o=Math.max(0,Math.floor((t-n.anchorEpochMs)/1e3));o!==n.lastEmittedSecond&&(n.lastEmittedSecond=o,self.postMessage({type:"tick",id:e,mode:"up",secondsElapsed:o}))}r()};self.onmessage=i=>{const{data:d}=i;if("route"===d.type)return o=d.activeRoute,(()=>{if(o)for(const[t,s]of e.store.timers)t!==o&&(e.store.timerCount-=s.timerCount,e.store.timers.delete(t))})(),void r();if("register"===d.type){const o="down"===d.mode?Date.now()+1e3*(d.durationSeconds??0):Date.now();return((t,o,s,r)=>{let n=e.store.timers.get(t);n||(n={timerCount:0,timers:new Map},e.store.timers.set(t,n));const i=n.timers.get(o);i?i.anchorEpochMs===r&&i.mode===s||(i.mode=s,i.anchorEpochMs=r,i.lastEmittedSecond=-1):(n.timers.set(o,{mode:s,anchorEpochMs:r,lastEmittedSecond:-1}),n.timerCount++,e.store.timerCount++)})(d.routeKey,d.id,d.mode,o),null===t&&(t=setInterval(n,1e3)),void n()}"unregister"===d.type&&(s(d.routeKey,d.id),r())};
+//# sourceMappingURL=timer.worker.js.map

package/dist/worker/timer.worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.worker.js","sources":["../../src/worker/timer.worker.ts"],"sourcesContent":["/// <reference lib=\"webworker\" />\r\n\r\nimport type { TimerMode, TimerRow, TimerStore, TimerWorkerIncomingMessage } from \"../types\";\r\n\r\nconst state: { store: TimerStore } = {\r\n  store: {\r\n    timerCount: 0,\r\n    timers: new Map(),\r\n  },\r\n};\r\n\r\nlet intervalId: ReturnType<typeof setInterval> | null = null;\r\nlet activeRoute: string | null = null;\r\n\r\nconst getCount = (): number => state.store.timerCount;\r\n\r\nconst addTimer = (routeKey: string, id: string, mode: TimerMode, anchorEpochMs: number): void => {\r\n  let route = state.store.timers.get(routeKey);\r\n  if (!route) {\r\n    route = { timerCount: 0, timers: new Map<string, TimerRow>() };\r\n    state.store.timers.set(routeKey, route);\r\n  }\r\n\r\n  const existing = route.timers.get(id);\r\n  if (existing) {\r\n    if (existing.anchorEpochMs !== anchorEpochMs || existing.mode !== mode) {\r\n      existing.mode = mode;\r\n      existing.anchorEpochMs = anchorEpochMs;\r\n      existing.lastEmittedSecond = -1;\r\n    }\r\n    return;\r\n  }\r\n\r\n  route.timers.set(id, { mode, anchorEpochMs, lastEmittedSecond: -1 });\r\n  route.timerCount++;\r\n  state.store.timerCount++;\r\n};\r\n\r\nconst deleteTimer = (routeKey: string, id: string): void => {\r\n  const route = state.store.timers.get(routeKey);\r\n  if (!route || !route.timers.has(id)) return;\r\n\r\n  route.timers.delete(id);\r\n  route.timerCount--;\r\n  state.store.timerCount--;\r\n\r\n  if (route.timerCount === 0) state.store.timers.delete(routeKey);\r\n};\r\n\r\nconst stopLoopIfIdle = (): void => {\r\n  if (getCount() === 0 && intervalId !== null) {\r\n    clearInterval(intervalId);\r\n    intervalId = null;\r\n  }\r\n};\r\n\r\nconst cleanupNonActiveRoutes = (): void => {\r\n  if (!activeRoute) return;\r\n  for (const [routeKey, route] of state.store.timers) {\r\n    if (routeKey === activeRoute) continue;\r\n    state.store.timerCount -= route.timerCount;\r\n    state.store.timers.delete(routeKey);\r\n  }\r\n};\r\n\r\nconst tickOnce = (): void => {\r\n  const now = Date.now();\r\n  for (const [routeKey, route] of state.store.timers) {\r\n    for (const [id, row] of route.timers) {\r\n      if (row.mode === \"down\") {\r\n        const secondsLeft = Math.max(0, Math.ceil((row.anchorEpochMs - now) / 1000));\r\n        if (secondsLeft === 0) {\r\n          if (row.lastEmittedSecond !== 0) {\r\n            row.lastEmittedSecond = 0;\r\n            self.postMessage({ type: \"expired\", id });\r\n            deleteTimer(routeKey, id);\r\n          }\r\n          continue;\r\n        }\r\n        if (secondsLeft !== row.lastEmittedSecond) {\r\n          row.lastEmittedSecond = secondsLeft;\r\n          self.postMessage({ type: \"tick\", id, mode: \"down\", secondsLeft });\r\n        }\r\n      } else {\r\n        const secondsElapsed = Math.max(0, Math.floor((now - row.anchorEpochMs) / 1000));\r\n        if (secondsElapsed !== row.lastEmittedSecond) {\r\n          row.lastEmittedSecond = secondsElapsed;\r\n          self.postMessage({ type: \"tick\", id, mode: \"up\", secondsElapsed });\r\n        }\r\n      }\r\n    }\r\n  }\r\n  stopLoopIfIdle();\r\n};\r\n\r\nconst startLoop = (): void => {\r\n  if (intervalId !== null) return;\r\n  intervalId = setInterval(tickOnce, 1000);\r\n};\r\n\r\nself.onmessage = (e: MessageEvent<TimerWorkerIncomingMessage>): void => {\r\n  const { data } = e;\r\n  if (data.type === \"route\") {\r\n    activeRoute = data.activeRoute;\r\n    cleanupNonActiveRoutes();\r\n    stopLoopIfIdle();\r\n    return;\r\n  }\r\n  if (data.type === \"register\") {\r\n    const anchorEpochMs = data.mode === \"down\" ? Date.now() + (data.durationSeconds ?? 0) * 1000 : Date.now();\r\n    addTimer(data.routeKey, data.id, data.mode, anchorEpochMs);\r\n    startLoop();\r\n    tickOnce();\r\n    return;\r\n  }\r\n  if (data.type === \"unregister\") {\r\n    deleteTimer(data.routeKey, data.id);\r\n    stopLoopIfIdle();\r\n  }\r\n};\r\n"],"names":["state","store","timerCount","timers","Map","intervalId","activeRoute","deleteTimer","routeKey","id","route","get","has","delete","stopLoopIfIdle","clearInterval","tickOnce","now","Date","row","mode","secondsLeft","Math","max","ceil","anchorEpochMs","lastEmittedSecond","self","postMessage","type","secondsElapsed","floor","onmessage","e","data","cleanupNonActiveRoutes","durationSeconds","set","existing","addTimer","setInterval"],"mappings":"AAIA,MAAMA,EAA+B,CACnCC,MAAO,CACLC,WAAY,EACZC,OAAQ,IAAIC,MAIhB,IAAIC,EAAoD,KACpDC,EAA6B,KAEjC,MAwBMC,EAAc,CAACC,EAAkBC,KACrC,MAAMC,EAAQV,EAAMC,MAAME,OAAOQ,IAAIH,GAChCE,GAAUA,EAAMP,OAAOS,IAAIH,KAEhCC,EAAMP,OAAOU,OAAOJ,GACpBC,EAAMR,aACNF,EAAMC,MAAMC,aAEa,IAArBQ,EAAMR,YAAkBF,EAAMC,MAAME,OAAOU,OAAOL,KAGlDM,EAAiB,KACF,IApCUd,EAAMC,MAAMC,YAoCF,OAAfG,IACtBU,cAAcV,GACdA,EAAa,OAaXW,EAAW,KACf,MAAMC,EAAMC,KAAKD,MACjB,IAAK,MAAOT,EAAUE,KAAUV,EAAMC,MAAME,OAC1C,IAAK,MAAOM,EAAIU,KAAQT,EAAMP,OAC5B,GAAiB,SAAbgB,EAAIC,KAAiB,CACvB,MAAMC,EAAcC,KAAKC,IAAI,EAAGD,KAAKE,MAAML,EAAIM,cAAgBR,GAAO,MACtE,GAAoB,IAAhBI,EAAmB,CACS,IAA1BF,EAAIO,oBACNP,EAAIO,kBAAoB,EACxBC,KAAKC,YAAY,CAAEC,KAAM,UAAWpB,OACpCF,EAAYC,EAAUC,IAExB,QACF,CACIY,IAAgBF,EAAIO,oBACtBP,EAAIO,kBAAoBL,EACxBM,KAAKC,YAAY,CAAEC,KAAM,OAAQpB,KAAIW,KAAM,OAAQC,gBAEvD,KAAO,CACL,MAAMS,EAAiBR,KAAKC,IAAI,EAAGD,KAAKS,OAAOd,EAAME,EAAIM,eAAiB,MACtEK,IAAmBX,EAAIO,oBACzBP,EAAIO,kBAAoBI,EACxBH,KAAKC,YAAY,CAAEC,KAAM,OAAQpB,KAAIW,KAAM,KAAMU,mBAErD,CAGJhB,KAQFa,KAAKK,UAAaC,IAChB,MAAMC,KAAEA,GAASD,EACjB,GAAkB,UAAdC,EAAKL,KAIP,OAHAvB,EAAc4B,EAAK5B,YA/CQ,MAC7B,GAAKA,EACL,IAAK,MAAOE,EAAUE,KAAUV,EAAMC,MAAME,OACtCK,IAAaF,IACjBN,EAAMC,MAAMC,YAAcQ,EAAMR,WAChCF,EAAMC,MAAME,OAAOU,OAAOL,KA2C1B2B,QACArB,IAGF,GAAkB,aAAdoB,EAAKL,KAAqB,CAC5B,MAAMJ,EAA8B,SAAdS,EAAKd,KAAkBF,KAAKD,MAAsC,KAA7BiB,EAAKE,iBAAmB,GAAYlB,KAAKD,MAIpG,MAjGa,EAACT,EAAkBC,EAAYW,EAAiBK,KAC/D,IAAIf,EAAQV,EAAMC,MAAME,OAAOQ,IAAIH,GAC9BE,IACHA,EAAQ,CAAER,WAAY,EAAGC,OAAQ,IAAIC,KACrCJ,EAAMC,MAAME,OAAOkC,IAAI7B,EAAUE,IAGnC,MAAM4B,EAAW5B,EAAMP,OAAOQ,IAAIF,GAC9B6B,EACEA,EAASb,gBAAkBA,GAAiBa,EAASlB,OAASA,IAChEkB,EAASlB,KAAOA,EAChBkB,EAASb,cAAgBA,EACzBa,EAASZ,mBAAoB,IAKjChB,EAAMP,OAAOkC,IAAI5B,EAAI,CAAEW,OAAMK,gBAAeC,mBAAmB,IAC/DhB,EAAMR,aACNF,EAAMC,MAAMC,eA2EVqC,CAASL,EAAK1B,SAAU0B,EAAKzB,GAAIyB,EAAKd,KAAMK,GAd3B,OAAfpB,IACJA,EAAamC,YAAYxB,EAAU,WAejCA,GAEF,CACkB,eAAdkB,EAAKL,OACPtB,EAAY2B,EAAK1B,SAAU0B,EAAKzB,IAChCK"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@mainframework/timer",
+  "version": "1.0.0",
+  "description": "a timer wrapper for setInterval",
+  "author": "Terry Slack <tslack@mainframework.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/vanilla/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/vanilla/index.js"
+    },
+    "./react": {
+      "types": "./dist/types/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TerrySlack/mainframework-timer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TerrySlack/mainframework-timer/issues"
+  },
+  "homepage": "https://github.com/TerrySlack/mainframework-timer",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --max-warnings=0 --no-warn-ignored"
+    ],
+    "*.{js,jsx,ts,tsx,json,css,md}": [
+      "prettier --write"
+    ]
+  },
+  "scripts": {
+    "prepare": "husky",
+    "clean": "rimraf dist tsconfig.tsbuildinfo -g src/**/*.js -g src/**/*.js.map",
+    "lint-staged": "lint-staged",
+    "lint": "eslint . --max-warnings=0 --no-warn-ignored",
+    "prebuild": "yarn clean",
+    "build": "rollup -c && tsc --emitDeclarationOnly --declarationDir dist/types",
+    "tscheck": "tsc"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.1",
+    "@babel/preset-typescript": "^8.0.1",
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-babel": "^7.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/react": "^19.2.17",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^10.7.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.8",
+    "prettier": "^3.9.5",
+    "react": "^19.2.7",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0"
+  }
+}