quickbase-js 0.1.0-beta.9 → 1.0.0

package/README.md

@@ -1,91 +1,304 @@
 # quickbase-js
 
-This is a Typescript library using the QuickBase OpenAPI spec and the typescipt-fetch generator. This library is designed for both browser and Node.js environments. Code pages have first class support.
+A Typescript API client for the [Quickbase JSON RESTful API](https://developer.quickbase.com/).
 
-Authentication methods: `Temporary Tokens`, `User Tokens`, `SSO`.
+Support for various authentication types (`user token`, `temporary tokens`, `SSO token`), `concurrent rate limiting strategies`, `auto pagination`, `js date conversion`, `429` (rate limit) and `401` (auth) error handling retries. It uses a Proxy to dynamically invoke API methods derived from the OpenAPI specification.
 
-# Installation
+Browser and Node.js support. ESM and UMD builds are available.
+
+Authentication and throttle methods are opinionated. See configuration options for details and available settings.
+
+## API Documentation
+
+<a href="https://quickbase-js.netlify.app/" target="_blank"> Documentation</a> for quickbase-js.
+
+## Installation
+
+#### Node.js install
 
 ```bash
 npm install --save quickbase-js
 ```
 
-## Examples
+#### CDN install.
+
+Find and select the latest version. UMD is recommended for code pages.
 
-### CDN Code Page
+<a href="https://www.jsdelivr.com/package/npm/quickbase-js?tab=files" target="_blank">CDN Files</a> for quickbase-js
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
     <title>Quickbase</title>
-    <script src="https://cdn.jsdelivr.net/npm/quickbase-js@1.1.0-beta.6/dist/umd/quickbase.umd.min.js"></script>
+    <!-- Replace xx.xx.xx with the latest version from CDN Files-->
+    <script src="https://cdn.jsdelivr.net/npm/quickbase-js@xx.xx.xx/dist/umd/quickbase.umd.min.js"></script>
   </head>
-
   <body>
-    <div>
-      <h1>Quickbase-js CDN Example</h1>
-      <p id="result">Loading...</p>
-    </div>
     <script>
-      var realm = "xxxxxxxxxxxxxxxxxxxx"; // replace with your realm
-      var appId = "xxxxxxxxxxxxxxxxxxxx"; // replace with your app ID
-      if (typeof QuickbaseJS === "undefined") {
-        document.getElementById("result").textContent =
-          "Error: Failed to load QuickbaseJS library.";
-      } else {
-        var qbClient = QuickbaseJS.quickbase({
-          realm,
-          useTempTokens: true,
-        });
-
-        qbClient
-          .getApp({ appId })
-          .then(function (app) {
-            document.getElementById("result").textContent =
-              "App Name: " + app.name;
-          })
-          .catch(function (err) {
-            document.getElementById("result").textContent =
-              "Error: " + (err.message || "Failed to load app");
-          });
-      }
+      const realm = ""; // Replace with your realm
+      const appId = ""; // Replace with your app ID
+
+      const qb = QuickbaseJS.quickbase({
+        realm,
+        useTempTokens: true,
+      });
+
+      qb.getApp({ appId })
+        .then((app) => console.log(app.name))
+        .catch((err) => console.log(err.message));
     </script>
   </body>
 </html>
 ```
 
+## Authentication Examples
+
+### User Token
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
+});
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
+```
+
+### Temporary Tokens (Code Pages)
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  useTempTokens: true,
+});
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
+```
+
+### SSO Token
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_SAML_TOKEN = ""; // Your SAML token (e.g., 'saml_xyz789...')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  samlToken: QB_SAML_TOKEN,
+  useSso: true,
+});
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
+```
+
 ## Configuration
 
 The `quickbase` function accepts a `QuickbaseConfig` object with the following options:
 
+### User Options
+
 - **`realm`** (`string`): Your QuickBase realm (e.g., "company"). This is required and has no default value.
+
 - **`userToken`** (`string`, optional): A QuickBase user token for authentication. No default is provided.
+
 - **`useTempTokens`** (`boolean`, optional): Enables temporary token authentication. Defaults to `false`.
+
 - **`useSso`** (`boolean`, optional): Enables SSO authentication. Defaults to `false`.
