floe-guard 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -514,4 +514,33 @@ interface BudgetGuardMiddleware {
  */
 declare function budgetGuardMiddleware(guard: BudgetGuard): BudgetGuardMiddleware;
 
-export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice };
+interface RetryPlan<T> {
+    /** Operation to run for this retry attempt. */
+    call: () => T | Promise<T>;
+    /**
+     * Estimated retry cost passed to `guard.check()` before the retry runs.
+     * Leave undefined to use the guard's default last-call estimate.
+     */
+    estimatedCost?: number;
+}
+interface BudgetRetryOptions<T> {
+    /** Estimated cost for retrying the original call. */
+    estimatedCost?: number;
+    /** Total attempts, including the first call. Default: 2. */
+    maxAttempts?: number;
+    /** Choose a cheaper retry plan when `guard.advisory().nearLimit` is true. */
+    onDegrade?: (error: unknown, advisory: BudgetAdvisory) => RetryPlan<T> | Promise<RetryPlan<T> | undefined> | undefined;
+    /** Decide whether an error is retryable. Defaults to all non-budget errors. */
+    retryIf?: (error: unknown) => boolean;
+}
+/**
+ * Run `call` with budget-aware retries.
+ *
+ * The first attempt runs unchanged. If it fails with a retryable error, the
+ * helper retries as-is with ample budget, asks `onDegrade` for a cheaper plan
+ * when near the limit, and always calls `guard.check(estimatedCost)` before a
+ * retry so an over-budget retry is blocked before it runs.
+ */
+declare function withBudgetRetry<T>(guard: BudgetGuard, call: () => T | Promise<T>, options?: BudgetRetryOptions<T>): Promise<T>;
+
+export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, type BudgetRetryOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type RetryPlan, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice, withBudgetRetry };

package/dist/index.js

@@ -1624,6 +1624,42 @@ function budgetGuardMiddleware(guard) {
     }
   };
 }
+
+// src/retry.ts
+function defaultRetryIf(error) {
+  return !(error instanceof BudgetExceeded);
+}
+async function withBudgetRetry(guard, call, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 2;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError(`maxAttempts must be an integer >= 1, got ${maxAttempts}`);
+  }
+  const retryIf = options.retryIf ?? defaultRetryIf;
+  let plan = { call, estimatedCost: options.estimatedCost };
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await plan.call();
+    } catch (error) {
+      if (attempt >= maxAttempts || !retryIf(error)) {
+        throw error;
+      }
+      plan = await nextPlan(guard, error, plan, options.onDegrade);
+    }
+  }
+  throw new Error("unreachable");
+}
+async function nextPlan(guard, error, current, onDegrade) {
+  const advisory = guard.advisory();
+  if (advisory.nearLimit && onDegrade !== void 0) {
+    const degraded = await onDegrade(error, advisory);
+    if (degraded !== void 0) {
+      guard.check(degraded.estimatedCost);
+      return degraded;
+    }
+  }
+  guard.check(current.estimatedCost);
+  return current;
+}
 export {
   BudgetExceeded,
   BudgetGuard,
@@ -1634,6 +1670,7 @@ export {
   budgetGuardMiddleware,
   priceTokens,
   pricing_exports as pricing,
-  resolvePrice
+  resolvePrice,
+  withBudgetRetry
 };
 //# sourceMappingURL=index.js.map