Class BuildStage

Default build stage.

Since

0.1.0-alpha

Hierarchy (View Summary)

AbstractStage<Stage.Args.Build, Stage.SubStage.Build>
- BuildStage

Index

Config

`Readonly`args

args: Stage.Args.Build

A completed args object for this instance.

`Readonly`clr

clr: Colour

Colour used for colour-coding this stage.

`Readonly`config

config: Config.Class

Complete project configuration.

`Readonly`name

name: string

Name for this stage used for notices.

`Readonly`params

params: Params

Current CLI params.

ARGS_DEFAULT

get ARGS_DEFAULT(): {
    compile: true;
    document: false;
    minimize: (
        _stage: Stage,
    ) => {
        css: false;
        html: false;
        js: false;
        json: { globs: [`${string}/**/*.json`] };
    };
    prettify: (
        _stage: Stage,
    ) => {
        css: readonly [readonly [`${string}/**/*.css`, `${string}/**/*.css`]];
        html: readonly [readonly [`${string}/**/*.html`]];
        js: readonly [
            readonly [
                `${string}/**/*.js`,
                `${string}/**/*.jsx`,
                `${string}/**/*.js`,
                `${string}/**/*.jsx`,
            ],
        ];
        json: readonly [readonly [`${string}/**/*.json`]];
        md: undefined;
        mdx: undefined;
        scss: readonly [readonly [`${string}/**/*.scss`, `${string}/**/*.scss`]];
        ts: readonly [
            readonly [
                `${string}/**/*.ts`,
                `${string}/**/*.tsx`,
                `${string}/**/*.ts`,
                `${string}/**/*.tsx`,
            ],
        ];
        yaml: readonly [readonly [`${string}/**/*.yaml`]];
    };
    replace: (
        stage: Stage,
    ) => { current?: string[]; ignore?: string[]; package?: string[] };
    test: false;
    utils: {};
}
Default args for this stage.

Returns {
    compile: true;
    document: false;
    minimize: (
        _stage: Stage,
    ) => {
        css: false;
        html: false;
        js: false;
        json: { globs: [`${string}/**/*.json`] };
    };
    prettify: (
        _stage: Stage,
    ) => {
        css: readonly [readonly [`${string}/**/*.css`, `${string}/**/*.css`]];
        html: readonly [readonly [`${string}/**/*.html`]];
        js: readonly [
            readonly [
                `${string}/**/*.js`,
                `${string}/**/*.jsx`,
                `${string}/**/*.js`,
                `${string}/**/*.jsx`,
            ],
        ];
        json: readonly [readonly [`${string}/**/*.json`]];
        md: undefined;
        mdx: undefined;
        scss: readonly [readonly [`${string}/**/*.scss`, `${string}/**/*.scss`]];
        ts: readonly [
            readonly [
                `${string}/**/*.ts`,
                `${string}/**/*.tsx`,
                `${string}/**/*.ts`,
                `${string}/**/*.tsx`,
            ],
        ];
        yaml: readonly [readonly [`${string}/**/*.yaml`]];
    };
    replace: (
        stage: Stage,
    ) => { current?: string[]; ignore?: string[]; package?: string[] };
    test: false;
    utils: {};
}
Overrides AbstractStage.ARGS_DEFAULT
- Defined in lib/03-stages/classes/BuildStage.ts:78

releaseDir

get releaseDir(): string
Path to release directory for building a package for the current version.

Returns string
Inherited from AbstractStage.releaseDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:197

buildArgs

buildArgs(
args?: Partial<Stage.Args.Build>,
): Stage.Args.Build & Partial<Stage.Args.Build>
Builds a complete version of this class' args, falling back to defaults as needed.

Uses mergeArgs recursively.
Parameters
- args: Partial<Stage.Args.Build> = {}
Returns Stage.Args.Build & Partial<Stage.Args.Build>
Overrides AbstractStage.buildArgs
- Defined in lib/03-stages/classes/BuildStage.ts:254

getDistDir

getDistDir(subDir?: DistDirectory, ...subpaths: string[]): string
Gets the paths from the config for the given dist sub directory.
Parameters
- OptionalsubDir: DistDirectory
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string
Inherited from AbstractStage.getDistDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:578

