@askrjs/askr 0.3.0 → 0.4.0

package/dist/fx/index.js

@@ -1,54 +1,115 @@
-import { h as scheduleEventHandler, n as enqueueRuntimeTask, v as logger } from "../access-CEA2pOry.js";
-import { O as ownCleanup, f as getCurrentComponentInstance } from "../scope-Cq_iYbTR.js";
+import { S as queueTask } from "../instance-BAnfmXOR.js";
+import { a as currentOwner, f as withOwner, i as currentComponent, y as reportUncaughtError } from "../hooks-BimKStr4.js";
+import { n as isPromiseLike } from "../promise-Dz8iIHAm.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
-* ```
+* @internal Edge logic for fx `debounceEvent`.
+* A trailing call only runs when a call arrived after the leading call.
 */
-function debounce(fn, ms, options) {
-	const callable = fn;
-	let timeoutId = null;
+function createDebouncer(invoke, ms, options) {
 	const { leading = false, trailing = true } = options || {};
+	let timeoutId = null;
 	let lastArgs = null;
 	let lastThis = null;
 	let trailingPending = false;
-	const debounced = function(...args) {
-		const windowActive = timeoutId !== null;
-		lastArgs = args;
-		lastThis = this;
-		if (timeoutId !== null) clearTimeout(timeoutId);
-		if (leading && !windowActive) {
-			callable.apply(this, args);
-			trailingPending = false;
-		} else if (trailing) trailingPending = true;
-		timeoutId = setTimeout(() => {
-			if (trailingPending) callable.apply(lastThis, lastArgs);
+	const clearTimer = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
 			timeoutId = null;
-			trailingPending = false;
-		}, ms);
+		}
 	};
-	debounced.cancel = () => {
+	const reset = () => {
+		trailingPending = false;
+		lastArgs = null;
+		lastThis = null;
+	};
+	const runTrailing = () => {
+		const pending = trailingPending;
+		const args = lastArgs;
+		const thisArg = lastThis;
+		reset();
+		if (pending) invoke(thisArg, args);
+	};
+	return {
+		call(thisArg, args) {
+			const windowActive = timeoutId !== null;
+			clearTimer();
+			if (leading && !windowActive) {
+				reset();
+				invoke(thisArg, args);
+			} else if (trailing) {
+				lastArgs = args;
+				lastThis = thisArg;
+				trailingPending = true;
+			}
+			timeoutId = setTimeout(() => {
+				timeoutId = null;
+				runTrailing();
+			}, ms);
+		},
+		cancel() {
+			clearTimer();
+			reset();
+		},
+		flush() {
+			if (timeoutId === null) return;
+			clearTimer();
+			runTrailing();
+		}
+	};
+}
+/**
+* @internal Edge logic shared by {@link throttle} and fx `throttleEvent`.
+* A trailing call only runs when a call arrived after the leading call.
+*/
+function createThrottler(invoke, ms, options) {
+	const { leading = true, trailing = true } = options || {};
+	let lastCallTime = null;
+	let timeoutId = null;
+	let lastArgs = null;
+	let lastThis = null;
+	const clearTimer = () => {
 		if (timeoutId !== null) {
 			clearTimeout(timeoutId);
 			timeoutId = null;
 		}
-		trailingPending = false;
 	};
-	return debounced;
+	return {
+		call(thisArg, args) {
+			const callTime = Date.now();
+			const timeSinceLastCall = lastCallTime === null ? Number.POSITIVE_INFINITY : callTime - lastCallTime;
+			if (leading && timeSinceLastCall >= ms) {
+				clearTimer();
+				lastArgs = null;
+				lastThis = null;
+				lastCallTime = callTime;
+				invoke(thisArg, args);
+				return;
+			}
+			if (!trailing) return;
+			lastArgs = args;
+			lastThis = thisArg;
+			if (!leading && timeSinceLastCall >= ms) lastCallTime = callTime;
+			if (timeoutId === null) timeoutId = setTimeout(() => {
+				timeoutId = null;
+				lastCallTime = Date.now();
+				const pendingArgs = lastArgs;
+				const pendingThis = lastThis;
+				lastArgs = null;
+				lastThis = null;
+				invoke(pendingThis, pendingArgs);
+			}, Math.max(0, ms - (callTime - lastCallTime)));
+		},
+		cancel() {
+			clearTimer();
+			lastArgs = null;
+			lastThis = null;
+		}
+	};
 }
+const applyTo = (callable) => (thisArg, args) => {
+	callable.apply(thisArg, args);
+};
 /**
 * Throttle — rate-limit execution, keep first/last
 *
@@ -67,39 +128,11 @@ function debounce(fn, ms, options) {
 * ```
 */
 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 throttler = createThrottler(applyTo(fn), ms, options);
 	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;
