@bereasoftware/time-guard 2.6.0 → 2.7.0

package/dist/svelte/index.es.js

@@ -0,0 +1,393 @@
+/*! 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";
+Array.isArray;
+Array.prototype.indexOf;
+Array.prototype.includes;
+Array.from;
+Array.prototype;
+var noop = () => {};
+/** @param {Array<() => void>} arr */
+function run_all(arr) {
+	for (var i = 0; i < arr.length; i++) arr[i]();
+}
+//#endregion
+//#region node_modules/.pnpm/svelte@5.55.9_@typescript-eslint+types@8.59.4/node_modules/svelte/src/internal/client/constants.js
+var CLEAN = 1024;
+var DIRTY = 2048;
+var MAYBE_DIRTY = 4096;
+/**
+* 'Transparent' effects do not create a transition boundary.
+* This is on a block effect 99% of the time but may also be on a branch effect if its parent block effect was pruned
+*/
+var EFFECT_TRANSPARENT = 65536;
+var EFFECT_PRESERVED = 1 << 19;
+new class StaleReactionError extends Error {
+	name = "StaleReactionError";
+	message = "The reaction that called `getAbortSignal()` was re-run or destroyed";
+}();
+globalThis.document?.contentType;
+//#endregion
+//#region node_modules/.pnpm/svelte@5.55.9_@typescript-eslint+types@8.59.4/node_modules/svelte/src/internal/client/reactivity/equality.js
+/**
+* @param {unknown} a
+* @param {unknown} b
+* @returns {boolean}
+*/
+function safe_not_equal(a, b) {
+	return a != a ? b == b : a !== b || a !== null && typeof a === "object" || typeof a === "function";
+}
+~(DIRTY | MAYBE_DIRTY | CLEAN);
+//#endregion
+//#region node_modules/.pnpm/svelte@5.55.9_@typescript-eslint+types@8.59.4/node_modules/svelte/src/store/utils.js
+/** @import { Readable } from './public' */
+/**
+* @template T
+* @param {Readable<T> | null | undefined} store
+* @param {(value: T) => void} run
+* @param {(value: T) => void} [invalidate]
+* @returns {() => void}
+*/
+function subscribe_to_store(store, run, invalidate) {
+	if (store == null) {
+		run(void 0);
+		if (invalidate) invalidate(void 0);
+		return noop;
+	}
+	const unsub = untrack(() => store.subscribe(run, invalidate));
+	return unsub.unsubscribe ? () => unsub.unsubscribe() : unsub;
+}
+//#endregion
+//#region node_modules/.pnpm/svelte@5.55.9_@typescript-eslint+types@8.59.4/node_modules/svelte/src/store/shared/index.js
+/** @import { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable } from '../public.js' */
+/** @import { Stores, StoresValues, SubscribeInvalidateTuple } from '../private.js' */
+/**
+* @type {Array<SubscribeInvalidateTuple<any> | any>}
+*/
+var subscriber_queue = [];
+/**
+* Creates a `Readable` store that allows reading by subscription.
+*
+* @template T
+* @param {T} [value] initial value
+* @param {StartStopNotifier<T>} [start]
+* @returns {Readable<T>}
+*/
+function readable(value, start) {
+	return { subscribe: writable(value, start).subscribe };
+}
+/**
+* Create a `Writable` store that allows both updating and reading by subscription.
+*
+* @template T
+* @param {T} [value] initial value
+* @param {StartStopNotifier<T>} [start]
+* @returns {Writable<T>}
+*/
+function writable(value, start = noop) {
+	/** @type {Unsubscriber | null} */
+	let stop = null;
+	/** @type {Set<SubscribeInvalidateTuple<T>>} */
+	const subscribers = /* @__PURE__ */ new Set();
+	/**
+	* @param {T} new_value
+	* @returns {void}
+	*/
+	function set(new_value) {
+		if (safe_not_equal(value, new_value)) {
+			value = new_value;
+			if (stop) {
+				const run_queue = !subscriber_queue.length;
+				for (const subscriber of subscribers) {
+					subscriber[1]();
+					subscriber_queue.push(subscriber, value);
+				}
+				if (run_queue) {
+					for (let i = 0; i < subscriber_queue.length; i += 2) subscriber_queue[i][0](subscriber_queue[i + 1]);
+					subscriber_queue.length = 0;
+				}
+			}
+		}
+	}
+	/**
+	* @param {Updater<T>} fn
+	* @returns {void}
+	*/
+	function update(fn) {
+		set(fn(value));
+	}
+	/**
+	* @param {Subscriber<T>} run
+	* @param {() => void} [invalidate]
+	* @returns {Unsubscriber}
+	*/
+	function subscribe(run, invalidate = noop) {
+		/** @type {SubscribeInvalidateTuple<T>} */
+		const subscriber = [run, invalidate];
+		subscribers.add(subscriber);
+		if (subscribers.size === 1) stop = start(set, update) || noop;
+		run(value);
+		return () => {
+			subscribers.delete(subscriber);
+			if (subscribers.size === 0 && stop) {
+				stop();
+				stop = null;
+			}
+		};
+	}
+	return {
+		set,
+		update,
+		subscribe
+	};
+}
+/**
+* Derived value store by synchronizing one or more readable stores and
+* applying an aggregation function over its input values.
+*
+* @template {Stores} S
+* @template T
+* @overload
+* @param {S} stores
+* @param {(values: StoresValues<S>, set: (value: T) => void, update: (fn: Updater<T>) => void) => Unsubscriber | void} fn
+* @param {T} [initial_value]
+* @returns {Readable<T>}
+*/
+/**
+* Derived value store by synchronizing one or more readable stores and
+* applying an aggregation function over its input values.
+*
+* @template {Stores} S
+* @template T
+* @overload
+* @param {S} stores
+* @param {(values: StoresValues<S>) => T} fn
+* @param {T} [initial_value]
+* @returns {Readable<T>}
+*/
+/**
+* @template {Stores} S
+* @template T
+* @param {S} stores
+* @param {Function} fn
+* @param {T} [initial_value]
+* @returns {Readable<T>}
+*/
+function derived(stores, fn, initial_value) {
+	const single = !Array.isArray(stores);
+	/** @type {Array<Readable<any>>} */
+	const stores_array = single ? [stores] : stores;
+	if (!stores_array.every(Boolean)) throw new Error("derived() expects stores as input, got a falsy value");
+	const auto = fn.length < 2;
+	return readable(initial_value, (set, update) => {
+		let started = false;
+		/** @type {T[]} */
+		const values = [];
+		let pending = 0;
+		let cleanup = noop;
+		const sync = () => {
+			if (pending) return;
+			cleanup();
+			const result = fn(single ? values[0] : values, set, update);
+			if (auto) set(result);
+			else cleanup = typeof result === "function" ? result : noop;
+		};
+		const unsubscribers = stores_array.map((store, i) => subscribe_to_store(store, (value) => {
+			values[i] = value;
+			pending &= ~(1 << i);
+			if (started) sync();
+		}, () => {
+			pending |= 1 << i;
+		}));
+		started = true;
+		sync();
+		return function stop() {
+			run_all(unsubscribers);
+			cleanup();
+			started = false;
+		};
+	});
+}
+EFFECT_TRANSPARENT | EFFECT_PRESERVED;
+//#endregion
+//#region node_modules/.pnpm/svelte@5.55.9_@typescript-eslint+types@8.59.4/node_modules/svelte/src/internal/client/runtime.js
+var untracking = false;
+/**
+* When used inside a [`$derived`](https://svelte.dev/docs/svelte/$derived) or [`$effect`](https://svelte.dev/docs/svelte/$effect),
+* any state read inside `fn` will not be treated as a dependency.
+*
+* ```ts
+* $effect(() => {
+*   // this will run when `data` changes, but not when `time` changes
+*   save(data, {
+*     timestamp: untrack(() => time)
+*   });
+* });
+* ```
+* @template T
+* @param {() => T} fn
+* @returns {T}
+*/
+function untrack(fn) {
+	var previous_untracking = untracking;
+	try {
+		untracking = true;
+		return fn();
+	} finally {
+		untracking = previous_untracking;
+	}
+}
+//#endregion
+//#region src/svelte.ts
+/**
+* TimeGuard — Svelte 5 Integration
+*
+* Provides reactive stores and lifecycle-managed wrappers for TimeGuard.
+* Compatible with both Svelte 4 (`$store` auto-subscription) and
+* Svelte 5 (`$state` + `get()` from stores).
+*
+* @example
+* ```svelte
+* <script lang="ts">
+*   import { useCurrentTime, useRelativeTime } from '@bereasoftware/time-guard/svelte';
+*
+*   const now = useCurrentTime({ interval: 1000 });
+*   const relative = useRelativeTime('2026-05-20T08:00:00');
+* <\/script>
+*
+* <h1>{$now.format('HH:mm:ss')}</h1>
+* <p>Published: {$relative}</p>
+* ```
+*/
+/**
+* Duck-type check: is this a Svelte store (has `subscribe`)?
+*/
+function isStore(val) {
+	return typeof val === "object" && val !== null && "subscribe" in val && typeof val.subscribe === "function";
+}
+/**
+* Coerce a plain value or a store into a Readable store.
+*/
+function toStore(val) {
+	return isStore(val) ? val : readable(val);
+}
+/**
+* Injection-key symbol to retrieve a global TimeGuard configuration
+* provided at the app root. Consumers use `getContext(TimeGuardConfigKey)`.
+*/
+var TimeGuardConfigKey = Symbol("TimeGuardConfig");
+/**
+* Creates a reactive readable store of a TimeGuard instance.
+* Automatically updates when `input` changes (supports both plain values
+* and Svelte stores as input — pass a `Readable` for full reactivity).
+* Integrates global config from `getContext(TimeGuardConfigKey)` as fallback.
+*
+* ```svelte
+* <script>
+*   import { writable } from 'svelte/store';
+*   import { useTimeGuard } from '@bereasoftware/time-guard/svelte';
+*   import { TimeGuard } from '@bereasoftware/time-guard';
+*
+*   // Static input — no reactivity needed
+*   const tg = useTimeGuard('2026-05-20');
+*
+*   // Reactive input — pass a store
+*   const dateStore = writable('2026-05-20');
+*   const tg2 = useTimeGuard(dateStore);
+* <\/script>
+*
+* <p>{$tg.format('dddd, DD MMMM YYYY')}</p>
+* <p>{$tg2.format('dddd, DD MMMM YYYY')}</p>
+* ```
+*/
+function useTimeGuard(input, config) {
+	if (isStore(input)) return derived(input, ($val) => TimeGuard.from($val, config));
+	return readable(TimeGuard.from(input, config));
+}
+/**
+* Creates a readable store of the current time that ticks on a specified
+* interval (default 1000ms). Automatically clears the interval on
+* component destroy.
+*
+* ```svelte
+* <script>
+*   import { useCurrentTime } from '@bereasoftware/time-guard/svelte';
+*   const now = useCurrentTime({ interval: 1000 });
+* <\/script>
+* <p>{$now.format('HH:mm:ss')}</p>
+* ```
+*/
+function useCurrentTime(options) {
+	const interval = options?.interval ?? 1e3;
+	const config = options?.config;
+	const store = writable(TimeGuard.now(config), () => {
+		const timer = setInterval(() => {
+			store.set(TimeGuard.now(config));
+		}, interval);
+		return () => {
+			clearInterval(timer);
+		};
+	});
+	return { subscribe: store.subscribe };
+}
+/**
+* Creates a readable store of a relative time string that recalculates
+* periodically (default every 60s).
+*
+* ```svelte
+* <script>
+*   import { useRelativeTime } from '@bereasoftware/time-guard/svelte';
+*   const relative = useRelativeTime('2026-05-20T08:00:00', { locale: 'es' });
+* <\/script>
+* <p>{$relative}</p>
+* ```
+*/
+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 store = writable(compute(), () => {
+		const timer = setInterval(() => {
+			store.set(compute());
+		}, interval);
+		return () => {
+			clearInterval(timer);
+		};
+	});
+	return { subscribe: store.subscribe };
+}
+/**
+* Creates a readable store of a TimeRange instance.
+* Recalculates reactively when `start` or `end` change (supports both
+* plain values and Svelte stores).
+*
+* ```svelte
+* <script>
+*   import { writable } from 'svelte/store';
+*   import { useTimeRange } from '@bereasoftware/time-guard/svelte';
+*
+*   // Static range
+*   const range = useTimeRange('2026-05-20', '2026-06-01');
+*
+*   // Reactive range
+*   const start = writable('2026-05-20');
+*   const end = writable('2026-06-01');
+*   const range2 = useTimeRange(start, end);
+* <\/script>
+*
+* <p>Duration: {$range.toDuration().humanize()}</p>
+*/
+function useTimeRange(start, end, config) {
+	return derived([toStore(start), toStore(end)], ([$start, $end]) => {
+		return new TimeRange(TimeGuard.from($start, config), TimeGuard.from($end, config));
+	});
+}
+//#endregion
+export { TimeGuardConfigKey, useCurrentTime, useRelativeTime, useTimeGuard, useTimeRange };