+
 - **`samlToken`** (`string`, optional): A SAML token for SSO authentication. No default is provided.
 
----
+### Advanced User Options
+
+- **`throttle`** (`{ type?: 'flow' | 'burst-aware';` `rate?: number;` `burst?: number;` `windowSeconds?: number }`, optional): Configures concurrent rate limiting to manage API request throughput. Defaults to `{ type: 'flow', rate: 5, burst: 50 }`.
+
+  - **`type`** (`string`): Throttle strategy. _Setting type without rate or burst enables default settings for that throttle type._
+
+    - `'flow'` (default): Uses `FlowThrottleBucket` for a QuickBase-agnostic burst-then-rate flow. Ideal for steady request pacing.
+
+    - `'burst-aware'`: Uses `BurstAwareThrottleBucket` for QuickBase-specific burst throttling with a sliding window (e.g., 100 requests per 10 seconds). Ideal for when you need to use nearly all your allotted API calls immediately, for example on page load.
+
+  _Set rate and burst if changing defaults._
+
+  - **`rate`** (`number`): Requests per second after the initial burst (for `'flow'` only). Default is `5`. Meaning 5 request tokens get created each second.
+
+  - **`burst`** (`number`): Maximum concurrent requests:
+    - For `'flow'`: Initial concurrent burst size (default: 50), followed by `rate`/sec.
+    - For `'burst-aware'`: Concurrent burst cap per window (default: 100), waits for window reset if exceeded.
+  - **`windowSeconds`** (`number`, `'burst-aware'` only): Sliding window duration in seconds (default: 10). Caps total requests (e.g., 100 requests available every 10s).
 
-_Optional advanced options:_
+  - **Examples**:
+    - `{ type: 'flow', rate: 5, burst: 50 }`: **~10s for 100 requests**, (50 instant, and 1 every 200ms. In other words, 50 at 10/sec).
+    - `{ type: 'burst-aware', burst: 100, windowSeconds: 10 }`: **~10s for 100 requests**, (100 instant, refreshing every 10s for next burst).
+
+- **`maxRetries`** (`number`, optional): Maximum retries for failed requests. Defaults to `3`.
+
+- **`retryDelay`** (`number`, optional): Base delay (in milliseconds) between retries, increases exponentially. Defaults to `1000`.
+
+- **`tempTokenLifespan`** (`number`, optional): Lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
 
-- **`tempTokenLifespan`** (`number`, optional): The lifespan (in milliseconds) of temporary tokens in the cache. Defaults to `290000` (290 seconds).
-- **`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 }`.
-- **`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`.
 - **`convertDates`** (`boolean`, optional): Converts ISO date strings to `Date` objects in responses. Defaults to `true`.
