From fafa9a21a455811b2e824cca7f078d36f0eb4be3 Mon Sep 17 00:00:00 2001
From: Jason Held <jasonsheld@gmail.com>
Date: Fri, 6 Mar 2026 08:58:10 -0500
Subject: [PATCH] Rename subDir to dir in initFlutter, treat as relative or
 absolute

---
 hive_flutter/lib/src/hive_extensions.dart | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/hive_flutter/lib/src/hive_extensions.dart b/hive_flutter/lib/src/hive_extensions.dart
index d11776db..4fc6a618 100644
--- a/hive_flutter/lib/src/hive_extensions.dart
+++ b/hive_flutter/lib/src/hive_extensions.dart
@@ -6,15 +6,15 @@ import 'package:hive_ce_flutter/src/wrapper/path.dart' as path_helper;
 
 /// Flutter extensions for Hive.
 extension HiveX on HiveInterface {
-  /// Initializes Hive with the path from [getApplicationDocumentsDirectory].
+  /// Initializes Hive with the path from [getApplicationDocumentsDirectory], or as an absolute path.
   ///
-  /// You can provide a [subDir] where the boxes should be stored.
+  /// You can provide a [dir] where the boxes should be stored.
   ///
   /// Also registers the flutter type adapters
   /// - [colorAdapterTypeId] - The type id for the color adapter (default: 200)
   /// - [timeOfDayAdapterTypeId] - The type id for the time of day adapter (default: 201)
   Future<void> initFlutter([
-    String? subDir,
+    String? dir,
     HiveStorageBackendPreference backendPreference =
         HiveStorageBackendPreference.native,
     int? colorAdapterTypeId,
@@ -24,8 +24,18 @@ extension HiveX on HiveInterface {
 
     String? path;
     if (!kIsWeb) {
-      final appDir = await getApplicationDocumentsDirectory();
-      path = path_helper.join(appDir.path, subDir);
+      // join accepts the latter arguments as nullable so it is safe
+      // to consider it "relative" even in that case. If the user wants an
+      // absolute path pointing to the base of a well-defined
+      // path (including one with built-in dart support),
+      // different from getApplicationDocumentsDirectory,
+      // then they should pass that directory in.
+      if (dir == null || path_helper.isRelative(dir)) {
+        final appDir = await getApplicationDocumentsDirectory();
+        path = path_helper.join(appDir.path, dir);
+      } else {
+        path = dir;
+      }
     }
 
     init(