.opencode/node_modules/effect/dist/unstable/persistence/RateLimiter.js

/**
 * Coordinates rate limits through shared persistent storage.
 *
 * The `RateLimiter` service consumes tokens for string keys using fixed-window
 * counters or token-bucket state. It can protect external APIs, enforce quotas,
 * or throttle workers across fibers and processes that share the same store.
 * This module includes helpers that fail when a limit is exceeded, return the
 * delay needed before continuing, or wrap an effect so it waits automatically.
 * It also defines the store service and in-memory or Redis-backed store layers.
 *
 * @since 4.0.0
 */
import * as Config from "../../Config.js";
import * as Context from "../../Context.js";
import * as Duration from "../../Duration.js";
import * as Effect from "../../Effect.js";
import { flow, identity } from "../../Function.js";
import * as Layer from "../../Layer.js";
import * as Schema from "../../Schema.js";
import * as Redis from "./Redis.js";
/**
 * Runtime type identifier for `RateLimiter` values.
 *
 * @category type IDs
 * @since 4.0.0
 */
export const TypeId = "~effect/persistence/RateLimiter";
/**
 * Service tag for persistent token-consumption services.
 *
 * **When to use**
 *
 * Use to access or provide rate-limit checks backed by fixed-window counters or
 * token-bucket state.
 *
 * @category services
 * @since 4.0.0
 */
export const RateLimiter = /*#__PURE__*/Context.Service(TypeId);
/**
 * Creates a `RateLimiter` from the current `RateLimiterStore`.
 *
 * **Details**
 *
 * The limiter supports fixed-window and token-bucket algorithms and either
 * fails or returns a delay when a limit is exceeded.
 *
 * @category constructors
 * @since 4.0.0
 */
export const make = /*#__PURE__*/Effect.gen(function* () {
  const store = yield* RateLimiterStore;
  return identity({
    [TypeId]: TypeId,
    consume(options) {
      const tokens = options.tokens ?? 1;
      const onExceeded = options.onExceeded ?? "fail";
      const algorithm = options.algorithm ?? "fixed-window";
      const window = Duration.max(Duration.fromInputUnsafe(options.window), Duration.millis(1));
      const windowMillis = Duration.toMillis(window);
      const refillRate = Duration.divideUnsafe(window, options.limit);
      const refillRateMillis = Duration.toMillis(refillRate);
      if (tokens > options.limit) {
        return onExceeded === "fail" ? Effect.fail(new RateLimiterError({
          reason: new RateLimitExceeded({
            key: options.key,
            retryAfter: window,
            limit: options.limit,
            remaining: 0
          })
        })) : Effect.succeed({
          delay: window,
          limit: options.limit,
          remaining: 0,
          resetAfter: window
        });
      }
      if (algorithm === "fixed-window") {
        return Effect.flatMap(store.fixedWindow({
          key: options.key,
          tokens,
          refillRate,
          limit: onExceeded === "fail" ? options.limit : undefined
        }), ([count, ttl]) => {
          if (onExceeded === "fail") {
            const remaining = options.limit - count;
            if (remaining < 0) {
              return Effect.fail(new RateLimiterError({
                reason: new RateLimitExceeded({
                  key: options.key,
                  retryAfter: Duration.millis(ttl),
                  limit: options.limit,
                  remaining: 0
                })
              }));
            }
            return Effect.succeed({
              delay: Duration.zero,
              limit: options.limit,
              remaining,
              resetAfter: Duration.millis(ttl)
            });
          }
          const ttlTotal = count * refillRateMillis;
          const elapsed = ttlTotal - ttl;
          const windowNumber = Math.floor((count - 1) / options.limit);
          const remaining = windowNumber * windowMillis - elapsed;
          const delay = remaining <= 0 ? Duration.zero : Duration.millis(remaining);
          return Effect.succeed({
            delay,
            limit: options.limit,
            remaining: options.limit - count,
            resetAfter: Duration.times(window, Math.ceil(ttl / windowMillis))
          });
        });
      }
      return Effect.flatMap(store.tokenBucket({
        key: options.key,
        tokens,
        limit: options.limit,
        refillRate,
        allowOverflow: onExceeded === "delay"
      }), remaining => {
        if (onExceeded === "fail") {
          if (remaining < 0) {
            return Effect.fail(new RateLimiterError({
              reason: new RateLimitExceeded({
                key: options.key,
                retryAfter: Duration.times(refillRate, -remaining),
                limit: options.limit,
                remaining: 0
              })
            }));
          }
          return Effect.succeed({
            delay: Duration.zero,
            limit: options.limit,
            remaining,
            resetAfter: Duration.times(refillRate, options.limit - remaining)
          });
        }
        if (remaining >= 0) {
          return Effect.succeed({
            delay: Duration.zero,
            limit: options.limit,
            remaining,
            resetAfter: Duration.times(refillRate, options.limit - remaining)
          });
        }
        return Effect.succeed({
          delay: Duration.times(refillRate, -remaining),
          limit: options.limit,
          remaining,
          resetAfter: Duration.times(refillRate, options.limit - remaining)
        });
      });
    }
  });
});
/**
 * Provides `RateLimiter` using the current `RateLimiterStore`.
 *
 * @category layers
 * @since 4.0.0
 */
