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

package/tests/vitest/qb/quickbase-js/BurstAwareThrottleBucket.test.ts

@@ -0,0 +1,125 @@
+// tests/vitest/qb/BurstAwareThrottleBucket.test.ts
+import { describe, it, expect } from "vitest";
+import { quickbase } from "../../../../src/quickbaseClient";
+
+// Set this to true to run the slow test with 80 burst and 100 calls
+const runSlowTests = false;
+
+describe("QuickbaseClient with BurstAwareThrottleBucket Integration Tests", () => {
+  // Helper function to reduce duplication
+  const runThrottleTest = async (
+    burst: number,
+    windowSeconds: number,
+    callCount: number
+  ) => {
+    const mockFetch = async (
+      url: string,
+      options: RequestInit
+    ): Promise<Response> => {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      return new Response(JSON.stringify({ id: "mock-app" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    const qbClient = quickbase({
+      realm: "test",
+      userToken: "mock-token",
+      throttle: { type: "burst-aware", burst, windowSeconds },
+      fetchApi: mockFetch,
+      debug: true,
+    });
+
+    const throttleTimes: number[] = [];
+    const startTimes: number[] = new Array(callCount).fill(0);
+    const completionTimes: number[] = [];
+    const recordTime = async (index: number) => {
+      const preThrottle = Date.now();
+      throttleTimes[index] = preThrottle;
+      await qbClient.getApp({
+        appId: "mock-app-id",
+        startTime: startTimes[index],
+      });
+      completionTimes[index] = Date.now();
+      startTimes[index] = startTimes[index] || Date.now() - 500;
+    };
+
+    const startTime = Date.now();
+    const promises = [];
+    for (let i = 0; i < callCount; i++) {
+      promises.push(recordTime(i));
+      await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    await Promise.all(promises);
+
+    const relativeThrottleTimes = throttleTimes.map((t) => t - startTime);
+    const relativeStartTimes = startTimes.map((t) => t - startTime);
+    const durations = completionTimes.map((t) => t - startTime);
+    const timings = completionTimes.map((t, i) => t - startTimes[i]);
+
+    console.log("Relative Throttle Times:", relativeThrottleTimes.slice(0, 10));
+    console.log("Relative Start Times:", relativeStartTimes.slice(0, 10));
+    console.log("Durations:", durations.slice(0, 10));
+    console.log("Timings:", timings.slice(0, 10));
+    console.log("Total Duration:", Date.now() - startTime);
+
+    return { totalDuration: Date.now() - startTime, durations, timings };
+  };
+
+  it("handles concurrent API calls with burst 3 and 0.5s window", async () => {
+    const { totalDuration, durations, timings } = await runThrottleTest(
+      3,
+      0.5,
+      6
+    );
+
+    expect(totalDuration).toBeGreaterThanOrEqual(1000);
+    expect(totalDuration).toBeLessThan(1200);
+
+    expect(durations.length).toBe(6);
+    expect(durations.slice(0, 3).every((d) => d >= 500 && d < 550)).toBe(true);
+
+    const sortedDurations = [...durations].sort((a, b) => a - b);
+    expect(sortedDurations[3]).toBeGreaterThanOrEqual(1000);
+    expect(sortedDurations[3]).toBeLessThan(1100);
+    expect(sortedDurations[4]).toBeGreaterThanOrEqual(1000);
+    expect(sortedDurations[4]).toBeLessThan(1100);
+    expect(sortedDurations[5]).toBeGreaterThanOrEqual(1000);
+    expect(sortedDurations[5]).toBeLessThan(1100);
+
+    expect(timings.every((t) => t >= 490 && t < 560)).toBe(true);
+  });
+
+  // Optional test for 80 burst - set runSlowTests = true to enable
+  if (runSlowTests) {
+    it(
+      "handles 100 concurrent API calls with burst 80 and 10s window",
+      { timeout: 12000 },
+      async () => {
+        const { totalDuration, durations, timings } = await runThrottleTest(
+          80,
+          10,
+          100
+        );
+
+        expect(totalDuration).toBeGreaterThanOrEqual(10500);
+        expect(totalDuration).toBeLessThan(11500);
+
+        expect(durations.length).toBe(100);
+        expect(durations.slice(0, 80).every((d) => d >= 500 && d < 600)).toBe(
+          true
+        );
+
+        const sortedDurations = [...durations].sort((a, b) => a - b);
+        expect(
+          sortedDurations.slice(80).every((d) => d >= 10500 && d < 10600)
+        ).toBe(true);
+
+        expect(timings.every((t) => t >= 490 && t < 560)).toBe(true);
+      }
+    );
+  } else {
+    it.skip("handles 100 concurrent API calls with burst 80 and 10s window", () => {});
+  }
+});

package/tests/vitest/qb/quickbase-js/FlowBucket.test.ts

@@ -0,0 +1,77 @@
+// tests/vitest/qb/ThrottleBucket.test.ts
+import { describe, it, expect } from "vitest";
+import { quickbase } from "../../../../src/quickbaseClient";
+
+describe("QuickbaseClient with ConcurrentThrottleBucket Integration Tests", () => {
+  it("handles concurrent API calls with burst and rate limiting in strict order", async () => {
+    const mockFetch = async (
+      url: string,
+      options: RequestInit
+    ): Promise<Response> => {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      return new Response(JSON.stringify({ id: "mock-app" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    const qbClient = quickbase({
+      realm: "test",
+      userToken: "mock-token",
+      throttle: { rate: 5, burst: 3 },
+      fetchApi: mockFetch,
+      debug: true,
+    });
+
+    const throttleTimes: number[] = [];
+    const startTimes: number[] = new Array(6).fill(0);
+    const completionTimes: number[] = [];
+    const recordTime = async (index: number) => {
+      const preThrottle = Date.now();
+      throttleTimes[index] = preThrottle;
+      await qbClient.getApp({
+        appId: "mock-app-id",
+        startTime: startTimes[index],
+      });
+      completionTimes[index] = Date.now();
+      startTimes[index] = startTimes[index] || Date.now() - 500;
+    };
+
+    const startTime = Date.now();
+    const promises = [];
+    for (let i = 0; i < 6; i++) {
+      promises.push(recordTime(i));
+      await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    await Promise.all(promises);
+
+    const relativeThrottleTimes = throttleTimes.map((t) => t - startTime);
+    const relativeStartTimes = startTimes.map((t) => t - startTime);
+    const durations = completionTimes.map((t) => t - startTime);
+    const timings = completionTimes.map((t, i) => t - startTimes[i]);
+
+    console.log("Relative Throttle Times:", relativeThrottleTimes);
+    console.log("Relative Start Times (post-throttle):", relativeStartTimes);
+    console.log("Durations (completion times):", durations);
+    console.log("Timings (fetch durations):", timings);
+    console.log("Total Duration:", Date.now() - startTime);
+
+    const totalDuration = Date.now() - startTime;
+    expect(totalDuration).toBeGreaterThanOrEqual(1000);
+    expect(totalDuration).toBeLessThan(1200); // Adjusted back to ~1100ms
+
+    expect(durations.length).toBe(6);
+    expect(durations.slice(0, 3).every((d) => d >= 500 && d < 550)).toBe(true);
+
+    // Sort durations to handle out-of-order completion
+    const sortedDurations = [...durations].sort((a, b) => a - b);
+    expect(sortedDurations[3]).toBeGreaterThanOrEqual(650);
+    expect(sortedDurations[3]).toBeLessThan(750);
+    expect(sortedDurations[4]).toBeGreaterThanOrEqual(850);
+    expect(sortedDurations[4]).toBeLessThan(950);
+    expect(sortedDurations[5]).toBeGreaterThanOrEqual(1050);
+    expect(sortedDurations[5]).toBeLessThan(1150);
+
+    expect(timings.every((t) => t >= 500 && t < 550)).toBe(true);
+  });
+});

package/tests/vitest/qb/quickbase-js/paginationSkip.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import {
+  createClient,
+  QB_TABLE_ID_1,
+  QB_REALM,
+  QB_USER_TOKEN,
+} from "@tests/setup";
+import { QuickbaseClient } from "@/quickbaseClient";
+import {
+  RunQueryRequest,
+  RunQueryRequestOptions,
+  RunQuery200Response,
+} from "@/generated/models";
+
+// Extend RunQueryRequestOptions to include sortBy (for reference, not used here)
+interface ExtendedRunQueryRequestOptions extends RunQueryRequestOptions {
+  sortBy?: Array<{ fieldId: number; order: "ASC" | "DESC" }>;
+}
+
+describe("QuickbaseClient Integration - Pagination with Skip", () => {
+  let qb: QuickbaseClient;
+
+  beforeAll(() => {
+    qb = createClient(undefined, {
+      realm: QB_REALM,
+      userToken: QB_USER_TOKEN,
+      debug: true,
+      autoPaginate: true, // Enable library's automatic pagination
+    });
+    console.log("[beforeAll] Client initialized");
+  });
+
+  it(
+    "fetches full dataset with auto-pagination and heavy data",
+    { timeout: 30000 }, // 30s for multiple calls
+    async () => {
+      const queryOptions: ExtendedRunQueryRequestOptions = {
+        skip: 0, // Start at beginning, no top specified
+        // sortBy removed to test without ordering
+      };
+
+      const queryRequest: RunQueryRequest = {
+        from: QB_TABLE_ID_1,
+        select: [3, 822, 823, 824, 825, 6], // FID 3 for Record ID
+        options: queryOptions,
+      };
+
+      const startTime = Date.now();
+      console.log(
+        "[Test Start] Query request with auto-pagination:",
+        queryRequest
+      );
+
+      try {
+        const response = (await qb.runQuery({
+          body: queryRequest,
+        })) as RunQuery200Response & {
+          data: Array<{ [key: string]: { value: any } }>;
+          metadata: {
+            totalRecords: number;
+            numRecords: number;
+            numFields: number;
+            skip: number;
+            top?: number;
+          };
+        };
+
+        const duration = Date.now() - startTime;
+        console.log(`[Test Complete] Response received in ${duration}ms`, {
+          recordCount: response.data.length,
+          totalRecords: response.metadata.totalRecords,
+          defaultTop: response.metadata.top,
+        });
+
+        // Assertions
+        expect(response.data).toBeDefined();
+        expect(response.data.length).toBeGreaterThan(2429); // More than initial cap, confirming pagination
+        expect(response.data.length).toEqual(response.metadata.totalRecords); // Full dataset fetched
+        expect(response.metadata).toBeDefined();
+        // Removed expect(response.metadata.totalRecords).toBe(5000)
+        expect(response.metadata.totalRecords).toBeGreaterThanOrEqual(5000); // Flexible minimum, allows growth
+        expect(response.metadata.numFields).toBe(6); // 6 fields with FID 3
+        expect(response.metadata.skip).toBe(0); // Initial skip
+
+        const sampleRecord = response.data[0];
+        console.log("[Debug] Sample record:", sampleRecord);
+        expect(sampleRecord["6"]?.value).toBeDefined();
+        expect(typeof sampleRecord["6"]?.value).toBe("string");
+        expect(sampleRecord["6"]?.value.length).toBeGreaterThan(9000); // ~10KB
+        expect(sampleRecord["3"]?.value).toBeDefined(); // Check FID 3 exists
+        expect(typeof sampleRecord["3"]?.value).toBe("number"); // Record ID is numeric
+
+        // Check for duplicates using Record ID (FID 3)
+        const recordIds = response.data.map(
+          (record: { [key: string]: { value: any } }) => record["3"]?.value
+        );
+        const uniqueRecordIds = new Set(recordIds);
+        expect(uniqueRecordIds.size).toEqual(response.data.length); // No duplicates
+        expect(uniqueRecordIds.size).toEqual(response.metadata.totalRecords); // All records unique
+
+        console.log(
+          `[Integration Test] Fetched ${response.data.length} records in ${duration}ms, totalRecords: ${response.metadata.totalRecords}`
+        );
+      } catch (error) {
+        const duration = Date.now() - startTime;
+        console.error("[Test Error] Failed after", duration, "ms:", error);
+        throw error;
+      }
+    }
+  );
+});

package/tests/vitest/qb/records/runQuery.test.ts

@@ -1,4 +1,3 @@
-// tests/vitest/qb/records/runQuery.test.ts
 import { describe, it, expect } from "vitest";
 import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
 import {
@@ -128,7 +127,7 @@ describe("QuickbaseClient Integration - runQuery", () => {
         numFields: 2,
         numRecords: 1,
         skip: 0,
-        top: 1,
+        // Removed top: 1, as it should be undefined in the final response
         totalRecords: expect.any(Number),
       });
 

package/tests/vitest/unit/auth/retryUserToken401.test.ts

@@ -1,5 +1,3 @@
-// tests/vitest/unit/auth/retryUserToken401.test.ts
-
 import { describe, it, expect, vi } from "vitest";
 import {
   createClient,
@@ -10,7 +8,6 @@ import {
 
 describe("QuickbaseClient Unit - User Token Retry on 401", () => {
   it("retries with the same user token on 401 and succeeds", async () => {
-    const userToken = "b9f3pk_q4jd_0_b4qu5eebyvuix3xs57ysd7zn3";
     mockFetch
       .mockResolvedValueOnce(
         new Response(JSON.stringify({ message: "Unauthorized" }), {
@@ -26,7 +23,7 @@ describe("QuickbaseClient Unit - User Token Retry on 401", () => {
     const consoleSpy = vi.spyOn(console, "log");
     const client = createClient(mockFetch, {
       realm: QB_REALM,
-      userToken,
+      userToken: "b9f3pk_q4jd_0_b4qu5eebyvuix3xs57ysd7zn3",
       useTempTokens: false,
       debug: true,
     });
@@ -41,7 +38,8 @@ describe("QuickbaseClient Unit - User Token Retry on 401", () => {
       expect.objectContaining({
         method: "GET",
         headers: expect.objectContaining({
-          Authorization: `QB-USER-TOKEN ${userToken}`,
+          Authorization:
+            "QB-USER-TOKEN b9f3pk_q4jd_0_b4qu5eebyvuix3xs57ysd7zn3",
           "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
           "Content-Type": "application/json",
         }),
@@ -53,17 +51,16 @@ describe("QuickbaseClient Unit - User Token Retry on 401", () => {
       expect.objectContaining({
         method: "GET",
         headers: expect.objectContaining({
-          Authorization: `QB-USER-TOKEN ${userToken}`,
+          Authorization:
+            "QB-USER-TOKEN b9f3pk_q4jd_0_b4qu5eebyvuix3xs57ysd7zn3",
           "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
           "Content-Type": "application/json",
         }),
       })
     );
     expect(consoleSpy).toHaveBeenCalledWith(
-      `Retrying getFields with existing user token: b9f3pk_q4j...`
-    );
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "[getFields] Retrying with token: b9f3pk_q4j..."
+      "Retrying getFields with existing user token: b9f3pk_q4j..."
     );
+    consoleSpy.mockRestore();
   });
 });

package/tests/vitest/unit/quickbase-js/BurstAwareThrottleBucket.test.ts

@@ -0,0 +1,108 @@
+// test/vitest/unit/BurstAwareThrottleBucket.test.ts
+import { describe, it, expect } from "vitest";
+import { BurstAwareThrottleBucket } from "@/BurstAwareThrottleBucket";
+
+describe("BurstAwareThrottleBucket Unit Tests", () => {
+  it("allows burst capacity immediately", async () => {
+    const bucket = new BurstAwareThrottleBucket({
+      maxTokens: 3,
+      windowSeconds: 10,
+    });
+    const startTime = Date.now();
+
+    await Promise.all([
+      bucket.acquire().then(() => bucket.release()),
+      bucket.acquire().then(() => bucket.release()),
+      bucket.acquire().then(() => bucket.release()),
+    ]);
+
+    const duration = Date.now() - startTime;
+    expect(duration).toBeLessThan(50);
+  });
+
+  it("delays calls beyond burst until window reset", async () => {
+    const bucket = new BurstAwareThrottleBucket({
+      maxTokens: 3,
+      windowSeconds: 0.5,
+    });
+    const timings: number[] = [];
+    const recordTime = async () => {
+      await bucket.acquire();
+      timings.push(Date.now());
+      bucket.release();
+    };
+
+    const startTime = Date.now();
+    await Promise.all([recordTime(), recordTime(), recordTime(), recordTime()]);
+
+    const durations = timings.map((t) => t - startTime);
+    expect(durations.length).toBe(4);
+    expect(durations[0]).toBeLessThan(50);
+    expect(durations[1]).toBeLessThan(50);
+    expect(durations[2]).toBeLessThan(50);
+    expect(durations[3]).toBeGreaterThanOrEqual(450);
+    expect(durations[3]).toBeLessThan(600); // Relaxed from 550 to 600
+  });
+
+  it("maintains burst limit over sustained calls with window", async () => {
+    const bucket = new BurstAwareThrottleBucket({
+      maxTokens: 2,
+      windowSeconds: 0.5,
+    });
+    const timings: number[] = [];
+    const recordTime = async () => {
+      await bucket.acquire();
+      timings.push(Date.now());
+      bucket.release();
+    };
+
+    const startTime = Date.now();
+    await Promise.all([
+      recordTime(),
+      recordTime(),
+      recordTime(),
+      recordTime(),
+      recordTime(),
+    ]);
+
+    const durations = timings.map((t) => t - startTime);
+    expect(durations.length).toBe(5);
+    expect(durations[0]).toBeLessThan(50);
+    expect(durations[1]).toBeLessThan(50);
+    expect(durations[2]).toBeGreaterThanOrEqual(450);
+    expect(durations[2]).toBeLessThan(600); // Relaxed from 550 to 600
+    expect(durations[3]).toBeGreaterThanOrEqual(450);
+    expect(durations[3]).toBeLessThan(600); // Relaxed from 550 to 600
+    expect(durations[4]).toBeGreaterThanOrEqual(950);
+    expect(durations[4]).toBeLessThan(1100); // Relaxed from 1050 to 1100
+  });
+
+  it("handles high concurrency without exceeding burst within window", async () => {
+    const bucket = new BurstAwareThrottleBucket({
+      maxTokens: 3,
+      windowSeconds: 0.5,
+    });
+    const timings: number[] = [];
+    const recordTime = async () => {
+      await bucket.acquire();
+      timings.push(Date.now());
+      bucket.release();
+    };
+
+    const startTime = Date.now();
+    await Promise.all(
+      Array(10)
+        .fill(null)
+        .map(() => recordTime())
+    );
+
+    const durations = timings.map((t) => t - startTime);
+    expect(durations.length).toBe(10);
+    expect(durations.slice(0, 3).every((d) => d < 50)).toBe(true);
+    for (let i = 3; i < 10; i++) {
+      const expectedDelay = Math.floor((i - 3) / 3) * 500 + 450;
+      expect(durations[i]).toBeGreaterThanOrEqual(expectedDelay - 50);
+      expect(durations[i]).toBeLessThan(expectedDelay + 100); // Relaxed from 50 to 100
+    }
+  });
+});

package/tests/vitest/unit/{ThrottleBucket.test.ts → quickbase-js/FlowBucket.test.ts}

@@ -1,23 +1,29 @@
+// test/vitest/unit/ThrottleBucket.test.ts
 import { describe, it, expect, vi } from "vitest";
-import { ThrottleBucket } from "@/ThrottleBucket"; // Adjust path as needed
+import { FlowThrottleBucket } from "@/FlowThrottleBucket"; // Should work with your alias
 
-describe("ThrottleBucket Unit Tests", () => {
+describe("ConcurrentThrottleBucket Unit Tests", () => {
   it("allows burst capacity immediately", async () => {
-    const bucket = new ThrottleBucket(5, 3); // rate: 5, burst: 3
+    const bucket = new FlowThrottleBucket(5, 3); // rate: 5, burst: 3
     const startTime = Date.now();
 
-    await Promise.all([bucket.acquire(), bucket.acquire(), bucket.acquire()]);
+    await Promise.all([
+      bucket.acquire().then(() => bucket.release()),
+      bucket.acquire().then(() => bucket.release()),
+      bucket.acquire().then(() => bucket.release()),
+    ]);
 
     const duration = Date.now() - startTime;
     expect(duration).toBeLessThan(50); // All 3 should be instant (within 50ms)
   });
 
   it("delays calls beyond burst at correct rate", async () => {
-    const bucket = new ThrottleBucket(5, 3); // rate: 5 tokens/sec, burst: 3
+    const bucket = new FlowThrottleBucket(5, 3); // rate: 5 tokens/sec, burst: 3
     const timings: number[] = [];
     const recordTime = async () => {
       await bucket.acquire();
       timings.push(Date.now());
+      bucket.release(); // Release slot
     };
 
     const startTime = Date.now();
@@ -38,11 +44,12 @@ describe("ThrottleBucket Unit Tests", () => {
   });
 
   it("maintains rate over sustained calls", async () => {
-    const bucket = new ThrottleBucket(2, 2); // rate: 2 tokens/sec, burst: 2
+    const bucket = new FlowThrottleBucket(2, 2); // rate: 2 tokens/sec, burst: 2
     const timings: number[] = [];
     const recordTime = async () => {
       await bucket.acquire();
       timings.push(Date.now());
+      bucket.release(); // Release slot
     };
 
     const startTime = Date.now();
@@ -67,11 +74,12 @@ describe("ThrottleBucket Unit Tests", () => {
   });
 
   it("handles high concurrency without exceeding burst", async () => {
-    const bucket = new ThrottleBucket(5, 3); // rate: 5, burst: 3
+    const bucket = new FlowThrottleBucket(5, 3); // rate: 5, burst: 3
     const timings: number[] = [];
     const recordTime = async () => {
       await bucket.acquire();
       timings.push(Date.now());
+      bucket.release(); // Release slot
     };
 
     const startTime = Date.now();
@@ -83,9 +91,7 @@ describe("ThrottleBucket Unit Tests", () => {
 
     const durations = timings.map((t) => t - startTime);
     expect(durations.length).toBe(10);
-    // First 3 should be instant
-    expect(durations.slice(0, 3).every((d) => d < 50)).toBe(true);
-    // Next calls should be staggered at ~200ms intervals
+    expect(durations.slice(0, 3).every((d) => d < 50)).toBe(true); // First 3 instant
     for (let i = 3; i < 10; i++) {
       const expectedDelay = (i - 2) * 200; // After burst, 200ms per token
       expect(durations[i]).toBeGreaterThanOrEqual(expectedDelay - 50);