feat: scheduleExit() function

Author: Sv443

CHANGELOG.md

@@ -11,12 +11,13 @@ Parts of the code have been overhauled, and some features have been added:
   - Added [`takeRandomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-takerandomitemindex), as a mutating counterpart to [`randomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-randomitemindex)
   - Added [`truncStr()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-truncstr) to truncate a string to a given length, optionally adding an ellipsis.
   - Added [`valsWithin()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-valswithin) to check if two values, rounded at the given decimal, are within a certain range of each other.
+  - Added [`scheduleExit()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-scheduleexit) to schedule a Node/Deno process to exit with the given code, after the microtask queue is empty or after the given timeout.
 - **BREAKING CHANGES:**
-  - Reworked DataStore
+  - Reworked `DataStore`
     - The constructor now needs an `engine` property that is an instance of a [`DataStoreEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine.)
     - Encoding with `deflate-raw` will now be enabled by default. Set `compressionFormat: null` to disable it and restore the previous behavior.
     - Added [`DataStoreEngine` class](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine) with two implementations available out-of-the-box; [`FileStorageEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-filestorageengine) and [`BrowserStorageEngine`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-browserstorageengine), for Node/Deno and browser environments respectively. Userscripts need to use [`BrowserStorageEngine`.](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-browserstorageengine)
     - Added shorthand property `compressionFormat` as an alternative to the properties `encodeData` and `decodeData`
     - The global key `__ds_fmt_ver` will now contain a global version number for DataStore-internal format integrity.
-  - Renamed `ab2str()` to `abtoa()` and `str2ab()` to `atoab()` to match `btoa()` and `atob()`
+  - Renamed `ab2str()` to `abtoa()` and `str2ab()` to `atoab()` to match the naming of `atob()` and `btoa()`
   - Renamed `purifyObj()` to `pureObj()`

README.md

@@ -79,6 +79,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟣 [`function pureObj()`](./docs.md#function-pureobj) - Applies an object's props to a null object (object without prototype chain) or just returns a new null object
   - 🟣 [`function setImmediateInterval()`](./docs.md#function-setimmediateinterval) - Like `setInterval()`, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
   - 🟣 [`function setImmediateTimeoutLoop()`](./docs.md#function-setimmediatetimeoutloop) - Like a recursive `setTimeout()` loop, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+  - 🟣 [`function scheduleExit()`](./docs.md#function-scheduleexit) - Schedules a process exit after the next event loop tick, to allow operations like IO writes to finish.
 - [**NanoEmitter:**](./docs.md#nanoemitter)
   - 🟧 [`class NanoEmitter`](./docs.md#class-nanoemitter) - Simple, lightweight event emitter class that can be used in both FP and OOP, inspired by [`EventEmitter` from `node:events`](https://nodejs.org/api/events.html#class-eventemitter), based on [`nanoevents`](https://npmjs.com/package/nanoevents)
     - 🔷 [`type NanoEmitterOptions`](./docs.md#type-nanoemitteroptions) - Options for the [`NanoEmitter` class](./docs.md#class-nanoemitter)

docs.md

@@ -97,6 +97,7 @@ For submitting bug reports or feature requests, please use the [GitHub issue tra
     - 🟣 [`function pureObj()`](#function-pureobj) - Applies an object's props to a null object (object without prototype chain) or just returns a new null object
     - 🟣 [`function setImmediateInterval()`](#function-setimmediateinterval) - Like `setInterval()`, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
     - 🟣 [`function setImmediateTimeoutLoop()`](#function-setimmediatetimeoutloop) - Like a recursive `setTimeout()` loop, but instantly calls the callback and supports passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    - 🟣 [`function scheduleExit()`](#function-scheduleexit) - Schedules a process exit after the next event loop tick, to allow operations like IO writes to finish.
   - [**NanoEmitter:**](#nanoemitter)
     - 🟧 [`class NanoEmitter`](#class-nanoemitter) - Simple, lightweight event emitter class that can be used in both FP and OOP, inspired by [`EventEmitter` from `node:events`](https://nodejs.org/api/events.html#class-eventemitter), based on [`nanoevents`](https://npmjs.com/package/nanoevents)
       - 🔷 [`type NanoEmitterOptions`](#type-nanoemitteroptions) - Options for the [`NanoEmitter` class](#class-nanoemitter)
@@ -2495,6 +2496,20 @@ abortButton.addEventListener("click", () => {
 ```
 </details>
 
+<br>
+
+### `function scheduleExit()`
+Signature:
+```ts
+function scheduleExit(code?: number, timeout?: number): void;
+```
+  
+Schedules the process to exit with the given exit code after a timeout, in both Node.js and Deno, but not in the browser.  
+This is useful for allowing the currently queued microtasks to finish before exiting the process. This can prevent data loss or corruption when writing to files or databases, for example.  
+If no exit code is given, it will default to 0 (success). Set it to 1 to indicate an error.  
+If no timeout is given, the process will exit immediately after the current microtask queue is cleared (0ms).  
+If a timeout is given, the process will exit after the timeout has elapsed, regardless of whether there are still microtasks in the queue.  
+
 <br><br>
 
 

lib/misc.ts

@@ -178,3 +178,25 @@ export function setImmediateTimeoutLoop(
   signal?.addEventListener("abort", cleanup);
   loop();
 }
+
+/**
+ * Schedules an exit of the current process after the next event loop tick, in order to allow any pending operations like IO writes to complete.  
+ * Works on both Node.js and Deno, but will not work in browser environments.
+ * @param code The exit code to use, defaults to 0 (success)
+ * @param timeout The time in milliseconds to wait before exiting, defaults to 0 (exit on the next event loop tick)
+ * @throws An error if no exit method is available (e.g. in browser environments)
+ */
+export function scheduleExit(code: number = 0, timeout = 0): void {
+  if(timeout < 0)
+    throw new TypeError("Timeout must be a non-negative number");
+
+  let exit: (() => void) | undefined;
+  if(typeof process !== "undefined" && "exit" in process)
+    exit = () => process.exit(code);
+  else if(typeof Deno !== "undefined" && "exit" in Deno)
+    exit = () => Deno.exit(code);
+  else
+    throw new Error("Cannot exit the process, no exit method available");
+
+  setTimeout(exit, timeout);
+}

package.json

@@ -59,6 +59,7 @@
     "@eslint/js": "^9.28.0",
     "@swc/core": "^1.11.29",
     "@testing-library/dom": "^10.4.0",
+    "@types/deno": "^2.3.0",
     "@types/node": "^22.15.29",
     "@types/tx2": "^1.0.3",
     "@typescript-eslint/eslint-plugin": "^8.33.0",

pnpm-lock.yaml

@@ -1,4 +1,4 @@
-import { readdir, readFile, writeFile, lstat } from "node:fs/promises";
+import { readdir, readFile, writeFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { styleText } from "node:util";
 
@@ -24,7 +24,7 @@ async function processRecursive(directory: string): Promise<void> {
 
   for(const file of files) {
     const fullPath = join(directory, file);
-    const stats = await lstat(fullPath);
+    const stats = await stat(fullPath);
 
     if(stats.isDirectory())
       await processRecursive(fullPath);