flowx-control 1.0.0

package/dist/circuit-breaker.mjs

@@ -0,0 +1,130 @@
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CircuitBreakerError = class extends FlowXError {
+  constructor(message = "Circuit breaker is open") {
+    super(message, "ERR_CIRCUIT_OPEN");
+    this.name = "CircuitBreakerError";
+  }
+};
+
+// src/circuit-breaker.ts
+function createCircuitBreaker(fn, options) {
+  const {
+    failureThreshold = 5,
+    resetTimeout = 3e4,
+    halfOpenLimit = 1,
+    shouldTrip,
+    onStateChange,
+    successThreshold = 1
+  } = options ?? {};
+  let state = "closed";
+  let failureCount = 0;
+  let successCount = 0;
+  let halfOpenActive = 0;
+  let resetTimer = null;
+  function transition(to) {
+    if (state === to) return;
+    const from = state;
+    state = to;
+    onStateChange?.(from, to);
+  }
+  function scheduleReset() {
+    if (resetTimer) clearTimeout(resetTimer);
+    resetTimer = setTimeout(() => {
+      resetTimer = null;
+      transition("half-open");
+      halfOpenActive = 0;
+      successCount = 0;
+    }, resetTimeout);
+  }
+  function reset() {
+    if (resetTimer) {
+      clearTimeout(resetTimer);
+      resetTimer = null;
+    }
+    failureCount = 0;
+    successCount = 0;
+    halfOpenActive = 0;
+    transition("closed");
+  }
+  function manualOpen() {
+    if (resetTimer) {
+      clearTimeout(resetTimer);
+      resetTimer = null;
+    }
+    failureCount = 0;
+    successCount = 0;
+    halfOpenActive = 0;
+    transition("open");
+    scheduleReset();
+  }
+  async function fire(...args) {
+    if (state === "open") {
+      throw new CircuitBreakerError();
+    }
+    if (state === "half-open" && halfOpenActive >= halfOpenLimit) {
+      throw new CircuitBreakerError("Circuit breaker is half-open \u2014 limit reached");
+    }
+    if (state === "half-open") {
+      halfOpenActive++;
+    }
+    try {
+      const result = await fn(...args);
+      if (state === "half-open") {
+        successCount++;
+        halfOpenActive--;
+        if (successCount >= successThreshold) {
+          reset();
+        }
+      } else {
+        failureCount = 0;
+      }
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (shouldTrip && !shouldTrip(err)) {
+        if (state === "half-open") {
+          halfOpenActive--;
+        }
+        throw err;
+      }
+      if (state === "half-open") {
+        halfOpenActive--;
+        transition("open");
+        scheduleReset();
+      } else {
+        failureCount++;
+        if (failureCount >= failureThreshold) {
+          transition("open");
+          scheduleReset();
+        }
+      }
+      throw err;
+    }
+  }
+  return {
+    fire,
+    get state() {
+      return state;
+    },
+    get failureCount() {
+      return failureCount;
+    },
+    get successCount() {
+      return successCount;
+    },
+    reset,
+    open: manualOpen
+  };
+}
+
+export { createCircuitBreaker };
+//# sourceMappingURL=circuit-breaker.mjs.map
+//# sourceMappingURL=circuit-breaker.mjs.map