-		}
+		throttler.call(this, args);
 	};
+	throttled.cancel = throttler.cancel;
 	return throttled;
 }
 /**
@@ -131,22 +164,6 @@ function once(fn) {
 	};
 }
 /**
-* 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
@@ -166,14 +183,31 @@ function raf(fn) {
 	let frameId = null;
 	let lastArgs = null;
 	let lastThis = null;
-	return function(...args) {
+	let generation = 0;
+	const scheduled = function(...args) {
 		lastArgs = args;
 		lastThis = this;
-		if (frameId === null) frameId = requestAnimationFrame(() => {
-			callable.apply(lastThis, lastArgs);
-			frameId = null;
-		});
+		if (frameId === null) {
+			const currentGeneration = ++generation;
+			frameId = requestAnimationFrame(() => {
+				if (currentGeneration !== generation) return;
+				frameId = null;
+				const args = lastArgs;
+				const receiver = lastThis;
+				lastArgs = null;
+				lastThis = null;
+				callable.apply(receiver, args);
+			});
+		}
 	};
+	scheduled.cancel = () => {
+		generation++;
+		if (frameId !== null) cancelAnimationFrame(frameId);
+		frameId = null;
+		lastArgs = null;
+		lastThis = null;
+	};
+	return scheduled;
 }
 /**
 * Idle — schedule low-priority work
@@ -249,126 +283,122 @@ const noopEventListenerWithFlush = Object.assign((_ev) => {}, {
 });
 //#endregion
 //#region src/fx/fx.ts
+/** The owner an event arrives under, else the owner that created the handler. */
+function captureLifecycleOwner() {
+	const captured = currentOwner();
+	return () => currentOwner() ?? captured;
+}
+function ownCleanup(owner, cleanup) {
+	owner.onCleanup(cleanup);
+}
 function throwIfDuringRender() {
-	if (getCurrentComponentInstance() !== null) throw new Error("[Askr] calling FX handler during render is not allowed. Move calls to event handlers or effects.");
+	if (currentComponent() !== 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
+* Schedule a user callback through the runtime scheduler. Its errors are
+* reported like a native listener's (reportError) so the rest of the flush
+* still runs.
 */
 function enqueueUserCallback(fn) {
-	enqueueRuntimeTask(() => {
+	queueTask(() => {
 		try {
 			fn();
 		} catch (err) {
-			logger.error("[Askr] FX handler error:", err);
+			reportUncaughtError(err);
 		}
 	});
 }
+const noopRelease = () => {};
+/**
+* Cancel scheduled work when the component whose committed lifecycle
+* (mount/commit operation, task, watch callback, or event handler) scheduled
+* it is cleaned up. Returns a release function for work that settles first.
+*/
+function cancelWithLifecycleOwner(owner, cancel) {
+	if (!owner) return noopRelease;
+	if (owner.disposed) {
+		cancel();
+		return noopRelease;
+	}
+	let active = true;
+	owner.onCleanup(() => {
+		if (active) cancel();
+	});
+	return () => {
+		active = false;
+	};
+}
+/** Run a wrapped handler later as the lifetime that received its event. */
+function enqueueOwnedHandler(handler, event, owner) {
+	enqueueUserCallback(() => withOwner(owner, () => handler.call(null, event)));
+}
+/** Schedule a native listener under the owner that created it. */
+function scheduleEventHandler(handler) {
+	const resolveOwner = captureLifecycleOwner();
+	return (event) => {
+		enqueueOwnedHandler(handler, event, resolveOwner());
+	};
+}
+function enqueueEventHandler(handler) {
+	return (_thisArg, [event, owner]) => {
+		enqueueOwnedHandler(handler, event, owner);
+	};
+}
 /** Wrap an event handler so rapid events are coalesced and delayed by `ms`. */
 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 inst = currentComponent();
+	if (inst && inst.server) return noopEventListenerWithFlush;
+	const resolveOwner = captureLifecycleOwner();
+	const debouncer = createDebouncer(enqueueEventHandler(handler), ms, options);
 	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);
+		debouncer.call(null, [ev, resolveOwner()]);
 	};
-	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) ownCleanup(inst.owner, () => {
-		debounced.cancel();
-	});
+	debounced.cancel = debouncer.cancel;
+	debounced.flush = debouncer.flush;
+	const owner = inst ?? currentOwner();
+	if (owner) ownCleanup(owner, debounced.cancel);
 	return debounced;
 }
 /** Wrap an event handler so it runs at most once per `ms` interval. */
 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 inst = currentComponent();
