feat: Add `Deno.exitCode` API (#23609)

This commits adds the ability to set a would-be exit code 
for the Deno process without forcing an immediate exit, 
through the new `Deno.exitCode` API.

- **Implements `Deno.exitCode` getter and setter**: Adds support for
setting
and retrieving a would-be exit code via `Deno.exitCode`.
This allows for asynchronous cleanup before process termination 
without immediately exiting.
- **Ensures type safety**: The setter for `Deno.exitCode` validates that
the provided value is a number, throwing a TypeError if not, to ensure
that
only valid exit codes are set.

Closes to #23605

---------

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

1 files changed, 94 insertions, 0 deletions

diff --git a/cli/tests/unit/os_test.ts b/cli/tests/unit/os_test.ts
new file mode 100644
index 000000000..af6ef219a
--- /dev/null
+++ b/cli/tests/unit/os_test.ts
@@ -0,0 +1,94 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+import { assertEquals, assertThrows } from "../../testing/asserts.ts";
+
+Deno.test("Deno.exitCode getter and setter", () => {
+  // Initial value is 0
+  assertEquals(Deno.exitCode, 0);
+
+  // Set a new value
+  Deno.exitCode = 5;
+  assertEquals(Deno.exitCode, 5);
+
+  // Reset to initial value
+  Deno.exitCode = 0;
+  assertEquals(Deno.exitCode, 0);
+});
+
+Deno.test("Setting Deno.exitCode to NaN throws TypeError", () => {
+  // @ts-expect-error;
+  Deno.exitCode = "123";
+  assertEquals(Deno.exitCode, 123);
+
+  // Reset
+  Deno.exitCode = 0;
+  assertEquals(Deno.exitCode, 0);
+
+  // Throws on non-number values
+  assertThrows(
+    () => {
+      // @ts-expect-error Testing for runtime error
+      Deno.exitCode = "not a number";
+    },
+    TypeError,
+    "Exit code must be a number.",
+  );
+});
+
+Deno.test("Setting Deno.exitCode does not cause an immediate exit", () => {
+  let exited = false;
+  const originalExit = Deno.exit;
+
+  // @ts-expect-error; read-only
+  Deno.exit = () => {
+    exited = true;
+  };
+
+  Deno.exitCode = 1;
+  assertEquals(exited, false);
+
+  // @ts-expect-error; read-only
+  Deno.exit = originalExit;
+});
+
+Deno.test("Running Deno.exit(value) overrides Deno.exitCode", () => {
+  let args: unknown[] | undefined;
+
+  const originalExit = Deno.exit;
+  // @ts-expect-error; read-only
+  Deno.exit = (...x) => {
+    args = x;
+  };
+
+  Deno.exitCode = 42;
+  Deno.exit(0);
+
+  assertEquals(args, [0]);
+  // @ts-expect-error; read-only
+  Deno.exit = originalExit;
+});
+
+Deno.test("Running Deno.exit() uses Deno.exitCode as fallback", () => {
+  let args: unknown[] | undefined;
+
+  const originalExit = Deno.exit;
+  // @ts-expect-error; read-only
+  Deno.exit = (...x) => {
+    args = x;
+  };
+
+  Deno.exitCode = 42;
+  Deno.exit();
+
+  assertEquals(args, [42]);
+  // @ts-expect-error; read-only
+  Deno.exit = originalExit;
+});
+
+Deno.test("Retrieving the set exit code before process termination", () => {
+  Deno.exitCode = 42;
+  assertEquals(Deno.exitCode, 42);
+
+  // Reset to initial value
+  Deno.exitCode = 0;
+});