Merge pull request #45 from denoland/docs_1_36

pick up docs update from last 30 days

.github/workflows/deploy.yml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: Clone repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Node.js
         uses: actions/setup-node@v3

kv/manual/key_expiration.md

@@ -0,0 +1,59 @@
+# Key Expiration
+
+:::caution Deno KV is currently in beta
+
+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.
+
+Excuting Deno programs that use KV currently requires the `--unstable` flag, as
+below:
+
+```sh
+deno run -A --unstable my_kv_code.ts
+```
+
+:::
+
+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.

kv/manual/on_deploy.md

@@ -15,29 +15,11 @@ deno run -A --unstable my_kv_code.ts
 
 :::
 
-Deno Deploy now offers a built-in serverless key-value database called Deno KV,
-which is currently in closed beta testing. To join the waitlist for this
-exclusive beta, please [sign up here.](https://dash.deno.com/kv). While in
-closed beta, Deno KV will not charge for storage and includes up to 1GB of
-storage per user.
+Deno Deploy now offers a built-in serverless key-value database called Deno KV.
 
 Additionally, Deno KV is available within Deno itself, utilizing SQLite as its
 backend. This feature has been accessible since Deno v1.32 with the `--unstable`
-flag.
-
-[Discover how to effectively use the Deno KV database by referring to the Deno Runtime user guide.](/kv/manual)
-
-## Getting started
-
-Upon receiving an invitation from the waitlist, a new “KV” tab will appear in
-all your projects. This tab displays basic usage statistics and a data browser.
-
-For GitHub projects, two separate databases are generated: one for the
-production branch (usually `main`) and another for all other branches. For
-playground projects, a single database is created.
-
-No additional configuration is required. If a Deno project utilizing KV works on
-a local setup, it will seamlessly function on Deploy without any modifications.
+flag. Learn more about [Deno KV](/kv/manual).
 
 ## Consistency
 
@@ -72,6 +54,23 @@ Below are the latency figures observed in our top regions:
 | California (us-west2)      | 72ms                           | 72ms                         |
 | Hong Kong (asia-east2)     | 42ms                           | 194ms                        |
 
+## Connect to managed databases from outside of Deno Deploy
+
+You can connect to your Deno Deploy KV database from your Deno application
+outside of Deno Deploy. To open a managed database, set the
+`DENO_KV_ACCESS_TOKEN` environment variable to a Deno Deploy personal access
+token and provide the URL of the database to `Deno.openKv`:
+
+```ts
+const kv = await Deno.openKv(
+  "https://api.deno.com/databases/<database-id>/connect",
+);
+```
+
+Please check the
+[docs](https://github.com/denoland/deno/tree/main/ext/kv#kv-connect) for the
+specification of the protocol for connecting to a remote KV database
+
 ## Data distribution
 
 Deno KV databases are replicated across at least 6 data centers, spanning 3

runtime/manual/basics/testing/snapshot_testing.md

@@ -1,10 +1,10 @@
 # Snapshot Testing
 
 The Deno standard library comes with a
-[snapshot module](https://deno.land/std/testing/snapshot.ts), which enables
-developers to write tests which assert a value against a reference snapshot.
-This reference snapshot, is a serialized representation of the original value
-and is stored alongside the test file.
+[snapshot module](https://deno.land/std@$STD_VERSION/testing/snapshot.ts), which
+enables developers to write tests which assert a value against a reference
+snapshot. This reference snapshot, is a serialized representation of the
+original value and is stored alongside the test file.
 
 Snapshot testing can be useful in many cases, as it enables catching a wide
 array of bugs with very little code. It is particularly helpful in situations
@@ -19,9 +19,10 @@ The `assertSnapshot` function will create a snapshot of a value and compare it
 to a reference snapshot, which is stored alongside the test file in the
 `__snapshots__` directory.
 
-```ts
-// example_test.ts
-import { assertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
+```ts title="example_test.ts"
+import {
+  assertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
 
 Deno.test("isSnapshotMatch", async function (t): Promise<void> {
   const a = {
@@ -32,8 +33,7 @@ Deno.test("isSnapshotMatch", async function (t): Promise<void> {
 });
 ```
 
-```js
-// __snapshots__/example_test.ts.snap
+```js title="__snapshots__/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`isSnapshotMatch 1`] = `
@@ -88,8 +88,10 @@ snapshots locally.
 The `assertSnapshot` function can also be called with an options object which
 offers greater flexibility and enables some non standard use cases.
 
-```ts, ignore
-import { assertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
+```ts
+import {
+  assertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
 
 Deno.test("isSnapshotMatch", async function (t): Promise<void> {
   const a = {
@@ -114,10 +116,12 @@ The result of the serializer function will be written to the snapshot file in
 update mode, and in assert mode will be compared to the snapshot stored in the
 snapshot file.
 
-```ts, ignore
-// example_test.ts
-import { assertSnapshot, serialize } from "https://deno.land/std/testing/snapshot.ts";
-import { stripColor } from "https://deno.land/std/fmt/colors.ts";
+```ts title="example_test.ts"
+import {
+  assertSnapshot,
+  serialize,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+import { stripColor } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
 
 /**
  * Serializes `actual` and removes ANSI escape codes.
@@ -134,8 +138,7 @@ Deno.test("Custom Serializer", async function (t): Promise<void> {
 });
 ```
 
-```js
-// __snapshots__/example_test.ts.snap
+```js title="__snapshots__/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`Custom Serializer 1`] = `"Hello World!"`;
@@ -201,23 +204,23 @@ The `name` option specifies the name of the snapshot. By default, the name of
 the test step will be used. However, if specified, the `name` option will be
 used instead.
 
-```ts, ignore
-// example_test.ts
-import { assertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
+```ts title="example_test.ts"
+import {
+  assertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
 
 Deno.test("isSnapshotMatch", async function (t): Promise<void> {
   const a = {
     hello: "world!",
     example: 123,
   };
   await assertSnapshot(t, a, {
-    name: "Test Name"
+    name: "Test Name",
   });
 });
 ```
 
-```js
-// __snapshots__/example_test.ts.snap
+```js title="__snapshots__/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`Test Name 1`] = `
@@ -241,9 +244,10 @@ error message, which includes the diff for failed snapshots.
 
 You can configure default options for `assertSnapshot`.
 
-```ts, ignore
-// example_test.ts
-import { createAssertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
+```ts title="example_test.ts"
+import {
+  createAssertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
 
 const assertSnapshot = createAssertSnapshot({
   // options
@@ -258,10 +262,11 @@ over the default options, where the value provided for an option differs.
 It is possible to "extend" an `assertSnapshot` function which has been
 configured with default options.
 
-```ts, ignore
-// example_test.ts
-import { createAssertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
-import { stripColor } from "https://deno.land/std/fmt/colors.ts";
+```ts title="example_test.ts"
+import {
+  createAssertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
+import { stripColor } from "https://deno.land/std@$STD_VERSION/fmt/colors.ts";
 
 const assertSnapshot = createAssertSnapshot({
   dir: ".snaps",
@@ -278,8 +283,7 @@ Deno.test("isSnapshotMatch", async function (t): Promise<void> {
 });
 ```
 
-```js
-// .snaps/example_test.ts.snap
+```js title=".snaps/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`isSnapshotMatch 1`] = `This green text has had it's colours stripped`;
@@ -301,9 +305,10 @@ Doing so will ensure that the custom serialization will, by default, be used
 whenever the object is passed to `assertSnapshot`. This can be useful in many
 cases. One example is shown in the code snippet below.
 
-```ts, ignore
-// example_test.ts
-import { assertSnapshot } from "https://deno.land/std/testing/snapshot.ts";
+```ts title="example_test.ts"
+import {
+  assertSnapshot,
+} from "https://deno.land/std@$STD_VERSION/testing/snapshot.ts";
 
 class HTMLTag {
   constructor(
@@ -342,7 +347,7 @@ Deno.test("Page HTML Tree", async (t) => {
         "Simple SSR Example",
       ]),
       new HTMLTag("p", [
-        "This is an example of how Deno.customInspect could be used to snapshot an intermediate SSR representation",
+        "Ex of customInspect for a snapshot of an SSR representation",
       ]),
     ]),
   ]);
@@ -353,8 +358,7 @@ Deno.test("Page HTML Tree", async (t) => {
 
 This test will produce the following snapshot.
 
-```js
-// __snapshots__/example_test.ts.snap
+```js title="__snapshots__/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`Page HTML Tree 1`] = `
@@ -369,7 +373,7 @@ snapshot[`Page HTML Tree 1`] = `
       Simple SSR Example
     </h1>
     <p>
-      This is an example of how Deno.customInspect could be used to snapshot an intermediate SSR representation
+      Ex of customInspect for a snapshot of an SSR representation
     </p>
   </body>
 </html>
@@ -379,8 +383,7 @@ snapshot[`Page HTML Tree 1`] = `
 In contrast, when we remove the `Deno.customInspect` method, the test will
 produce the following snapshot.
 
-```js
-// __snapshots__/example_test.ts.snap
+```js title="__snapshots__/example_test.ts.snap"
 export const snapshot = {};
 
 snapshot[`Page HTML Tree 1`] = `
@@ -407,7 +410,7 @@ HTMLTag {
         },
         HTMLTag {
           children: [
-            "This is an example of how Deno.customInspect could be used to snapshot an intermediate SSR representation",
+            "Ex of customInspect for a snapshot of an SSR representation",
           ],
           name: "p",
         },

runtime/manual/getting_started/first_steps.md

@@ -36,8 +36,8 @@ deno run first_steps.ts
 ```
 
 Deno also has the ability to execute scripts from URLs. Deno
-[hosts a library](https://deno.land/std/examples) of example code,
-one of which is a `Hello World` program. To run that hosted code, do:
+[hosts a library](https://deno.land/std/examples) of example code, one of which
+is a `Hello World` program. To run that hosted code, do:
 
 ```shell
 deno run https://deno.land/std/examples/welcome.ts
@@ -72,8 +72,7 @@ Try it out:
 deno run first_steps.ts
 ```
 
-Or, try this script hosted at
-`https://deno.land/std/examples/curl.ts`:
+Or, try this script hosted at `https://deno.land/std/examples/curl.ts`:
 
 ```shell
 deno run https://deno.land/std/examples/curl.ts https://deno.com
@@ -153,7 +152,7 @@ import { serve } from "https://deno.land/std/http/server.ts";
 
 const handler = async (_request: Request): Promise<Response> => {
   const resp = await fetch("https://api.github.com/users/denoland", {
-    // The init object here has an headers object containing a
+    // The init object here has a headers object containing a
     // header that indicates what type of response we accept.
     // We're not specifying the method field since by default
     // fetch makes a GET request.