getScriptsPath

getScriptsPath(subDir?: "logs", ...subpaths: string[]): string
Gets an absolute path to the Config.Paths.scripts directories.
Parameters
- OptionalsubDir: "logs"
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string
Inherited from AbstractStage.getScriptsPath
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:590

getSrcDir

getSrcDir(subDir: SourceDirectory, ...subpaths: string[]): string[]
If there's a subdir, the return will be an array of strings.
Parameters
- subDir: SourceDirectory
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string[]
Inherited from AbstractStage.getSrcDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:597
getSrcDir(subDir?: undefined, ...subpaths: string[]): string
If there's no subdir, the return will be a string.
Parameters
- OptionalsubDir: undefined
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string
Inherited from AbstractStage.getSrcDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:602

isSubStageIncluded

isSubStageIncluded(subStage: Stage.SubStage.Build, level: number): boolean
Whether the given substage should be run according to the values of CLI.Params.only and CLI.Params.without.
Parameters
- subStage: Stage.SubStage.Build
  Substage to check.
- level: number
  Depth level for this message.
Returns boolean
Whether to run this sub-stage.
Inherited from AbstractStage.isSubStageIncluded
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:485

Constructor

constructor

new BuildStage(
    config: Config.Class,
    params: Params,
    args: Partial<Stage.Args.Build>,
    pkg?: PackageJson,
    version?: SemVer,
): BuildStage
Parameters
- config: Config.Class
  Current project config.
- params: Params
  Current CLI params.
- args: Partial<Stage.Args.Build>
  Partial overrides for the default args.
- Optionalpkg: PackageJson
  Parsed contents of the project’s package.json file.
- Optionalversion: SemVer
  Version object for the project’s version.
Returns BuildStage
Overrides AbstractStage.constructor
- Defined in lib/03-stages/classes/BuildStage.ts:301

Errors

logError

logError(
    logMsg: string,
    error: unknown,
    level: number,
    errMsg?: string,
    date?: Date,
): BulkMsgs
Alias for internal.logError.
Parameters
- logMsg: string
  Message to prepend to the return for output to the console.
- error: unknown
  Caught error to log.
- level: number
  Depth level for output to the console.
- OptionalerrMsg: string
  See logError.Args.errMsg.
- Optionaldate: Date
  Used for the timestamp.
Returns BulkMsgs
Inherited from AbstractStage.logError
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:656

writeLog

writeLog(
    msg: string | string[] | BulkMsgs,
    filename: string,
    subDir?: string[],
    date?: null | Date,
): string | false
Alias for internal.writeLog.
Parameters
- msg: string | string[] | BulkMsgs
  Log message to write.
- filename: string
  File name for the log.
- subDir: string[] = []
  Subdirectories used for the path to write the log file.
- date: null | Date = null
  Used for the timestamp.
Returns string | false
If false, writing the log failed. Otherwise, this is the path to the written log file.
Inherited from AbstractStage.writeLog
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:457

`Protected`atry

atry<T_Params extends never[], T_Return extends unknown>(
    tryer: () => Promise<T_Return>,
    level: number,
    params?: NoInfer<T_Params>,
    handlerArgs?: Partial<AbstractError.Handler.Args> & { exitProcess?: false },
): Promise<T_Return>
Experimental
If the tryer function has no params, then they are optional.

If the handler must exit, then 'FAILED' is not possible.
Type Parameters
- T_Params extends never[]
- T_Return extends unknown
Parameters
- tryer: () => Promise<T_Return>
  Function to run inside the try {}.
- level: number
  Depth level for the error handler.
- Optionalparams: NoInfer<T_Params>
  Parameters passed to the tryer function, if any.
- OptionalhandlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess?: false }
Returns Promise<T_Return>
The tryer function’s return, or 'FAILED' if an error is caught and the process isn’t exited.
Inherited from AbstractStage.atry
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:794
atry<T_Params extends unknown[], T_Return extends unknown>(
    tryer: (...params: T_Params) => Promise<T_Return>,
    level: number,
    params: NoInfer<T_Params>,
    handlerArgs?: Partial<AbstractError.Handler.Args> & { exitProcess?: false },
): Promise<T_Return>
Experimental
If the tryer function has params, then they are required.

