@unikvs/rate-limit 0.0.0-stage → 0.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present, tai-kun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @unikvs/rate-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Document](https://tai-kun.github.io/unikvs/)

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import { ErrorBase, ErrorOptions, IMiddleware, InvalidUsageErrorBase } from "@unikvs/core";
+import { PassThrough } from "@unikvs/passthrough";
+//#region ../src/errors.d.ts
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+type RateLimitExceededErrorMeta = {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-exceeded-retry-after-ms)
+   */
+  readonly retryAfterMs: number;
+};
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+type RateLimitExceededErrorArgs = ErrorOptions & RateLimitExceededErrorMeta;
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+export declare class RateLimitExceededError extends ErrorBase<RateLimitExceededErrorMeta> {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+   */
+  constructor(args: RateLimitExceededErrorArgs);
+}
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+type RateLimitInvalidOptionErrorMeta = {
+  /**
+   * 不正だったオプション名です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-name)
+   */
+  readonly name: string;
+  /**
+   * 指定された値です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-actual)
+   */
+  readonly actual: unknown;
+};
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+type RateLimitInvalidOptionErrorArgs = ErrorOptions & RateLimitInvalidOptionErrorMeta;
+/**
+ * コンストラクターに不正なオプションが渡されたときのエラーです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+export declare class RateLimitInvalidOptionError extends InvalidUsageErrorBase<RateLimitInvalidOptionErrorMeta> {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+   */
+  constructor(args: RateLimitInvalidOptionErrorArgs);
+}
+//#endregion
+//#region ../src/rate-limit.d.ts
+/**
+ * レート制限を超えたときの挙動です。
+ *
+ * - `"wait"` はトークンが補充されるまで待機します。
+ * - `"throw"` は直ちにエラーを投げます。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-strategy)
+ */
+type RateLimitStrategy = "wait" | "throw";
+/**
+ * 待機処理の実装です。テストで時刻を制御するときに差し替えます。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#irate-limit-sleep)
+ */
+interface IRateLimitSleep {
+  (ms: number, signal: AbortSignal): Promise<void>;
+}
+/**
+ * RateLimit ミドルウェアのオプションです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options)
+ */
+type RateLimitOptions = {
+  /**
+   * 1 インターバルあたりに補充されるトークン数です。既定値は `1` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-tokens-per-interval)
+   */
+  readonly tokensPerInterval?: number | undefined;
+  /**
+   * トークンを補充する間隔 (ミリ秒) です。既定値は `1000` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-interval-ms)
+   */
+  readonly intervalMs?: number | undefined;
+  /**
+   * 保持できるトークンの上限です。既定値は `tokensPerInterval` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-max-tokens)
+   */
+  readonly maxTokens?: number | undefined;
+  /**
+   * `maxTokens` の別名です。両方を指定した場合は `maxTokens` が優先されます。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-burst)
+   */
+  readonly burst?: number | undefined;
+  /**
+   * レート制限を超えたときの挙動です。既定値は `"wait"` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-strategy)
+   */
+  readonly strategy?: RateLimitStrategy | undefined;
+  /**
+   * 現在時刻 (epoch ミリ秒) を返す関数です。既定値は `Date.now` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-now)
+   */
+  readonly now?: (() => number) | undefined;
+  /**
+   * 待機処理です。既定では `setTimeout` を使用します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-sleep)
+   */
+  readonly sleep?: IRateLimitSleep | undefined;
+};
+/**
+ * トークンバケットで操作頻度を制限するミドルウェアです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+ */
+declare class RateLimit extends PassThrough implements IMiddleware {
+  #private;
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  override readonly name: string;
+  /**
+   * 1 インターバルあたりに補充されるトークン数です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  readonly tokensPerInterval: number;
+  /**
+   * トークンを補充する間隔 (ミリ秒) です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  readonly intervalMs: number;
+  /**
+   * 保持できるトークンの上限です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  readonly maxTokens: number;
+  /**
+   * レート制限を超えたときの挙動です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  readonly strategy: RateLimitStrategy;
+  /**
+   * RateLimit ミドルウェアを作成します。
+   *
+   * @param options トークン数と補充間隔などの設定です。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  constructor(options?: RateLimitOptions);
+  /**
+   * 現在保持しているトークン数です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  get availableTokens(): number;
+  use(c: IMiddleware.UseContext, next: IMiddleware.INext): Promise<void>;
+}
+//#endregion
+export { type IRateLimitSleep, RateLimit, type RateLimitExceededErrorArgs, type RateLimitExceededErrorMeta, type RateLimitInvalidOptionErrorArgs, type RateLimitInvalidOptionErrorMeta, type RateLimitOptions, type RateLimitStrategy };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/rate-limit.ts"],"mappings":";;;;;;KAKY;;;;WAID;;;;;KAMC,6BAA6B,eAAe;;;;qBAK3C,+BAA+B,UAAU;;;;EAQpD,YAAmB,MAAM;;;;;KAsBf;;;;;;WAMD;;;;;;WAOA;;;;;KAMC,kCAAkC,eAAe;;;;;;qBAOhD,oCAAoC,sBAAsB;;;;EAQrE,YAAmB,MAAM;;;;;;;;;;;;KCtEf;;;;;;UAOK;GACd,YAAY,QAAQ,cAAc;;;;;;;KAQzB;;;;;;WAMD;;;;;;WAOA;;;;;;WAOA;;;;;;WAOA;;;;;;WAOA,WAAW;;;;;;WAOX;;;;;;WAOA,QAAQ;;;;;;;cAqCE,kBAAkB,uBAAuB;;;;;oBAInC;;;;;;WAOT;;;;;;WAOA;;;;;;WAOA;;;;;;WAOA,UAAU;;;;;;;EAkB1B,YAAmB,UAAS;;;;;;MAuDjB;EAMX,IAAiB,GAAG,YAAY,YAAY,MAAM,YAAY,QAAQ"}

package/dist/index.js

@@ -0,0 +1,219 @@
+import { ErrorBase, InvalidUsageErrorBase, setErrorMessage } from "@unikvs/core";
+import { PassThrough } from "@unikvs/passthrough";
+import { getAbortReason, throwIfAborted } from "abort-signal-utils";
+//#region ../src/errors.ts
+var _RateLimitExceededError;
+var _RateLimitInvalidOptionError;
+/**
+* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+*/
+var RateLimitExceededError = class extends ErrorBase {
+	/**
+	* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+	*/
+	constructor(args) {
+		const { retryAfterMs, ...options } = args;
+		super({ retryAfterMs }, ({ retryAfterMs: messageRetryAfterMs }) => `Rate limit exceeded. Retry after ${String(messageRetryAfterMs)}ms.`, options);
+	}
+};
+_RateLimitExceededError = RateLimitExceededError;
+_RateLimitExceededError.prototype.name = "RateLimitExceededError";
+setErrorMessage(RateLimitExceededError, ({ retryAfterMs }) => `レート制限を超えました。${String(retryAfterMs)}ms 後に再試行してください。`, "ja");
+/**
+* コンストラクターに不正なオプションが渡されたときのエラーです。
+*
+* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+*/
+var RateLimitInvalidOptionError = class extends InvalidUsageErrorBase {
+	/**
+	* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+	*/
+	constructor(args) {
+		const { name, actual, ...options } = args;
+		super({
+			name,
+			actual
+		}, ({ name: messageName, actual: messageActual }) => `Invalid RateLimit option ${JSON.stringify(messageName)}: ${formatActual(messageActual)}`, options);
+	}
+};
+_RateLimitInvalidOptionError = RateLimitInvalidOptionError;
+_RateLimitInvalidOptionError.prototype.name = "RateLimitInvalidOptionError";
+setErrorMessage(RateLimitInvalidOptionError, ({ name, actual }) => `無効な RateLimit オプション ${JSON.stringify(name)}: ${formatActual(actual)}`, "ja");
+/**
+* エラーメッセージに埋め込む実際の値を整形します。
+*
+* @param actual 整形する値です。
+*
+* @returns 整形した文字列を返します。
+*/
+function formatActual(actual) {
+	if (typeof actual === "string") return JSON.stringify(actual);
+	if (typeof actual === "number" || typeof actual === "boolean" || actual === null || actual === void 0) return String(actual);
+	try {
+		return JSON.stringify(actual) ?? "[object Object]";
+	} catch {
+		return "[object Object]";
+	}
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/checkPrivateRedeclaration.js
+function _checkPrivateRedeclaration(e, t) {
+	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateMethodInitSpec.js
+function _classPrivateMethodInitSpec(e, a) {
+	_checkPrivateRedeclaration(e, a), a.add(e);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldInitSpec.js
+function _classPrivateFieldInitSpec(e, t, a) {
+	_checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/assertClassBrand.js
+function _assertClassBrand(e, t, n) {
+	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+	throw new TypeError("Private element is not present on this object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldSet2.js
+function _classPrivateFieldSet2(s, a, r) {
+	return s.set(_assertClassBrand(s, a), r), r;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldGet2.js
+function _classPrivateFieldGet2(s, a) {
+	return s.get(_assertClassBrand(s, a));
+}
+//#endregion
+//#region ../src/rate-limit.ts
+function defaultSleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(getAbortReason(signal));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(getAbortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function assertPositiveNumber(name, value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new RateLimitInvalidOptionError({
+		name,
+		actual: value
+	});
+}
+var _now = /* @__PURE__ */ new WeakMap();
+var _sleep = /* @__PURE__ */ new WeakMap();
+var _tokens = /* @__PURE__ */ new WeakMap();
+var _lastRefill = /* @__PURE__ */ new WeakMap();
+var _tail = /* @__PURE__ */ new WeakMap();
+var _RateLimit_brand = /* @__PURE__ */ new WeakSet();
+/**
+* トークンバケットで操作頻度を制限するミドルウェアです。
+*
+* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+*/
+var RateLimit = class extends PassThrough {
+	/**
+	* RateLimit ミドルウェアを作成します。
+	*
+	* @param options トークン数と補充間隔などの設定です。
+	* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+	*/
+	constructor(options = {}) {
+		super();
+		_classPrivateMethodInitSpec(this, _RateLimit_brand);
+		this.name = "RateLimit";
+		_classPrivateFieldInitSpec(this, _now, void 0);
+		_classPrivateFieldInitSpec(this, _sleep, void 0);
+		_classPrivateFieldInitSpec(this, _tokens, void 0);
+		_classPrivateFieldInitSpec(this, _lastRefill, void 0);
+		_classPrivateFieldInitSpec(this, _tail, void 0);
+		const { now = Date.now, burst, sleep = defaultSleep, strategy = "wait", maxTokens, intervalMs = 1e3, tokensPerInterval = 1 } = options;
+		assertPositiveNumber("tokensPerInterval", tokensPerInterval);
+		assertPositiveNumber("intervalMs", intervalMs);
+		const capacity = maxTokens ?? burst ?? tokensPerInterval;
+		assertPositiveNumber("maxTokens", capacity);
+		if (strategy !== "wait" && strategy !== "throw") throw new RateLimitInvalidOptionError({
+			name: "strategy",
+			actual: strategy
+		});
+		if (typeof now !== "function") throw new RateLimitInvalidOptionError({
+			name: "now",
+			actual: now
+		});
+		if (typeof sleep !== "function") throw new RateLimitInvalidOptionError({
+			name: "sleep",
+			actual: sleep
+		});
+		this.tokensPerInterval = tokensPerInterval;
+		this.intervalMs = intervalMs;
+		this.maxTokens = capacity;
+		this.strategy = strategy;
+		_classPrivateFieldSet2(_now, this, now);
+		_classPrivateFieldSet2(_sleep, this, sleep);
+		_classPrivateFieldSet2(_tokens, this, capacity);
+		_classPrivateFieldSet2(_lastRefill, this, now());
+		_classPrivateFieldSet2(_tail, this, Promise.resolve());
+	}
+	/**
+	* 現在保持しているトークン数です。
+	*
+	* [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+	*/
+	get availableTokens() {
+		_assertClassBrand(_RateLimit_brand, this, _refill).call(this);
+		return _classPrivateFieldGet2(_tokens, this);
+	}
+	async use(c, next) {
+		await _assertClassBrand(_RateLimit_brand, this, _acquire).call(this, c.signal);
+		await next();
+	}
+};
+async function _acquire(signal) {
+	throwIfAborted(signal);
+	let release;
+	const previous = _classPrivateFieldGet2(_tail, this);
+	_classPrivateFieldSet2(_tail, this, new Promise((resolve) => {
+		release = resolve;
+	}));
+	await previous;
+	try {
+		for (;;) {
+			throwIfAborted(signal);
+			_assertClassBrand(_RateLimit_brand, this, _refill).call(this);
+			if (_classPrivateFieldGet2(_tokens, this) >= 1) {
+				_classPrivateFieldSet2(_tokens, this, _classPrivateFieldGet2(_tokens, this) - 1);
+				return;
+			}
+			if (this.strategy === "throw") throw new RateLimitExceededError({ retryAfterMs: _assertClassBrand(_RateLimit_brand, this, _retryAfterMs).call(this) });
+			await _classPrivateFieldGet2(_sleep, this).call(this, _assertClassBrand(_RateLimit_brand, this, _retryAfterMs).call(this), signal);
+		}
+	} finally {
+		release();
+	}
+}
+function _refill() {
+	const now = _classPrivateFieldGet2(_now, this).call(this);
+	const elapsed = now - _classPrivateFieldGet2(_lastRefill, this);
+	if (elapsed <= 0) return;
+	_classPrivateFieldSet2(_tokens, this, Math.min(this.maxTokens, _classPrivateFieldGet2(_tokens, this) + elapsed * this.tokensPerInterval / this.intervalMs));
+	_classPrivateFieldSet2(_lastRefill, this, now);
+}
+function _retryAfterMs() {
+	const deficit = 1 - _classPrivateFieldGet2(_tokens, this);
+	return Math.max(0, Math.ceil(deficit * this.intervalMs / this.tokensPerInterval));
+}
+//#endregion
+export { RateLimit, RateLimitExceededError, RateLimitInvalidOptionError };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/errors.ts","../src/rate-limit.ts"],"sourcesContent":["import { type ErrorOptions, ErrorBase, setErrorMessage, InvalidUsageErrorBase } from \"@unikvs/core\";\n\n/**\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)\n */\nexport type RateLimitExceededErrorMeta = {\n  /**\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-exceeded-retry-after-ms)\n   */\n  readonly retryAfterMs: number;\n};\n\n/**\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)\n */\nexport type RateLimitExceededErrorArgs = ErrorOptions & RateLimitExceededErrorMeta;\n\n/**\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)\n */\nexport class RateLimitExceededError extends ErrorBase<RateLimitExceededErrorMeta> {\n  static {\n    this.prototype.name = \"RateLimitExceededError\";\n  }\n\n  /**\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)\n   */\n  public constructor(args: RateLimitExceededErrorArgs) {\n    const { retryAfterMs, ...options } = args;\n    const meta: RateLimitExceededErrorMeta = { retryAfterMs };\n    super(\n      meta,\n      ({ retryAfterMs: messageRetryAfterMs }) =>\n        `Rate limit exceeded. Retry after ${String(messageRetryAfterMs)}ms.`,\n      options,\n    );\n  }\n}\n\nsetErrorMessage(\n  RateLimitExceededError,\n  ({ retryAfterMs }) =>\n    `レート制限を超えました。${String(retryAfterMs)}ms 後に再試行してください。`,\n  \"ja\",\n);\n\n/**\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)\n */\nexport type RateLimitInvalidOptionErrorMeta = {\n  /**\n   * 不正だったオプション名です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-name)\n   */\n  readonly name: string;\n\n  /**\n   * 指定された値です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-actual)\n   */\n  readonly actual: unknown;\n};\n\n/**\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)\n */\nexport type RateLimitInvalidOptionErrorArgs = ErrorOptions & RateLimitInvalidOptionErrorMeta;\n\n/**\n * コンストラクターに不正なオプションが渡されたときのエラーです。\n *\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)\n */\nexport class RateLimitInvalidOptionError extends InvalidUsageErrorBase<RateLimitInvalidOptionErrorMeta> {\n  static {\n    this.prototype.name = \"RateLimitInvalidOptionError\";\n  }\n\n  /**\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)\n   */\n  public constructor(args: RateLimitInvalidOptionErrorArgs) {\n    const { name, actual, ...options } = args;\n    const meta: RateLimitInvalidOptionErrorMeta = {\n      name,\n      actual,\n    };\n    super(\n      meta,\n      ({ name: messageName, actual: messageActual }) =>\n        `Invalid RateLimit option ${JSON.stringify(messageName)}: ${formatActual(messageActual)}`,\n      options,\n    );\n  }\n}\n\nsetErrorMessage(\n  RateLimitInvalidOptionError,\n  ({ name, actual }) =>\n    `無効な RateLimit オプション ${JSON.stringify(name)}: ${formatActual(actual)}`,\n  \"ja\",\n);\n\n/**\n * エラーメッセージに埋め込む実際の値を整形します。\n *\n * @param actual 整形する値です。\n *\n * @returns 整形した文字列を返します。\n */\nfunction formatActual(actual: unknown): string {\n  if (typeof actual === \"string\") {\n    return JSON.stringify(actual);\n  }\n\n  if (\n    typeof actual === \"number\" ||\n    typeof actual === \"boolean\" ||\n    actual === null ||\n    actual === undefined\n  ) {\n    return String(actual);\n  }\n\n  try {\n    return JSON.stringify(actual) ?? \"[object Object]\";\n  } catch {\n    return \"[object Object]\";\n  }\n}\n","import type { IMiddleware } from \"@unikvs/core\";\nimport { PassThrough } from \"@unikvs/passthrough\";\nimport { getAbortReason, throwIfAborted } from \"abort-signal-utils\";\n\nimport { RateLimitExceededError, RateLimitInvalidOptionError } from \"./errors.js\";\n\n/**\n * レート制限を超えたときの挙動です。\n *\n * - `\"wait\"` はトークンが補充されるまで待機します。\n * - `\"throw\"` は直ちにエラーを投げます。\n *\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-strategy)\n */\nexport type RateLimitStrategy = \"wait\" | \"throw\";\n\n/**\n * 待機処理の実装です。テストで時刻を制御するときに差し替えます。\n *\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#irate-limit-sleep)\n */\nexport interface IRateLimitSleep {\n  (ms: number, signal: AbortSignal): Promise<void>;\n}\n\n/**\n * RateLimit ミドルウェアのオプションです。\n *\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options)\n */\nexport type RateLimitOptions = {\n  /**\n   * 1 インターバルあたりに補充されるトークン数です。既定値は `1` です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-tokens-per-interval)\n   */\n  readonly tokensPerInterval?: number | undefined;\n\n  /**\n   * トークンを補充する間隔 (ミリ秒) です。既定値は `1000` です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-interval-ms)\n   */\n  readonly intervalMs?: number | undefined;\n\n  /**\n   * 保持できるトークンの上限です。既定値は `tokensPerInterval` です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-max-tokens)\n   */\n  readonly maxTokens?: number | undefined;\n\n  /**\n   * `maxTokens` の別名です。両方を指定した場合は `maxTokens` が優先されます。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-burst)\n   */\n  readonly burst?: number | undefined;\n\n  /**\n   * レート制限を超えたときの挙動です。既定値は `\"wait\"` です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-strategy)\n   */\n  readonly strategy?: RateLimitStrategy | undefined;\n\n  /**\n   * 現在時刻 (epoch ミリ秒) を返す関数です。既定値は `Date.now` です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-now)\n   */\n  readonly now?: (() => number) | undefined;\n\n  /**\n   * 待機処理です。既定では `setTimeout` を使用します。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-sleep)\n   */\n  readonly sleep?: IRateLimitSleep | undefined;\n};\n\nfunction defaultSleep(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal.aborted) {\n      reject(getAbortReason(signal));\n\n      return;\n    }\n\n    const timer = setTimeout(() => {\n      signal.removeEventListener(\"abort\", onAbort);\n      resolve();\n    }, ms);\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      reject(getAbortReason(signal));\n    };\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\nfunction assertPositiveNumber(name: string, value: number): void {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new RateLimitInvalidOptionError({\n      name,\n      actual: value,\n    });\n  }\n}\n\n/**\n * トークンバケットで操作頻度を制限するミドルウェアです。\n *\n * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n */\nexport default class RateLimit extends PassThrough implements IMiddleware {\n  /**\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public override readonly name: string = \"RateLimit\";\n\n  /**\n   * 1 インターバルあたりに補充されるトークン数です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public readonly tokensPerInterval: number;\n\n  /**\n   * トークンを補充する間隔 (ミリ秒) です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public readonly intervalMs: number;\n\n  /**\n   * 保持できるトークンの上限です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public readonly maxTokens: number;\n\n  /**\n   * レート制限を超えたときの挙動です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public readonly strategy: RateLimitStrategy;\n\n  readonly #now: () => number;\n\n  readonly #sleep: IRateLimitSleep;\n\n  #tokens: number;\n\n  #lastRefill: number;\n\n  #tail: Promise<void>;\n\n  /**\n   * RateLimit ミドルウェアを作成します。\n   *\n   * @param options トークン数と補充間隔などの設定です。\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public constructor(options: RateLimitOptions = {}) {\n    super();\n\n    const {\n      now = Date.now,\n      burst,\n      sleep = defaultSleep,\n      strategy = \"wait\",\n      maxTokens,\n      intervalMs = 1000,\n      tokensPerInterval = 1,\n    } = options;\n    assertPositiveNumber(\"tokensPerInterval\", tokensPerInterval);\n    assertPositiveNumber(\"intervalMs\", intervalMs);\n\n    const capacity = maxTokens ?? burst ?? tokensPerInterval;\n    assertPositiveNumber(\"maxTokens\", capacity);\n\n    if (strategy !== \"wait\" && strategy !== \"throw\") {\n      throw new RateLimitInvalidOptionError({\n        name: \"strategy\",\n        actual: strategy,\n      });\n    }\n\n    if (typeof now !== \"function\") {\n      throw new RateLimitInvalidOptionError({\n        name: \"now\",\n        actual: now,\n      });\n    }\n\n    if (typeof sleep !== \"function\") {\n      throw new RateLimitInvalidOptionError({\n        name: \"sleep\",\n        actual: sleep,\n      });\n    }\n\n    this.tokensPerInterval = tokensPerInterval;\n    this.intervalMs = intervalMs;\n    this.maxTokens = capacity;\n    this.strategy = strategy;\n    this.#now = now;\n    this.#sleep = sleep;\n    this.#tokens = capacity;\n    this.#lastRefill = now();\n    this.#tail = Promise.resolve();\n  }\n\n  /**\n   * 現在保持しているトークン数です。\n   *\n   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)\n   */\n  public get availableTokens(): number {\n    this.#refill();\n\n    return this.#tokens;\n  }\n\n  public async use(c: IMiddleware.UseContext, next: IMiddleware.INext): Promise<void> {\n    await this.#acquire(c.signal);\n\n    await next();\n  }\n\n  async #acquire(signal: AbortSignal): Promise<void> {\n    throwIfAborted(signal);\n\n    let release!: () => void;\n    const previous = this.#tail;\n    this.#tail = new Promise<void>((resolve) => {\n      release = resolve;\n    });\n    await previous;\n\n    try {\n      for (;;) {\n        throwIfAborted(signal);\n        this.#refill();\n\n        if (this.#tokens >= 1) {\n          this.#tokens -= 1;\n\n          return;\n        }\n\n        if (this.strategy === \"throw\") {\n          throw new RateLimitExceededError({ retryAfterMs: this.#retryAfterMs() });\n        }\n\n        await this.#sleep(this.#retryAfterMs(), signal);\n      }\n    } finally {\n      release();\n    }\n  }\n\n  #refill(): void {\n    const now = this.#now();\n    const elapsed = now - this.#lastRefill;\n\n    if (elapsed <= 0) {\n      return;\n    }\n\n    this.#tokens = Math.min(\n      this.maxTokens,\n      this.#tokens + (elapsed * this.tokensPerInterval) / this.intervalMs,\n    );\n    this.#lastRefill = now;\n  }\n\n  #retryAfterMs(): number {\n    const deficit = 1 - this.#tokens;\n\n    return Math.max(0, Math.ceil((deficit * this.intervalMs) / this.tokensPerInterval));\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@unikvs/rate-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.13",
+  "description": "Transformer plugin that limits operations per time window with a token bucket.",
+  "homepage": "https://tai-kun.github.io/unikvs/",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/tai-kun/unikvs",
+    "directory": "packages/rate-limit"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@unikvs/core": "0.0.13",
+    "@unikvs/passthrough": "0.0.13",
+    "abort-signal-utils": "^0.0.6"
+  },
+  "devDependencies": {
+    "@unikvs/testing": "0.0.0",
+    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/coverage-istanbul": "5.0.5",
+    "@vitest/coverage-v8": "5.0.5",
+    "playwright": "1.64.1",
+    "valibot": "1.5.0",
+    "vite-plus": "1.3.0"
+  },
+  "peerDependencies": {
+    "@logtape/logtape": "^2.0.0"
+  },
+  "readme": "README.md",
+  "scripts": {
+    "build": "vp -C .config pack"
+  }
 }

package/src/errors.ts

@@ -0,0 +1,133 @@
+import { type ErrorOptions, ErrorBase, setErrorMessage, InvalidUsageErrorBase } from "@unikvs/core";
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+export type RateLimitExceededErrorMeta = {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-exceeded-retry-after-ms)
+   */
+  readonly retryAfterMs: number;
+};
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+export type RateLimitExceededErrorArgs = ErrorOptions & RateLimitExceededErrorMeta;
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+ */
+export class RateLimitExceededError extends ErrorBase<RateLimitExceededErrorMeta> {
+  static {
+    this.prototype.name = "RateLimitExceededError";
+  }
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-exceeded)
+   */
+  public constructor(args: RateLimitExceededErrorArgs) {
+    const { retryAfterMs, ...options } = args;
+    const meta: RateLimitExceededErrorMeta = { retryAfterMs };
+    super(
+      meta,
+      ({ retryAfterMs: messageRetryAfterMs }) =>
+        `Rate limit exceeded. Retry after ${String(messageRetryAfterMs)}ms.`,
+      options,
+    );
+  }
+}
+
+setErrorMessage(
+  RateLimitExceededError,
+  ({ retryAfterMs }) =>
+    `レート制限を超えました。${String(retryAfterMs)}ms 後に再試行してください。`,
+  "ja",
+);
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+export type RateLimitInvalidOptionErrorMeta = {
+  /**
+   * 不正だったオプション名です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-name)
+   */
+  readonly name: string;
+
+  /**
+   * 指定された値です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-invalid-option-actual)
+   */
+  readonly actual: unknown;
+};
+
+/**
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+export type RateLimitInvalidOptionErrorArgs = ErrorOptions & RateLimitInvalidOptionErrorMeta;
+
+/**
+ * コンストラクターに不正なオプションが渡されたときのエラーです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+ */
+export class RateLimitInvalidOptionError extends InvalidUsageErrorBase<RateLimitInvalidOptionErrorMeta> {
+  static {
+    this.prototype.name = "RateLimitInvalidOptionError";
+  }
+
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#error-rate-limit-invalid-option)
+   */
+  public constructor(args: RateLimitInvalidOptionErrorArgs) {
+    const { name, actual, ...options } = args;
+    const meta: RateLimitInvalidOptionErrorMeta = {
+      name,
+      actual,
+    };
+    super(
+      meta,
+      ({ name: messageName, actual: messageActual }) =>
+        `Invalid RateLimit option ${JSON.stringify(messageName)}: ${formatActual(messageActual)}`,
+      options,
+    );
+  }
+}
+
+setErrorMessage(
+  RateLimitInvalidOptionError,
+  ({ name, actual }) =>
+    `無効な RateLimit オプション ${JSON.stringify(name)}: ${formatActual(actual)}`,
+  "ja",
+);
+
+/**
+ * エラーメッセージに埋め込む実際の値を整形します。
+ *
+ * @param actual 整形する値です。
+ *
+ * @returns 整形した文字列を返します。
+ */
+function formatActual(actual: unknown): string {
+  if (typeof actual === "string") {
+    return JSON.stringify(actual);
+  }
+
+  if (
+    typeof actual === "number" ||
+    typeof actual === "boolean" ||
+    actual === null ||
+    actual === undefined
+  ) {
+    return String(actual);
+  }
+
+  try {
+    return JSON.stringify(actual) ?? "[object Object]";
+  } catch {
+    return "[object Object]";
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type {
+  RateLimitExceededErrorArgs,
+  RateLimitExceededErrorMeta,
+  RateLimitInvalidOptionErrorArgs,
+  RateLimitInvalidOptionErrorMeta,
+} from "./errors.js";
+export { RateLimitExceededError, RateLimitInvalidOptionError } from "./errors.js";
+
+export type * from "./rate-limit.js";
+export { default as RateLimit } from "./rate-limit.js";

package/src/rate-limit.ts

@@ -0,0 +1,285 @@
+import type { IMiddleware } from "@unikvs/core";
+import { PassThrough } from "@unikvs/passthrough";
+import { getAbortReason, throwIfAborted } from "abort-signal-utils";
+
+import { RateLimitExceededError, RateLimitInvalidOptionError } from "./errors.js";
+
+/**
+ * レート制限を超えたときの挙動です。
+ *
+ * - `"wait"` はトークンが補充されるまで待機します。
+ * - `"throw"` は直ちにエラーを投げます。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-strategy)
+ */
+export type RateLimitStrategy = "wait" | "throw";
+
+/**
+ * 待機処理の実装です。テストで時刻を制御するときに差し替えます。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#irate-limit-sleep)
+ */
+export interface IRateLimitSleep {
+  (ms: number, signal: AbortSignal): Promise<void>;
+}
+
+/**
+ * RateLimit ミドルウェアのオプションです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options)
+ */
+export type RateLimitOptions = {
+  /**
+   * 1 インターバルあたりに補充されるトークン数です。既定値は `1` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-tokens-per-interval)
+   */
+  readonly tokensPerInterval?: number | undefined;
+
+  /**
+   * トークンを補充する間隔 (ミリ秒) です。既定値は `1000` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-interval-ms)
+   */
+  readonly intervalMs?: number | undefined;
+
+  /**
+   * 保持できるトークンの上限です。既定値は `tokensPerInterval` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-max-tokens)
+   */
+  readonly maxTokens?: number | undefined;
+
+  /**
+   * `maxTokens` の別名です。両方を指定した場合は `maxTokens` が優先されます。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-burst)
+   */
+  readonly burst?: number | undefined;
+
+  /**
+   * レート制限を超えたときの挙動です。既定値は `"wait"` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-strategy)
+   */
+  readonly strategy?: RateLimitStrategy | undefined;
+
+  /**
+   * 現在時刻 (epoch ミリ秒) を返す関数です。既定値は `Date.now` です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-now)
+   */
+  readonly now?: (() => number) | undefined;
+
+  /**
+   * 待機処理です。既定では `setTimeout` を使用します。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit-options-sleep)
+   */
+  readonly sleep?: IRateLimitSleep | undefined;
+};
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(getAbortReason(signal));
+
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(getAbortReason(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function assertPositiveNumber(name: string, value: number): void {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new RateLimitInvalidOptionError({
+      name,
+      actual: value,
+    });
+  }
+}
+
+/**
+ * トークンバケットで操作頻度を制限するミドルウェアです。
+ *
+ * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+ */
+export default class RateLimit extends PassThrough implements IMiddleware {
+  /**
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public override readonly name: string = "RateLimit";
+
+  /**
+   * 1 インターバルあたりに補充されるトークン数です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public readonly tokensPerInterval: number;
+
+  /**
+   * トークンを補充する間隔 (ミリ秒) です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public readonly intervalMs: number;
+
+  /**
+   * 保持できるトークンの上限です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public readonly maxTokens: number;
+
+  /**
+   * レート制限を超えたときの挙動です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public readonly strategy: RateLimitStrategy;
+
+  readonly #now: () => number;
+
+  readonly #sleep: IRateLimitSleep;
+
+  #tokens: number;
+
+  #lastRefill: number;
+
+  #tail: Promise<void>;
+
+  /**
+   * RateLimit ミドルウェアを作成します。
+   *
+   * @param options トークン数と補充間隔などの設定です。
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public constructor(options: RateLimitOptions = {}) {
+    super();
+
+    const {
+      now = Date.now,
+      burst,
+      sleep = defaultSleep,
+      strategy = "wait",
+      maxTokens,
+      intervalMs = 1000,
+      tokensPerInterval = 1,
+    } = options;
+    assertPositiveNumber("tokensPerInterval", tokensPerInterval);
+    assertPositiveNumber("intervalMs", intervalMs);
+
+    const capacity = maxTokens ?? burst ?? tokensPerInterval;
+    assertPositiveNumber("maxTokens", capacity);
+
+    if (strategy !== "wait" && strategy !== "throw") {
+      throw new RateLimitInvalidOptionError({
+        name: "strategy",
+        actual: strategy,
+      });
+    }
+
+    if (typeof now !== "function") {
+      throw new RateLimitInvalidOptionError({
+        name: "now",
+        actual: now,
+      });
+    }
+
+    if (typeof sleep !== "function") {
+      throw new RateLimitInvalidOptionError({
+        name: "sleep",
+        actual: sleep,
+      });
+    }
+
+    this.tokensPerInterval = tokensPerInterval;
+    this.intervalMs = intervalMs;
+    this.maxTokens = capacity;
+    this.strategy = strategy;
+    this.#now = now;
+    this.#sleep = sleep;
+    this.#tokens = capacity;
+    this.#lastRefill = now();
+    this.#tail = Promise.resolve();
+  }
+
+  /**
+   * 現在保持しているトークン数です。
+   *
+   * [API Reference](https://tai-kun.github.io/unikvs/packages/rate-limit#rate-limit)
+   */
+  public get availableTokens(): number {
+    this.#refill();
+
+    return this.#tokens;
+  }
+
+  public async use(c: IMiddleware.UseContext, next: IMiddleware.INext): Promise<void> {
+    await this.#acquire(c.signal);
+
+    await next();
+  }
+
+  async #acquire(signal: AbortSignal): Promise<void> {
+    throwIfAborted(signal);
+
+    let release!: () => void;
+    const previous = this.#tail;
+    this.#tail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+
+    try {
+      for (;;) {
+        throwIfAborted(signal);
+        this.#refill();
+
+        if (this.#tokens >= 1) {
+          this.#tokens -= 1;
+
+          return;
+        }
+
+        if (this.strategy === "throw") {
+          throw new RateLimitExceededError({ retryAfterMs: this.#retryAfterMs() });
+        }
+
+        await this.#sleep(this.#retryAfterMs(), signal);
+      }
+    } finally {
+      release();
+    }
+  }
+
+  #refill(): void {
+    const now = this.#now();
+    const elapsed = now - this.#lastRefill;
+
+    if (elapsed <= 0) {
+      return;
+    }
+
+    this.#tokens = Math.min(
+      this.maxTokens,
+      this.#tokens + (elapsed * this.tokensPerInterval) / this.intervalMs,
+    );
+    this.#lastRefill = now;
+  }
+
+  #retryAfterMs(): number {
+    const deficit = 1 - this.#tokens;
+
+    return Math.max(0, Math.ceil((deficit * this.intervalMs) / this.tokensPerInterval));
+  }
+}