feat(fs): add Node.js normalizeEncoding for robust encoding handling

Add normalizeEncoding function based on Node.js internal/util.js
implementation to handle encoding name variations and normalization.

- Add slowCases() helper to handle less common encoding variants
- Add normalizeEncoding() for optimized common case handling
- Integrate normalizeEncoding into safeReadFile and safeReadFileSync
- Handles uppercase, hyphenated, and variant encoding names
- Optimized for performance with fast path for utf8/utf-8/null

This ensures consistent encoding behavior matching Node.js core,
handling variants like UTF-8, utf-8, UTF8, LATIN1, latin1, etc.

Based on: https://github.com/nodejs/node/blob/ae62b36d442b7bf987e85ae6e0df0f02cc1bb17f/lib/internal/util.js#L247-L310

Author: jdalton

src/fs.ts

@@ -356,6 +356,144 @@ function getPath() {
   return _path as typeof import('path')
 }
 
+/**
+ * Move the "slow cases" to a separate function to make sure this function gets
+ * inlined properly. That prioritizes the common case.
+ *
+ * Based on Node.js internal/util.js normalizeEncoding implementation.
+ * @see https://github.com/nodejs/node/blob/ae62b36d442b7bf987e85ae6e0df0f02cc1bb17f/lib/internal/util.js#L247-L310
+ *
+ * @param enc - Encoding to normalize
+ * @returns Normalized encoding string or undefined if no match
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function slowCases(enc: string): BufferEncoding | undefined {
+  switch (enc.length) {
+    case 4:
+      if (enc === 'UTF8') {
+        return 'utf8'
+      }
+      if (enc === 'ucs2' || enc === 'UCS2') {
+        return 'utf16le'
+      }
+      enc = enc.toLowerCase()
+      if (enc === 'utf8') {
+        return 'utf8'
+      }
+      if (enc === 'ucs2') {
+        return 'utf16le'
+      }
+      break
+    case 3:
+      if (enc === 'hex' || enc === 'HEX' || enc.toLowerCase() === 'hex') {
+        return 'hex'
+      }
+      break
+    case 5:
+      if (enc === 'ascii') {
+        return 'ascii'
+      }
+      if (enc === 'ucs-2') {
+        return 'utf16le'
+      }
+      if (enc === 'UTF-8') {
+        return 'utf8'
+      }
+      if (enc === 'ASCII') {
+        return 'ascii'
+      }
+      if (enc === 'UCS-2') {
+        return 'utf16le'
+      }
+      enc = enc.toLowerCase()
+      if (enc === 'utf-8') {
+        return 'utf8'
+      }
+      if (enc === 'ascii') {
+        return 'ascii'
+      }
+      if (enc === 'ucs-2') {
+        return 'utf16le'
+      }
+      break
+    case 6:
+      if (enc === 'base64') {
+        return 'base64'
+      }
+      if (enc === 'latin1' || enc === 'binary') {
+        return 'latin1'
+      }
+      if (enc === 'BASE64') {
+        return 'base64'
+      }
+      if (enc === 'LATIN1' || enc === 'BINARY') {
+        return 'latin1'
+      }
+      enc = enc.toLowerCase()
+      if (enc === 'base64') {
+        return 'base64'
+      }
+      if (enc === 'latin1' || enc === 'binary') {
+        return 'latin1'
+      }
+      break
+    case 7:
+      if (
+        enc === 'utf16le' ||
+        enc === 'UTF16LE' ||
+        enc.toLowerCase() === 'utf16le'
+      ) {
+        return 'utf16le'
+      }
+      break
+    case 8:
+      if (
+        enc === 'utf-16le' ||
+        enc === 'UTF-16LE' ||
+        enc.toLowerCase() === 'utf-16le'
+      ) {
+        return 'utf16le'
+      }
+      break
+    case 9:
+      if (
+        enc === 'base64url' ||
+        enc === 'BASE64URL' ||
+        enc.toLowerCase() === 'base64url'
+      ) {
+        return 'base64url'
+      }
+      break
+    default:
+      if (enc === '') {
+        return 'utf8'
+      }
+  }
+  return undefined
+}
+
+/**
+ * Normalize encoding string to canonical form.
+ * Handles common encodings inline for performance, delegates to slowCases for others.
+ *
+ * Based on Node.js internal/util.js normalizeEncoding implementation.
+ * @see https://github.com/nodejs/node/blob/ae62b36d442b7bf987e85ae6e0df0f02cc1bb17f/lib/internal/util.js#L247-L310
+ *
+ * @param enc - Encoding to normalize (can be null/undefined)
+ * @returns Normalized encoding string, defaults to 'utf8'
+ * @private
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function normalizeEncoding(
+  enc: BufferEncoding | string | null | undefined,
+): BufferEncoding {
+  if (enc == null || enc === 'utf8' || enc === 'utf-8') {
+    return 'utf8'
+  }
+  return slowCases(enc) ?? 'utf8'
+}
+
 /**
  * Process directory entries and filter for directories.
  * Filters entries to include only directories, optionally excluding empty ones.
@@ -1443,7 +1581,9 @@ export async function safeReadFile(
       : ({ __proto__: null, ...options } as SafeReadOptions)
   const { defaultValue, ...rawReadOpts } = opts as SafeReadOptions
   const readOpts = { __proto__: null, ...rawReadOpts } as ReadOptions
-  const { encoding = 'utf8' } = readOpts
+  let { encoding = 'utf8' } = readOpts
+  // Normalize encoding to canonical form.
+  encoding = encoding === null ? null : normalizeEncoding(encoding)
   const shouldReturnBuffer = encoding === null
   const fs = getFs()
   try {
@@ -1510,7 +1650,9 @@ export function safeReadFileSync(
       : ({ __proto__: null, ...options } as SafeReadOptions)
   const { defaultValue, ...rawReadOpts } = opts as SafeReadOptions
   const readOpts = { __proto__: null, ...rawReadOpts } as ReadOptions
-  const { encoding = 'utf8' } = readOpts
+  let { encoding = 'utf8' } = readOpts
+  // Normalize encoding to canonical form.
+  encoding = encoding === null ? null : normalizeEncoding(encoding)
   const shouldReturnBuffer = encoding === null
   const fs = getFs()
   try {