@photostructure/fs-metadata 0.3.3 → 0.5.0

package/dist/types/object.d.ts

@@ -1,13 +0,0 @@
-/**
- * Check if a value is an object
- */
-export declare function isObject(value: unknown): value is object;
-/**
- * Map a value to another value, or undefined if the value is undefined
- */
-export declare function map<T, U>(obj: T | undefined, fn: (value: T) => U): U | undefined;
-/**
- * Omit the specified fields from an object
- */
-export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K>;
-export declare function compactValues<T extends object>(obj: T | undefined): Partial<T>;

package/dist/types/options.d.ts

@@ -1,33 +0,0 @@
-import type { Options } from "./types/options.js";
-/**
- * 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 declare const TimeoutMsDefault: 5000;
-/**
- * System paths and globs that indicate system volumes
- */
-export declare const SystemPathPatternsDefault: string[];
-/**
- * Filesystem types that indicate system volumes
- */
-export declare const SystemFsTypesDefault: readonly ["autofs", "binfmt_misc", "cgroup", "cgroup2", "configfs", "debugfs", "devpts", "devtmpfs", "efivarfs", "fusectl", "fuse.snapfuse", "hugetlbfs", "mqueue", "none", "proc", "pstore", "rootfs", "securityfs", "snap*", "squashfs", "sysfs", "tmpfs"];
-export declare const LinuxMountTablePathsDefault: readonly ["/proc/self/mounts", "/proc/mounts", "/etc/mtab"];
-/**
- * Should {@link getAllVolumeMetadata} include system volumes by
- * default?
- */
-export declare const IncludeSystemVolumesDefault: boolean;
-/**
- * Default {@link Options} object.
- *
- * @see {@link optionsWithDefaults} for creating an options object with default values
- */
-export declare const OptionsDefault: Options;
-/**
- * Create an {@link Options} object using default values from
- * {@link OptionsDefault} for missing fields.
- */
-export declare function optionsWithDefaults<T extends Options>(overrides?: Partial<T>): T;

package/dist/types/path.d.ts

@@ -1,17 +0,0 @@
-export declare function normalizePath(mountPoint: string | undefined): string | undefined;
-/**
- * Normalizes a Linux or macOS mount point by removing any trailing slashes.
- * This is a no-op for root mount points.
- */
-export declare function normalizePosixPath(mountPoint: string | undefined): string | undefined;
-/**
- * Normalizes a Windows mount point by ensuring drive letters end with a
- * backslash.
- */
-export declare function normalizeWindowsPath(mountPoint: string): string;
-/**
- * @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 declare function isRootDirectory(path: string): boolean;

package/dist/types/platform.d.ts

@@ -1,4 +0,0 @@
-export declare const isLinux: boolean;
-export declare const isWindows: boolean;
-export declare const isMacOS: boolean;
-export declare const isArm: boolean;

package/dist/types/random.d.ts

@@ -1,12 +0,0 @@
-/**
- * @return a random character `[a-z]`
- */
-export declare function randomLetter(): string;
-export declare function randomLetters(length: number): string;
-/**
- * Shuffle an array using the Fisher-Yates (Knuth) algorithm.
- * @param a The array to shuffle
- * @returns A shallow shuffled copy of `a`
- */
-export declare function shuffle<T>(a: T[]): T[];
-export declare function pickRandom<T>(a: T[]): T;

package/dist/types/remote_info.d.ts

@@ -1,6 +0,0 @@
-import { RemoteInfo } from "./types/remote_info.js";
-export declare function isRemoteInfo(obj: unknown): obj is RemoteInfo;
-export declare function normalizeFsType(fstype: string): string;
-export declare function isRemoteFsType(fstype: string | undefined): boolean;
-export declare function parseURL(s: string): URL | undefined;
-export declare function extractRemoteInfo(fsSpec: string | undefined): RemoteInfo | undefined;

package/dist/types/stack_path.d.ts

@@ -1,2 +0,0 @@
-export declare function getCallerDirname(): string;
-export declare function extractCallerPath(stack: string): string;

package/dist/types/string.d.ts

