@plugjs/plug/dist/helpers.d.ts

PlugJS Build System ===================

import { Files } from './files';
import type { Pipe } from './index';
import type { AbsolutePath } from './paths';
import type { Context } from './pipe';
import type { RunBuildOptions } from './plugs/build';
import type { ExecChildOptions } from './utils/exec';
import type { WalkOptions } from './utils/walk';
/**
 * The {@link UsingOptions} interface defines the options for building
 * {@link Files} instances from a static list of paths.
 */
export interface UsingOptions {
    /**
     * The directory the {@link Files} instance will be rooted into (defaults to
     * the _current working directory_).
     */
    directory?: string;
}
/** The {@link FindOptions} interface defines the options for finding files. */
export interface FindOptions extends WalkOptions {
    /** The directory where to start looking for files. */
    directory?: string;
}
/** Return the current execution {@link Context} */
export declare function context(): Context;
/** Find files in the current directory using the specified _glob_. */
export declare function find(glob: string): Pipe;
/** Find files in the current directory using the specified _globs_. */
export declare function find(glob: string, ...globs: string[]): Pipe;
/** Find files using the specified _glob_ and {@link FindOptions | options}. */
export declare function find(glob: string, options: FindOptions): Pipe;
/** Find files using the specified _globs_ and {@link FindOptions | options}. */
export declare function find(glob: string, ...extra: [...globs: string[], options: FindOptions]): Pipe;
export type InvokeBuildOptions = RunBuildOptions & Record<string, string>;
export type InvokeBuildTasks = string | [string, ...string[]];
export declare function invokeBuild(buildFile: string): Promise<void>;
export declare function invokeBuild(buildFile: string, task: string): Promise<void>;
export declare function invokeBuild(buildFile: string, task: string, options: InvokeBuildOptions): Promise<void>;
export declare function invokeBuild(buildFile: string, tasks: [string, ...string[]]): Promise<void>;
export declare function invokeBuild(buildFile: string, tasks: [string, ...string[]], options: InvokeBuildOptions): Promise<void>;
export declare function invokeBuild(buildFile: string, options: InvokeBuildOptions): Promise<void>;
/**
 * Recursively remove the specified directory _**(use with care)**_.
 */
export declare function rmrf(directory: string): Promise<void>;
/**
 * Merge the results of several {@link Pipe}s into a single one.
 *
 * Merging is performed _in parallel_. When serial execution is to be desired,
 * we can merge the awaited _result_ of the {@link Pipe}.
 *
 * For example:
 *
 * ```
 * const pipe: Pipe = merge([
 *   await this.anotherTask1(),
 *   await this.anotherTask2(),
 * ])
 * ```
 */
export declare function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe;
/**
 * Create an empty _no-op_ {@link Pipe}.
 *
 * This is useful when creating tasks with conditional pipes and returning the
 * correct type, for example:
 *
 * ```
 * if (someCondition) {
 *   return find(...).pipe(...)
 * } else {
 *   return noop()
 * }
 * ```
 */
export declare function noop(): Pipe;
/**
 * Create a {@link Pipe} from a static set of files.
 *
 * The default directory where the {@link Files} instance will be rooted into
 * is the _current working directory_.
 *
 * If _relative_ each file specified will be resolved relatively to the base
 * {@link Files} directory.
 */
export declare function using(...args: [...string[]]): Pipe;
export declare function using(...args: [...string[], options: UsingOptions]): Pipe;
/**
 * Resolve a (set of) path(s) into an {@link AbsolutePath}.
 *
 * If the path (or first component thereof) starts with `@...`, then the
 * resolved path will be relative to the directory containing the build file
 * where the current task was defined, otherwise it will be relative to the
 * current working directory.
 */
export declare function resolve(...paths: [string, ...string[]]): AbsolutePath;
/**
 * Return an absolute path of the file if it exist on disk.
 *
 * See the comments on {@link resolve} to understand how paths are resolved.
 */
export declare function isFile(...paths: [string, ...string[]]): AbsolutePath | undefined;
/**
 * Return an absolute path of the directory if it exist on disk.
 *
 * See the comments on {@link resolve} to understand how paths are resolved.
 */
export declare function isDirectory(...paths: [string, ...string[]]): AbsolutePath | undefined;
/**
 * Create a temporary directory and return its {@link AbsolutePath}.
 *
 * The directory will be rooted in `/tmp` or wherever `os.tmpdir()` decides.
 */
export declare function mkdtemp(): AbsolutePath;
/**
 * Execute a command and await for its result from within a task.
 *
 * For example:
 *
 * ```
 * import { exec } from '@plugjs/plugjs'
 *
 * export default build({
 *   async runme() {
 *     await exec('ls', '-la', '/')
 *     // or similarly letting the shell interpret the command
 *     await exec('ls -la /', { shell: true })
 *   },
 * })
 * ```
 *
 * @param cmd The command to execute
 * @param args Any additional argument for the command to execute
 * @param options Extra {@link ExecChildOptions | options} for process execution
 */
export declare function exec(cmd: string, ...args: [...args: string[]] | [...args: string[], options: ExecChildOptions]): Promise<void>;
/**
 * Read and parse a JSON/JSONC file, throwing an error if not found.
 *
 * @params file The JSON file to parse
 */
export declare function parseJson(file: string, strict?: boolean): any;