dree/bundled/lib/esm/index.d.ts

A nodejs module wich helps you handle a directory tree providing you its abstraction through tested functions and a custom configuration.

// Generated by dts-bundle-generator v9.5.1

import { BinaryToTextEncoding } from 'node:crypto';
import { Stats } from 'node:fs';

/**
 * Enum whose values are DIRECTORY or FILE
 */
export declare enum Type {
	DIRECTORY = "directory",
	FILE = "file"
}
/**
 * Callback used by [[scan]] when a file or dir is encountered.
 * Note that it can extend the node that will be returned in the directory tree.
 * @template Node The type of the tree object, which can be extended and changed by the onFile and onDir functions.
 */
export type Callback<Node extends Dree = Dree> = (dirTree: Node, stat: Stats) => void;
/**
 * Callback used by [[scanAsync]] when a file or dir is encountered.
 * Note that it can extend the node that will be returned in the directory tree.
 * @template Node The type of the tree object, which can be extended and changed by the onFile and onDir functions.
 */
export type CallbackAsync<Node extends Dree = Dree> = (dirTree: Node, stat: Stats) => void | Promise<void>;
/**
 * Enum whose values are used to determine how the paths should be sorted
 */
export declare enum SortMethodPredefined {
	/** Alphabetical order */
	ALPHABETICAL = "alpha",
	/** Alphabetical order, reversed */
	ALPHABETICAL_REVERSE = "antialpha",
	/** Alphabetical order, case insensitive */
	ALPHABETICAL_INSENSITIVE = "alpha-insensitive",
	/** Alphabetical order, reversed, case insensitive */
	ALPHABETICAL_INSENSITIVE_REVERSE = "antialpha-insensitive"
}
/**
 * Function used to sort paths
 */
export type SortDiscriminator = (x: string, y: string) => number;
/**
 * Enum whose values are used to determine how the nodes should be sorted. Differently from [[SortMethodPredefined]],
 * it specifies the behavior of the sorting after all the children of a folder are scanned.
 */
export declare enum PostSortMethodPredefined {
	/** Alphabetical order */
	ALPHABETICAL = "alpha",
	/** Alphabetical order, reversed */
	ALPHABETICAL_REVERSE = "antialpha",
	/** Alphabetical order, case insensitive */
	ALPHABETICAL_INSENSITIVE = "alpha-insensitive",
	/** Alphabetical order, reversed, case insensitive */
	ALPHABETICAL_INSENSITIVE_REVERSE = "antialpha-insensitive",
	/** Folders first, files after */
	FOLDERS_FIRST = "folders-first",
	/** Files first, folders after */
	FILES_FIRST = "files-first"
}
/**
 * Function used to sort nodes
 */
export type PostSortDiscriminator = (x: Dree, y: Dree) => number;
/**
 * Interface of an object representing a Directory Tree
 */
export interface Dree {
	/**
	 *  The name of the node as a string
	 */
	name: string;
	/**
	 * The absolute path of the node
	 */
	path: string;
	/**
	 * The relative path from the root of the node
	 */
	relativePath: string;
	/**
	 * Values: Type.DIRECTORY or Type.FILE
	 */
	type: Type;
	/**
	 * A boolean with true value if the node is a symbolic link
	 */
	isSymbolicLink: boolean;
	/**
	 * Optional. The size in bytes of the node
	 */
	sizeInBytes?: number;
	/**
	 * Optional. The size of the node, rounded to two decimals and appropriate unit
	 */
	size?: string;
	/**
	 * Optional. The hash of the node
	 */
	hash?: string;
	/**
	 * Optional. The extension (without dot) of the node. Returned only if the node is a file
	 */
	extension?: string;
	/**
	 * Optional. True if the node is a directory and contains no files and no directories
	 */
	isEmpty?: boolean;
	/**
	 * Optional. The fs.lstat or fs.fstat of the node
	 */
	stat?: Stats;
	/**
	 * Optional. The number of descendants of the node. Returned only if the node is a directory and [[descendants]] option is specified
	 */
	descendants?: number;
	/**
	 * Optional. An array of Dree objects, containing all the children of the node
	 */
	children?: Dree[];
}
/**
 * Interface of the options object used with "scan" function
 */