package/dist/circuit-breaker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/circuit-breaker.ts"],"names":[],"mappings":"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","file":"circuit-breaker.mjs","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Circuit Breaker Pattern\n// ============================================================================\nimport { CircuitBreakerError } from './types';\n\nexport type CircuitState = 'closed' | 'open' | 'half-open';\n\nexport interface CircuitBreakerOptions {\n  /** Number of failures before opening the circuit (default: 5) */\n  failureThreshold?: number;\n  /** Time in ms before attempting half-open (default: 30000) */\n  resetTimeout?: number;\n  /** Max concurrent calls in half-open state (default: 1) */\n  halfOpenLimit?: number;\n  /** Custom predicate to decide if an error should count as a failure */\n  shouldTrip?: (error: Error) => boolean;\n  /** Callback fired on state changes */\n  onStateChange?: (from: CircuitState, to: CircuitState) => void;\n  /** Number of successes in half-open to close the circuit (default: 1) */\n  successThreshold?: number;\n}\n\nexport interface CircuitBreaker<TArgs extends any[], TReturn> {\n  /** Execute the protected function */\n  fire: (...args: TArgs) => Promise<TReturn>;\n  /** Get the current circuit state */\n  readonly state: CircuitState;\n  /** Get the current failure count */\n  readonly failureCount: number;\n  /** Get the current success count (in half-open) */\n  readonly successCount: number;\n  /** Manually reset the circuit to closed */\n  reset: () => void;\n  /** Manually open the circuit */\n  open: () => void;\n}\n\n/**\n * Create a circuit breaker to protect against cascading failures.\n *\n * @example\n * ```ts\n * const breaker = createCircuitBreaker(callExternalApi, {\n *   failureThreshold: 5,\n *   resetTimeout: 30000,\n * });\n * const data = await breaker.fire('arg1');\n * ```\n */\nexport function createCircuitBreaker<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options?: CircuitBreakerOptions,\n): CircuitBreaker<TArgs, TReturn> {\n  const {\n    failureThreshold = 5,\n    resetTimeout = 30000,\n    halfOpenLimit = 1,\n    shouldTrip,\n    onStateChange,\n    successThreshold = 1,\n  } = options ?? {};\n\n  let state: CircuitState = 'closed';\n  let failureCount = 0;\n  let successCount = 0;\n  let halfOpenActive = 0;\n  let resetTimer: ReturnType<typeof setTimeout> | null = null;\n\n  function transition(to: CircuitState): void {\n    if (state === to) return;\n    const from = state;\n    state = to;\n    onStateChange?.(from, to);\n  }\n\n  function scheduleReset(): void {\n    /* istanbul ignore next -- defensive guard; timer always fires before reschedule in normal flow */\n    if (resetTimer) clearTimeout(resetTimer);\n    resetTimer = setTimeout(() => {\n      resetTimer = null;\n      transition('half-open');\n      halfOpenActive = 0;\n      successCount = 0;\n    }, resetTimeout);\n  }\n\n  function reset(): void {\n    if (resetTimer) {\n      clearTimeout(resetTimer);\n      resetTimer = null;\n    }\n    failureCount = 0;\n    successCount = 0;\n    halfOpenActive = 0;\n    transition('closed');\n  }\n\n  function manualOpen(): void {\n    if (resetTimer) {\n      clearTimeout(resetTimer);\n      resetTimer = null;\n    }\n    failureCount = 0;\n    successCount = 0;\n    halfOpenActive = 0;\n    transition('open');\n    scheduleReset();\n  }\n\n  async function fire(...args: TArgs): Promise<TReturn> {\n    if (state === 'open') {\n      throw new CircuitBreakerError();\n    }\n\n    if (state === 'half-open' && halfOpenActive >= halfOpenLimit) {\n      throw new CircuitBreakerError('Circuit breaker is half-open — limit reached');\n    }\n\n    if (state === 'half-open') {\n      halfOpenActive++;\n    }\n\n    try {\n      const result = await fn(...args);\n\n      if (state === 'half-open') {\n        successCount++;\n        halfOpenActive--;\n        if (successCount >= successThreshold) {\n          reset();\n        }\n      } else {\n        // In closed state, reset failure count on success\n        failureCount = 0;\n      }\n\n      return result;\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n\n      if (shouldTrip && !shouldTrip(err)) {\n        if (state === 'half-open') {\n          halfOpenActive--;\n        }\n        throw err;\n      }\n\n      if (state === 'half-open') {\n        halfOpenActive--;\n        transition('open');\n        scheduleReset();\n      } else {\n        failureCount++;\n        if (failureCount >= failureThreshold) {\n          transition('open');\n          scheduleReset();\n        }\n      }\n\n      throw err;\n    }\n  }\n\n  return {\n    fire,\n    get state() {\n      return state;\n    },\n    get failureCount() {\n      return failureCount;\n    },\n    get successCount() {\n      return successCount;\n    },\n    reset,\n    open: manualOpen,\n  };\n}\n"]}

package/dist/debounce.d.mts

@@ -0,0 +1,30 @@
+interface DebounceOptions {
+    /** Invoke on the leading edge (default: false) */
+    leading?: boolean;
+    /** Invoke on the trailing edge (default: true) */
+    trailing?: boolean;
+    /** Maximum wait time before forced invocation in ms */
+    maxWait?: number;
+}
+interface DebouncedFunction<TArgs extends any[], TReturn> {
+    /** Call the debounced function */
+    (...args: TArgs): Promise<TReturn>;
+    /** Cancel any pending invocation */
+    cancel: () => void;
+    /** Immediately invoke any pending call */
+    flush: () => Promise<TReturn | undefined>;
+    /** Whether there is a pending invocation */
+    readonly pending: boolean;
+}
+/**
+ * Create a debounced version of an async function.
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce(searchApi, 300);
+ * await debouncedSearch('query');
+ * ```
+ */
+declare function debounce<TArgs extends any[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, wait: number, options?: DebounceOptions): DebouncedFunction<TArgs, TReturn>;
+
+export { type DebounceOptions, type DebouncedFunction, debounce };

