Add the ability to create directories (#215)

Author: brianquinlan

pkgs/io_file/README.md

@@ -12,7 +12,7 @@ See
 | :---                  |  :---:  | :---: | :---: | :---: | :----:  | :--------: | :----------: | 
 |  canonicalize path    |         |       |       |       |         |            |              |
 |  copy file            |         |       |       |       |         |            |              |
-|  create directory     |         |       |       |       |         |            |              |
+|  create directory     |         |   ✓   |   ✓   |   ✓   |    ✓    |            |              |
 |  create hard link     |         |       |       |       |         |            |              |
 |  create symbolic link |         |       |       |       |         |            |              |
 |  create tmp directory |         |       |       |       |         |            |              |

pkgs/io_file/lib/src/file_system.dart

@@ -4,6 +4,10 @@
 
 import 'dart:typed_data';
 
+// TODO(brianquinlan): When we switch to using exception types outside of
+// `dart:io` then change the doc strings to use reference syntax rather than
+// code syntax e.g. `PathExistsException` => [PathExistsException].
+
 /// The modes in which a File can be written.
 class WriteMode {
   /// Open the file for writing such that data can only be appended to the end
@@ -30,6 +34,15 @@ class WriteMode {
 
 /// An abstract representation of a file system.
 base class FileSystem {
+  /// Create a directory at the given path.
+  ///
+  /// If the directory already exists, then `PathExistsException` is thrown.
+  ///
+  /// If the parent path does not exist, then `PathNotFoundException` is thrown.
+  void createDirectory(String path) {
+    throw UnsupportedError('createDirectory');
+  }
+
   /// Renames, and possibly moves a file system object from one path to another.
   ///
   /// If `newPath` is a relative path, it is resolved against the current

pkgs/io_file/lib/src/vm_posix_file_system.dart

@@ -16,6 +16,9 @@ import 'internal_constants.dart';
 /// The default `mode` to use with `open` calls that may create a file.
 const _defaultMode = 438; // => 0666 => rw-rw-rw-
 
+/// The default `mode` to use when creating a directory.
+const _defaultDirectoryMode = 511; // => 0777 => rwxrwxrwx
+
 Exception _getError(int errno, String message, String path) {
   //TODO(brianquinlan): In the long-term, do we need to avoid exceptions that
   // are part of `dart:io`? Can we move those exceptions into a different
@@ -57,6 +60,14 @@ external int write(int fd, Pointer<Uint8> buf, int count);
 /// A [FileSystem] implementation for POSIX systems (e.g. Android, iOS, Linux,
 /// macOS).
 base class PosixFileSystem extends FileSystem {
+  @override
+  void createDirectory(String path) {
+    if (stdlibc.mkdir(path, _defaultDirectoryMode) == -1) {
+      final errno = stdlibc.errno;
+      throw _getError(errno, 'create directory failed', path);
+    }
+  }
+
   @override
   void rename(String oldPath, String newPath) {
     // See https://pubs.opengroup.org/onlinepubs/000095399/functions/rename.html

pkgs/io_file/lib/src/vm_windows_file_system.dart

@@ -68,6 +68,18 @@ Exception _getError(int errorCode, String message, String path) {
 
 /// A [FileSystem] implementation for Windows systems.
 base class WindowsFileSystem extends FileSystem {
+  @override
+  void createDirectory(String path) => using((arena) {
+    // Calling `GetLastError` for the first time causes the `GetLastError`
+    // symbol to be loaded, which resets `GetLastError`. So make a harmless
+    // call before the value is needed.
+    win32.GetLastError();
+    if (win32.CreateDirectory(path.toNativeUtf16(), nullptr) == win32.FALSE) {
+      final errorCode = win32.GetLastError();
+      throw _getError(errorCode, 'create directory failed', path);
+    }
+  });
+
   @override
   void rename(String oldPath, String newPath) => using((arena) {
     // Calling `GetLastError` for the first time causes the `GetLastError`

pkgs/io_file/test/create_directory_test.dart

@@ -0,0 +1,93 @@
+// 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';
+
+import 'package:io_file/io_file.dart';
+import 'package:stdlibc/stdlibc.dart' as stdlibc;
+import 'package:test/test.dart';
+import 'package:win32/win32.dart' as win32;
+
+import 'test_utils.dart';
+
+void main() {
+  group('createDirectory', () {
+    late String tmp;
+
+    setUp(() => tmp = createTemp('createDirectory'));
+
+    tearDown(() => deleteTemp(tmp));
+
+    //TODO(brianquinlan): test with a very long path.
+
+    test('success', () {
+      final path = '$tmp/dir';
+
+      fileSystem.createDirectory(path);
+      expect(FileSystemEntity.isDirectorySync(path), isTrue);
+    });
+
+    test('create in non-existent directory', () {
+      final path = '$tmp/foo/dir';
+
+      expect(
+        () => fileSystem.createDirectory(path),
+        throwsA(
+          isA<PathNotFoundException>()
+              .having((e) => e.message, 'message', 'create directory failed')
+              .having(
+                (e) => e.osError?.errorCode,
+                'errorCode',
+                Platform.isWindows
+                    ? win32.ERROR_PATH_NOT_FOUND
+                    : stdlibc.ENOENT,
+              ),
+        ),
+      );
+    });
+
+    test('create over existing directory', () {
+      final path = '$tmp/dir';
+      Directory(path).createSync();
+
+      expect(
+        () => fileSystem.createDirectory(path),
+        throwsA(
+          isA<PathExistsException>()
+              .having((e) => e.message, 'message', 'create directory failed')
+              .having(
+                (e) => e.osError?.errorCode,
+                'errorCode',
+                Platform.isWindows
+                    ? win32.ERROR_ALREADY_EXISTS
+                    : stdlibc.EEXIST,
+              ),
+        ),
+      );
+    });
+
+    test('create over existing file', () {
+      final path = '$tmp/file';
+      File(path).createSync();
+
+      expect(
+        () => fileSystem.createDirectory(path),
+        throwsA(
+          isA<PathExistsException>()
+              .having((e) => e.message, 'message', 'create directory failed')
+              .having(
+                (e) => e.osError?.errorCode,
+                'errorCode',
+                Platform.isWindows
+                    ? win32.ERROR_ALREADY_EXISTS
+                    : stdlibc.EEXIST,
+              ),
+        ),
+      );
+    });
+  });
+}