Merge branch 'main' into main

Author: twocaretcat

.github/workflows/lint.yml

@@ -16,6 +16,8 @@ jobs:
     steps:
       - name: Clone repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Deno
         uses: denoland/setup-deno@v2

.gitignore

@@ -2,6 +2,7 @@ _site
 _cache
 _broken_links.json
 
+.claude
 .idea
 
 node_modules

_components/Feedback.tsx

@@ -7,7 +7,7 @@ export default function Feedback({ file }: { file: string | undefined }) {
     return (
       <section
         id="feedback-section"
-        class="flex flex-col mt-12 gap-2 p-4 sm:p-8 bg-blue-splash dark:bg-deploy-900 rounded-md mx-auto"
+        class="flex flex-col mt-12 gap-2 p-4 sm:p-8 bg-blue-splash dark:bg-background-secondary rounded-md mx-auto"
       >
         <h2 class="text-xl mb-2 pb-2 font-normal">
           Did you find what you needed?

_config.ts

@@ -91,7 +91,11 @@ const site = lume(
         createMarkdownSourceMiddleware({ root: "_site" }),
         createRoutingMiddleware(),
         createGAMiddleware({
-          addr: { transport: "tcp", hostname: "localhost", port: 3000 },
+          addr: {
+            transport: "tcp",
+            hostname: "localhost",
+            port: parseInt(Deno.env.get("PORT") || "3000"),
+          },
         }),
         createLlmsFilesMiddleware({ root: "_site" }),
         apiDocumentContentTypeMiddleware,
@@ -451,6 +455,37 @@ site.ignore(
 // the default layout if no other layout is specified
 site.data("layout", "doc.tsx");
 
+// Populate lastModified from git history using a single git command
+site.preprocess([".md", ".mdx"], (filteredPages) => {
+  const result = Deno.spawnAndWaitSync("git", [
+    "log",
+    "--pretty=format:%aI",
+    "--name-only",
+    "--diff-filter=ACMR",
+    "HEAD",
+  ]);
+
+  const output = new TextDecoder().decode(result.stdout);
+  const lastModified = new Map<string, string>();
+  let currentDate = "";
+
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    if (line.match(/^\d{4}-/)) {
+      currentDate = line;
+    } else if (!lastModified.has(line)) {
+      lastModified.set(line, currentDate);
+    }
+  }
+
+  for (const page of filteredPages) {
+    const src = page.sourcePath?.replace(/^\//, "");
+    if (src && lastModified.has(src)) {
+      page.data.lastModified = new Date(lastModified.get(src)!);
+    }
+  }
+});
+
 // Load API categories data globally
 import denoCategories from "./reference_gen/deno-categories.json" with {
   type: "json",
@@ -499,9 +534,6 @@ site.data("apiCategories", {
 
 // Do more expensive operations if we're building the full site
 if (Deno.env.get("BUILD_TYPE") == "FULL" && !Deno.env.has("SKIP_OG")) {
-  // Use Lume's built in date function to get the last modified date of the file
-  // site.data("date", "Git Last Modified");;
-
   // Generate Open Graph images
   site.data("openGraphLayout", "/open_graph/default.jsx");
   site.use(
@@ -546,7 +578,7 @@ site.scopedUpdates(
 
 site.addEventListener("afterStartServer", () => {
   log.warn(
-    `${cliNow()} Server available at <green>http://localhost:3000</green>`,
+    `${cliNow()} Server available at <green>http://localhost:${site.server.options.port}</green>`,
   );
 });
 

_includes/doc.tsx

@@ -101,6 +101,18 @@ export default function Doc(data: Lume.Data, helpers: Lume.Helpers) {
               {data.children}
             </div>
           </article>
+          {data.lastModified && !isReference && !isLintRule && (
+            <p class="text-sm text-foreground-secondary mt-8">
+              Last updated on{" "}
+              <time dateTime={data.lastModified.toISOString()}>
+                {data.lastModified.toLocaleDateString("en-US", {
+                  year: "numeric",
+                  month: "long",
+                  day: "numeric",
+                })}
+              </time>
+            </p>
+          )}
           <data.comp.Feedback file={file} />
         </div>
       </main>

api/deno/index.md

@@ -777,22 +777,52 @@ Deno supports browser compatible lifecycle events:
   Scheduling more asynchronous work (like timers or network requests) will cause
   the program to continue.
 - [`unload`](https://developer.mozilla.org/en-US/docs/Web/API/Window/unload_event):
-  fired when the document or a child resource is being unloaded.
+  fired when the program has no more work to do. Scheduling more asynchronous
+  work (like timers or network requests) **does not** keep the program alive.
 - [`unhandledrejection`](https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event):
   fired when a promise that has no rejection handler is rejected, ie. a promise
   that has no `.catch()` handler or a second argument to `.then()`.
 - [`rejectionhandled`](https://developer.mozilla.org/en-US/docs/Web/API/Window/rejectionhandled_event):
-  fired when a `.catch()` handler is added to a a promise that has already
+  fired when a `.catch()` handler is added to a promise that has already been
   rejected. This event is fired only if there's `unhandledrejection` listener
   installed that prevents propagation of the event (which would result in the
   program terminating with an error).
+- [`error`](https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event):
+  fired when an uncaught exception occurs. If a listener is registered, it
+  prevents the default behavior of printing the error to the console and
+  terminating the program.
+
+Deno also supports Node.js compatible lifecycle events:
+
+- [`process.on("beforeExit")`](https://nodejs.org/api/process.html#event-beforeexit):
+  fired when the event loop has no more work to do and is about to exit.
+  Scheduling more asynchronous work (like timers or network requests) will cause
+  the program to continue. Counterpart to `beforeunload` Web event. Fires
+  immediately after `beforeunload` event.
+- [`process.on("exit")`](https://nodejs.org/api/process.html#event-exit): fired
+  when the program has no more work to do. Scheduling more asynchronous work
+  (like timers or network requests) **does not** keep the program alive.
+  Counterpart to `unload` Web event. Fired immediately after `unload` event.
+- [`process.on("rejectionHandled")`](https://nodejs.org/api/process.html#event-rejectionhandled):
+  fired when a `.catch()` handler is added to a promise that has already been
+  rejected. Counterpart to `rejectionhandled` Web event. Fired immediately after
+  `rejectionhandled` event.
+- [`process.on("uncaughtException")`](https://nodejs.org/api/process.html#event-uncaughtexception):
+  fired when an uncaught exception bubbles up. If a listener is registered, it
+  prevents the default behavior of printing the stack trace and exiting.
+  Counterpart to `error` Web event. Fired immediately after `error` event.
+- [`process.on("unhandledRejection")`](https://nodejs.org/api/process.html#event-unhandledrejection):
+  fired when a promise is rejected and no rejection handler is attached.
+  Counterpart to `unhandledrejection` Web event. Fired immediately after
+  `unhandledrejection` event.
 
 You can use these events to provide setup and cleanup code in your program.
 
-Listeners for `load` events can be asynchronous and will be awaited, this event
+Listeners for `load` events can be asynchronous and will be awaited. This event
 cannot be canceled. Listeners for `beforeunload` need to be synchronous and can
 be cancelled to keep the program running. Listeners for `unload` events need to
-be synchronous and cannot be cancelled.
+be synchronous and cannot be cancelled. The same rules apply to their Node.js
+counterparts (`beforeExit` and `exit`).
 
 ## main.ts
 

deploy/getting_started.md

@@ -135,73 +135,17 @@ To add environment variables:
 
 ![Screenshot of the Deploy env variables config screen](./images/env_var.png)
 
+You can re-open the drawer to edit / remove environment variables you have
+added. You can also edit the app name on this page, and select which region(s)
+the application should be served from.
+
 ## Build and deploy your app
 
 1. Click `Create App` to create the application and start the first build
 2. Watch the build progress through the live logs:
 
 ![Screenshot of app build logs](./images/build_logs.png)
 
-The build logs show these stages:
-
-- **Prepare**: Cloning the repository and restoring caches
-- **Install**: Running the install command and framework-specific setup
-- **Build**: Executing the build command and preparing the deployment artifact
-- **Warm up**: Testing the deployment with a request
-- **Route**: Deploying the build to global regions
-
-You can cancel a build with the button in the top-left corner, or restart failed
-builds from the same location.
-
-After completion, the top-right shows the preview URL, and below that, all
-timelines where the build is deployed.
-
-## Monitor your application
-
-After deploying, use the observability tools to monitor your application:
-
-### Logs
-
-View application logs with filtering options for context, revision, and text
-content:
-
-![Screenshot of the Logs page](./images/logs.png)
-
-Use the search bar to filter logs (e.g., `context:production`, `revision:<id>`).
-The time picker adjusts the displayed time range.
-
-If a log is associated with a trace, you can click "View trace" to see the
-corresponding trace information.
-
-### Traces
-
-View request traces with detailed timing information:
-
-![Screenshot of the Traces page](./images/traces.png)
-
-Click any trace to open the trace view showing all spans in a waterfall
-visualization:
-
-![Screenshot of the Trace view](./images/trace.png)
-
-The trace view shows:
-
-- Timeline of spans with duration
-- Span details including attributes
-- Logs emitted during the span To save the environment variables, press the save
-  button. You can re-open the drawer to edit / remove environment variables you
-  have added.
-
-You can also edit the app name on this page, and select which region(s) the
-application should be served from.
-
-## Build and deploy your app
-
-Finally, you can press the `Create App` button to create the app. This will
-create the app and immediately trigger the first build:
-
-![Screenshot of app build logs](./images/build_logs.png)
-
 On the build page you can see live streaming build logs split into multiple
 sections:
 
@@ -219,9 +163,9 @@ sections:
 In the top left of this build is a button to cancel the build. For failed
 builds, there is also a button to restart the build.
 
-For completed builds, the top right shows the preview URL of the build. Further
-down all timelines that this build is deployed to are shown, such as
-`Production`, or `Git Branch` timelines.
+For completed builds, the top right shows the preview URL. Further down all
+timelines that this build is deployed to are shown, such as `Production`, or
+`Git Branch` timelines.
 
 You can also see how the build was triggered on this page. This can either be
 `manual action`, for builds triggered through the UI, or `GitHub repo` for
@@ -232,12 +176,15 @@ URLs shown in the timelines list.
 
 ## Monitor your application
 
-After visiting your application, you can view telemetry about your application
-in the form of the logs and traces available in our observability panels. You
-can visit these pages by clicking the respective buttons in the left sidebar.
+After deploying, you can view telemetry about your application in the form of
+the logs and traces available in our observability panels. You can visit these
+pages by clicking the respective buttons in the left sidebar.
 
 ### Logs
 
+View application logs with filtering options for context, revision, and text
+content:
+
 ![Screenshot of the Logs page](./images/logs.png)
 
 The logs page shows all recent logs in the project. By default logs from all
@@ -246,7 +193,7 @@ search bar at the top, the shown logs can be restricted. For example, to filter
 to only production logs, add `context:production` to the search bar. To only
 show logs from a certain revision, use `revision:<id>` etc.
 
-You can also use full text search in the search bar. The full text search fill
+You can also use full text search in the search bar. The full text search will
 filter down the log entries to only those containing the text written,
 case-insensitively.
 
@@ -260,6 +207,8 @@ trace. Clicking this button will open the respective trace as an overlay.
 
 ### Traces
 
+View request traces with detailed timing information:
+
 ![Screenshot of the Traces page](./images/traces.png)
 
 The traces page shows all recent traces in the project. By default traces from

deploy/kv/index.md

@@ -37,7 +37,7 @@ To close the database connection, use the
 ```ts
 const kv = await Deno.openKv();
 // Execute some queries ...
-await kv.close();
+kv.close();
 ```
 
 ## Creating, updating, and reading a key-value pair

examples/tutorials/basic_opentelemetry.md

@@ -123,6 +123,18 @@ To run the server with OpenTelemetry, use these flags:
 OTEL_DENO=true OTEL_SERVICE_NAME=my-server deno run --allow-net server.ts
 ```
 
+:::tip
+
+To quickly see telemetry output without setting up a collector, you can use the
+built-in console exporter which prints spans, logs, and metrics directly to
+stderr:
+
+```sh
+OTEL_DENO=true OTEL_EXPORTER_OTLP_PROTOCOL=console OTEL_SERVICE_NAME=my-server deno run --allow-net server.ts
+```
+
+:::
+
 ## Step 3: Create a Test Client
 
 Let's create a simple client to send requests to our server:

examples/tutorials/snapshot_test.md

@@ -50,7 +50,7 @@ Deno.test("isSnapshotMatch", async (t) => {
 
 You will need to grant read and write file permissions in order for Deno to
 write a snapshot file and then read it to test the assertion. If it is the first
-time you are running the test a do not already have a snapshot, add the
+time you are running the test and you do not already have a snapshot, add the
 `--update` flag:
 
 ```bash
@@ -143,7 +143,7 @@ Deno.test("isSnapshotMatch", async (t) => {
 When you run a test with `assertSnapshot`, the data you're testing needs to be
 converted to a string format that can be written to the snapshot file (when
 creating or updating snapshots) and compared with the existing snapshot (when
-validating), this is called serialization.
+validating). This is called serialization.
 
 The `serializer` option allows you to provide a custom serializer function. This
 custom function will be called by `assertSnapshot` and be passed the value being