package/dist/debounce.d.ts

@@ -0,0 +1,30 @@
+interface DebounceOptions {
+    /** Invoke on the leading edge (default: false) */
+    leading?: boolean;
+    /** Invoke on the trailing edge (default: true) */
+    trailing?: boolean;
+    /** Maximum wait time before forced invocation in ms */
+    maxWait?: number;
+}
+interface DebouncedFunction<TArgs extends any[], TReturn> {
+    /** Call the debounced function */
+    (...args: TArgs): Promise<TReturn>;
+    /** Cancel any pending invocation */
+    cancel: () => void;
+    /** Immediately invoke any pending call */
+    flush: () => Promise<TReturn | undefined>;
+    /** Whether there is a pending invocation */
+    readonly pending: boolean;
+}
+/**
+ * Create a debounced version of an async function.
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce(searchApi, 300);
+ * await debouncedSearch('query');
+ * ```
+ */
+declare function debounce<TArgs extends any[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, wait: number, options?: DebounceOptions): DebouncedFunction<TArgs, TReturn>;
+
+export { type DebounceOptions, type DebouncedFunction, debounce };

package/dist/debounce.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// src/debounce.ts
+function debounce(fn, wait, options) {
+  const { leading = false, trailing = true, maxWait } = options ?? {};
+  if (wait < 0) throw new RangeError("wait must be >= 0");
+  let timer = null;
+  let maxTimer = null;
+  let lastArgs = null;
+  const pendingResolvers = [];
+  let isPending = false;
+  async function invoke() {
+    const args = lastArgs;
+    const resolvers = pendingResolvers.splice(0);
+    lastArgs = null;
+    isPending = false;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (maxTimer) {
+      clearTimeout(maxTimer);
+      maxTimer = null;
+    }
+    try {
+      const result = await fn(...args);
+      for (const r of resolvers) r.resolve(result);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      for (const r of resolvers) r.reject(err);
+    }
+  }
+  function debounced(...args) {
+    lastArgs = args;
+    return new Promise((resolve, reject) => {
+      pendingResolvers.push({ resolve, reject });
+      if (leading && !isPending) {
+        isPending = true;
+        invoke();
+        return;
+      }
+      isPending = true;
+      if (timer) clearTimeout(timer);
+      if (trailing) {
+        timer = setTimeout(() => {
+          timer = null;
+          invoke();
+        }, wait);
+      }
+      if (maxWait !== void 0 && !maxTimer) {
+        maxTimer = setTimeout(() => {
+          maxTimer = null;
+          if (timer) {
+            clearTimeout(timer);
+            timer = null;
+          }
+          invoke();
+        }, maxWait);
+      }
+    });
+  }
+  debounced.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (maxTimer) {
+      clearTimeout(maxTimer);
+      maxTimer = null;
+    }
+    lastArgs = null;
+    isPending = false;
+    const resolvers = pendingResolvers.splice(0);
+    for (const r of resolvers) {
+      r.reject(new Error("Debounced call cancelled"));
+    }
+  };
+  debounced.flush = async () => {
+    if (!isPending) return void 0;
+    const promise = new Promise((resolve, reject) => {
+      pendingResolvers.push({ resolve, reject });
+    });
+    await invoke();
+    return promise;
+  };
+  Object.defineProperty(debounced, "pending", {
+    get() {
+      return isPending;
+    }
+  });
+  return debounced;
+}
+
+exports.debounce = debounce;
+//# sourceMappingURL=debounce.js.map
+//# sourceMappingURL=debounce.js.map

