fix(fs): improve safeReadFile type signatures with proper encoding overloads

- Add function overloads to correctly type return values based on encoding
- When encoding is null, return Buffer | undefined
- When encoding is specified or default, return string | undefined
- Default to 'utf8' encoding for better ergonomics
- Add support for defaultValue handling based on return type
- Improve JSDoc with clearer examples for string vs buffer usage

This resolves TypeScript errors where safeReadFile with encoding: 'utf8'
was incorrectly typed as returning Buffer instead of string.

Author: jdalton

src/fs.ts

@@ -301,6 +301,26 @@ const defaultRemoveOptions = objectFreeze({
   retryDelay: 200,
 })
 
+let _buffer: typeof import('node:buffer') | undefined
+/**
+ * Lazily load the buffer module.
+ *
+ * Performs on-demand loading of Node.js buffer module to avoid initialization
+ * overhead and potential Webpack bundling errors.
+ *
+ * @private
+ * @returns {typeof import('node:buffer')} The buffer module
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function getBuffer() {
+  if (_buffer === undefined) {
+    // Use non-'node:' prefixed require to avoid Webpack errors.
+
+    _buffer = /*@__PURE__*/ require('node:buffer')
+  }
+  return _buffer as typeof import('node:buffer')
+}
+
 let _fs: typeof import('fs') | undefined
 /**
  * Lazily load the fs module to avoid Webpack errors.
@@ -983,8 +1003,8 @@ export async function readJson(
   try {
     content = await fs.promises.readFile(filepath, {
       __proto__: null,
-      encoding: 'utf8',
       ...fsOptions,
+      encoding: 'utf8',
     } as unknown as Parameters<typeof fs.promises.readFile>[1] & {
       encoding: string
     })
@@ -1060,8 +1080,8 @@ export function readJsonSync(
   try {
     content = fs.readFileSync(filepath, {
       __proto__: null,
-      encoding: 'utf8',
       ...fsOptions,
+      encoding: 'utf8',
     } as unknown as Parameters<typeof fs.readFileSync>[1] & {
       encoding: string
     })
@@ -1381,74 +1401,133 @@ export function safeMkdirSync(
  * Safely read a file asynchronously, returning undefined on error.
  * Useful when you want to attempt reading a file without handling errors explicitly.
  * Returns undefined for any error (file not found, permission denied, etc.).
+ * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly set to null.
  *
  * @param filepath - Path to file
  * @param options - Read options including encoding and default value
- * @returns Promise resolving to file contents, or undefined on error
+ * @returns Promise resolving to file contents (string by default), or undefined on error
  *
  * @example
  * ```ts
- * // Try to read a file, get undefined if it doesn't exist
+ * // Try to read a file as UTF-8 string (default), get undefined if it doesn't exist
  * const content = await safeReadFile('./optional-config.txt')
  * if (content) {
  *   console.log('Config found:', content)
  * }
  *
  * // Read with specific encoding
  * const data = await safeReadFile('./data.txt', { encoding: 'utf8' })
+ *
+ * // Read as Buffer by setting encoding to null
+ * const buffer = await safeReadFile('./binary.dat', { encoding: null })
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
+export async function safeReadFile(
+  filepath: PathLike,
+  options: SafeReadOptions & { encoding: null },
+): Promise<Buffer | undefined>
+/*@__NO_SIDE_EFFECTS__*/
 export async function safeReadFile(
   filepath: PathLike,
   options?: SafeReadOptions | undefined,
-) {
-  const opts = typeof options === 'string' ? { encoding: options } : options
+): Promise<string | undefined>
+/*@__NO_SIDE_EFFECTS__*/
+export async function safeReadFile(
+  filepath: PathLike,
+  options?: SafeReadOptions | undefined,
+): Promise<string | Buffer | undefined> {
+  const opts =
+    typeof options === 'string'
+      ? { __proto__: null, encoding: options }
+      : ({ __proto__: null, ...options } as SafeReadOptions)
+  const { defaultValue, ...rawReadOpts } = opts as SafeReadOptions
+  const readOpts = { __proto__: null, ...rawReadOpts } as ReadOptions
+  const { encoding = 'utf8' } = readOpts
+  const shouldReturnBuffer = encoding === null
   const fs = getFs()
   try {
     return await fs.promises.readFile(filepath, {
+      __proto__: null,
       signal: abortSignal,
-      ...opts,
+      ...readOpts,
+      encoding,
     } as Abortable)
   } catch {}
-  return undefined
+  if (defaultValue === undefined) {
+    return undefined
+  }
+  if (shouldReturnBuffer) {
+    const { Buffer } = getBuffer()
+    return Buffer.isBuffer(defaultValue) ? defaultValue : undefined
+  }
+  return typeof defaultValue === 'string' ? defaultValue : String(defaultValue)
 }
 
 /**
  * Safely read a file synchronously, returning undefined on error.
  * Useful when you want to attempt reading a file without handling errors explicitly.
  * Returns undefined for any error (file not found, permission denied, etc.).
+ * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly set to null.
  *
  * @param filepath - Path to file
  * @param options - Read options including encoding and default value
- * @returns File contents, or undefined on error
+ * @returns File contents (string by default), or undefined on error
  *
  * @example
  * ```ts
- * // Try to read a config file
+ * // Try to read a config file as UTF-8 string (default)
  * const config = safeReadFileSync('./config.txt')
  * if (config) {
  *   console.log('Config loaded successfully')
  * }
  *
- * // Read binary file safely
+ * // Read with explicit encoding
+ * const data = safeReadFileSync('./data.txt', { encoding: 'utf8' })
+ *
+ * // Read binary file by setting encoding to null
  * const buffer = safeReadFileSync('./image.png', { encoding: null })
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
+export function safeReadFileSync(
+  filepath: PathLike,
+  options: SafeReadOptions & { encoding: null },
+): Buffer | undefined
+/*@__NO_SIDE_EFFECTS__*/
 export function safeReadFileSync(
   filepath: PathLike,
   options?: SafeReadOptions | undefined,
-) {
-  const opts = typeof options === 'string' ? { encoding: options } : options
+): string | undefined
+/*@__NO_SIDE_EFFECTS__*/
+export function safeReadFileSync(
+  filepath: PathLike,
+  options?: SafeReadOptions | undefined,
+): string | Buffer | undefined {
+  const opts =
+    typeof options === 'string'
+      ? { __proto__: null, encoding: options }
+      : ({ __proto__: null, ...options } as SafeReadOptions)
+  const { defaultValue, ...rawReadOpts } = opts as SafeReadOptions
+  const readOpts = { __proto__: null, ...rawReadOpts } as ReadOptions
+  const { encoding = 'utf8' } = readOpts
+  const shouldReturnBuffer = encoding === null
   const fs = getFs()
   try {
     return fs.readFileSync(filepath, {
       __proto__: null,
-      ...opts,
+      ...readOpts,
+      encoding,
     } as ObjectEncodingOptions)
   } catch {}
-  return undefined
+  if (defaultValue === undefined) {
+    return undefined
+  }
+  if (shouldReturnBuffer) {
+    const { Buffer } = getBuffer()
+    return Buffer.isBuffer(defaultValue) ? defaultValue : undefined
+  }
+  return typeof defaultValue === 'string' ? defaultValue : String(defaultValue)
 }
 
 /**

test/unit/fs-sync.test.ts

@@ -200,13 +200,13 @@ describe.sequential('fs - Sync Functions', () => {
   })
 
   describe('safeReadFileSync', () => {
-    it('should read existing file', () => {
+    it('should read existing file as utf8 string by default', () => {
       const file = join(testDir, 'safe-read.txt')
       writeFileSync(file, 'safe content')
 
       const result = safeReadFileSync(file)
-      expect(Buffer.isBuffer(result)).toBe(true)
-      expect(result?.toString()).toBe('safe content')
+      expect(typeof result).toBe('string')
+      expect(result).toBe('safe content')
     })
 
     it('should return undefined for non-existent files', () => {
@@ -220,8 +220,8 @@ describe.sequential('fs - Sync Functions', () => {
       writeFileSync(emptyFile, '')
 
       const result = safeReadFileSync(emptyFile)
-      expect(Buffer.isBuffer(result)).toBe(true)
-      expect(result?.toString()).toBe('')
+      expect(typeof result).toBe('string')
+      expect(result).toBe('')
     })
 
     it('should read files with special characters', () => {
@@ -231,6 +231,16 @@ describe.sequential('fs - Sync Functions', () => {
       writeFileSync(file, content)
 
       const result = safeReadFileSync(file)
+      expect(typeof result).toBe('string')
+      expect(result).toBe(content)
+    })
+
+    it('should read as buffer when encoding is explicitly null', () => {
+      const file = join(testDir, 'buffer-read.txt')
+      const content = 'buffer content'
+      writeFileSync(file, content)
+
+      const result = safeReadFileSync(file, { encoding: null })
       expect(Buffer.isBuffer(result)).toBe(true)
       expect(result?.toString()).toBe(content)
     })
@@ -301,8 +311,8 @@ describe.sequential('fs - Sync Functions', () => {
       writeFileSync(file1, 'content1')
       writeFileSync(file2, 'content2')
 
-      expect(safeReadFileSync(file1)?.toString()).toBe('content1')
-      expect(safeReadFileSync(file2)?.toString()).toBe('content2')
+      expect(safeReadFileSync(file1)).toBe('content1')
+      expect(safeReadFileSync(file2)).toBe('content2')
       expect(safeReadFileSync(file3)).toBeUndefined()
 
       expect(safeStatsSync(file1)?.isFile()).toBe(true)

test/unit/fs.test.ts

@@ -875,7 +875,7 @@ describe('fs', () => {
   })
 
   describe('safeReadFile', () => {
-    it('should read existing file', async () => {
+    it('should read existing file with explicit encoding', async () => {
       await runWithTempDir(async tmpDir => {
         const testFile = path.join(tmpDir, 'test.txt')
         const testContent = 'test content'
@@ -891,20 +891,33 @@ describe('fs', () => {
       expect(result).toBeUndefined()
     })
 
-    it('should read as buffer when no encoding specified', async () => {
+    it('should read as utf8 string by default when no encoding specified', async () => {
+      await runWithTempDir(async tmpDir => {
+        const testFile = path.join(tmpDir, 'text.txt')
+        const testContent = 'default encoding test'
+        await fs.writeFile(testFile, testContent, 'utf8')
+
+        const result = await safeReadFile(testFile)
+        expect(typeof result).toBe('string')
+        expect(result).toBe(testContent)
+      }, 'safeReadFile-default-')
+    })
+
+    it('should read as buffer when encoding is explicitly null', async () => {
       await runWithTempDir(async tmpDir => {
         const testFile = path.join(tmpDir, 'binary.dat')
         const testData = Buffer.from([0x01, 0x02, 0x03])
         await fs.writeFile(testFile, testData)
 
-        const result = await safeReadFile(testFile)
+        const result = await safeReadFile(testFile, { encoding: null })
         expect(Buffer.isBuffer(result)).toBe(true)
+        expect(result).toEqual(testData)
       }, 'safeReadFile-buffer-')
     })
   })
 
   describe('safeReadFileSync', () => {
-    it('should read existing file', async () => {
+    it('should read existing file with explicit encoding', async () => {
       await runWithTempDir(async tmpDir => {
         const testFile = path.join(tmpDir, 'test.txt')
         const testContent = 'test content'
@@ -920,14 +933,27 @@ describe('fs', () => {
       expect(result).toBeUndefined()
     })
 
-    it('should read as buffer when no encoding specified', async () => {
+    it('should read as utf8 string by default when no encoding specified', async () => {
+      await runWithTempDir(async tmpDir => {
+        const testFile = path.join(tmpDir, 'text.txt')
+        const testContent = 'default encoding test'
+        await fs.writeFile(testFile, testContent, 'utf8')
+
+        const result = safeReadFileSync(testFile)
+        expect(typeof result).toBe('string')
+        expect(result).toBe(testContent)
+      }, 'safeReadFileSync-default-')
+    })
+
+    it('should read as buffer when encoding is explicitly null', async () => {
       await runWithTempDir(async tmpDir => {
         const testFile = path.join(tmpDir, 'binary.dat')
         const testData = Buffer.from([0x01, 0x02, 0x03])
         await fs.writeFile(testFile, testData)
 
-        const result = safeReadFileSync(testFile)
+        const result = safeReadFileSync(testFile, { encoding: null })
         expect(Buffer.isBuffer(result)).toBe(true)
+        expect(result).toEqual(testData)
       }, 'safeReadFileSync-buffer-')
     })
   })