Add removeFile (#268)

brianquinlan · web-flow · commit 77464e7611c5 · 2025-08-14T16:12:17.000-07:00
diff --git a/pkgs/io_file/README.md b/pkgs/io_file/README.md
@@ -18,7 +18,7 @@ See
 |  create tmp directory |    ✓    |   ✓   |   ✓   |   ✓   |    ✓    |            |              |
 |  create tmp file      |         |       |       |       |        |            |              |
 |  delete directory     |    ✓    |   ✓   |   ✓   |   ✓   |    ✓    |            |              |
-|  delete file          |         |       |       |                |            |              |
+|  delete file          |    ✓    |   ✓   |   ✓   |   ✓   |    ✓    |            |              |
 |  delete tree          |    ✓    |   ✓   |   ✓   |   ✓   |    ✓    |            |              |
 |  enum dir contents    |         |       |       |       |        |            |              |
 |  exists               |         |       |              |         |            |              |
diff --git a/pkgs/io_file/lib/src/file_system.dart b/pkgs/io_file/lib/src/file_system.dart
@@ -256,6 +256,17 @@ abstract class FileSystem {
   /// those links are deleted but their targets are not.
   void removeDirectoryTree(String path);
 
+  /// Deletes the file at the given path.
+  ///
+  /// If `path` represents a directory, then [IOFileException] is thrown.
+  ///
+  /// If `path` represents a symbolic link to a file, then the symbolic link is
+  /// deleted.
+  ///
+  /// If `path` represents a symbolic link to a directory then, on POSIX, the
+  /// symbolic link is deleted. On Windows, a [IOFileException] is thrown.
+  void removeFile(String path);
+
   /// Reads the entire file contents as a list of bytes.
   Uint8List readAsBytes(String path);
 
diff --git a/pkgs/io_file/lib/src/vm_posix_file_system.dart b/pkgs/io_file/lib/src/vm_posix_file_system.dart
@@ -517,6 +517,15 @@ final class PosixFileSystem extends FileSystem {
     );
   });
 