export const layer = /*#__PURE__*/Layer.effect(RateLimiter, make);
/**
 * Accesses a function that applies rate limiting to an effect.
 *
 * **Example** (Applying rate limits to effects)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { RateLimiter } from "effect/unstable/persistence"
 *
 * Effect.gen(function*() {
 *   // Access the `withLimiter` function from the RateLimiter module
 *   const withLimiter = yield* RateLimiter.makeWithRateLimiter
 *
 *   // Apply a rate limiter to an effect
 *   yield* Effect.log("Making a request with rate limiting").pipe(
 *     withLimiter({
 *       key: "some-key",
 *       limit: 10,
 *       onExceeded: "delay",
 *       window: "5 seconds",
 *       algorithm: "fixed-window"
 *     })
 *   )
 * })
 * ```
 *
 * @category accessors
 * @since 4.0.0
 */
export const makeWithRateLimiter = /*#__PURE__*/RateLimiter.use(limiter => Effect.succeed(options => effect => Effect.flatMap(limiter.consume(options), ({
  delay
}) => {
  if (Duration.isZero(delay)) return effect;
  return Effect.delay(effect, delay);
})));
/**
 * Accesses a function that sleeps when the rate limit is exceeded.
 *
 * **Example** (Sleeping until rate limit permits)
 *
 * ```ts
 * import { Effect } from "effect"
 * import { RateLimiter } from "effect/unstable/persistence"
 *
 * Effect.gen(function*() {
 *   // Access the `sleep` function from the RateLimiter module
 *   const sleep = yield* RateLimiter.makeSleep
 *
 *   // Use the `sleep` function with specific rate limiting parameters.
 *   // This will only sleep if the rate limit has been exceeded.
 *   yield* sleep({
 *     key: "some-key",
 *     limit: 10,
 *     window: "5 seconds",
 *     algorithm: "fixed-window"
 *   })
 * })
 * ```
 *
 * @category accessors
 * @since 4.0.0
 */
export const makeSleep = /*#__PURE__*/RateLimiter.use(limiter => Effect.succeed(options => Effect.flatMap(limiter.consume({
  ...options,
  onExceeded: "delay"
}), result => {
  if (Duration.isZero(result.delay)) return Effect.succeed(result);
  return Effect.as(Effect.sleep(result.delay), result);
})));
/**
 * Runtime type identifier for `RateLimiterError`.
 *
 * @category type IDs
 * @since 4.0.0
 */
export const ErrorTypeId = "~@effect/experimental/RateLimiter/RateLimiterError";
/**
 * Error reason for a rate-limit check that exceeded the configured limit.
 *
 * **Details**
 *
 * Includes the affected key, limit, remaining token count, and retry delay.
 *
 * @category errors
 * @since 4.0.0
 */
export class RateLimitExceeded extends /*#__PURE__*/Schema.ErrorClass("effect/persistence/RateLimiter/RateLimitExceeded")({
  _tag: /*#__PURE__*/Schema.tag("RateLimitExceeded"),
  retryAfter: Schema.DurationFromMillis,
  key: Schema.String,
  limit: Schema.Number,
  remaining: Schema.Number
}) {
  /**
   * Public message used when the rate limiter rejects a request.
   *
   * @since 4.0.0
   */
  get message() {
    return `Rate limit exceeded`;
  }
}
/**
 * Error reason for failures in the backing `RateLimiterStore`.
 *
 * @category errors
 * @since 4.0.0
 */
