quickbase-js 0.1.0-beta.11 → 0.1.0-beta.12

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [0.1.0-beta.12](https://github.com/DrewBradfordXYZ/quickbase-js/compare/v0.1.0-beta.11...v0.1.0-beta.12) (2025-03-23)
+
+
+### Features
+
+* enable true concurrency with throttle bucket ([8dc4dee](https://github.com/DrewBradfordXYZ/quickbase-js/commit/8dc4deeaddb4365f4f64a8bd07390c7071f739f7))
+
 ## [0.1.0-beta.11](https://github.com/DrewBradfordXYZ/quickbase-js/compare/v0.1.0-beta.10...v0.1.0-beta.11) (2025-03-23)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 A Typescript API client for the [Quickbase JSON RESTful API](https://developer.quickbase.com/).
 
-Support for various authentication strategies (`user token`, `temporary tokens`, `SSO token`), `rate limiting`, `429` and `401` error handling retries and automatic `date` conversion. It uses a Proxy to dynamically invoke API methods derived from the OpenAPI specification.
+Support for various authentication strategies (`user token`, `temporary tokens`, `SSO token`), `rate limiting`, `429`(rate limit) error and `401`(auth) error handling retries and automatic `date` conversion. It uses a Proxy to dynamically invoke API methods derived from the OpenAPI specification.
 
 Browser and Node.js support. ESM and UMD builds are available.
 
@@ -155,37 +155,29 @@ _User options:_
 
 _Advanced user options:_
 
-- **`throttle`** (`{ rate: number; burst: number }`, optional): Configures rate limiting, where `rate` is requests per second and `burst` is the maximum burst of requests. Defaults to `{ rate: 10, burst: 10 }`.
-
+- **`throttle`** (`{ rate: number; burst: number }`, optional): Configures rate limiting to manage how many API requests are sent at once and how quickly additional requests follow. Defaults to `{ rate: 5, burst: 3 }`.
+  - **`burst`**: The number of requests that can start immediately (concurrent calls). Default is `3`, meaning up to 3 requests run at the same time.
+  - **`rate`**: The number of requests allowed per second after the initial burst. Default is `5`, pacing extra requests at one every ~200ms.
+  - **How It Works**: Taking the default setting for example: requests in general take ~500ms to finish. Imagine having 6 requests, 3 start right away finishing at ~500ms. Because the rate is set to 200ms, 2 request tokens have built up during this time, so the next 2 requests are sent out immediately when the first 3 finnish, leaving 1 burst spot available. The third request waits the extra 100ms to be dispatched starting at ~600ms using up the remaining burst spot, which takes another ~500ms to finish. All requests finishing around ~1100ms total. This keeps you safely under Quickbase’s 10 requests/sec limit while maximizing speed. A more liberal setting of `{ rate: 10, burst: 5 }` allows 5 requests at once, with request tokens building up every ~100ms, finishing 6 requests in ~1000ms.
 - **`maxRetries`** (`number`, optional): The maximum number of retries for failed requests. Defaults to `3`.
-
 - **`retryDelay`** (`number`, optional): The base delay (in milliseconds) between retries, which increases exponentially. Defaults to `1000`.
-
 - **`tempTokenLifespan`** (`number`, optional): The lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
-
 - **`convertDates`** (`boolean`, optional): Converts ISO date strings to `Date` objects in responses. Defaults to `true`.
 
 _Overrides and development options:_
 
-- **`fetchApi`** (`typeof fetch`, optional): For browser environments, this defaults to the built-in `fetch`. In Node.js, you are able to use `node-fetch` or another compatible library.
-
+- **`fetchApi`** (`typeof fetch`, optional): For browser environments, this defaults to the built-in `fetch`. In Node.js, you can use `node-fetch` or another compatible library.
 - **`baseUrl`** (`string`, optional): The base URL for the QuickBase API. Defaults to `"https://api.quickbase.com/v1"`.
-
 - **`debug`** (`boolean`, optional): Enables debug logging to the console. Defaults to `false`.
-
-- **`tempToken`** (`string`, optional): If you would like to override the default behavior of tempTokens you can provide your own tempToken.
-
-- **`tokenCache`** (`TokenCache`, optional): If you would like to use your own token cache, you can provide an instance of `TokenCache`.
+- **`tempToken`** (`string`, optional): Overrides the default behavior of tempTokens by providing your own tempToken.
+- **`tokenCache`** (`TokenCache`, optional): Allows you to use your own token cache instance.
 
 ---
 
 #### Configuration Notes
 
-- **Authentication**: There are three mutually exclusive authentication methods: `userToken`, `useTempTokens` and `useSso` with `samlToken`. Only one auth method may be active at a time.
-
-- **`throttle`**: Adjust this to handle 429 Too Many Requests errors. Controls API request pacing to avoid hitting rate limits. For example, `{ rate: 5, burst: 20 }` allows 5 requests per second with a burst capacity of 20.
-
-- **`tokenCache`**: Temporary tokens are cached with their dbid with a `tempTokenLifespan`. This is automatically setup for you when `useTempTokens` is enabled.
+- **Authentication**: There are three mutually exclusive authentication methods: `userToken`, `useTempTokens`, and `useSso` with `samlToken`. Only one auth method may be active at a time.
+- **`tokenCache`**: Temporary tokens are cached with their dbid and `tempTokenLifespan`. This is automatically set up when `useTempTokens` is enabled.
 
 ---
 

package/dist/esm/quickbase.js

@@ -7648,8 +7648,8 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
     const hasBody = "body" in params && params.body !== undefined;
     const body = hasBody ? params.body : undefined;
     const restParams = hasBody
-        ? Object.fromEntries(Object.entries(params).filter(([key]) => key !== "body"))
-        : { ...params };
+        ? Object.fromEntries(Object.entries(params).filter(([key]) => key !== "body" && key !== "startTime"))
+        : { ...params, startTime: undefined };
     const requestParameters = {
         ...restParams,
         ...(hasBody ? { generated: body } : {}),
@@ -7714,12 +7714,21 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
         return { message, status };
     }
     while (attempt < maxAttempts) {
+        let acquired = false;
         try {
             await rateLimiter.throttle();
-            const response = await methodInfo.method(requestParameters, requestOptions);
+            acquired = true;
+            const postThrottleTime = Date.now(); // Capture post-throttle time
+            if (params.startTime !== undefined)
+                params.startTime = postThrottleTime; // Update startTime for testing
+            const responsePromise = methodInfo.method(requestParameters, requestOptions);
+            rateLimiter.release(); // Release slot immediately after starting fetch
+            const response = await responsePromise;
             return await processResponse(response);
         }
         catch (error) {
+            if (acquired)
+                rateLimiter.release();
             let status;
             let message;
             let response;
@@ -7732,7 +7741,7 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
                 ({ message, status } = await parseErrorResponse(response));
             }
             else {
-                throw error; // Rethrow truly unexpected errors
+                throw error;
             }
             if (status === 429) {
                 if (!(error instanceof ResponseError)) {
@@ -7748,15 +7757,13 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
                 attempt++;
                 continue;
             }
-            // Handle authentication errors
             let newToken;
             try {
                 newToken = await authStrategy.handleError(status, params, attempt, maxAttempts, debug, methodName);
             }
             catch (authError) {
-                throw authError; // Propagate the fetchTempToken error and exit immediately
+                throw authError;
             }
-            // Only proceed with retry if we have a valid new token
             if (newToken !== null) {
                 token = newToken;
                 authStrategy.applyHeaders(baseHeaders, token);
@@ -7766,7 +7773,6 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
                 attempt++;
                 continue;
             }
-            // If no new token was provided, throw the original error
             throw new Error(`API Error: ${message} (Status: ${status})`);
         }
     }
@@ -7774,41 +7780,71 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
 }
 
 // src/ThrottleBucket.ts
-class ThrottleBucket {
+class ConcurrentThrottleBucket {
     tokens;
     maxTokens;
-    refillRate; // Tokens per second
+    refillRate;
     lastRefill;
-    pending = Promise.resolve(); // Queue for sequential execution
+    semaphore;
     constructor(rate, burst) {
         this.tokens = burst;
         this.maxTokens = burst;
         this.refillRate = rate;
         this.lastRefill = Date.now();
+        this.semaphore = new Semaphore(burst);
     }
     refill() {
         const now = Date.now();
-        const elapsed = (now - this.lastRefill) / 1000; // Seconds elapsed
+        const elapsed = (now - this.lastRefill) / 1000;
         const newTokens = elapsed * this.refillRate;
         this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
         this.lastRefill = now;
     }
     async acquire() {
-        // Chain the new acquisition onto the pending queue
-        const previous = this.pending;
-        this.pending = (async () => {
-            await previous; // Wait for prior calls to complete
+        await this.semaphore.acquire();
+        try {
             this.refill();
-            if (this.tokens >= 1) {
-                this.tokens -= 1;
-                return;
+            while (this.tokens < 1) {
+                const waitTime = ((1 - this.tokens) / this.refillRate) * 1000;
+                await new Promise((resolve) => setTimeout(resolve, waitTime));
+                this.refill();
             }
-            const waitTime = ((1 - this.tokens) / this.refillRate) * 1000; // ms until next token
-            await new Promise((resolve) => setTimeout(resolve, waitTime));
-            this.refill();
             this.tokens -= 1;
-        })();
-        await this.pending;
+        }
+        catch (error) {
+            this.semaphore.release();
+            throw error;
+        }
+    }
+    release() {
+        this.semaphore.release();
+    }
+}
+class Semaphore {
+    permits;
+    waiting = [];
+    constructor(maxPermits) {
+        this.permits = maxPermits;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits -= 1;
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            this.waiting.push({ resolve, reject });
+        });
+    }
+    release() {
+        this.permits += 1;
+        if (this.waiting.length > 0 && this.permits > 0) {
+            const { resolve } = this.waiting.shift();
+            this.permits -= 1;
+            resolve();
+        }
+    }
+    available() {
+        return this.permits;
     }
 }
 
@@ -7816,7 +7852,8 @@ class RateLimiter {
     throttleBucket;
     maxRetries;
     retryDelay;
-    constructor(throttleBucket, maxRetries = 3, retryDelay = 1000) {
+    constructor(throttleBucket, // Updated type
+    maxRetries = 3, retryDelay = 1000) {
         this.throttleBucket = throttleBucket;
         this.maxRetries = maxRetries;
         this.retryDelay = retryDelay;
@@ -7826,8 +7863,12 @@ class RateLimiter {
             await this.throttleBucket.acquire();
         }
     }
+    release() {
+        if (this.throttleBucket) {
+            this.throttleBucket.release();
+        }
+    }
     async handle429(error, attempt) {
-        // Remove the throw here; let invokeMethod handle exhaustion
         const retryAfter = error.response.headers.get("Retry-After");
         return retryAfter
             ? parseInt(retryAfter, 10) * 1000
@@ -7836,10 +7877,11 @@ class RateLimiter {
 }
 
 function quickbase(config) {
-    const { realm, userToken, tempToken, useTempTokens, useSso, samlToken, fetchApi, debug, convertDates = true, tempTokenLifespan = 290000, throttle = { rate: 10, burst: 10 }, maxRetries = 3, retryDelay = 1000, tokenCache: providedTokenCache, baseUrl = "https://api.quickbase.com/v1", } = config;
+    const { realm, userToken, tempToken, useTempTokens, useSso, samlToken, fetchApi, debug, convertDates = true, tempTokenLifespan = 290000, throttle = { rate: 5, burst: 3 }, // Updated default to match passing test
+    maxRetries = 3, retryDelay = 1000, tokenCache: providedTokenCache, baseUrl = "https://api.quickbase.com/v1", } = config;
     const tokenCache = providedTokenCache || new TokenCache(tempTokenLifespan);
     const throttleBucket = throttle
-        ? new ThrottleBucket(throttle.rate, throttle.burst)
+        ? new ConcurrentThrottleBucket(throttle.rate, throttle.burst)
         : null;
     const rateLimiter = new RateLimiter(throttleBucket, maxRetries, retryDelay);
     const defaultFetch = typeof globalThis.window !== "undefined"