fix(kv): improve backoff error message and inline documentation (#27537)

Ref: #27536

cli/tsc/dts/lib.deno.unstable.d.ts

@@ -293,7 +293,8 @@ declare namespace Deno {
    * executions. Each element in the array represents the number of milliseconds
    * to wait before retrying the execution. For example, `[1000, 5000, 10000]`
    * means that a failed execution will be retried at most 3 times, with 1
-   * second, 5 seconds, and 10 seconds delay between each retry.
+   * second, 5 seconds, and 10 seconds delay between each retry. There is a
+   * limit of 5 retries and a maximum interval of 1 hour (3600000 milliseconds).
    *
    * @category Cloud
    * @experimental

ext/kv/01_db.ts

@@ -77,7 +77,9 @@ const maxQueueBackoffInterval = 60 * 60 * 1000;
 
 function validateBackoffSchedule(backoffSchedule: number[]) {
   if (backoffSchedule.length > maxQueueBackoffIntervals) {
-    throw new TypeError("Invalid backoffSchedule");
+    throw new TypeError(
+      `Invalid backoffSchedule, max ${maxQueueBackoffIntervals} intervals allowed`,
+    );
   }
   for (let i = 0; i < backoffSchedule.length; ++i) {
     const interval = backoffSchedule[i];
@@ -85,7 +87,9 @@ function validateBackoffSchedule(backoffSchedule: number[]) {
       interval < 0 || interval > maxQueueBackoffInterval ||
       NumberIsNaN(interval)
     ) {
-      throw new TypeError("Invalid backoffSchedule");
+      throw new TypeError(
+        `Invalid backoffSchedule, interval at index ${i} is invalid`,
+      );
     }
   }
 }

tests/unit/kv_test.ts

@@ -1951,14 +1951,14 @@ dbTest("Invalid backoffSchedule", async (db) => {
       await db.enqueue("foo", { backoffSchedule: [1, 1, 1, 1, 1, 1] });
     },
     TypeError,
-    "Invalid backoffSchedule",
+    "Invalid backoffSchedule, max 5 intervals allowed",
   );
   await assertRejects(
     async () => {
       await db.enqueue("foo", { backoffSchedule: [3600001] });
     },
     TypeError,
-    "Invalid backoffSchedule",
+    "Invalid backoffSchedule, interval at index 0 is invalid",
   );
 });