export interface ScanOptions {
	/**
	 * If true every node of the result will contain stat property, provided by fs.lstat or fs.stat
	 */
	stat?: boolean;
	/**
	 * If true, on windows, normalize each path replacing each backslash \\\\ with a slash /
	 */
	normalize?: boolean;
	/**
	 * If true, all symbolic links found will be included in the result. Could not work on Windows
	 */
	symbolicLinks?: boolean;
	/**
	 * If true, all symbolic links will be followed, including even their content if they link to a folder.
	 * Could not work on Windows
	 */
	followLinks?: boolean;
	/**
	 * If true, every node in the result will contain sizeInBytes property as the number of bytes of the content.
	 * If a node is a folder, only its considered inner files will be computed to have this size
	 */
	sizeInBytes?: boolean;
	/**
	 * If true, every node in the result will contain size property. Same as sizeInBytes, but it
	 * is a string rounded to the second decimal digit and with an appropriate unit
	 */
	size?: boolean;
	/**
	 * If true, every node in the result will contain hash property, computed by taking in consideration
	 * the name and the content of the node. If the node is a folder, all his considered inner files will be used by the algorithm
	 */
	hash?: boolean;
	/**
	 * Hash algorithm used by cryptojs to return the hash
	 */
	hashAlgorithm?: "md5" | "sha1";
	/**
	 * Hash encoding used by cryptojs to return the hash
	 */
	hashEncoding?: BinaryToTextEncoding;
	/**
	 * If true, all hidden files and dirs will be included in the result. A hidden file or a directory
	 * has a name which starts with a dot and in some systems like Linux are hidden
	 */
	showHidden?: boolean;
	/**
	 * It is a number which says the max depth the algorithm can reach scanning the given path.
	 * All files and dirs which are beyound the max depth will not be considered by the algorithm
	 */
	depth?: number;
	/**
	 * It is a regex, string (glob patterns) or array of them and all the matching paths will not be considered by the algorithm.
	 */
	exclude?: string | RegExp | (RegExp | string)[];
	/**
	 * It is a regex, string (glob pattern) or array of them and all the non-matching paths will not be considered by the algorithm. Note: All the
	 * ancestors of a matching node will be added.
	 */
	matches?: string | RegExp | (RegExp | string)[];
	/**
	 * It is an array of strings and all the files whose extension is not included in that array will be skipped by the algorithm.
	 * If value is undefined, all file extensions will be considered, if it is [], no files will be included
	 */
	extensions?: string[];
	/**
	 * If true, every node of type directory in the result will contain isEmpty property, which will be true if the folder contains
	 * no files and no directories
	 */
	emptyDirectory?: boolean;
	/**
	 * If true, every empty directory will be excluded from the result. If the directory is not empty but all the contained files
	 * and directories are excluded by other options such as exclude or extensions, the directory will not be included in the result
	 */
	excludeEmptyDirectories?: boolean;
	/**
	 * If true, also the number of descendants of each node will be added to the result.
	 */
	descendants?: boolean;
	/**
	 * If true, only files will be count as descendants of a node. It does not have effect if [[descendants]] option is not true.
	 */
	descendantsIgnoreDirectories?: boolean;
	/**
	 * If true, directories and files will be scanned ordered by path. The value can be both boolean for default alpha order, a
	 * custom sorting function or a predefined sorting method in [[SortMethodPredefined]].
	 */
	sorted?: boolean | SortMethodPredefined | SortDiscriminator;
	/**
	 * If true, the child nodes of a node will be ordered. The value can be both boolean for default alpha order, a
	 * custom sorting function or a predefined sorting method in [[PostSortMethodPredefined]].
	 */
	postSorted?: boolean | PostSortMethodPredefined | PostSortDiscriminator;
	/**
	 * If true, the unix homedir shortcut ~ will be expanded to the user home directory
	 */
	homeShortcut?: boolean;
	/**
	 * If true, folders whose user has not permissions will be skipped. An error will be thrown otherwise. Note: in fact every
	 * error thrown by fs calls will be ignored
	 */
	skipErrors?: boolean;
}
/**
 * Interface of the symbols used to represent the tree in a string.
 * See [[DEFAULT_SYMBOLS]] for an example with the default values
 */
export interface TreeSymbols {
	dirChild: string;
	fileChild: string;
	forkChild: string;
	lastChild: string;
	linkChild: string;
	tabIndent: string;
	pipeIndent: string;
}
/**
 * Interface of the options object used with "parse" or "parseTree" functions
 */