package/dist/svelte.d.ts

@@ -0,0 +1,88 @@
+import { Readable } from 'svelte/store';
+import { TimeGuard, ITimeGuardConfig, TimeRange } from './core';
+/**
+ * Injection-key symbol to retrieve a global TimeGuard configuration
+ * provided at the app root. Consumers use `getContext(TimeGuardConfigKey)`.
+ */
+export declare const TimeGuardConfigKey: unique symbol;
+/**
+ * Creates a reactive readable store of a TimeGuard instance.
+ * Automatically updates when `input` changes (supports both plain values
+ * and Svelte stores as input — pass a `Readable` for full reactivity).
+ * Integrates global config from `getContext(TimeGuardConfigKey)` as fallback.
+ *
+ * ```svelte
+ * <script>
+ *   import { writable } from 'svelte/store';
+ *   import { useTimeGuard } from '@bereasoftware/time-guard/svelte';
+ *   import { TimeGuard } from '@bereasoftware/time-guard';
+ *
+ *   // Static input — no reactivity needed
+ *   const tg = useTimeGuard('2026-05-20');
+ *
+ *   // Reactive input — pass a store
+ *   const dateStore = writable('2026-05-20');
+ *   const tg2 = useTimeGuard(dateStore);
+ * </script>
+ *
+ * <p>{$tg.format('dddd, DD MMMM YYYY')}</p>
+ * <p>{$tg2.format('dddd, DD MMMM YYYY')}</p>
+ * ```
+ */
+export declare function useTimeGuard(input?: unknown | Readable<unknown>, config?: ITimeGuardConfig): Readable<TimeGuard>;
+/**
+ * Creates a readable store of the current time that ticks on a specified
+ * interval (default 1000ms). Automatically clears the interval on
+ * component destroy.
+ *
+ * ```svelte
+ * <script>
+ *   import { useCurrentTime } from '@bereasoftware/time-guard/svelte';
+ *   const now = useCurrentTime({ interval: 1000 });
+ * </script>
+ * <p>{$now.format('HH:mm:ss')}</p>
+ * ```
+ */
+export declare function useCurrentTime(options?: {
+    interval?: number;
+    config?: ITimeGuardConfig;
+}): Readable<TimeGuard>;
+/**
+ * Creates a readable store of a relative time string that recalculates
+ * periodically (default every 60s).
+ *
+ * ```svelte
+ * <script>
+ *   import { useRelativeTime } from '@bereasoftware/time-guard/svelte';
+ *   const relative = useRelativeTime('2026-05-20T08:00:00', { locale: 'es' });
+ * </script>
+ * <p>{$relative}</p>
+ * ```
+ */
+export declare function useRelativeTime(date: unknown, options?: {
+    interval?: number;
+    locale?: string;
+    numeric?: 'always' | 'auto';
+}): Readable<string>;
+/**
+ * Creates a readable store of a TimeRange instance.
+ * Recalculates reactively when `start` or `end` change (supports both
+ * plain values and Svelte stores).
+ *
+ * ```svelte
+ * <script>
+ *   import { writable } from 'svelte/store';
+ *   import { useTimeRange } from '@bereasoftware/time-guard/svelte';
+ *
+ *   // Static range
+ *   const range = useTimeRange('2026-05-20', '2026-06-01');
+ *
+ *   // Reactive range
+ *   const start = writable('2026-05-20');
+ *   const end = writable('2026-06-01');
+ *   const range2 = useTimeRange(start, end);
+ * </script>
+ *
+ * <p>Duration: {$range.toDuration().humanize()}</p>
+ */
+export declare function useTimeRange(start: unknown | Readable<unknown>, end: unknown | Readable<unknown>, config?: ITimeGuardConfig): Readable<TimeRange>;