@photostructure/fs-metadata 1.0.1 → 1.2.0

package/dist/index.d.cts

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,33 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @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.
@@ -393,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, 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

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,33 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @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.
@@ -393,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, 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

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,33 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @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.
@@ -393,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, 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 };