+	if (inst && inst.server) return noopEventListener;
+	const resolveOwner = captureLifecycleOwner();
+	const throttler = createThrottler(enqueueEventHandler(handler), ms, options);
 	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));
-		}
+		throttler.call(null, [ev, resolveOwner()]);
 	};
-	throttled.cancel = () => {
-		if (timeoutId !== null) {
-			clearTimeout(timeoutId);
-			timeoutId = null;
-		}
-		lastEvent = null;
-	};
-	if (inst) ownCleanup(inst.owner, () => throttled.cancel());
+	throttled.cancel = throttler.cancel;
+	const owner = inst ?? currentOwner();
+	if (owner) ownCleanup(owner, throttled.cancel);
 	return throttled;
 }
 /** Wrap an event handler so it runs at most once per animation frame, using the latest event. */
 function rafEvent(handler) {
-	const inst = getCurrentComponentInstance();
-	if (inst && inst.ssr) return noopEventListener;
+	const inst = currentComponent();
+	if (inst && inst.server) return noopEventListener;
+	const resolveOwner = captureLifecycleOwner();
 	let frameId = null;
 	let lastEvent = null;
+	let lastOwner = null;
 	const scheduleFrame = () => {
 		frameId = (typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : (cb) => setTimeout(() => cb(Date.now()), 16))(() => {
 			frameId = null;
 			if (lastEvent) {
 				const ev = lastEvent;
+				const owner = lastOwner;
 				lastEvent = null;
-				enqueueUserCallback(() => handler.call(null, ev));
+				lastOwner = null;
+				enqueueOwnedHandler(handler, ev, owner);
 			}
 		});
 	};
 	const fn = function(ev) {
 		throwIfDuringRender();
 		lastEvent = ev;
+		lastOwner = resolveOwner();
 		if (frameId === null) scheduleFrame();
 	};
 	fn.cancel = () => {
@@ -378,85 +408,173 @@ function rafEvent(handler) {
 			frameId = null;
 		}
 		lastEvent = null;
+		lastOwner = null;
 	};
-	if (inst) ownCleanup(inst.owner, () => fn.cancel());
+	const owner = inst ?? currentOwner();
+	if (owner) ownCleanup(owner, fn.cancel);
 	return fn;
 }
-/** Schedule `fn` after `ms`, auto-cancelling on component cleanup; returns a cancel function. */
+/**
+* Schedule `fn` after `ms`; returns a cancel function. Called from a mounted
+* component's task, watch callback, or event handler, it is also cancelled
+* when that component is cleaned up.
+*/
 function scheduleTimeout(ms, fn) {
 	throwIfDuringRender();
-	const inst = getCurrentComponentInstance();
-	if (inst && inst.ssr) return () => {};
+	const owner = currentOwner();
+	let release = noopRelease;
+	let settled = false;
+	const run = () => {
+		if (settled) return;
+		settled = true;
+		release();
+		withOwner(owner, fn);
+	};
 	let id = setTimeout(() => {
 		id = null;
-		enqueueUserCallback(fn);
+		enqueueUserCallback(run);
 	}, ms);
 	const cancel = () => {
+		settled = true;
 		if (id !== null) {
 			clearTimeout(id);
 			id = null;
 		}
+		release();
 	};
-	if (inst) ownCleanup(inst.owner, cancel);
+	release = cancelWithLifecycleOwner(owner, cancel);
 	return cancel;
 }
