@photostructure/fs-metadata 0.3.2 → 0.4.0

package/src/hidden.ts

@@ -6,45 +6,9 @@ import { WrappedError } from "./error.js";
 import { canStatAsync, statAsync } from "./fs.js";
 import { isRootDirectory, normalizePath } from "./path.js";
 import { isWindows } from "./platform.js";
+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;
-  };
-}
-
 const HiddenSupportByPlatform: Partial<
   Record<NodeJS.Platform, Pick<HiddenMetadata, "supported">>
 > = {
@@ -79,7 +43,7 @@ export const LocalSupport = HiddenSupportByPlatform[process.platform]
  * @returns A boolean indicating if the item is hidden
  * @throws {Error} If the file doesn't exist or permissions are insufficient
  */
-export async function isHidden(
+export async function isHiddenImpl(
   pathname: string,
   nativeFn: NativeBindingsFn,
 ): Promise<boolean> {
@@ -93,7 +57,7 @@ export async function isHidden(
   );
 }
 
-export async function isHiddenRecursive(
+export async function isHiddenRecursiveImpl(
   path: string,
   nativeFn: NativeBindingsFn,
 ): Promise<boolean> {
@@ -102,7 +66,7 @@ export async function isHiddenRecursive(
     throw new Error("Invalid path: " + JSON.stringify(path));
   }
   while (!isRootDirectory(norm)) {
-    if (await isHidden(norm, nativeFn)) {
+    if (await isHiddenImpl(norm, nativeFn)) {
       return true;
     }
     norm = dirname(norm);
@@ -165,7 +129,7 @@ async function isSystemHidden(
  * @returns An object containing detailed hidden state information
  * @throws {Error} If the file doesn't exist or permissions are insufficient
  */
-export async function getHiddenMetadata(
+export async function getHiddenMetadataImpl(
   pathname: string,
   nativeFn: NativeBindingsFn,
 ): Promise<HiddenMetadata> {
@@ -193,7 +157,7 @@ export type SetHiddenResult = {
   };
 };
 
-export async function setHidden(
+export async function setHiddenImpl(
   pathname: string,
   hide: boolean,
   method: HideMethod,

package/src/{exports.ts → index.ts}

@@ -1,8 +1,17 @@
-// src/exports.ts
+// src/index.ts
 
-import type { HiddenMetadata, HideMethod, SetHiddenResult } from "./hidden.js";
-import type { MountPoint } from "./mount_point.js";
-import type { Options } from "./options.js";
+import NodeGypBuild from "node-gyp-build";
+import { debug, debugLogContext, isDebugEnabled } from "./debuglog.js";
+import { defer } from "./defer.js";
+import { _dirname } from "./dirname.js";
+import { findAncestorDir } from "./fs.js";
+import type { HideMethod, SetHiddenResult } from "./hidden.js";
+import {
+  getHiddenMetadataImpl,
+  isHiddenImpl,
+  isHiddenRecursiveImpl,
+  setHiddenImpl,
+} from "./hidden.js";
 import {
   IncludeSystemVolumesDefault,
   LinuxMountTablePathsDefault,
@@ -18,10 +27,19 @@ import type {
   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 { NativeBindings } from "./types/native_bindings.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 { VolumeMetadata } from "./volume_metadata.js";
+import {
+  getAllVolumeMetadataImpl,
+  getVolumeMetadataImpl,
+} from "./volume_metadata.js";
 import type { GetVolumeMountPointOptions } from "./volume_mount_points.js";
+import { getVolumeMountPointsImpl } from "./volume_mount_points.js";
 
 export type {
   GetVolumeMountPointOptions,
@@ -38,6 +56,28 @@ export type {
   VolumeMetadata,
 };
 
+const nativeFn = defer<Promise<NativeBindings>>(async () => {
+  const start = Date.now();
+  try {
+    const dirname = _dirname();
+    const dir = await findAncestorDir(dirname, "binding.gyp");
+    if (dir == null) {
+      throw new Error(
+        "Could not find bindings.gyp in any ancestor directory of " + dirname,
+      );
+    }
+    const bindings = NodeGypBuild(dir) as NativeBindings;
+    bindings.setDebugLogging(isDebugEnabled());
+    bindings.setDebugPrefix(debugLogContext() + ":native");
+    return bindings;
+  } catch (error) {
+    debug("Loading native bindings failed: %s", error);
+    throw error;
+  } finally {
+    debug(`Native bindings took %d ms to load`, Date.now() - start);
+  }
+});
+
 /**
  * List all active local and remote mount points on the system.
  *
@@ -48,9 +88,11 @@ export type {
  *
  * @param opts Optional filesystem operation settings to override default values
  */
-export declare function getVolumeMountPoints(
+export function getVolumeMountPoints(
   opts?: Partial<GetVolumeMountPointOptions>,
-): Promise<MountPoint[]>;
+): Promise<MountPoint[]> {
+  return getVolumeMountPointsImpl(optionsWithDefaults(opts), nativeFn);
+}
 
 /**
  * Get metadata for the volume at the given mount point.
@@ -58,10 +100,15 @@ export declare function getVolumeMountPoints(
  * @param mountPoint Must be a non-blank string
  * @param opts Optional filesystem operation settings
  */
-export declare function getVolumeMetadata(
+export function getVolumeMetadata(
   mountPoint: string,
   opts?: Partial<Pick<Options, "timeoutMs">>,
-): Promise<VolumeMetadata>;
+): Promise<VolumeMetadata> {
+  return getVolumeMetadataImpl(
+    { ...optionsWithDefaults(opts), mountPoint },
+    nativeFn,
+  );
+}
 
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
@@ -74,15 +121,17 @@ export declare function getVolumeMetadata(
  * 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 getVolumeMountPoints}, as well as **each** {@link getVolumeMetadata}
+ * {@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(
+export function getAllVolumeMetadata(
   opts?: Partial<Options> & { includeSystemVolumes?: boolean },
-): Promise<VolumeMetadata[]>;
+): Promise<VolumeMetadata[]> {
+  return getAllVolumeMetadataImpl(optionsWithDefaults(opts), nativeFn);
+}
 
 /**
  * Check if a file or directory is hidden.
@@ -93,7 +142,9 @@ export declare function getAllVolumeMetadata(
  * @param pathname Path to file or directory
  * @returns Promise resolving to boolean indicating hidden state
  */
-export declare function isHidden(pathname: string): Promise<boolean>;
+export function isHidden(pathname: string): Promise<boolean> {
+  return isHiddenImpl(pathname, nativeFn);
+}
 
 /**
  * Check if a file or directory is hidden, or if any of its ancestor
@@ -102,7 +153,9 @@ export declare function isHidden(pathname: string): Promise<boolean>;
  * @param pathname Path to file or directory
  * @returns Promise resolving to boolean indicating hidden state
  */
-export declare function isHiddenRecursive(pathname: string): Promise<boolean>;
+export function isHiddenRecursive(pathname: string): Promise<boolean> {
+  return isHiddenRecursiveImpl(pathname, nativeFn);
+}
 
 /**
  * Get detailed metadata about the hidden state of a file or directory.
@@ -110,9 +163,9 @@ export declare function isHiddenRecursive(pathname: string): Promise<boolean>;
  * @param pathname Path to file or directory
  * @returns Promise resolving to metadata about the hidden state
  */
-export declare function getHiddenMetadata(
-  pathname: string,
-): Promise<HiddenMetadata>;
+export function getHiddenMetadata(pathname: string): Promise<HiddenMetadata> {
+  return getHiddenMetadataImpl(pathname, nativeFn);
+}
 
 /**
  * Set the hidden state of a file or directory
@@ -128,21 +181,13 @@ export declare function getHiddenMetadata(
  * @throws {Error} If the file doesn't exist, permissions are insufficient, or
  * the requested method is unsupported
  */
-export declare function setHidden(
+export function setHidden(
   pathname: string,
   hidden: boolean,
-  method?: HideMethod,
-): Promise<SetHiddenResult>;
-
-export type ExportedFunctions = {
-  getVolumeMountPoints: typeof getVolumeMountPoints;
-  getVolumeMetadata: typeof getVolumeMetadata;
-  getAllVolumeMetadata: typeof getAllVolumeMetadata;
-  isHidden: typeof isHidden;
-  isHiddenRecursive: typeof isHiddenRecursive;
-  getHiddenMetadata: typeof getHiddenMetadata;
-  setHidden: typeof setHidden;
-};
+  method: HideMethod = "auto",
+): Promise<SetHiddenResult> {
+  return setHiddenImpl(pathname, hidden, method, nativeFn);
+}
 
 export {
   IncludeSystemVolumesDefault,

package/src/linux/mount_points.ts

@@ -2,10 +2,12 @@
 import { readFile } from "node:fs/promises";
 import { debug } from "../debuglog.js";
 import { toError, WrappedError } from "../error.js";
-import { isMountPoint, type MountPoint } from "../mount_point.js";
+import { isMountPoint } from "../mount_point.js";
 import { compactValues } from "../object.js";
-import { optionsWithDefaults, type Options } from "../options.js";
+import { optionsWithDefaults } 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, mountEntryToMountPoint, parseMtab } from "./mtab.js";
 
 export async function getLinuxMountPoints(

package/src/linux/mtab.ts

@@ -1,6 +1,5 @@
 // src/linux/mtab.ts
 
-import { MountPoint } from "../mount_point.js";
 import { toInt } from "../number.js";
 import { normalizePosixPath } from "../path.js";
 import { extractRemoteInfo } from "../remote_info.js";
@@ -11,7 +10,8 @@ import {
   toNotBlank,
 } from "../string.js";
 import { isSystemVolume, 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.
@@ -70,7 +70,7 @@ export function mountEntryToPartialVolumeMetadata(
     fstype: entry.fs_vfstype,
     mountFrom: entry.fs_spec,
     isSystemVolume: isSystemVolume(entry.fs_file, entry.fs_vfstype, options),
-    remote: false, // < default to false
+    remote: false, // < default to false, but it may be overridden by extractRemoteInfo
     ...extractRemoteInfo(entry.fs_spec),
   };
 }

package/src/mount_point.ts

@@ -1,58 +1,7 @@
 import { isObject } from "./object";
 import { isNotBlank } from "./string";
-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 function isMountPoint(obj: unknown): obj is MountPoint {
-  if (!isObject(obj)) return false;
-  return "mountPoint" in obj && isNotBlank(obj.mountPoint);
+  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
 }

package/src/object.ts

@@ -3,7 +3,7 @@
 import { isNotBlank, isString } from "./string.js";
 
 /**
- * Check if a value is an object
+ * @return true iff value is an object and not an array
  */
 export function isObject(value: unknown): value is object {
   // typeof null is 'object', so we need to check for that case YAY JAVASCRIPT
@@ -11,7 +11,8 @@ export function isObject(value: unknown): value is object {
 }
 
 /**
- * Map a value to another value, or undefined if the value is undefined
+ * @return undefined if `obj` is nullish, or the return value of `fn` applied
+ * against `obj` if `obj` is defined
  */
 export function map<T, U>(
   obj: T | undefined,
@@ -21,7 +22,7 @@ export function map<T, U>(
 }
 
 /**
- * Omit the specified fields from an object
+ * @return a shallow copy of `obj` that omits the specified `keys`
  */
 export function omit<T extends object, K extends keyof T>(
   obj: T,
@@ -40,6 +41,10 @@ export function omit<T extends object, K extends keyof T>(
   return result;
 }
 
+/**
+ * @return a shallow copy of `obj` that only includes fields that are defined
+ * and not nullish or blank.
+ */
 export function compactValues<T extends object>(
   obj: T | undefined,
 ): Partial<T> {

package/src/options.ts

@@ -3,59 +3,7 @@
 import { availableParallelism } from "node:os";
 import { compactValues, isObject } from "./object.js";
 import { isWindows } from "./platform.js";
-
-/**
- * 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}.
@@ -82,6 +30,9 @@ export const SystemPathPatternsDefault = [
   "/run/user/*/gvfs",
   "/snap/**",
   "/sys/**",
+  "/tmp",
+  "/var/tmp",
+  // we aren't including /tmp/**, as some people temporarily mount volumes there, like /tmp/project.
   "**/#snapshot", // Synology and Kubernetes volume snapshots
 
   // windows for linux:
@@ -100,7 +51,7 @@ export const SystemPathPatternsDefault = [
   "/System/Volumes/Update",
   "/System/Volumes/VM",
   "/System/Volumes/xarts",
-];
+] as const;
 
 /**
  * Filesystem types that indicate system volumes

package/src/path.ts

@@ -24,11 +24,18 @@ export function normalizePath(
 export function normalizePosixPath(
   mountPoint: string | undefined,
 ): string | undefined {
-  return isBlank(mountPoint)
-    ? undefined
-    : mountPoint === "/"
-      ? mountPoint
-      : mountPoint.replace(/\/+$/, "");
+  if (isBlank(mountPoint)) return undefined;
+  if (mountPoint === "/") return mountPoint;
+
+  // Fast path: check last char only if no trailing slash
+  if (mountPoint[mountPoint.length - 1] !== "/") return mountPoint;
+
+  // Slower path: trim trailing slashes
+  let end = mountPoint.length - 1;
+  while (end > 0 && mountPoint[end] === "/") {
+    end--;
+  }
+  return mountPoint.slice(0, end + 1);
 }
 
 /**

package/src/platform.ts

@@ -1,9 +1,9 @@
 // src/platform.ts
 
-import { platform } from "node:os";
+import { arch, platform } from "node:process";
 
-const p = platform();
+export const isLinux = platform === "linux";
+export const isWindows = platform === "win32";
+export const isMacOS = platform === "darwin";
 
-export const isLinux = p === "linux";
-export const isWindows = p === "win32";
-export const isMacOS = p === "darwin";
+export const isArm = isLinux && arch.startsWith("arm");