feat!: Rename SimpleCache.delete to SimpleCache.purge and require purge options to be supplied as the second parameter

We are renaming because "purge" is already a well-known and documented concept for removing content from Fastly's cache.

The second argument allows the caller to decide what scope to purge the content from, currently they can choose to purge from all of Fastly ("global") or from the POP that contains the currently executing instance ("pop"). We do not provide a default option right now, in the future we may provide a default option, if we discover a common pattern is being used.

Author: Jake Champion

documentation/docs/fastly:cache/SimpleCache/delete.mdx

@@ -0,0 +1,89 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# SimpleCache.purge
+
+purge the entry associated with the key `key` from the cache.
+
+## Syntax
+
+```js
+purge(key, options)
+```
+
+### Parameters
+
+- `key` _: string_
+  - The key to purge from within the cache.
+
+- `options` _: object_
+  - `scope` _: string_
+    - : Where to purge the content from.
+    - Possible values are:
+      - "global" - This will remove the content from all of Fastly.
+      - "pop" - This will remove the content from the POP that contains the currently executing instance.
+  - `headers`
+    - : Any headers you want to add to your request, contained
+      within a `Headers` object or an object literal with `String` values.
+  - `body`
+    - : Any body that you want to add to your request: this can be an `ArrayBuffer`, a `TypedArray`, a `DataView`, a `URLSearchParams`, string object or literal, or a `ReadableStream` object.
+  - `backend` _**Fastly-specific**_
+  - `cacheOverride` _**Fastly-specific**_
+  - `cacheKey` _**Fastly-specific**_
+
+### Return value
+
+Returns `undefined`.
+
+### Exceptions
+
+- `TypeError`
+  - If the provided `key`:
+    - Is an empty string
+    - Cannot be coerced to a string
+    - Is longer than 8135 characters
+
+## Examples
+
+In this example, when a request contains a `purge` querystring parameter, we purge the an entry from the cache.
+
+```js
+/// <reference types="@fastly/js-compute" />
+
+import { SimpleCache } from 'fastly:cache';
+
+addEventListener('fetch', event => event.respondWith(app(event)));
+
+async function app(event) {
+  const url = new URL(event.request);
+  const path = url.pathname;
+  if (url.searchParams.has('purge')) {
+    SimpleCache.purge(path, { scope: "global" });
+    return new Response(page, { status: 204 });
+  }
+
+  let page = SimpleCache.getOrSet(path, async () => {
+    return {
+      value: await render(path),
+      // Store the page in the cache for 1 minute.
+      ttl: 60
+    }
+  });
+  return new Response(page, {
+    headers: {
+      'content-type': 'text/plain;charset=UTF-8'
+    }
+  });
+}
+
+async function render(path) {
+  // expensive/slow function which constructs and returns the contents for a given path
+  await new Promise(resolve => setTimeout(resolve, 10_000));
+  return path;
+}
+
+```

documentation/docs/fastly:cache/SimpleCache/purge.mdx

@@ -8,7 +8,7 @@ import { SimpleCache, SimpleCacheEntry } from 'fastly:cache';
 let error;
 routes.set("/simple-cache/interface", () => {
     let actual = Reflect.ownKeys(SimpleCache)
-    let expected = ["prototype", "delete", "get", "getOrSet", "set", "length", "name"]
+    let expected = ["prototype", "purge", "get", "getOrSet", "set", "length", "name"]
     error = assert(actual, expected, `Reflect.ownKeys(SimpleCache)`)
     if (error) { return error }
 
@@ -163,34 +163,34 @@ routes.set("/simple-cache/interface", () => {
         if (error) { return error }
     }
 
-    // Check the delete static method has correct descriptors, length and name
+    // Check the purge static method has correct descriptors, length and name
     {
-        actual = Reflect.getOwnPropertyDescriptor(SimpleCache, 'delete')
-        expected = { "writable": true, "enumerable": true, "configurable": true, value: SimpleCache.delete }
-        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache, 'delete')`)
+        actual = Reflect.getOwnPropertyDescriptor(SimpleCache, 'purge')
+        expected = { "writable": true, "enumerable": true, "configurable": true, value: SimpleCache.purge }
+        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache, 'purge')`)
         if (error) { return error }
 
-        error = assert(typeof SimpleCache.delete, 'function', `typeof SimpleCache.delete`)
+        error = assert(typeof SimpleCache.purge, 'function', `typeof SimpleCache.purge`)
         if (error) { return error }
 
-        actual = Reflect.getOwnPropertyDescriptor(SimpleCache.delete, 'length')
+        actual = Reflect.getOwnPropertyDescriptor(SimpleCache.purge, 'length')
         expected = {
-            "value": 1,
+            "value": 2,
             "writable": false,
             "enumerable": false,
             "configurable": true
         }
-        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache.delete, 'length')`)
+        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache.purge, 'length')`)
         if (error) { return error }
 
-        actual = Reflect.getOwnPropertyDescriptor(SimpleCache.delete, 'name')
+        actual = Reflect.getOwnPropertyDescriptor(SimpleCache.purge, 'name')
         expected = {
-            "value": "delete",
+            "value": "purge",
             "writable": false,
             "enumerable": false,
             "configurable": true
         }
