flowx-control 1.0.0

package/dist/retry.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// 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 AbortError = class extends FlowXError {
+  constructor(message = "Operation aborted") {
+    super(message, "ERR_ABORTED");
+    this.name = "AbortError";
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError());
+      return;
+    }
+    let onAbort;
+    const timer = setTimeout(() => {
+      if (signal && onAbort) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve();
+    }, ms);
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        reject(new AbortError());
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function calculateDelay(attempt, baseDelay, strategy, jitter = false) {
+  let delay;
+  if (typeof strategy === "function") {
+    delay = strategy(attempt, baseDelay);
+  } else {
+    switch (strategy) {
+      case "fixed":
+        delay = baseDelay;
+        break;
+      case "linear":
+        delay = baseDelay * attempt;
+        break;
+      case "exponential":
+        delay = baseDelay * Math.pow(2, attempt - 1);
+        break;
+    }
+  }
+  if (jitter) {
+    const factor = typeof jitter === "number" ? jitter : 1;
+    delay = delay * (1 - factor * 0.5 + Math.random() * factor);
+  }
+  return Math.max(0, Math.floor(delay));
+}
+
+// src/retry.ts
+async function retry(fn, options) {
+  const {
+    retries = 3,
+    delay = 1e3,
+    backoff = "exponential",
+    jitter = false,
+    maxDelay = 3e4,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options ?? {};
+  if (retries < 0) {
+    throw new RangeError("retries must be >= 0");
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (signal?.aborted) {
+      throw new AbortError("Retry aborted");
+    }
+    try {
+      const result = await fn();
+      return result;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt === retries) break;
+      if (shouldRetry) {
+        const shouldContinue = await shouldRetry(lastError, attempt + 1);
+        if (!shouldContinue) break;
+      }
+      if (onRetry) {
+        await onRetry(lastError, attempt + 1);
+      }
+      let waitTime = calculateDelay(attempt + 1, delay, backoff, jitter);
+      waitTime = Math.min(waitTime, maxDelay);
+      await sleep(waitTime, signal);
+    }
+  }
+  throw lastError;
+}
+function retryable(fn, options) {
+  return (...args) => retry(() => fn(...args), options);
+}
+
+exports.retry = retry;
+exports.retryable = retryable;
+//# sourceMappingURL=retry.js.map
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/retry.ts"],"names":[],"mappings":";;;AAmBO,IAAM,UAAA,GAAN,cAAyB,KAAA,CAAM;AAAA,EAEpC,WAAA,CAAY,SAAiB,IAAA,EAAc;AACzC,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF,CAAA;AA2BO,IAAM,UAAA,GAAN,cAAyB,UAAA,CAAW;AAAA,EACzC,WAAA,CAAY,UAAU,mBAAA,EAAqB;AACzC,IAAA,KAAA,CAAM,SAAS,aAAa,CAAA;AAC5B,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AAAA,EACd;AACF,CAAA;AAaO,SAAS,KAAA,CAAM,IAAY,MAAA,EAAqC;AACrE,EAAA,OAAO,IAAI,OAAA,CAAc,CAAC,OAAA,EAAS,MAAA,KAAW;AAC5C,IAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,MAAA,MAAA,CAAO,IAAI,YAAY,CAAA;AACvB,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,OAAA;AAEJ,IAAA,MAAM,KAAA,GAAQ,WAAW,MAAM;AAC7B,MAAA,IAAI,UAAU,OAAA,EAAS;AACrB,QAAA,MAAA,CAAO,mBAAA,CAAoB,SAAS,OAAO,CAAA;AAAA,MAC7C;AACA,MAAA,OAAA,EAAQ;AAAA,IACV,GAAG,EAAE,CAAA;AAEL,IAAA,IAAI,MAAA,EAAQ;AACV,MAAA,OAAA,GAAU,MAAM;AACd,QAAA,YAAA,CAAa,KAAK,CAAA;AAClB,QAAA,MAAA,CAAO,IAAI,YAAY,CAAA;AAAA,MACzB,CAAA;AACA,MAAA,MAAA,CAAO,iBAAiB,OAAA,EAAS,OAAA,EAAS,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,IAC1D;AAAA,EACF,CAAC,CAAA;AACH;AAGO,SAAS,cAAA,CACd,OAAA,EACA,SAAA,EACA,QAAA,EACA,SAA2B,KAAA,EACnB;AACR,EAAA,IAAI,KAAA;AAEJ,EAAA,IAAI,OAAO,aAAa,UAAA,EAAY;AAClC,IAAA,KAAA,GAAQ,QAAA,CAAS,SAAS,SAAS,CAAA;AAAA,EACrC,CAAA,MAAO;AACL,IAAA,QAAQ,QAAA;AAAU,MAChB,KAAK,OAAA;AACH,QAAA,KAAA,GAAQ,SAAA;AACR,QAAA;AAAA,MACF,KAAK,QAAA;AACH,QAAA,KAAA,GAAQ,SAAA,GAAY,OAAA;AACpB,QAAA;AAAA,MACF,KAAK,aAAA;AACH,QAAA,KAAA,GAAQ,SAAA,GAAY,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,UAAU,CAAC,CAAA;AAC3C,QAAA;AAAA;AACJ,EACF;AAEA,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,MAAM,MAAA,GAAS,OAAO,MAAA,KAAW,QAAA,GAAW,MAAA,GAAS,CAAA;AACrD,IAAA,KAAA,GAAQ,SAAS,CAAA,GAAI,MAAA,GAAS,GAAA,GAAM,IAAA,CAAK,QAAO,GAAI,MAAA,CAAA;AAAA,EACtD;AAEA,EAAA,OAAO,KAAK,GAAA,CAAI,CAAA,EAAG,IAAA,CAAK,KAAA,CAAM,KAAK,CAAC,CAAA;AACtC;;;AC7FA,eAAsB,KAAA,CAAS,IAA0B,OAAA,EAAoC;AAC3F,EAAA,MAAM;AAAA,IACJ,OAAA,GAAU,CAAA;AAAA,IACV,KAAA,GAAQ,GAAA;AAAA,IACR,OAAA,GAAU,aAAA;AAAA,IACV,MAAA,GAAS,KAAA;AAAA,IACT,QAAA,GAAW,GAAA;AAAA,IACX,WAAA;AAAA,IACA,OAAA;AAAA,IACA;AAAA,GACF,GAAI,WAAW,EAAC;AAEhB,EAAA,IAAI,UAAU,CAAA,EAAG;AACf,IAAA,MAAM,IAAI,WAAW,sBAAsB,CAAA;AAAA,EAC7C;AAEA,EAAA,IAAI,SAAA;AAEJ,EAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,OAAA,EAAS,OAAA,EAAA,EAAW;AACnD,IAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,MAAA,MAAM,IAAI,WAAW,eAAe,CAAA;AAAA,IACtC;AAEA,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,MAAM,EAAA,EAAG;AACxB,MAAA,OAAO,MAAA;AAAA,IACT,SAAS,KAAA,EAAO;AACd,MAAA,SAAA,GAAY,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC,CAAA;AAEpE,MAAA,IAAI,YAAY,OAAA,EAAS;AAEzB,MAAA,IAAI,WAAA,EAAa;AACf,QAAA,MAAM,cAAA,GAAiB,MAAM,WAAA,CAAY,SAAA,EAAW,UAAU,CAAC,CAAA;AAC/D,QAAA,IAAI,CAAC,cAAA,EAAgB;AAAA,MACvB;AAEA,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,MAAM,OAAA,CAAQ,SAAA,EAAW,OAAA,GAAU,CAAC,CAAA;AAAA,MACtC;AAEA,MAAA,IAAI,WAAW,cAAA,CAAe,OAAA,GAAU,CAAA,EAAG,KAAA,EAAO,SAAS,MAAM,CAAA;AACjE,MAAA,QAAA,GAAW,IAAA,CAAK,GAAA,CAAI,QAAA,EAAU,QAAQ,CAAA;AAEtC,MAAA,MAAM,KAAA,CAAM,UAAU,MAAM,CAAA;AAAA,IAC9B;AAAA,EACF;AAEA,EAAA,MAAM,SAAA;AACR;AAWO,SAAS,SAAA,CACd,IACA,OAAA,EACsC;AACtC,EAAA,OAAO,CAAA,GAAI,SAAgB,KAAA,CAAM,MAAM,GAAG,GAAG,IAAI,GAAG,OAAO,CAAA;AAC7D","file":"retry.js","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 — Retry with Advanced Backoff Strategies\n// ============================================================================\nimport { AbortError, BackoffStrategy, calculateDelay, sleep } from './types';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  retries?: number;\n  /** Base delay in ms between retries (default: 1000) */\n  delay?: number;\n  /** Backoff strategy (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Add randomized jitter to delays (default: false) */\n  jitter?: boolean | number;\n  /** Maximum delay cap in ms (default: 30000) */\n  maxDelay?: number;\n  /** Custom predicate to decide if retry should happen */\n  shouldRetry?: (error: Error, attempt: number) => boolean | Promise<boolean>;\n  /** Callback fired before each retry */\n  onRetry?: (error: Error, attempt: number) => void | Promise<void>;\n  /** AbortSignal for cancellation */\n  signal?: AbortSignal;\n}\n\n/**\n * Execute an async function with automatic retry and configurable backoff.\n *\n * @example\n * ```ts\n * const data = await retry(() => fetch('/api/data'), {\n *   retries: 5,\n *   backoff: 'exponential',\n *   jitter: true,\n * });\n * ```\n */\nexport async function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T> {\n  const {\n    retries = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    jitter = false,\n    maxDelay = 30000,\n    shouldRetry,\n    onRetry,\n    signal,\n  } = options ?? {};\n\n  if (retries < 0) {\n    throw new RangeError('retries must be >= 0');\n  }\n\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= retries; attempt++) {\n    if (signal?.aborted) {\n      throw new AbortError('Retry aborted');\n    }\n\n    try {\n      const result = await fn();\n      return result;\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      if (attempt === retries) break;\n\n      if (shouldRetry) {\n        const shouldContinue = await shouldRetry(lastError, attempt + 1);\n        if (!shouldContinue) break;\n      }\n\n      if (onRetry) {\n        await onRetry(lastError, attempt + 1);\n      }\n\n      let waitTime = calculateDelay(attempt + 1, delay, backoff, jitter);\n      waitTime = Math.min(waitTime, maxDelay);\n\n      await sleep(waitTime, signal);\n    }\n  }\n\n  throw lastError!;\n}\n\n/**\n * Wrap a function to automatically retry on failure.\n *\n * @example\n * ```ts\n * const safeFetch = retryable(fetch, { retries: 3 });\n * const data = await safeFetch('/api/data');\n * ```\n */\nexport function retryable<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options?: RetryOptions,\n): (...args: TArgs) => Promise<TReturn> {\n  return (...args: TArgs) => retry(() => fn(...args), options);\n}\n"]}

