Remove the dependency on LegacyAdatpers in FileSystem. (#5170)

Author: iclanton

common/changes/@rushstack/node-core-library/remove-legacyAdapters-from-FileSystem_2025-03-24-22-21.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "",
+      "type": "none",
+      "packageName": "@rushstack/node-core-library"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library",
+  "email": "iclanton@users.noreply.github.com"
+}

common/changes/@rushstack/node-core-library/remove-legacyAdapters-from-FileSystem_2025-03-24-22-40.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "Expand `FileSystem.writeBuffersToFile` and `FileSystem.writeBuffersToFileAsync` to take more kinds of buffers.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library"
+}

common/reviews/api/node-core-library.api.md

@@ -201,8 +201,8 @@ export class FileSystem {
     static readLinkAsync(path: string): Promise<string>;
     static updateTimes(path: string, times: IFileSystemUpdateTimeParameters): void;
     static updateTimesAsync(path: string, times: IFileSystemUpdateTimeParameters): Promise<void>;
-    static writeBuffersToFile(filePath: string, contents: ReadonlyArray<Uint8Array>, options?: IFileSystemWriteBinaryFileOptions): void;
-    static writeBuffersToFileAsync(filePath: string, contents: ReadonlyArray<Uint8Array>, options?: IFileSystemWriteBinaryFileOptions): Promise<void>;
+    static writeBuffersToFile(filePath: string, contents: ReadonlyArray<NodeJS.ArrayBufferView>, options?: IFileSystemWriteBinaryFileOptions): void;
+    static writeBuffersToFileAsync(filePath: string, contents: ReadonlyArray<NodeJS.ArrayBufferView>, options?: IFileSystemWriteBinaryFileOptions): Promise<void>;
     static writeFile(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): void;
     static writeFileAsync(filePath: string, contents: string | Buffer, options?: IFileSystemWriteFileOptions): Promise<void>;
 }

libraries/node-core-library/src/FileSystem.ts

@@ -3,11 +3,11 @@
 
 import * as nodeJsPath from 'path';
 import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
 import * as fsx from 'fs-extra';
 
 import { Text, type NewlineKind, Encoding } from './Text';
 import { PosixModeBits } from './PosixModeBits';
-import { LegacyAdapters } from './LegacyAdapters';
 
 /**
  * An alias for the Node.js `fs.Stats` object.
@@ -684,11 +684,7 @@ export class FileSystem {
         ...options
       };
 
-      const folderEntries: FolderItem[] = await LegacyAdapters.convertCallbackToPromise(
-        fs.readdir,
-        folderPath,
-        { withFileTypes: true }
-      );
+      const folderEntries: FolderItem[] = await fsPromises.readdir(folderPath, { withFileTypes: true });
       if (options.absolutePaths) {
         return folderEntries.map((folderEntry) => {
           folderEntry.name = nodeJsPath.resolve(folderPath, folderEntry.name);
@@ -806,13 +802,13 @@ export class FileSystem {
    */
   public static writeBuffersToFile(
     filePath: string,
-    contents: ReadonlyArray<Uint8Array>,
+    contents: ReadonlyArray<NodeJS.ArrayBufferView>,
     options?: IFileSystemWriteBinaryFileOptions
   ): void {
     FileSystem._wrapException(() => {
       // Need a mutable copy of the iterable to handle incomplete writes,
       // since writev() doesn't take an argument for where to start writing.
-      const toCopy: Uint8Array[] = [...contents];
+      const toCopy: NodeJS.ArrayBufferView[] = [...contents];
 
       let fd: number | undefined;
       try {
@@ -837,7 +833,12 @@ export class FileSystem {
             const bytesInCurrentBuffer: number = toCopy[buffersWritten].byteLength;
             if (bytesWritten < bytesInCurrentBuffer) {
               // This buffer was partially written.
-              toCopy[buffersWritten] = toCopy[buffersWritten].subarray(bytesWritten);
+              const currentToCopy: NodeJS.ArrayBufferView = toCopy[buffersWritten];
+              toCopy[buffersWritten] = new Uint8Array(
+                currentToCopy.buffer,
+                currentToCopy.byteOffset + bytesWritten,
+                currentToCopy.byteLength - bytesWritten
+              );
               break;
             }
             bytesWritten -= bytesInCurrentBuffer;
@@ -896,25 +897,25 @@ export class FileSystem {
    */
   public static async writeBuffersToFileAsync(
     filePath: string,
-    contents: ReadonlyArray<Uint8Array>,
+    contents: ReadonlyArray<NodeJS.ArrayBufferView>,
     options?: IFileSystemWriteBinaryFileOptions
   ): Promise<void> {
     await FileSystem._wrapExceptionAsync(async () => {
       // Need a mutable copy of the iterable to handle incomplete writes,
       // since writev() doesn't take an argument for where to start writing.
-      const toCopy: Uint8Array[] = [...contents];
+      const toCopy: NodeJS.ArrayBufferView[] = [...contents];
 
-      let handle: fs.promises.FileHandle | undefined;
+      let handle: fsPromises.FileHandle | undefined;
       try {
-        handle = await fs.promises.open(filePath, 'w');
+        handle = await fsPromises.open(filePath, 'w');
       } catch (error) {
         if (!options?.ensureFolderExists || !FileSystem.isNotExistError(error as Error)) {
           throw error;
         }
 
         const folderPath: string = nodeJsPath.dirname(filePath);
         await FileSystem.ensureFolderAsync(folderPath);
-        handle = await fs.promises.open(filePath, 'w');
+        handle = await fsPromises.open(filePath, 'w');
       }
 
       try {
@@ -927,7 +928,12 @@ export class FileSystem {
             const bytesInCurrentBuffer: number = toCopy[buffersWritten].byteLength;
             if (bytesWritten < bytesInCurrentBuffer) {
               // This buffer was partially written.
-              toCopy[buffersWritten] = toCopy[buffersWritten].subarray(bytesWritten);
+              const currentToCopy: NodeJS.ArrayBufferView = toCopy[buffersWritten];
+              toCopy[buffersWritten] = new Uint8Array(
+                currentToCopy.buffer,
+                currentToCopy.byteOffset + bytesWritten,
+                currentToCopy.byteLength - bytesWritten
+              );
               break;
             }
             bytesWritten -= bytesInCurrentBuffer;

libraries/node-core-library/src/test/writeBuffersToFile.test.ts

@@ -18,6 +18,11 @@ jest.mock('fs-extra', () => {
     writevSync
   };
 });
+jest.mock('fs/promises', () => {
+  return {
+    open: openHandle
+  };
+});
 jest.mock('../Text', () => {
   return {
     Encoding: {
@@ -26,14 +31,6 @@ jest.mock('../Text', () => {
   };
 });
 
-import fs from 'node:fs';
-
-jest.spyOn(fs, 'promises', 'get').mockImplementation(() => {
-  return {
-    open: openHandle
-  } as unknown as typeof fs.promises;
-});
-
 describe('FileSystem', () => {
   const content: Uint8Array[] = [];
   let totalBytes: number = 0;