14 files changed, 260 insertions, 0 deletions

diff --git a/docs/guides/util/deep-equals.md b/docs/guides/util/deep-equals.md
new file mode 100644
index 000000000..9d8dc74d4
--- /dev/null
+++ b/docs/guides/util/deep-equals.md
@@ -0,0 +1,39 @@
+---
+name: Check if two objects are deeply equal
+---
+
+Check if two objects are deeply equal. This is used internally by `expect().toEqual()` in Bun's [test runner](/docs/test/writing).
+
+```ts#index.ts
+const a = { a: 1, b: 2, c: { d: 3 } };
+const b = { a: 1, b: 2, c: { d: 3 } };
+
+Bun.deepEquals(a, b); // true
+```
+
+---
+
+Pass `true` as a third argument to enable strict mode. This is used internally by `expect().toStrictEqual()` in Bun's [test runner](/docs/test/writing).
+
+The following examples would return `true` in non-strict mode but `false` in strict mode.
+
+```ts
+// undefined values
+Bun.deepEquals({}, { a: undefined }, true); // false
+
+// undefined in arrays
+Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false
+
+// sparse arrays
+Bun.deepEquals([, 1], [undefined, 1], true); // false
+
+// object literals vs instances w/ same properties
+class Foo {
+  a = 1;
+}
+Bun.deepEquals(new Foo(), { a: 1 }, true); // false
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/deflate.md b/docs/guides/util/deflate.md
new file mode 100644
index 000000000..91dd8925a
--- /dev/null
+++ b/docs/guides/util/deflate.md
@@ -0,0 +1,18 @@
+---
+name: Compress and decompress data with DEFLATE
+---
+
+Use `Bun.deflateSync()` to compress a `Uint8Array` with DEFLATE.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.deflateSync("Hello, world!");
+// => Uint8Array
+
+const decompressed = Bun.inflateSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/entrypoint.md b/docs/guides/util/entrypoint.md
new file mode 100644
index 000000000..e53d4c9a1
--- /dev/null
+++ b/docs/guides/util/entrypoint.md
@@ -0,0 +1,17 @@
+---
+name: Check if the current file is the entrypoint
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/api/import-meta) object. Use `import.meta.main` to check if the current file is the entrypoint of the current process.
+
+```ts#index.ts
+if(import.meta.main){
+  // this file is directly executed with `bun run`
+}else{
+  // this file is being imported by another file
+}
+```
+
+---
+
+See [Docs > API > import.meta](/docs/api/import-meta) for complete documentation.
diff --git a/docs/guides/util/escape-html.md b/docs/guides/util/escape-html.md
new file mode 100644
index 000000000..4d88fb857
--- /dev/null
+++ b/docs/guides/util/escape-html.md
@@ -0,0 +1,22 @@
+---
+name: Escape an HTML string
+---
+
+The `Bun.escapeHTML()` utility can be used to escape HTML characters in a string. The following replacements are made.
+
+- `"` becomes `"""`
+- `&` becomes `"&"`
+- `'` becomes `"'"`
+- `<` becomes `"&lt;"`
+- `>` becomes `"&gt;"`
+
+This function is optimized for large input. Non-string types will be converted to a string before escaping.
+
+```ts
+Bun.escapeHTML("<script>alert('Hello World!')</script>");
+// &lt;script&gt;alert(&#x27;Hello World!&#x27;)&lt;&#x2F;script&gt;
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/file-url-to-path.md b/docs/guides/util/file-url-to-path.md
new file mode 100644
index 000000000..0464504a6
--- /dev/null
+++ b/docs/guides/util/file-url-to-path.md
@@ -0,0 +1,14 @@
+---
+name: Convert a file URL to an absolute path
+---
+
+Use `Bun.fileURLToPath()` to convert a `file://` URL to an absolute path.
+
+```ts
+Bun.fileURLToPath("file:///path/to/file.txt");
+// => "/path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/gzip.md b/docs/guides/util/gzip.md
new file mode 100644
index 000000000..c755b7c8b
--- /dev/null
+++ b/docs/guides/util/gzip.md
@@ -0,0 +1,18 @@
+---
+name: Compress and decompress data with gzip
+---
+
+Use `Bun.gzipSync()` to compress a `Uint8Array` with gzip.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.gzipSync("Hello, world!");
+// => Uint8Array
+
+const decompressed = Bun.gunzipSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/import-meta-dir.md b/docs/guides/util/import-meta-dir.md
new file mode 100644
index 000000000..edfa02372
--- /dev/null
+++ b/docs/guides/util/import-meta-dir.md
@@ -0,0 +1,13 @@
+---
+name: Get the directory of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/api/import-meta) object.
+
+```ts#/a/b/c.ts
+import.meta.dir; // => "/a/b"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/api/import-meta) for complete documentation.
diff --git a/docs/guides/util/import-meta-file.md b/docs/guides/util/import-meta-file.md
new file mode 100644
index 000000000..8edf262b2
--- /dev/null
+++ b/docs/guides/util/import-meta-file.md
@@ -0,0 +1,13 @@
+---
+name: Get the file name of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/api/import-meta) object. Use `import.meta.file` to retreive the name of the current file.
+
+```ts#/a/b/c.ts
+import.meta.file; // => "c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/api/import-meta) for complete documentation.
diff --git a/docs/guides/util/import-meta-path.md b/docs/guides/util/import-meta-path.md
new file mode 100644
index 000000000..b93670a38
--- /dev/null
+++ b/docs/guides/util/import-meta-path.md
@@ -0,0 +1,13 @@
+---
+name: Get the absolute path of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/api/import-meta) object. Use `import.meta.path` to retreive the absolute path of the current file.
+
+```ts#/a/b/c.ts
+import.meta.path; // => "/a/b/c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/api/import-meta) for complete documentation.
diff --git a/docs/guides/util/index.json b/docs/guides/util/index.json
new file mode 100644
index 000000000..7e988ae25
--- /dev/null
+++ b/docs/guides/util/index.json
@@ -0,0 +1,4 @@
+{
+  "name": "Utilities",
+  "description": "A collection of guides relating to Bun's array of built-in utility functions"
+}
diff --git a/docs/guides/util/main.md b/docs/guides/util/main.md
new file mode 100644
index 000000000..e34fcd8f7
--- /dev/null
+++ b/docs/guides/util/main.md
@@ -0,0 +1,32 @@
+---
+name: Get the absolute path to the current entrypoint
+---
+
+The `Bun.main` property contains the absolute path to the current entrypoint.
+
+{% codetabs %}
+
+```ts#foo.ts
+console.log(Bun.main);
+```
+
+```ts#index.ts
+import "./foo.ts";
+```
+
+{% /codetabs %}
+
+---
+
+The printed path corresponds to the file that is executed with `bun run`.
+
+```sh
+$ bun run index.ts
+/path/to/index.ts
+$ bun run foo.ts
+/path/to/foo.ts
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/path-to-file-url.md b/docs/guides/util/path-to-file-url.md
new file mode 100644
index 000000000..202be61eb
--- /dev/null
+++ b/docs/guides/util/path-to-file-url.md
@@ -0,0 +1,14 @@
+---
+name: Convert an absolute path to a file URL
+---
+
+Use `Bun.pathToFileURL()` to convert an absolute path to a `file://` URL.
+
+```ts
+Bun.pathToFileURL("/path/to/file.txt");
+// => "file:///path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/sleep.md b/docs/guides/util/sleep.md
new file mode 100644
index 000000000..dbc39c057
--- /dev/null
+++ b/docs/guides/util/sleep.md
@@ -0,0 +1,22 @@
+---
+name: Sleep for a fixed number of milliseconds
+---
+
+The `Bun.sleep` method provides a convenient way to create a void `Promise` that resolves in a fixed number of milliseconds.
+
+```ts
+// sleep for 1 second
+await Bun.sleep(1000);
+```
+
+---
+
+Internally, this is equivalent to the following snippet that uses [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout).
+
+```ts
+await new Promise((resolve) => setTimeout(resolve, ms));
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/util/version.md b/docs/guides/util/version.md
new file mode 100644
index 000000000..c1f5b8bfa
--- /dev/null
+++ b/docs/guides/util/version.md
@@ -0,0 +1,21 @@
+---
+name: Get the current Bun version
+---
+
+Get the current version of Bun in a semver format.
+
+```ts#index.ts
+Bun.version; // => "0.6.15"
+```
+
+---
+
+Get the exact `git` commit of [`oven-sh/bun`](https://github.com/oven-sh/bun) that was compiled to produce this Bun binary.
+
+```ts#index.ts
+Bun.revision; // => "49231b2cb9aa48497ab966fc0bb6b742dacc4994"
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.