If the handler must exit, then 'FAILED' is not possible.
Type Parameters
- T_Params extends unknown[]
- T_Return extends unknown
Parameters
- tryer: (...params: T_Params) => Promise<T_Return>
- level: number
- params: NoInfer<T_Params>
- OptionalhandlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess?: false }
Returns Promise<T_Return>
Inherited from AbstractStage.atry
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:809
atry<T_Params extends never[], T_Return extends unknown>(
    tryer: () => Promise<T_Return>,
    level: number,
    params: undefined | NoInfer<T_Params>,
    handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean },
): Promise<"FAILED" | T_Return>
Experimental
If the tryer function has no params, then they are optional.

If the handler won't exit, then 'FAILED' is possible.
Type Parameters
- T_Params extends never[]
- T_Return extends unknown
Parameters
- tryer: () => Promise<T_Return>
- level: number
- params: undefined | NoInfer<T_Params>
- handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean }
Returns Promise<"FAILED" | T_Return>
Inherited from AbstractStage.atry
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:824
atry<T_Params extends unknown[], T_Return extends unknown>(
    tryer: (...params: T_Params) => Promise<T_Return>,
    level: number,
    params: NoInfer<T_Params>,
    handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean },
): Promise<"FAILED" | T_Return>
Experimental
If the tryer function has params, then they are required.
Type Parameters
- T_Params extends unknown[]
- T_Return extends unknown
Parameters
- tryer: (...params: T_Params) => Promise<T_Return>
- level: number
- params: NoInfer<T_Params>
- handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean }
Returns Promise<"FAILED" | T_Return>
Inherited from AbstractStage.atry
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:837

`Protected`handleError

handleError(
    error: any,
    level: number,
    args?: Partial<AbstractError.Handler.Args>,
): void
Alias for errorHandler.
Parameters
- error: any
  Error to handle.
- level: number
  Depth level for output to the console.
- Optionalargs: Partial<AbstractError.Handler.Args>
  Overrides for default options.
Returns void
Inherited from AbstractStage.handleError
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:631

`Protected`try

try<T_Params extends never[], T_Return extends unknown>(
    tryer: () => T_Return,
    level: number,
    params?: NoInfer<T_Params>,
    handlerArgs?: Partial<AbstractError.Handler.Args> & { exitProcess?: false },
): T_Return
Experimental
If the tryer function has no params, then they are optional.

If the handler must exit, then 'FAILED' is not possible.
Type Parameters
- T_Params extends never[]
- T_Return extends unknown
Parameters
- tryer: () => T_Return
  Function to run inside the try {}.
- level: number
  Depth level for the error handler.
- Optionalparams: NoInfer<T_Params>
  Parameters passed to the tryer function, if any.
- OptionalhandlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess?: false }
Returns T_Return
The tryer function’s return, or 'FAILED' if an error is caught and the process isn’t exited.
Inherited from AbstractStage.try
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:690
try<T_Params extends unknown[], T_Return extends unknown>(
    tryer: (...params: T_Params) => T_Return,
    level: number,
    params: NoInfer<T_Params>,
    handlerArgs?: Partial<AbstractError.Handler.Args> & { exitProcess?: false },
): T_Return
Experimental
If the tryer function has params, then they are required.

If the handler must exit, then 'FAILED' is not possible.
Type Parameters
- T_Params extends unknown[]
- T_Return extends unknown
Parameters
- tryer: (...params: T_Params) => T_Return
- level: number
- params: NoInfer<T_Params>
- OptionalhandlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess?: false }
Returns T_Return
Inherited from AbstractStage.try
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:705
try<T_Params extends never[], T_Return extends unknown>(
    tryer: () => T_Return,
    level: number,
    params: undefined | NoInfer<T_Params>,
    handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean },
): T_Return | "FAILED"
Experimental
If the tryer function has no params, then they are optional.

