@hyperfrontend/time-utils 0.0.5 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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
+
+- Marked stable. No API changes since 0.0.5.
+
 ## [0.0.5](https://github.com/AndrewRedican/hyperfrontend/compare/c8db08be8b183addd26caf81fdd17fb3693f296f...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
 ### Other

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,38 +37,41 @@
   <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/)
+• 👉 See [**guides & tutorials**](https://www.hyperfrontend.dev/docs/guides/?package=%40hyperfrontend%2Ftime-utils)
 
 ## 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.
+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
 
@@ -161,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) => {
@@ -170,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
 ```
 
@@ -191,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
 
@@ -243,11 +250,11 @@ cleanup()
 </script>
 ```
 
-**Global variable:** `HyperfrontendTimeUtils`
+**Global variable:** [`HyperfrontendTimeUtils`](https://www.hyperfrontend.dev/docs/libraries/utils/time/)
 
 ### Dependencies
 
-None — zero external dependencies.
+None: zero external dependencies.
 
 ## Part of hyperfrontend
 

package/SECURITY.md

@@ -1,5 +1,28 @@
 # Security Policy
 
+## The Security Model
+
+Before reporting or reviewing, read the model this project is built on:
+**[Security Model](https://www.hyperfrontend.dev/docs/core-concepts/security)**. It is the canonical
+statement of what hyperfrontend defends against and what it does not, and it is the reference every
+other security claim in these docs points back to. In short:
+
+- **The named adversary is co-resident script**: an analytics snippet, tag manager, compromised
+  dependency, or unknown page that embeds a feature URL. A host that deliberately installs a feature
+  is trusting it, the way it trusts any dependency; the controls exist to bound a trusted
+  feature's bad day, not to treat its authors as hostile.
+- **Origin checks authenticate rooms, not speakers.** Once arbitrary script runs inside a page, no
+  message check distinguishes it from the application. Threats inside a page need Content Security
+  Policy, Trusted Types, dependency provenance, and server-side authorisation. That is a different
+  treatment, deliberately outside this model.
+- **Three parties carry the security of an integration.** The browser enforces document isolation
+  and the frame's capability attributes; the protocol enforces the relationship (pinned
+  counterparts, gated handshake, validated payloads, versioned contracts, an optional encrypted
+  envelope); and **you** decide authorisation: `frame-ancestors`, backend checks, HTTPS, the
+  envelope you choose, and the containment posture you set.
+
+A vulnerability report is most useful when it names which of those three the issue defeats.
+
 ## Reporting a Vulnerability
 
 We take the security of hyperfrontend seriously. If you discover a security vulnerability, please help us protect our users by following responsible disclosure practices.
@@ -58,14 +81,30 @@ Thank you for helping keep hyperfrontend and its users safe!
 
 ## Security Best Practices
 
-When using hyperfrontend in your applications:
-
-1. **Keep Dependencies Updated**: Regularly update to the latest version to receive security patches
-2. **Content Security Policy**: Implement appropriate CSP headers when embedding features
-3. **Input Validation**: Validate and sanitize all data passed between features
-4. **Origin Verification**: Always verify the origin of messages in cross-frame communication
-5. **Authentication**: Implement proper authentication and authorization for sensitive features
-6. **HTTPS**: Always serve hyperfrontend features over HTTPS in production
+These are the decisions the SDK cannot make for you. Everything the protocol already enforces —
+origin pinning, window binding, instance identity, the gated handshake, payload validation on both
+ends — is on by default and is not something you should be re-implementing by hand.
+
+1. **Restrict who may embed the feature.** Send
+   `Content-Security-Policy: frame-ancestors <hosts>` on the response that serves the feature
+   document. Origin pinning keeps a conversation consistent; only `frame-ancestors` decides whether
+   a page was ever allowed to frame you.
+2. **Authorise on the server.** A message that crossed the boundary is not an authorised operation.
+   Protected work needs credentials the feature's own backend validates.
+3. **Choose the envelope deliberately.** `v2` with a pre-shared key is the confidentiality control;
+   `v1` is time-window obfuscation and buys deterrence only. Provision and rotate the `v2` key
+   yourself; a key is never baked into a built artifact. A handshake that cannot agree on an
+   encrypted transport falls back to plaintext; where that would be unacceptable, drive
+   `@hyperfrontend/nexus` directly and set `security.mode: 'fail-closed'` on the channel so the
+   connection is denied instead.
+4. **Declare schemas and a contract version.** Actions without a schema pass unvalidated, and a side
+   without a version always passes the compatibility gate. Both are how drift is caught early.
+5. **Grant capability narrowly.** Delegate only the Permissions-Policy features the integration
+   needs, and price a `sandbox` posture against what the product actually requires.
+6. **Serve everything over HTTPS**, host and feature alike.
+7. **Keep dependencies updated** on both sides of the boundary, and pair that with the page-integrity
+   controls this model deliberately leaves to you: Content Security Policy, Trusted Types,
+   Subresource Integrity, and dependency provenance.
 
 ## Security Updates
 
@@ -73,10 +112,6 @@ Security updates will be released as patch versions and documented in the [CHANG
 
 ## Supported Versions
 
-We currently provide security updates for:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.0.x   | :white_check_mark: |
-
-As the project matures, we will update this table to reflect our long-term support policy.
+Security updates are provided for the latest published version of each `@hyperfrontend/*` package.
+Older releases receive no backports. A long-term support policy will replace this section once the
+packages settle on a stable release cadence.

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

@@ -1,158 +1,29 @@
 var HyperfrontendTimeUtils = (function (exports) {
     'use strict';
 
-    /**
-     * Safe copies of Date built-in via factory function and static methods.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/date
-     */
-    /* eslint-disable jsdoc/require-param */
     const _Date = globalThis.Date;
     const _Reflect$2 = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Date using the captured Date constructor.
-     * Use this instead of `new Date()`. Accepts all standard Date constructor signatures.
-     *
-     * @returns A new Date instance.
-     *
-     * @example Creating Date instances
-     * ```typescript
-     * const now = createDate()
-     * const fromTimestamp = createDate(1704067200000)
-     * const fromString = createDate('2024-01-01T00:00:00Z')
-     * const fromParts = createDate(2024, 0, 1, 12, 30, 0) // Jan 1, 2024 12:30:00
-     * ```
-     */
     function createDate(...args) {
         return _Reflect$2.construct(_Date, args);
     }
-    /**
-     * (Safe copy) Returns the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC.
-     *
-     * @example
-     * ```typescript
-     * const timestamp = dateNow()
-     * // => 1704067200000 (example timestamp)
-     * ```
-     */
     const dateNow = _Date.now;
 
-    /**
-     * Safe copies of Object built-in methods.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
-     */
     const _Object = globalThis.Object;
-    /**
-     * (Safe copy) Prevents modification of existing property attributes and values,
-     * and prevents the addition of new properties.
-     */
     const freeze = _Object.freeze;
 
-    /**
-     * Safe copies of Timer/Scheduling built-in functions.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/timers
-     */
     const _setTimeout = globalThis.setTimeout;
     const _setInterval = globalThis.setInterval;
     const _clearTimeout = globalThis.clearTimeout;
     const _clearInterval = globalThis.clearInterval;
-    /**
-     * (Safe copy) Sets a timer which executes a function once the timer expires.
-     *
-     * @param callback - Function to call when the timer elapses.
-     * @param delay - Time in milliseconds before executing.
-     * @param args - Additional arguments to pass to the callback.
-     * @returns A numeric ID for the timer.
-     *
-     * @example Setting a timeout
-     * ```typescript
-     * const timerId = setTimeout(() => console.log('Executed'), 1000)
-     * // Pass arguments to callback
-     * setTimeout((name, count) => console.log(name, count), 500, 'items', 5)
-     * ```
-     */
     const setTimeout = (callback, delay, ...args) => _setTimeout(callback, delay, ...args);
-    /**
-     * (Safe copy) Repeatedly calls a function with a fixed time delay between each call.
-     *
-     * @param callback - Function to call at each interval.
-     * @param delay - Time in milliseconds between calls.
-     * @param args - Additional arguments to pass to the callback.
-     * @returns A numeric ID for the interval.
-     *
-     * @example Setting an interval
-     * ```typescript
-     * let count = 0
-     * const intervalId = setInterval(() => {
-     *   count++
-     *   if (count >= 5) clearInterval(intervalId)
-     * }, 1000)
-     * ```
-     */
     const setInterval = (callback, delay, ...args) => _setInterval(callback, delay, ...args);
-    /**
-     * (Safe copy) Cancels a timeout previously established by setTimeout.
-     *
-     * @param id - The identifier of the timeout to cancel.
-     *
-     * @example Canceling a timeout
-     * ```typescript
-     * const timerId = setTimeout(() => console.log('Never runs'), 5000)
-     * clearTimeout(timerId)
-     * ```
-     */
     const clearTimeout = (id) => {
         _clearTimeout(id);
     };
-    /**
-     * (Safe copy) Cancels a timed, repeating action previously established by setInterval.
-     *
-     * @param id - The identifier of the interval to cancel.
-     *
-     * @example Canceling an interval
-     * ```typescript
-     * const intervalId = setInterval(() => console.log('tick'), 1000)
-     * // Stop after some condition
-     * clearInterval(intervalId)
-     * ```
-     */
     const clearInterval = (id) => {
         _clearInterval(id);
     };
 
-    /**
-     * Creates an interval loop that invokes one or more subscribed callback functions
-     * at the specified internal (in milliseconds).
-     *
-     * Allows you to start or stop the interval loop, much like a stop watch.
-     * Allows you to unsubscribe callback functions.
-     *
-     * @param interval - Time in milliseconds between each callback invocation (default: 1000ms)
-     * @returns A Clock instance with start, stop, subscribe, and unsubscribe methods
-     *
-     * @example Creating interval clock
-     * ```typescript
-     * const clock = createClock(1000)
-     *
-     * const updateDisplay = (currentTime: Date) => {
-     *   console.log(currentTime.toISOString())
-     * }
-     *
-     * clock.subscribe(updateDisplay)
-     * clock.start()
-     *
-     * // Later: stop receiving updates
-     * clock.stop()
-     * ```
-     */
     function createClock(interval = 1000) {
         let clockId = null;
         let subscribers = [];
@@ -179,32 +50,6 @@ var HyperfrontendTimeUtils = (function (exports) {
         return freeze({ start, stop, subscribe, unsubscribe, interval });
     }
 
-    /**
-     * Invokes callback function after the designated time has passed, much like a timer.
-     * Allows you to pause, resume, or reset the progress of time tracked.
-     *
-     * @param callback - The function to invoke after the delay
-     * @param delay - Time in milliseconds to wait until callback is invoked
-     * @returns A Timer instance with pause, resume, and reset methods
-     *
-     * @example Creating pausable timer
-     * ```typescript
-     * const timer = createTimer(() => {
-     *   console.log('Session expired')
-     * }, 30_000)
-     *
-     * timer.resume() // Start the 30-second countdown
-     *
-     * // User activity detected - pause the timer
-     * timer.pause()
-     *
-     * // User idle again - resume from where we left off
-     * timer.resume()
-     *
-     * // Reset to full 30 seconds on explicit action
-     * timer.reset()
-     * ```
-     */
     function createTimer(callback, delay) {
         let timerId = null;
         let start = null;
@@ -213,7 +58,6 @@ var HyperfrontendTimeUtils = (function (exports) {
             if (timerId !== null) {
                 clearTimeout(timerId);
                 const now = dateNow();
-                /* istanbul ignore else - start is always set when timerId is not null */
                 if (start !== null) {
                     remaining -= now - start;
                 }
@@ -237,85 +81,24 @@ var HyperfrontendTimeUtils = (function (exports) {
         return freeze({ pause, resume, reset });
     }
 
-    /**
-     * Safe copies of Error built-ins via factory functions.
-     *
-     * Since constructors cannot be safely captured via Object.assign, this module
-     * provides factory functions that use Reflect.construct internally.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
-     */
     const _Error = globalThis.Error;
     const _Reflect$1 = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Error using the captured Error constructor.
-     * Use this instead of `new Error()`.
-     *
-     * @param message - Optional error message.
-     * @param options - Optional error options.
-     * @returns A new Error instance.
-     *
-     * @example Creating Error instances
-     * ```typescript
-     * const error = createError('Operation failed')
-     * // With cause for error chaining
-     * const wrapped = createError('Request failed', { cause: originalError })
-     * ```
-     */
     const createError = (message, options) => _Reflect$1.construct(_Error, [message, options]);
 
-    /**
-     * Safe copies of Math built-in methods.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
-     */
     const _Math = globalThis.Math;
-    /**
-     * (Safe copy) Returns the largest integer less than or equal to a number.
-     */
     const floor = _Math.floor;
 
-    /**
-     * Safe copies of Number built-in methods and constants.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/number
-     */
+    const _Number = globalThis.Number;
     const _isNaN = globalThis.isNaN;
-    /**
-     * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
-     */
+    const isFinite = _Number.isFinite;
     const globalIsNaN = _isNaN;
 
-    /**
-     * 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
-     * @returns A new Date object normalized to the start of the time window
-     *
-     * @example Normalizing to 15-minute buckets
-     * ```typescript
-     * // Round timestamps to 15-minute intervals for analytics bucketing
-     * const eventTime = new Date('2024-03-15T14:23:45Z')
-     * const bucketTime = normalizeToBaseTimeWindow(eventTime, 15)
-     * // => 2024-03-15T14:15:00.000Z
-     * ```
-     */
     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;
@@ -323,90 +106,22 @@ var HyperfrontendTimeUtils = (function (exports) {
         return createDate(normalizedTimeInMs);
     }
 
-    /**
-     * Creates a repeating interval that invokes a callback function at regular intervals.
-     *
-     * @param callback - The function to invoke at each interval
-     * @param interval - Time in milliseconds between each callback invocation
-     * @returns A cleanup function that stops the interval when called
-     *
-     * @example Setting interval with cleanup
-     * ```typescript
-     * const stopPolling = setIntervalCallback(() => {
-     *   fetchLatestData()
-     * }, 5000)
-     *
-     * // Later: clean up when component unmounts
-     * stopPolling()
-     * ```
-     */
     function setIntervalCallback(callback, interval) {
         const timerId = setInterval(callback, interval);
         return () => clearInterval(timerId);
     }
 
-    /**
-     * Safe Promise factory and bound static methods.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/promise
-     */
-    /* eslint-disable workspace/lib-require-jsdoc-example */
     const _Promise = globalThis.Promise;
     const _Reflect = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Promise using the captured Promise constructor.
-     * Use this instead of `new Promise()`.
-     *
-     * @param executor - The executor function.
-     * @returns A new Promise instance.
-     */
     const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
-    /**
-     * (Safe copy) Returns a Promise that resolves with the given value.
-     */
     _Promise.resolve.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that rejects with the given reason.
-     */
     _Promise.reject.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves when all promises resolve.
-     */
     _Promise.all.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves/rejects with the first settled promise.
-     */
     _Promise.race.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves when all promises settle.
-     */
     _Promise.allSettled.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves with the first fulfilled promise.
-     */
     _Promise.any.bind(_Promise);
-    /**
-     * (Safe copy) Creates a Promise along with its resolve and reject functions.
-     * Note: Available only in ES2024+ environments.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     _Promise.withResolvers?.bind(_Promise);
 
-    /**
-     * Pauses execution for a specified duration.
-     *
-     * @param milliseconds - The duration to sleep in milliseconds
-     * @returns A promise that resolves after the specified duration
-     *
-     * @example Implementing retry backoff
-     * ```typescript
-     * async function retryWithBackoff(attempt: number) {
-     *   const backoffMs = Math.min(1000 * 2 ** attempt, 30_000)
-     *   await sleep(backoffMs)
-     *   return fetchResource()
-     * }
-     * ```
-     */
     function sleep(milliseconds) {
         return createPromise((resolve) => setTimeout(resolve, milliseconds));
     }

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

@@ -4,158 +4,29 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.HyperfrontendTimeUtils = {}));
 })(this, (function (exports) { 'use strict';
 
-    /**
-     * Safe copies of Date built-in via factory function and static methods.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/date
-     */
-    /* eslint-disable jsdoc/require-param */
     const _Date = globalThis.Date;
     const _Reflect$2 = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Date using the captured Date constructor.
-     * Use this instead of `new Date()`. Accepts all standard Date constructor signatures.
-     *
-     * @returns A new Date instance.
-     *
-     * @example Creating Date instances
-     * ```typescript
-     * const now = createDate()
-     * const fromTimestamp = createDate(1704067200000)
-     * const fromString = createDate('2024-01-01T00:00:00Z')
-     * const fromParts = createDate(2024, 0, 1, 12, 30, 0) // Jan 1, 2024 12:30:00
-     * ```
-     */
     function createDate(...args) {
         return _Reflect$2.construct(_Date, args);
     }
-    /**
-     * (Safe copy) Returns the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC.
-     *
-     * @example
-     * ```typescript
-     * const timestamp = dateNow()
-     * // => 1704067200000 (example timestamp)
-     * ```
-     */
     const dateNow = _Date.now;
 
-    /**
-     * Safe copies of Object built-in methods.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
-     */
     const _Object = globalThis.Object;
-    /**
-     * (Safe copy) Prevents modification of existing property attributes and values,
-     * and prevents the addition of new properties.
-     */
     const freeze = _Object.freeze;
 
-    /**
-     * Safe copies of Timer/Scheduling built-in functions.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/timers
-     */
     const _setTimeout = globalThis.setTimeout;
     const _setInterval = globalThis.setInterval;
     const _clearTimeout = globalThis.clearTimeout;
     const _clearInterval = globalThis.clearInterval;
-    /**
-     * (Safe copy) Sets a timer which executes a function once the timer expires.
-     *
-     * @param callback - Function to call when the timer elapses.
-     * @param delay - Time in milliseconds before executing.
-     * @param args - Additional arguments to pass to the callback.
-     * @returns A numeric ID for the timer.
-     *
-     * @example Setting a timeout
-     * ```typescript
-     * const timerId = setTimeout(() => console.log('Executed'), 1000)
-     * // Pass arguments to callback
-     * setTimeout((name, count) => console.log(name, count), 500, 'items', 5)
-     * ```
-     */
     const setTimeout = (callback, delay, ...args) => _setTimeout(callback, delay, ...args);
-    /**
-     * (Safe copy) Repeatedly calls a function with a fixed time delay between each call.
-     *
-     * @param callback - Function to call at each interval.
-     * @param delay - Time in milliseconds between calls.
-     * @param args - Additional arguments to pass to the callback.
-     * @returns A numeric ID for the interval.
-     *
-     * @example Setting an interval
-     * ```typescript
-     * let count = 0
-     * const intervalId = setInterval(() => {
-     *   count++
-     *   if (count >= 5) clearInterval(intervalId)
-     * }, 1000)
-     * ```
-     */
     const setInterval = (callback, delay, ...args) => _setInterval(callback, delay, ...args);
-    /**
-     * (Safe copy) Cancels a timeout previously established by setTimeout.
-     *
-     * @param id - The identifier of the timeout to cancel.
-     *
-     * @example Canceling a timeout
-     * ```typescript
-     * const timerId = setTimeout(() => console.log('Never runs'), 5000)
-     * clearTimeout(timerId)
-     * ```
-     */
     const clearTimeout = (id) => {
         _clearTimeout(id);
     };
-    /**
-     * (Safe copy) Cancels a timed, repeating action previously established by setInterval.
-     *
-     * @param id - The identifier of the interval to cancel.
-     *
-     * @example Canceling an interval
-     * ```typescript
-     * const intervalId = setInterval(() => console.log('tick'), 1000)
-     * // Stop after some condition
-     * clearInterval(intervalId)
-     * ```
-     */
     const clearInterval = (id) => {
         _clearInterval(id);
     };
 
-    /**
-     * Creates an interval loop that invokes one or more subscribed callback functions
-     * at the specified internal (in milliseconds).
-     *
-     * Allows you to start or stop the interval loop, much like a stop watch.
-     * Allows you to unsubscribe callback functions.
-     *
-     * @param interval - Time in milliseconds between each callback invocation (default: 1000ms)
-     * @returns A Clock instance with start, stop, subscribe, and unsubscribe methods
-     *
-     * @example Creating interval clock
-     * ```typescript
-     * const clock = createClock(1000)
-     *
-     * const updateDisplay = (currentTime: Date) => {
-     *   console.log(currentTime.toISOString())
-     * }
-     *
-     * clock.subscribe(updateDisplay)
-     * clock.start()
-     *
-     * // Later: stop receiving updates
-     * clock.stop()
-     * ```
-     */
     function createClock(interval = 1000) {
         let clockId = null;
         let subscribers = [];
@@ -182,32 +53,6 @@
         return freeze({ start, stop, subscribe, unsubscribe, interval });
     }
 
-    /**
-     * Invokes callback function after the designated time has passed, much like a timer.
-     * Allows you to pause, resume, or reset the progress of time tracked.
-     *
-     * @param callback - The function to invoke after the delay
-     * @param delay - Time in milliseconds to wait until callback is invoked
-     * @returns A Timer instance with pause, resume, and reset methods
-     *
-     * @example Creating pausable timer
-     * ```typescript
-     * const timer = createTimer(() => {
-     *   console.log('Session expired')
-     * }, 30_000)
-     *
-     * timer.resume() // Start the 30-second countdown
-     *
-     * // User activity detected - pause the timer
-     * timer.pause()
-     *
-     * // User idle again - resume from where we left off
-     * timer.resume()
-     *
-     * // Reset to full 30 seconds on explicit action
-     * timer.reset()
-     * ```
-     */
     function createTimer(callback, delay) {
         let timerId = null;
         let start = null;
@@ -216,7 +61,6 @@
             if (timerId !== null) {
                 clearTimeout(timerId);
                 const now = dateNow();
-                /* istanbul ignore else - start is always set when timerId is not null */
                 if (start !== null) {
                     remaining -= now - start;
                 }
@@ -240,85 +84,24 @@
         return freeze({ pause, resume, reset });
     }
 
-    /**
-     * Safe copies of Error built-ins via factory functions.
-     *
-     * Since constructors cannot be safely captured via Object.assign, this module
-     * provides factory functions that use Reflect.construct internally.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
-     */
     const _Error = globalThis.Error;
     const _Reflect$1 = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Error using the captured Error constructor.
-     * Use this instead of `new Error()`.
-     *
-     * @param message - Optional error message.
-     * @param options - Optional error options.
-     * @returns A new Error instance.
-     *
-     * @example Creating Error instances
-     * ```typescript
-     * const error = createError('Operation failed')
-     * // With cause for error chaining
-     * const wrapped = createError('Request failed', { cause: originalError })
-     * ```
-     */
     const createError = (message, options) => _Reflect$1.construct(_Error, [message, options]);
 
-    /**
-     * Safe copies of Math built-in methods.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
-     */
     const _Math = globalThis.Math;
-    /**
-     * (Safe copy) Returns the largest integer less than or equal to a number.
-     */
     const floor = _Math.floor;
 
-    /**
-     * Safe copies of Number built-in methods and constants.
-     *
-     * These references are captured at module initialization time to protect against
-     * prototype pollution attacks. Import only what you need for tree-shaking.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/number
-     */
+    const _Number = globalThis.Number;
     const _isNaN = globalThis.isNaN;
-    /**
-     * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
-     */
+    const isFinite = _Number.isFinite;
     const globalIsNaN = _isNaN;
 
-    /**
-     * 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
-     * @returns A new Date object normalized to the start of the time window
-     *
-     * @example Normalizing to 15-minute buckets
-     * ```typescript
-     * // Round timestamps to 15-minute intervals for analytics bucketing
-     * const eventTime = new Date('2024-03-15T14:23:45Z')
-     * const bucketTime = normalizeToBaseTimeWindow(eventTime, 15)
-     * // => 2024-03-15T14:15:00.000Z
-     * ```
-     */
     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;
@@ -326,90 +109,22 @@
         return createDate(normalizedTimeInMs);
     }
 
-    /**
-     * Creates a repeating interval that invokes a callback function at regular intervals.
-     *
-     * @param callback - The function to invoke at each interval
-     * @param interval - Time in milliseconds between each callback invocation
-     * @returns A cleanup function that stops the interval when called
-     *
-     * @example Setting interval with cleanup
-     * ```typescript
-     * const stopPolling = setIntervalCallback(() => {
-     *   fetchLatestData()
-     * }, 5000)
-     *
-     * // Later: clean up when component unmounts
-     * stopPolling()
-     * ```
-     */
     function setIntervalCallback(callback, interval) {
         const timerId = setInterval(callback, interval);
         return () => clearInterval(timerId);
     }
 
-    /**
-     * Safe Promise factory and bound static methods.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/promise
-     */
-    /* eslint-disable workspace/lib-require-jsdoc-example */
     const _Promise = globalThis.Promise;
     const _Reflect = globalThis.Reflect;
-    /**
-     * (Safe copy) Creates a new Promise using the captured Promise constructor.
-     * Use this instead of `new Promise()`.
-     *
-     * @param executor - The executor function.
-     * @returns A new Promise instance.
-     */
     const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
-    /**
-     * (Safe copy) Returns a Promise that resolves with the given value.
-     */
     _Promise.resolve.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that rejects with the given reason.
-     */
     _Promise.reject.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves when all promises resolve.
-     */
     _Promise.all.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves/rejects with the first settled promise.
-     */
     _Promise.race.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves when all promises settle.
-     */
     _Promise.allSettled.bind(_Promise);
-    /**
-     * (Safe copy) Returns a Promise that resolves with the first fulfilled promise.
-     */
     _Promise.any.bind(_Promise);
-    /**
-     * (Safe copy) Creates a Promise along with its resolve and reject functions.
-     * Note: Available only in ES2024+ environments.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     _Promise.withResolvers?.bind(_Promise);
 
-    /**
-     * Pauses execution for a specified duration.
-     *
-     * @param milliseconds - The duration to sleep in milliseconds
-     * @returns A promise that resolves after the specified duration
-     *
-     * @example Implementing retry backoff
-     * ```typescript
-     * async function retryWithBackoff(attempt: number) {
-     *   const backoffMs = Math.min(1000 * 2 ** attempt, 30_000)
-     *   await sleep(backoffMs)
-     *   return fetchResource()
-     * }
-     * ```
-     */
     function sleep(milliseconds) {
         return createPromise((resolve) => setTimeout(resolve, milliseconds));
     }

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": "0.0.5",
+  "version": "1.0.1",
   "description": "Functional time utilities for async operations, intervals, and time normalization.",
   "license": "MIT",
   "sideEffects": false,