docs: document new KVStore features, add some edge case tests (#1030)

Author: Guy Bedford

documentation/docs/backend/Backend/prototype/tcpKeepalive.mdx

@@ -11,11 +11,11 @@ The read-only **`tcpKeepalive`** property of a `Backend` instance returns an obj
 the TCP keepalive configuration, if any, otherwise returning `null` if TCP keepalive is not enabled.
 
 This object has the following properties:
-- `timeSecs` _: number or null.
+- `timeSecs` _: number or null._
   - Configure how long to wait after the last sent data over the TCP connection before starting to send TCP keepalive probes.
-- `intervalSecs` _: number or null.
+- `intervalSecs` _: number or null._
   - Configure how long to wait between each TCP keepalive probe sent to the backend to determine if it is still active.
-- `probes` _: number or null.
+- `probes` _: number or null._
   - Number of probes to send to the backend before it is considered dead.
 
 ## Value

documentation/docs/kv-store/KVStore/prototype/list.mdx

@@ -0,0 +1,59 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# KVStore.prototype.list
+
+The **`list()`** can be used to list the keys of a store.
+
+## Syntax
+
+```js
+list(options?)
+```
+
+### Parameters
+
+- `options` _: object_ _**optional**_
+  - List options supporting properties:
+  - `cursor` _: string_ _**optional**_
+    - The cursor used to pick up from a previous iteration.
+  - `limit` _: number_ _**optional**_
+    - The maximum number of keys to return.
+  - `prefix` _: string_ _**optional**_
+    - List only those keys that start with the given string prefix.
+  - `noSync` _: boolean_ _**optional**_
+    - Do not sync the key list first, instead provide a possibly out-of-date listing. May be faster but inconsistent.
+
+### Return value
+
+Returns a `Promise` which resolves with `{ list: string[], cursor: string | undefined }`.
+
+## Example
+
+In this example we list the keys of a KV Store named `'files'`, iterating 10 at a time, counting the total;
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { KVStore } from 'fastly:kv-store';
+
+async function app(event) {
+  const files = new KVStore('files');
+
+  let cursor,
+    list,
+    total = 0;
+  do {
+    ({ cursor, list } = await files.list({ limit: 10, cursor }));
+    total += list?.length;
+  } while (list);
+
+  return new Response(`Iterated ${total} entries`);
+}
+
+addEventListener('fetch', (event) => event.respondWith(app(event)));
+```

documentation/docs/kv-store/KVStore/prototype/put.mdx

@@ -13,7 +13,7 @@ The **`put()`** method stores a `value` into the KV store under a `key`.
 ## Syntax
 
 ```js
-put(key, value)
+put(key, value, options?)
 ```
 
 ### Parameters
@@ -22,6 +22,14 @@ put(key, value)
   - The key to store the supplied value under within the KV store.
 - `value` _:  ArrayBuffer | TypedArray | DataView| ReadableStream | URLSearchParams | String | string literal_
   - The value to store within the KV store.
+- `options` _: object_ _**optional**_
+  - An insert options parameter, supporting:
+  - `metadata` _: ArrayBuffer | TypedArray | DataView_ _**optional**_
+    - Binary metadata associated with the entry, may be up to 1000 bytes.
+  - `ttl` _: number_ _**optional**_
+    - TTL for the entry
+  - `mode` _: 'overwrite' | 'add' | 'append' | 'prepend'_ _**optional**_
+    - Insert mode, defaults to 'overwrite'
 
 ### Return value
 

documentation/docs/kv-store/KVStoreEntry/prototype/metadata.mdx

@@ -0,0 +1,26 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# KVStoreEntry.metadata()
+
+The `metadata()` method of the `KVStoreEntry` interface provides the binary metadata associated with the `KVStoreEntry`.
+
+The metadata binary may be up to 1000 bytes, and is returned as a `Uint8Array` TypedArray buffer, if metadata is set, or null otherwise.
+
+## Syntax
+
+```js
+metadata()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A `Promise` that resolves to a `Uint8Array` buffer object.

documentation/docs/kv-store/KVStoreEntry/prototype/metadataText.mdx

@@ -0,0 +1,26 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# KVStoreEntry.metadataText()
+
+The `metadataText()` method of the `KVStoreEntry` interface provides a String interpretation of binary metadata associated with the `KVStoreEntry`.
+
+If the binary data is not a valid string, an encoding error will be thrown.
+
+## Syntax
+
+```js
+metadataText()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A `Promise` that resolves to a String.

integration-tests/js-compute/fixtures/module-mode/src/kv-store.js

@@ -55,11 +55,19 @@ import { routes, isRunningLocally } from './routes.js';
     // TTL only supported on compute not viceroy
     if (!isRunningLocally()) {
       await store.put('t', 't', { ttl: 2 });
-      strictEqual(await (await store.get('t')).text(), 't');
+      const tEntry = await store.get('t');
+      strictEqual(await tEntry.text(), 't');
+      const metadata = await tEntry.metadata();
+      strictEqual(metadata, null);
       await new Promise((resolve) => setTimeout(resolve, 2000));
       strictEqual(await store.get('t'), null);
     }
 
+    // bad cursor gives a "bad request" error
+    assertRejects(async () => {
+      await store.list({ cursor: 'boooo' });
+    }, TypeError);
+
     assertThrows(() => {
       store.list({ limit: 'booooo' });
     }, TypeError);
@@ -86,7 +94,6 @@ import { routes, isRunningLocally } from './routes.js';
     ]);
 
     ({ list, cursor } = await store.list({ limit: 10, prefix: 'c', cursor }));
-
     deepStrictEqual(list, [
       'c18',
       'c19',
@@ -99,6 +106,95 @@ import { routes, isRunningLocally } from './routes.js';
       'c25',
       'c26',
     ]);
+
+    ({ list, cursor } = await store.list({ limit: 70, prefix: 'c', cursor }));
+    deepStrictEqual(list, [
+      'c27',
+      'c28',
+      'c29',
+      'c3',
+      'c30',
+      'c31',
+      'c32',
+      'c33',
+      'c34',
+      'c35',
+      'c36',
+      'c37',
+      'c38',
+      'c39',
+      'c4',
+      'c40',
+      'c41',
+      'c42',
+      'c43',
+      'c44',
+      'c45',
+      'c46',
+      'c47',
+      'c48',
+      'c49',
+      'c5',
+      'c50',
+      'c51',
+      'c52',
+      'c53',
+      'c54',
+      'c55',
+      'c56',
+      'c57',
+      'c58',
+      'c59',
+      'c6',
+      'c60',
+      'c61',
+      'c62',
+      'c63',
+      'c64',
+      'c65',
+      'c66',
+      'c67',
+      'c68',
+      'c69',
+      'c7',
+      'c70',
+      'c71',
+      'c72',
+      'c73',
+      'c74',
+      'c75',
+      'c76',
+      'c77',
+      'c78',
+      'c79',
+      'c8',
+      'c80',
+      'c81',
+      'c82',
+      'c83',
+      'c84',
+      'c85',
+      'c86',
+      'c87',
+      'c88',
+      'c89',
+      'c9',
+    ]);
+
+    ({ list, cursor } = await store.list({ limit: 15, prefix: 'c', cursor }));
+    deepStrictEqual(list, [
+      'c90',
+      'c91',
+      'c92',
+      'c93',
+      'c94',
+      'c95',
+      'c96',
+      'c97',
+      'c98',
+      'c99',
+    ]);
+    strictEqual(cursor, undefined);
   });
 }
 

types/kv-store.d.ts

@@ -84,7 +84,7 @@ declare module 'fastly:kv-store' {
          */
         metadata?: ArrayBufferView | ArrayBuffer | string;
         /**
-         * TTL for the entry, defaults to 0.
+         * TTL for the entry.
          */
         ttl?: number;
         /**
@@ -120,9 +120,11 @@ declare module 'fastly:kv-store' {
     }): {
       list: string[];
       /**
-       * Pass this base64 cursor into a subsequent list call to obtain the next listing
+       * Pass this base64 cursor into a subsequent list call to obtain the next listing.
+       * 
+       * The cursor is *undefined* when the end of the list is reached.
        */
-      cursor: string;
+      cursor: string | undefined;
     };
   }