From cb9b96dd2e72395bcc8a792a4629b84ff04d46ed Mon Sep 17 00:00:00 2001
From: Heyang Zhou <zhy20000919@hotmail.com>
Date: Fri, 15 Sep 2023 03:47:10 +0800
Subject: [PATCH] docs: add key expiration (#731)

* docs: add key expiration

* fix typeck
---
 runtime/kv/key_expiration.md | 52 ++++++++++++++++++++++++++++++++++++
 toc.json                     |  3 ++-
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 runtime/kv/key_expiration.md

diff --git a/runtime/kv/key_expiration.md b/runtime/kv/key_expiration.md
new file mode 100644
index 00000000..7ddede75
--- /dev/null
+++ b/runtime/kv/key_expiration.md
@@ -0,0 +1,52 @@
+# Key Expiration
+
+> ⚠️ Deno KV is currently **experimental** and **subject to change**. While we do
+> our best to ensure data durability, data loss is possible, especially around
+> Deno updates. We recommend that you backup your data regularly and consider
+> storing data in a secondary store for the time being.
+
+> 🌐 Deno KV is available for Deno Deploy.
+> [Read the Deno Deploy KV docs](https://deno.com/deploy/docs/kv).
+
+Since version 1.36.2, Deno KV supports key expiration. This allows an expiration
+timestamp to be associated with a key, after which the key will be automatically
+deleted from the database:
+
+```ts,ignore
+const kv = await Deno.openKv();
+
+// `expireIn` is the number of milliseconds after which the key will expire.
+function addSession(session: Session, expireIn: number) {
+  await kv.set(["sessions", session.id], session, { expireIn });
+}
+```
+
+Key expiration is supported on both Deno CLI and Deno Deploy.
+
+## Atomic expiration of multiple keys
+
+If multiple keys are set in the same atomic operation and have the same
+`expireIn` value, the expiration of those keys will be atomic. For example:
+
+```ts,ignore
+const kv = await Deno.openKv();
+
+function addUnverifiedUser(
+  user: User,
+  verificationToken: string,
+  expireIn: number,
+) {
+  await kv.atomic()
+    .set(["users", user.id], user, { expireIn })
+    .set(["verificationTokens", verificationToken], user.id, { expireIn })
+    .commit();
+}
+```
+
+## Caveats
+
+The expire timestamp specifies the _earliest_ time after which the key can be
+deleted from the database. An implementation is allowed to expire a key at any
+time after the specified timestamp, but not before. If you need to strictly
+enforce an expiration time (e.g. for security purposes), please also add it as a
+field of your value and do a check after retrieving the value from the database.
diff --git a/toc.json b/toc.json
index c9967ec0..fd3791d6 100644
--- a/toc.json
+++ b/toc.json
@@ -143,7 +143,8 @@
           "operations": "Operations",
           "transactions": "Transactions",
           "secondary_indexes": "Secondary indexes",
-          "key_space": "Key Space"
+          "key_space": "Key Space",
+          "key_expiration": "Key Expiration"
         }
       },
       "location_api": "Location API",