If the handler won't exit, then 'FAILED' is possible.
Type Parameters
- T_Params extends never[]
- T_Return extends unknown
Parameters
- tryer: () => T_Return
- level: number
- params: undefined | NoInfer<T_Params>
- handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean }
Returns T_Return | "FAILED"
Inherited from AbstractStage.try
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:720
try<T_Params extends unknown[], T_Return extends unknown>(
    tryer: (...params: T_Params) => T_Return,
    level: number,
    params: NoInfer<T_Params>,
    handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean },
): T_Return | "FAILED"
Experimental
If the tryer function has params, then they are required.
Type Parameters
- T_Params extends unknown[]
- T_Return extends unknown
Parameters
- tryer: (...params: T_Params) => T_Return
- level: number
- params: NoInfer<T_Params>
- handlerArgs: Partial<AbstractError.Handler.Args> & { exitProcess: boolean }
Returns T_Return | "FAILED"
Inherited from AbstractStage.try
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:733

Project

isDraftVersion

get isDraftVersion(): boolean
Wheather the current project version is a draft (e.g., this is not a non-dryrun release).

Returns boolean
Inherited from AbstractStage.isDraftVersion
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:342

pkg

get pkg(): {
    bin: undefined
    | string
    | { [key: string]: string };
    bugs: undefined | { email?: string; url?: string };
    config: undefined | { [key: string | number]: any };
    description: undefined | string;
    engines: undefined | { [key: string]: string };
    files: undefined | string[];
    homepage: undefined | string;
    license: undefined | string;
    main: undefined | string;
    name: string;
    repository: undefined | string;
    version: string;
}
Current value of the package.json file for this project.

Returns {
    bin: undefined | string | { [key: string]: string };
    bugs: undefined | { email?: string; url?: string };
    config: undefined | { [key: string | number]: any };
    description: undefined | string;
    engines: undefined | { [key: string]: string };
    files: undefined | string[];
    homepage: undefined | string;
    license: undefined | string;
    main: undefined | string;
    name: string;
    repository: undefined | string;
    version: string;
}
Inherited from AbstractStage.pkg
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:152

version

get version(): SemVer
Current version object for the project.

Returns SemVer
Inherited from AbstractStage.version
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:228
set version(input: undefined | string | SemVer): void
If undefined, nothing is set. Otherwise, a SemVer is created and the value of AbstractStage.pkg.version is updated.
Parameters
- input: undefined | string | SemVer
Returns void
Inherited from AbstractStage.version
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:241

Running

`Readonly`subStages

subStages: Stage.SubStage.Build[] = ...

All sub-stages to run in this stage (in order).

Source

    public readonly subStages: Stage.SubStage.Build[] = [
        'compile',
        'replace',
        'prettify',
        'minimize',
        'test',
        'document',
    ];

run

run(): Promise<void>
Runs the entire stage (asynchronously).

This method should probably not be overwritten, except in completely custom class implementations.

Cycles through each substage and runs AbstractStage.runSubStage if AbstractStage.isSubStageIncluded returns true.

Returns Promise<void>
Inherited from AbstractStage.run
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:938

startEndNotice

startEndNotice(which: null | "start" | "end"): void | Promise<void>
Prints a message to the console signalling the start or end of this build stage.
Parameters
- which: null | "start" | "end"
  Whether we are starting or ending.
Returns void | Promise<void>
Overrides AbstractStage.startEndNotice
- Defined in lib/03-stages/classes/BuildStage.ts:316

`Protected`runStage

runStage(stage: Name, level: number): Promise<void>
Runs the given stage as a sub-stage to the current one.

This method should probably not be overwritten.
Parameters
- stage: Name
  Stage to run as a substage.
  - "snapshot"
  - "compile"
  - "test"
  - "document"
  - "build"
  - "package"
  - "release"
- level: number
  Depth level for output to the console.
Returns Promise<void>
Inherited from AbstractStage.runStage
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:975

`Protected`runSubStage

runSubStage(subStage: Stage.SubStage.Build): Promise<void>
Used to run a single stage within this class; used by AbstractStage.run.
Parameters
- subStage: Stage.SubStage.Build
Returns Promise<void>
Overrides AbstractStage.runSubStage
- Defined in lib/03-stages/classes/BuildStage.ts:325

Sub-Stages

`Protected`compile

compile(): Promise<void>
Runs the project's compile class.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:334

`Protected`document