package/dist/retry.mjs

@@ -0,0 +1,108 @@
+// 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 AbortError = class extends FlowXError {
+  constructor(message = "Operation aborted") {
+    super(message, "ERR_ABORTED");
+    this.name = "AbortError";
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError());
+      return;
+    }
+    let onAbort;
+    const timer = setTimeout(() => {
+      if (signal && onAbort) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve();
+    }, ms);
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        reject(new AbortError());
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function calculateDelay(attempt, baseDelay, strategy, jitter = false) {
+  let delay;
+  if (typeof strategy === "function") {
+    delay = strategy(attempt, baseDelay);
+  } else {
+    switch (strategy) {
+      case "fixed":
+        delay = baseDelay;
+        break;
+      case "linear":
+        delay = baseDelay * attempt;
+        break;
+      case "exponential":
+        delay = baseDelay * Math.pow(2, attempt - 1);
+        break;
+    }
+  }
+  if (jitter) {
+    const factor = typeof jitter === "number" ? jitter : 1;
+    delay = delay * (1 - factor * 0.5 + Math.random() * factor);
+  }
+  return Math.max(0, Math.floor(delay));
+}
+
+// src/retry.ts
+async function retry(fn, options) {
+  const {
+    retries = 3,
+    delay = 1e3,
+    backoff = "exponential",
+    jitter = false,
+    maxDelay = 3e4,
+    shouldRetry,
+    onRetry,
+    signal
+  } = options ?? {};
+  if (retries < 0) {
+    throw new RangeError("retries must be >= 0");
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (signal?.aborted) {
+      throw new AbortError("Retry aborted");
+    }
+    try {
+      const result = await fn();
+      return result;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt === retries) break;
+      if (shouldRetry) {
+        const shouldContinue = await shouldRetry(lastError, attempt + 1);
+        if (!shouldContinue) break;
+      }
+      if (onRetry) {
+        await onRetry(lastError, attempt + 1);
+      }
+      let waitTime = calculateDelay(attempt + 1, delay, backoff, jitter);
+      waitTime = Math.min(waitTime, maxDelay);
+      await sleep(waitTime, signal);
+    }
+  }
+  throw lastError;
+}
+function retryable(fn, options) {
+  return (...args) => retry(() => fn(...args), options);
+}
+
+export { retry, retryable };
+//# sourceMappingURL=retry.mjs.map
+//# sourceMappingURL=retry.mjs.map

