@photostructure/fs-metadata 0.3.2 → 0.3.3

package/dist/types/volume_metadata.d.ts

@@ -1,54 +1,8 @@
-import type { MountPoint } from "./mount_point.js";
-import { type Options } from "./options.js";
-import { type RemoteInfo } from "./remote_info.js";
 import type { GetVolumeMetadataOptions, NativeBindingsFn } from "./types/native_bindings.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;
-}
-export declare function getVolumeMetadata(o: GetVolumeMetadataOptions & Options, nativeFn: NativeBindingsFn): Promise<VolumeMetadata>;
-export declare function getAllVolumeMetadata(opts: Required<Options> & {
+import type { Options } from "./types/options.js";
+import type { VolumeMetadata } from "./types/volume_metadata.js";
+export declare function getVolumeMetadataImpl(o: GetVolumeMetadataOptions & Options, nativeFn: NativeBindingsFn): Promise<VolumeMetadata>;
+export declare function getAllVolumeMetadataImpl(opts: Required<Options> & {
     includeSystemVolumes?: boolean;
     maxConcurrency?: number;
 }, nativeFn: NativeBindingsFn): Promise<VolumeMetadata[]>;
-export declare const _: undefined;

package/dist/types/volume_mount_points.d.ts

@@ -1,9 +1,6 @@
-import { MountPoint } from "./mount_point.js";
-import { Options } from "./options.js";
 import { SystemVolumeConfig } from "./system_volume.js";
+import type { MountPoint } from "./types/mount_point.js";
 import type { NativeBindingsFn } from "./types/native_bindings.js";
+import type { Options } from "./types/options.js";
 export type GetVolumeMountPointOptions = Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "maxConcurrency" | "includeSystemVolumes"> & SystemVolumeConfig>;
-/**
- * Helper function for {@link getVolumeMountPoints}.
- */
-export declare function getVolumeMountPoints(opts: Required<GetVolumeMountPointOptions>, nativeFn: NativeBindingsFn): Promise<MountPoint[]>;
+export declare function getVolumeMountPointsImpl(opts: Required<GetVolumeMountPointOptions>, nativeFn: NativeBindingsFn): Promise<MountPoint[]>;

package/jest.config.base.cjs

@@ -0,0 +1,63 @@
+// @ts-check
+
+// jest.config.base.cjs
+
+const { argv, platform } = require("node:process");
+
+const otherPlatforms = ["linux", "darwin", "windows"]
+  .filter((ea) => ea !== (platform === "win32" ? "windows" : platform))
+  .map((ea) => `/${ea}/`);
+
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+const baseConfig = {
+  testEnvironment: "jest-environment-node",
+  roots: ["<rootDir>/src"],
+  coverageProvider: "v8",
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  verbose: true,
+  silent: false,
+  randomize: true,
+  setupFilesAfterEnv: [
+    "jest-extended/all",
+    "<rootDir>/src/test-utils/jest-matchers.ts",
+  ],
+  collectCoverage: !argv.includes("--no-coverage"),
+  coverageDirectory: "coverage",
+  coverageReporters: ["text", "lcov", "html"],
+  collectCoverageFrom: [
+    "src/**/*.ts",
+    // We have to include dist/*js because there are integration tests that
+    // import/require the root package directory:
+    "dist/*js",
+  ],
+  coveragePathIgnorePatterns: [
+    "exports",
+    "setup",
+    "/test-utils/",
+    "\.d.ts$",
+    "/types/",
+    ...otherPlatforms,
+  ],
+  coverageThreshold: {
+    // As of 20250106 on linux:
+    // % Stmts | % Branch | % Funcs | % Lines
+    //   93.63 |    87.05 |   91.86 |   93.63
+    // As of 20250106 on darwin:
+    // % Stmts | % Branch | % Funcs | % Lines
+    //   85.91 |    84.03 |   88.69 |   85.91
+    // As of 20250106 on windows:
+    // % Stmts | % Branch | % Funcs | % Lines
+    //   85.91 |    84.03 |   88.69 |   85.91
+    global: {
+      statements: 80,
+      branches: 80,
+      functions: 80,
+      lines: 80,
+    },
+  },
+};
+
+module.exports = baseConfig;

package/jest.config.cjs

@@ -1,15 +1,11 @@
 // @ts-check
 
-/** @type {import('ts-jest').JestConfigWithTsJest} */
+const baseConfig = require("./jest.config.base.cjs");
 
+/** @type {import('ts-jest').JestConfigWithTsJest} */
 const config = {
+  ...baseConfig,
   displayName: "@photostructure/fs-metadata (CJS)",
-  testEnvironment: "jest-environment-node",
-  roots: ["<rootDir>/src"],
-  coverageProvider: "v8",
-  moduleNameMapper: {
-    "^(\\.{1,2}/.*)\\.js$": "$1",
-  },
   transform: {
     "^.+\\.(c)?ts$": [
       "ts-jest",
@@ -19,15 +15,6 @@ const config = {
       },
     ],
   },
-  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
-  collectCoverage: false,
-  verbose: true,
-  silent: false,
-  randomize: true,
-  setupFilesAfterEnv: [
-    "jest-extended/all",
-    "<rootDir>/src/test-utils/jest-matchers.ts",
-  ],
 };
 
 module.exports = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/types/index.d.ts",
@@ -26,18 +26,14 @@
     "compile:esm": "tsc -p tsconfig.esm.json --noEmit",
     "compile:cjs": "tsc -p tsconfig.cjs.json --noEmit",
     "compile:types": "tsc -p tsconfig.types.json",
-    "postcompile:types": "mv dist/types/index.d.mts dist/types/index.d.ts",
-    "watch": "tsc --watch",
     "bundle": "run-p bundle:* compile:types",
-    "bundle:cjs": "tsup src/index.cts --format cjs --tsconfig tsconfig.cjs.json",
-    "bundle:esm": "tsup src/index.mts --format esm --tsconfig tsconfig.esm.json",
-    "docs": "typedoc --tsconfig tsconfig.esm.json --out docs src/index.mts",
-    "jest:coverage": "jest --coverage",
-    "jest:watch": "npm t -- --watch",
-    "jest:clear": "jest --clearCache",
+    "bundle:cjs": "tsup src/index.ts --format cjs --tsconfig tsconfig.cjs.json",
+    "bundle:esm": "tsup src/index.ts --format esm --tsconfig tsconfig.esm.json",
+    "docs": "typedoc --tsconfig tsconfig.esm.json --out docs src/index.ts",
     "// tests": "`compile` validates the typescript compiles with tsc. `lint` checks for style issues. `bundle` uses tsup to emit the CJS and ESM rollups that the integration tests depend on. `test:*` runs the tests.",
+    "// test": "support `npm t name_of_file` (and don't fail due to missing coverage)",
+    "test": "npm run test:cjs -- --no-coverage",
     "tests": "run-s compile lint bundle test:*",
-    "test": "npm run test:cjs",
     "test:cjs": "jest --config jest.config.cjs",
     "test:esm": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js --config jest.config.mjs",
     "// test:memory:todo": "set up valgrind or similar",
@@ -52,7 +48,7 @@
     "fmt:json": "prettier --write \"**/*.json\"",
     "fmt:pkg": "npm pkg fix",
     "fmt:ts": "prettier --write \"**/*.(c|m)?ts\"",
-    "precommit": "run-s fmt clean prebuild tests snyk",
+    "precommit": "run-s fmt clean prebuild tests",
     "prepare-release": "npm run bundle",
     "release": "release-it"
   },
@@ -89,9 +85,9 @@
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.10.3",
-    "@typescript-eslint/eslint-plugin": "^8.19.0",
-    "@typescript-eslint/parser": "^8.19.0",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.19.1",
+    "@typescript-eslint/parser": "^8.19.1",
     "cross-env": "^7.0.3",
     "del-cli": "^6.0.0",
     "eslint": "^9.17.0",
@@ -110,8 +106,9 @@
     "terser": "^5.37.0",
     "ts-jest": "^29.2.5",
     "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
     "typedoc": "^0.27.6",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.19.0"
+    "typescript-eslint": "^8.19.1"
   }
 }

