@types/jake/index.d.ts

/// <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;
    }
}