package/dist/retry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/retry.ts"],"names":[],"mappings":"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","file":"retry.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 — Retry with Advanced Backoff Strategies\n// ============================================================================\nimport { AbortError, BackoffStrategy, calculateDelay, sleep } from './types';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  retries?: number;\n  /** Base delay in ms between retries (default: 1000) */\n  delay?: number;\n  /** Backoff strategy (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Add randomized jitter to delays (default: false) */\n  jitter?: boolean | number;\n  /** Maximum delay cap in ms (default: 30000) */\n  maxDelay?: number;\n  /** Custom predicate to decide if retry should happen */\n  shouldRetry?: (error: Error, attempt: number) => boolean | Promise<boolean>;\n  /** Callback fired before each retry */\n  onRetry?: (error: Error, attempt: number) => void | Promise<void>;\n  /** AbortSignal for cancellation */\n  signal?: AbortSignal;\n}\n\n/**\n * Execute an async function with automatic retry and configurable backoff.\n *\n * @example\n * ```ts\n * const data = await retry(() => fetch('/api/data'), {\n *   retries: 5,\n *   backoff: 'exponential',\n *   jitter: true,\n * });\n * ```\n */\nexport async function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T> {\n  const {\n    retries = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    jitter = false,\n    maxDelay = 30000,\n    shouldRetry,\n    onRetry,\n    signal,\n  } = options ?? {};\n\n  if (retries < 0) {\n    throw new RangeError('retries must be >= 0');\n  }\n\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= retries; attempt++) {\n    if (signal?.aborted) {\n      throw new AbortError('Retry aborted');\n    }\n\n    try {\n      const result = await fn();\n      return result;\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      if (attempt === retries) break;\n\n      if (shouldRetry) {\n        const shouldContinue = await shouldRetry(lastError, attempt + 1);\n        if (!shouldContinue) break;\n      }\n\n      if (onRetry) {\n        await onRetry(lastError, attempt + 1);\n      }\n\n      let waitTime = calculateDelay(attempt + 1, delay, backoff, jitter);\n      waitTime = Math.min(waitTime, maxDelay);\n\n      await sleep(waitTime, signal);\n    }\n  }\n\n  throw lastError!;\n}\n\n/**\n * Wrap a function to automatically retry on failure.\n *\n * @example\n * ```ts\n * const safeFetch = retryable(fetch, { retries: 3 });\n * const data = await safeFetch('/api/data');\n * ```\n */\nexport function retryable<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options?: RetryOptions,\n): (...args: TArgs) => Promise<TReturn> {\n  return (...args: TArgs) => retry(() => fn(...args), options);\n}\n"]}

