@photostructure/fs-metadata 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -0,0 +1,360 @@
+/**
+ * Represents the detailed state of a file or directory's hidden attribute
+ */
+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;
+    };
+}
+
+type StringEnumType<T extends string> = {
+    [K in T]: K;
+};
+type StringEnum<T extends string> = StringEnumType<T> & {
+    values: T[];
+    size: number;
+    get(s: string | undefined): T | undefined;
+};
+type StringEnumKeys<Type> = Type extends StringEnum<infer X> ? X : never;
+
+/**
+ * Health statuses for volumes (mostly applicable to Windows).
+ *
+ * - `healthy`: Volume is "OK": accessible and functioning normally
+ * - `timeout`: Volume could not be accessed before the specified timeout. It
+ *   may be inaccessible or disconnected.
+ * - `inaccessible`: Volume exists but can't be accessed (permissions/locks)
+ * - `disconnected`: Network volume that's offline
+ * - `unknown`: Status can't be determined
+ */
+declare const VolumeHealthStatuses: StringEnum<"healthy" | "timeout" | "inaccessible" | "disconnected" | "unknown">;
+type VolumeHealthStatus = StringEnumKeys<typeof VolumeHealthStatuses>;
+
+/**
+ * A mount point is a location in the file system where a volume is mounted.
+ *
+ * @see https://en.wikipedia.org/wiki/Mount_(computing)
+ */
+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;
+}
+
+/**
+ * Configuration options for filesystem operations.
+ *
+ * @see {@link optionsWithDefaults} for creating an options object with default values
+ * @see {@link OptionsDefault} for the default values
+ */
+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;
+}
+
+/**
+ * Represents remote filesystem information.
+ */
+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;
+}
+
+/**
+ * Metadata associated to a volume.
+ *
+ * @see https://en.wikipedia.org/wiki/Volume_(computing)
+ */
+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;
+}
+
+type HideMethod = "dotPrefix" | "systemFlag" | "all" | "auto";
+type SetHiddenResult = {
+    pathname: string;
+    actions: {
+        dotPrefix: boolean;
+        systemFlag: boolean;
+    };
+};
+
+/**
+ * Default timeout in milliseconds for {@link Options.timeoutMs}.
+ *
+ * Note that this timeout may be insufficient for some devices, like spun-down
+ * optical drives or network shares that need to spin up or reconnect.
+ */
+declare const TimeoutMsDefault: 5000;
+/**
+ * System paths and globs that indicate system volumes
+ */
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/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"];
+/**
+ * Filesystem types that indicate system volumes
+ */
+declare const SystemFsTypesDefault: readonly ["autofs", "binfmt_misc", "cgroup", "cgroup2", "configfs", "debugfs", "devpts", "devtmpfs", "efivarfs", "fusectl", "fuse.snapfuse", "hugetlbfs", "mqueue", "none", "proc", "pstore", "rootfs", "securityfs", "snap*", "squashfs", "sysfs", "tmpfs"];
+declare const LinuxMountTablePathsDefault: readonly ["/proc/self/mounts", "/proc/mounts", "/etc/mtab"];
+/**
+ * Should {@link getAllVolumeMetadata} include system volumes by
+ * default?
+ */
+declare const IncludeSystemVolumesDefault: boolean;
+/**
+ * Default {@link Options} object.
+ *
+ * @see {@link optionsWithDefaults} for creating an options object with default values
+ */
+declare const OptionsDefault: Options;
+/**
+ * Create an {@link Options} object using default values from
+ * {@link OptionsDefault} for missing fields.
+ */
+declare function optionsWithDefaults<T extends Options>(overrides?: Partial<T>): T;
+
+/**
+ * Configuration for system volume detection
+ *
+ * @see {@link MountPoint.isSystemVolume}
+ */
+type SystemVolumeConfig = Pick<Options, "systemPathPatterns" | "systemFsTypes">;
+
+type GetVolumeMountPointOptions = Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "maxConcurrency" | "includeSystemVolumes"> & SystemVolumeConfig>;
+
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
+
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, type Options, OptionsDefault, type SetHiddenResult, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, TimeoutMsDefault, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getVolumeMetadata, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };