@types/jake
Version:
TypeScript definitions for jake
439 lines (374 loc) • 19 kB
TypeScript
/// <reference types="node" />
import { EventEmitter } from "events";
declare global {
/**
* Complets an asynchronous task, allowing Jake's execution to proceed to the next task
* @param value A value to return from the task.
*/
function complete(value?: any): void;
/**
* Creates a description for a Jake Task (or FileTask, DirectoryTask). When invoked, the description that iscreated will be associated with whatever Task is created next.
* @param description The description for the Task
*/
function desc(description: string): void;
/**
* Creates a Jake DirectoryTask. Can be used as a prerequisite for FileTasks, or for simply ensuring a directory exists for use with a Task's action.
* @param name The name of the DiretoryTask
*/
function directory(name: string): jake.DirectoryTask;
/**
* Causes Jake execution to abort with an error. Allows passing an optional error code, which will be used to set the exit-code of exiting process.
* @param err The error to thow when aborting execution. If this argument is an Error object, it will simply be thrown. If a String, it will be used as the error-message. (If it is a multi-line String, the first line will be used as the Error message, and the remaining lines will be used as the error-stack.)
*/
function fail(...err: string[]): void;
function fail(...err: Error[]): void;
function fail(...err: any[]): void;
/**
* Creates a Jake FileTask.
* @name name The name of the Task
* @param prereqs Prerequisites to be run before this task
* @param action The action to perform for this task
* @param opts Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
*/
function file(
name: string,
prereqs?: string[],
action?: (this: jake.FileTask) => void,
opts?: jake.FileTaskOptions,
): jake.FileTask;
/**
* Creates Jake FileTask from regex patterns
* @name name/pattern of the Task
* @param source calculated from the name pattern
* @param prereqs Prerequisites to be run before this task
* @param action The action to perform for this task
* @param opts Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
*/
function rule(
pattern: RegExp,
source: string | { (name: string): string },
prereqs?: string[],
action?: () => void,
opts?: jake.TaskOptions,
): void;
/**
* Creates a namespace which allows logical grouping of tasks, and prevents name-collisions with task-names. Namespaces can be nested inside of other namespaces.
* @param name The name of the namespace
* @param scope The enclosing scope for the namespaced tasks
*/
function namespace(name: string, scope: () => void): void;
/**
* @param name The name of the Task
* @param prereqs Prerequisites to be run before this task
* @param action The action to perform for this task
* @param opts
*/
function task(
name: string,
prereqs?: string[],
action?: (this: jake.Task, ...params: any[]) => any,
opts?: jake.TaskOptions,
): jake.Task;
function task(
name: string,
action?: (this: jake.Task, ...params: any[]) => any,
opts?: jake.TaskOptions,
): jake.Task;
function task(
name: string,
opts?: jake.TaskOptions,
action?: (this: jake.Task, ...params: any[]) => any,
): jake.Task;
/**
* @param name The name of the NpmPublishTask
* @param packageFiles The files to include in the package
* @param definition A function that creates the package definition
*/
function npmPublishTask(name: string, packageFiles: string[]): jake.NpmPublishTask;
function npmPublishTask(name: string, definition?: () => void): jake.NpmPublishTask;
namespace jake {
////////////////////////////////////////////////////////////////////////////////////
// File-utils //////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////
interface UtilOptions {
silent?: boolean | undefined;
}
/**
* The jake.mkdirP utility recursively creates a set of nested directories. It will not throw an error if any of the directories already exists.
* https://github.com/substack/node-mkdirp
*/
export function mkdirP(name: string, mode?: string, f?: (er: Error, made: any) => void): void;
export function mkdirP(name: string, f?: (er: Error, made: any) => void): void;
/**
* The jake.cpR utility does a recursive copy of a file or directory.
* Note that this command can only copy files and directories; it does not perform globbing (so arguments like '*.txt' are not possible).
* @param path the file/directory to copy,
* @param destination the destination.
*/
export function cpR(path: string, destination: string, opts?: UtilOptions, callback?: () => void): void;
export function cpR(path: string, destination: string, callback?: (err: Error) => void): void;
/**
* The jake.readdirR utility gives you a recursive directory listing, giving you output somewhat similar to the Unix find command. It only works with a directory name, and does not perform filtering or globbing.
* @return an array of filepaths for all files in the 'pkg' directory, and all its subdirectories.
*/
export function readdirR(name: string, opts?: UtilOptions): string[];
/**
* The jake.rmRf utility recursively removes a directory and all its contents.
*/
export function rmRf(name: string, opts?: UtilOptions): void;
//////////////////////////////////////////////////////////////////////////////////////////////
// Running shell-commands ////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////
interface ExecOptions {
/**
* print to stdout, default false
*/
printStdout?: boolean | undefined;
/**
* print to stderr, default false
*/
printStderr?: boolean | undefined;
/**
* stop execution on error, default true
*/
breakOnError?: boolean | undefined;
/** */
windowsVerbatimArguments?: boolean | undefined;
}
export function exec(cmds: string[], callback?: () => void, opts?: ExecOptions): void;
/**
* @event cmdStart When a new command begins to run. Passes one arg, the command being run.
* @event cmdEnd When a command finishes. Passes one arg, the command being run.
* @event stdout When the stdout for the child-process recieves data. This streams the stdout data. Passes one arg, the chunk of data.
* @event stderr When the stderr for the child-process recieves data. This streams the stderr data. Passes one arg, the chunk of data.
* @event error When a shell-command
*/
export interface Exec extends NodeJS.EventEmitter {
append(cmd: string): void;
run(): void;
}
export function createExec(cmds: string[], callback?: () => void, opts?: ExecOptions): Exec;
export function createExec(cmds: string[], opts?: ExecOptions, callback?: () => void): Exec;
export function createExec(cmds: string, callback?: () => void, opts?: ExecOptions): Exec;
export function createExec(cmds: string, opts?: ExecOptions, callback?: () => void): Exec;
////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Logging and output ////////////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////////////////////////
interface Logger {
log(value: any): void;
error(value: any): void;
}
export var logger: Logger;
//////////////////////////////////////////////////////////////////////////////////////////////////////////////
// program ////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////////////////////////////
export var program: {
opts: {
[name: string]: any;
quiet: boolean;
};
taskNames: string[];
taskArgs: string[];
envVars: { [key: string]: string };
};
//////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Tasks /////////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////////////////////
export interface TaskOptions {
/**
* Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
* @default false
*/
async?: boolean | undefined;
/**
* number of parllel async tasks
*/
parallelLimit?: number | undefined;
}
/**
* A Jake Task
*
* @event complete
*/
export class Task extends EventEmitter {
/**
* @name name The name of the Task
* @param prereqs Prerequisites to be run before this task
* @param action The action to perform for this task
* @param opts Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
*/
constructor(name: string, prereqs?: string[], action?: (this: Task) => void, opts?: TaskOptions);
/**
* Runs prerequisites, then this task. If the task has already been run, will not run the task again.
*/
invoke(): void;
/**
* Runs this task, without running any prerequisites. If the task has already been run, it will still run it again.
*/
reenable(): void;
addListener(event: string, listener: Function): this;
on(event: string, listener: Function): this;
once(event: string, listener: Function): this;
removeListener(event: string, listener: Function): this;
removeAllListeners(event?: string): this;
setMaxListeners(n: number): this;
getMaxListeners(): number;
listeners(event: string): Function[];
emit(event: string, ...args: any[]): boolean;
listenerCount(type: string): number;
complete(value?: any): void;
value: any;
name?: string | undefined;
prereqs?: string[] | undefined;
action?: ((...params: any[]) => any) | undefined;
taskStatus?: string | undefined;
async?: boolean | undefined;
description?: string | undefined;
fullName: string;
}
export class DirectoryTask extends FileTask {
/**
* @param name The name of the directory to create.
*/
constructor(name: string);
}
export interface FileTaskOptions {
/**
* Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
* @default false
*/
async?: boolean | undefined;
}
export class FileTask extends Task {
/**
* @param name The name of the Task
* @param prereqs Prerequisites to be run before this task
* @param action The action to perform to create this file
* @param opts Perform this task asynchronously. If you flag a task with this option, you must call the global `complete` method inside the task's action, for execution to proceed to the next task.
*/
constructor(name: string, prereqs?: string[], action?: (this: FileTask) => void, opts?: FileTaskOptions);
}
interface FileFilter {
(filename: string): boolean;
}
export class FileList {
constructor();
/**
* Includes file-patterns in the FileList. Should be called with one or more
* pattern for finding file to include in the list. Arguments should be strings
* for either a glob-pattern or a specific file-name, or an array of them
*/
include(files: string[]): void;
include(...files: string[]): void;
/**
* Indicates whether a particular file would be filtered out by the current
* exclusion rules for this FileList.
* @param name The filename to check
* @return Whether or not the file should be excluded
*/
shouldExclude(name: string): boolean;
/**
* Excludes file-patterns from the FileList. Should be called with one or more
* pattern for finding file to include in the list. Arguments can be:
* 1. Strings for either a glob-pattern or a specific file-name
* 2. Regular expression literals
* 3. Functions to be run on the filename that return a true/false
*/
exclude(file: string[]): void;
exclude(...file: string[]): void;
exclude(file: RegExp[]): void;
exclude(...file: RegExp[]): void;
exclude(file: FileFilter[]): void;
exclude(...file: FileFilter[]): void;
/**
* Populates the FileList from the include/exclude rules with a list of
* actual files
*/
resolve(): void;
/**
* Convert to a plain-jane array
*/
toArray(): string[];
/**
* Get rid of any current exclusion rules
*/
clearExclude(): void;
}
export class PackageTask {
/**
* Instantiating a PackageTask creates a number of Jake Tasks that make packaging and distributing your software easy.
* @param name The name of the project
* @param version The current project version (will be appended to the project-name in the package-archive
* @param definition Defines the contents of the package, and format of the package-archive. Will be executed on the instantiated PackageTask (i.e., 'this', will be the PackageTask instance), to set the various instance-propertiess.
*/
constructor(name: string, version: string, definition: () => void);
/**
* Equivalent to the '-C' command for the `tar` and `jar` commands. ("Change to this directory before adding files.")
*/
archiveChangeDir: string;
/**
* Specifies the files and directories to include in the package-archive. If unset, this will default to the main package directory -- i.e., name + version.
*/
archiveContentDir: string;
/**
* The shell-command to use for creating jar archives.
*/
jarCommand: string;
/**
* Can be set to point the `jar` utility at a manifest file to use in a .jar archive. If unset, one will be automatically created by the `jar` utility. This path should be relative to the root of the package directory (this.packageDir above, likely 'pkg')
*/
manifestFile: string;
/**
* The name of the project
*/
name: string;
/**
* If set to true, uses the `jar` utility to create a .jar archive of the pagckage
*/
needJar: boolean;
/**
* If set to true, uses the `tar` utility to create a gzip .tgz archive of the pagckage
*/
needTar: boolean;
/**
* If set to true, uses the `tar` utility to create a bzip2 .bz2 archive of the pagckage
*/
needTarBz2: boolean;
/**
* If set to true, uses the `zip` utility to create a .zip archive of the pagckage
*/
needZip: boolean;
/**
* The list of files and directories to include in the package-archive
*/
packageFiles: FileList;
/**
* The shell-command to use for creating tar archives.
*/
tarCommand: string;
/**
* The project version-string
*/
version: string;
/**
* The shell-command to use for creating zip archives.
*/
zipCommand: string;
}
export class TestTask {
constructor(name: string, definition?: () => void);
}
export class NpmPublishTask {
constructor(name: string, packageFiles: string[]);
constructor(name: string, definition?: () => void);
}
export function addListener(event: string, listener: Function): NodeJS.EventEmitter;
export function on(event: string, listener: Function): NodeJS.EventEmitter;
export function once(event: string, listener: Function): NodeJS.EventEmitter;
export function removeListener(event: string, listener: Function): NodeJS.EventEmitter;
export function removeAllListener(event: string): NodeJS.EventEmitter;
export function setMaxListeners(n: number): void;
export function listeners(event: string): Function[];
export function emit(event: string, ...args: any[]): boolean;
}
}