package/dist/semaphore.d.mts

@@ -0,0 +1,27 @@
+interface Semaphore {
+    /** Acquire a permit. Returns a release function. */
+    acquire: () => Promise<() => void>;
+    /** Execute a function exclusively within the semaphore */
+    runExclusive: <T>(fn: () => T | Promise<T>) => Promise<T>;
+    /** Number of available permits */
+    readonly available: number;
+    /** Number of tasks waiting for a permit */
+    readonly waiting: number;
+}
+/**
+ * Create a counting semaphore for concurrency control.
+ *
+ * @example
+ * ```ts
+ * const sem = createSemaphore(3);
+ * const release = await sem.acquire();
+ * try {
+ *   await doWork();
+ * } finally {
+ *   release();
+ * }
+ * ```
+ */
+declare function createSemaphore(permits: number): Semaphore;
+
+export { type Semaphore, createSemaphore };

package/dist/semaphore.d.ts

@@ -0,0 +1,27 @@
+interface Semaphore {
+    /** Acquire a permit. Returns a release function. */
+    acquire: () => Promise<() => void>;
+    /** Execute a function exclusively within the semaphore */
+    runExclusive: <T>(fn: () => T | Promise<T>) => Promise<T>;
+    /** Number of available permits */
+    readonly available: number;
+    /** Number of tasks waiting for a permit */
+    readonly waiting: number;
+}
+/**
+ * Create a counting semaphore for concurrency control.
+ *
+ * @example
+ * ```ts
+ * const sem = createSemaphore(3);
+ * const release = await sem.acquire();
+ * try {
+ *   await doWork();
+ * } finally {
+ *   release();
+ * }
+ * ```
+ */
+declare function createSemaphore(permits: number): Semaphore;
+
+export { type Semaphore, createSemaphore };

