@bereasoftware/time-guard 2.6.0 → 2.7.0

package/dist/qwik/index.cjs

@@ -0,0 +1,104 @@
+/*! time-guard v2.7.0 | (c) 2026 Berea-Soft | MIT License | https://github.com/Berea-Soft/time-guard */
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_core = require("../core-CafqOI7W.cjs");
+let _builder_io_qwik = require("@builder.io/qwik");
+//#region src/qwik.ts
+/**
+* TimeGuard — Qwik Integration
+*
+* Provides reactive signal-based wrappers for TimeGuard using Qwik's
+* resumable reactivity model. All hooks use `useSignal` and
+* `useVisibleTask$` with automatic cleanup for optimal performance.
+*
+* @example
+* ```tsx
+* import { component$ } from '@builder.io/qwik';
+* import { useCurrentTime, useRelativeTime } from '@bereasoftware/time-guard/qwik';
+*
+* export default component$(() => {
+*   const now = useCurrentTime({ interval: 1000 });
+*   const relative = useRelativeTime('2026-05-20T08:00:00');
+*
+*   return (
+*     <div>
+*       <h1>{now.value.format('HH:mm:ss')}</h1>
+*       <p>Published: {relative.value}</p>
+*     </div>
+*   );
+* });
+* ```
+*/
+/**
+* Creates a Qwik Signal of a TimeGuard instance.
+* Uses `useTask$` to reactively update when input changes.
+* Must be called inside `component$`.
+*/
+function useTimeGuard(input, config) {
+	const tg = (0, _builder_io_qwik.useSignal)(require_core.TimeGuard.from(input, config));
+	(0, _builder_io_qwik.useTask$)(({ track }) => {
+		track(() => input);
+		tg.value = require_core.TimeGuard.from(input, config);
+	});
+	return tg;
+}
+/**
+* Creates a Qwik Signal of the current time that ticks on a specified
+* interval (default 1000ms). Uses `useVisibleTask$` for cleanup.
+* Must be called inside `component$`.
+*/
+function useCurrentTime(options) {
+	const interval = options?.interval ?? 1e3;
+	const config = options?.config;
+	const time = (0, _builder_io_qwik.useSignal)(require_core.TimeGuard.now(config));
+	(0, _builder_io_qwik.useVisibleTask$)(({ cleanup }) => {
+		const timer = setInterval(() => {
+			time.value = require_core.TimeGuard.now(config);
+		}, interval);
+		cleanup(() => clearInterval(timer));
+	});
+	return time;
+}
+/**
+* Creates a Qwik Signal of a relative time string that recalculates
+* periodically (default every 60s).
+* Must be called inside `component$`.
+*/
+function useRelativeTime(date, options) {
+	const interval = options?.interval ?? 6e4;
+	const locale = options?.locale;
+	const numeric = options?.numeric;
+	const compute = () => {
+		const tgDate = require_core.TimeGuard.from(date);
+		const now = require_core.TimeGuard.now();
+		return tgDate.since(now).humanize({
+			locale,
+			numeric
+		});
+	};
+	const relative = (0, _builder_io_qwik.useSignal)(compute());
+	(0, _builder_io_qwik.useVisibleTask$)(({ cleanup }) => {
+		const timer = setInterval(() => {
+			relative.value = compute();
+		}, interval);
+		cleanup(() => clearInterval(timer));
+	});
+	return relative;
+}
+/**
+* Creates a Qwik Signal of a TimeRange instance.
+* Must be called inside `component$`.
+*/
+function useTimeRange(start, end, config) {
+	const range = (0, _builder_io_qwik.useSignal)(new require_core.TimeRange(require_core.TimeGuard.from(start, config), require_core.TimeGuard.from(end, config)));
+	(0, _builder_io_qwik.useTask$)(({ track }) => {
+		track(() => start);
+		track(() => end);
+		range.value = new require_core.TimeRange(require_core.TimeGuard.from(start, config), require_core.TimeGuard.from(end, config));
+	});
+	return range;
+}
+//#endregion
+exports.useCurrentTime = useCurrentTime;
+exports.useRelativeTime = useRelativeTime;
+exports.useTimeGuard = useTimeGuard;
+exports.useTimeRange = useTimeRange;

