feat!: Rename Object Store and related APIs to KV Store (#476)

Author: JakeChampion

.github/workflows/main.yml

@@ -10,7 +10,7 @@ defaults:
   run:
     shell: bash
 env:
-  viceroy_version: 0.3.5
+  viceroy_version: 0.4.4
   wasm-tools_version: 1.0.28
 
 jobs:
@@ -129,7 +129,7 @@ jobs:
       matrix:
         include:
           - crate: viceroy
-            version: 0.3.5 # Note: workflow-level env vars can't be used in matrix definitions
+            version: 0.4.4 # Note: workflow-level env vars can't be used in matrix definitions
             options: ""
           - crate: wasm-tools
             version: 1.0.28 # Note: workflow-level env vars can't be used in matrix definitions
@@ -237,7 +237,7 @@ jobs:
           - log
           - missing-backend
           - multiple-set-cookie
-          - object-store
+          - kv-store
           - random
           - react-byob
           - regex
@@ -391,7 +391,7 @@ jobs:
           - 'geoip'
           - 'hello-world'
           - 'multiple-set-cookie'
-          - 'object-store'
+          - 'kv-store'
           - 'react-byob'
           - 'request-clone'
           - 'request-headers'

documentation/README.md

@@ -30,4 +30,4 @@ This command generates static content into the `build` directory and can be serv
 $ yarn deploy
 ```
 
-This command will run `yarn build` and then will upload the website to Fastly Object Store and deploy the application to Fastly Compute@Edge.
+This command will run `yarn build` and then will upload the website to Fastly KV Store and deploy the application to Fastly Compute@Edge.

documentation/app/fastly.toml

@@ -13,4 +13,4 @@ service_id = "1B3wrEgiLdTaCjsmK5Jq25"
 
 [local_server]
 
-[local_server.object_store]
+[local_server.kv_stores]

documentation/docs/fastly:kv-store/KVStore/KVStore.mdx

@@ -0,0 +1,62 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# `KVStore()`
+
+The **`KVStore` constructor** lets you connect your Compute@Edge application to a Fastly KV store.
+
+A Fastly KV store is a persistent, globally consistent key-value store. See [Data stores for Fastly services](https://developer.fastly.com/learning/concepts/kv-stores/#kv-stores) for initialization and usage details.
+
+>**Note**: Can only be used when processing requests, not during build-time initialization.
+
+## Syntax
+
+```js
+new KVStore(name)
+```
+
+> **Note:** `KVStore()` can only be constructed with `new`. Attempting to call it without `new` throws a [`TypeError`](../../globals/TypeError/TypeError.mdx).
+
+### Parameters
+
+- `name` _: string_
+  - The Fastly KV store which should be associated with this KVStore instance
+  
+### Return value
+
+A new `KVStore` object.
+
+### Exceptions
+
+- `TypeError`
+  - Thrown if no KV Store exists with the provided name
+  - Thrown if the provided name is longer than 255 in length
+  - Thrown if the provided name is an empty string
+  - Thrown if the provided name does not start with an ascii alphabetical character 
+  - Thrown if the provided name contains control characters `(\u0000-\u001F)`
+
+## Examples
+
+In this example we connect to an KV Store named `'files'` and save an entry to the store under the key `'hello'` and then read back the value and return it to the client.
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { KVStore } from "fastly:kv-store";
+
+async function app(event) {
+  const files = new KVStore('files')
+
+  await files.put('hello', 'world')
+
+  const entry = await files.get('hello')
+
+  return new Response(await entry.text())
+}
+
+addEventListener("fetch", (event) => event.respondWith(app(event)))
+
+```

documentation/docs/fastly:kv-store/KVStore/prototype/get.mdx

@@ -0,0 +1,68 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# KVStore.prototype.get
+
+▸ **get**(): `string`
+
+Gets the value associated with the key `key` in the KV store.
+
+## Syntax
+
+```js
+get(key)
+```
+
+### Parameters
+
+- `key` _: string_
+  - The key to retrieve from within the KV-store.
+
+### Return value
+
+If the key does not exist in the KV store, this returns a `Promise` which resolves with `null`.
+
+If the key does exist in the KV store, this returns a `Promise` which resolves with an `KVStoreEntry`.
+
+## Description
+
+Send the given message, converted to a string, to this KVStore instance's endpoint.
+
+The `get()` method requires its `this` value to be a [`KVStore`](../KVStore.mdx) object.
+
+If the `this` value does not inherit from `KVStore.prototype`, a [`TypeError`](../../../globals/TypeError/TypeError.mdx) is thrown.
+
+### Exceptions
+
+- `TypeError`
+  - If the provided `key`:
+    - Is any of the strings `""`, `"."`, or `".."`
+    - Starts with the string `".well-known/acme-challenge/"`
+    - Contains any of the characters `"#?*[]\n\r"`
+    - Is longer than 1024 characters
+
+## Examples
+
+In this example we connect to an KV Store named `'files'` and save an entry to the store under the key `'hello'` and then read back the value and return it to the client.
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { KVStore } from "fastly:kv-store";
+
+async function app(event) {
+  const files = new KVStore('files')
+
+  await files.put('hello', 'world')
+
+  const entry = await files.get('hello')
+
+  return new Response(await entry.text())
+}
+
+addEventListener("fetch", (event) => event.respondWith(app(event)))
+
+```

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

@@ -0,0 +1,68 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# KVStore.prototype.put
+
+The **`put()`** method stores a `value` into the KV store under a `key`.
+
+> **Note**: KV stores are eventually consistent, this means that the updated contents associated with the key `key` may not be available to read from all edge locations immediately and some edge locations may continue returning the previous contents associated with the key.
+
+## Syntax
+
+```js
+put(key, value)
+```
+
+### Parameters
+
+- `key` _: string_
+  - 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.
+
+### Return value
+
+Returns a `Promise` which resolves with `undefined` when the provided `value` has been written into the KV store.
+
+## Description
+
+Stores the supplied `value` into the KV store under the supplied `key`.
+
+The `put()` method requires its `this` value to be a [`KVStore`](../KVStore.mdx) object.
+
+If the `this` value does not inherit from `KVStore.prototype`, a [`TypeError`](../../../globals/TypeError/TypeError.mdx) is thrown.
+
+### Exceptions
+
+- `TypeError`
+  - If the provided `key`:
+    - Is any of the strings `""`, `"."`, or `".."`
+    - Starts with the string `".well-known/acme-challenge/"`
+    - Contains any of the characters `"#?*[]\n\r"`
+    - Is longer than 1024 characters
+
+## Examples
+
+In this example we connect to an KV Store named `'files'` and save an entry to the store under the key `'hello'` and then read back the value and return it to the client.
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { KVStore } from "fastly:kv-store";
+
+async function app(event) {
+  const files = new KVStore('files')
+
+  await files.put('hello', 'world')
+
+  const entry = await files.put('hello')
+
+  return new Response(await entry.text())
+}
+
+addEventListener("fetch", (event) => event.respondWith(app(event)))
+
+```