package/dist/semaphore.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// src/semaphore.ts
+function createSemaphore(permits) {
+  if (permits < 1) throw new RangeError("permits must be >= 1");
+  let available = permits;
+  const waiters = [];
+  function release() {
+    available++;
+    if (waiters.length > 0) {
+      available--;
+      const next = waiters.shift();
+      next.resolve(release);
+    }
+  }
+  function acquire() {
+    if (available > 0) {
+      available--;
+      return Promise.resolve(release);
+    }
+    return new Promise((resolve) => {
+      waiters.push({ resolve });
+    });
+  }
+  async function runExclusive(fn) {
+    const releaseFn = await acquire();
+    try {
+      return await fn();
+    } finally {
+      releaseFn();
+    }
+  }
+  return {
+    acquire,
+    runExclusive,
+    get available() {
+      return available;
+    },
+    get waiting() {
+      return waiters.length;
+    }
+  };
+}
+
+exports.createSemaphore = createSemaphore;
+//# sourceMappingURL=semaphore.js.map
+//# sourceMappingURL=semaphore.js.map

package/dist/semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/semaphore.ts"],"names":[],"mappings":";;;AAiCO,SAAS,gBAAgB,OAAA,EAA4B;AAC1D,EAAA,IAAI,OAAA,GAAU,CAAA,EAAG,MAAM,IAAI,WAAW,sBAAsB,CAAA;AAE5D,EAAA,IAAI,SAAA,GAAY,OAAA;AAChB,EAAA,MAAM,UAAoB,EAAC;AAE3B,EAAA,SAAS,OAAA,GAAgB;AACvB,IAAA,SAAA,EAAA;AACA,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,MAAA,SAAA,EAAA;AACA,MAAA,MAAM,IAAA,GAAO,QAAQ,KAAA,EAAM;AAC3B,MAAA,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,IACtB;AAAA,EACF;AAEA,EAAA,SAAS,OAAA,GAA+B;AACtC,IAAA,IAAI,YAAY,CAAA,EAAG;AACjB,MAAA,SAAA,EAAA;AACA,MAAA,OAAO,OAAA,CAAQ,QAAQ,OAAO,CAAA;AAAA,IAChC;AAEA,IAAA,OAAO,IAAI,OAAA,CAAoB,CAAC,OAAA,KAAY;AAC1C,MAAA,OAAA,CAAQ,IAAA,CAAK,EAAE,OAAA,EAAS,CAAA;AAAA,IAC1B,CAAC,CAAA;AAAA,EACH;AAEA,EAAA,eAAe,aAAgB,EAAA,EAAsC;AACnE,IAAA,MAAM,SAAA,GAAY,MAAM,OAAA,EAAQ;AAChC,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,EAAA,EAAG;AAAA,IAClB,CAAA,SAAE;AACA,MAAA,SAAA,EAAU;AAAA,IACZ;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,YAAA;AAAA,IACA,IAAI,SAAA,GAAY;AACd,MAAA,OAAO,SAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,OAAA,GAAU;AACZ,MAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,IACjB;AAAA,GACF;AACF","file":"semaphore.js","sourcesContent":["// ============================================================================\n// FlowX — Counting Semaphore\n// ============================================================================\n\nexport interface Semaphore {\n  /** Acquire a permit. Returns a release function. */\n  acquire: () => Promise<() => void>;\n  /** Execute a function exclusively within the semaphore */\n  runExclusive: <T>(fn: () => T | Promise<T>) => Promise<T>;\n  /** Number of available permits */\n  readonly available: number;\n  /** Number of tasks waiting for a permit */\n  readonly waiting: number;\n}\n\ninterface Waiter {\n  resolve: (release: () => void) => void;\n}\n\n/**\n * Create a counting semaphore for concurrency control.\n *\n * @example\n * ```ts\n * const sem = createSemaphore(3);\n * const release = await sem.acquire();\n * try {\n *   await doWork();\n * } finally {\n *   release();\n * }\n * ```\n */\nexport function createSemaphore(permits: number): Semaphore {\n  if (permits < 1) throw new RangeError('permits must be >= 1');\n\n  let available = permits;\n  const waiters: Waiter[] = [];\n\n  function release(): void {\n    available++;\n    if (waiters.length > 0) {\n      available--;\n      const next = waiters.shift()!;\n      next.resolve(release);\n    }\n  }\n\n  function acquire(): Promise<() => void> {\n    if (available > 0) {\n      available--;\n      return Promise.resolve(release);\n    }\n\n    return new Promise<() => void>((resolve) => {\n      waiters.push({ resolve });\n    });\n  }\n\n  async function runExclusive<T>(fn: () => T | Promise<T>): Promise<T> {\n    const releaseFn = await acquire();\n    try {\n      return await fn();\n    } finally {\n      releaseFn();\n    }\n  }\n\n  return {\n    acquire,\n    runExclusive,\n    get available() {\n      return available;\n    },\n    get waiting() {\n      return waiters.length;\n    },\n  };\n}\n"]}

