@sapphire/node-utilities/dist/esm/index.d.mts

Node specific JavaScript utilities for the Sapphire Community

import { PathLike } from 'node:fs';

/**
 *
 * @param path The path in which to find files.
 * @param predicate A predicate function receives the path as a parameter. Truthy values will have the path included, falsey values will have the file excluded.
 *
 * @return An {@link AsyncIterableIterator} of all the files. To loop over these use `for await (const file of findFilesRecursively(path, predicate)) {}`
 *
 * @example
 * ```typescript
 * // With CommonJS: To find all files ending with `.ts` in the src directory:
 * const path = require('node:path');
 *
 * for await (const file of findFilesRecursively(path.join(__dirname, 'src'), (filePath) => filePath.endsWith('.ts'))) {
 *   console.log(file);
 * }
 * ```
 *
 * @example
 * ```typescript
 * // With ESM: To find all files ending with `.ts` in the src directory:
 * for await (const file of findFilesRecursively(new URL('src', import.meta.url), (filePath) => filePath.endsWith('.ts'))) {
 *   console.log(file);
 * }
 * ```
 */
declare function findFilesRecursively(path: PathLike, predicate?: (filePath: string) => boolean): AsyncIterableIterator<string>;
/**
 *
 * @param path The path in which to find files. This can be a string, buffer, or {@link URL}.
 * @param fileStartsWith The string pattern with which the file name must start.
 *
 * Note that we do **not** support a full globby pattern using asterisk for wildcards. It has to be an exact match with {@link String.startsWith}
 *
 * @return An {@link AsyncIterableIterator} of all the files. To loop over these use `for await (const file of findFilesRecursivelyStringStartsWith(path, fileNameEndsWith)) {}`
 */
declare function findFilesRecursivelyStringStartsWith(path: PathLike, fileStartsWith: string): AsyncIterableIterator<string>;
/**
 *
 * @param path The path in which to find files. This can be a string, buffer, or {@link URL}.
 * @param fileEndsWith The string pattern with which the file name must end.
 * Ideally this is a file extension, however you can also provide more parts of the end of the file.
 *
 * Note that we do **not** support a full globby pattern using asterisk for wildcards. It has to be an exact match with {@link String.endsWith}
 *
 * @return An {@link AsyncIterableIterator} of all the files. To loop over these use `for await (const file of findFilesRecursivelyStringEndsWith(path, fileNameEndsWith)) {}`
 */
declare function findFilesRecursivelyStringEndsWith(path: PathLike, fileEndsWith: string): AsyncIterableIterator<string>;
/**
 * @param path The path in which to find files. This can be a string, buffer, or {@link URL}.
 * @param include The string pattern which must be present in the file name.
 *
 * Note that we do **not** support a full globby pattern using asterisk for wildcards. It has to be an exact match with {@link String.includes}
 *
 * @return An {@link AsyncIterableIterator} of all the files. To loop over these use `for await (const file of findFilesRecursivelyStringIncludes(path, fileNameEndsWith)) {}`
 */
declare function findFilesRecursivelyStringIncludes(path: PathLike, include: string): AsyncIterableIterator<string>;
/**
 * @param path The path in which to find files. This can be a string, buffer, or {@link URL}.
 * @param regex The regex pattern that the file name must match.
 *
 * @return An {@link AsyncIterableIterator} of all the files. To loop over these use `for await (const file of findFilesRecursivelyRegex(path, fileNameEndsWith)) {}`
 */
declare function findFilesRecursivelyRegex(path: PathLike, regex: RegExp): AsyncIterableIterator<string>;

export { findFilesRecursively, findFilesRecursivelyRegex, findFilesRecursivelyStringEndsWith, findFilesRecursivelyStringIncludes, findFilesRecursivelyStringStartsWith };