-/** Schedule `fn` during browser idle time, auto-cancelling on component cleanup. */
+/**
+* Schedule `fn` during browser idle time; returns a cancel function. Called
+* from a mounted component's task, watch callback, or event handler, it is
+* also cancelled when that component is cleaned up.
+*/
 function scheduleIdle(fn, options) {
 	throwIfDuringRender();
-	const inst = getCurrentComponentInstance();
-	if (inst && inst.ssr) return () => {};
+	const owner = currentOwner();
+	let release = noopRelease;
+	let settled = false;
+	const run = () => {
+		if (settled) return;
+		settled = true;
+		release();
+		withOwner(owner, fn);
+	};
 	let id = null;
 	let usingRIC = false;
 	if (typeof requestIdleCallback !== "undefined") {
 		usingRIC = true;
 		id = requestIdleCallback(() => {
 			id = null;
-			enqueueUserCallback(fn);
+			enqueueUserCallback(run);
 		}, options);
 	} else id = setTimeout(() => {
 		id = null;
-		enqueueUserCallback(fn);
+		enqueueUserCallback(run);
 	}, 0);
 	const cancel = () => {
+		settled = true;
 		if (id !== null) {
 			if (usingRIC && typeof cancelIdleCallback !== "undefined" && typeof id === "number") cancelIdleCallback(id);
 			else clearTimeout(id);
 			id = null;
 		}
+		release();
 	};
-	if (inst) ownCleanup(inst.owner, cancel);
+	release = cancelWithLifecycleOwner(owner, cancel);
 	return cancel;
 }
-/** Run `fn`, retrying with backoff on failure, auto-cancelling on component cleanup. */
+/**
+* Run `fn`, retrying with backoff on failure. Called from a mounted
+* component's task, watch callback, or event handler, pending attempts are
+* also cancelled when that component is cleaned up.
+*/
 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 || {};
+	const owner = currentOwner();
 	let cancelled = false;
+	let retryId = null;
+	let release = noopRelease;
+	let resolveResult;
+	const result = new Promise((resolve) => {
+		resolveResult = resolve;
+	});
+	const settle = (outcome) => {
+		if (cancelled) return;
+		cancelled = true;
+		release();
+		resolveResult(outcome);
+	};
 	const attempt = (index) => {
+		retryId = null;
 		if (cancelled) return;
-		enqueueRuntimeTask(() => {
+		queueTask(() => {
 			if (cancelled) return;
-			fn().then(() => {}, () => {
+			let p;
+			try {
+				p = withOwner(owner, fn);
+			} catch (e) {
+				settle({
+					status: "error",
+					error: e
+				});
+				reportUncaughtError(e);
+				return;
+			}
+			if (!isPromiseLike(p)) {
+				settle({
+					status: "error",
+					error: /* @__PURE__ */ new TypeError("scheduleRetry callback must return a promise")
+				});
+				return;
+			}
+			Promise.resolve(p).then((value) => settle({
+				status: "success",
+				value
+			}), (error) => {
 				if (cancelled) return;
-				if (index + 1 < maxAttempts) {
-					const delay = backoff(index);
-					setTimeout(() => {
+				if (index + 1 < maxAttempts) try {
+					retryId = setTimeout(() => {
 						attempt(index + 1);
-					}, delay);
+					}, backoff(index));
+				} catch (backoffError) {
+					settle({
+						status: "error",
+						error: backoffError
+					});
+					reportUncaughtError(backoffError);
 				}
-			}).catch((e) => {
-				logger.error("[Askr] scheduleRetry error:", e);
+				else {
+					settle({
+						status: "error",
+						error
+					});
+					reportUncaughtError(error);
+				}
+			}).catch((error) => {
+				settle({
+					status: "error",
+					error
+				});
+				reportUncaughtError(error);
 			});
 		});
 	};
-	attempt(0);
 	const cancel = () => {
-		cancelled = true;
+		if (retryId !== null) {
+			clearTimeout(retryId);
+			retryId = null;
+		}
+		settle({ status: "cancelled" });
+	};
+	release = cancelWithLifecycleOwner(owner, cancel);
+	attempt(0);
+	return {
+		cancel,
+		result
 	};
-	if (inst) ownCleanup(inst.owner, cancel);
-	return { cancel };
 }
 //#endregion
-export { debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };
+export { debounceEvent, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };