@photostructure/fs-metadata 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -14,6 +14,18 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 1.3.0 - 2026-03-26
+
+### Added
+
+- New optional `mountPoints` field on `Options`: pass pre-fetched mount points to `getMountPointForPath()` and `getVolumeMetadataForPath()` to avoid redundant system queries when resolving multiple paths. Obtain via `getVolumeMountPoints({ includeSystemVolumes: true })`.
+
+## 1.2.0 - 2026-03-26
+
+### Added
+
+- New `getMountPointForPath(pathname)` function: a lightweight alternative to `getVolumeMetadataForPath()` that returns only the mount point string without fetching full volume metadata (size, UUID, label, etc.). On macOS, uses a single `fstatfs()` call — no DiskArbitration, IOKit, or space calculations. On Linux/Windows, uses the same device-ID matching logic. Handles symlinks and APFS firmlinks correctly.
+
 ## 1.1.0 - 2026-03-16
 
 ### Added

package/binding.gyp

@@ -171,6 +171,7 @@
           "OS=='mac'",
           {
             "sources": [
+              "src/darwin/get_mount_point.cpp",
               "src/darwin/volume_mount_points.cpp",
               "src/darwin/volume_metadata.cpp",
               "src/darwin/hidden.cpp"

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   VolumeHealthStatuses: () => VolumeHealthStatuses,
   getAllVolumeMetadata: () => getAllVolumeMetadata,
   getHiddenMetadata: () => getHiddenMetadata,
+  getMountPointForPath: () => getMountPointForPath,
   getTimeoutMsDefault: () => getTimeoutMsDefault,
   getVolumeMetadata: () => getVolumeMetadata,
   getVolumeMetadataForPath: () => getVolumeMetadataForPath,
@@ -630,6 +631,74 @@ async function setHiddenImpl(pathname, hide, method, nativeFn2) {
   return { pathname: norm, actions };
 }
 
+// src/mount_point_for_path.ts
+var import_promises6 = require("fs/promises");
+var import_node_path7 = require("path");
+
+// src/volume_metadata.ts
+var import_promises5 = require("fs/promises");
+var import_node_path6 = require("path");
+
+// src/linux/dev_disk.ts
+var import_promises3 = require("fs/promises");
+var import_node_path5 = require("path");
+async function getUuidFromDevDisk(devicePath) {
+  try {
+    const result = await getBasenameLinkedTo(
+      "/dev/disk/by-uuid",
+      (0, import_node_path5.resolve)(devicePath)
+    );
+    debug("[getUuidFromDevDisk] result: %o", result);
+    return result;
+  } catch (error) {
+    debug("[getUuidFromDevDisk] failed: " + error);
+    return;
+  }
+}
+async function getLabelFromDevDisk(devicePath) {
+  try {
+    const result = await getBasenameLinkedTo(
+      "/dev/disk/by-label",
+      (0, import_node_path5.resolve)(devicePath)
+    );
+    debug("[getLabelFromDevDisk] result: %o", result);
+    return result;
+  } catch (error) {
+    debug("[getLabelFromDevDisk] failed: " + error);
+    return;
+  }
+}
+async function getBasenameLinkedTo(linkDir, linkPath) {
+  for await (const ea of readLinks(linkDir)) {
+    if (ea.linkTarget === linkPath) {
+      return decodeEscapeSequences(ea.dirent.name);
+    }
+  }
+  return;
+}
+async function* readLinks(directory) {
+  for (const dirent of await (0, import_promises3.readdir)(directory, { withFileTypes: true })) {
+    if (dirent.isSymbolicLink()) {
+      try {
+        const linkTarget = (0, import_node_path5.resolve)(
+          directory,
+          await (0, import_promises3.readlink)((0, import_node_path5.join)(directory, dirent.name))
+        );
+        yield { dirent, linkTarget };
+      } catch {
+      }
+    }
+  }
+}
+
+// src/linux/mount_points.ts
+var import_promises4 = require("fs/promises");
+
+// src/mount_point.ts
+function isMountPoint(obj) {
+  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
+}
+
 // src/options.ts
 var import_node_os2 = require("os");
 var import_node_process3 = require("process");
@@ -830,113 +899,6 @@ function optionsWithDefaults(overrides = {}) {
   };
 }
 
-// src/string_enum.ts
-function stringEnum(...o) {
-  const set = new Set(o);
-  const dict = {};
-  for (const key of o) {
-    dict[key] = key;
-  }
-  return {
-    ...dict,
-    values: Object.freeze([...set]),
-    size: set.size,
-    get: (s) => s != null && set.has(s) ? s : void 0
-  };
-}
-
-// src/volume_health_status.ts
-var VolumeHealthStatuses = stringEnum(
-  "healthy",
-  "timeout",
-  "inaccessible",
-  "disconnected",
-  "unknown"
-);
-async function directoryStatus(dir, timeoutMs, canReaddirImpl = canReaddir) {
-  try {
-    if (await canReaddirImpl(dir, timeoutMs)) {
-      return { status: VolumeHealthStatuses.healthy };
-    }
-  } catch (error) {
-    debug("[directoryStatus] %s: %s", dir, error);
-    let status = VolumeHealthStatuses.unknown;
-    if (error instanceof TimeoutError) {
-      status = VolumeHealthStatuses.timeout;
-    } else if (isObject(error) && error instanceof Error && "code" in error) {
-      if (error.code === "EPERM" || error.code === "EACCES") {
-        status = VolumeHealthStatuses.inaccessible;
-      }
-    }
-    return { status, error: toError(error) };
-  }
-  return { status: VolumeHealthStatuses.unknown };
-}
-
-// src/volume_metadata.ts
-var import_promises5 = require("fs/promises");
-var import_node_path6 = require("path");
-
-// src/linux/dev_disk.ts
-var import_promises3 = require("fs/promises");
-var import_node_path5 = require("path");
-async function getUuidFromDevDisk(devicePath) {
-  try {
-    const result = await getBasenameLinkedTo(
-      "/dev/disk/by-uuid",
-      (0, import_node_path5.resolve)(devicePath)
-    );
-    debug("[getUuidFromDevDisk] result: %o", result);
-    return result;
-  } catch (error) {
-    debug("[getUuidFromDevDisk] failed: " + error);
-    return;
-  }
-}
-async function getLabelFromDevDisk(devicePath) {
-  try {
-    const result = await getBasenameLinkedTo(
-      "/dev/disk/by-label",
-      (0, import_node_path5.resolve)(devicePath)
-    );
-    debug("[getLabelFromDevDisk] result: %o", result);
-    return result;
-  } catch (error) {
-    debug("[getLabelFromDevDisk] failed: " + error);
-    return;
-  }
-}
-async function getBasenameLinkedTo(linkDir, linkPath) {
-  for await (const ea of readLinks(linkDir)) {
-    if (ea.linkTarget === linkPath) {
-      return decodeEscapeSequences(ea.dirent.name);
-    }
-  }
-  return;
-}
-async function* readLinks(directory) {
-  for (const dirent of await (0, import_promises3.readdir)(directory, { withFileTypes: true })) {
-    if (dirent.isSymbolicLink()) {
-      try {
-        const linkTarget = (0, import_node_path5.resolve)(
-          directory,
-          await (0, import_promises3.readlink)((0, import_node_path5.join)(directory, dirent.name))
-        );
-        yield { dirent, linkTarget };
-      } catch {
-      }
-    }
-  }
-}
-
-// src/linux/mount_points.ts
-var import_promises4 = require("fs/promises");
-
-// src/mount_point.ts
-function isMountPoint(obj) {
-  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
-}
-
 // src/remote_info.ts
 function isRemoteInfo(obj) {
   if (!isObject(obj)) return false;
@@ -1318,6 +1280,49 @@ function extractUUID(uuid) {
   return toS(uuid).match(uuidRegex)?.[0];
 }
 
+// src/string_enum.ts
+function stringEnum(...o) {
+  const set = new Set(o);
+  const dict = {};
+  for (const key of o) {
+    dict[key] = key;
+  }
+  return {
+    ...dict,
+    values: Object.freeze([...set]),
+    size: set.size,
+    get: (s) => s != null && set.has(s) ? s : void 0
+  };
+}
+
+// src/volume_health_status.ts
+var VolumeHealthStatuses = stringEnum(
+  "healthy",
+  "timeout",
+  "inaccessible",
+  "disconnected",
+  "unknown"
+);
+async function directoryStatus(dir, timeoutMs, canReaddirImpl = canReaddir) {
+  try {
+    if (await canReaddirImpl(dir, timeoutMs)) {
+      return { status: VolumeHealthStatuses.healthy };
+    }
+  } catch (error) {
+    debug("[directoryStatus] %s: %s", dir, error);
+    let status = VolumeHealthStatuses.unknown;
+    if (error instanceof TimeoutError) {
+      status = VolumeHealthStatuses.timeout;
+    } else if (isObject(error) && error instanceof Error && "code" in error) {
+      if (error.code === "EPERM" || error.code === "EACCES") {
+        status = VolumeHealthStatuses.inaccessible;
+      }
+    }
+    return { status, error: toError(error) };
+  }
+  return { status: VolumeHealthStatuses.unknown };
+}
+
 // src/array.ts
 function uniqBy(arr, keyFn) {
   const seen = /* @__PURE__ */ new Set();
@@ -1487,22 +1492,31 @@ async function getVolumeMetadataForPathImpl(pathname, opts, nativeFn2) {
       nativeFn2
     );
   }
+  const mountPoint = await findMountPointByDeviceId(
+    resolved,
+    resolvedStat,
+    opts,
+    nativeFn2
+  );
+  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn2);
+}
+async function findMountPointByDeviceId(resolved, resolvedStat, opts, nativeFn2) {
   const targetDev = resolvedStat.dev;
-  const mountPoints = await getVolumeMountPointsImpl(
+  const mountPoints = opts.mountPoints ?? await getVolumeMountPointsImpl(
     { ...opts, includeSystemVolumes: true },
     nativeFn2
   );
   const prefixMatches = [];
   const deviceMatches = [];
   await Promise.all(
-    mountPoints.map(async ({ mountPoint: mountPoint2 }) => {
+    mountPoints.map(async ({ mountPoint }) => {
       try {
-        const mpDev = (await statAsync(mountPoint2)).dev;
+        const mpDev = (await statAsync(mountPoint)).dev;
         if (mpDev !== targetDev) return;
-        if (isAncestorOrSelf(mountPoint2, resolved)) {
-          prefixMatches.push(mountPoint2);
+        if (isAncestorOrSelf(mountPoint, resolved)) {
+          prefixMatches.push(mountPoint);
         } else {
-          deviceMatches.push(mountPoint2);
+          deviceMatches.push(mountPoint);
         }
       } catch {
       }
@@ -1511,13 +1525,10 @@ async function getVolumeMetadataForPathImpl(pathname, opts, nativeFn2) {
   const candidates = prefixMatches.length > 0 ? prefixMatches : deviceMatches;
   if (candidates.length === 0) {
     throw new Error(
-      "No mount point found for path: " + JSON.stringify(pathname)
+      "No mount point found for path: " + JSON.stringify(resolved)
     );
   }
-  const mountPoint = candidates.reduce(
-    (a, b) => a.length >= b.length ? a : b
-  );
-  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn2);
+  return candidates.reduce((a, b) => a.length >= b.length ? a : b);
 }
 async function getAllVolumeMetadataImpl(opts, nativeFn2) {
   const o = optionsWithDefaults(opts);
@@ -1570,15 +1581,44 @@ async function getAllVolumeMetadataImpl(opts, nativeFn2) {
   );
 }
 
+// src/mount_point_for_path.ts
+async function getMountPointForPathImpl(pathname, opts, nativeFn2) {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+  const resolved = await (0, import_promises6.realpath)(pathname);
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : (0, import_node_path7.dirname)(resolved);
+  if (isMacOS) {
+    const native = await nativeFn2();
+    if (native.getMountPoint) {
+      debug("[getMountPointForPath] using native getMountPoint for %s", dir);
+      const p = native.getMountPoint(dir);
+      const mountPoint = await withTimeout({
+        desc: "getMountPoint()",
+        timeoutMs: opts.timeoutMs,
+        promise: p
+      });
+      if (isNotBlank(mountPoint)) {
+        debug("[getMountPointForPath] resolved to %s", mountPoint);
+        return mountPoint;
+      }
+    }
+    throw new Error("getMountPoint native function unavailable");
+  }
+  debug("[getMountPointForPath] using device matching for %s", resolved);
+  return findMountPointByDeviceId(resolved, resolvedStat, opts, nativeFn2);
+}
+
 // src/index.ts
 var nativeFn = defer2(async () => {
   const start = Date.now();
   try {
-    const dirname5 = _dirname();
-    const dir = await findAncestorDir(dirname5, "binding.gyp");
+    const dirname6 = _dirname();
+    const dir = await findAncestorDir(dirname6, "binding.gyp");
     if (dir == null) {
       throw new Error(
-        "Could not find bindings.gyp in any ancestor directory of " + dirname5
+        "Could not find bindings.gyp in any ancestor directory of " + dirname6
       );
     }
     const bindings = (0, import_node_gyp_build.default)(dir);
@@ -1608,6 +1648,13 @@ function getVolumeMetadataForPath(pathname, opts) {
     nativeFn
   );
 }
+function getMountPointForPath(pathname, opts) {
+  return getMountPointForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn
+  );
+}
 function getAllVolumeMetadata(opts) {
   return getAllVolumeMetadataImpl(optionsWithDefaults(opts), nativeFn);
 }
@@ -1635,6 +1682,7 @@ function setHidden(pathname, hidden, method = "auto") {
   VolumeHealthStatuses,
   getAllVolumeMetadata,
   getHiddenMetadata,
+  getMountPointForPath,
   getTimeoutMsDefault,
   getVolumeMetadata,
   getVolumeMetadataForPath,