package/dist/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debounce.ts"],"names":[],"mappings":"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","file":"debounce.js","sourcesContent":["// ============================================================================\n// FlowX — Async-Aware Debounce\n// ============================================================================\n\nexport interface DebounceOptions {\n  /** Invoke on the leading edge (default: false) */\n  leading?: boolean;\n  /** Invoke on the trailing edge (default: true) */\n  trailing?: boolean;\n  /** Maximum wait time before forced invocation in ms */\n  maxWait?: number;\n}\n\nexport interface DebouncedFunction<TArgs extends any[], TReturn> {\n  /** Call the debounced function */\n  (...args: TArgs): Promise<TReturn>;\n  /** Cancel any pending invocation */\n  cancel: () => void;\n  /** Immediately invoke any pending call */\n  flush: () => Promise<TReturn | undefined>;\n  /** Whether there is a pending invocation */\n  readonly pending: boolean;\n}\n\n/**\n * Create a debounced version of an async function.\n *\n * @example\n * ```ts\n * const debouncedSearch = debounce(searchApi, 300);\n * await debouncedSearch('query');\n * ```\n */\nexport function debounce<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => TReturn | Promise<TReturn>,\n  wait: number,\n  options?: DebounceOptions,\n): DebouncedFunction<TArgs, TReturn> {\n  const { leading = false, trailing = true, maxWait } = options ?? {};\n\n  if (wait < 0) throw new RangeError('wait must be >= 0');\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let maxTimer: ReturnType<typeof setTimeout> | null = null;\n  let lastArgs: TArgs | null = null;\n  const pendingResolvers: Array<{\n    resolve: (value: TReturn) => void;\n    reject: (error: Error) => void;\n  }> = [];\n  let isPending = false;\n\n  async function invoke(): Promise<void> {\n\n    const args = lastArgs!;\n    const resolvers = pendingResolvers.splice(0);\n    lastArgs = null;\n    isPending = false;\n\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    if (maxTimer) {\n      clearTimeout(maxTimer);\n      maxTimer = null;\n    }\n\n    try {\n      const result = await fn(...args);\n      for (const r of resolvers) r.resolve(result);\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      for (const r of resolvers) r.reject(err);\n    }\n  }\n\n  function debounced(...args: TArgs): Promise<TReturn> {\n    lastArgs = args;\n\n    return new Promise<TReturn>((resolve, reject) => {\n      pendingResolvers.push({ resolve, reject });\n\n      // Leading edge\n      if (leading && !isPending) {\n        isPending = true;\n        invoke();\n        return;\n      }\n\n      isPending = true;\n\n      // Reset trailing timer\n      if (timer) clearTimeout(timer);\n\n      if (trailing) {\n        timer = setTimeout(() => {\n          timer = null;\n          invoke();\n        }, wait);\n      }\n\n      // Set max wait timer\n      if (maxWait !== undefined && !maxTimer) {\n        maxTimer = setTimeout(() => {\n          maxTimer = null;\n          if (timer) {\n            clearTimeout(timer);\n            timer = null;\n          }\n          invoke();\n        }, maxWait);\n      }\n    });\n  }\n\n  debounced.cancel = (): void => {\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    if (maxTimer) {\n      clearTimeout(maxTimer);\n      maxTimer = null;\n    }\n    lastArgs = null;\n    isPending = false;\n    // Reject all pending resolvers\n    const resolvers = pendingResolvers.splice(0);\n    for (const r of resolvers) {\n      r.reject(new Error('Debounced call cancelled'));\n    }\n  };\n\n  debounced.flush = async (): Promise<TReturn | undefined> => {\n    if (!isPending) return undefined;\n    const promise = new Promise<TReturn>((resolve, reject) => {\n      pendingResolvers.push({ resolve, reject });\n    });\n    await invoke();\n    return promise;\n  };\n\n  Object.defineProperty(debounced, 'pending', {\n    get() {\n      return isPending;\n    },\n  });\n\n  return debounced as DebouncedFunction<TArgs, TReturn>;\n}\n"]}

package/dist/debounce.mjs

@@ -0,0 +1,94 @@
+// src/debounce.ts
+function debounce(fn, wait, options) {
+  const { leading = false, trailing = true, maxWait } = options ?? {};
+  if (wait < 0) throw new RangeError("wait must be >= 0");
+  let timer = null;
+  let maxTimer = null;
+  let lastArgs = null;
+  const pendingResolvers = [];
+  let isPending = false;
+  async function invoke() {
+    const args = lastArgs;
+    const resolvers = pendingResolvers.splice(0);
+    lastArgs = null;
+    isPending = false;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (maxTimer) {
+      clearTimeout(maxTimer);
+      maxTimer = null;
+    }
+    try {
+      const result = await fn(...args);
+      for (const r of resolvers) r.resolve(result);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      for (const r of resolvers) r.reject(err);
+    }
+  }
+  function debounced(...args) {
+    lastArgs = args;
+    return new Promise((resolve, reject) => {
+      pendingResolvers.push({ resolve, reject });
+      if (leading && !isPending) {
+        isPending = true;
+        invoke();
+        return;
+      }
+      isPending = true;
+      if (timer) clearTimeout(timer);
+      if (trailing) {
+        timer = setTimeout(() => {
+          timer = null;
+          invoke();
+        }, wait);
+      }
+      if (maxWait !== void 0 && !maxTimer) {
+        maxTimer = setTimeout(() => {
+          maxTimer = null;
+          if (timer) {
+            clearTimeout(timer);
+            timer = null;
+          }
+          invoke();
+        }, maxWait);
+      }
+    });
+  }
+  debounced.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (maxTimer) {
+      clearTimeout(maxTimer);
+      maxTimer = null;
+    }
+    lastArgs = null;
+    isPending = false;
+    const resolvers = pendingResolvers.splice(0);
+    for (const r of resolvers) {
+      r.reject(new Error("Debounced call cancelled"));
+    }
+  };
+  debounced.flush = async () => {
+    if (!isPending) return void 0;
+    const promise = new Promise((resolve, reject) => {
+      pendingResolvers.push({ resolve, reject });
+    });
+    await invoke();
+    return promise;
+  };
+  Object.defineProperty(debounced, "pending", {
+    get() {
+      return isPending;
+    }
+  });
+  return debounced;
+}
+
+export { debounce };
+//# sourceMappingURL=debounce.mjs.map
+//# sourceMappingURL=debounce.mjs.map