export interface ParseOptions {
	/**
	 * If true, all symbolic links found will be included in the result. Could not work on Windows
	 */
	symbolicLinks?: boolean;
	/**
	 * If true, all symbolic links will be followed, including even their content if they link to a folder.
	 * Could not work on Windows
	 */
	followLinks?: boolean;
	/**
	 * If true, all hidden files and dirs will be included in the result. A hidden file or a directory
	 * has a name which starts with a dot and in some systems like Linux are hidden
	 */
	showHidden?: boolean;
	/**
	 * It is a number which says the max depth the algorithm can reach scanning the given path.
	 * All files and dirs which are beyound the max depth will not be considered by the algorithm
	 */
	depth?: number;
	/**
	 * It is a regex, string (glob patterns) or array of them and all the matched paths will not be considered by the algorithm
	 */
	exclude?: string | RegExp | (RegExp | string)[];
	/**
	 * It is an array of strings and all the files whose extension is not included in that array will be skipped by the algorithm.
	 * If value is undefined, all file extensions will be considered, if it is [], no files will be included
	 */
	extensions?: string[];
	/**
	 * If true, directories and files will be scanned ordered by path. The value can be both boolean for default alpha order, a
	 * custom sorting function or a predefined sorting method in [[SortMethodPredefined]].
	 */
	sorted?: boolean | SortMethodPredefined | SortDiscriminator;
	/**
	 * If true, the child nodes of a node will be ordered. The value can be both boolean for default alpha order, a
	 * custom sorting function or a predefined sorting method in [[PostSortMethodPredefined]].
	 */
	postSorted?: boolean | PostSortMethodPredefined | PostSortDiscriminator;
	/**
	 * If true, the unix homedir shortcut ~ will be expanded to the user home directory
	 */
	homeShortcut?: boolean;
	/**
	 * Symbols used to represent the tree in a string
	 */
	symbols?: TreeSymbols;
	/**
	 * If true, folders whose user has not permissions will be skipped. An error will be thrown otherwise. Note: in fact every
	 * error thrown by fs calls will be ignored
	 */
	skipErrors?: boolean;
}
/**
 * The default symbols used to represent the tree in a string
 */
export declare const DEFAULT_SYMBOLS: TreeSymbols;
/**
 * The ascii symbols used to represent the tree in a string.
 * Note: Inspiration was taken from the bash command: `tree --charset=ascii`
 */
export declare const ASCII_SYMBOLS: TreeSymbols;
/**
 * Returns the Directory Tree of a given path. This function in synchronous.
 * @param  {string} path The path which you want to inspect
 * @param  {object} options An object used as options of the function
 * @param  {function} onFile A function called when a file is added. It has the tree object and its stat as parameters. The object can me changed and extended here, on typescript there the function uses indeed generics.
 * @param  {function} onDir A function called when a dir is added. It has the tree object and its stat as parameters. The object can me changed and extended here, on typescript there the function uses indeed generics.
 * @return {object} The directory tree as a Dree object
 * @template Node The type of the tree object, which can be extended and changed by the onFile and onDir functions.
 */
export declare function scan<Node extends Dree = Dree>(path: string, options?: ScanOptions, onFile?: Callback<Node>, onDir?: Callback<Node>): Node;
/**
 * Returns in a promise the Directory Tree of a given path. This function is asynchronous.
 * @param  {string} path The path which you want to inspect
 * @param  {object} options An object used as options of the function
 * @param  {function} onFile A function called when a file is added - has the tree object and its stat as parameters
 * @param  {function} onDir A function called when a dir is added - has the tree object and its stat as parameters
 * @return {Promise<object>} A promise to the directory tree as a Dree object
 * @template Node The type of the tree object, which can be extended and changed by the onFile and onDir functions.
 */
export declare function scanAsync<Node extends Dree = Dree>(path: string, options?: ScanOptions, onFile?: CallbackAsync<Node>, onDir?: CallbackAsync<Node>): Promise<Node>;
/**
 * Returns a string representation of a Directory Tree given a path to a directory or file
 * @param  {string} path The path which you want to inspect
 * @param  {object} options An object used as options of the function
 * @return {string} A string representing the Directory Tree of the given path
 */
export declare function parse(path: string, options?: ParseOptions): string;
/**
 * Returns a promise to a string representation of a Directory Tree given a path to a directory or file
 * @param  {string} path The path which you want to inspect
 * @param  {object} options An object used as options of the function
 * @return {Promise<string>} A promise to a string representing the Directory Tree of the given path
 */
export declare function parseAsync(path: string, options?: ParseOptions): Promise<string>;
/**
 * Returns a string representation of a Directory Tree given an object returned from scan
 * @param  {object} dirTree The object returned from scan, which will be parsed
 * @param  {object} options An object used as options of the function
 * @return {string} A string representing the object given as first parameter
 */
export declare function parseTree(dirTree: Dree, options?: ParseOptions): string;
/**
 * Returns a promise to a string representation of a Directory Tree given an object returned from scan
 * @param  {object} dirTree The object returned from scan, which will be parsed
 * @param  {object} options An object used as options of the function
 * @return {Promise<string>} A promise to a string representing the object given as first parameter
 */
export declare function parseTreeAsync(dirTree: Dree, options?: ParseOptions): Promise<string>;

export {};