package/dist/qwik/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../qwik'
+export {}

package/dist/qwik/index.es.js

@@ -0,0 +1,100 @@
+/*! time-guard v2.7.0 | (c) 2026 Berea-Soft | MIT License | https://github.com/Berea-Soft/time-guard */
+import { n as TimeGuard, r as TimeRange } from "../core-BAd7GYfw.js";
+import { useSignal, useTask$, useVisibleTask$ } from "@builder.io/qwik";
+//#region src/qwik.ts
+/**
+* TimeGuard — Qwik Integration
+*
+* Provides reactive signal-based wrappers for TimeGuard using Qwik's
+* resumable reactivity model. All hooks use `useSignal` and
+* `useVisibleTask$` with automatic cleanup for optimal performance.
+*
+* @example
+* ```tsx
+* import { component$ } from '@builder.io/qwik';
+* import { useCurrentTime, useRelativeTime } from '@bereasoftware/time-guard/qwik';
+*
+* export default component$(() => {
+*   const now = useCurrentTime({ interval: 1000 });
+*   const relative = useRelativeTime('2026-05-20T08:00:00');
+*
+*   return (
+*     <div>
+*       <h1>{now.value.format('HH:mm:ss')}</h1>
+*       <p>Published: {relative.value}</p>
+*     </div>
+*   );
+* });
+* ```
+*/
+/**
+* Creates a Qwik Signal of a TimeGuard instance.
+* Uses `useTask$` to reactively update when input changes.
+* Must be called inside `component$`.
+*/
+function useTimeGuard(input, config) {
+	const tg = useSignal(TimeGuard.from(input, config));
+	useTask$(({ track }) => {
+		track(() => input);
+		tg.value = TimeGuard.from(input, config);
+	});
+	return tg;
+}
+/**
+* Creates a Qwik Signal of the current time that ticks on a specified
+* interval (default 1000ms). Uses `useVisibleTask$` for cleanup.
+* Must be called inside `component$`.
+*/
+function useCurrentTime(options) {
+	const interval = options?.interval ?? 1e3;
+	const config = options?.config;
+	const time = useSignal(TimeGuard.now(config));
+	useVisibleTask$(({ cleanup }) => {
+		const timer = setInterval(() => {
+			time.value = TimeGuard.now(config);
+		}, interval);
+		cleanup(() => clearInterval(timer));
+	});
+	return time;
+}
+/**
+* Creates a Qwik Signal of a relative time string that recalculates
+* periodically (default every 60s).
+* Must be called inside `component$`.
+*/
+function useRelativeTime(date, options) {
+	const interval = options?.interval ?? 6e4;
+	const locale = options?.locale;
+	const numeric = options?.numeric;
+	const compute = () => {
+		const tgDate = TimeGuard.from(date);
+		const now = TimeGuard.now();
+		return tgDate.since(now).humanize({
+			locale,
+			numeric
+		});
+	};
+	const relative = useSignal(compute());
+	useVisibleTask$(({ cleanup }) => {
+		const timer = setInterval(() => {
+			relative.value = compute();
+		}, interval);
+		cleanup(() => clearInterval(timer));
+	});
+	return relative;
+}
+/**
+* Creates a Qwik Signal of a TimeRange instance.
+* Must be called inside `component$`.
+*/
+function useTimeRange(start, end, config) {
+	const range = useSignal(new TimeRange(TimeGuard.from(start, config), TimeGuard.from(end, config)));
+	useTask$(({ track }) => {
+		track(() => start);
+		track(() => end);
+		range.value = new TimeRange(TimeGuard.from(start, config), TimeGuard.from(end, config));
+	});
+	return range;
+}
+//#endregion
+export { useCurrentTime, useRelativeTime, useTimeGuard, useTimeRange };

package/dist/qwik.d.ts