-- **`baseUrl`** (`string`, optional): The base URL for the QuickBase API. Defaults to `"https://api.quickbase.com/v1"`.
-- **`tempToken`** (`string`, optional): A temporary token for authentication. No default is provided.
-- **`tokenCache`** (`TokenCache`, optional): A custom token cache instance. Defaults to a new `TokenCache` instance created with `tempTokenLifespan`.
-- **`fetchApi`** (`typeof fetch`, optional): A custom fetch implementation (e.g., for Node.js). Defaults to the browser’s `fetch` if available, or the provided implementation.
+
+- **`autoPaginate`** (`boolean`, optional): Enables automatic pagination of multi-page API responses. Defaults to `true`.
+
+### Overrides and Development Options
+
+- **`fetchApi`** (`typeof fetch`, optional): Defaults to built-in `fetch` in browsers and Node.js >= 18. In older Node.js versions, node-fetch or another compatible library via fetchApi is required.
+
+- **`baseUrl`** (`string`, optional): 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`.
 
-### Configuration Notes
+- **`tempToken`** (`string`, optional): Overrides default tempToken behavior by providing your own token.
+
+- **`tokenCache`** (`TokenCache`, optional): Allows use of a custom token cache instance.
+
+---
+
+#### Configuration Notes
+
+- **Authentication**: Three mutually exclusive methods: `userToken`, `useTempTokens`, and `useSso` with `samlToken`. Only one may be active at a time.
+- **`tokenCache`**: Temporary tokens are cached here with their `dbid` and `tempTokenLifespan` when `useTempTokens` is enabled.
+
+---
+
+### Pagination Control
+
+The library supports automatic pagination for methods like `runQuery` when `autoPaginate` is enabled (default: `true`). To temporarily disable or constrain pagination for a specific operation without altering the global configuration, use the `withPaginationDisabled()` or `withPaginationLimit()` methods.
+
+#### `withPaginationDisabled(callback)`
+
+- **Description**: Executes an asynchronous callback with pagination temporarily disabled, restoring the original `autoPaginate` setting afterward. Useful for fetching only the initial page of results without modifying method signatures or global settings.
+- **Parameters**:
+  - `callback`: `() => Promise<T>` - An async function containing the API call(s) to execute without pagination.
+- **Returns**: `Promise<T>` - The result of the callback.
+- **Example**:
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_TABLE_ID = ""; // Your table ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
+  autoPaginate: true, // Pagination enabled by default
+});
 
-- **Authentication**: Use `userToken` for standard auth, `tempToken` with `useTempTokens` for temporary tokens, or `samlToken` with `useSso` for SSO. Only one auth method is active at a time.
-- **`throttle`**: 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`**: If not provided, a new cache is initialized automatically, storing temporary tokens for the specified `tempTokenLifespan`.
-- **`fetchApi`**: In Node.js, you must provide a fetch implementation (e.g., `node-fetch`), as there’s no built-in `fetch` like in browsers.
+const runLimitedQuery = async () => {
+  try {
+    const result = await qb.withPaginationDisabled(async () => {
+      return qb.runQuery({
+        body: {
+          from: QB_TABLE_ID,
+          select: [3], // Example field ID
+          options: { top: 2 }, // Fetch only 2 records
+        },
+      });
+    });
+    console.log("Fetched records:", result.data.length); // Outputs: 2
+  } catch (error) {
+    console.error("Error running query:", error.message);
+  }
+};
+
+runLimitedQuery();
+```
+
+#### `withPaginationLimit(limit, callback)`
+
+- **Description**: Executes an asynchronous callback with pagination enabled but limited to a specified number of records, restoring the original `autoPaginate` setting afterward. Useful for fetching a precise number of records (e.g., 100) from a larger dataset, stopping pagination once the limit is reached, without modifying method signatures or global settings.
+- **Parameters**:
+  - `limit`: `number` - The maximum number of records to fetch across all pages.
+  - `callback`: `() => Promise<T>` - An async function containing the API call(s) to execute with the pagination limit.
+- **Returns**: `Promise<T>` - The result of the callback, containing up to `limit` records.
+- **Example**:
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_TABLE_ID = ""; // Your table ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
+  autoPaginate: true, // Pagination enabled by default
+});
+
+const runCappedQuery = async () => {
+  try {
+    const result = await qb.withPaginationLimit(100, async () => {
+      return qb.runQuery({
+        body: {
+          from: QB_TABLE_ID,
+          select: [3], // Example field ID
+          options: { top: 25 }, // Fetch 25 records per page
+        },
+      });
+    });
+    console.log("Fetched records:", result.data.length); // Outputs: 100
+  } catch (error) {
+    console.error("Error running query:", error.message);
+  }
+};
+
+runCappedQuery();
+```
+
+---
 
 ### Development workflow
 
@@ -95,26 +308,23 @@ npm run build
 npm run test:all
 ```
 
-### Prerequisites
+---
 
-Node.js >= 18
+### Prerequisites
 
-npm >= 8
+- Node.js version >= 18
+- A Quickbase account. [Free tier available](https://www.quickbase.com/builder-program).
 
-A Quickbase app with a table and a user token. A free builder account works with must API calls.
+---
 
 ### Contributing
 
-1. Fork the repository.
-
-2. Create a feature branch (git checkout -b feature/your-feature).
+If you would like to contribute to this project, please fork the repository and submit a pull request.
 
-3. Commit changes (git commit -m "Add your feature").
-
-4. Push to your branch (git push origin feature/your-feature).
-
-5. Open a pull request.
+---
 
 ### License
 
 MIT License - see LICENSE for details.
+
+---