document(): Promise<void>
Runs the project's document class.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:343

`Protected`minimize

minimize(): Promise<void>
Minimizes files.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:352

`Protected`prettify

prettify(): Promise<void>
Runs prettier to format files.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:428

`Protected`replace

replace(): Promise<void>
Replaces placeholders in the built files and directories.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:487

`Protected`test

test(): Promise<void>
Runs the project's test class.

Returns Promise<void>
- Defined in lib/03-stages/classes/BuildStage.ts:514

Utilities

`Readonly`compiler

compiler: Stage_Compiler

Instance used to compile files from the src directory.

`Readonly`console

console: Stage_Console

Instance used to send messages to the console.

fs

get fs(): FileSystem
Instance used to deal with files and paths.

Returns FileSystem
Inherited from AbstractStage.fs
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:111
set fs(fs: undefined | FileSystem): void
Instance used to deal with files and paths.
Parameters
- fs: undefined | FileSystem
Returns void
Inherited from AbstractStage.fs
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:126

getSrcDir

getSrcDir(subDir: SourceDirectory, ...subpaths: string[]): string[]
If there's a subdir, the return will be an array of strings.
Parameters
- subDir: SourceDirectory
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string[]
Inherited from AbstractStage.getSrcDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:597
getSrcDir(subDir?: undefined, ...subpaths: string[]): string
If there's no subdir, the return will be a string.
Parameters
- OptionalsubDir: undefined
  Sub-path to get.
- ...subpaths: string[]
  Optional additional subpaths.
Returns string
Inherited from AbstractStage.getSrcDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:602

replaceInFiles

replaceInFiles(
    globs: string[],
    version: "package" | "current",
    level: number,
    ignore?: string[],
    docsMode?: boolean,
): string[]
Replaces placeholders in files as defined by Config.replace.
Parameters
- globs: string[]
  Where to find & replace placeholders.
- version: "package" | "current"
  Which version of the replacements to run.
- level: number
  Depth level for output to the console.
- ignore: string[] = []
  Globs to ignore while replacing. Default FileSystem.globs.SYSTEM.
- docsMode: boolean = false
  Whether to make the replacements in 'docs' mode (i.e., assumes markdown in comments was converted to HTML).
Returns string[]
Paths where placeholders were replaced.
Inherited from AbstractStage.replaceInFiles
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:360

Class BuildStage

Since

Hierarchy (View Summary)

Index

Config

Constructor

Errors

Project

Running

Sub-Stages

Utilities

Config

Readonlyargs

Readonlyclr

Readonlyconfig

Readonlyname

Readonlyparams

ARGS_DEFAULT

releaseDir

Returns string

buildArgs

Parameters

Returns Stage.Args.Build & Partial<Stage.Args.Build>

getDistDir

Parameters

Returns string

getScriptsPath

Parameters

Returns string

getSrcDir

Parameters

Returns string[]

Parameters

Returns string

isSubStageIncluded

Parameters

Returns boolean

Constructor

constructor

Parameters

Returns BuildStage

Errors

logError

Parameters

Returns BulkMsgs

writeLog

Parameters

Returns string | false

Protectedatry

Type Parameters

Parameters

Returns Promise<T_Return>

Type Parameters

Parameters

Returns Promise<T_Return>

Type Parameters

Parameters

Returns Promise<"FAILED" | T_Return>

Type Parameters

Parameters

Returns Promise<"FAILED" | T_Return>

ProtectedhandleError

Parameters

Returns void

Protectedtry

Type Parameters

Parameters

Returns T_Return

Type Parameters

Parameters

Returns T_Return

Type Parameters

Parameters

Returns T_Return | "FAILED"

Type Parameters

Parameters

Returns T_Return | "FAILED"

Project

isDraftVersion

Returns boolean

`Readonly`args

`Readonly`clr

`Readonly`config

`Readonly`name

`Readonly`params

`Protected`atry

`Protected`handleError

`Protected`try

`Readonly`subStages

`Protected`runStage

`Protected`runSubStage

`Protected`compile

`Protected`document

`Protected`minimize

`Protected`prettify

`Protected`replace

`Protected`test

`Readonly`compiler

`Readonly`console