@@ -0,0 +1,32 @@
+import { Signal } from '@builder.io/qwik';
+import { TimeGuard, ITimeGuardConfig, TimeRange } from './core';
+/**
+ * Creates a Qwik Signal of a TimeGuard instance.
+ * Uses `useTask$` to reactively update when input changes.
+ * Must be called inside `component$`.
+ */
+export declare function useTimeGuard(input?: unknown, config?: ITimeGuardConfig): Signal<TimeGuard>;
+/**
+ * Creates a Qwik Signal of the current time that ticks on a specified
+ * interval (default 1000ms). Uses `useVisibleTask$` for cleanup.
+ * Must be called inside `component$`.
+ */
+export declare function useCurrentTime(options?: {
+    interval?: number;
+    config?: ITimeGuardConfig;
+}): Signal<TimeGuard>;
+/**
+ * Creates a Qwik Signal of a relative time string that recalculates
+ * periodically (default every 60s).
+ * Must be called inside `component$`.
+ */
+export declare function useRelativeTime(date: unknown, options?: {
+    interval?: number;
+    locale?: string;
+    numeric?: 'always' | 'auto';
+}): Signal<string>;
+/**
+ * Creates a Qwik Signal of a TimeRange instance.
+ * Must be called inside `component$`.
+ */
+export declare function useTimeRange(start: unknown, end: unknown, config?: ITimeGuardConfig): Signal<TimeRange>;

package/dist/react/index.cjs

@@ -0,0 +1,112 @@
+/*! time-guard v2.7.0 | (c) 2026 Berea-Soft | MIT License | https://github.com/Berea-Soft/time-guard */
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("../chunk-Ddh6569R.cjs");
+const require_core = require("../core-CafqOI7W.cjs");
+let react = require("react");
+react = require_chunk.__toESM(react, 1);
+//#region src/react.ts
+/**
+* Context to share global TimeGuard configuration across the React component tree.
+*/
+var TimeGuardContext = (0, react.createContext)(void 0);
+/**
+* React Provider to define default/global TimeGuard configurations.
+*/
+function TimeGuardProvider({ children, config }) {
+	return react.default.createElement(TimeGuardContext.Provider, { value: config }, children);
+}
+/**
+* React Hook to safely retrieve the global TimeGuard configuration from Context.
+*/
+function useTimeGuardConfig() {
+	return (0, react.useContext)(TimeGuardContext);
+}
+/**
+* React Hook to create a reactive TimeGuard instance.
+* Automatically updates when input or configuration changes.
+* Integrates global context configuration as a fallback.
+*/
+function useTimeGuard(input, config) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = config ?? globalConfig;
+	const [tg, setTg] = (0, react.useState)(() => require_core.TimeGuard.from(input, activeConfig));
+	(0, react.useEffect)(() => {
+		setTg(require_core.TimeGuard.from(input, activeConfig));
+	}, [input, activeConfig ? JSON.stringify(activeConfig) : void 0]);
+	return tg;
+}
+/**
+* React Hook to get a reactive TimeGuard instance representing the current time.
+* Automatically updates on a specified interval (default: 1000ms).
+* Integrates global context configuration as a fallback.
+*/
+function useCurrentTime(options) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = options?.config ?? globalConfig;
+	const interval = options?.interval ?? 1e3;
+	const [time, setTime] = (0, react.useState)(() => require_core.TimeGuard.now(activeConfig));
+	(0, react.useEffect)(() => {
+		const timer = setInterval(() => {
+			setTime(require_core.TimeGuard.now(activeConfig));
+		}, interval);
+		return () => clearInterval(timer);
+	}, [interval, activeConfig ? JSON.stringify(activeConfig) : void 0]);
+	return time;
+}
+/**
+* React Hook that returns a dynamic relative time string that updates periodically.
+* Integrates global context configuration as a fallback.
+*/
+function useRelativeTime(date, options) {
+	const globalConfig = useTimeGuardConfig();
+	const interval = options?.interval ?? 6e4;
+	const locale = options?.locale ?? globalConfig?.locale;
+	const numeric = options?.numeric;
+	const [relative, setRelative] = (0, react.useState)("");
+	(0, react.useEffect)(() => {
+		const update = () => {
+			const tgDate = require_core.TimeGuard.from(date);
+			const now = require_core.TimeGuard.now();
+			setRelative(tgDate.since(now).humanize({
+				locale,
+				numeric
+			}));
+		};
+		update();
+		const timer = setInterval(update, interval);
+		return () => clearInterval(timer);
+	}, [
+		date,
+		interval,
+		locale,
+		numeric
+	]);
+	return relative;
+}
+/**
+* React Hook to create and manage reactive TimeRange instances.
+* Automatically updates when start, end, or configuration changes.
+*/
+function useTimeRange(start, end, config) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = config ?? globalConfig;
+	const [range, setRange] = (0, react.useState)(() => {
+		return new require_core.TimeRange(require_core.TimeGuard.from(start, activeConfig), require_core.TimeGuard.from(end, activeConfig));
+	});
+	(0, react.useEffect)(() => {
+		setRange(new require_core.TimeRange(require_core.TimeGuard.from(start, activeConfig), require_core.TimeGuard.from(end, activeConfig)));
+	}, [
+		start,
+		end,
+		activeConfig ? JSON.stringify(activeConfig) : void 0
+	]);
+	return range;
+}
+//#endregion
+exports.TimeGuardContext = TimeGuardContext;
+exports.TimeGuardProvider = TimeGuardProvider;
+exports.useCurrentTime = useCurrentTime;
+exports.useRelativeTime = useRelativeTime;
+exports.useTimeGuard = useTimeGuard;
+exports.useTimeGuardConfig = useTimeGuardConfig;
+exports.useTimeRange = useTimeRange;

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../react'
+export {}

