@askrjs/askr 0.0.52 → 0.0.53

package/dist/fx/index.d.ts

@@ -1,4 +1,191 @@
-import { scheduleEventHandler } from "../runtime/scheduler.js";
-import { DebounceOptions, RetryOptions, ThrottleOptions, debounce, defer, idle, once, raf, retry, throttle, timeout } from "./timing.js";
-import { debounceEvent, rafEvent, scheduleIdle, scheduleRetry, scheduleTimeout, throttleEvent } from "./fx.js";
+import { n as scheduleEventHandler } from "../scheduler-CmLO4Dfm.js";
+
+//#region src/fx/timing.d.ts
+/**
+ * Timing utilities — pure helpers for common async patterns
+ * No framework coupling. No lifecycle awareness.
+ */
+interface DebounceOptions {
+  leading?: boolean;
+  trailing?: boolean;
+}
+interface ThrottleOptions {
+  leading?: boolean;
+  trailing?: boolean;
+}
+interface RetryOptions {
+  maxAttempts?: number;
+  delayMs?: number;
+  backoff?: (attemptIndex: number) => number;
+}
+type AnyFn = (...args: never[]) => unknown;
+/**
+ * Debounce — delay execution, coalesce rapid calls
+ *
+ * Useful for: text input, resize, autosave
+ *
+ * @param fn Function to debounce
+ * @param ms Delay in milliseconds
+ * @param options trailing (default true), leading
+ * @returns Debounced function with cancel() method
+ *
+ * @example
+ * ```ts
+ * const save = debounce((text) => api.save(text), 500);
+ * input.addEventListener('input', (e) => save(e.target.value));
+ * save.cancel(); // stop any pending execution
+ * ```
+ */
+declare function debounce<T extends AnyFn>(fn: T, ms: number, options?: DebounceOptions): T & {
+  cancel(): void;
+};
+/**
+ * Throttle — rate-limit execution, keep first/last
+ *
+ * Useful for: scroll, mouse move, high-frequency events
+ *
+ * @param fn Function to throttle
+ * @param ms Minimum interval between calls in milliseconds
+ * @param options leading (default true), trailing (default true)
+ * @returns Throttled function with cancel() method
+ *
+ * @example
+ * ```ts
+ * const handleScroll = throttle(updateUI, 100);
+ * window.addEventListener('scroll', handleScroll);
+ * handleScroll.cancel();
+ * ```
+ */
+declare function throttle<T extends AnyFn>(fn: T, ms: number, options?: ThrottleOptions): T & {
+  cancel(): void;
+};
+/**
+ * Once — guard against double execution
+ *
+ * Useful for: init logic, event safety
+ *
+ * @param fn Function to call at most once
+ * @returns Function that executes fn only on first call
+ *
+ * @example
+ * ```ts
+ * const init = once(setup);
+ * init(); // runs
+ * init(); // does nothing
+ * init(); // does nothing
+ * ```
+ */
+declare function once<T extends AnyFn>(fn: T): T;
+/**
+ * Defer — schedule on microtask queue
+ *
+ * Useful for: run-after-current-stack logic
+ * More reliable than setTimeout(..., 0)
+ *
+ * @param fn Function to defer
+ *
+ * @example
+ * ```ts
+ * defer(() => update()); // runs after current stack, before next macrotask
+ * ```
+ */
+declare function defer(fn: () => void): void;
+/**
+ * RAF — coalesce multiple updates into single frame
+ *
+ * Useful for: animation, layout work, render updates
+ *
+ * @param fn Function to schedule on next animation frame
+ * @returns Function that schedules fn on requestAnimationFrame
+ *
+ * @example
+ * ```ts
+ * const update = raf(render);
+ * update(); // schedules on next frame
+ * update(); // same frame, no duplicate
+ * ```
+ */
+declare function raf<T extends AnyFn>(fn: T): T;
+/**
+ * Idle — schedule low-priority work
+ *
+ * Useful for: background prep, non-urgent updates
+ * Falls back to setTimeout if requestIdleCallback unavailable
+ *
+ * @param fn Function to call when idle
+ * @param options timeout for fallback
+ *
+ * @example
+ * ```ts
+ * idle(() => prefetchData());
+ * ```
+ */
+declare function idle(fn: () => void, options?: {
+  timeout?: number;
+}): void;
+/**
+ * Timeout — Promise-based delay
+ *
+ * Useful for: readable async code, waiting between retries
+ *
+ * @param ms Milliseconds to wait
+ * @returns Promise that resolves after delay
+ *
+ * @example
+ * ```ts
+ * await timeout(300);
+ * console.log('300ms later');
+ * ```
+ */
+declare function timeout(ms: number): Promise<void>;
+/**
+ * Retry — attempt function with backoff
+ *
+ * Useful for: network calls, transient failures
+ *
+ * @param fn Async function to retry
+ * @param options maxAttempts, delayMs, backoff function
+ * @returns Promise with final result or error
+ *
+ * @example
+ * ```ts
+ * const data = await retry(() => fetch(url), {
+ *   maxAttempts: 3,
+ *   delayMs: 100,
+ * });
+ * ```
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//#endregion
+//#region src/fx/fx.d.ts
+type CancelFn = () => void;
+declare function debounceEvent(ms: number, handler: EventListener, options?: {
+  leading?: boolean;
+  trailing?: boolean;
+}): EventListener & {
+  cancel(): void;
+  flush(): void;
+};
+declare function throttleEvent(ms: number, handler: EventListener, options?: {
+  leading?: boolean;
+  trailing?: boolean;
+}): EventListener & {
+  cancel(): void;
+};
+declare function rafEvent(handler: EventListener): EventListener & {
+  cancel(): void;
+};
+declare function scheduleTimeout(ms: number, fn: () => void): CancelFn;
+declare function scheduleIdle(fn: () => void, options?: {
+  timeout?: number;
+}): CancelFn;
+interface RetryOptions$1 {
+  maxAttempts?: number;
+  delayMs?: number;
+  backoff?: (attemptIndex: number) => number;
+}
+declare function scheduleRetry<T>(fn: () => Promise<T>, options?: RetryOptions$1): {
+  cancel(): void;
+};
+//#endregion
 export { type DebounceOptions, type RetryOptions, type ThrottleOptions, debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };

package/dist/fx/index.js

@@ -1,5 +1,455 @@
-import { scheduleEventHandler } from "../runtime/scheduler.js";
-import "../runtime/index.js";
-import { debounce, defer, idle, once, raf, retry, throttle, timeout } from "./timing.js";
-import { debounceEvent, rafEvent, scheduleIdle, scheduleRetry, scheduleTimeout, throttleEvent } from "./fx.js";
+import { h as scheduleEventHandler, n as enqueueRuntimeTask, v as logger } from "../access-Bg4RJNC8.js";
+import { f as getCurrentComponentInstance } from "../component-scope-CC3cojX9.js";
+//#region src/fx/timing.ts
+/**
+* Debounce — delay execution, coalesce rapid calls
+*
+* Useful for: text input, resize, autosave
+*
+* @param fn Function to debounce
+* @param ms Delay in milliseconds
+* @param options trailing (default true), leading
+* @returns Debounced function with cancel() method
+*
+* @example
+* ```ts
+* const save = debounce((text) => api.save(text), 500);
+* input.addEventListener('input', (e) => save(e.target.value));
+* save.cancel(); // stop any pending execution
+* ```
+*/
+function debounce(fn, ms, options) {
+	const callable = fn;
+	let timeoutId = null;
+	const { leading = false, trailing = true } = options || {};
+	let lastArgs = null;
+	let lastThis = null;
+	let lastCallTime = 0;
+	const debounced = function(...args) {
+		const callTime = Date.now();
+		lastArgs = args;
+		lastThis = this;
+		if (timeoutId !== null) clearTimeout(timeoutId);
+		if (leading && callTime - lastCallTime >= ms) {
+			callable.apply(this, args);
+			lastCallTime = callTime;
+		}
+		if (trailing) timeoutId = setTimeout(() => {
+			callable.apply(lastThis, lastArgs);
+			timeoutId = null;
+			lastCallTime = Date.now();
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return debounced;
+}
+/**
+* Throttle — rate-limit execution, keep first/last
+*
+* Useful for: scroll, mouse move, high-frequency events
+*
+* @param fn Function to throttle
+* @param ms Minimum interval between calls in milliseconds
+* @param options leading (default true), trailing (default true)
+* @returns Throttled function with cancel() method
+*
+* @example
+* ```ts
+* const handleScroll = throttle(updateUI, 100);
+* window.addEventListener('scroll', handleScroll);
+* handleScroll.cancel();
+* ```
+*/
+function throttle(fn, ms, options) {
+	const callable = fn;
+	let lastCallTime = null;
+	let timeoutId = null;
+	const { leading = true, trailing = true } = options || {};
+	let lastArgs = null;
+	let lastThis = null;
+	const throttled = function(...args) {
+		const callTime = Date.now();
+		const timeSinceLastCall = lastCallTime === null ? Number.POSITIVE_INFINITY : callTime - lastCallTime;
+		lastArgs = args;
+		lastThis = this;
+		if (leading && timeSinceLastCall >= ms) {
+			callable.apply(this, args);
+			lastCallTime = callTime;
+			if (timeoutId !== null) {
+				clearTimeout(timeoutId);
+				timeoutId = null;
+			}
+			return;
+		}
+		if (!leading && lastCallTime === null) lastCallTime = callTime;
+		if (trailing && timeoutId === null) timeoutId = setTimeout(() => {
+			callable.apply(lastThis, lastArgs);
+			lastCallTime = Date.now();
+			timeoutId = null;
+		}, lastCallTime === null ? ms : Math.max(0, ms - (callTime - lastCallTime)));
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return throttled;
+}
+/**
+* Once — guard against double execution
+*
+* Useful for: init logic, event safety
+*
+* @param fn Function to call at most once
+* @returns Function that executes fn only on first call
+*
+* @example
+* ```ts
+* const init = once(setup);
+* init(); // runs
+* init(); // does nothing
+* init(); // does nothing
+* ```
+*/
+function once(fn) {
+	const callable = fn;
+	let called = false;
+	let result;
+	return ((...args) => {
+		if (!called) {
+			called = true;
+			result = callable(...args);
+		}
+		return result;
+	});
+}
+/**
+* Defer — schedule on microtask queue
+*
+* Useful for: run-after-current-stack logic
+* More reliable than setTimeout(..., 0)
+*
+* @param fn Function to defer
+*
+* @example
+* ```ts
+* defer(() => update()); // runs after current stack, before next macrotask
+* ```
+*/
+function defer(fn) {
+	Promise.resolve().then(fn);
+}
+/**
+* RAF — coalesce multiple updates into single frame
+*
+* Useful for: animation, layout work, render updates
+*
+* @param fn Function to schedule on next animation frame
+* @returns Function that schedules fn on requestAnimationFrame
+*
+* @example
+* ```ts
+* const update = raf(render);
+* update(); // schedules on next frame
+* update(); // same frame, no duplicate
+* ```
+*/
+function raf(fn) {
+	const callable = fn;
+	let frameId = null;
+	let lastArgs = null;
+	let lastThis = null;
+	return function(...args) {
+		lastArgs = args;
+		lastThis = this;
+		if (frameId === null) frameId = requestAnimationFrame(() => {
+			callable.apply(lastThis, lastArgs);
+			frameId = null;
+		});
+	};
+}
+/**
+* Idle — schedule low-priority work
+*
+* Useful for: background prep, non-urgent updates
+* Falls back to setTimeout if requestIdleCallback unavailable
+*
+* @param fn Function to call when idle
+* @param options timeout for fallback
+*
+* @example
+* ```ts
+* idle(() => prefetchData());
+* ```
+*/
+function idle(fn, options) {
+	if (typeof requestIdleCallback !== "undefined") requestIdleCallback(fn, options ? { timeout: options.timeout } : void 0);
+	else Promise.resolve().then(() => {
+		setTimeout(fn, 0);
+	});
+}
+/**
+* Timeout — Promise-based delay
+*
+* Useful for: readable async code, waiting between retries
+*
+* @param ms Milliseconds to wait
+* @returns Promise that resolves after delay
+*
+* @example
+* ```ts
+* await timeout(300);
+* console.log('300ms later');
+* ```
+*/
+function timeout(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Retry — attempt function with backoff
+*
+* Useful for: network calls, transient failures
+*
+* @param fn Async function to retry
+* @param options maxAttempts, delayMs, backoff function
+* @returns Promise with final result or error
+*
+* @example
+* ```ts
+* const data = await retry(() => fetch(url), {
+*   maxAttempts: 3,
+*   delayMs: 100,
+* });
+* ```
+*/
+async function retry(fn, options) {
+	const { maxAttempts = 3, delayMs = 100, backoff = (i) => delayMs * Math.pow(2, i) } = options || {};
+	let lastError = null;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxAttempts - 1) await timeout(backoff(attempt));
+	}
+	throw lastError || /* @__PURE__ */ new Error("Retry failed");
+}
+//#endregion
+//#region src/fx/noop.ts
+const noopEventListener = Object.assign((_ev) => {}, { cancel() {} });
+const noopEventListenerWithFlush = Object.assign((_ev) => {}, {
+	cancel() {},
+	flush() {}
+});
+//#endregion
+//#region src/fx/fx.ts
+function throwIfDuringRender() {
+	if (getCurrentComponentInstance() !== null) throw new Error("[Askr] calling FX handler during render is not allowed. Move calls to event handlers or effects.");
+}
+/**
+* Helper: schedule a user callback through the global scheduler
+*/
+function enqueueUserCallback(fn) {
+	enqueueRuntimeTask(() => {
+		try {
+			fn();
+		} catch (err) {
+			logger.error("[Askr] FX handler error:", err);
+		}
+	});
+}
+function debounceEvent(ms, handler, options) {
+	const { leading = false, trailing = true } = options || {};
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListenerWithFlush;
+	let timeoutId = null;
+	let lastEvent = null;
+	let lastCallTime = 0;
+	const debounced = function(ev) {
+		throwIfDuringRender();
+		const now = Date.now();
+		lastEvent = ev;
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		if (leading && now - lastCallTime >= ms) {
+			enqueueUserCallback(() => handler.call(null, ev));
+			lastCallTime = now;
+		}
+		if (trailing) timeoutId = setTimeout(() => {
+			if (lastEvent) enqueueUserCallback(() => handler.call(null, lastEvent));
+			timeoutId = null;
+			lastCallTime = Date.now();
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastEvent = null;
+	};
+	debounced.flush = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			const ev = lastEvent;
+			lastEvent = null;
+			timeoutId = null;
+			if (ev) enqueueUserCallback(() => handler.call(null, ev));
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => {
+		debounced.cancel();
+	});
+	return debounced;
+}
+function throttleEvent(ms, handler, options) {
+	const { leading = true, trailing = true } = options || {};
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListener;
+	let lastCallTime = 0;
+	let timeoutId = null;
+	let lastEvent = null;
+	const throttled = function(ev) {
+		throwIfDuringRender();
+		const now = Date.now();
+		lastEvent = ev;
+		if (leading && now - lastCallTime >= ms) {
+			enqueueUserCallback(() => handler.call(null, ev));
+			lastCallTime = now;
+			if (timeoutId !== null) {
+				clearTimeout(timeoutId);
+				timeoutId = null;
+			}
+		} else if (!leading && lastCallTime === 0) lastCallTime = now;
+		if (trailing && timeoutId === null) {
+			const wait = ms - (now - lastCallTime);
+			timeoutId = setTimeout(() => {
+				if (lastEvent) enqueueUserCallback(() => handler.call(null, lastEvent));
+				lastCallTime = Date.now();
+				timeoutId = null;
+			}, Math.max(0, wait));
+		}
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastEvent = null;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => throttled.cancel());
+	return throttled;
+}
+function rafEvent(handler) {
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListener;
+	let frameId = null;
+	let lastEvent = null;
+	const scheduleFrame = () => {
+		frameId = (typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : (cb) => setTimeout(() => cb(Date.now()), 16))(() => {
+			frameId = null;
+			if (lastEvent) {
+				const ev = lastEvent;
+				lastEvent = null;
+				enqueueUserCallback(() => handler.call(null, ev));
+			}
+		});
+	};
+	const fn = function(ev) {
+		throwIfDuringRender();
+		lastEvent = ev;
+		if (frameId === null) scheduleFrame();
+	};
+	fn.cancel = () => {
+		if (frameId !== null) {
+			if (typeof cancelAnimationFrame !== "undefined" && typeof frameId === "number") cancelAnimationFrame(frameId);
+			else clearTimeout(frameId);
+			frameId = null;
+		}
+		lastEvent = null;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => fn.cancel());
+	return fn;
+}
+function scheduleTimeout(ms, fn) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return () => {};
+	let id = setTimeout(() => {
+		id = null;
+		enqueueUserCallback(fn);
+	}, ms);
+	const cancel = () => {
+		if (id !== null) {
+			clearTimeout(id);
+			id = null;
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return cancel;
+}
+function scheduleIdle(fn, options) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return () => {};
+	let id = null;
+	let usingRIC = false;
+	if (typeof requestIdleCallback !== "undefined") {
+		usingRIC = true;
+		id = requestIdleCallback(() => {
+			id = null;
+			enqueueUserCallback(fn);
+		}, options);
+	} else id = setTimeout(() => {
+		id = null;
+		enqueueUserCallback(fn);
+	}, 0);
+	const cancel = () => {
+		if (id !== null) {
+			if (usingRIC && typeof cancelIdleCallback !== "undefined" && typeof id === "number") cancelIdleCallback(id);
+			else clearTimeout(id);
+			id = null;
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return cancel;
+}
+function scheduleRetry(fn, options) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return { cancel: () => {} };
+	const { maxAttempts = 3, delayMs = 100, backoff = (i) => delayMs * Math.pow(2, i) } = options || {};
+	let cancelled = false;
+	const attempt = (index) => {
+		if (cancelled) return;
+		enqueueRuntimeTask(() => {
+			if (cancelled) return;
+			fn().then(() => {}, () => {
+				if (cancelled) return;
+				if (index + 1 < maxAttempts) {
+					const delay = backoff(index);
+					setTimeout(() => {
+						attempt(index + 1);
+					}, delay);
+				}
+			}).catch((e) => {
+				logger.error("[Askr] scheduleRetry error:", e);
+			});
+		});
+	};
+	attempt(0);
+	const cancel = () => {
+		cancelled = true;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return { cancel };
+}
+//#endregion
 export { debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };