@photostructure/fs-metadata 0.3.2 → 0.3.3

package/src/types/volume_metadata.ts

@@ -0,0 +1,52 @@
+// src/types/volume_metadata.ts
+
+import type { MountPoint } from "./mount_point.js";
+import type { RemoteInfo } from "./remote_info.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;
+}

package/src/unc.ts

@@ -1,7 +1,7 @@
 // src/unc.ts
 
-import { RemoteInfo } from "./remote_info.js";
 import { isBlank, isString } from "./string.js";
+import { RemoteInfo } from "./types/remote_info.js";
 
 /**
  * Checks if a string is formatted as a valid UNC path.

package/src/units.ts

@@ -1,31 +1,63 @@
 // src/units.ts
 
 /**
- * KiB = 1024 bytes
+ * Milliseconds in a second
+ */
+export const SecondMs = 1000;
+
+/**
+ * Milliseconds in a minute
+ */
+export const MinuteMs = 60 * SecondMs;
+
+/**
+ * Milliseconds in an hour
+ */
+export const HourMs = 60 * MinuteMs;
+
+/**
+ * Milliseconds in a day
+ */
+export const DayMs = 24 * HourMs;
+
+/**
+ * Kibibyte (KiB) = 1024 bytes
  * @see https://en.wikipedia.org/wiki/Kibibyte
  */
 export const KiB = 1024;
 
 /**
- * MiB = 1024 KiB
+ * Mebibyte (MiB) = 1024 KiB
  * @see https://en.wikipedia.org/wiki/Mebibyte
  */
 export const MiB = 1024 * KiB;
 
 /**
- * GiB = 1024 MiB
+ * Gibibyte (GiB)= 1024 MiB
  * @see https://en.wikipedia.org/wiki/Gibibyte
  */
 export const GiB = 1024 * MiB;
 
