@hyperfrontend/time-utils 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.1](https://github.com/AndrewRedican/hyperfrontend/compare/106ce4517092cdfa9f222b73d938d272c333d69b...adf0a4f77dece2be855e7ab88185a4fe84e7b16b) - 2026-09-14
+
+### Bug Fixes
+
+- reject a non-finite base time window instead of returning an invalid date
+
 ## [1.0.0](https://github.com/AndrewRedican/hyperfrontend/compare/5f116abb8ba6355dfb283fa03b7481e5eb029480...4b34883aead4c721f021465b19fa5bdd49514d37) - 2026-08-31
 
 ### Features

package/README.md

@@ -1,4 +1,8 @@
-# @hyperfrontend/time-utils
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/utils/time/">
+    <img width="640" height="180" src="https://www.hyperfrontend.dev/media/banner-time-utils/banner.gif" alt="@hyperfrontend/time-utils">
+  </a>
+</p>
 
 <p align="center">
   <a href="https://github.com/AndrewRedican/hyperfrontend/actions/workflows/ci-lib-time-utils.yml">
@@ -33,6 +37,12 @@
   <img src="https://img.shields.io/badge/tree%20shakeable-%E2%9C%93-success?style=flat-square" alt="Tree Shakeable">
 </p>
 
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/utils/time/">
+    <img width="640" height="360" src="https://www.hyperfrontend.dev/media/time-utils-countdown/hero.gif" alt="Two stacked 30-second countdown bars draining in parallel: the setTimeout bar runs red straight to zero, while the createTimer bar holds green at 21.0s through a pause and then continues down from there">
+  </a>
+</p>
+
 Functional time utilities for async operations, intervals, and time normalization.
 
 • 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/utils/time/)
@@ -40,32 +50,28 @@ Functional time utilities for async operations, intervals, and time normalizatio
 
 ## What is @hyperfrontend/time-utils?
 