export class RateLimitStoreError extends /*#__PURE__*/Schema.ErrorClass("effect/persistence/RateLimiter/RateLimitStoreError")({
  _tag: /*#__PURE__*/Schema.tag("RateLimitStoreError"),
  message: Schema.String,
  cause: /*#__PURE__*/Schema.optional(/*#__PURE__*/Schema.Defect())
}) {}
/**
 * Schema for all reasons that can be carried by `RateLimiterError`.
 *
 * @category errors
 * @since 4.0.0
 */
export const RateLimiterErrorReason = /*#__PURE__*/Schema.Union([RateLimitExceeded, RateLimitStoreError]);
/**
 * Error raised by rate limiter operations, wrapping a concrete failure
 * `reason`.
 *
 * @category errors
 * @since 4.0.0
 */
export class RateLimiterError extends /*#__PURE__*/Schema.ErrorClass(ErrorTypeId)({
  _tag: /*#__PURE__*/Schema.tag("RateLimiterError"),
  reason: RateLimiterErrorReason
}) {
  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
  constructor(props) {
    if ("cause" in props.reason) {
      super({
        ...props,
        cause: props.reason.cause
      });
    } else {
      super(props);
    }
  }
  /**
   * Marks this value as a rate limiter error for runtime guards.
   *
   * @since 4.0.0
   */
  [ErrorTypeId] = ErrorTypeId;
  get message() {
    return this.reason.message;
  }
}
/**
 * Defines the low-level backing store for fixed-window counters and token-bucket state.
 *
 * **When to use**
 *
 * Use to provide the shared counter storage used by persistent rate-limit
 * checks.
 *
 * @category store
 * @since 4.0.0
 */
export class RateLimiterStore extends /*#__PURE__*/Context.Service()("effect/persistence/RateLimiter/RateLimiterStore") {}
/**
 * Provides a process-local in-memory `RateLimiterStore`.
 *
 * @category RateLimiterStore
 * @since 4.0.0
 */
export const layerStoreMemory = /*#__PURE__*/Layer.sync(RateLimiterStore, () => {
  const fixedCounters = new Map();
  const tokenBuckets = new Map();
  return RateLimiterStore.of({
    fixedWindow: options => Effect.clockWith(clock => Effect.sync(() => {
      const refillRateMillis = Duration.toMillis(options.refillRate);
      const now = clock.currentTimeMillisUnsafe();
      let counter = fixedCounters.get(options.key);
      if (!counter || counter.expiresAt <= now) {
        counter = {
          count: 0,
          expiresAt: now
        };
        fixedCounters.set(options.key, counter);
      }
      if (options.limit && counter.count + options.tokens > options.limit) {
        return [counter.count + options.tokens, counter.expiresAt - now];
      }
      counter.count += options.tokens;
      counter.expiresAt += refillRateMillis * options.tokens;
      return [counter.count, counter.expiresAt - now];
    })),
    tokenBucket: options => Effect.clockWith(clock => Effect.sync(() => {
      const refillRateMillis = Duration.toMillis(options.refillRate);
      const now = clock.currentTimeMillisUnsafe();
      let bucket = tokenBuckets.get(options.key);
      if (!bucket) {
        bucket = {
          tokens: options.limit,
          lastRefill: now
        };
        tokenBuckets.set(options.key, bucket);
      } else {
        const elapsed = now - bucket.lastRefill;
        const tokensToAdd = Math.floor(elapsed / refillRateMillis);
        if (tokensToAdd > 0) {
          bucket.tokens = Math.min(options.limit, bucket.tokens + tokensToAdd);
          bucket.lastRefill += tokensToAdd * refillRateMillis;
        }
      }
      const newTokenCount = bucket.tokens - options.tokens;
      if (options.allowOverflow || newTokenCount >= 0) {
        bucket.tokens = newTokenCount;
      }
      return newTokenCount;
    }))
  });
});
/**
 * Creates a Redis-backed `RateLimiterStore` using Lua scripts and the
 * configured key prefix.
 *
 * @category RateLimiterStore
 * @since 4.0.0
 */