@@ -1,37 +0,0 @@
-export declare function isString(input: unknown): input is string;
-export declare function toS(input: unknown): string;
-/**
- * @return true iff the input is a string and has at least one non-whitespace character
- */
-export declare function isNotBlank(input: unknown): input is string;
-/**
- * @return true iff the input is not a string or only has non-whitespace characters
- */
-export declare function isBlank(input: unknown): input is undefined;
-export declare function toNotBlank(input: unknown): string | 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 declare function decodeEscapeSequences(input: string): string;
-export declare function encodeEscapeSequences(input: string): string;
-/**
- * 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 declare function sortByLocale(arr: string[], locales?: Intl.LocalesArgument, options?: Intl.CollatorOptions): string[];
-/**
- * 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 declare function sortObjectsByLocale<T>(arr: T[], fn: (key: T) => string, locales?: Intl.LocalesArgument, options?: Intl.CollatorOptions): T[];

package/dist/types/string_enum.d.ts

@@ -1,19 +0,0 @@
-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 declare function stringEnum<T extends string>(...o: T[]): StringEnum<T>;

package/dist/types/system_volume.d.ts

@@ -1,14 +0,0 @@
-import type { MountPoint } from "./types/mount_point.js";
-import type { Options } from "./types/options.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 declare function isSystemVolume(mountPoint: string, fstype: string | undefined, config?: Partial<SystemVolumeConfig>): boolean;
-export declare function assignSystemVolume(mp: MountPoint, config: Partial<SystemVolumeConfig>): void;

package/dist/types/types/hidden_metadata.d.ts

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

package/dist/types/types/mount_point.d.ts

@@ -1,46 +0,0 @@
-import type { 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;
-}

package/dist/types/types/native_bindings.d.ts

@@ -1,51 +0,0 @@
-import type { 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/dist/types/types/options.d.ts

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

package/dist/types/types/remote_info.d.ts

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

package/dist/types/types/volume_metadata.d.ts

@@ -1,46 +0,0 @@
-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/dist/types/unc.d.ts

@@ -1,11 +0,0 @@
-import { RemoteInfo } from "./types/remote_info.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 declare function parseUNCPath(path: string | null | undefined): RemoteInfo | undefined;

package/dist/types/units.d.ts

@@ -1,38 +0,0 @@
-/**
- * Milliseconds in a second
- */
-export declare const SecondMs = 1000;
-/**
- * Milliseconds in a minute
- */
-export declare const MinuteMs: number;
-/**
- * Milliseconds in an hour
- */
-export declare const HourMs: number;
-/**
- * Milliseconds in a day
- */
-export declare const DayMs: number;
-/**
- * Kibibyte (KiB) = 1024 bytes
- * @see https://en.wikipedia.org/wiki/Kibibyte
- */
-export declare const KiB = 1024;
-/**
- * Mebibyte (MiB) = 1024 KiB
- * @see https://en.wikipedia.org/wiki/Mebibyte
- */
-export declare const MiB: number;
-/**
- * Gibibyte (GiB)= 1024 MiB
- * @see https://en.wikipedia.org/wiki/Gibibyte
- */
-export declare const GiB: number;
-/**
- * Tebibyte (TiB) = 1024 GiB
- *
- * @see https://en.wikipedia.org/wiki/Byte#Multiple-byte_units
- */
-export declare const TiB: number;
-export declare function fmtBytes(bytes: number): string;

package/dist/types/uuid.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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 declare function extractUUID(uuid: string | undefined): string | undefined;

package/dist/types/volume_health_status.d.ts

@@ -1,24 +0,0 @@
-import { canReaddir } from "./fs.js";
-import { 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 declare const VolumeHealthStatuses: import("./string_enum.js").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 declare function directoryStatus(dir: string, timeoutMs: number, canReaddirImpl?: typeof canReaddir): Promise<{
-    status: VolumeHealthStatus;
-    error?: Error;
-}>;

package/dist/types/volume_metadata.d.ts

@@ -1,8 +0,0 @@
-import type { GetVolumeMetadataOptions, NativeBindingsFn } from "./types/native_bindings.js";
-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[]>;

package/dist/types/volume_mount_points.d.ts

@@ -1,6 +0,0 @@
-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>;
-export declare function getVolumeMountPointsImpl(opts: Required<GetVolumeMountPointOptions>, nativeFn: NativeBindingsFn): Promise<MountPoint[]>;

package/jest.config.base.cjs

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