@photostructure/fs-metadata 0.3.2 → 0.3.3

package/dist/types/hidden.d.ts

@@ -1,44 +1,7 @@
+import type { HiddenMetadata } from "./types/hidden_metadata.js";
 import type { NativeBindingsFn } from "./types/native_bindings.js";
-/**
- * Represents the detailed state of a file or directory's hidden attribute
- */
-export interface HiddenMetadata {
-    /**
-     * Whether the item is considered hidden by any method
-     */
-    hidden: boolean;
-    /**
-     * Whether the item has a dot prefix (POSIX-style hidden). Windows doesn't
-     * care about dot prefixes.
-     */
-    dotPrefix: boolean;
-    /**
-     * Whether the item has system hidden flags set, like via `chflags` on macOS
-     * or on Windows via `GetFileAttributesW`
-     */
-    systemFlag: boolean;
-    /**
-     * Indicates which hiding methods are supported on the current platform
-     */
-    supported: {
-        /**
-         * Whether dot prefix hiding is supported on the current operating system
-         */
-        dotPrefix: boolean;
-        /**
-         * Whether system flag hiding is supported
-         */
-        systemFlag: boolean;
-    };
-}
 export declare const LocalSupport: {
-    /**
-     * Whether dot prefix hiding is supported on the current operating system
-     */
     dotPrefix: boolean;
-    /**
-     * Whether system flag hiding is supported
-     */
     systemFlag: boolean;
 };
 /**
@@ -46,15 +9,15 @@ export declare const LocalSupport: {
  * @returns A boolean indicating if the item is hidden
  * @throws {Error} If the file doesn't exist or permissions are insufficient
  */
-export declare function isHidden(pathname: string, nativeFn: NativeBindingsFn): Promise<boolean>;
-export declare function isHiddenRecursive(path: string, nativeFn: NativeBindingsFn): Promise<boolean>;
+export declare function isHiddenImpl(pathname: string, nativeFn: NativeBindingsFn): Promise<boolean>;
+export declare function isHiddenRecursiveImpl(path: string, nativeFn: NativeBindingsFn): Promise<boolean>;
 export declare function createHiddenPosixPath(pathname: string, hidden: boolean): string;
 /**
  * Gets detailed information about the hidden state of the file or directory
  * @returns An object containing detailed hidden state information
  * @throws {Error} If the file doesn't exist or permissions are insufficient
  */
-export declare function getHiddenMetadata(pathname: string, nativeFn: NativeBindingsFn): Promise<HiddenMetadata>;
+export declare function getHiddenMetadataImpl(pathname: string, nativeFn: NativeBindingsFn): Promise<HiddenMetadata>;
 export type HideMethod = "dotPrefix" | "systemFlag" | "all" | "auto";
 export type SetHiddenResult = {
     pathname: string;
@@ -63,4 +26,4 @@ export type SetHiddenResult = {
         systemFlag: boolean;
     };
 };
-export declare function setHidden(pathname: string, hide: boolean, method: HideMethod, nativeFn: NativeBindingsFn): Promise<SetHiddenResult>;
+export declare function setHiddenImpl(pathname: string, hide: boolean, method: HideMethod, nativeFn: NativeBindingsFn): Promise<SetHiddenResult>;

package/dist/types/index.d.ts