package/dist/debounce.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debounce.ts"],"names":[],"mappings":"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","file":"debounce.mjs","sourcesContent":["// ============================================================================\n// FlowX — Async-Aware Debounce\n// ============================================================================\n\nexport interface DebounceOptions {\n  /** Invoke on the leading edge (default: false) */\n  leading?: boolean;\n  /** Invoke on the trailing edge (default: true) */\n  trailing?: boolean;\n  /** Maximum wait time before forced invocation in ms */\n  maxWait?: number;\n}\n\nexport interface DebouncedFunction<TArgs extends any[], TReturn> {\n  /** Call the debounced function */\n  (...args: TArgs): Promise<TReturn>;\n  /** Cancel any pending invocation */\n  cancel: () => void;\n  /** Immediately invoke any pending call */\n  flush: () => Promise<TReturn | undefined>;\n  /** Whether there is a pending invocation */\n  readonly pending: boolean;\n}\n\n/**\n * Create a debounced version of an async function.\n *\n * @example\n * ```ts\n * const debouncedSearch = debounce(searchApi, 300);\n * await debouncedSearch('query');\n * ```\n */\nexport function debounce<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => TReturn | Promise<TReturn>,\n  wait: number,\n  options?: DebounceOptions,\n): DebouncedFunction<TArgs, TReturn> {\n  const { leading = false, trailing = true, maxWait } = options ?? {};\n\n  if (wait < 0) throw new RangeError('wait must be >= 0');\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let maxTimer: ReturnType<typeof setTimeout> | null = null;\n  let lastArgs: TArgs | null = null;\n  const pendingResolvers: Array<{\n    resolve: (value: TReturn) => void;\n    reject: (error: Error) => void;\n  }> = [];\n  let isPending = false;\n\n  async function invoke(): Promise<void> {\n\n    const args = lastArgs!;\n    const resolvers = pendingResolvers.splice(0);\n    lastArgs = null;\n    isPending = false;\n\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    if (maxTimer) {\n      clearTimeout(maxTimer);\n      maxTimer = null;\n    }\n\n    try {\n      const result = await fn(...args);\n      for (const r of resolvers) r.resolve(result);\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      for (const r of resolvers) r.reject(err);\n    }\n  }\n\n  function debounced(...args: TArgs): Promise<TReturn> {\n    lastArgs = args;\n\n    return new Promise<TReturn>((resolve, reject) => {\n      pendingResolvers.push({ resolve, reject });\n\n      // Leading edge\n      if (leading && !isPending) {\n        isPending = true;\n        invoke();\n        return;\n      }\n\n      isPending = true;\n\n      // Reset trailing timer\n      if (timer) clearTimeout(timer);\n\n      if (trailing) {\n        timer = setTimeout(() => {\n          timer = null;\n          invoke();\n        }, wait);\n      }\n\n      // Set max wait timer\n      if (maxWait !== undefined && !maxTimer) {\n        maxTimer = setTimeout(() => {\n          maxTimer = null;\n          if (timer) {\n            clearTimeout(timer);\n            timer = null;\n          }\n          invoke();\n        }, maxWait);\n      }\n    });\n  }\n\n  debounced.cancel = (): void => {\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    if (maxTimer) {\n      clearTimeout(maxTimer);\n      maxTimer = null;\n    }\n    lastArgs = null;\n    isPending = false;\n    // Reject all pending resolvers\n    const resolvers = pendingResolvers.splice(0);\n    for (const r of resolvers) {\n      r.reject(new Error('Debounced call cancelled'));\n    }\n  };\n\n  debounced.flush = async (): Promise<TReturn | undefined> => {\n    if (!isPending) return undefined;\n    const promise = new Promise<TReturn>((resolve, reject) => {\n      pendingResolvers.push({ resolve, reject });\n    });\n    await invoke();\n    return promise;\n  };\n\n  Object.defineProperty(debounced, 'pending', {\n    get() {\n      return isPending;\n    },\n  });\n\n  return debounced as DebouncedFunction<TArgs, TReturn>;\n}\n"]}

