@askrjs/askr 0.0.3 → 0.0.5

package/README.md

@@ -65,9 +65,12 @@ function Home() {
   );
 }
 
+```
 
 **Tip:** Prefer functional updates when updating based on previous state: `count.set(prev => prev + 1)`.
 
+```ts
+
 function User({ id }: { id: string }) {
   return (
     <div>
@@ -131,16 +134,16 @@ Askr doesn’t introduce a new cancellation concept. When work becomes stale (un
 Example (recommended pattern):
 
 ```ts
-import { route, resource, getSignal } from '@askrjs/askr';
+import { route, resource } from '@askrjs/askr';
 
 function User({ id }: { id: string }) {
-  const user = resource(async () => {
-    const res = await fetch(`/api/users/${id}`, { signal: getSignal() });
+  const user = resource(async ({ signal }) => {
+    const res = await fetch(`/api/users/${id}`, { signal });
     return res.json();
   }, [id]);
 
-  if (!user) return <div>Loading...</div>;
-  return <pre>{JSON.stringify(user, null, 2)}</pre>;
+  if (user.pending) return <div>Loading...</div>;
+  return <pre>{JSON.stringify(user.value, null, 2)}</pre>;
 }
 
 route('/user/{id}', ({ id }) => <User id={id} />);

package/dist/fx.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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$1 {
+    maxAttempts?: number;
+    delayMs?: number;
+    backoff?: (attemptIndex: number) => number;
+}
+/**
+ * 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 (...args: unknown[]) => unknown>(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 (...args: unknown[]) => unknown>(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 (...args: unknown[]) => unknown>(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 (...args: unknown[]) => unknown>(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$1): Promise<T>;
+
+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 {
+    maxAttempts?: number;
+    delayMs?: number;
+    backoff?: (attemptIndex: number) => number;
+}
+declare function scheduleRetry<T>(fn: () => Promise<T>, options?: RetryOptions): {
+    cancel(): void;
+};
+
+export { type DebounceOptions, type RetryOptions$1 as RetryOptions, type ThrottleOptions, debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };