Add fs methods

Author: jdalton

registry/lib/fs.d.ts

@@ -1,14 +1,23 @@
 /// <reference types="node" />
-import {
+import NPMCliPackageJson from '@npmcli/package-json'
+
+import { Remap } from './objects'
+
+import type { Abortable } from 'node:events'
+import type {
+  BigIntStats,
   ObjectEncodingOptions,
+  OpenMode,
   PathLike,
+  PathOrFileDescriptor,
   RmOptions,
-  WriteFileOptions
+  StatSyncOptions,
+  Stats,
+  WriteFileOptions,
+  readFile,
+  readFileSync
 } from 'node:fs'
-
-import NPMCliPackageJson from '@npmcli/package-json'
-
-import { Remap } from './objects'
+import type { FileHandle } from 'node:fs/promises'
 
 declare type BufferEncoding =
   | 'ascii'
@@ -29,9 +38,10 @@ declare type IsDirEmptyOptions = {
 declare type JsonContent = NPMCliPackageJson.Content
 declare type ReadFileOptions =
   | Remap<
-      ObjectEncodingOptions & {
-        flag?: string | undefined
-      }
+      ObjectEncodingOptions &
+        Abortable & {
+          flag?: OpenMode | undefined
+        }
     >
   | BufferEncoding
   | null
@@ -68,6 +78,14 @@ declare const Fs: {
     dirname: string,
     options?: ReadDirOptions | undefined
   ) => string[]
+  readFileBinary(
+    filepath: PathLike | FileHandle,
+    options?: ReadFileOptions | undefined
+  ): Promise<Buffer>
+  readFileUtf8(
+    filepath: PathLike | FileHandle,
+    options?: ReadFileOptions | undefined
+  ): Promise<string>
   readJson(
     filepath: PathLike,
     options?: ReadJsonOptions | undefined
@@ -78,6 +96,51 @@ declare const Fs: {
   ): JsonContent
   remove(filepath: PathLike, options?: RmOptions): Promise<void>
   removeSync(filepath: PathLike, options?: RmOptions): void
+  safeReadFile(
+    filepath: PathLike | FileHandle,
+    options?: 'utf8' | 'utf-8' | { encoding: 'utf8' | 'utf-8' } | undefined
+  ): Promise<string | undefined>
+  safeReadFile(
+    filepath: PathLike | FileHandle,
+    options?: ReadFileOptions | NodeJS.BufferEncoding | undefined
+  ): Promise<Awaited<ReturnType<typeof readFile>> | undefined>
+  safeReadFileSync(
+    filepath: PathOrFileDescriptor,
+    options?: 'utf8' | 'utf-8' | { encoding: 'utf8' | 'utf-8' } | undefined
+  ): string | undefined
+  safeReadFileSync(
+    filepath: PathOrFileDescriptor,
+    options?:
+      | {
+          encoding?: NodeJS.BufferEncoding | undefined
+          flag?: string | undefined
+        }
+      | NodeJS.BufferEncoding
+      | undefined
+  ): ReturnType<typeof readFileSync> | undefined
+  safeStatsSync(filepath: PathLike, options?: undefined): Stats | undefined
+  safeStatsSync(
+    filepath: PathLike,
+    options?: StatSyncOptions & {
+      bigint?: false | undefined
+    }
+  ): Stats | undefined
+  safeStatsSync(
+    filepath: PathLike,
+    options: StatSyncOptions & {
+      bigint: true
+    }
+  ): BigIntStats | undefined
+  safeStatsSync(
+    filepath: PathLike,
+    options: StatSyncOptions & {
+      bigint: boolean
+    }
+  ): Stats | BigIntStats | undefined
+  safeStatsSync(
+    filepath: PathLike,
+    options?: StatSyncOptions
+  ): Stats | BigIntStats | undefined
   uniqueSync(filepath: PathLike): string
   writeJson(
     filepath: PathLike,

registry/lib/fs.js

@@ -95,6 +95,12 @@ function innerReadDirNames(dirents, options) {
   return sort ? names.sort(naturalCompare) : names
 }
 
+/*@__NO_SIDE_EFFECTS__*/
+function isDirSync(filepath) {
+  const fs = getFs()
+  return fs.existsSync(filepath) && !!safeStatsSync(filepath)?.isDirectory()
+}
+
 /*@__NO_SIDE_EFFECTS__*/
 function isDirEmptySync(dirname, options) {
   const { ignore = defaultIgnore } = { __proto__: null, ...options }
@@ -148,7 +154,10 @@ async function readDirNames(dirname, options) {
   const fs = getFs()
   try {
     return innerReadDirNames(
-      await fs.promises.readdir(dirname, { withFileTypes: true }),
+      await fs.promises.readdir(dirname, {
+        __proto__: null,
+        withFileTypes: true
+      }),
       options
     )
   } catch {}
@@ -160,29 +169,48 @@ function readDirNamesSync(dirname, options) {
   const fs = getFs()
   try {
     return innerReadDirNames(
-      fs.readdirSync(dirname, { withFileTypes: true }),
+      fs.readdirSync(dirname, { __proto__: null, withFileTypes: true }),
       options
     )
   } catch {}
   return []
 }
 
+/*@__NO_SIDE_EFFECTS__*/
+async function readFileBinary(filepath, options) {
+  const fs = getFs()
+  return await fs.promises.readFile(filepath, {
+    signal: /*@__PURE__*/ require('./constants/abort-signal'),
+    ...options,
+    encoding: 'binary'
+  })
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+async function readFileUtf8(filepath, options) {
+  const fs = getFs()
+  return await fs.promises.readFile(filepath, {
+    signal: /*@__PURE__*/ require('./constants/abort-signal'),
+    ...options,
+    encoding: 'utf8'
+  })
+}
+
 /*@__NO_SIDE_EFFECTS__*/
 async function readJson(filepath, options) {
   if (typeof options === 'string') {
     options = { encoding: options }
   }
-  const { reviver, throws, ...fsOptionsRaw } = { __proto__: null, ...options }
-  const fsOptions = {
-    __proto__: null,
-    encoding: 'utf8',
-    ...fsOptionsRaw
-  }
+  const { reviver, throws, ...fsOptions } = { __proto__: null, ...options }
   const fs = getFs()
   const shouldThrow = throws === undefined || !!throws
   return parse(
     filepath,
-    await fs.promises.readFile(filepath, fsOptions),
+    await fs.promises.readFile(filepath, {
+      __proto__: null,
+      encoding: 'utf8',
+      ...fsOptions
+    }),
     reviver,
     shouldThrow
   )
@@ -193,17 +221,16 @@ function readJsonSync(filepath, options) {
   if (typeof options === 'string') {
     options = { encoding: options }
   }
-  const { reviver, throws, ...fsOptionsRaw } = { __proto__: null, ...options }
-  const fsOptions = {
-    __proto__: null,
-    encoding: 'utf8',
-    ...fsOptionsRaw
-  }
+  const { reviver, throws, ...fsOptions } = { __proto__: null, ...options }
   const fs = getFs()
   const shouldThrow = throws === undefined || !!throws
   return parse(
     filepath,
-    fs.readFileSync(filepath, fsOptions),
+    fs.readFileSync(filepath, {
+      __proto__: null,
+      encoding: 'utf8',
+      ...fsOptions
+    }),
     reviver,
     shouldThrow
   )
@@ -231,6 +258,45 @@ function removeSync(filepath, options) {
   })
 }
 
+/*@__NO_SIDE_EFFECTS__*/
+async function safeReadFile(filepath, options) {
+  const fs = getFs()
+  try {
+    return await fs.promises.readFile(filepath, {
+      encoding: 'utf8',
+      signal: /*@__PURE__*/ require('./constants/abort-signal'),
+      ...(typeof options === 'string' ? { encoding: options } : options)
+    })
+  } catch {}
+  return undefined
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+function safeStatsSync(filepath, options) {
+  const fs = getFs()
+  try {
+    return fs.statSync(filepath, {
+      __proto__: null,
+      throwIfNoEntry: false,
+      ...options
+    })
+  } catch {}
+  return undefined
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+function safeReadFileSync(filepath, options) {
+  const fs = getFs()
+  try {
+    return fs.readFileSync(filepath, {
+      __proto__: null,
+      encoding: 'utf8',
+      ...(typeof options === 'string' ? { encoding: options } : options)
+    })
+  } catch {}
+  return undefined
+}
+
 /*@__NO_SIDE_EFFECTS__*/
 function stringify(
   json,
@@ -261,48 +327,52 @@ async function writeJson(filepath, json, options) {
   if (typeof options === 'string') {
     options = { encoding: options }
   }
-  const { EOL, finalEOL, replacer, spaces, ...fsOptionsRaw } = {
+  const { EOL, finalEOL, replacer, spaces, ...fsOptions } = {
     __proto__: null,
     ...options
   }
-  const fsOptions = {
-    __proto__: null,
-    encoding: 'utf8',
-    ...fsOptionsRaw
-  }
   const fs = getFs()
   const str = stringify(json, EOL, finalEOL, replacer, spaces)
-  await fs.promises.writeFile(filepath, str, fsOptions)
+  await fs.promises.writeFile(filepath, str, {
+    __proto__: null,
+    encoding: 'utf8',
+    ...fsOptions
+  })
 }
 
 /*@__NO_SIDE_EFFECTS__*/
 function writeJsonSync(filepath, json, options) {
   if (typeof options === 'string') {
     options = { encoding: options }
   }
-  const { EOL, finalEOL, replacer, spaces, ...fsOptionsRaw } = {
+  const { EOL, finalEOL, replacer, spaces, ...fsOptions } = {
     __proto__: null,
     ...options
   }
-  const fsOptions = {
-    __proto__: null,
-    encoding: 'utf8',
-    ...fsOptionsRaw
-  }
   const fs = getFs()
   const str = stringify(json, EOL, finalEOL, replacer, spaces)
-  fs.writeFileSync(filepath, str, fsOptions)
+  fs.writeFileSync(filepath, str, {
+    __proto__: null,
+    encoding: 'utf8',
+    ...fsOptions
+  })
 }
 
 module.exports = {
+  isDirSync,
   isDirEmptySync,
   isSymLinkSync,
+  readFileBinary,
+  readFileUtf8,
   readJson,
   readJsonSync,
   readDirNames,
   readDirNamesSync,
   remove,
   removeSync,
+  safeReadFile,
+  safeReadFileSync,
+  safeStatsSync,
   uniqueSync,
   writeJson,
   writeJsonSync