package/dist/deferred.d.mts

@@ -0,0 +1,27 @@
+interface Deferred<T> {
+    /** The underlying promise */
+    promise: Promise<T>;
+    /** Resolve the deferred */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /** Reject the deferred */
+    reject: (reason?: any) => void;
+    /** Whether the deferred has been settled */
+    readonly isSettled: boolean;
+    /** Whether the deferred was resolved */
+    readonly isResolved: boolean;
+    /** Whether the deferred was rejected */
+    readonly isRejected: boolean;
+}
+/**
+ * Create a deferred promise — a promise whose resolve/reject are externally accessible.
+ *
+ * @example
+ * ```ts
+ * const deferred = createDeferred<string>();
+ * setTimeout(() => deferred.resolve('done'), 1000);
+ * const result = await deferred.promise; // 'done'
+ * ```
+ */
+declare function createDeferred<T = void>(): Deferred<T>;
+
+export { type Deferred, createDeferred };

package/dist/deferred.d.ts

@@ -0,0 +1,27 @@
+interface Deferred<T> {
+    /** The underlying promise */
+    promise: Promise<T>;
+    /** Resolve the deferred */
+    resolve: (value: T | PromiseLike<T>) => void;
+    /** Reject the deferred */
+    reject: (reason?: any) => void;
+    /** Whether the deferred has been settled */
+    readonly isSettled: boolean;
+    /** Whether the deferred was resolved */
+    readonly isResolved: boolean;
+    /** Whether the deferred was rejected */
+    readonly isRejected: boolean;
+}
+/**
+ * Create a deferred promise — a promise whose resolve/reject are externally accessible.
+ *
+ * @example
+ * ```ts
+ * const deferred = createDeferred<string>();
+ * setTimeout(() => deferred.resolve('done'), 1000);
+ * const result = await deferred.promise; // 'done'
+ * ```
+ */
+declare function createDeferred<T = void>(): Deferred<T>;
+
+export { type Deferred, createDeferred };

package/dist/deferred.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// src/deferred.ts
+function createDeferred() {
+  let isSettled = false;
+  let isResolved = false;
+  let isRejected = false;
+  let resolveFn;
+  let rejectFn;
+  const promise = new Promise((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+  });
+  return {
+    promise,
+    resolve: (value) => {
+      if (isSettled) return;
+      isSettled = true;
+      isResolved = true;
+      resolveFn(value);
+    },
+    reject: (reason) => {
+      if (isSettled) return;
+      isSettled = true;
+      isRejected = true;
+      rejectFn(reason);
+    },
+    get isSettled() {
+      return isSettled;
+    },
+    get isResolved() {
+      return isResolved;
+    },
+    get isRejected() {
+      return isRejected;
+    }
+  };
+}
+
+exports.createDeferred = createDeferred;
+//# sourceMappingURL=deferred.js.map
+//# sourceMappingURL=deferred.js.map