-        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache.delete, 'name')`)
+        error = assert(actual, expected, `Reflect.getOwnPropertyDescriptor(SimpleCache.purge, 'name')`)
         if (error) { return error }
     }
 
@@ -245,19 +245,19 @@ routes.set("/simple-cache/interface", () => {
     });
 }
 
-// SimpleCache delete static method
-// static delete(key: string): undefined;
+// SimpleCache purge static method
+// static purge(key: string, options: PurgeOptions): undefined;
 {
-    routes.set("/simple-cache/delete/called-as-constructor", () => {
+    routes.set("/simple-cache/purge/called-as-constructor", () => {
         error = assertThrows(() => {
-            new SimpleCache.delete('1')
-        }, TypeError, `SimpleCache.delete is not a constructor`)
+            new SimpleCache.purge('1', {scope:"global"})
+        }, TypeError, `SimpleCache.purge is not a constructor`)
         if (error) { return error }
         return pass()
     });
     // Ensure we correctly coerce the parameter to a string as according to
     // https://tc39.es/ecma262/#sec-tostring
-    routes.set("/simple-cache/delete/key-parameter-calls-7.1.17-ToString", () => {
+    routes.set("/simple-cache/purge/key-parameter-calls-7.1.17-ToString", () => {
         let sentinel;
         const test = () => {
             sentinel = Symbol('sentinel');
@@ -266,7 +266,7 @@ routes.set("/simple-cache/interface", () => {
                     throw sentinel;
                 }
             }
-            SimpleCache.delete(key)
+            SimpleCache.purge(key, {scope:"global"})
         }
         error = assertThrows(test)
         if (error) { return error }
@@ -277,43 +277,71 @@ routes.set("/simple-cache/interface", () => {
             if (error) { return error }
         }
         error = assertThrows(() => {
-            SimpleCache.delete(Symbol())
+            SimpleCache.purge(Symbol(),{scope:"global"})
         }, TypeError, `can't convert symbol to string`)
         if (error) { return error }
         return pass()
     });
-    routes.set("/simple-cache/delete/key-parameter-not-supplied", () => {
+    routes.set("/simple-cache/purge/key-parameter-not-supplied", () => {
         error = assertThrows(() => {
-            SimpleCache.delete()
-        }, TypeError, `SimpleCache.delete: At least 1 argument required, but only 0 passed`)
+            SimpleCache.purge()
+        }, TypeError, `SimpleCache.purge: At least 2 arguments required, but only 0 passed`)
         if (error) { return error }
         return pass()
     });
-    routes.set("/simple-cache/delete/key-parameter-empty-string", () => {
+    routes.set("/simple-cache/purge/key-parameter-empty-string", () => {
         error = assertThrows(() => {
-            SimpleCache.delete('')
-        }, Error, `SimpleCache.delete: key can not be an empty string`)
+            SimpleCache.purge('',{scope:"global"})
+        }, Error, `SimpleCache.purge: key can not be an empty string`)
         if (error) { return error }
         return pass()
     });
-    routes.set("/simple-cache/delete/key-parameter-8135-character-string", () => {
+    routes.set("/simple-cache/purge/key-parameter-8135-character-string", () => {
         error = assertDoesNotThrow(() => {
             const key = 'a'.repeat(8135)
-            SimpleCache.delete(key)
+            SimpleCache.purge(key,{scope:"global"})
         })
         if (error) { return error }
         return pass()
     });
-    routes.set("/simple-cache/delete/key-parameter-8136-character-string", () => {
+    routes.set("/simple-cache/purge/key-parameter-8136-character-string", () => {
         error = assertThrows(() => {
             const key = 'a'.repeat(8136)
-            SimpleCache.delete(key)
-        }, Error, `SimpleCache.delete: key is too long, the maximum allowed length is 8135.`)
+            SimpleCache.purge(key,{scope:"global"})
+        }, Error, `SimpleCache.purge: key is too long, the maximum allowed length is 8135.`)
+        if (error) { return error }
+        return pass()
+    });
+    routes.set("/simple-cache/purge/options-parameter", () => {
+        error = assertThrows(() => {
+            const key = 'a'
+            SimpleCache.purge(key, "hello")
+        }, Error, `SimpleCache.purge: options parameter is not an object.`)
+        if (error) { return error }
+        error = assertThrows(() => {
+            const key = 'a'
+            SimpleCache.purge(key, {scope: Symbol()})
+        }, Error, `can't convert symbol to string`)
+        if (error) { return error }
+        error = assertThrows(() => {
+            const key = 'a'
+            SimpleCache.purge(key, {scope: ""})
+        }, Error, `SimpleCache.purge: scope field of options parameter must be either 'pop', or 'global'.`)
+        if (error) { return error }
+        error = assertDoesNotThrow(() => {
+            const key = 'a'
+            SimpleCache.purge(key, {scope: "pop"})
+        })
+        if (error) { return error }
+        error = assertDoesNotThrow(() => {
+            const key = 'a'
+            SimpleCache.purge(key, {scope: "global"})
+        })
         if (error) { return error }
         return pass()
     });
-    routes.set("/simple-cache/delete/returns-undefined", () => {
-        error = assert(SimpleCache.delete('meow'), undefined, "SimpleCache.delete('meow') === undefined")
+    routes.set("/simple-cache/purge/returns-undefined", () => {
+        error = assert(SimpleCache.purge('meow', {scope:"global"}), undefined, "SimpleCache.purge('meow', {scope'global'})")
         if (error) { return error }
         return pass()
     });