package/dist/semaphore.mjs

@@ -0,0 +1,45 @@
+// src/semaphore.ts
+function createSemaphore(permits) {
+  if (permits < 1) throw new RangeError("permits must be >= 1");
+  let available = permits;
+  const waiters = [];
+  function release() {
+    available++;
+    if (waiters.length > 0) {
+      available--;
+      const next = waiters.shift();
+      next.resolve(release);
+    }
+  }
+  function acquire() {
+    if (available > 0) {
+      available--;
+      return Promise.resolve(release);
+    }
+    return new Promise((resolve) => {
+      waiters.push({ resolve });
+    });
+  }
+  async function runExclusive(fn) {
+    const releaseFn = await acquire();
+    try {
+      return await fn();
+    } finally {
+      releaseFn();
+    }
+  }
+  return {
+    acquire,
+    runExclusive,
+    get available() {
+      return available;
+    },
+    get waiting() {
+      return waiters.length;
+    }
+  };
+}
+
+export { createSemaphore };
+//# sourceMappingURL=semaphore.mjs.map
+//# sourceMappingURL=semaphore.mjs.map

package/dist/semaphore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/semaphore.ts"],"names":[],"mappings":";AAiCO,SAAS,gBAAgB,OAAA,EAA4B;AAC1D,EAAA,IAAI,OAAA,GAAU,CAAA,EAAG,MAAM,IAAI,WAAW,sBAAsB,CAAA;AAE5D,EAAA,IAAI,SAAA,GAAY,OAAA;AAChB,EAAA,MAAM,UAAoB,EAAC;AAE3B,EAAA,SAAS,OAAA,GAAgB;AACvB,IAAA,SAAA,EAAA;AACA,IAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,MAAA,SAAA,EAAA;AACA,MAAA,MAAM,IAAA,GAAO,QAAQ,KAAA,EAAM;AAC3B,MAAA,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,IACtB;AAAA,EACF;AAEA,EAAA,SAAS,OAAA,GAA+B;AACtC,IAAA,IAAI,YAAY,CAAA,EAAG;AACjB,MAAA,SAAA,EAAA;AACA,MAAA,OAAO,OAAA,CAAQ,QAAQ,OAAO,CAAA;AAAA,IAChC;AAEA,IAAA,OAAO,IAAI,OAAA,CAAoB,CAAC,OAAA,KAAY;AAC1C,MAAA,OAAA,CAAQ,IAAA,CAAK,EAAE,OAAA,EAAS,CAAA;AAAA,IAC1B,CAAC,CAAA;AAAA,EACH;AAEA,EAAA,eAAe,aAAgB,EAAA,EAAsC;AACnE,IAAA,MAAM,SAAA,GAAY,MAAM,OAAA,EAAQ;AAChC,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,EAAA,EAAG;AAAA,IAClB,CAAA,SAAE;AACA,MAAA,SAAA,EAAU;AAAA,IACZ;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,YAAA;AAAA,IACA,IAAI,SAAA,GAAY;AACd,MAAA,OAAO,SAAA;AAAA,IACT,CAAA;AAAA,IACA,IAAI,OAAA,GAAU;AACZ,MAAA,OAAO,OAAA,CAAQ,MAAA;AAAA,IACjB;AAAA,GACF;AACF","file":"semaphore.mjs","sourcesContent":["// ============================================================================\n// FlowX — Counting Semaphore\n// ============================================================================\n\nexport interface Semaphore {\n  /** Acquire a permit. Returns a release function. */\n  acquire: () => Promise<() => void>;\n  /** Execute a function exclusively within the semaphore */\n  runExclusive: <T>(fn: () => T | Promise<T>) => Promise<T>;\n  /** Number of available permits */\n  readonly available: number;\n  /** Number of tasks waiting for a permit */\n  readonly waiting: number;\n}\n\ninterface Waiter {\n  resolve: (release: () => void) => void;\n}\n\n/**\n * Create a counting semaphore for concurrency control.\n *\n * @example\n * ```ts\n * const sem = createSemaphore(3);\n * const release = await sem.acquire();\n * try {\n *   await doWork();\n * } finally {\n *   release();\n * }\n * ```\n */\nexport function createSemaphore(permits: number): Semaphore {\n  if (permits < 1) throw new RangeError('permits must be >= 1');\n\n  let available = permits;\n  const waiters: Waiter[] = [];\n\n  function release(): void {\n    available++;\n    if (waiters.length > 0) {\n      available--;\n      const next = waiters.shift()!;\n      next.resolve(release);\n    }\n  }\n\n  function acquire(): Promise<() => void> {\n    if (available > 0) {\n      available--;\n      return Promise.resolve(release);\n    }\n\n    return new Promise<() => void>((resolve) => {\n      waiters.push({ resolve });\n    });\n  }\n\n  async function runExclusive<T>(fn: () => T | Promise<T>): Promise<T> {\n    const releaseFn = await acquire();\n    try {\n      return await fn();\n    } finally {\n      releaseFn();\n    }\n  }\n\n  return {\n    acquire,\n    runExclusive,\n    get available() {\n      return available;\n    },\n    get waiting() {\n      return waiters.length;\n    },\n  };\n}\n"]}

