@photostructure/fs-metadata 0.1.6 → 0.2.0

package/src/string_enum.ts

@@ -0,0 +1,41 @@
+// src/string_enum.ts
+
+// See https://basarat.gitbooks.io/typescript/content/docs/types/literal-types.html
+
+export type StringEnumType<T extends string> = {
+  [K in T]: K;
+};
+
+export type StringEnum<T extends string> = StringEnumType<T> & {
+  values: T[];
+  size: number;
+  get(s: string | undefined): T | undefined;
+};
+
+export type StringEnumKeys<Type> = Type extends StringEnum<infer X> ? X : never;
+
+/**
+ * Create a string enum with the given values. 
+
+Example usage:
+
+export const Directions = stringEnum("North", "South", "East", "West")
+export type Direction = StringEnumKeys<typeof Directions>
+
+*/
+export function stringEnum<T extends string>(...o: T[]): StringEnum<T> {
+  const set = new Set(o);
+
+  const dict: StringEnumType<T> = {} as StringEnumType<T>;
+  for (const key of o) {
+    dict[key] = key;
+  }
+
+  return {
+    ...dict,
+    values: Object.freeze([...set]) as T[],
+    size: set.size,
+    get: (s: string | undefined) =>
+      s != null && set.has(s as T) ? (s as T) : undefined,
+  };
+}

package/src/system_volume.ts

@@ -0,0 +1,67 @@
+// src/system_volume.ts
+
+import { debug } from "./debuglog.js";
+import { compileGlob } from "./glob.js";
+import { MountPoint } from "./mount_point.js";
+import {
+  Options,
+  SystemFsTypesDefault,
+  SystemPathPatternsDefault,
+} from "./options.js";
+import { normalizePath } from "./path.js";
+import { isWindows } from "./platform.js";
+import { isNotBlank } from "./string.js";
+
+/**
+ * Configuration for system volume detection
+ *
+ * @see {@link MountPoint.isSystemVolume}
+ */
+export type SystemVolumeConfig = Pick<
+  Options,
+  "systemPathPatterns" | "systemFsTypes"
+>;
+
+/**
+ * Determines if a mount point represents a system volume based on its path and
+ * filesystem type
+ */
+export function isSystemVolume(
+  mountPoint: string,
+  fstype: string | undefined,
+  config: Partial<SystemVolumeConfig> = {},
+): boolean {
+  debug("[isSystemVolume] checking %s (fstype: %s)", mountPoint, fstype);
+  if (isWindows) {
+    const systemDrive = normalizePath(process.env["SystemDrive"]);
+    if (systemDrive != null && mountPoint === systemDrive) {
+      debug("[isSystemVolume] %s is the Windows system drive", mountPoint);
+      return true;
+    }
+  }
+  const result =
+    (isNotBlank(fstype) &&
+      (config.systemFsTypes ?? SystemFsTypesDefault).has(fstype)) ||
+    compileGlob(config.systemPathPatterns ?? SystemPathPatternsDefault).test(
+      mountPoint,
+    );
+  debug("[isSystemVolume] %s -> %s", mountPoint, result);
+  return result;
+}
+
+export function assignSystemVolume(
+  mp: MountPoint,
+  config: Partial<SystemVolumeConfig>,
+) {
+  const result = isSystemVolume(mp.mountPoint, mp.fstype, config);
+
+  if (isWindows) {
+    // native code actually knows the system drive and has more in-depth
+    // metadata information that we trust more than these heuristics
+    mp.isSystemVolume ??= result;
+  } else {
+    // macOS and Linux don't have a concept of an explicit "system drive" like
+    // Windows--always trust our heuristics
+    mp.isSystemVolume = result;
+  }
+}

package/src/test-utils/assert.ts