package/dist/deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/deferred.ts"],"names":[],"mappings":";;;AA6BO,SAAS,cAAA,GAAwC;AACtD,EAAA,IAAI,SAAA,GAAY,KAAA;AAChB,EAAA,IAAI,UAAA,GAAa,KAAA;AACjB,EAAA,IAAI,UAAA,GAAa,KAAA;AACjB,EAAA,IAAI,SAAA;AACJ,EAAA,IAAI,QAAA;AAEJ,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAW,CAAC,SAAS,MAAA,KAAW;AAClD,IAAA,SAAA,GAAY,OAAA;AACZ,IAAA,QAAA,GAAW,MAAA;AAAA,EACb,CAAC,CAAA;AAED,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,OAAA,EAAS,CAAC,KAAA,KAA8B;AACtC,MAAA,IAAI,SAAA,EAAW;AACf,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,UAAA,GAAa,IAAA;AACb,MAAA,SAAA,CAAU,KAAK,CAAA;AAAA,IACjB,CAAA;AAAA,IACA,MAAA,EAAQ,CAAC,MAAA,KAAiB;AACxB,MAAA,IAAI,SAAA,EAAW;AACf,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,UAAA,GAAa,IAAA;AACb,MAAA,QAAA,CAAS,MAAM,CAAA;AAAA,IACjB,CAAA;AAAA,IACA,IAAI,SAAA,GAAY;AACd,MAAA,OAAO,SAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,UAAA,GAAa;AACf,MAAA,OAAO,UAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,UAAA,GAAa;AACf,MAAA,OAAO,UAAA;AAAA,IACT;AAAA,GACF;AACF","file":"deferred.js","sourcesContent":["// ============================================================================\n// FlowX — Deferred Promise\n// ============================================================================\n\nexport interface Deferred<T> {\n  /** The underlying promise */\n  promise: Promise<T>;\n  /** Resolve the deferred */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Reject the deferred */\n  reject: (reason?: any) => void;\n  /** Whether the deferred has been settled */\n  readonly isSettled: boolean;\n  /** Whether the deferred was resolved */\n  readonly isResolved: boolean;\n  /** Whether the deferred was rejected */\n  readonly isRejected: boolean;\n}\n\n/**\n * Create a deferred promise — a promise whose resolve/reject are externally accessible.\n *\n * @example\n * ```ts\n * const deferred = createDeferred<string>();\n * setTimeout(() => deferred.resolve('done'), 1000);\n * const result = await deferred.promise; // 'done'\n * ```\n */\nexport function createDeferred<T = void>(): Deferred<T> {\n  let isSettled = false;\n  let isResolved = false;\n  let isRejected = false;\n  let resolveFn!: (value: T | PromiseLike<T>) => void;\n  let rejectFn!: (reason?: any) => void;\n\n  const promise = new Promise<T>((resolve, reject) => {\n    resolveFn = resolve;\n    rejectFn = reject;\n  });\n\n  return {\n    promise,\n    resolve: (value: T | PromiseLike<T>) => {\n      if (isSettled) return;\n      isSettled = true;\n      isResolved = true;\n      resolveFn(value);\n    },\n    reject: (reason?: any) => {\n      if (isSettled) return;\n      isSettled = true;\n      isRejected = true;\n      rejectFn(reason);\n    },\n    get isSettled() {\n      return isSettled;\n    },\n    get isResolved() {\n      return isResolved;\n    },\n    get isRejected() {\n      return isRejected;\n    },\n  };\n}\n"]}

package/dist/deferred.mjs

@@ -0,0 +1,40 @@
+// src/deferred.ts
+function createDeferred() {
+  let isSettled = false;
+  let isResolved = false;
+  let isRejected = false;
+  let resolveFn;
+  let rejectFn;
+  const promise = new Promise((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+  });
+  return {
+    promise,
+    resolve: (value) => {
+      if (isSettled) return;
+      isSettled = true;
+      isResolved = true;
+      resolveFn(value);
+    },
+    reject: (reason) => {
+      if (isSettled) return;
+      isSettled = true;
+      isRejected = true;
+      rejectFn(reason);
+    },
+    get isSettled() {
+      return isSettled;
+    },
+    get isResolved() {
+      return isResolved;
+    },
+    get isRejected() {
+      return isRejected;
+    }
+  };
+}
+
+export { createDeferred };
+//# sourceMappingURL=deferred.mjs.map
+//# sourceMappingURL=deferred.mjs.map

