Class AbstractStage<T_Args, T_SubStage>`Abstract`

Abstract class for a single build stage, along with a variety of utilities for building projects.

Since

0.1.0-alpha

Type Parameters

T_Args extends Stage.Args
Argument object for this stage.
T_SubStage extends string
String literal of substages to run within this stage.

Hierarchy (View Summary)

AbstractStage

Implements

Stage<T_Args, T_SubStage>

Index

Config

`Readonly`args

args: T_Args

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.

`Abstract`ARGS_DEFAULT

get ARGS_DEFAULT(): T_Args
Default args for this stage.

Returns T_Args
Implementation of Stage.ARGS_DEFAULT
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:284

releaseDir

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

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

buildArgs

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

Uses mergeArgs recursively.
Parameters
- Optionalargs: Partial<T_Args>
Returns T_Args
Implementation of Stage.buildArgs
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:268

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
Implementation of Stage.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
Implementation of Stage.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[]
Implementation of Stage.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
Implementation of Stage.getSrcDir
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:602

isSubStageIncluded

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

Constructor

constructor

new AbstractStage<T_Args extends Stage.Args, T_SubStage extends string>(
    name: string,
    clr: Colour,
    config: Config.Class,
    params: Params,
    args: Partial<T_Args>,
    pkg: undefined | PackageJson,
    version: undefined | SemVer,
): AbstractStage<T_Args, T_SubStage>
Type Parameters
- T_Args extends Stage.Args
- T_SubStage extends string
Parameters
- name: string
  Name for this stage used for notices.
- clr: Colour
  Colour used for colour-coding this class.
- config: Config.Class
  Current project config.
- params: Params
  Current CLI params.
- args: Partial<T_Args>
  Partial overrides for the default stage args.
- pkg: undefined | PackageJson
  Parsed contents of the project’s package.json file.
- version: undefined | SemVer
  Version object for the project’s version.
Returns AbstractStage<T_Args, T_SubStage>
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:302

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
- 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.
- 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.
- 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>
- 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>
- 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>
- 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
- 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.
- 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
- 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"
- 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"
- 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
Implementation of Stage.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;
}
Implementation of Stage.pkg
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:152

version

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

Returns SemVer
Implementation of Stage.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
Implementation of Stage.version
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:241

Running

`Abstract` `Readonly`subStages

subStages: T_SubStage[]

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

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>
Implementation of Stage.run
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:938

startEndNotice

startEndNotice(
which: null | "start" | "end",
watcherVersion?: boolean,
): 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.
- watcherVersion: boolean = false
  Whether to display the watcher version of the message if applicable. Default false.
Returns void | Promise<void>
Implementation of Stage.startEndNotice
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:893

`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>
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:975

`Protected` `Abstract`runSubStage

runSubStage(subStage: T_SubStage): Promise<void>
Used to run a single stage within this class; used by AbstractStage.run.
Parameters
- subStage: T_SubStage
Returns Promise<void>
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:1021

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
Implementation of Stage.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
Implementation of Stage.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[]
Implementation of Stage.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
Implementation of Stage.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.
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:360

Class AbstractStage<T_Args, T_SubStage>Abstract

Since

Type Parameters

Hierarchy (View Summary)

Implements

Index

Config

Constructor

Errors

Project

Running

Utilities

Config

Readonlyargs

Readonlyclr

Readonlyconfig

Readonlyname

Readonlyparams

AbstractARGS_DEFAULT

Returns T_Args

releaseDir

Returns string

buildArgs

Parameters

Returns T_Args

getDistDir

Parameters

Returns string

getScriptsPath

Parameters

Returns string

getSrcDir

Parameters

Returns string[]

Parameters

Returns string

isSubStageIncluded

Parameters

Returns boolean

Constructor

constructor

Type Parameters

Parameters

Returns AbstractStage<T_Args, T_SubStage>

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"

Class AbstractStage<T_Args, T_SubStage>`Abstract`

`Readonly`args

`Readonly`clr

`Readonly`config

`Readonly`name

`Readonly`params

`Abstract`ARGS_DEFAULT

`Protected`atry

`Protected`handleError

`Protected`try

`Abstract` `Readonly`subStages

`Protected`runStage

`Protected` `Abstract`runSubStage

`Readonly`compiler

`Readonly`console