package/dist/throttle.d.mts

@@ -0,0 +1,25 @@
+interface ThrottleOptions {
+    /** Invoke on the leading edge (default: true) */
+    leading?: boolean;
+    /** Invoke on the trailing edge (default: true) */
+    trailing?: boolean;
+}
+interface ThrottledFunction<TArgs extends any[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** Cancel any pending trailing invocation */
+    cancel: () => void;
+    /** Whether there is a pending trailing invocation */
+    readonly pending: boolean;
+}
+/**
+ * Create a throttled version of an async function.
+ *
+ * @example
+ * ```ts
+ * const throttledSave = throttle(saveData, 1000);
+ * await throttledSave(data);
+ * ```
+ */
+declare function throttle<TArgs extends any[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, wait: number, options?: ThrottleOptions): ThrottledFunction<TArgs, TReturn>;
+
+export { type ThrottleOptions, type ThrottledFunction, throttle };

package/dist/throttle.d.ts

@@ -0,0 +1,25 @@
+interface ThrottleOptions {
+    /** Invoke on the leading edge (default: true) */
+    leading?: boolean;
+    /** Invoke on the trailing edge (default: true) */
+    trailing?: boolean;
+}
+interface ThrottledFunction<TArgs extends any[], TReturn> {
+    (...args: TArgs): Promise<TReturn>;
+    /** Cancel any pending trailing invocation */
+    cancel: () => void;
+    /** Whether there is a pending trailing invocation */
+    readonly pending: boolean;
+}
+/**
+ * Create a throttled version of an async function.
+ *
+ * @example
+ * ```ts
+ * const throttledSave = throttle(saveData, 1000);
+ * await throttledSave(data);
+ * ```
+ */
+declare function throttle<TArgs extends any[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, wait: number, options?: ThrottleOptions): ThrottledFunction<TArgs, TReturn>;
+
+export { type ThrottleOptions, type ThrottledFunction, throttle };

package/dist/throttle.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// src/throttle.ts
+function throttle(fn, wait, options) {
+  const { leading = true, trailing = true } = options ?? {};
+  if (wait < 0) throw new RangeError("wait must be >= 0");
+  let lastCallTime = null;
+  let timer = null;
+  let lastArgs = null;
+  let isPending = false;
+  const trailingResolvers = [];
+  async function invokeTrailing() {
+    const args = lastArgs;
+    const resolvers = trailingResolvers.splice(0);
+    lastArgs = null;
+    isPending = false;
+    timer = null;
+    if (!args) {
+      for (const r of resolvers) r.resolve(void 0);
+      return;
+    }
+    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 throttled(...args) {
+    const now = Date.now();
+    lastArgs = args;
+    const timeSinceLastCall = lastCallTime === null ? wait : now - lastCallTime;
+    const shouldCallLeading = leading && timeSinceLastCall >= wait;
+    if (shouldCallLeading) {
+      lastCallTime = now;
+      lastArgs = null;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      const prevResolvers = trailingResolvers.splice(0);
+      const resultPromise = (async () => {
+        try {
+          const result = await fn(...args);
+          for (const r of prevResolvers) r.resolve(result);
+          return result;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          for (const r of prevResolvers) r.reject(err);
+          throw err;
+        }
+      })();
+      if (trailing) {
+        timer = setTimeout(() => {
+          lastCallTime = Date.now();
+          invokeTrailing();
+        }, wait);
+      }
+      return resultPromise;
+    }
+    isPending = true;
+    return new Promise((resolve, reject) => {
+      trailingResolvers.push({ resolve, reject });
+      if (!timer && trailing) {
+        const remaining = wait - timeSinceLastCall;
+        timer = setTimeout(() => {
+          lastCallTime = Date.now();
+          invokeTrailing();
+        }, remaining);
+      }
+    });
+  }
+  throttled.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    lastArgs = null;
+    lastCallTime = null;
+    isPending = false;
+    const resolvers = trailingResolvers.splice(0);
+    for (const r of resolvers) {
+      r.reject(new Error("Throttled call cancelled"));
+    }
+  };
+  Object.defineProperty(throttled, "pending", {
+    get() {
+      return isPending;
+    }
+  });
+  return throttled;
+}
+
+exports.throttle = throttle;
+//# sourceMappingURL=throttle.js.map
+//# sourceMappingURL=throttle.js.map

