@photostructure/fs-metadata 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -368,6 +368,22 @@ declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Optio
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
+/**
+ * Get the mount point path for an arbitrary file or directory path.
+ *
+ * This is a lightweight alternative to {@link getVolumeMetadataForPath} when
+ * you only need the mount point string. On macOS it uses a single fstatfs()
+ * call (no DiskArbitration, IOKit, or space calculations). On Linux/Windows
+ * it uses device ID matching against the mount table.
+ *
+ * Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional settings (timeoutMs, linuxMountTablePaths)
+ * @returns The mount point path (e.g., "/", "/System/Volumes/Data", "C:\\")
+ */
+declare function getMountPointForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<string>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -429,4 +445,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getMountPointForPath, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.d.mts

@@ -368,6 +368,22 @@ declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Optio
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
+/**
+ * Get the mount point path for an arbitrary file or directory path.
+ *
+ * This is a lightweight alternative to {@link getVolumeMetadataForPath} when
+ * you only need the mount point string. On macOS it uses a single fstatfs()
+ * call (no DiskArbitration, IOKit, or space calculations). On Linux/Windows
+ * it uses device ID matching against the mount table.
+ *
+ * Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional settings (timeoutMs, linuxMountTablePaths)
+ * @returns The mount point path (e.g., "/", "/System/Volumes/Data", "C:\\")
+ */
+declare function getMountPointForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<string>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -429,4 +445,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getMountPointForPath, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.d.ts

@@ -368,6 +368,22 @@ declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Optio
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
+/**
+ * Get the mount point path for an arbitrary file or directory path.
+ *
+ * This is a lightweight alternative to {@link getVolumeMetadataForPath} when
+ * you only need the mount point string. On macOS it uses a single fstatfs()
+ * call (no DiskArbitration, IOKit, or space calculations). On Linux/Windows
+ * it uses device ID matching against the mount table.
+ *
+ * Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional settings (timeoutMs, linuxMountTablePaths)
+ * @returns The mount point path (e.g., "/", "/System/Volumes/Data", "C:\\")
+ */
+declare function getMountPointForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<string>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -429,4 +445,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getMountPointForPath, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.mjs

@@ -586,6 +586,74 @@ async function setHiddenImpl(pathname, hide, method, nativeFn2) {
   return { pathname: norm, actions };
 }
 
+// src/mount_point_for_path.ts
+import { realpath as realpath2 } from "fs/promises";
+import { dirname as dirname5 } from "path";
+
+// src/volume_metadata.ts
+import { realpath } from "fs/promises";
+import { dirname as dirname4 } from "path";
+
+// src/linux/dev_disk.ts
+import { readdir, readlink } from "fs/promises";
+import { join as join3, resolve as resolve3 } from "path";
+async function getUuidFromDevDisk(devicePath) {
+  try {
+    const result = await getBasenameLinkedTo(
+      "/dev/disk/by-uuid",
+      resolve3(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",
+      resolve3(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 readdir(directory, { withFileTypes: true })) {
+    if (dirent.isSymbolicLink()) {
+      try {
+        const linkTarget = resolve3(
+          directory,
+          await readlink(join3(directory, dirent.name))
+        );
+        yield { dirent, linkTarget };
+      } catch {
+      }
+    }
+  }
+}
+
+// src/linux/mount_points.ts
+import { readFile } from "fs/promises";
+
+// src/mount_point.ts
+function isMountPoint(obj) {
+  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
+}
+
 // src/options.ts
 import { availableParallelism as availableParallelism2 } from "os";
 import { env as env2 } from "process";
@@ -786,113 +854,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
-import { realpath } from "fs/promises";
-import { dirname as dirname4 } from "path";
-
-// src/linux/dev_disk.ts
-import { readdir, readlink } from "fs/promises";
-import { join as join3, resolve as resolve3 } from "path";
-async function getUuidFromDevDisk(devicePath) {
-  try {
-    const result = await getBasenameLinkedTo(
-      "/dev/disk/by-uuid",
-      resolve3(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",
-      resolve3(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 readdir(directory, { withFileTypes: true })) {
-    if (dirent.isSymbolicLink()) {
-      try {
-        const linkTarget = resolve3(
-          directory,
-          await readlink(join3(directory, dirent.name))
-        );
-        yield { dirent, linkTarget };
-      } catch {
-      }
-    }
-  }
-}
-
-// src/linux/mount_points.ts
-import { readFile } from "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;
@@ -1274,6 +1235,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();
@@ -1443,6 +1447,15 @@ 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(
     { ...opts, includeSystemVolumes: true },
@@ -1451,14 +1464,14 @@ async function getVolumeMetadataForPathImpl(pathname, opts, 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 {
       }
@@ -1467,13 +1480,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);
@@ -1526,15 +1536,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 realpath2(pathname);
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : dirname5(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 = NodeGypBuild(dir);
@@ -1564,6 +1603,13 @@ function getVolumeMetadataForPath(pathname, opts) {
     nativeFn
   );
 }
+function getMountPointForPath(pathname, opts) {
+  return getMountPointForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn
+  );
+}
 function getAllVolumeMetadata(opts) {
   return getAllVolumeMetadataImpl(optionsWithDefaults(opts), nativeFn);
 }
@@ -1590,6 +1636,7 @@ export {
   VolumeHealthStatuses,
   getAllVolumeMetadata,
   getHiddenMetadata,
+  getMountPointForPath,
   getTimeoutMsDefault,
   getVolumeMetadata,
   getVolumeMetadataForPath,