package/dist/react/index.es.js

@@ -0,0 +1,103 @@
+/*! time-guard v2.7.0 | (c) 2026 Berea-Soft | MIT License | https://github.com/Berea-Soft/time-guard */
+import { n as TimeGuard, r as TimeRange } from "../core-BAd7GYfw.js";
+import React, { createContext, useContext, useEffect, useState } from "react";
+//#region src/react.ts
+/**
+* Context to share global TimeGuard configuration across the React component tree.
+*/
+var TimeGuardContext = createContext(void 0);
+/**
+* React Provider to define default/global TimeGuard configurations.
+*/
+function TimeGuardProvider({ children, config }) {
+	return React.createElement(TimeGuardContext.Provider, { value: config }, children);
+}
+/**
+* React Hook to safely retrieve the global TimeGuard configuration from Context.
+*/
+function useTimeGuardConfig() {
+	return useContext(TimeGuardContext);
+}
+/**
+* React Hook to create a reactive TimeGuard instance.
+* Automatically updates when input or configuration changes.
+* Integrates global context configuration as a fallback.
+*/
+function useTimeGuard(input, config) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = config ?? globalConfig;
+	const [tg, setTg] = useState(() => TimeGuard.from(input, activeConfig));
+	useEffect(() => {
+		setTg(TimeGuard.from(input, activeConfig));
+	}, [input, activeConfig ? JSON.stringify(activeConfig) : void 0]);
+	return tg;
+}
+/**
+* React Hook to get a reactive TimeGuard instance representing the current time.
+* Automatically updates on a specified interval (default: 1000ms).
+* Integrates global context configuration as a fallback.
+*/
+function useCurrentTime(options) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = options?.config ?? globalConfig;
+	const interval = options?.interval ?? 1e3;
+	const [time, setTime] = useState(() => TimeGuard.now(activeConfig));
+	useEffect(() => {
+		const timer = setInterval(() => {
+			setTime(TimeGuard.now(activeConfig));
+		}, interval);
+		return () => clearInterval(timer);
+	}, [interval, activeConfig ? JSON.stringify(activeConfig) : void 0]);
+	return time;
+}
+/**
+* React Hook that returns a dynamic relative time string that updates periodically.
+* Integrates global context configuration as a fallback.
+*/
+function useRelativeTime(date, options) {
+	const globalConfig = useTimeGuardConfig();
+	const interval = options?.interval ?? 6e4;
+	const locale = options?.locale ?? globalConfig?.locale;
+	const numeric = options?.numeric;
+	const [relative, setRelative] = useState("");
+	useEffect(() => {
+		const update = () => {
+			const tgDate = TimeGuard.from(date);
+			const now = TimeGuard.now();
+			setRelative(tgDate.since(now).humanize({
+				locale,
+				numeric
+			}));
+		};
+		update();
+		const timer = setInterval(update, interval);
+		return () => clearInterval(timer);
+	}, [
+		date,
+		interval,
+		locale,
+		numeric
+	]);
+	return relative;
+}
+/**
+* React Hook to create and manage reactive TimeRange instances.
+* Automatically updates when start, end, or configuration changes.
+*/
+function useTimeRange(start, end, config) {
+	const globalConfig = useTimeGuardConfig();
+	const activeConfig = config ?? globalConfig;
+	const [range, setRange] = useState(() => {
+		return new TimeRange(TimeGuard.from(start, activeConfig), TimeGuard.from(end, activeConfig));
+	});
+	useEffect(() => {
+		setRange(new TimeRange(TimeGuard.from(start, activeConfig), TimeGuard.from(end, activeConfig)));
+	}, [
+		start,
+		end,
+		activeConfig ? JSON.stringify(activeConfig) : void 0
+	]);
+	return range;
+}
+//#endregion
+export { TimeGuardContext, TimeGuardProvider, useCurrentTime, useRelativeTime, useTimeGuard, useTimeGuardConfig, useTimeRange };