@@ -0,0 +1,69 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+// src/test-utils/assert.ts
+import { isMacOS } from "../platform.js";
+import type { VolumeMetadata } from "../volume_metadata.js";
+
+/**
+ * Asserts that the given metadata object has valid filesystem metadata
+ * properties
+ * @param metadata The metadata object to validate
+ */
+export function assertMetadata(metadata: VolumeMetadata | undefined) {
+  try {
+    // Basic type checks
+    expect(metadata).toBeDefined();
+    if (metadata == null) throw new Error("Metadata is undefined");
+
+    expect(metadata.mountPoint).toBeDefined();
+    expect(typeof metadata.mountPoint).toBe("string");
+    expect(metadata.mountPoint.length).toBeGreaterThan(0);
+
+    if (metadata.fstype !== undefined) {
+      expect(typeof metadata.fstype).toBe("string");
+      expect(metadata.fstype).toMatch(/^[^/]+$/);
+    }
+
+    // Size checks
+    if (isMacOS && metadata.mountPoint === "/System/Volumes/Data/home") {
+      // skip size checks for this path on macOS, it's for the legacy /home mount which may be empty
+    } else {
+      expect(metadata.size).toBeGreaterThan(0);
+      expect(metadata.used).toBeGreaterThanOrEqual(0);
+      expect(metadata.available).toBeGreaterThanOrEqual(0);
+      expect(metadata.used! + metadata.available!).toBeLessThanOrEqual(
+        metadata.size!,
+      );
+    }
+
+    // Optional fields with type checking
+    if (metadata.label !== undefined) {
+      expect(typeof metadata.label).toBe("string");
+      expect(metadata.label.length).toBeGreaterThan(0);
+    }
+
+    if (metadata.uuid !== undefined) {
+      expect(typeof metadata.uuid).toBe("string");
+      expect(metadata.uuid).toMatch(/^[0-9a-z-]{8,}$/i);
+    }
+
+    if (metadata.remote !== undefined) {
+      expect(typeof metadata.remote).toBe("boolean");
+
+      // If it's a remote volume, check for remote-specific properties
+      if (metadata.remote === true) {
+        if (metadata.remoteHost !== undefined) {
+          expect(typeof metadata.remoteHost).toBe("string");
+          expect(metadata.remoteHost.length).toBeGreaterThan(0);
+        }
+
+        if (metadata.remoteShare !== undefined) {
+          expect(typeof metadata.remoteShare).toBe("string");
+          expect(metadata.remoteShare.length).toBeGreaterThan(0);
+        }
+      }
+    }
+  } catch (e) {
+    console.log("Assertions failed: " + e, { metadata });
+    throw e;
+  }
+}

package/src/test-utils/hidden-tests.ts

@@ -0,0 +1,33 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isHidden, isHiddenRecursive, setHidden } from "../..";
+
+/**
+ * This function exercises the hidden file functionality and is used by both
+ * memory.test and hidden.test suites.
+ */
+export async function validateHidden(dir: string) {
+  await mkdir(dir, { recursive: true });
+  let file = join(dir, "test.txt");
+  await writeFile(file, "test");
+  expect(await isHidden(dir)).toBe(false);
+  expect(await isHidden(file)).toBe(false);
+  expect(await isHiddenRecursive(dir)).toBe(false);
+  expect(await isHiddenRecursive(file)).toBe(false);
+  const hiddenDir = (await setHidden(dir, true)).pathname;
+  expect(await isHidden(hiddenDir)).toBe(true);
+
+  file = join(hiddenDir, "test.txt");
+  expect(await isHidden(file)).toBe(false);
+  expect(await isHiddenRecursive(file)).toBe(true);
+
+  // This should be a no-op:
+  expect(await setHidden(hiddenDir, true)).toEqual(
+    expect.objectContaining({
+      pathname: hiddenDir,
+    }),
+  );
+  const hiddenFile = (await setHidden(file, true)).pathname;
+  expect(await isHidden(hiddenFile)).toBe(true);
+  expect(await isHidden(hiddenDir)).toBe(true);
+}

package/src/test-utils/jest-matchers.ts

@@ -0,0 +1,29 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+import { expect } from "@jest/globals";
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toBeWithinDelta(expected: number, delta: number): R;
+    }
+  }
+}
+
+function toBeWithinDelta(received: number, expected: number, delta: number) {
+  const pass = Math.abs(received - expected) <= delta;
+  if (pass) {
+    return {
+      message: () =>
+        `expected ${received} not to be within ${delta} of ${expected}`,
+      pass: true,
+    };
+  } else {
+    return {
+      message: () =>
+        `expected ${received} to be within ${delta} of ${expected}`,
+      pass: false,
+    };
+  }
+}
+
+expect.extend({ toBeWithinDelta });

package/src/test-utils/platform.ts