package/dist/deferred.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/deferred.ts"],"names":[],"mappings":";AA6BO,SAAS,cAAA,GAAwC;AACtD,EAAA,IAAI,SAAA,GAAY,KAAA;AAChB,EAAA,IAAI,UAAA,GAAa,KAAA;AACjB,EAAA,IAAI,UAAA,GAAa,KAAA;AACjB,EAAA,IAAI,SAAA;AACJ,EAAA,IAAI,QAAA;AAEJ,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAW,CAAC,SAAS,MAAA,KAAW;AAClD,IAAA,SAAA,GAAY,OAAA;AACZ,IAAA,QAAA,GAAW,MAAA;AAAA,EACb,CAAC,CAAA;AAED,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,OAAA,EAAS,CAAC,KAAA,KAA8B;AACtC,MAAA,IAAI,SAAA,EAAW;AACf,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,UAAA,GAAa,IAAA;AACb,MAAA,SAAA,CAAU,KAAK,CAAA;AAAA,IACjB,CAAA;AAAA,IACA,MAAA,EAAQ,CAAC,MAAA,KAAiB;AACxB,MAAA,IAAI,SAAA,EAAW;AACf,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,UAAA,GAAa,IAAA;AACb,MAAA,QAAA,CAAS,MAAM,CAAA;AAAA,IACjB,CAAA;AAAA,IACA,IAAI,SAAA,GAAY;AACd,MAAA,OAAO,SAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,UAAA,GAAa;AACf,MAAA,OAAO,UAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,UAAA,GAAa;AACf,MAAA,OAAO,UAAA;AAAA,IACT;AAAA,GACF;AACF","file":"deferred.mjs","sourcesContent":["// ============================================================================\n// FlowX — Deferred Promise\n// ============================================================================\n\nexport interface Deferred<T> {\n  /** The underlying promise */\n  promise: Promise<T>;\n  /** Resolve the deferred */\n  resolve: (value: T | PromiseLike<T>) => void;\n  /** Reject the deferred */\n  reject: (reason?: any) => void;\n  /** Whether the deferred has been settled */\n  readonly isSettled: boolean;\n  /** Whether the deferred was resolved */\n  readonly isResolved: boolean;\n  /** Whether the deferred was rejected */\n  readonly isRejected: boolean;\n}\n\n/**\n * Create a deferred promise — a promise whose resolve/reject are externally accessible.\n *\n * @example\n * ```ts\n * const deferred = createDeferred<string>();\n * setTimeout(() => deferred.resolve('done'), 1000);\n * const result = await deferred.promise; // 'done'\n * ```\n */\nexport function createDeferred<T = void>(): Deferred<T> {\n  let isSettled = false;\n  let isResolved = false;\n  let isRejected = false;\n  let resolveFn!: (value: T | PromiseLike<T>) => void;\n  let rejectFn!: (reason?: any) => void;\n\n  const promise = new Promise<T>((resolve, reject) => {\n    resolveFn = resolve;\n    rejectFn = reject;\n  });\n\n  return {\n    promise,\n    resolve: (value: T | PromiseLike<T>) => {\n      if (isSettled) return;\n      isSettled = true;\n      isResolved = true;\n      resolveFn(value);\n    },\n    reject: (reason?: any) => {\n      if (isSettled) return;\n      isSettled = true;\n      isRejected = true;\n      rejectFn(reason);\n    },\n    get isSettled() {\n      return isSettled;\n    },\n    get isResolved() {\n      return isResolved;\n    },\n    get isRejected() {\n      return isRejected;\n    },\n  };\n}\n"]}

package/dist/fallback.d.mts

@@ -0,0 +1,33 @@
+interface FallbackOptions {
+    /** Predicate to determine if the error warrants a fallback */
+    shouldFallback?: (error: Error) => boolean;
+    /** Callback fired when the primary function fails and fallback is used */
+    onFallback?: (error: Error, fallbackIndex: number) => void;
+}
+/**
+ * Execute a function with a fallback value or function if it fails.
+ *
+ * @example
+ * ```ts
+ * const data = await withFallback(
+ *   () => fetch('/primary-api'),
+ *   'default-value',
+ * );
+ * ```
+ */
+declare function withFallback<T>(fn: () => T | Promise<T>, fallback: T | (() => T | Promise<T>), options?: FallbackOptions): Promise<T>;
+/**
+ * Execute the first successful function from a chain of fallbacks.
+ *
+ * @example
+ * ```ts
+ * const data = await fallbackChain([
+ *   () => fetch('/primary'),
+ *   () => fetch('/secondary'),
+ *   () => fetch('/tertiary'),
+ * ]);
+ * ```
+ */
+declare function fallbackChain<T>(fns: Array<() => T | Promise<T>>, options?: FallbackOptions): Promise<T>;
+
+export { type FallbackOptions, fallbackChain, withFallback };

package/dist/fallback.d.ts

@@ -0,0 +1,33 @@
+interface FallbackOptions {
+    /** Predicate to determine if the error warrants a fallback */
+    shouldFallback?: (error: Error) => boolean;
+    /** Callback fired when the primary function fails and fallback is used */
+    onFallback?: (error: Error, fallbackIndex: number) => void;
+}
+/**
+ * Execute a function with a fallback value or function if it fails.
+ *
+ * @example
+ * ```ts
+ * const data = await withFallback(
+ *   () => fetch('/primary-api'),
+ *   'default-value',
+ * );
+ * ```
+ */
+declare function withFallback<T>(fn: () => T | Promise<T>, fallback: T | (() => T | Promise<T>), options?: FallbackOptions): Promise<T>;
+/**
+ * Execute the first successful function from a chain of fallbacks.
+ *
+ * @example
+ * ```ts
+ * const data = await fallbackChain([
+ *   () => fetch('/primary'),
+ *   () => fetch('/secondary'),
+ *   () => fetch('/tertiary'),
+ * ]);
+ * ```
+ */
+declare function fallbackChain<T>(fns: Array<() => T | Promise<T>>, options?: FallbackOptions): Promise<T>;
+
+export { type FallbackOptions, fallbackChain, withFallback };