awaitly 2.0.0 → 3.0.0

package/dist/reliability.js

@@ -0,0 +1,1589 @@
+// src/slugs.ts
+var AWAITLY_SLUGS = {
+  // --- step-* ---
+  "step-require-id": "step-require-id",
+  "step-no-immediate-execution": "step-no-immediate-execution",
+  "step-require-thunk-for-key": "step-require-thunk-for-key",
+  "step-no-bare-await": "step-no-bare-await",
+  "step-no-try-catch-wrap": "step-no-try-catch-wrap",
+  "step-stable-cache-keys": "step-stable-cache-keys",
+  // --- workflow-* ---
+  "workflow-no-floating": "workflow-no-floating",
+  "workflow-options-position": "workflow-options-position",
+  "workflow-callback-shape": "workflow-callback-shape",
+  "workflow-no-callable-form": "workflow-no-callable-form",
+  "workflow-no-dynamic-import": "workflow-no-dynamic-import",
+  "workflow-prefer-step-if": "workflow-prefer-step-if",
+  "workflow-prefer-step-foreach": "workflow-prefer-step-foreach",
+  // --- result-* ---
+  "result-no-floating": "result-no-floating",
+  "result-require-handling": "result-require-handling",
+  "result-no-double-wrap": "result-no-double-wrap",
+  "result-no-manual-propagation": "result-no-manual-propagation",
+  "result-no-direct-ok-err": "result-no-direct-ok-err",
+  // --- error-* ---
+  "error-check-unexpected-first": "error-check-unexpected-first",
+  "error-access-cause": "error-access-cause",
+  "error-normalize": "error-normalize",
+  "error-no-throw-in-deps": "error-no-throw-in-deps",
+  // --- concurrency-* ---
+  "concurrency-no-promise-all": "concurrency-no-promise-all",
+  "concurrency-no-promise-race": "concurrency-no-promise-race",
+  "concurrency-no-promise-allsettled": "concurrency-no-promise-allsettled",
+  // --- runtime-* ---
+  "runtime-step-timeout": "runtime-step-timeout",
+  "runtime-step-aborted": "runtime-step-aborted",
+  "runtime-retry-exhausted": "runtime-retry-exhausted",
+  "runtime-rate-limit": "runtime-rate-limit",
+  "runtime-circuit-open": "runtime-circuit-open",
+  "runtime-unexpected": "runtime-unexpected",
+  "runtime-resolver-not-found": "runtime-resolver-not-found",
+  "runtime-saga-compensation": "runtime-saga-compensation"
+};
+function slugDocsUrl(slug) {
+  return `https://jagreehal.github.io/awaitly/rules/#${slug}`;
+}
+var ALL_SLUGS = Object.keys(
+  AWAITLY_SLUGS
+);
+
+// src/tagged-error.ts
+var InternalTaggedErrorBase = class extends Error {
+  type;
+  /** @deprecated Use `type`. */
+  _tag;
+};
+function TaggedError(tag, options) {
+  return class extends InternalTaggedErrorBase {
+    type = tag;
+    /** @deprecated Use `type`. */
+    _tag = tag;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(props, errorOptions) {
+      const message = options?.message ? options.message(props ?? {}) : tag;
+      super(message);
+      this.name = tag;
+      if (options?.slug !== void 0) {
+        if (!options.hint) {
+          throw new TypeError(
+            `TaggedError: 'hint' is required when 'slug' is set (slug: "${options.slug}")`
+          );
+        }
+        Object.defineProperty(this, "code", {
+          value: options.slug,
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+        Object.defineProperty(this, "hint", {
+          value: options.hint,
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+        Object.defineProperty(this, "docsUrl", {
+          value: slugDocsUrl(options.slug),
+          enumerable: true,
+          writable: false,
+          configurable: false
+        });
+      }
+      Object.setPrototypeOf(this, new.target.prototype);
+      if (props && typeof props === "object") {
+        let safeProps;
+        if (options?.slug !== void 0) {
+          const {
+            _tag: _,
+            type: _t,
+            name: _n,
+            message: _m,
+            stack: _s,
+            code: _c,
+            hint: _h,
+            docsUrl: _d,
+            ...rest
+          } = props;
+          safeProps = rest;
+        } else {
+          const {
+            _tag: _,
+            type: _t,
+            name: _n,
+            message: _m,
+            stack: _s,
+            ...rest
+          } = props;
+          safeProps = rest;
+        }
+        const hasUserCause = Object.prototype.hasOwnProperty.call(
+          safeProps,
+          "cause"
+        );
+        const userCause = hasUserCause ? safeProps.cause : void 0;
+        if (hasUserCause) {
+          delete safeProps.cause;
+        }
+        const hasOptionsCause = errorOptions?.cause !== void 0;
+        if (hasUserCause && hasOptionsCause) {
+          throw new TypeError(
+            "TaggedError: cannot provide 'cause' in props when also setting ErrorOptions.cause"
+          );
+        }
+        Object.assign(this, safeProps);
+        if (hasUserCause) {
+          this.cause = userCause;
+        }
+        if (hasOptionsCause) {
+          this.cause = errorOptions?.cause;
+        }
+      } else if (errorOptions?.cause !== void 0) {
+        this.cause = errorOptions.cause;
+      }
+    }
+  };
+}
+Object.defineProperty(TaggedError, Symbol.hasInstance, {
+  value: (instance) => instance instanceof InternalTaggedErrorBase
+});
+((TaggedError2) => {
+  function isError(value) {
+    return value instanceof Error;
+  }
+  TaggedError2.isError = isError;
+  function isTaggedError(value) {
+    return value instanceof InternalTaggedErrorBase;
+  }
+  TaggedError2.isTaggedError = isTaggedError;
+  function match(error, handlers) {
+    const tag = error._tag;
+    const handler = handlers[tag];
+    return handler(
+      error
+    );
+  }
+  TaggedError2.match = match;
+  function matchPartial(error, handlers, otherwise) {
+    const tag = error._tag;
+    const handler = handlers[tag];
+    if (handler) {
+      return handler(
+        error
+      );
+    }
+    return otherwise(error);
+  }
+  TaggedError2.matchPartial = matchPartial;
+})(TaggedError || (TaggedError = {}));
+
+// src/errors.ts
+var TimeoutError = class extends (/* @__PURE__ */ TaggedError("TimeoutError", {
+  slug: "runtime-step-timeout",
+  hint: "Increase the step's timeout option, or check why the upstream operation is slow.",
+  message: (p) => p.operation ? `TimeoutError: ${p.operation} timed out after ${p.ms}ms` : `TimeoutError: Operation timed out after ${p.ms}ms`
+})) {
+};
+var UnexpectedError = class extends (/* @__PURE__ */ TaggedError("UnexpectedError", {
+  slug: "runtime-unexpected",
+  hint: "An unexpected exception escaped a step. Inspect cause; consider returning a typed Result instead of throwing.",
+  message: (p) => `UnexpectedError: ${p.cause instanceof Error ? p.cause.message : String(p.cause ?? "unknown")}`
+})) {
+};
+
+// src/result/index.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error, options) {
+  const cause = options?.cause;
+  return { ok: false, error, ...cause !== void 0 ? { cause } : {} };
+}
+
+// src/duration.ts
+function millis(ms) {
+  return { _tag: "Duration", millis: ms };
+}
+function seconds(s) {
+  return { _tag: "Duration", millis: s * 1e3 };
+}
+function minutes(m) {
+  return { _tag: "Duration", millis: m * 60 * 1e3 };
+}
+function hours(h) {
+  return { _tag: "Duration", millis: h * 60 * 60 * 1e3 };
+}
+function days(d) {
+  return { _tag: "Duration", millis: d * 24 * 60 * 60 * 1e3 };
+}
+function toMillis(duration) {
+  return duration.millis;
+}
+function parse(input) {
+  const match = input.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
+  if (!match) return void 0;
+  const value = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "ms":
+      return millis(value);
+    case "s":
+      return seconds(value);
+    case "m":
+      return minutes(value);
+    case "h":
+      return hours(value);
+    case "d":
+      return days(value);
+    default:
+      return void 0;
+  }
+}
+
+// src/core/bound-steps.ts
+var isDepResultShaped = (value) => typeof value === "object" && value !== null && "ok" in value && typeof value.ok === "boolean" && (value.ok ? "value" in value : "error" in value);
+
+// src/core/policies.ts
+var toMs = (d) => typeof d === "number" ? d : toMillis(d);
+var attemptCall = async (fn, args) => {
+  try {
+    const value = await fn(...args);
+    if (isDepResultShaped(value)) {
+      return value.ok ? { kind: "ok", value: value.value } : { kind: "err", error: value.error, result: value };
+    }
+    return { kind: "ok", value };
+  } catch (thrown) {
+    return { kind: "threw", thrown };
+  }
+};
+var named = (wrapped, source) => {
+  const name = source.name;
+  if (name) {
+    Object.defineProperty(wrapped, "name", { value: name, configurable: true });
+  }
+  return wrapped;
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function retry(fn, options) {
+  const attempts = Math.max(1, Math.trunc(options.attempts));
+  const baseDelay = options.delay === void 0 ? 0 : toMs(options.delay);
+  const maxDelay = options.maxDelay === void 0 ? Infinity : toMs(options.maxDelay);
+  const backoff = options.backoff ?? "fixed";
+  const delayFor = (attempt) => {
+    const raw = backoff === "exponential" ? baseDelay * 2 ** (attempt - 1) : backoff === "linear" ? baseDelay * attempt : baseDelay;
+    return Math.min(raw, maxDelay);
+  };
+  const wrapped = async (...args) => {
+    let last = { kind: "threw", thrown: void 0 };
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      last = await attemptCall(fn, args);
+      if (last.kind === "ok") return ok(last.value);
+      const failure = last.kind === "err" ? last.error : last.thrown;
+      if (options.retryIf && !options.retryIf(failure)) break;
+      if (attempt < attempts) {
+        options.onRetry?.({ attempt, failure });
+        const ms = delayFor(attempt);
+        if (ms > 0) await sleep(ms);
+      }
+    }
+    if (last.kind === "err") return last.result;
+    throw last.thrown;
+  };
+  return named(wrapped, fn);
+}
+function timeout(fn, after) {
+  const ms = toMs(after);
+  const TIMED_OUT = /* @__PURE__ */ Symbol("timed-out");
+  const wrapped = async (...args) => {
+    let timer;
+    try {
+      const outcome = await Promise.race([
+        attemptCall(fn, args),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(TIMED_OUT), ms);
+        })
+      ]);
+      if (outcome === TIMED_OUT) {
+        return err(new TimeoutError({ operation: fn.name || void 0, ms }));
+      }
+      if (outcome.kind === "ok") return ok(outcome.value);
+      if (outcome.kind === "err") return outcome.result;
+      throw outcome.thrown;
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  };
+  return named(wrapped, fn);
+}
+function fallback(fn, onFailure) {
+  const wrapped = async (...args) => {
+    const outcome = await attemptCall(fn, args);
+    if (outcome.kind === "ok") return ok(outcome.value);
+    const failure = outcome.kind === "err" ? outcome.error : new UnexpectedError({ cause: outcome.thrown });
+    const recovered = await attemptCall(onFailure, [failure, ...args]);
+    if (recovered.kind === "ok") return ok(recovered.value);
+    if (recovered.kind === "err") return recovered.result;
+    throw recovered.thrown;
+  };
+  return named(wrapped, fn);
+}
+
+// src/core/index.ts
+function err2(error, options) {
+  const cause = options?.cause;
+  return { ok: false, error, ...cause !== void 0 ? { cause } : {} };
+}
+
+// src/circuit-breaker.ts
+var CircuitOpenError = class extends Error {
+  type = "CIRCUIT_OPEN";
+  circuitName;
+  state;
+  retryAfterMs;
+  constructor(options) {
+    super(
+      options.message ?? `Circuit breaker "${options.circuitName}" is ${options.state}. Retry after ${Math.ceil(options.retryAfterMs / 1e3)}s`
+    );
+    this.name = "CircuitOpenError";
+    this.circuitName = options.circuitName;
+    this.state = options.state;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
+function isCircuitOpenError(error) {
+  return typeof error === "object" && error !== null && error.type === "CIRCUIT_OPEN";
+}
+var DEFAULT_CONFIG = {
+  failureThreshold: 5,
+  resetTimeout: 3e4,
+  windowSize: 6e4,
+  halfOpenMax: 3
+};
+function createCircuitBreaker(name, config) {
+  const effectiveConfig = {
+    ...DEFAULT_CONFIG,
+    ...config
+  };
+  let state = "CLOSED";
+  let failures = [];
+  let lastFailureTime = null;
+  let lastSuccessTime = null;
+  let successCount = 0;
+  let halfOpenSuccesses = 0;
+  function cleanupFailures() {
+    const now = Date.now();
+    failures = failures.filter(
+      (f) => now - f.timestamp < effectiveConfig.windowSize
+    );
+  }
+  function transitionTo(newState) {
+    if (state !== newState) {
+      const oldState = state;
+      state = newState;
+      if (newState === "HALF_OPEN") {
+        halfOpenSuccesses = 0;
+      }
+      effectiveConfig.onStateChange?.(oldState, newState, name);
+    }
+  }
+  function checkOpenToHalfOpen() {
+    if (state !== "OPEN" || lastFailureTime === null) {
+      return false;
+    }
+    const now = Date.now();
+    if (now - lastFailureTime >= effectiveConfig.resetTimeout) {
+      transitionTo("HALF_OPEN");
+      return true;
+    }
+    return false;
+  }
+  function handleSuccess() {
+    lastSuccessTime = Date.now();
+    successCount++;
+    if (state === "HALF_OPEN") {
+      halfOpenSuccesses++;
+      if (halfOpenSuccesses >= effectiveConfig.halfOpenMax) {
+        transitionTo("CLOSED");
+        failures = [];
+      }
+    }
+  }
+  function handleFailure(error) {
+    const now = Date.now();
+    lastFailureTime = now;
+    cleanupFailures();
+    failures.push({ timestamp: now, error });
+    if (state === "HALF_OPEN") {
+      transitionTo("OPEN");
+    } else if (state === "CLOSED") {
+      if (failures.length >= effectiveConfig.failureThreshold) {
+        transitionTo("OPEN");
+      }
+    }
+  }
+  function canExecute() {
+    if (state === "CLOSED") {
+      return 0;
+    }
+    if (state === "OPEN") {
+      if (checkOpenToHalfOpen()) {
+        return 0;
+      }
+      const now = Date.now();
+      const elapsed = lastFailureTime ? now - lastFailureTime : 0;
+      return Math.max(0, effectiveConfig.resetTimeout - elapsed);
+    }
+    return 0;
+  }
+  return {
+    async execute(operation, _options) {
+      const waitTime = canExecute();
+      if (waitTime > 0) {
+        throw new CircuitOpenError({
+          circuitName: name,
+          state,
+          retryAfterMs: waitTime
+        });
+      }
+      try {
+        const result = await operation();
+        handleSuccess();
+        return result;
+      } catch (error) {
+        handleFailure(error);
+        throw error;
+      }
+    },
+    async executeResult(operation, _options) {
+      const waitTime = canExecute();
+      if (waitTime > 0) {
+        return err2(
+          new CircuitOpenError({
+            circuitName: name,
+            state,
+            retryAfterMs: waitTime
+          })
+        );
+      }
+      try {
+        const result = await operation();
+        if (result.ok) {
+          handleSuccess();
+        } else {
+          handleFailure(result.error);
+        }
+        return result;
+      } catch (error) {
+        handleFailure(error);
+        throw error;
+      }
+    },
+    getState() {
+      if (state === "OPEN") {
+        checkOpenToHalfOpen();
+      }
+      return state;
+    },
+    getStats() {
+      cleanupFailures();
+      return {
+        state: this.getState(),
+        failureCount: failures.length,
+        successCount,
+        lastFailureTime,
+        lastSuccessTime,
+        halfOpenSuccesses
+      };
+    },
+    reset() {
+      transitionTo("CLOSED");
+      failures = [];
+      halfOpenSuccesses = 0;
+    },
+    forceOpen() {
+      lastFailureTime = Date.now();
+      transitionTo("OPEN");
+    },
+    recordSuccess() {
+      handleSuccess();
+    },
+    recordFailure(error) {
+      handleFailure(error ?? new Error("Manual failure"));
+    }
+  };
+}
+var circuitBreakerPresets = {
+  /**
+   * Aggressive circuit breaker for critical paths.
+   * Opens quickly (3 failures) and recovers slowly (60s).
+   */
+  critical: {
+    failureThreshold: 3,
+    resetTimeout: 6e4,
+    windowSize: 3e4,
+    halfOpenMax: 1
+  },
+  /**
+   * Standard circuit breaker for typical API calls.
+   * Balanced between stability and availability.
+   */
+  standard: {
+    failureThreshold: 5,
+    resetTimeout: 3e4,
+    windowSize: 6e4,
+    halfOpenMax: 3
+  },
+  /**
+   * Lenient circuit breaker for non-critical operations.
+   * Opens slowly (10 failures) and recovers quickly (15s).
+   */
+  lenient: {
+    failureThreshold: 10,
+    resetTimeout: 15e3,
+    windowSize: 12e4,
+    halfOpenMax: 5
+  }
+};
+
+// src/rate-limiter/index.ts
+function isRateLimitExceededError(error) {
+  return typeof error === "object" && error !== null && error.type === "RATE_LIMIT_EXCEEDED";
+}
+function isQueueFullError(error) {
+  return typeof error === "object" && error !== null && error.type === "QUEUE_FULL";
+}
+function createRateLimiter(name, config) {
+  const { maxPerSecond, strategy = "wait" } = config;
+  const maxTokens = config.burstCapacity ?? maxPerSecond * 2;
+  let tokens = maxTokens;
+  let lastRefill = Date.now();
+  const refillRate = maxPerSecond / 1e3;
+  const waitQueue = [];
+  function refill() {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+    const tokensToAdd = elapsed * refillRate;
+    tokens = Math.min(maxTokens, tokens + tokensToAdd);
+    lastRefill = now;
+  }
+  function tryConsume() {
+    refill();
+    if (tokens >= 1) {
+      tokens -= 1;
+      return 0;
+    }
+    const tokensNeeded = 1 - tokens;
+    return Math.ceil(tokensNeeded / refillRate);
+  }
+  async function waitForToken() {
+    return new Promise((resolve) => {
+      const check = () => {
+        const waitTime = tryConsume();
+        if (waitTime === 0) {
+          resolve();
+        } else {
+          waitQueue.push(check);
+          setTimeout(() => {
+            const idx = waitQueue.indexOf(check);
+            if (idx !== -1) {
+              waitQueue.splice(idx, 1);
+              check();
+            }
+          }, waitTime);
+        }
+      };
+      check();
+    });
+  }
+  return {
+    async execute(operation) {
+      const waitTime = tryConsume();
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          throw {
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          };
+        }
+        await waitForToken();
+      }
+      return operation();
+    },
+    async executeResult(operation) {
+      const waitTime = tryConsume();
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          return err2({
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          });
+        }
+        await waitForToken();
+      }
+      return operation();
+    },
+    getStats() {
+      refill();
+      return {
+        availableTokens: Math.floor(tokens),
+        maxTokens,
+        tokensPerSecond: maxPerSecond,
+        waitingCount: waitQueue.length
+      };
+    },
+    reset() {
+      tokens = maxTokens;
+      lastRefill = Date.now();
+      waitQueue.length = 0;
+    }
+  };
+}
+function createConcurrencyLimiter(name, config) {
+  const { maxConcurrent, strategy = "queue", maxQueueSize = Infinity } = config;
+  let activeCount = 0;
+  const queue = [];
+  async function acquire() {
+    if (activeCount < maxConcurrent) {
+      activeCount++;
+      return;
+    }
+    if (strategy === "reject") {
+      throw {
+        type: "QUEUE_FULL",
+        limiterName: name,
+        queueSize: queue.length,
+        maxQueueSize
+      };
+    }
+    if (queue.length >= maxQueueSize) {
+      throw {
+        type: "QUEUE_FULL",
+        limiterName: name,
+        queueSize: queue.length,
+        maxQueueSize
+      };
+    }
+    return new Promise((resolve, reject) => {
+      queue.push({ resolve, reject });
+    });
+  }
+  function release() {
+    activeCount--;
+    if (queue.length > 0 && activeCount < maxConcurrent) {
+      activeCount++;
+      const next = queue.shift();
+      next?.resolve();
+    }
+  }
+  return {
+    async execute(operation) {
+      await acquire();
+      try {
+        return await operation();
+      } finally {
+        release();
+      }
+    },
+    async executeAll(operations) {
+      const results = new Array(operations.length);
+      const executing = [];
+      for (let i = 0; i < operations.length; i++) {
+        const index = i;
+        const promise = this.execute(operations[index]).then((result) => {
+          results[index] = result;
+        });
+        executing.push(promise);
+      }
+      await Promise.all(executing);
+      return results;
+    },
+    async executeResult(operation) {
+      try {
+        await acquire();
+      } catch (error) {
+        if (isQueueFullError(error)) {
+          return err2(error);
+        }
+        throw error;
+      }
+      try {
+        return await operation();
+      } finally {
+        release();
+      }
+    },
+    getStats() {
+      return {
+        activeCount,
+        maxConcurrent,
+        queueSize: queue.length,
+        maxQueueSize
+      };
+    },
+    reset() {
+      activeCount = 0;
+      while (queue.length > 0) {
+        const item = queue.shift();
+        item?.reject(new Error("Limiter reset"));
+      }
+    }
+  };
+}
+function createCombinedLimiter(name, config) {
+  const rate = config.rate ? createRateLimiter(`${name}-rate`, config.rate) : void 0;
+  const concurrency = config.concurrency ? createConcurrencyLimiter(`${name}-concurrency`, config.concurrency) : void 0;
+  return {
+    rate,
+    concurrency,
+    async execute(operation) {
+      let op = operation;
+      if (rate) {
+        const originalOp = op;
+        op = () => rate.execute(originalOp);
+      }
+      if (concurrency) {
+        return concurrency.execute(op);
+      }
+      return op();
+    }
+  };
+}
+function createFixedWindowLimiter(name, config) {
+  const { limit, windowMs = 1e3, strategy = "wait" } = config;
+  let windowStart = Date.now();
+  let requestCount = 0;
+  const waitQueue = [];
+  function checkWindow() {
+    const now = Date.now();
+    const elapsed = now - windowStart;
+    if (elapsed >= windowMs) {
+      windowStart = now;
+      requestCount = 0;
+      return 0;
+    }
+    return windowMs - elapsed;
+  }
+  function tryConsume(cost) {
+    const remainingMs = checkWindow();
+    if (requestCount + cost <= limit) {
+      requestCount += cost;
+      return 0;
+    }
+    return remainingMs;
+  }
+  async function waitForWindow(cost) {
+    return new Promise((resolve) => {
+      const check = () => {
+        const waitTime = tryConsume(cost);
+        if (waitTime === 0) {
+          resolve();
+        } else {
+          waitQueue.push({ resolve: check, cost });
+          setTimeout(() => {
+            const idx = waitQueue.findIndex((w) => w.resolve === check);
+            if (idx !== -1) {
+              waitQueue.splice(idx, 1);
+              check();
+            }
+          }, waitTime);
+        }
+      };
+      check();
+    });
+  }
+  return {
+    async execute(operation, cost = 1) {
+      if (cost > limit) {
+        throw {
+          type: "RATE_LIMIT_EXCEEDED",
+          limiterName: name,
+          retryAfterMs: windowMs
+        };
+      }
+      const waitTime = tryConsume(cost);
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          throw {
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          };
+        }
+        await waitForWindow(cost);
+      }
+      return operation();
+    },
+    async executeResult(operation, cost = 1) {
+      if (cost > limit) {
+        return err2({
+          type: "RATE_LIMIT_EXCEEDED",
+          limiterName: name,
+          retryAfterMs: windowMs
+        });
+      }
+      const waitTime = tryConsume(cost);
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          return err2({
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          });
+        }
+        await waitForWindow(cost);
+      }
+      return operation();
+    },
+    getStats() {
+      const remainingMs = checkWindow();
+      return {
+        requestCount,
+        limit,
+        windowMs,
+        remainingMs,
+        waitingCount: waitQueue.length
+      };
+    },
+    reset() {
+      windowStart = Date.now();
+      requestCount = 0;
+      waitQueue.length = 0;
+    }
+  };
+}
+function createCostBasedRateLimiter(name, config) {
+  const { tokensPerSecond, strategy = "wait" } = config;
+  const maxTokens = config.maxTokens ?? tokensPerSecond * 2;
+  let tokens = maxTokens;
+  let lastRefill = Date.now();
+  const refillRate = tokensPerSecond / 1e3;
+  const waitQueue = [];
+  function refill() {
+    const now = Date.now();
+    const elapsed = now - lastRefill;
+    const tokensToAdd = elapsed * refillRate;
+    tokens = Math.min(maxTokens, tokens + tokensToAdd);
+    lastRefill = now;
+  }
+  function tryConsume(cost) {
+    refill();
+    if (tokens >= cost) {
+      tokens -= cost;
+      return 0;
+    }
+    const tokensNeeded = cost - tokens;
+    return Math.ceil(tokensNeeded / refillRate);
+  }
+  async function waitForTokens(cost) {
+    return new Promise((resolve) => {
+      const check = () => {
+        const waitTime = tryConsume(cost);
+        if (waitTime === 0) {
+          resolve();
+        } else {
+          waitQueue.push({ check, cost });
+          setTimeout(() => {
+            const idx = waitQueue.findIndex((w) => w.check === check);
+            if (idx !== -1) {
+              waitQueue.splice(idx, 1);
+              check();
+            }
+          }, waitTime);
+        }
+      };
+      check();
+    });
+  }
+  return {
+    async execute(operation, cost = 1) {
+      if (cost > maxTokens) {
+        throw {
+          type: "RATE_LIMIT_EXCEEDED",
+          limiterName: name,
+          retryAfterMs: Math.ceil(cost / refillRate)
+        };
+      }
+      const waitTime = tryConsume(cost);
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          throw {
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          };
+        }
+        await waitForTokens(cost);
+      }
+      return operation();
+    },
+    async executeResult(operation, cost = 1) {
+      if (cost > maxTokens) {
+        return err2({
+          type: "RATE_LIMIT_EXCEEDED",
+          limiterName: name,
+          retryAfterMs: Math.ceil(cost / refillRate)
+        });
+      }
+      const waitTime = tryConsume(cost);
+      if (waitTime > 0) {
+        if (strategy === "reject") {
+          return err2({
+            type: "RATE_LIMIT_EXCEEDED",
+            limiterName: name,
+            retryAfterMs: waitTime
+          });
+        }
+        await waitForTokens(cost);
+      }
+      return operation();
+    },
+    getStats() {
+      refill();
+      return {
+        availableTokens: tokens,
+        maxTokens,
+        tokensPerSecond,
+        waitingCount: waitQueue.length
+      };
+    },
+    reset() {
+      tokens = maxTokens;
+      lastRefill = Date.now();
+      waitQueue.length = 0;
+    }
+  };
+}
+var rateLimiterPresets = {
+  /**
+   * Typical API rate limit (10 req/s).
+   */
+  api: {
+    maxPerSecond: 10,
+    burstCapacity: 20,
+    strategy: "wait"
+  },
+  /**
+   * Database pool limit (concurrent connections).
+   */
+  database: {
+    maxConcurrent: 10,
+    strategy: "queue",
+    maxQueueSize: 100
+  },
+  /**
+   * Aggressive rate limit for external APIs (5 req/s).
+   */
+  external: {
+    maxPerSecond: 5,
+    burstCapacity: 10,
+    strategy: "wait"
+  }
+};
+
+// src/cache.ts
+function toMs2(duration) {
+  if (typeof duration === "string") {
+    const parsed = parse(duration);
+    if (!parsed) {
+      throw new Error(`Invalid duration string: ${duration}`);
+    }
+    return parsed.millis;
+  }
+  return duration.millis;
+}
+function cached(fn) {
+  let state = { status: "empty" };
+  return async () => {
+    if (state.status === "filled") {
+      return state.value;
+    }
+    if (state.status === "pending") {
+      return state.promise;
+    }
+    const promise = Promise.resolve(fn()).then((value) => {
+      state = { status: "filled", value };
+      return value;
+    });
+    state = { status: "pending", promise };
+    return promise;
+  };
+}
+function cachedWithTTL(fn, options) {
+  const ttlMs = toMs2(options.ttl);
+  let state = { status: "empty" };
+  return async () => {
+    const now = Date.now();
+    if (state.status === "filled" && now < state.expiresAt) {
+      return state.value;
+    }
+    if (state.status === "pending") {
+      return state.promise;
+    }
+    const promise = Promise.resolve(fn()).then((value) => {
+      state = {
+        status: "filled",
+        value,
+        expiresAt: Date.now() + ttlMs
+      };
+      return value;
+    });
+    state = { status: "pending", promise };
+    return promise;
+  };
+}
+function cachedFunction(fn, options = {}) {
+  const {
+    keyFn = (...args) => JSON.stringify(args),
+    maxSize = Infinity
+  } = options;
+  const ttlMs = options.ttl ? toMs2(options.ttl) : void 0;
+  const cache = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  let hits = 0;
+  let misses = 0;
+  function evictOldest() {
+    if (cache.size <= maxSize) return;
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [key, entry] of cache.entries()) {
+      if (entry.timestamp < oldestTime) {
+        oldestTime = entry.timestamp;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey) {
+      cache.delete(oldestKey);
+    }
+  }
+  const memoized = async (...args) => {
+    const key = keyFn(...args);
+    const now = Date.now();
+    const cached2 = cache.get(key);
+    if (cached2) {
+      if (cached2.expiresAt && now >= cached2.expiresAt) {
+        cache.delete(key);
+      } else {
+        hits++;
+        return cached2.value;
+      }
+    }
+    const pendingPromise = pending.get(key);
+    if (pendingPromise) {
+      return pendingPromise;
+    }
+    misses++;
+    const promise = Promise.resolve(fn(...args)).then((value) => {
+      const entry = {
+        value,
+        timestamp: Date.now(),
+        expiresAt: ttlMs ? Date.now() + ttlMs : void 0
+      };
+      cache.set(key, entry);
+      pending.delete(key);
+      evictOldest();
+      return value;
+    });
+    pending.set(key, promise);
+    try {
+      return await promise;
+    } catch (error) {
+      pending.delete(key);
+      throw error;
+    }
+  };
+  memoized.clear = () => {
+    cache.clear();
+    pending.clear();
+  };
+  memoized.delete = (...args) => {
+    const key = keyFn(...args);
+    return cache.delete(key);
+  };
+  memoized.has = (...args) => {
+    const key = keyFn(...args);
+    const entry = cache.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt && Date.now() >= entry.expiresAt) {
+      cache.delete(key);
+      return false;
+    }
+    return true;
+  };
+  memoized.getStats = () => ({
+    hits,
+    misses,
+    size: cache.size
+  });
+  return memoized;
+}
+function once(fn) {
+  let state = { status: "idle" };
+  const onceFn = async () => {
+    if (state.status === "done") {
+      return state.value;
+    }
+    if (state.status === "failed") {
+      throw state.error;
+    }
+    if (state.status === "running") {
+      return state.promise;
+    }
+    const promise = Promise.resolve(fn()).then((value) => {
+      state = { status: "done", value };
+      return value;
+    }).catch((error) => {
+      state = { status: "failed", error };
+      throw error;
+    });
+    state = { status: "running", promise };
+    return promise;
+  };
+  Object.defineProperty(onceFn, "called", {
+    get: () => state.status !== "idle"
+  });
+  Object.defineProperty(onceFn, "completed", {
+    get: () => state.status === "done"
+  });
+  Object.defineProperty(onceFn, "failed", {
+    get: () => state.status === "failed"
+  });
+  onceFn.reset = () => {
+    state = { status: "idle" };
+  };
+  return onceFn;
+}
+function createCache(config = {}) {
+  const { maxSize = Infinity } = config;
+  const defaultTTLMs = config.defaultTTL ? toMs2(config.defaultTTL) : void 0;
+  const store = /* @__PURE__ */ new Map();
+  let hits = 0;
+  let misses = 0;
+  function isExpired(entry) {
+    return entry.expiresAt !== void 0 && Date.now() >= entry.expiresAt;
+  }
+  function evictOldest() {
+    if (store.size <= maxSize) return;
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [key, entry] of store.entries()) {
+      if (entry.timestamp < oldestTime) {
+        oldestTime = entry.timestamp;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== null) {
+      store.delete(oldestKey);
+    }
+  }
+  return {
+    get(key) {
+      const entry = store.get(key);
+      if (!entry) {
+        misses++;
+        return void 0;
+      }
+      if (isExpired(entry)) {
+        store.delete(key);
+        misses++;
+        return void 0;
+      }
+      hits++;
+      return entry.value;
+    },
+    set(key, value, options) {
+      const ttlMs = options?.ttl ? toMs2(options.ttl) : defaultTTLMs;
+      const now = Date.now();
+      store.set(key, {
+        value,
+        timestamp: now,
+        expiresAt: ttlMs ? now + ttlMs : void 0
+      });
+      evictOldest();
+    },
+    has(key) {
+      const entry = store.get(key);
+      if (!entry) return false;
+      if (isExpired(entry)) {
+        store.delete(key);
+        return false;
+      }
+      return true;
+    },
+    delete(key) {
+      return store.delete(key);
+    },
+    clear() {
+      store.clear();
+    },
+    get size() {
+      return store.size;
+    },
+    getStats() {
+      return { hits, misses, size: store.size };
+    }
+  };
+}
+
+// src/singleflight.ts
+function singleflight(operation, options) {
+  const inflight = /* @__PURE__ */ new Map();
+  const cache = options.ttl ? /* @__PURE__ */ new Map() : null;
+  return async (...args) => {
+    const key = options.key(...args);
+    if (cache) {
+      const cached2 = cache.get(key);
+      if (cached2 && cached2.expiresAt > Date.now()) {
+        return cached2.result;
+      }
+      if (cached2) {
+        cache.delete(key);
+      }
+    }
+    const existing = inflight.get(key);
+    if (existing) {
+      return existing;
+    }
+    const promise = operation(...args).then((result) => {
+      if (cache && options.ttl && result.ok) {
+        cache.set(key, {
+          result,
+          expiresAt: Date.now() + options.ttl
+        });
+      }
+      return result;
+    }).finally(() => {
+      inflight.delete(key);
+    });
+    inflight.set(key, promise);
+    return promise;
+  };
+}
+function createSingleflightGroup() {
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    execute: async (key, operation) => {
+      const existing = inflight.get(key);
+      if (existing) {
+        return existing;
+      }
+      const promise = operation().then((result) => result).finally(() => {
+        inflight.delete(key);
+      });
+      inflight.set(key, promise);
+      return promise;
+    },
+    isInflight: (key) => inflight.has(key),
+    size: () => inflight.size,
+    clear: () => inflight.clear()
+  };
+}
+
+// src/policies.ts
+function mergePolicies(...policies) {
+  const result = {};
+  for (const policy of policies) {
+    if (policy.key !== void 0) result.key = policy.key;
+    if (policy.retry !== void 0) {
+      result.retry = result.retry ? { ...result.retry, ...policy.retry } : { ...policy.retry };
+    }
+    if (policy.timeout !== void 0) {
+      result.timeout = result.timeout ? { ...result.timeout, ...policy.timeout } : { ...policy.timeout };
+    }
+  }
+  return result;
+}
+function createPolicyApplier(...basePolicies) {
+  const basePolicy = mergePolicies(...basePolicies);
+  return (stepOptions2) => {
+    const opts = stepOptions2 ?? {};
+    return mergePolicies(basePolicy, opts);
+  };
+}
+function createPolicyBundle(name, ...policies) {
+  return {
+    name,
+    policy: mergePolicies(...policies)
+  };
+}
+function retryPolicy(options) {
+  return { retry: options };
+}
+var retryPolicies = {
+  /**
+   * No retry - fail immediately on error.
+   */
+  none: retryPolicy({ attempts: 1 }),
+  /**
+   * Quick retry for transient errors (3 attempts, fast backoff).
+   */
+  transient: retryPolicy({
+    attempts: 3,
+    backoff: "exponential",
+    initialDelay: 100,
+    maxDelay: 1e3,
+    jitter: true
+  }),
+  /**
+   * Standard retry for API calls (3 attempts, moderate backoff).
+   */
+  standard: retryPolicy({
+    attempts: 3,
+    backoff: "exponential",
+    initialDelay: 200,
+    maxDelay: 5e3,
+    jitter: true
+  }),
+  /**
+   * Aggressive retry for critical operations (5 attempts, longer backoff).
+   */
+  aggressive: retryPolicy({
+    attempts: 5,
+    backoff: "exponential",
+    initialDelay: 500,
+    maxDelay: 3e4,
+    jitter: true
+  }),
+  /**
+   * Fixed interval retry (useful for polling).
+   */
+  fixed: (attempts, delayMs) => retryPolicy({
+    attempts,
+    backoff: "fixed",
+    initialDelay: delayMs,
+    jitter: false
+  }),
+  /**
+   * Linear backoff retry.
+   */
+  linear: (attempts, initialDelay) => retryPolicy({
+    attempts,
+    backoff: "linear",
+    initialDelay,
+    jitter: true
+  }),
+  /**
+   * Custom retry policy builder.
+   */
+  custom: (options) => retryPolicy({
+    backoff: "exponential",
+    initialDelay: 100,
+    maxDelay: 3e4,
+    jitter: true,
+    ...options
+  })
+};
+function timeoutPolicy(options) {
+  return { timeout: options };
+}
+var timeoutPolicies = {
+  /**
+   * No timeout.
+   */
+  none: {},
+  /**
+   * Fast timeout for quick operations (1 second).
+   */
+  fast: timeoutPolicy({ ms: 1e3 }),
+  /**
+   * Standard API timeout (5 seconds).
+   */
+  api: timeoutPolicy({ ms: 5e3 }),
+  /**
+   * Extended timeout for slower operations (30 seconds).
+   */
+  extended: timeoutPolicy({ ms: 3e4 }),
+  /**
+   * Long timeout for batch operations (2 minutes).
+   */
+  long: timeoutPolicy({ ms: 12e4 }),
+  /**
+   * Custom timeout in milliseconds.
+   */
+  ms: (ms) => timeoutPolicy({ ms }),
+  /**
+   * Custom timeout in seconds.
+   */
+  seconds: (seconds2) => timeoutPolicy({ ms: seconds2 * 1e3 }),
+  /**
+   * Timeout with custom error.
+   */
+  withError: (ms, error) => timeoutPolicy({ ms, error }),
+  /**
+   * Timeout with AbortSignal support.
+   */
+  withSignal: (ms) => timeoutPolicy({ ms, signal: true })
+};
+var servicePolicies = {
+  /**
+   * Policy for external HTTP APIs.
+   * - 5 second timeout
+   * - 3 retries with exponential backoff
+   */
+  httpApi: mergePolicies(
+    timeoutPolicies.api,
+    retryPolicies.standard
+  ),
+  /**
+   * Policy for database operations.
+   * - 30 second timeout
+   * - 2 retries for transient errors
+   */
+  database: mergePolicies(
+    timeoutPolicies.extended,
+    retryPolicy({
+      attempts: 2,
+      backoff: "exponential",
+      initialDelay: 100,
+      maxDelay: 2e3,
+      jitter: true
+    })
+  ),
+  /**
+   * Policy for cache operations.
+   * - 1 second timeout
+   * - No retry (cache misses are not errors)
+   */
+  cache: mergePolicies(
+    timeoutPolicies.fast,
+    retryPolicies.none
+  ),
+  /**
+   * Policy for message queue operations.
+   * - 30 second timeout
+   * - 5 retries with longer backoff
+   */
+  messageQueue: mergePolicies(
+    timeoutPolicies.extended,
+    retryPolicies.aggressive
+  ),
+  /**
+   * Policy for file operations.
+   * - 2 minute timeout
+   * - 3 retries
+   */
+  fileSystem: mergePolicies(
+    timeoutPolicies.long,
+    retryPolicies.standard
+  ),
+  /**
+   * Policy for third-party services with rate limits.
+   * - 10 second timeout
+   * - 5 retries with linear backoff
+   */
+  rateLimited: mergePolicies(
+    timeoutPolicy({ ms: 1e4 }),
+    retryPolicy({
+      attempts: 5,
+      backoff: "linear",
+      initialDelay: 1e3,
+      maxDelay: 1e4,
+      jitter: true
+    })
+  )
+};
+function withPolicy(policy, stepOptions2) {
+  const opts = stepOptions2 ?? {};
+  return mergePolicies(policy, opts);
+}
+function withPolicies(policies, stepOptions2) {
+  const opts = stepOptions2 ?? {};
+  return mergePolicies(...policies, opts);
+}
+function conditionalPolicy(condition, policy, elsePolicy = {}) {
+  return condition ? policy : elsePolicy;
+}
+function envPolicy(envPolicies, currentEnv = process.env.NODE_ENV ?? "development", defaultPolicy = {}) {
+  return envPolicies[currentEnv] ?? defaultPolicy;
+}
+function createPolicyRegistry() {
+  const policies = /* @__PURE__ */ new Map();
+  return {
+    register(name, policy) {
+      policies.set(name, policy);
+    },
+    get(name) {
+      return policies.get(name);
+    },
+    has(name) {
+      return policies.has(name);
+    },
+    names() {
+      return Array.from(policies.keys());
+    },
+    apply(policyName, stepOptions2) {
+      const policy = policies.get(policyName);
+      if (!policy) {
+        throw new Error(`Policy not found: ${policyName}`);
+      }
+      return withPolicy(policy, stepOptions2);
+    }
+  };
+}
+function stepOptions() {
+  const policies = [];
+  const builder = {
+    key(key) {
+      policies.push({ key });
+      return builder;
+    },
+    policy(policy) {
+      policies.push(policy);
+      return builder;
+    },
+    timeout(ms) {
+      policies.push(timeoutPolicy({ ms }));
+      return builder;
+    },
+    retry(options) {
+      policies.push(retryPolicy(options));
+      return builder;
+    },
+    retries(attempts) {
+      policies.push(retryPolicies.custom({ attempts }));
+      return builder;
+    },
+    build() {
+      return mergePolicies(...policies);
+    }
+  };
+  return builder;
+}
+export {
+  CircuitOpenError,
+  cached,
+  cachedFunction,
+  cachedWithTTL,
+  circuitBreakerPresets,
+  conditionalPolicy,
+  createCache,
+  createCircuitBreaker,
+  createCombinedLimiter,
+  createConcurrencyLimiter,
+  createCostBasedRateLimiter,
+  createFixedWindowLimiter,
+  createPolicyApplier,
+  createPolicyBundle,
+  createPolicyRegistry,
+  createRateLimiter,
+  createSingleflightGroup,
+  envPolicy,
+  fallback,
+  isCircuitOpenError,
+  isQueueFullError,
+  isRateLimitExceededError,
+  mergePolicies,
+  once,
+  rateLimiterPresets,
+  retry,
+  retryPolicies,
+  retryPolicy,
+  servicePolicies,
+  singleflight,
+  stepOptions,
+  timeout,
+  timeoutPolicies,
+  timeoutPolicy,
+  withPolicies,
+  withPolicy
+};
+//# sourceMappingURL=reliability.js.map