export const makeStoreRedis = /*#__PURE__*/Effect.fnUntraced(function* (options) {
  const prefix = options?.prefix ?? "ratelimiter:";
  const redis = yield* Redis.Redis;
  const fixedWindow = redis.eval(fixedWindowScript);
  const tokenBucket = redis.eval(tokenBucketScript);
  return RateLimiterStore.of({
    fixedWindow(options) {
      const key = `${prefix}${options.key}`;
      const refillMillis = Duration.toMillis(options.refillRate);
      return Effect.mapError(fixedWindow(key, options.tokens, refillMillis, options.limit), cause => new RateLimiterError({
        reason: new RateLimitStoreError({
          message: `Failed to execute fixedWindow rate limiting command`,
          cause: cause.cause
        })
      }));
    },
    tokenBucket(options) {
      const key = `${prefix}${options.key}`;
      const lastRefillKey = `${key}:refill`;
      const refillMillis = Duration.toMillis(options.refillRate);
      return Effect.clockWith(clock => Effect.mapError(tokenBucket(key, lastRefillKey, options.tokens, refillMillis, options.limit, clock.currentTimeMillisUnsafe(), options.allowOverflow ? 1 : 0), cause => new RateLimiterError({
        reason: new RateLimitStoreError({
          message: `Failed to execute tokenBucket rate limiting command`,
          cause
        })
      })));
    }
  });
});
const fixedWindowScript = /*#__PURE__*/Redis.script((key, tokens, refillMillis, limit) => [key, tokens, refillMillis, limit], {
  numberOfKeys: 1,
  lua: `
local key = KEYS[1]
local tokens = tonumber(ARGV[1])
local refillms = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local current = tonumber(redis.call("GET", key))

if not current then
  local nextpttl = refillms * tokens
  redis.call("SET", key, tokens, "PX", nextpttl)
  return { tokens, nextpttl }
end

local currentpttl = tonumber(redis.call("PTTL", key) or "0")
local next = current + tokens
if limit and next > limit then
  return { next, currentpttl }
end

local nextpttl = currentpttl + (refillms * tokens)
redis.call("SET", key, next, "PX", nextpttl)
return { next, nextpttl }
`
}).withReturnType();
const tokenBucketScript = /*#__PURE__*/Redis.script((key, lastRefillKey, tokens, refillMillis, limit, now, overflow) => [key, lastRefillKey, tokens, refillMillis, limit, now, overflow], {
  numberOfKeys: 2,
  lua: `
local key = KEYS[1]
local last_refill_key = KEYS[2]
local tokens = tonumber(ARGV[1])
local refill_ms = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
local now = tonumber(ARGV[4])
local overflow = ARGV[5] == "1"
local current = tonumber(redis.call("GET", key))
local last_refill = tonumber(redis.call("GET", last_refill_key))

if not current then current = limit end
if not last_refill then last_refill = now end

local elapsed = now - last_refill
local refill_amount = math.floor(elapsed / refill_ms)
if refill_amount > 0 then
  current = math.min(current + refill_amount, limit)
  last_refill = last_refill + (refill_amount * refill_ms)
end

local next = current - tokens
local stored = current
if next >= 0 or overflow then
  stored = next
end

local ttl = math.floor((limit - stored) * refill_ms)
if ttl < 1 then ttl = 1 end
redis.call("SET", key, stored, "PX", ttl)
redis.call("SET", last_refill_key, last_refill, "PX", ttl)
return next
`
}).withReturnType();
/**
 * Provides a Redis-backed `RateLimiterStore` using `makeStoreRedis`.
 *
 * @category layers
 * @since 4.0.0
 */
export const layerStoreRedis = /*#__PURE__*/flow(makeStoreRedis, /*#__PURE__*/Layer.effect(RateLimiterStore));
/**
 * Provides a Redis-backed `RateLimiterStore` from wrapped configuration
 * options.
 *
 * @category layers
 * @since 4.0.0
 */
export const layerStoreRedisConfig = options => Layer.effect(RateLimiterStore, Effect.flatMap(Config.unwrap(options), makeStoreRedis));
//# sourceMappingURL=RateLimiter.js.map