scandirectory/edition-types/index.d.ts

Scan a directory recursively with a lot of control and power

/// <reference types="node" />
/// <reference types="node" />
import { Stats } from 'fs';
import { Options as IgnoreOptions } from 'ignorefs';
/** Encoding types that will return a string */
export type StringEncoding = Exclude<BufferEncoding, 'binary'>;
/** Encoding that will return a string, a buffer, or not be used at all. */
export type ResultEncoding = BufferEncoding | undefined;
/** A type of result, unknown is a WIP. */
export type ResultType = 'unknown' | 'file' | 'dir';
/** The result object */
export interface Result<Type extends ResultType, Encoding extends ResultEncoding = undefined> {
    absolutePath: string;
    relativePath: string;
    basename: string;
    directory: Type extends 'unknown' ? null : Type extends 'dir' ? true : Type extends 'file' ? false : never;
    stats: Type extends 'unknown' ? null : Type extends 'dir' | 'file' ? Stats : never;
    parent: null | Result<'dir', Encoding>;
    children: Type extends 'unknown' | 'file' ? null : Record<string, Result<ResultType, Encoding>>;
    data: Type extends 'unknown' | 'dir' ? null : Type extends 'file' ? Encoding extends undefined ? null : Encoding extends StringEncoding ? string : Buffer : never;
}
/**
 * A mapping of all relative paths to {@link Result}
 * If you want a tree, specify {@link Options.includeRoot} as true and use `results['.'].children`
 */
export interface Results<Encoding extends ResultEncoding = undefined> {
    [relativePath: string]: Result<'file' | 'dir', Encoding>;
}
/**
 * Support old action callback format for {@link scanDirectoryCompatibility}
 * @deprecated use {@link ActionCallback} instead
 * @returns `false` if you wish to discard this result and not recurse into it
 */
export type CompatibilityActionCallback<Type extends 'file' | 'dir' = 'file' | 'dir'> = (absolutePath: string, relativePath: string, basename?: string, stat?: Stats & {
    directory: Type extends 'file' ? false : Type extends 'dir' ? true : boolean;
}) => boolean | void;
/**
 * Action callback for {@link scanDirectory}
 * @returns `false` if you wish to discard this result and not recurse into it
 */
export type ActionCallback<Type extends 'file' | 'dir' = 'file' | 'dir', Encoding extends ResultEncoding = undefined> = (result: Result<Type, Encoding>) => boolean | void;
/** Options to configure {@link scanDirectory} and its ignore handling. */
export interface BaseOptions<Encoding extends ResultEncoding = undefined> extends IgnoreOptions {
    /** Directory path to scan */
    directory: string;
    /** Whether to traverse directories */
    recurse?: boolean;
    /** The encoding to read files as */
    encoding?: Encoding;
    /**
     * Include the root {@link Options.directory} in the result listing?
     * If you want pure tree results, set this to true, then use `results['.'].children` as your listing.
     */
    includeRoot?: boolean;
}
/** Options to configure {@link scanDirectory} and its ignore handling. */
export interface Options<Encoding extends ResultEncoding = undefined> extends BaseOptions<Encoding> {
    /** Callback invoked on files and directories */
    action?: ActionCallback<'file' | 'dir', Encoding>;
    /** Callback invoked on files, set to false to ignore files */
    fileAction?: ActionCallback<'file', Encoding> | false;
    /** Callback invoked on directories, set to false to ignore directories */
    dirAction?: ActionCallback<'dir', Encoding> | false;
}
/** List-style result for  {@link scanDirectoryCompatibility} */
export type List<Encoding extends ResultEncoding = undefined> = {
    [relativePath: string]: (Encoding extends undefined ? 'file' : Encoding extends StringEncoding ? string : Buffer) | 'dir';
};
/** Tree-style result for  {@link scanDirectoryCompatibility} */
export type Tree<Encoding extends ResultEncoding = undefined> = {
    [relativePath: string]: (Encoding extends undefined ? true : Encoding extends StringEncoding ? string : Buffer) | Tree<Encoding>;
};
/** Generate results for  {@link scanDirectoryCompatibility} */
export type CompatibilityNextCallback<Encoding extends ResultEncoding = undefined> = (error?: Error | null, list?: List<Encoding>, tree?: Tree<Encoding>) => void;
/** Options to configure {@link scanDirectoryCompatibility} and its ignore handling. */
export interface CompatibilityOptions<Encoding extends ResultEncoding = undefined> extends Partial<BaseOptions<Encoding>> {
    /** @deprecated alias for {@link Options.directory} */
    path?: string;
    /** @deprecated use {@link options.encoding} */
    readFiles?: never;
    /** @deprecated use {@link scanDirectory} */
    next?: CompatibilityNextCallback<Encoding>;
    /** Callback invoked on files and directories */
    action?: ActionCallback<'file' | 'dir', Encoding> | CompatibilityActionCallback;
    /** Callback invoked on files, set to false to ignore files */
    fileAction?: ActionCallback<'file', Encoding> | CompatibilityActionCallback<'file'> | false;
    /** Callback invoked on directories, set to false to ignore directories */
    dirAction?: ActionCallback<'dir', Encoding> | CompatibilityActionCallback<'file'> | false;
}
/** Scan the contents of a directory */
export declare function scanDirectory<Encoding extends ResultEncoding>(opts: Options<Encoding>): Promise<Results<Encoding>>;
/** Scan the contents of a directory, with compatibility for scandirectory < v8 */
export default function scanDirectoryCompatibility<Encoding extends ResultEncoding = undefined>(...args: Array<string | CompatibilityNextCallback<Encoding> | CompatibilityOptions<Encoding>>): Promise<Results<Encoding>>;
/** Compatibility helper for {@link scanDirectoryCompatibility} to generate results compatible with {@link CompatibilityNextCallback} */
export declare function toList<Encoding extends ResultEncoding = undefined>(results: Results<Encoding>): List<Encoding>;
/** Compatibility helper for {@link scanDirectoryCompatibility} to generate results compatible with {@link CompatibilityNextCallback} */
export declare function toTree<Encoding extends ResultEncoding = undefined>(results: Results<Encoding> | null, descending?: boolean): Tree<Encoding>;
/** Convert {@link Results} into a non-recursive JSON string */
export declare function stringify(any: any, indentation?: string): string;
//# sourceMappingURL=index.d.ts.map