package/dist/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/throttle.ts"],"names":[],"mappings":"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","file":"throttle.js","sourcesContent":["// ============================================================================\n// FlowX — Async-Aware Throttle\n// ============================================================================\n\nexport interface ThrottleOptions {\n  /** Invoke on the leading edge (default: true) */\n  leading?: boolean;\n  /** Invoke on the trailing edge (default: true) */\n  trailing?: boolean;\n}\n\nexport interface ThrottledFunction<TArgs extends any[], TReturn> {\n  (...args: TArgs): Promise<TReturn>;\n  /** Cancel any pending trailing invocation */\n  cancel: () => void;\n  /** Whether there is a pending trailing invocation */\n  readonly pending: boolean;\n}\n\n/**\n * Create a throttled version of an async function.\n *\n * @example\n * ```ts\n * const throttledSave = throttle(saveData, 1000);\n * await throttledSave(data);\n * ```\n */\nexport function throttle<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => TReturn | Promise<TReturn>,\n  wait: number,\n  options?: ThrottleOptions,\n): ThrottledFunction<TArgs, TReturn> {\n  const { leading = true, trailing = true } = options ?? {};\n\n  if (wait < 0) throw new RangeError('wait must be >= 0');\n\n  let lastCallTime: number | null = null;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let lastArgs: TArgs | null = null;\n  let isPending = false;\n  const trailingResolvers: Array<{\n    resolve: (value: TReturn) => void;\n    reject: (error: Error) => void;\n  }> = [];\n\n  async function invokeTrailing(): Promise<void> {\n    const args = lastArgs;\n    const resolvers = trailingResolvers.splice(0);\n    lastArgs = null;\n    isPending = false;\n    timer = null;\n\n    if (!args) {\n      /* istanbul ignore next -- resolvers is always empty here; lastArgs cleared before trailing fires */\n      for (const r of resolvers) r.resolve(undefined as TReturn);\n      return;\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 throttled(...args: TArgs): Promise<TReturn> {\n    const now = Date.now();\n    lastArgs = args;\n\n    const timeSinceLastCall = lastCallTime === null ? wait : now - lastCallTime;\n    const shouldCallLeading = leading && timeSinceLastCall >= wait;\n\n    if (shouldCallLeading) {\n      lastCallTime = now;\n      lastArgs = null;\n\n      if (timer) {\n        clearTimeout(timer);\n        timer = null;\n      }\n\n      // Resolve any pending trailing resolvers with this call's result\n      const prevResolvers = trailingResolvers.splice(0);\n\n      const resultPromise = (async () => {\n        try {\n          const result = await fn(...args);\n          for (const r of prevResolvers) r.resolve(result);\n          return result;\n        } catch (error) {\n          const err = error instanceof Error ? error : new Error(String(error));\n          /* istanbul ignore next -- prevResolvers is always empty on leading calls in normal flow */\n          for (const r of prevResolvers) r.reject(err);\n          throw err;\n        }\n      })();\n\n      if (trailing) {\n        timer = setTimeout(() => {\n          lastCallTime = Date.now();\n          invokeTrailing();\n        }, wait);\n      }\n\n      return resultPromise;\n    }\n\n    // Schedule trailing call\n    isPending = true;\n\n    return new Promise<TReturn>((resolve, reject) => {\n      trailingResolvers.push({ resolve, reject });\n\n      if (!timer && trailing) {\n        const remaining = wait - timeSinceLastCall;\n        timer = setTimeout(() => {\n          lastCallTime = Date.now();\n          invokeTrailing();\n        }, remaining);\n      }\n    });\n  }\n\n  throttled.cancel = (): void => {\n    if (timer) {\n      clearTimeout(timer);\n      timer = null;\n    }\n    lastArgs = null;\n    lastCallTime = null;\n    isPending = false;\n    const resolvers = trailingResolvers.splice(0);\n    for (const r of resolvers) {\n      r.reject(new Error('Throttled call cancelled'));\n    }\n  };\n\n  Object.defineProperty(throttled, 'pending', {\n    get() {\n      return isPending;\n    },\n  });\n\n  return throttled as ThrottledFunction<TArgs, TReturn>;\n}\n"]}