package/src/async.ts

@@ -2,6 +2,7 @@ import { availableParallelism } from "node:os";
 import { env } from "node:process";
 import { gt0, isNumber } from "./number.js";
 import { isBlank } from "./string.js";
+import { DayMs } from "./units.js";
 
 /**
  * An error that is thrown when a promise does not resolve within the specified
@@ -53,6 +54,14 @@ export async function withTimeout<T>(opts: {
     );
   }
 
+  if (timeoutMs > DayMs) {
+    throw new TypeError(
+      desc +
+        ": Invalid timeoutMs is too large: must be less than one day, but got " +
+        timeoutMs,
+    );
+  }
+
   if (timeoutMs === 0) {
     return opts.promise;
   }

package/src/debuglog.ts

@@ -1,7 +1,11 @@
 import { debuglog, format } from "node:util";
-import { defer } from "./defer.js";
 
-// allow tests to reset the debug log context
+// inlined as a hack to get around relative imports broken in ts-node (used by
+// the debuglog tests):
+function defer<T>(thunk: () => T) {
+  let t: T;
+  return () => (t ??= thunk());
+}
 
 export const debugLogContext = defer(() => {
   for (const ea of ["fs-metadata", "fs-meta"]) {

package/src/defer.ts

@@ -1,6 +1,6 @@
 // src/defer.ts
 
-type Defer<T> = (() => T) & {
+export type Defer<T> = (() => T) & {
   reset: () => void;
 };
 

package/src/dirname.ts

@@ -0,0 +1,13 @@
+import { getCallerDirname } from "./stack_path";
+
+// Thanks to tsup shims, __dirname should always be defined except when run by
+// jest (which will use the stack_path shim)
+export function _dirname() {
+  try {
+    if (typeof __dirname !== "undefined") return __dirname;
+  } catch {
+    // ignore
+  }
+  // we must be in jest. Use the stack_path ~~hack~~ shim:
+  return getCallerDirname();
+}

package/src/global.d.ts

@@ -0,0 +1 @@
+/// <reference types="jest-extended" />

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),
   };
 }