@hyperfrontend/time-utils 0.0.5 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

@@ -36,6 +36,7 @@
 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?
 
@@ -62,7 +63,7 @@ All timing abstractions maintain internal state privately while exposing frozen
 
 ### 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()`.
 
@@ -247,7 +248,7 @@ cleanup()
 
 ### 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/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,79 +81,16 @@ 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 _isNaN = globalThis.isNaN;
-    /**
-     * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
-     */
     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');
@@ -323,90 +104,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.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,79 +84,16 @@
         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 _isNaN = globalThis.isNaN;
-    /**
-     * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
-     */
     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');
@@ -326,90 +107,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/package.json

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