Make token class name clearer

Author: airhorns

README.md

@@ -333,7 +333,7 @@ const conservativeBucket = new AIMDBucket({
 
 ## API Reference
 
-### AIMDBucket
+### `AIMDBucket`
 
 #### Constructor
 
@@ -343,12 +343,12 @@ new AIMDBucket(config?: AIMDBucketConfig)
 
 #### Methods
 
-- `acquire(): Promise<Token>` - Acquire a token for making a request
+- `acquire(): Promise<AIMDBucketToken>` - Acquire a token for making a request
 - `getCurrentRate(): number` - Get current rate limit (tokens per second)
 - `getStatistics(): AIMDBucketStatistics` - Get current statistics
 - `shutdown(): Promise<void>` - Gracefully shut down the bucket
 
-### Token
+### `AIMDBucketToken`
 
 #### Methods
 

spec/aimd-bucket.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { AIMDBucket, AIMDBucketConfig, Token } from "../src/index";
+import { AIMDBucket, AIMDBucketConfig, AIMDBucketToken } from "../src/index";
 
 describe("AIMDBucket", () => {
   let bucket: AIMDBucket;
@@ -46,7 +46,7 @@ describe("AIMDBucket", () => {
 
     it("should acquire tokens immediately when bucket has capacity", async () => {
       const token = await bucket.acquire();
-      expect(token).toBeInstanceOf(Token);
+      expect(token).toBeInstanceOf(AIMDBucketToken);
       expect(token.isExpired()).toBe(false);
     });
 
@@ -63,7 +63,7 @@ describe("AIMDBucket", () => {
 
       // Now we should be able to acquire more
       const additionalToken = await bucket.acquire();
-      expect(additionalToken).toBeInstanceOf(Token);
+      expect(additionalToken).toBeInstanceOf(AIMDBucketToken);
     });
 
     it("should process multiple pending requests in order", async () => {
@@ -77,14 +77,14 @@ describe("AIMDBucket", () => {
       const newTokens = await Promise.all([bucket.acquire(), bucket.acquire(), bucket.acquire()]);
 
       expect(newTokens).toHaveLength(3);
-      newTokens.forEach((token) => expect(token).toBeInstanceOf(Token));
+      newTokens.forEach((token) => expect(token).toBeInstanceOf(AIMDBucketToken));
     });
 
     it("should support concurrent token acquisition", async () => {
       const promises = Array.from({ length: 5 }, () => bucket.acquire());
       const tokens = await Promise.all(promises);
       expect(tokens).toHaveLength(5);
-      tokens.forEach((token) => expect(token).toBeInstanceOf(Token));
+      tokens.forEach((token) => expect(token).toBeInstanceOf(AIMDBucketToken));
     });
 
     it("should respect maxRate limit", async () => {
@@ -537,7 +537,7 @@ describe("AIMDBucket", () => {
       // Should still be able to acquire more after timeout
       await vi.advanceTimersByTimeAsync(10000);
       const newToken = await bucket.acquire();
-      expect(newToken).toBeInstanceOf(Token);
+      expect(newToken).toBeInstanceOf(AIMDBucketToken);
     });
 
     it("should handle configuration edge cases", () => {
@@ -593,7 +593,7 @@ describe("AIMDBucket", () => {
       const additionalTokens = await Promise.all([bucket.acquire(), bucket.acquire(), bucket.acquire()]);
 
       expect(additionalTokens).toHaveLength(3);
-      additionalTokens.forEach((token) => expect(token).toBeInstanceOf(Token));
+      additionalTokens.forEach((token) => expect(token).toBeInstanceOf(AIMDBucketToken));
 
       const finalStats = bucket.getStatistics();
       expect(finalStats.tokensIssued).toBe(initialStats.tokensIssued + 13);
@@ -603,7 +603,7 @@ describe("AIMDBucket", () => {
 
 describe("Token", () => {
   let bucket: AIMDBucket;
-  let token: Token;
+  let token: AIMDBucketToken;
 
   beforeEach(async () => {
     vi.useFakeTimers();

src/index.ts

@@ -39,7 +39,7 @@ export interface AIMDBucketStatistics {
  * One token that has been successfully acquired from the bucket
  * Expected to be completed once as either a success, failure, rate limited, or timeout
  */
-export class Token {
+export class AIMDBucketToken {
   private completed = false;
   private expired = false;
   private timeoutHandle?: NodeJS.Timeout;
@@ -126,7 +126,7 @@ export class AIMDBucket {
   private lastRefill = Date.now();
   private recentOutcomes: Array<{ timestamp: number; outcome: "success" | "failure" | "rateLimited" | "timeout" }> = [];
   private tokensIssued = 0; // Only track total issued for reporting
-  private pending: { resolve: (token: Token) => void; reject: (error: Error) => void; timestamp: number }[] = [];
+  private pending: { resolve: (token: AIMDBucketToken) => void; reject: (error: Error) => void; timestamp: number }[] = [];
   private isShutdown = false;
 
   private config: Required<AIMDBucketConfig>;
@@ -152,7 +152,7 @@ export class AIMDBucket {
    * Acquire a token to make a request
    * @returns Promise that resolves to a Token when one becomes available
    */
-  async acquire(): Promise<Token> {
+  async acquire(): Promise<AIMDBucketToken> {
     if (this.isShutdown) {
       throw new Error("Bucket has been shut down");
     }
@@ -163,7 +163,7 @@ export class AIMDBucket {
       // capacity is available now, immediately issue a token
       this.tokens--;
       this.tokensIssued++;
-      return new Token(this, this.config.tokenTimeoutMs);
+      return new AIMDBucketToken(this, this.config.tokenTimeoutMs);
     } else {
       // capacity is not available now, return a promise for a future token
       const span = tracer.startSpan("token-bucket.wait", {
@@ -176,7 +176,7 @@ export class AIMDBucket {
 
       return new Promise((resolve, reject) => {
         this.pending.push({
-          resolve: (token: Token) => {
+          resolve: (token: AIMDBucketToken) => {
             span.end();
             resolve(token);
           },
@@ -286,7 +286,7 @@ export class AIMDBucket {
       const request = this.pending.shift()!;
       this.tokens--;
       this.tokensIssued++;
-      request.resolve(new Token(this, this.config.tokenTimeoutMs));
+      request.resolve(new AIMDBucketToken(this, this.config.tokenTimeoutMs));
     }
   }