package/dist/react.d.ts

@@ -0,0 +1,46 @@
+import { default as React, ReactNode } from 'react';
+import { TimeGuard, ITimeGuardConfig, TimeRange } from './core';
+/**
+ * Context to share global TimeGuard configuration across the React component tree.
+ */
+export declare const TimeGuardContext: React.Context<ITimeGuardConfig | undefined>;
+/**
+ * React Provider to define default/global TimeGuard configurations.
+ */
+export declare function TimeGuardProvider({ children, config, }: {
+    children: ReactNode;
+    config?: ITimeGuardConfig;
+}): React.FunctionComponentElement<React.ProviderProps<ITimeGuardConfig | undefined>>;
+/**
+ * React Hook to safely retrieve the global TimeGuard configuration from Context.
+ */
+export declare function useTimeGuardConfig(): ITimeGuardConfig | undefined;
+/**
+ * React Hook to create a reactive TimeGuard instance.
+ * Automatically updates when input or configuration changes.
+ * Integrates global context configuration as a fallback.
+ */
+export declare function useTimeGuard(input?: unknown, config?: ITimeGuardConfig): TimeGuard;
+/**
+ * React Hook to get a reactive TimeGuard instance representing the current time.
+ * Automatically updates on a specified interval (default: 1000ms).
+ * Integrates global context configuration as a fallback.
+ */
+export declare function useCurrentTime(options?: {
+    interval?: number;
+    config?: ITimeGuardConfig;
+}): TimeGuard;
+/**
+ * React Hook that returns a dynamic relative time string that updates periodically.
+ * Integrates global context configuration as a fallback.
+ */
+export declare function useRelativeTime(date: unknown, options?: {
+    interval?: number;
+    locale?: string;
+    numeric?: 'always' | 'auto';
+}): string;
+/**
+ * React Hook to create and manage reactive TimeRange instances.
+ * Automatically updates when start, end, or configuration changes.
+ */
+export declare function useTimeRange(start: unknown, end: unknown, config?: ITimeGuardConfig): TimeRange;

package/dist/solid/index.cjs

