@hyperfrontend/time-utils 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,16 +1,24 @@
 # Changelog
 
-This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+All notable changes to this project will be documented in this file.
 
-## [0.0.4](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.3...lib-time-utils@0.0.4) (2026-03-08)
+## [0.0.5](https://github.com/AndrewRedican/hyperfrontend/compare/c8db08be8b183addd26caf81fdd17fb3693f296f...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
-## [0.0.3](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.2...lib-time-utils@0.0.3) (2026-03-02)
+### Other
 
+- **@hyperfrontend/workspace:** remove lib-builder and tool-package as implicit dependencies for all lib projects
+
+## [0.0.4](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.3...lib-time-utils@0.0.4) - 2026-03-08
+
+
+## [0.0.3](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.2...lib-time-utils@0.0.3) - 2026-03-02
 
 ### Bug Fixes
 
-* **lib-time-utils:** correct package exports and dependencies ([3b9096b](https://github.com/AndrewRedican/hyperfrontend/commit/3b9096b54337c2c2f3e06d6b97865a772e79aad9))
+- **lib-time-utils:** correct package exports and dependencies ([3b9096b](https://github.com/AndrewRedican/hyperfrontend/commit/3b9096b54337c2c2f3e06d6b97865a772e79aad9))
+
+## [0.0.2](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.1...lib-time-utils@0.0.2) - 2026-02-26
+
 
-## [0.0.2](https://github.com/AndrewRedican/hyperfrontend/compare/lib-time-utils@0.0.1...lib-time-utils@0.0.2) (2026-02-26)
+## 0.0.1 - 2026-02-15
 
-## 0.0.1 (2026-02-15)

package/README.md

@@ -35,6 +35,8 @@
 
 Functional time utilities for async operations, intervals, and time normalization.
 
+• 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/utils/time/)
+
 ## 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.
@@ -257,4 +259,4 @@ This library is part of the [hyperfrontend](https://github.com/AndrewRedican/hyp
 
 ## License
 
-MIT
+[MIT](https://github.com/AndrewRedican/hyperfrontend/blob/main/LICENSE.md)

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

@@ -0,0 +1,10 @@
+'use strict';
+
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+const dateNow = _Date.now;
+exports.createDate = createDate;
+exports.dateNow = dateNow;

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

@@ -0,0 +1,8 @@
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+const dateNow = _Date.now;
+
+export { createDate, dateNow };

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

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+exports.createError = createError;

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

@@ -0,0 +1,5 @@
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+
+export { createError };

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

@@ -0,0 +1,5 @@
+'use strict';
+
+const _Math = globalThis.Math;
+const floor = _Math.floor;
+exports.floor = floor;

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

@@ -0,0 +1,4 @@
+const _Math = globalThis.Math;
+const floor = _Math.floor;
+
+export { floor };

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

@@ -0,0 +1,4 @@
+'use strict';
+const _isNaN = globalThis.isNaN;
+const globalIsNaN = _isNaN;
+exports.globalIsNaN = globalIsNaN;

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

@@ -0,0 +1,5 @@
+
+const _isNaN = globalThis.isNaN;
+const globalIsNaN = _isNaN;
+
+export { globalIsNaN };

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

@@ -0,0 +1,5 @@
+'use strict';
+
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+exports.freeze = freeze;

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

@@ -0,0 +1,4 @@
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+
+export { freeze };

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

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Promise = globalThis.Promise;
+const _Reflect = globalThis.Reflect;
+const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
+exports.createPromise = createPromise;

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

@@ -0,0 +1,5 @@
+const _Promise = globalThis.Promise;
+const _Reflect = globalThis.Reflect;
+const createPromise = (executor) => _Reflect.construct(_Promise, [executor]);
+
+export { createPromise };

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

@@ -0,0 +1,18 @@
+'use strict';
+
+const _setTimeout = globalThis.setTimeout;
+const _setInterval = globalThis.setInterval;
+const _clearTimeout = globalThis.clearTimeout;
+const _clearInterval = globalThis.clearInterval;
+const setTimeout = (callback, delay, ...args) => _setTimeout(callback, delay, ...args);
+const setInterval = (callback, delay, ...args) => _setInterval(callback, delay, ...args);
+const clearTimeout = (id) => {
+    _clearTimeout(id);
+};
+const clearInterval = (id) => {
+    _clearInterval(id);
+};
+exports.clearInterval = clearInterval;
+exports.clearTimeout = clearTimeout;
+exports.setInterval = setInterval;
+exports.setTimeout = setTimeout;

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

@@ -0,0 +1,14 @@
+const _setTimeout = globalThis.setTimeout;
+const _setInterval = globalThis.setInterval;
+const _clearTimeout = globalThis.clearTimeout;
+const _clearInterval = globalThis.clearInterval;
+const setTimeout = (callback, delay, ...args) => _setTimeout(callback, delay, ...args);
+const setInterval = (callback, delay, ...args) => _setInterval(callback, delay, ...args);
+const clearTimeout = (id) => {
+    _clearTimeout(id);
+};
+const clearInterval = (id) => {
+    _clearInterval(id);
+};
+
+export { clearInterval, clearTimeout, setInterval, setTimeout };

package/bundle/index.iife.js

@@ -4,22 +4,36 @@ var HyperfrontendTimeUtils = (function (exports) {
     /**
      * Safe copies of Date built-in via factory function and static methods.
      *
-     * Since constructors cannot be safely captured via Object.assign, this module
-     * provides a factory function that uses 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/date
      */
-    // Capture references at module initialization time
+    /* 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;
 
@@ -31,7 +45,6 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
      */
-    // Capture references at module initialization time
     const _Object = globalThis.Object;
     /**
      * (Safe copy) Prevents modification of existing property attributes and values,
@@ -47,7 +60,6 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/timers
      */
-    // Capture references at module initialization time
     const _setTimeout = globalThis.setTimeout;
     const _setInterval = globalThis.setInterval;
     const _clearTimeout = globalThis.clearTimeout;
@@ -59,6 +71,13 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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);
     /**
@@ -68,12 +87,27 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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);
@@ -82,6 +116,13 @@ var HyperfrontendTimeUtils = (function (exports) {
      * (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);
@@ -96,6 +137,21 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @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;
@@ -130,6 +186,24 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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;
@@ -174,7 +248,6 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
      */
-    // Capture references at module initialization time
     const _Error = globalThis.Error;
     const _Reflect$1 = globalThis.Reflect;
     /**
@@ -184,6 +257,13 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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]);
 
@@ -195,7 +275,6 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
      */
-    // Capture references at module initialization time
     const _Math = globalThis.Math;
     /**
      * (Safe copy) Returns the largest integer less than or equal to a number.
@@ -210,11 +289,7 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/number
      */
-    // Capture references at module initialization time
     const _isNaN = globalThis.isNaN;
-    // ============================================================================
-    // Global Type Checking (legacy, less strict)
-    // ============================================================================
     /**
      * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
      */
@@ -226,6 +301,14 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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())) {
@@ -246,6 +329,16 @@ var HyperfrontendTimeUtils = (function (exports) {
      * @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);
@@ -253,17 +346,11 @@ var HyperfrontendTimeUtils = (function (exports) {
     }
 
     /**
-     * Safe copies of Promise built-in methods 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.
+     * Safe Promise factory and bound static methods.
      *
      * @module @hyperfrontend/immutable-api-utils/built-in-copy/promise
      */
-    // Capture references at module initialization time
+    /* eslint-disable workspace/lib-require-jsdoc-example */
     const _Promise = globalThis.Promise;
     const _Reflect = globalThis.Reflect;
     /**
@@ -310,6 +397,15 @@ var HyperfrontendTimeUtils = (function (exports) {
      *
      * @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));
@@ -324,4 +420,3 @@ var HyperfrontendTimeUtils = (function (exports) {
     return exports;
 
 })({});
-//# sourceMappingURL=index.iife.js.map

package/bundle/index.iife.min.js

@@ -1,2 +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}({});
-//# sourceMappingURL=index.iife.min.js.map