@photostructure/fs-metadata 0.1.6 → 0.3.0

package/src/object.ts

@@ -0,0 +1,55 @@
+// src/object.js
+
+import { isNotBlank, isString } from "./string.js";
+
+/**
+ * Check if a value is an object
+ */
+export function isObject(value: unknown): value is object {
+  // typeof null is 'object', so we need to check for that case YAY JAVASCRIPT
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Map a value to another value, or undefined if the value is undefined
+ */
+export function map<T, U>(
+  obj: T | undefined,
+  fn: (value: T) => U,
+): U | undefined {
+  return obj == null ? undefined : fn(obj);
+}
+
+/**
+ * Omit the specified fields from an object
+ */
+export function omit<T extends object, K extends keyof T>(
+  obj: T,
+  ...keys: K[]
+): Omit<T, K> {
+  const result = {} as Omit<T, K>;
+  const keysSet = new Set(keys);
+
+  // OH THE TYPING HUGEMANATEE
+  for (const key of Object.keys(obj) as Array<keyof Omit<T, K>>) {
+    if (!keysSet.has(key as unknown as K)) {
+      result[key] = obj[key];
+    }
+  }
+
+  return result;
+}
+
+export function compactValues<T extends object>(
+  obj: T | undefined,
+): Partial<T> {
+  const result = {} as Partial<T>;
+  if (obj == null || !isObject(obj)) return {};
+  for (const [key, value] of Object.entries(obj)) {
+    // skip blank strings and nullish values:
+    if (value != null && (!isString(value) || isNotBlank(value))) {
+      result[key as keyof T] = value as T[keyof T];
+    }
+  }
+  return result;
+}

package/src/options.ts

@@ -0,0 +1,179 @@
+// src/options.ts
+
+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;
+}
+
+/**
+ * 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.
+ */
+export const TimeoutMsDefault = 5_000 as const;
+
+/**
+ * System paths and globs that indicate system volumes
+ */
+export const SystemPathPatternsDefault = [
+  "/boot",
+  "/boot/efi",
+  "/dev",
+  "/dev/**",
+  "/proc/**",
+  "/run",
+  "/run/credentials/**",
+  "/run/lock",
+  "/run/snapd/**",
+  "/run/user/*/doc",
+  "/run/user/*/gvfs",
+  "/snap/**",
+  "/sys/**",
+  "**/#snapshot", // Synology and Kubernetes volume snapshots
+
+  // windows for linux:
+  "/mnt/wslg/distro",
+  "/mnt/wslg/doc",
+  "/mnt/wslg/versions.txt",
+  "/usr/lib/wsl/drivers",
+
+  // MacOS stuff:
+  "/private/var/vm", // macOS swap
+  "/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
+ */
+export const SystemFsTypesDefault = [
+  "autofs",
+  "binfmt_misc",
+  "cgroup",
+  "cgroup2",
+  "configfs",
+  "debugfs",
+  "devpts",
+  "devtmpfs",
+  "efivarfs",
+  "fusectl",
+  "fuse.snapfuse",
+  "hugetlbfs",
+  "mqueue",
+  "none",
+  "proc",
+  "pstore",
+  "rootfs",
+  "securityfs",
+  "snap*",
+  "squashfs",
+  "sysfs",
+  "tmpfs",
+] as const;
+
+export const LinuxMountTablePathsDefault = [
+  "/proc/self/mounts",
+  "/proc/mounts",
+  "/etc/mtab",
+] as const;
+
+/**
+ * Should {@link getAllVolumeMetadata} include system volumes by
+ * default?
+ */
+export const IncludeSystemVolumesDefault = isWindows;
+
+/**
+ * Default {@link Options} object.
+ *
+ * @see {@link optionsWithDefaults} for creating an options object with default values
+ */
+export const OptionsDefault: Options = {
+  timeoutMs: TimeoutMsDefault,
+  maxConcurrency: availableParallelism(),
+  systemPathPatterns: [...SystemPathPatternsDefault],
+  systemFsTypes: [...SystemFsTypesDefault],
+  linuxMountTablePaths: [...LinuxMountTablePathsDefault],
+  includeSystemVolumes: IncludeSystemVolumesDefault,
+} as const;
+
+/**
+ * Create an {@link Options} object using default values from
+ * {@link OptionsDefault} for missing fields.
+ */
+export function optionsWithDefaults<T extends Options>(
+  overrides: Partial<T> = {},
+): T {
+  if (!isObject(overrides)) {
+    throw new TypeError(
+      "options(): expected an object, got " +
+        typeof overrides +
+        ": " +
+        JSON.stringify(overrides),
+    );
+  }
+
+  return {
+    ...OptionsDefault,
+    ...(compactValues(overrides) as T),
+  };
+}

package/src/path.ts

@@ -0,0 +1,54 @@
+// src/path.ts
+
+import { dirname, resolve } from "node:path";
+import { isWindows } from "./platform.js";
+import { isBlank } from "./string.js";
+
+export function normalizePath(
+  mountPoint: string | undefined,
+): string | undefined {
+  if (isBlank(mountPoint)) return undefined;
+
+  const result = isWindows
+    ? normalizeWindowsPath(mountPoint)
+    : normalizePosixPath(mountPoint);
+
+  // Make sure the native code doesn't see anything weird:
+  return result != null ? resolve(result) : undefined;
+}
+
+/**
+ * Normalizes a Linux or macOS mount point by removing any trailing slashes.
+ * This is a no-op for root mount points.
+ */
+export function normalizePosixPath(
+  mountPoint: string | undefined,
+): string | undefined {
+  return isBlank(mountPoint)
+    ? undefined
+    : mountPoint === "/"
+      ? mountPoint
+      : mountPoint.replace(/\/+$/, "");
+}
+
+/**
+ * Normalizes a Windows mount point by ensuring drive letters end with a
+ * backslash.
+ */
+export function normalizeWindowsPath(mountPoint: string): string {
+  // Terrible things happen if we give syscalls "C:" instead of "C:\"
+
+  return /^[a-z]:$/i.test(mountPoint)
+    ? mountPoint.toUpperCase() + "\\"
+    : mountPoint;
+}
+
+/**
+ * @return true if `path` is the root directory--this is platform-specific. Only
+ * "/" on linux/macOS is considered a root directory. On Windows, the root
+ * directory is a drive letter followed by a colon, e.g. "C:\".
+ */
+export function isRootDirectory(path: string): boolean {
+  const n = normalizePath(path);
+  return n == null ? false : isWindows ? dirname(n) === n : n === "/";
+}

package/src/platform.ts

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

package/src/random.ts

@@ -0,0 +1,40 @@
+// src/random.ts
+
+import { randomInt } from "node:crypto";
+
+const CharCode_a = "a".charCodeAt(0);
+/**
+ * @return a random character `[a-z]`
+ */
+export function randomLetter(): string {
+  return String.fromCharCode(CharCode_a + randomInt(0, 26));
+}
+
+export function randomLetters(length: number): string {
+  return Array.from({ length }, randomLetter).join("");
+}
+
+/**
+ * Shuffle an array using the Fisher-Yates (Knuth) algorithm.
+ * @param a The array to shuffle
+ * @returns A shallow shuffled copy of `a`
+ */
+export function shuffle<T>(a: T[]): T[] {
+  if (a.length <= 1) return a;
+  a = [...a]; // Copy the array
+  for (let i = a.length - 1; i > 0; i--) {
+    // Pick a random index from 0 to i
+    const j = Math.floor(Math.random() * (i + 1));
+    // Swap elements at indices i and j
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    [a[i], a[j]] = [a[j]!, a[i]!];
+  }
+  return a;
+}
+
+export function pickRandom<T>(a: T[]): T {
+  if (a == null || a.length === 0) {
+    throw new Error("Cannot pick from an empty array");
+  }
+  return a[randomInt(0, a.length)] as T;
+}

package/src/remote_info.ts

@@ -0,0 +1,161 @@
+// src/remote_info.ts
+
+import { debug } from "./debuglog.js";
+import { compactValues, isObject } from "./object.js";
+import { isWindows } from "./platform.js";
+import { isBlank, isNotBlank } from "./string.js";
+
+/**
+ * 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;
+}
+
+export function isRemoteInfo(obj: unknown): obj is RemoteInfo {
+  if (!isObject(obj)) return false;
+  const { remoteHost, remoteShare } = obj as Partial<RemoteInfo>;
+  return isNotBlank(remoteHost) && isNotBlank(remoteShare);
+}
+
+const NETWORK_FS_TYPES = new Set([
+  "9p",
+  "afp",
+  "afs",
+  "beegfs",
+  "ceph",
+  "cifs",
+  "ftp",
+  "fuse.cephfs",
+  "fuse.glusterfs",
+  "fuse.sshfs",
+  "fuse",
+  "gfs2",
+  "glusterfs",
+  "lustre",
+  "ncpfs",
+  "nfs",
+  "nfs4",
+  "smb",
+  "smbfs",
+  "sshfs",
+  "webdav",
+]);
+
+export function normalizeProtocol(protocol: string): string {
+  return (protocol ?? "").toLowerCase().replace(/:$/, "");
+}
+
+export function isRemoteFsType(fstype: string | undefined): boolean {
+  return isNotBlank(fstype) && NETWORK_FS_TYPES.has(normalizeProtocol(fstype));
+}
+
+export function parseURL(s: string): URL | undefined {
+  try {
+    return isBlank(s) ? undefined : new URL(s);
+  } catch {
+    return;
+  }
+}
+
+export function extractRemoteInfo(
+  fsSpec: string | undefined,
+): RemoteInfo | undefined {
+  if (fsSpec == null || isBlank(fsSpec)) return;
+
+  if (isWindows) {
+    fsSpec = fsSpec.replace(/\\/g, "/");
+  }
+
+  const url = parseURL(fsSpec);
+
+  if (url?.protocol === "file:") {
+    return {
+      remote: false,
+      uri: fsSpec,
+    };
+  }
+
+  const patterns = [
+    // CIFS/SMB pattern: //hostname/share or //user@host/share
+    {
+      regex:
+        /^\/\/(?:(?<remoteUser>[^/@]+)@)?(?<remoteHost>[^/@]+)\/(?<remoteShare>.+)$/,
+    },
+    // NFS pattern: hostname:/share
+    {
+      protocol: "nfs",
+      regex: /^(?<remoteHost>[^:]+):\/(?!\/)(?<remoteShare>.+)$/,
+    },
+  ];
+
+  for (const { protocol, regex } of patterns) {
+    const o = compactValues({
+      protocol,
+      remote: true,
+      ...(fsSpec.match(regex)?.groups ?? {}),
+    });
+    if (isRemoteInfo(o)) {
+      debug("[extractRemoteInfo] matched pattern: %o", o);
+      return o;
+    }
+  }
+
+  // Let's try URL last, as nfs mounts are URI-ish
+  try {
+    // try to parse fsSpec as a uri:
+    const parsed = new URL(fsSpec);
+    if (parsed != null) {
+      debug("[extractRemoteInfo] parsed URL: %o", parsed);
+      const protocol = normalizeProtocol(parsed.protocol);
+      if (!isRemoteFsType(protocol)) {
+        // don't set remoteUser, remoteHost, or remoteShare, it's not remote!
+        return {
+          uri: fsSpec,
+          remote: false,
+        };
+      } else {
+        return compactValues({
+          uri: fsSpec,
+          protocol,
+          remote: true,
+          remoteUser: parsed.username,
+          remoteHost: parsed.hostname,
+          // URL pathname includes leading slash:
+          remoteShare: parsed.pathname.replace(/^\//, ""),
+        }) as unknown as RemoteInfo;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return;
+}

package/src/setup.ts

@@ -0,0 +1,69 @@
+// src/exports.ts
+
+import NodeGypBuild from "node-gyp-build";
+import { debug, debugLogContext, isDebugEnabled } from "./debuglog.js";
+import { defer } from "./defer.js";
+import { ExportedFunctions } from "./exports.js";
+import { findAncestorDir } from "./fs.js";
+import {
+  getHiddenMetadata,
+  HideMethod,
+  isHidden,
+  isHiddenRecursive,
+  setHidden,
+} from "./hidden.js";
+import { optionsWithDefaults } from "./options.js";
+import type { NativeBindings } from "./types/native_bindings.js";
+import { getAllVolumeMetadata, getVolumeMetadata } from "./volume_metadata.js";
+import {
+  getVolumeMountPoints,
+  type GetVolumeMountPointOptions,
+} from "./volume_mount_points.js";
+
+export function setup(dirname: string): ExportedFunctions {
+  const nativeFn = defer<Promise<NativeBindings>>(async () => {
+    const start = Date.now();
+    try {
+      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);
+    }
+  });
+
+  return {
+    getVolumeMountPoints: (opts: Partial<GetVolumeMountPointOptions> = {}) =>
+      getVolumeMountPoints(optionsWithDefaults(opts), nativeFn),
+
+    getVolumeMetadata: (mountPoint: string, opts = {}) =>
+      getVolumeMetadata({ ...optionsWithDefaults(opts), mountPoint }, nativeFn),
+
+    getAllVolumeMetadata: (opts = {}) =>
+      getAllVolumeMetadata(optionsWithDefaults(opts), nativeFn),
+
+    isHidden: (pathname: string) => isHidden(pathname, nativeFn),
+
+    isHiddenRecursive: (pathname: string) =>
+      isHiddenRecursive(pathname, nativeFn),
+
+    getHiddenMetadata: (pathname: string) =>
+      getHiddenMetadata(pathname, nativeFn),
+
+    setHidden: (
+      pathname: string,
+      hidden: boolean,
+      method: HideMethod = "auto",
+    ) => setHidden(pathname, hidden, method, nativeFn),
+  } as const;
+}

package/src/string.ts

@@ -0,0 +1,99 @@
+// src/string.ts
+
+export function isString(input: unknown): input is string {
+  return typeof input === "string";
+}
+
+export function toS(input: unknown): string {
+  return isString(input) ? input : input == null ? "" : String(input);
+}
+
+/**
+ * @return true iff the input is a string and has at least one non-whitespace character
+ */
+export function isNotBlank(input: unknown): input is string {
+  return typeof input === "string" && input.trim().length > 0;
+}
+
+/**
+ * @return true iff the input is not a string or only has non-whitespace characters
+ */
+export function isBlank(input: unknown): input is undefined {
+  return !isNotBlank(input);
+}
+
+export function toNotBlank(input: unknown): string | undefined {
+  return isNotBlank(input) ? input : undefined;
+}
+
+/**
+ * Decodes a string containing octal (\000-\377) and/or hexadecimal
+ * (\x00-\xFF) escape sequences
+ * @param input The string containing escape sequences to decode
+ * @returns The decoded string with escape sequences converted to their
+ * corresponding characters
+ * @throws Error if an invalid escape sequence is encountered
+ */
+export function decodeEscapeSequences(input: string): string {
+  const escapeRegex = /\\(?:([0-7]{2,6})|x([0-9a-fA-F]{2,4}))/g;
+
+  return input.replace(escapeRegex, (match, octal, hex) => {
+    // Handle octal escape sequences
+    if (octal != null) {
+      return String.fromCharCode(parseInt(octal, 8));
+    }
+
+    // Handle hexadecimal escape sequences
+    if (hex != null) {
+      return String.fromCharCode(parseInt(hex, 16));
+    }
+
+    // This should never happen due to the regex pattern
+    throw new Error(`Invalid escape sequence: ${match}`);
+  });
+}
+
+const AlphaNumericRE = /[a-z0-9.-_]/i;
+
+export function encodeEscapeSequences(input: string): string {
+  return input
+    .split("")
+    .map((char) => {
+      const encodedChar = AlphaNumericRE.test(char)
+        ? char
+        : "\\" + char.charCodeAt(0).toString(8).padStart(2, "0");
+      return encodedChar;
+    })
+    .join("");
+}
+
+/**
+ * Sort an array of strings using the locale-aware collation algorithm.
+ *
+ * @param arr The array of strings to sort. The original array **is sorted in
+ * place**.
+ */
+export function sortByLocale(
+  arr: string[],
+  locales?: Intl.LocalesArgument,
+  options?: Intl.CollatorOptions,
+): string[] {
+  return arr.sort((a, b) => a.localeCompare(b, locales, options));
+}
+
+/**
+ * Sort an array of objects using the locale-aware collation algorithm.
+ *
+ * @param arr The array of objects to sort.
+ * @param fn The function to extract the key to sort by from each object.
+ * @param locales The locales to use for sorting.
+ * @param options The collation options to use for sorting.
+ */
+export function sortObjectsByLocale<T>(
+  arr: T[],
+  fn: (key: T) => string,
+  locales?: Intl.LocalesArgument,
+  options?: Intl.CollatorOptions,
+): T[] {
+  return arr.sort((a, b) => fn(a).localeCompare(fn(b), locales, options));
+}