@@ -1,2 +1,91 @@
-export * from "./exports.js";
-export declare const getVolumeMountPoints: typeof import("./exports.js").getVolumeMountPoints, getVolumeMetadata: typeof import("./exports.js").getVolumeMetadata, getAllVolumeMetadata: typeof import("./exports.js").getAllVolumeMetadata, isHidden: typeof import("./exports.js").isHidden, isHiddenRecursive: typeof import("./exports.js").isHiddenRecursive, getHiddenMetadata: typeof import("./exports.js").getHiddenMetadata, setHidden: typeof import("./exports.js").setHidden;
+import type { HideMethod, SetHiddenResult } from "./hidden.js";
+import { IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, OptionsDefault, optionsWithDefaults, SystemFsTypesDefault, SystemPathPatternsDefault, TimeoutMsDefault } from "./options.js";
+import type { StringEnum, StringEnumKeys, StringEnumType } from "./string_enum.js";
+import type { SystemVolumeConfig } from "./system_volume.js";
+import type { HiddenMetadata } from "./types/hidden_metadata.js";
+import type { MountPoint } from "./types/mount_point.js";
+import type { Options } from "./types/options.js";
+import type { VolumeMetadata } from "./types/volume_metadata.js";
+import type { VolumeHealthStatus } from "./volume_health_status.js";
+import { VolumeHealthStatuses } from "./volume_health_status.js";
+import type { GetVolumeMountPointOptions } from "./volume_mount_points.js";
+export type { GetVolumeMountPointOptions, HiddenMetadata, HideMethod, MountPoint, Options, SetHiddenResult, StringEnum, StringEnumKeys, StringEnumType, SystemVolumeConfig, VolumeHealthStatus, VolumeMetadata, };
+/**
+ * List all active local and remote mount points on the system.
+ *
+ * Only readable directories are included in the results.
+ *
+ * Note that on Windows, `timeoutMs` will be used **per system call** and not
+ * for the entire operation.
+ *
+ * @param opts Optional filesystem operation settings to override default values
+ */
+export declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>): Promise<MountPoint[]>;
+/**
+ * Get metadata for the volume at the given mount point.
+ *
+ * @param mountPoint Must be a non-blank string
+ * @param opts Optional filesystem operation settings
+ */
+export declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Retrieves metadata for all mounted volumes with optional filtering and
+ * concurrency control.
+ *
+ * @param opts - Optional configuration object
+ * @param opts.includeSystemVolumes - If true, includes system volumes in the
+ * results. Defaults to true on Windows and false elsewhere.
+ * @param opts.maxConcurrency - Maximum number of concurrent operations.
+ * Defaults to the system's available parallelism: see
+ * {@link https://nodejs.org/api/os.html#osavailableparallelism | os.availableParallelism()}
+ * @param opts.timeoutMs - Maximum time to wait for
+ * {@link getVolumeMountPointsImpl}, as well as **each** {@link getVolumeMetadataImpl}
+ * to complete. Defaults to {@link TimeoutMsDefault}
+ * @returns Promise that resolves to an array of either VolumeMetadata objects
+ * or error objects containing the mount point and error
+ * @throws Never - errors are caught and returned as part of the result array
+ */
+export declare function getAllVolumeMetadata(opts?: Partial<Options> & {
+    includeSystemVolumes?: boolean;
+}): Promise<VolumeMetadata[]>;
+/**
+ * Check if a file or directory is hidden.
+ *
+ * Note that `path` may be _effectively_ hidden if any of the ancestor
+ * directories are hidden: use {@link isHiddenRecursive} to check for this.
+ *
+ * @param pathname Path to file or directory
+ * @returns Promise resolving to boolean indicating hidden state
+ */
+export declare function isHidden(pathname: string): Promise<boolean>;
+/**
+ * Check if a file or directory is hidden, or if any of its ancestor
+ * directories are hidden.
+ *
+ * @param pathname Path to file or directory
+ * @returns Promise resolving to boolean indicating hidden state
+ */
+export declare function isHiddenRecursive(pathname: string): Promise<boolean>;
+/**
+ * Get detailed metadata about the hidden state of a file or directory.
+ *
+ * @param pathname Path to file or directory
+ * @returns Promise resolving to metadata about the hidden state
+ */
+export declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
+/**
+ * Set the hidden state of a file or directory
+ *
+ * @param pathname Path to file or directory
+ * @param hidden - Whether the item should be hidden (true) or visible (false)
+ * @param method Method to use for hiding the file or directory. The default
+ * is "auto", which is "dotPrefix" on Linux and macOS, and "systemFlag" on
+ * Windows. "all" will attempt to use all relevant methods for the current
+ * operating system.
+ * @returns Promise resolving the final name of the file or directory (as it
+ * will change on POSIX systems), and the action(s) taken.
+ * @throws {Error} If the file doesn't exist, permissions are insufficient, or
+ * the requested method is unsupported
+ */
+export declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
+export { IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, OptionsDefault, optionsWithDefaults, SystemFsTypesDefault, SystemPathPatternsDefault, TimeoutMsDefault, VolumeHealthStatuses, };

package/dist/types/linux/mount_points.d.ts

@@ -1,6 +1,6 @@
-import { type MountPoint } from "../mount_point.js";
-import { type Options } from "../options.js";
+import { type MountPoint } from "../types/mount_point.js";
 import type { NativeBindingsFn } from "../types/native_bindings.js";
+import type { Options } from "../types/options.js";
 import { MountEntry } from "./mtab.js";
 export declare function getLinuxMountPoints(native: NativeBindingsFn, opts?: Pick<Options, "linuxMountTablePaths">): Promise<MountPoint[]>;
 export declare function getLinuxMtabMetadata(mountPoint: string, opts?: Pick<Options, "linuxMountTablePaths">): Promise<MountEntry>;

package/dist/types/linux/mtab.d.ts

@@ -1,6 +1,6 @@
-import { MountPoint } from "../mount_point.js";
 import { SystemVolumeConfig } from "../system_volume.js";
-import { VolumeMetadata } from "../volume_metadata.js";
+import type { MountPoint } from "../types/mount_point.js";
+import type { VolumeMetadata } from "../types/volume_metadata.js";
 /**
  * Represents an entry in the mount table.
  */

package/dist/types/mount_point.d.ts

@@ -1,47 +1,2 @@
-import { VolumeHealthStatus } from "./volume_health_status";
-/**
- * A mount point is a location in the file system where a volume is mounted.
- *
- * @see https://en.wikipedia.org/wiki/Mount_(computing)
- */
-export interface MountPoint {
-    /**
-     * Mount location (like "/" or "C:\").
-     */
-    mountPoint: string;
-    /**
-     * The type of file system on the volume, like `ext4`, `apfs`, or `ntfs`.
-     *
-     * Note: on Windows this may show as "ntfs" for remote filesystems, as that
-     * is how the filesystem is presented to the OS.
-     */
-    fstype?: string;
-    /**
-     * On Windows, returns the health status of the volume.
-     *
-     * Note that this is only available on Windows, as both Linux and macOS  are
-     * prohibitively expensive, requiring forking `fsck -N` or `diskutil
-     * verifyVolume`.
-     *
-     * If there are non-critical errors while extracting metadata, those error
-     * messages may be added to this field (say, from blkid or gio).
-     *
-     * @see {@link VolumeHealthStatuses} for values returned by Windows.
-     */
-    status?: VolumeHealthStatus | string;
-    /**
-     * 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.
-     *
-     * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
-     */
-    isSystemVolume?: boolean;
-    /**
-     * If there are non-critical errors while extracting metadata, those errors
-     * may be added to this field.
-     */
-    error?: Error | string;
-}
+import { MountPoint } from "./types/mount_point";
 export declare function isMountPoint(obj: unknown): obj is MountPoint;

package/dist/types/options.d.ts

@@ -1,50 +1,4 @@
-/**
- * Configuration options for filesystem operations.
- *
- * @see {@link optionsWithDefaults} for creating an options object with default values
- * @see {@link OptionsDefault} for the default values
- */
-export interface Options {
-    /**
-     * Timeout in milliseconds for filesystem operations.
-     *
-     * Disable timeouts by setting this to 0.
-     *
-     * @see {@link TimeoutMsDefault}.
-     */
-    timeoutMs: number;
-    /**
-     * Maximum number of concurrent filesystem operations.
-     *
-     * Defaults to {@link https://nodejs.org/api/os.html#osavailableparallelism | availableParallelism}.
-     */
-    maxConcurrency: number;
-    /**
-     * On Linux and macOS, mount point pathnames that matches any of these glob
-     * patterns will have {@link MountPoint.isSystemVolume} set to true.
-     *
-     * @see {@link SystemPathPatternsDefault} for the default value
-     */
-    systemPathPatterns: string[];
-    /**
-     * On Linux and macOS, volumes whose filesystem matches any of these strings
-     * will have {@link MountPoint.isSystemVolume} set to true.
-     *
-     * @see {@link SystemFsTypesDefault} for the default value
-     */
-    systemFsTypes: string[];
-    /**
-     * On Linux, use the first mount point table in this array that is readable.
-     *
-     * @see {@link LinuxMountTablePathsDefault} for the default values
-     */
-    linuxMountTablePaths: string[];
-    /**
-     * Should system volumes be included in result arrays? Defaults to true on
-     * Windows and false elsewhere.
-     */
-    includeSystemVolumes: boolean;
-}
+import type { Options } from "./types/options.js";
 /**
  * Default timeout in milliseconds for {@link Options.timeoutMs}.
  *

package/dist/types/platform.d.ts

@@ -1,3 +1,4 @@
 export declare const isLinux: boolean;
 export declare const isWindows: boolean;
 export declare const isMacOS: boolean;
+export declare const isArm: boolean;

package/dist/types/remote_info.d.ts

@@ -1,38 +1,6 @@
-/**
- * Represents remote filesystem information.
- */
-export interface RemoteInfo {
-    /**
-     * We can sometimes fetch a URI of the resource (like "smb://server/share" or
-     * "file:///media/user/usb")
-     */
-    uri?: string;
-    /**
-     * Protocol used to access the share.
-     */
-    protocol?: string;
-    /**
-     * Does the protocol seem to be a remote filesystem?
-     */
-    remote: boolean;
-    /**
-     * If remote, may include the username used to access the share.
-     *
-     * This will be undefined on NFS and other remote filesystem types that do
-     * authentication out of band.
-     */
-    remoteUser?: string;
-    /**
-     * If remote, the ip or hostname hosting the share (like "rusty" or "10.1.1.3")
-     */
-    remoteHost?: string;
-    /**
-     * If remote, the name of the share (like "homes")
-     */
-    remoteShare?: string;
-}
+import { RemoteInfo } from "./types/remote_info.js";
 export declare function isRemoteInfo(obj: unknown): obj is RemoteInfo;
-export declare function normalizeProtocol(protocol: string): string;
+export declare function normalizeFsType(fstype: string): string;
 export declare function isRemoteFsType(fstype: string | undefined): boolean;
 export declare function parseURL(s: string): URL | undefined;
 export declare function extractRemoteInfo(fsSpec: string | undefined): RemoteInfo | undefined;

package/dist/types/stack_path.d.ts

@@ -0,0 +1,2 @@
+export declare function getCallerDirname(): string;
+export declare function extractCallerPath(stack: string): string;

package/dist/types/system_volume.d.ts

@@ -1,5 +1,5 @@
-import { MountPoint } from "./mount_point.js";
-import { Options } from "./options.js";
+import type { MountPoint } from "./types/mount_point.js";
+import type { Options } from "./types/options.js";
 /**
  * Configuration for system volume detection
  *

package/dist/types/types/hidden_metadata.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents the detailed state of a file or directory's hidden attribute
+ */
+export interface HiddenMetadata {
+    /**
+     * Whether the item is considered hidden by any method
+     */
+    hidden: boolean;
+    /**
+     * Whether the item has a dot prefix (POSIX-style hidden). Windows doesn't
+     * care about dot prefixes.
+     */
+    dotPrefix: boolean;
+    /**
+     * Whether the item has system hidden flags set, like via `chflags` on macOS
+     * or on Windows via `GetFileAttributesW`
+     */
+    systemFlag: boolean;
+    /**
+     * Indicates which hiding methods are supported on the current platform
+     */
+    supported: {
+        /**
+         * Whether dot prefix hiding is supported on the current operating system
+         */
+        dotPrefix: boolean;
+        /**
+         * Whether system flag hiding is supported
+         */
+        systemFlag: boolean;
+    };
+}

package/dist/types/types/mount_point.d.ts

@@ -0,0 +1,46 @@
+import type { VolumeHealthStatus } from "../volume_health_status";
+/**
+ * A mount point is a location in the file system where a volume is mounted.
+ *
+ * @see https://en.wikipedia.org/wiki/Mount_(computing)
+ */
+export interface MountPoint {
+    /**
+     * Mount location (like "/" or "C:\").
+     */
+    mountPoint: string;
+    /**
+     * The type of file system on the volume, like `ext4`, `apfs`, or `ntfs`.
+     *
+     * Note: on Windows this may show as "ntfs" for remote filesystems, as that
+     * is how the filesystem is presented to the OS.
+     */
+    fstype?: string;
+    /**
+     * On Windows, returns the health status of the volume.
+     *
+     * Note that this is only available on Windows, as both Linux and macOS  are
+     * prohibitively expensive, requiring forking `fsck -N` or `diskutil
+     * verifyVolume`.
+     *
+     * If there are non-critical errors while extracting metadata, those error
+     * messages may be added to this field (say, from blkid or gio).
+     *
+     * @see {@link VolumeHealthStatuses} for values returned by Windows.
+     */
+    status?: VolumeHealthStatus | string;
+    /**
+     * 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.
+     *
+     * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
+     */
+    isSystemVolume?: boolean;
+    /**
+     * If there are non-critical errors while extracting metadata, those errors
+     * may be added to this field.
+     */
+    error?: Error | string;
+}

package/dist/types/types/native_bindings.d.ts

@@ -1,6 +1,6 @@
-import { MountPoint } from "../mount_point.js";
-import type { Options } from "../options.js";
-import type { VolumeMetadata } from "../volume_metadata.js";
+import type { MountPoint } from "./mount_point.js";
+import type { Options } from "./options.js";
+import type { VolumeMetadata } from "./volume_metadata.js";
 export interface NativeBindings {
     /**
      * Enable or disable debug logging. Set automatically if the `NODE_DEBUG`

package/dist/types/types/options.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Configuration options for filesystem operations.
+ *
+ * @see {@link optionsWithDefaults} for creating an options object with default values
+ * @see {@link OptionsDefault} for the default values
+ */
+export interface Options {
+    /**
+     * Timeout in milliseconds for filesystem operations.
+     *
+     * Disable timeouts by setting this to 0.
+     *
+     * @see {@link TimeoutMsDefault}.
+     */
+    timeoutMs: number;
+    /**
+     * Maximum number of concurrent filesystem operations.
+     *
+     * Defaults to {@link https://nodejs.org/api/os.html#osavailableparallelism | availableParallelism}.
+     */
+    maxConcurrency: number;
+    /**
+     * On Linux and macOS, mount point pathnames that matches any of these glob
+     * patterns will have {@link MountPoint.isSystemVolume} set to true.
+     *
+     * @see {@link SystemPathPatternsDefault} for the default value
+     */
+    systemPathPatterns: string[];
+    /**
+     * On Linux and macOS, volumes whose filesystem matches any of these strings
+     * will have {@link MountPoint.isSystemVolume} set to true.
+     *
+     * @see {@link SystemFsTypesDefault} for the default value
+     */
+    systemFsTypes: string[];
+    /**
+     * On Linux, use the first mount point table in this array that is readable.
+     *
+     * @see {@link LinuxMountTablePathsDefault} for the default values
+     */
+    linuxMountTablePaths: string[];
+    /**
+     * Should system volumes be included in result arrays? Defaults to true on
+     * Windows and false elsewhere.
+     */
+    includeSystemVolumes: boolean;
+}

package/dist/types/types/remote_info.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Represents remote filesystem information.
+ */
+export interface RemoteInfo {
+    /**
+     * We can sometimes fetch a URI of the resource (like "smb://server/share" or
+     * "file:///media/user/usb")
+     */
+    uri?: string;
+    /**
+     * Protocol used to access the share.
+     */
+    protocol?: string;
+    /**
+     * Does the protocol seem to be a remote filesystem?
+     */
+    remote: boolean;
+    /**
+     * If remote, may include the username used to access the share.
+     *
+     * This will be undefined on NFS and other remote filesystem types that do
+     * authentication out of band.
+     */
+    remoteUser?: string;
+    /**
+     * If remote, the ip or hostname hosting the share (like "rusty" or "10.1.1.3")
+     */
+    remoteHost?: string;
+    /**
+     * If remote, the name of the share (like "homes")
+     */
+    remoteShare?: string;
+}

package/dist/types/types/volume_metadata.d.ts

@@ -0,0 +1,46 @@
+import type { MountPoint } from "./mount_point.js";
+import type { RemoteInfo } from "./remote_info.js";
+/**
+ * Metadata associated to a volume.
+ *
+ * @see https://en.wikipedia.org/wiki/Volume_(computing)
+ */
+export interface VolumeMetadata extends RemoteInfo, MountPoint {
+    /**
+     * The name of the partition
+     */
+    label?: string;
+    /**
+     * Total size in bytes
+     */
+    size?: number;
+    /**
+     * Used size in bytes
+     */
+    used?: number;
+    /**
+     * Available size in bytes
+     */
+    available?: number;
+    /**
+     * Path to the device or service that the mountpoint is from.
+     *
+     * Examples include `/dev/sda1`, `nfs-server:/export`,
+     * `//username@remoteHost/remoteShare`, or `//cifs-server/share`.
+     *
+     * May be undefined for remote volumes.
+     */
+    mountFrom?: string;
+    /**
+     * The name of the mount. This may match the resolved mountPoint.
+     */
+    mountName?: string;
+    /**
+     * UUID for the volume, like "c9b08f6e-b392-11ef-bf19-4b13bb7db4b4".
+     *
+     * On windows, this _may_ be the 128-bit volume UUID, but if that is not
+     * available, like in the case of remote volumes, we fallback to the 32-bit
+     * volume serial number, rendered in lowercase hexadecimal.
+     */
+    uuid?: string;
+}

package/dist/types/unc.d.ts

@@ -1,4 +1,4 @@
-import { RemoteInfo } from "./remote_info.js";
+import { RemoteInfo } from "./types/remote_info.js";
 /**
  * Checks if a string is formatted as a valid UNC path.
  * A valid UNC path starts with double backslashes or slashes,

package/dist/types/units.d.ts

@@ -1,16 +1,38 @@
 /**
- * KiB = 1024 bytes
+ * Milliseconds in a second
+ */
+export declare const SecondMs = 1000;
+/**
+ * Milliseconds in a minute
+ */
+export declare const MinuteMs: number;
+/**
+ * Milliseconds in an hour
+ */
+export declare const HourMs: number;
+/**
+ * Milliseconds in a day
+ */
+export declare const DayMs: number;
+/**
+ * Kibibyte (KiB) = 1024 bytes
  * @see https://en.wikipedia.org/wiki/Kibibyte
  */
 export declare const KiB = 1024;
 /**
- * MiB = 1024 KiB
+ * Mebibyte (MiB) = 1024 KiB
  * @see https://en.wikipedia.org/wiki/Mebibyte
  */
 export declare const MiB: number;
 /**
- * GiB = 1024 MiB
+ * Gibibyte (GiB)= 1024 MiB
  * @see https://en.wikipedia.org/wiki/Gibibyte
  */
 export declare const GiB: number;
+/**
+ * Tebibyte (TiB) = 1024 GiB
+ *
+ * @see https://en.wikipedia.org/wiki/Byte#Multiple-byte_units
+ */
+export declare const TiB: number;
 export declare function fmtBytes(bytes: number): string;