+/**
+ * Tebibyte (TiB) = 1024 GiB
+ *
+ * @see https://en.wikipedia.org/wiki/Byte#Multiple-byte_units
+ */
+export const TiB = 1024 * GiB;
+
+const f = 1023.995 / 1024;
+
 export function fmtBytes(bytes: number): string {
-  if (bytes < KiB) {
+  if (bytes < 1023.5) {
+    bytes = Math.round(bytes);
     return `${bytes} B`;
-  } else if (bytes < MiB) {
+  } else if (bytes < MiB * f) {
     return `${(bytes / KiB).toFixed(2)} KiB`;
-  } else if (bytes < GiB) {
+  } else if (bytes < GiB * f) {
     return `${(bytes / MiB).toFixed(2)} MiB`;
-  } else {
+  } else if (bytes < TiB * f) {
     return `${(bytes / GiB).toFixed(2)} GiB`;
+  } else {
+    return `${(bytes / TiB).toFixed(2)} TiB`;
   }
 }

package/src/volume_metadata.ts

@@ -9,83 +9,28 @@ import {
   type MtabVolumeMetadata,
   mountEntryToPartialVolumeMetadata,
 } from "./linux/mtab.js";
-import type { MountPoint } from "./mount_point.js";
 import { compactValues } from "./object.js";
-import {
-  IncludeSystemVolumesDefault,
-  type Options,
-  optionsWithDefaults,
-} from "./options.js";
+import { IncludeSystemVolumesDefault, optionsWithDefaults } from "./options.js";
 import { normalizePath } from "./path.js";
 import { isLinux, isWindows } from "./platform.js";
-import {
-  type RemoteInfo,
-  extractRemoteInfo,
-  isRemoteFsType,
-} from "./remote_info.js";
+import { extractRemoteInfo, isRemoteFsType } from "./remote_info.js";
 import { isBlank, isNotBlank } from "./string.js";
 import { assignSystemVolume } from "./system_volume.js";
 import type {
   GetVolumeMetadataOptions,
   NativeBindingsFn,
 } from "./types/native_bindings.js";
+import type { Options } from "./types/options.js";
+import type { VolumeMetadata } from "./types/volume_metadata.js";
 import { parseUNCPath } from "./unc.js";
 import { extractUUID } from "./uuid.js";
 import {
   VolumeHealthStatuses,
   directoryStatus,
 } from "./volume_health_status.js";
-import { getVolumeMountPoints } from "./volume_mount_points.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;
+import { getVolumeMountPointsImpl } from "./volume_mount_points.js";
 
-  /**
-   * 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 async function getVolumeMetadata(
+export async function getVolumeMetadataImpl(
   o: GetVolumeMetadataOptions & Options,
   nativeFn: NativeBindingsFn,
 ): Promise<VolumeMetadata> {
@@ -211,7 +156,7 @@ async function _getVolumeMetadata(
   return compactValues(result) as VolumeMetadata;
 }
 
-export async function getAllVolumeMetadata(
+export async function getAllVolumeMetadataImpl(
   opts: Required<Options> & {
     includeSystemVolumes?: boolean;
     maxConcurrency?: number;
@@ -221,7 +166,7 @@ export async function getAllVolumeMetadata(
   const o = optionsWithDefaults(opts);
   debug("[getAllVolumeMetadata] starting with options: %o", o);
 
-  const arr = await getVolumeMountPoints(o, nativeFn);
+  const arr = await getVolumeMountPointsImpl(o, nativeFn);
   debug("[getAllVolumeMetadata] found %d mount points", arr.length);
 
   const unhealthyMountPoints = arr
@@ -269,7 +214,7 @@ export async function getAllVolumeMetadata(
         ? healthy
         : healthy.filter((ea) => !ea.isSystemVolume),
     fn: async (mp) =>
-      getVolumeMetadata({ ...mp, ...o }, nativeFn).catch((error) => ({
+      getVolumeMetadataImpl({ ...mp, ...o }, nativeFn).catch((error) => ({
         mountPoint: mp.mountPoint,
         error,
       })),
@@ -290,5 +235,3 @@ export async function getAllVolumeMetadata(
         }) as VolumeMetadata,
   );
 }
-
-export const _ = undefined;

package/src/volume_mount_points.ts

@@ -4,9 +4,7 @@ import { uniqBy } from "./array.js";
 import { mapConcurrent, withTimeout } from "./async.js";
 import { debug } from "./debuglog.js";
 import { getLinuxMountPoints } from "./linux/mount_points.js";
-import { MountPoint } from "./mount_point.js";
 import { compactValues } from "./object.js";
-import { Options } from "./options.js";
 import { isMacOS, isWindows } from "./platform.js";
 import {
   isBlank,
@@ -15,7 +13,9 @@ import {
   toNotBlank,
 } from "./string.js";
 import { assignSystemVolume, 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";
 import { directoryStatus } from "./volume_health_status.js";
 
 export type GetVolumeMountPointOptions = Partial<
@@ -29,10 +29,7 @@ export type GetVolumeMountPointOptions = Partial<
     SystemVolumeConfig
 >;
 
-/**
- * Helper function for {@link getVolumeMountPoints}.
- */
-export async function getVolumeMountPoints(
+export async function getVolumeMountPointsImpl(
   opts: Required<GetVolumeMountPointOptions>,
   nativeFn: NativeBindingsFn,
 ): Promise<MountPoint[]> {

package/tsup.config.ts

@@ -4,5 +4,6 @@ export default defineConfig({
   outExtension: ({ format }) => ({
     js: format === "cjs" ? ".cjs" : ".mjs", // Use .cjs for CommonJS and .mjs for ESM
   }),
+  shims: true,
   sourcemap: true,
 });

package/dist/types/exports.d.ts

@@ -1,99 +0,0 @@
-import type { HiddenMetadata, HideMethod, SetHiddenResult } from "./hidden.js";
-import type { MountPoint } from "./mount_point.js";
-import type { Options } from "./options.js";
-import { IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, OptionsDefault, optionsWithDefaults, SystemFsTypesDefault, SystemPathPatternsDefault, TimeoutMsDefault } from "./options.js";
-import type { StringEnum, StringEnumKeys, StringEnumType } from "./string_enum.js";
-import type { SystemVolumeConfig } from "./system_volume.js";
-import type { VolumeHealthStatus } from "./volume_health_status.js";
-import { VolumeHealthStatuses } from "./volume_health_status.js";
-import type { VolumeMetadata } from "./volume_metadata.js";
-import type { GetVolumeMountPointOptions } from "./volume_mount_points.js";
-export type { GetVolumeMountPointOptions, HiddenMetadata, HideMethod, MountPoint, Options, SetHiddenResult, StringEnum, StringEnumKeys, StringEnumType, SystemVolumeConfig, VolumeHealthStatus, VolumeMetadata, };
-/**
- * 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
- */
-export 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
- */
-export 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 getVolumeMountPoints}, as well as **each** {@link getVolumeMetadata}
- * 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(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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export declare 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;
-};
-export { IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, OptionsDefault, optionsWithDefaults, SystemFsTypesDefault, SystemPathPatternsDefault, TimeoutMsDefault, VolumeHealthStatuses, };

package/dist/types/setup.d.ts

@@ -1,2 +0,0 @@
-import { ExportedFunctions } from "./exports.js";
-export declare function setup(dirname: string): ExportedFunctions;

package/src/index.cts

@@ -1,15 +0,0 @@
-// src/index.cts
-
-import { setup } from "./setup.js";
-
-export * from "./exports.js";
-
-export const {
-  getVolumeMountPoints,
-  getVolumeMetadata,
-  getAllVolumeMetadata,
-  isHidden,
-  isHiddenRecursive,
-  getHiddenMetadata,
-  setHidden,
-} = setup(__dirname);

package/src/index.mts

@@ -1,17 +0,0 @@
-// src/index.mts
-
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { setup } from "./setup.js";
-
-export * from "./exports.js";
-
-export const {
-  getVolumeMountPoints,
-  getVolumeMetadata,
-  getAllVolumeMetadata,
-  isHidden,
-  isHiddenRecursive,
-  getHiddenMetadata,
-  setHidden,
-} = setup(dirname(fileURLToPath(import.meta.url)));

package/src/setup.ts

@@ -1,69 +0,0 @@
-// 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;
-}