@@ -0,0 +1,39 @@
+// src/test-utils/platform.ts
+
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { env, platform } from "node:process";
+import { normalizePath } from "../path.js";
+import { isMacOS, isWindows } from "../platform.js";
+import { toNotBlank } from "../string.js";
+
+/**
+ * Helper function to skip tests based on platform
+ * @param platform The platform to run tests on ('win32', 'darwin', 'linux')
+ * @returns jest.Describe function that only runs on specified platform
+ */
+export function describePlatform(...supported: NodeJS.Platform[]) {
+  return supported.includes(platform) ? describe : describe.skip;
+}
+
+export function systemDrive() {
+  if (isWindows) {
+    return normalizePath(
+      toNotBlank(env["SystemDrive"] ?? "") ?? "C:\\",
+    ) as string;
+  } else {
+    return "/";
+  }
+}
+
+export function tmpDirNotHidden() {
+  const dir = isMacOS
+    ? join(homedir(), "tmp")
+    : isWindows
+      ? join(systemDrive(), "tmp")
+      : "/tmp";
+
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/src/types/native_bindings.ts

@@ -0,0 +1,64 @@
+// src/types/native_bindings.ts
+
+import { 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`
+   * environment matches `fs-meta`, `fs-metadata`, or
+   * `photostructure:fs-metadata`.
+   */
+  setDebugLogging(enabled: boolean): void;
+
+  /**
+   * Sets a prefix for debug log messages. Defaults to the shortest enabled
+   * debug log context, plus the process ID.
+   */
+  setDebugPrefix(prefix: string): void;
+
+  /**
+   * This is only available on macOS and Windows--Linux only hides files via
+   * filename (if basename starts with a dot).
+   */
+  isHidden(path: string): Promise<boolean>;
+
+  /**
+   * This is only available on macOS and Windows--Linux only hides files via
+   * filename (if basename starts with a dot).
+   *
+   * @param path The path to the file or directory to hide or unhide
+   * @param hidden If true, the file or directory will be hidden; if false, it
+   * will be unhidden
+   * @throws {Error} If the operation fails
+   */
+  setHidden(path: string, hidden: boolean): Promise<void>;
+
+  /**
+   * This is only available on macOS and Windows--Linux directly reads from the
+   * proc mounts table.
+   */
+  getVolumeMountPoints(
+    options?: Pick<Options, "timeoutMs">,
+  ): Promise<MountPoint[]>;
+
+  /**
+   * This is only available on Linux, and only if libglib-2.0 is installed.
+   */
+  getGioMountPoints?(): Promise<MountPoint[]>;
+
+  /**
+   * This is only a partial implementation for most platforms, to minimize
+   * native code when possible. The javascript side handles a bunch of
+   * subsequent parsing and extraction logic.
+   */
+  getVolumeMetadata(options: GetVolumeMetadataOptions): Promise<VolumeMetadata>;
+}
+
+export type GetVolumeMetadataOptions = {
+  mountPoint: string;
+  device?: string;
+} & Partial<Pick<Options, "timeoutMs">>;
+
+export type NativeBindingsFn = () => NativeBindings | Promise<NativeBindings>;

package/src/types/node-gyp-build.d.ts

@@ -0,0 +1,6 @@
+// src/types/node-gyp-build.d.ts
+
+declare module "node-gyp-build" {
+  function NodeGypBuild(dir: string): unknown;
+  export default NodeGypBuild;
+}

package/src/unc.ts

@@ -0,0 +1,63 @@
+// src/unc.ts
+
+import { RemoteInfo } from "./remote_info.js";
+import { isBlank, isString } from "./string.js";
+
+/**
+ * Checks if a string is formatted as a valid UNC path.
+ * A valid UNC path starts with double backslashes or slashes,
+ * followed by a server/host name, and then a share name.
+ * The path must use consistent slashes (all forward or all backward).
+ *
+ * @param path - The string to check
+ * @returns boolean - True if the string is a valid UNC path, false otherwise
+ */
+export function parseUNCPath(
+  path: string | null | undefined,
+): RemoteInfo | undefined {
+  if (path == null || isBlank(path) || !isString(path)) {
+    return;
+  }
+
+  // Check for two forward slashes or two backslashes at start
+  if (!path.startsWith("\\\\") && !path.startsWith("//")) {
+    return;
+  }
+
+  // Determine slash type from the start of the path
+  const isForwardSlash = path.startsWith("//");
+  const slashChar = isForwardSlash ? "/" : "\\";
+
+  // Split path using the correct slash type
+  const parts = path.slice(2).split(slashChar);
+
+  // Check minimum required parts (server and share)
+  if (parts.length < 2) {
+    return;
+  }
+
+  // Validate server and share names exist and aren't empty
+  const [remoteHost, remoteShare] = parts;
+  if (
+    remoteHost == null ||
+    isBlank(remoteHost) ||
+    remoteShare == null ||
+    isBlank(remoteShare)
+  ) {
+    return;
+  }
+
+  // Check for invalid characters in server and share names
+  const invalidChars = /[<>:"|?*]/;
+  if (invalidChars.test(remoteHost) || invalidChars.test(remoteShare)) {
+    return;
+  }
+
+  // Check for mixed slash usage
+  const wrongSlash = isForwardSlash ? "\\" : "/";
+  if (path.includes(wrongSlash)) {
+    return;
+  }
+
+  return { remoteHost, remoteShare, remote: true };
+}

package/src/units.ts

@@ -0,0 +1,31 @@
+// src/units.ts
+
+/**
+ * KiB = 1024 bytes
+ * @see https://en.wikipedia.org/wiki/Kibibyte
+ */
+export const KiB = 1024;
+
+/**
+ * MiB = 1024 KiB
+ * @see https://en.wikipedia.org/wiki/Mebibyte
+ */
+export const MiB = 1024 * KiB;
+
+/**
+ * GiB = 1024 MiB
+ * @see https://en.wikipedia.org/wiki/Gibibyte
+ */
+export const GiB = 1024 * MiB;
+
+export function fmtBytes(bytes: number): string {
+  if (bytes < KiB) {
+    return `${bytes} B`;
+  } else if (bytes < MiB) {
+    return `${(bytes / KiB).toFixed(2)} KiB`;
+  } else if (bytes < GiB) {
+    return `${(bytes / MiB).toFixed(2)} MiB`;
+  } else {
+    return `${(bytes / GiB).toFixed(2)} GiB`;
+  }
+}

package/src/uuid.ts

@@ -0,0 +1,24 @@
+// src/uuid.ts
+
+import { toS } from "./string.js";
+
+const uuidRegex = /[a-z0-9][a-z0-9-]{7,}/i;
+
+/**
+ * Some volume UUIDs are short, like, `ABCD1234`.
+ *
+ * Some volume UUIDs are in hexadecimal, but others and use G-Z. We will allow
+ * that.
+ *
+ * Some Windows syscalls wrap the UUID in a "\\\\?\\Volume{...}\\" prefix and
+ * suffix. This function will strip out that prefix and suffix.
+ *
+ * We will ignore any UUID-ish string that is not at least 8 characters long
+ * (and return `undefined` if no other, longer uuid-ish string is found).
+ *
+ * UUIDs cannot start with a hyphen, and can only contain a-z, 0-9, and hyphens
+ * (case-insensitive).
+ */
+export function extractUUID(uuid: string | undefined): string | undefined {
+  return toS(uuid).match(uuidRegex)?.[0];
+}

package/src/volume_health_status.ts

@@ -0,0 +1,58 @@
+// src/volume_health_status.ts
+
+import { TimeoutError } from "./async.js";
+import { debug } from "./debuglog.js";
+import { toError } from "./error.js";
+import { canReaddir } from "./fs.js";
+import { isObject } from "./object.js";
+import { stringEnum, StringEnumKeys } from "./string_enum.js";
+
+/**
+ * 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
+ */
+export const VolumeHealthStatuses = stringEnum(
+  "healthy",
+  "timeout",
+  "inaccessible",
+  "disconnected",
+  "unknown",
+);
+
+export type VolumeHealthStatus = StringEnumKeys<typeof VolumeHealthStatuses>;
+
+/**
+ * Attempt to read a directory to determine if it's accessible, and if an error
+ * is thrown, convert to a health status.
+ * @returns the "health status" of the directory, based on the success of `readdir(dir)`.
+ * @throws never
+ */
+export async function directoryStatus(
+  dir: string,
+  timeoutMs: number,
+  canReaddirImpl: typeof canReaddir = canReaddir,
+): Promise<{ status: VolumeHealthStatus; error?: Error }> {
+  try {
+    if (await canReaddirImpl(dir, timeoutMs)) {
+      return { status: VolumeHealthStatuses.healthy };
+    }
+  } catch (error) {
+    debug("[directoryStatus] %s: %s", dir, error);
+    let status: VolumeHealthStatus = VolumeHealthStatuses.unknown;
+    if (error instanceof TimeoutError) {
+      status = VolumeHealthStatuses.timeout;
+    } else if (isObject(error) && error instanceof Error && "code" in error) {
+      if (error.code === "EPERM" || error.code === "EACCES") {
+        status = VolumeHealthStatuses.inaccessible;
+      }
+    }
+    return { status, error: toError(error) };
+  }
+  return { status: VolumeHealthStatuses.unknown };
+}