-`@hyperfrontend/time-utils` provides composable, testable utilities for working with time-based operations in JavaScript. The library focuses on enhancing the control and flexibility of standard timing APIs (`setTimeout`, `setInterval`) while adding specialized utilities for async workflows and time window calculations.
+[`@hyperfrontend/time-utils`](https://www.hyperfrontend.dev/docs/libraries/utils/time/) provides composable, testable utilities for working with time-based operations in JavaScript. The library focuses on enhancing the control and flexibility of standard timing APIs (`setTimeout`, `setInterval`) while adding specialized utilities for async workflows and time window calculations.
 
 Unlike the native timing APIs which offer limited lifecycle control, this library wraps them in functional interfaces that support pausing, resuming, resetting, and subscription management. All utilities return immutable objects with frozen APIs, preventing accidental mutation while maintaining predictable behavior.
 
 ### Key Features
 
-- **Controllable timers** - Pause, resume, and reset `setTimeout` operations with tracked remaining time
-- **Multi-subscriber clocks** - Observable interval loops supporting multiple callbacks with unified start/stop control
-- **Promise-based delays** - Async/await compatible `sleep()` utility for sequential code flows
-- **Time window normalization** - Bucket timestamps into fixed intervals (e.g., 5-minute windows for aggregation)
+- **[Controllable timers](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-createTimer)** - Pause, resume, and reset `setTimeout` operations with tracked remaining time
+- **[Multi-subscriber clocks](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-createClock)** - Observable interval loops supporting multiple callbacks with unified start/stop control
+- **[Promise-based delays](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-sleep)** - Async/await compatible `sleep()` utility for sequential code flows
+- **[Time window normalization](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-normalizeToBaseTimeWindow)** - Bucket timestamps into fixed intervals (e.g., 5-minute windows for aggregation)
 - **Functional cleanup** - All repeating operations return cleanup functions for straightforward teardown
 - **Immutable APIs** - All returned objects are frozen, preventing accidental state modifications
 - **Zero dependencies** - Self-contained timing utilities with no external dependencies
 - **TypeScript native** - Full type definitions with comprehensive JSDoc documentation
 
-### Architecture Highlights
-
-All timing abstractions maintain internal state privately while exposing frozen API objects, following the revealing module pattern. Timer implementations track elapsed time explicitly to enable pause/resume functionality, while clock implementations manage subscriber arrays with simple filter-based unsubscription. The library avoids classes and prototypes in favor of factory functions that return object literals.
-
 ## Why Use @hyperfrontend/time-utils?
 
 ### 1. Pause/Resume Capabilities Native APIs Lack
 
 JavaScript's `setTimeout` and `setInterval` cannot be paused: once started, they either complete or get cancelled. This creates problems for features like user-initiated pauses in games, animations during background tabs, or request throttling. `createTimer()` tracks elapsed time internally, enabling pause/resume without restarting from the beginning or losing progress.
 
-**Example:** A countdown timer in a game needs to pause when the user switches tabs. With `setTimeout`, you'd need to calculate remaining time manually and create a new timeout. With `createTimer`, just call `timer.pause()`.
+**Example:** A countdown timer in a game needs to pause when the user switches tabs. With `setTimeout`, you'd need to calculate remaining time manually and create a new timeout. With [`createTimer`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-createTimer), just call `timer.pause()`.
 
 ### 2. Multi-Subscriber Interval Management
 
@@ -162,7 +168,8 @@ async function retryWithDelay(fn, attempts = 3) {
 import { normalizeToBaseTimeWindow } from '@hyperfrontend/time-utils'
 
 // Group metrics into 5-minute windows
-const events = [new Date('2024-01-17T10:03:45Z'), new Date('2024-01-17T10:07:22Z'), new Date('2024-01-17T10:12:03Z')]
+const times = ['10:03:45', '10:07:22', '10:12:03']
+const events = times.map((time) => new Date(`2024-01-17T${time}Z`))
 
 const buckets = new Map()
 events.forEach((timestamp) => {
@@ -171,8 +178,9 @@ events.forEach((timestamp) => {
   buckets.set(key, (buckets.get(key) || 0) + 1)
 })
 
-// Results:
-// "2024-01-17T10:00:00Z" → 2 events
+// Results: 10:07:22 floors to 10:05, not to 10:00, so the three events land in three separate buckets
+// "2024-01-17T10:00:00Z" → 1 event
+// "2024-01-17T10:05:00Z" → 1 event
 // "2024-01-17T10:10:00Z" → 1 event
 ```
 
@@ -192,34 +200,32 @@ cleanup()
 
 ## API Overview
 
-**Timing Abstractions:**
-
-- **`createTimer(callback, delay)`** - Creates a pauseable, resumable timer (enhanced setTimeout)
-  - `timer.pause()` - Pauses timer, preserving remaining time
-  - `timer.resume()` - Resumes timer from remaining time
-  - `timer.reset(newDelay?)` - Restarts timer with optional new duration
+Five functions, one gap they all fill: `setTimeout` and `setInterval` schedule work but give you nothing to steer it with afterwards. Two of the five are where you
+start. [`createTimer`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-createTimer) is a timeout you can interrupt: pausing banks whatever was
+left of the delay instead of discarding it, so resuming runs out that remainder rather than serving the full delay again, and `reset(newDelay?)` is the one call
+that does start over. [`createClock`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-createClock) solves the opposite problem, fanning a single
+interval out to any number of subscribers, so ten widgets on a one-second cadence share one tick and one `Date` rather than drifting apart on ten intervals of
+their own.
 
-- **`createClock(interval?)`** - Creates a multi-subscriber interval loop (default: 1000ms)
-  - `clock.start()` - Begins interval loop
-  - `clock.stop()` - Stops interval loop
-  - `clock.subscribe(callback)` - Adds callback to subscriber list
-  - `clock.unsubscribe(callback)` - Removes callback from subscribers
-  - `clock.interval` - Read-only interval duration
+Both hand back a frozen object rather than a numeric handle you are expected to hold onto and clear. A [`Timer`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Timer)
+is [`pause`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Timer-prop-pause), [`resume`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Timer-prop-resume) and [`reset`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Timer-prop-reset); a [`Clock`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock) is [`start`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock-prop-start), [`stop`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock-prop-stop), [`subscribe`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock-prop-subscribe), [`unsubscribe`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock-prop-unsubscribe)
+and a read-only [`interval`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-Clock-prop-interval). One detail worth knowing before your first call: a timer is created idle, so nothing is scheduled until you `resume()` it once.
 
-**Utility Functions:**
+The remaining three are single-purpose and take no object at all. [`sleep`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-sleep) is a delay you can
+`await` in sequence. [`setIntervalCallback`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-setIntervalCallback) is a repeating interval for the case
+where teardown is all you want back, returning the cleanup function directly. And
+[`normalizeToBaseTimeWindow`](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-normalizeToBaseTimeWindow) floors a `Date` to a window boundary and
+returns a new `Date`, which is how independent callers derive the same bucket key from clocks that never agreed to the millisecond.
 
-- **`sleep(milliseconds)`** - Returns promise that resolves after delay (async/await compatible)
-- **`setIntervalCallback(callback, interval)`** - Simple setInterval wrapper returning cleanup function
-- **`normalizeToBaseTimeWindow(time, baseTimeWindow)`** - Rounds timestamp down to nearest time window boundary (window in minutes)
+Every signature, option and return type is in the [API reference](https://www.hyperfrontend.dev/docs/libraries/utils/time/#api-reference).
 
 ## Compatibility
 
-| Platform                      | Support |
-| ----------------------------- | :-----: |
-| Browser                       |   ✅    |
-| Node.js                       |   ✅    |
-| Web Workers                   |   ✅    |
-| Deno, Bun, Cloudflare Workers |   ✅    |
+<p align="center">
+  <a href="https://www.hyperfrontend.dev/docs/libraries/utils/time/#compatibility">
+    <img width="640" height="150" src="https://www.hyperfrontend.dev/media/runtimes-time-utils/runtimes.png" alt="Runs in Node.js 18 or later, evergreen browsers and web workers">
+  </a>
+</p>
 
 ### Output Formats
 
@@ -244,7 +250,7 @@ cleanup()
 </script>
 ```
 
-**Global variable:** `HyperfrontendTimeUtils`
+**Global variable:** [`HyperfrontendTimeUtils`](https://www.hyperfrontend.dev/docs/libraries/utils/time/)
 
 ### Dependencies
 

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.cjs.js

@@ -1,4 +1,8 @@
 'use strict';
+
+const _Number = globalThis.Number;
 const _isNaN = globalThis.isNaN;
+const isFinite = _Number.isFinite;
 const globalIsNaN = _isNaN;
 exports.globalIsNaN = globalIsNaN;
+exports.isFinite = isFinite;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js

@@ -1,5 +1,6 @@
-
+const _Number = globalThis.Number;
 const _isNaN = globalThis.isNaN;
+const isFinite = _Number.isFinite;
 const globalIsNaN = _isNaN;
 
-export { globalIsNaN };
+export { globalIsNaN, isFinite };

package/bundle/index.iife.js

@@ -88,15 +88,17 @@ var HyperfrontendTimeUtils = (function (exports) {
     const _Math = globalThis.Math;
     const floor = _Math.floor;
 
+    const _Number = globalThis.Number;
     const _isNaN = globalThis.isNaN;
+    const isFinite = _Number.isFinite;
     const globalIsNaN = _isNaN;
 
     function normalizeToBaseTimeWindow(time, baseTimeWindow) {
         if (!time || !(time instanceof Date) || globalIsNaN(time.getTime())) {
             throw createError('Invalid time input');
         }
-        if (baseTimeWindow <= 0) {
-            throw createError('Base time window must be positive');
+        if (!isFinite(baseTimeWindow) || baseTimeWindow <= 0) {
+            throw createError('Base time window must be a positive finite number');
         }
         const timeInMs = time.getTime();
         const windowInMs = baseTimeWindow * 60 * 1000;

package/bundle/index.iife.min.js

@@ -1 +1 @@
-var HyperfrontendTimeUtils=function(e){"use strict";const l=globalThis.Date,t=globalThis.Reflect;function n(...e){return t.construct(l,e)}const i=l.now,o=globalThis.Object.freeze,s=globalThis.setTimeout,r=globalThis.setInterval,a=globalThis.clearTimeout,c=globalThis.clearInterval,u=(e,l,...t)=>s(e,l,...t),b=(e,l,...t)=>r(e,l,...t),T=e=>{c(e)};const f=globalThis.Error,h=globalThis.Reflect,g=(e,l)=>h.construct(f,[e,l]),m=globalThis.Math.floor,d=globalThis.isNaN;const v=globalThis.Promise,p=globalThis.Reflect;return v.resolve.bind(v),v.reject.bind(v),v.all.bind(v),v.race.bind(v),v.allSettled.bind(v),v.any.bind(v),v.withResolvers?.bind(v),e.createClock=function(e=1e3){let l=null,t=[];return o({start:()=>{null===l&&(l=b(()=>{const e=n();t.forEach(l=>l(e))},e))},stop:()=>{null!==l&&(T(l),l=null)},subscribe:e=>{t.push(e)},unsubscribe:e=>{t=t.filter(l=>l!==e)},interval:e})},e.createTimer=function(e,l){let t=null,n=null,s=l;const r=()=>{if(null!==t){a(t);const e=i();null!==n&&(s-=e-n),t=null}},c=()=>{null===t&&(n=i(),t=u(()=>{e(),t=null},s))};return o({pause:r,resume:c,reset:(e=l)=>{r(),s=e,c()}})},e.normalizeToBaseTimeWindow=function(e,l){if(!e||!(e instanceof Date)||d(e.getTime()))throw g("Invalid time input");if(l<=0)throw g("Base time window must be positive");const t=e.getTime(),i=60*l*1e3;return n(m(t/i)*i)},e.setIntervalCallback=function(e,l){const t=b(e,l);return()=>T(t)},e.sleep=function(e){return l=l=>u(l,e),p.construct(v,[l]);var l},e}({});
+var HyperfrontendTimeUtils=function(e){"use strict";const l=globalThis.Date,t=globalThis.Reflect;function n(...e){return t.construct(l,e)}const i=l.now,o=globalThis.Object.freeze,s=globalThis.setTimeout,r=globalThis.setInterval,a=globalThis.clearTimeout,u=globalThis.clearInterval,c=(e,l,...t)=>s(e,l,...t),b=(e,l,...t)=>r(e,l,...t),T=e=>{u(e)};const f=globalThis.Error,h=globalThis.Reflect,g=(e,l)=>h.construct(f,[e,l]),m=globalThis.Math.floor,d=globalThis.Number,v=globalThis.isNaN,p=d.isFinite,w=v;const I=globalThis.Promise,R=globalThis.Reflect;return I.resolve.bind(I),I.reject.bind(I),I.all.bind(I),I.race.bind(I),I.allSettled.bind(I),I.any.bind(I),I.withResolvers?.bind(I),e.createClock=function(e=1e3){let l=null,t=[];return o({start:()=>{null===l&&(l=b(()=>{const e=n();t.forEach(l=>l(e))},e))},stop:()=>{null!==l&&(T(l),l=null)},subscribe:e=>{t.push(e)},unsubscribe:e=>{t=t.filter(l=>l!==e)},interval:e})},e.createTimer=function(e,l){let t=null,n=null,s=l;const r=()=>{if(null!==t){a(t);const e=i();null!==n&&(s-=e-n),t=null}},u=()=>{null===t&&(n=i(),t=c(()=>{e(),t=null},s))};return o({pause:r,resume:u,reset:(e=l)=>{r(),s=e,u()}})},e.normalizeToBaseTimeWindow=function(e,l){if(!e||!(e instanceof Date)||w(e.getTime()))throw g("Invalid time input");if(!p(l)||l<=0)throw g("Base time window must be a positive finite number");const t=e.getTime(),i=60*l*1e3;return n(m(t/i)*i)},e.setIntervalCallback=function(e,l){const t=b(e,l);return()=>T(t)},e.sleep=function(e){return l=l=>c(l,e),R.construct(I,[l]);var l},e}({});

package/bundle/index.umd.js

@@ -91,15 +91,17 @@
     const _Math = globalThis.Math;
     const floor = _Math.floor;
 
+    const _Number = globalThis.Number;
     const _isNaN = globalThis.isNaN;
+    const isFinite = _Number.isFinite;
     const globalIsNaN = _isNaN;
 
     function normalizeToBaseTimeWindow(time, baseTimeWindow) {
         if (!time || !(time instanceof Date) || globalIsNaN(time.getTime())) {
             throw createError('Invalid time input');
         }
-        if (baseTimeWindow <= 0) {
-            throw createError('Base time window must be positive');
+        if (!isFinite(baseTimeWindow) || baseTimeWindow <= 0) {
+            throw createError('Base time window must be a positive finite number');
         }
         const timeInMs = time.getTime();
         const windowInMs = baseTimeWindow * 60 * 1000;

package/bundle/index.umd.min.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).HyperfrontendTimeUtils={})}(this,function(e){"use strict";const t=globalThis.Date,l=globalThis.Reflect;function n(...e){return l.construct(t,e)}const i=t.now,o=globalThis.Object.freeze,s=globalThis.setTimeout,r=globalThis.setInterval,a=globalThis.clearTimeout,u=globalThis.clearInterval,c=(e,t,...l)=>s(e,t,...l),f=(e,t,...l)=>r(e,t,...l),b=e=>{u(e)};const T=globalThis.Error,h=globalThis.Reflect,d=(e,t)=>h.construct(T,[e,t]),g=globalThis.Math.floor,m=globalThis.isNaN;const p=globalThis.Promise,v=globalThis.Reflect;p.resolve.bind(p),p.reject.bind(p),p.all.bind(p),p.race.bind(p),p.allSettled.bind(p),p.any.bind(p),p.withResolvers?.bind(p),e.createClock=function(e=1e3){let t=null,l=[];return o({start:()=>{null===t&&(t=f(()=>{const e=n();l.forEach(t=>t(e))},e))},stop:()=>{null!==t&&(b(t),t=null)},subscribe:e=>{l.push(e)},unsubscribe:e=>{l=l.filter(t=>t!==e)},interval:e})},e.createTimer=function(e,t){let l=null,n=null,s=t;const r=()=>{if(null!==l){a(l);const e=i();null!==n&&(s-=e-n),l=null}},u=()=>{null===l&&(n=i(),l=c(()=>{e(),l=null},s))};return o({pause:r,resume:u,reset:(e=t)=>{r(),s=e,u()}})},e.normalizeToBaseTimeWindow=function(e,t){if(!e||!(e instanceof Date)||m(e.getTime()))throw d("Invalid time input");if(t<=0)throw d("Base time window must be positive");const l=e.getTime(),i=60*t*1e3;return n(g(l/i)*i)},e.setIntervalCallback=function(e,t){const l=f(e,t);return()=>b(l)},e.sleep=function(e){return t=t=>c(t,e),v.construct(p,[t]);var t}});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).HyperfrontendTimeUtils={})}(this,function(e){"use strict";const t=globalThis.Date,l=globalThis.Reflect;function n(...e){return l.construct(t,e)}const i=t.now,o=globalThis.Object.freeze,s=globalThis.setTimeout,r=globalThis.setInterval,a=globalThis.clearTimeout,u=globalThis.clearInterval,c=(e,t,...l)=>s(e,t,...l),b=(e,t,...l)=>r(e,t,...l),f=e=>{u(e)};const T=globalThis.Error,h=globalThis.Reflect,d=(e,t)=>h.construct(T,[e,t]),g=globalThis.Math.floor,m=globalThis.Number,p=globalThis.isNaN,v=m.isFinite,w=p;const y=globalThis.Promise,I=globalThis.Reflect;y.resolve.bind(y),y.reject.bind(y),y.all.bind(y),y.race.bind(y),y.allSettled.bind(y),y.any.bind(y),y.withResolvers?.bind(y),e.createClock=function(e=1e3){let t=null,l=[];return o({start:()=>{null===t&&(t=b(()=>{const e=n();l.forEach(t=>t(e))},e))},stop:()=>{null!==t&&(f(t),t=null)},subscribe:e=>{l.push(e)},unsubscribe:e=>{l=l.filter(t=>t!==e)},interval:e})},e.createTimer=function(e,t){let l=null,n=null,s=t;const r=()=>{if(null!==l){a(l);const e=i();null!==n&&(s-=e-n),l=null}},u=()=>{null===l&&(n=i(),l=c(()=>{e(),l=null},s))};return o({pause:r,resume:u,reset:(e=t)=>{r(),s=e,u()}})},e.normalizeToBaseTimeWindow=function(e,t){if(!e||!(e instanceof Date)||w(e.getTime()))throw d("Invalid time input");if(!v(t)||t<=0)throw d("Base time window must be a positive finite number");const l=e.getTime(),i=60*t*1e3;return n(g(l/i)*i)},e.setIntervalCallback=function(e,t){const l=b(e,t);return()=>f(l)},e.sleep=function(e){return t=t=>c(t,e),I.construct(y,[t]);var t}});

package/index.cjs.js

@@ -93,7 +93,7 @@ function createTimer(callback, delay) {
         if (timerId !== null) {
             index_cjs_js$1.clearTimeout(timerId);
             const now = index_cjs_js$2.dateNow();
-            /* istanbul ignore else - start is always set when timerId is not null */
+            // why: start is always set when timerId is not null, so the guard never falls through.
             if (start !== null) {
                 remaining -= now - start;
             }
@@ -121,7 +121,7 @@ function createTimer(callback, delay) {
  * Normalizes a given time to the nearest base time window.
  *
  * @param time - The Date object to normalize to the nearest time window
- * @param baseTimeWindow - The size of the time window in minutes for normalization
+ * @param baseTimeWindow - The size of the time window in minutes for normalization; must be a positive finite number
  * @returns A new Date object normalized to the start of the time window
  *
  * @example Normalizing to 15-minute buckets
@@ -136,8 +136,8 @@ function normalizeToBaseTimeWindow(time, baseTimeWindow) {
     if (!time || !(time instanceof Date) || index_cjs_js$3.globalIsNaN(time.getTime())) {
         throw index_cjs_js$4.createError('Invalid time input');
     }
-    if (baseTimeWindow <= 0) {
-        throw index_cjs_js$4.createError('Base time window must be positive');
+    if (!index_cjs_js$3.isFinite(baseTimeWindow) || baseTimeWindow <= 0) {
+        throw index_cjs_js$4.createError('Base time window must be a positive finite number');
     }
     const timeInMs = time.getTime();
     const windowInMs = baseTimeWindow * 60 * 1000;

package/index.d.ts

@@ -81,7 +81,7 @@ declare function createTimer(callback: () => void, delay: number): Timer;
  * Normalizes a given time to the nearest base time window.
  *
  * @param time - The Date object to normalize to the nearest time window
- * @param baseTimeWindow - The size of the time window in minutes for normalization
+ * @param baseTimeWindow - The size of the time window in minutes for normalization; must be a positive finite number
  * @returns A new Date object normalized to the start of the time window
  *
  * @example Normalizing to 15-minute buckets

package/index.esm.js

@@ -3,7 +3,7 @@ import { freeze } from './_dependencies/@hyperfrontend/immutable-api-utils/built
 import { setInterval, clearInterval, setTimeout, clearTimeout } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
 import { createError } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
 import { floor } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
-import { globalIsNaN } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
+import { globalIsNaN, isFinite } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
 import { createPromise } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
 
 /**
@@ -91,7 +91,7 @@ function createTimer(callback, delay) {
         if (timerId !== null) {
             clearTimeout(timerId);
             const now = dateNow();
-            /* istanbul ignore else - start is always set when timerId is not null */
+            // why: start is always set when timerId is not null, so the guard never falls through.
             if (start !== null) {
                 remaining -= now - start;
             }
@@ -119,7 +119,7 @@ function createTimer(callback, delay) {
  * Normalizes a given time to the nearest base time window.
  *
  * @param time - The Date object to normalize to the nearest time window
- * @param baseTimeWindow - The size of the time window in minutes for normalization
+ * @param baseTimeWindow - The size of the time window in minutes for normalization; must be a positive finite number
  * @returns A new Date object normalized to the start of the time window
  *
  * @example Normalizing to 15-minute buckets
@@ -134,8 +134,8 @@ function normalizeToBaseTimeWindow(time, baseTimeWindow) {
     if (!time || !(time instanceof Date) || globalIsNaN(time.getTime())) {
         throw createError('Invalid time input');
     }
-    if (baseTimeWindow <= 0) {
-        throw createError('Base time window must be positive');
+    if (!isFinite(baseTimeWindow) || baseTimeWindow <= 0) {
+        throw createError('Base time window must be a positive finite number');
     }
     const timeInMs = time.getTime();
     const windowInMs = baseTimeWindow * 60 * 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfrontend/time-utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Functional time utilities for async operations, intervals, and time normalization.",
   "license": "MIT",
   "sideEffects": false,