+  @override
+  void removeFile(String path) => ffi.using((arena) {
+    final nativePath = path.toNativeUtf8(allocator: arena);
+    if (libc.unlinkat(libc.AT_FDCWD, nativePath.cast(), 0) == -1) {
+      final errno = libc.errno;
+      throw _getError(errno, systemCall: 'unlinkat', path1: path);
+    }
+  });
+
   @override
   Uint8List readAsBytes(String path) => ffi.using((arena) {
     final fd = _tempFailureRetry(
diff --git a/pkgs/io_file/lib/src/vm_windows_file_system.dart b/pkgs/io_file/lib/src/vm_windows_file_system.dart
@@ -678,6 +678,16 @@ final class WindowsFileSystem extends FileSystem {
     }
   });
 
+  @override
+  void removeFile(String path) => using((arena) {
+    _primeGetLastError();
+
+    if (win32.DeleteFile(_extendedPath(path, arena)) == win32.FALSE) {
+      final errorCode = win32.GetLastError();
+      throw _getError(errorCode, systemCall: 'DeleteFile', path1: path);
+    }
+  });
+
   @override
   Uint8List readAsBytes(String path) => using((arena) {
     _primeGetLastError();
diff --git a/pkgs/io_file/lib/src/web_posix_file_system.dart b/pkgs/io_file/lib/src/web_posix_file_system.dart
@@ -55,6 +55,11 @@ final class PosixFileSystem extends FileSystem {
     throw UnimplementedError();
   }
 
+  @override
+  void removeFile(String path) {
+    throw UnimplementedError();
+  }
+
   @override
   void rename(String oldPath, String newPath) {
     throw UnimplementedError();
diff --git a/pkgs/io_file/lib/src/web_windows_file_system.dart b/pkgs/io_file/lib/src/web_windows_file_system.dart
@@ -54,6 +54,11 @@ base class WindowsFileSystem extends FileSystem {
     throw UnimplementedError();
   }
 
+  @override
+  void removeFile(String path) {
+    throw UnimplementedError();
+  }
+
   @override
   void rename(String oldPath, String newPath) {
     throw UnimplementedError();
diff --git a/pkgs/io_file/test/dart_io_file_utils.dart b/pkgs/io_file/test/dart_io_file_utils.dart
@@ -19,6 +19,10 @@ class DartIOFileUtils implements FileUtils {
   void deleteDirectoryTree(String path) =>
       Directory(path).deleteSync(recursive: true);
 
+  @override
+  bool exists(String path) =>
+      FileSystemEntity.typeSync(path) != FileSystemEntityType.notFound;
+
   @override
   bool isDirectory(String path) => FileSystemEntity.isDirectorySync(path);
 
diff --git a/pkgs/io_file/test/file_system_file_utils.dart b/pkgs/io_file/test/file_system_file_utils.dart
@@ -40,6 +40,18 @@ class FileSystemFileUtils implements FileUtils {
     fs.removeDirectoryTree(path);
   }
 
+  @override
+  bool exists(String path) {
+    // TODO(brianquinlan): Switch to `FileSystem.exists` when such a method
+    // exists.
+    try {
+      fs.metadata(path);
+    } on PathNotFoundException {
+      return false;
+    }
+    return true;
+  }
+
   @override
   bool isDirectory(String path) => fs.metadata(path).isDirectory;
 
diff --git a/pkgs/io_file/test/remove_file_test.dart b/pkgs/io_file/test/remove_file_test.dart
@@ -0,0 +1,161 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+@TestOn('vm')
+library;
+
+import 'dart:io' as io;
+
+import 'package:io_file/io_file.dart';
+import 'package:io_file/src/vm_windows_file_system.dart';
+import 'package:path/path.dart' as p;
+import 'package:test/test.dart';
+import 'package:win32/win32.dart' as win32;
+
+import 'errors.dart' as errors;
+import 'file_system_file_utils.dart' hide fileUtils;
+import 'test_utils.dart';
+
+void tests(FileUtils utils, FileSystem fs) {
+  late String tmp;
+  late String cwd;
+
+  setUp(() {
+    tmp = utils.createTestDirectory('removeFile');
+    cwd = fs.currentDirectory;
+    fs.currentDirectory = tmp;
+  });
+
+  tearDown(() {
+    fs.currentDirectory = cwd;
+    utils.deleteDirectoryTree(tmp);
+  });
+
+  test('success', () {
+    final path = '$tmp/file';
+    utils.createTextFile(path, 'Hello World!');
+
+    fileSystem.removeFile(path);
+
+    expect(utils.exists(path), isFalse, reason: '$path exists');
+  });
+
+  test('absolute path, long directory name', () {
+    // On Windows:
+    // When using an API to create a directory, the specified path cannot be
+    // so long that you cannot append an 8.3 file name (that is, the directory
+    // name cannot exceed MAX_PATH minus 12).
+    final dirname = 'd' * (io.Platform.isWindows ? win32.MAX_PATH - 12 : 255);
+    final path = p.join(tmp, dirname);
+    utils.createTextFile(path, 'Hello World!');
+
+    fileSystem.removeFile(path);
+
+    expect(utils.exists(path), isFalse, reason: '$path exists');
+  });
+
+  test('relative path, long directory name', () {
+    // On Windows:
+    // When using an API to create a directory, the specified path cannot be
+    // so long that you cannot append an 8.3 file name (that is, the directory
+    // name cannot exceed MAX_PATH minus 12).
+    final path = 'd' * (io.Platform.isWindows ? win32.MAX_PATH - 12 : 255);
+    utils.createTextFile(path, 'Hello World!');
+
+    fileSystem.removeFile(path);
+
+    expect(utils.exists(path), isFalse, reason: '$path exists');
+  });
+
+  test('directory', () {
+    final path = p.join(tmp, 'dir');
+    utils.createDirectory(path);
+
+    expect(
+      () => fileSystem.removeFile(path),
+      throwsA(
+        isA<IOFileException>().having(
+          (e) => e.errorCode,
+          'errorCode',
+          fileSystem is WindowsFileSystem
+              ? win32.ERROR_ACCESS_DENIED
+              : anyOf(
+                errors.eperm, // POSIX
+                errors.eisdir, // Linux
+              ),
+        ),
+      ),
+    );
+  });
+
+  test('link to directory', () {
+    final dirPath = p.join(tmp, 'dir');
+    final linkPath = p.join(tmp, 'link');
+    utils.createDirectory(dirPath);
+    io.Link(linkPath).createSync(dirPath);
+
+    if (fs is WindowsFileSystem) {
+      expect(
+        () => fileSystem.removeFile(linkPath),
+        throwsA(
+          isA<PathAccessException>().having(
+            (e) => e.errorCode,
+            'errorCode',
+            win32.ERROR_ACCESS_DENIED,
+          ),
+        ),
+      );
+      expect(utils.exists(dirPath), isTrue, reason: '$dirPath does not exist');
+      expect(
+        utils.exists(linkPath),
+        isTrue,
+        reason: '$linkPath does not exist',
+      );
+    } else {
+      fileSystem.removeFile(linkPath);
+
+      expect(utils.exists(dirPath), isTrue, reason: '$dirPath does not exist');
+      expect(utils.exists(linkPath), isFalse, reason: '$linkPath exists');
+    }
+  });
+
+  test('link to file', () {
+    final filePath = p.join(tmp, 'file');
+    final linkPath = p.join(tmp, 'link');
+    utils.createTextFile(filePath, 'Hello World!');
+    io.Link(linkPath).createSync(filePath);
+
+    fileSystem.removeFile(linkPath);
+
+    expect(utils.exists(filePath), isTrue, reason: '$filePath does not exist');
+    expect(utils.exists(linkPath), isFalse, reason: '$linkPath exists');
+  });
+
+  test('path does not exist', () {
+    final path = '$tmp/file';
+
+    expect(
+      () => fileSystem.removeFile(path),
+      throwsA(
+        isA<PathNotFoundException>().having(
+          (e) => e.errorCode,
+          'errorCode',
+          fileSystem is WindowsFileSystem
+              ? win32.ERROR_FILE_NOT_FOUND
+              : errors.enoent,
+        ),
+      ),
+    );
+  });
+}
+
+void main() {
+  group('removeFile', () {
+    group('dart:io verification', () => tests(fileUtils(), fileSystem));
+    group(
+      'self verification',
+      () => tests(FileSystemFileUtils(fileSystem), fileSystem),
+    );
+  });
+}
diff --git a/pkgs/io_file/test/test_utils.dart b/pkgs/io_file/test/test_utils.dart
@@ -27,6 +27,7 @@ abstract interface class FileUtils {
   String createTestDirectory(String testName);
   void deleteDirectoryTree(String path);
 
+  bool exists(String path);
   bool isDirectory(String path);
 
   void createDirectory(String path);