@@ -0,0 +1,127 @@
+/*! time-guard v2.7.0 | (c) 2026 Berea-Soft | MIT License | https://github.com/Berea-Soft/time-guard */
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_core = require("../core-CafqOI7W.cjs");
+let solid_js = require("solid-js");
+//#region src/solid.ts
+/**
+* TimeGuard — SolidJS Integration
+*
+* Provides reactive signal-based wrappers for TimeGuard using Solid's
+* fine-grained reactivity system. All hooks return signals (`Accessor`)
+* that automatically update without re-rendering the entire component tree.
+*
+* @example
+* ```tsx
+* import { useCurrentTime, useRelativeTime } from '@bereasoftware/time-guard/solid';
+*
+* function Clock() {
+*   const now = useCurrentTime({ interval: 1000 });
+*   const relative = useRelativeTime('2026-05-20T08:00:00');
+*
+*   return (
+*     <div>
+*       <h1>{now().format('HH:mm:ss')}</h1>
+*       <p>Published: {relative()}</p>
+*     </div>
+*   );
+* }
+* ```
+*/
+/**
+* Context key for providing global TimeGuard configuration.
+* Use Solid's `createContext` + `useContext` at the app level.
+*/
+var TimeGuardConfigContext = Symbol("TimeGuardConfig");
+/**
+* Creates a reactive signal of a TimeGuard instance.
+* The signal updates reactively when `input` changes.
+*
+* ```tsx
+* const tg = useTimeGuard('2026-05-20');
+* return <p>{tg().format('dddd, DD MMMM YYYY')}</p>;
+* ```
+*/
+function useTimeGuard(input, config) {
+	const [tg, setTg] = (0, solid_js.createSignal)(require_core.TimeGuard.from(input, config));
+	(0, solid_js.createEffect)(() => {
+		const _input = input;
+		setTg(() => require_core.TimeGuard.from(_input, config));
+	});
+	return tg;
+}
+/**
+* Creates a signal of the current time that ticks on a specified interval
+* (default 1000ms). Clears the interval on cleanup.
+*
+* ```tsx
+* const now = useCurrentTime({ interval: 1000 });
+* return <p>{now().format('HH:mm:ss')}</p>;
+* ```
+*/
+function useCurrentTime(options) {
+	const interval = options?.interval ?? 1e3;
+	const config = options?.config;
+	const [time, setTime] = (0, solid_js.createSignal)(require_core.TimeGuard.now(config));
+	const timer = setInterval(() => {
+		setTime(require_core.TimeGuard.now(config));
+	}, interval);
+	(0, solid_js.onCleanup)(() => {
+		clearInterval(timer);
+	});
+	return time;
+}
+/**
+* Creates a signal of a relative time string that recalculates periodically
+* (default every 60s).
+*
+* ```tsx
+* const relative = useRelativeTime('2026-05-20T08:00:00', { locale: 'es' });
+* return <p>{relative()}</p>;
+* ```
+*/
+function useRelativeTime(date, options) {
+	const interval = options?.interval ?? 6e4;
+	const locale = options?.locale;
+	const numeric = options?.numeric;
+	const compute = () => {
+		const tgDate = require_core.TimeGuard.from(date);
+		const now = require_core.TimeGuard.now();
+		return tgDate.since(now).humanize({
+			locale,
+			numeric
+		});
+	};
+	const [relative, setRelative] = (0, solid_js.createSignal)(compute());
+	const timer = setInterval(() => {
+		setRelative(compute());
+	}, interval);
+	(0, solid_js.onCleanup)(() => {
+		clearInterval(timer);
+	});
+	return relative;
+}
+/**
+* Creates a signal of a TimeRange instance.
+*
+* ```tsx
+* const range = useTimeRange('2026-05-20', '2026-06-01');
+* return <p>Duration: {range().humanize()}</p>;
+* ```
+*/
+function useTimeRange(start, end, config) {
+	const [range, setRange] = (0, solid_js.createSignal)(new require_core.TimeRange(require_core.TimeGuard.from(start, config), require_core.TimeGuard.from(end, config)));
+	(0, solid_js.createEffect)(() => {
+		const _start = start;
+		const _end = end;
+		const startTg = require_core.TimeGuard.from(_start, config);
+		const endTg = require_core.TimeGuard.from(_end, config);
+		setRange(() => new require_core.TimeRange(startTg, endTg));
+	});
+	return range;
+}
+//#endregion
+exports.TimeGuardConfigContext = TimeGuardConfigContext;
+exports.useCurrentTime = useCurrentTime;
+exports.useRelativeTime = useRelativeTime;
+exports.useTimeGuard = useTimeGuard;
+exports.useTimeRange = useTimeRange;

package/dist/solid/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../solid'
+export {}