Class PackageStage

Default package stage.

Since

0.1.0-alpha

Hierarchy (View Summary)

AbstractStage<Stage.Args.Package, Stage.SubStage.Package>
- PackageStage

Index

Config

`Readonly`args

args: Stage.Args.Package

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(): { utils: {} }
Default args for this stage.

Returns { utils: {} }
Overrides AbstractStage.ARGS_DEFAULT
- Defined in lib/03-stages/classes/PackageStage.ts:81

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:199

buildArgs

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

Uses mergeArgs recursively.
Parameters
- Optionalargs: Partial<Stage.Args.Package>
Returns Stage.Args.Package
Inherited from AbstractStage.buildArgs
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:311

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:623

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:635

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:642
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:647

isSubStageIncluded

isSubStageIncluded(subStage: Stage.SubStage.Package, 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.Package
  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:530

Constructor

constructor

new PackageStage(
    config: Config.Class,
    params: Params,
    args: Partial<Stage.Args.Package>,
    pkg?: PackageJson,
    version?: SemVer,
): PackageStage
Parameters
- config: Config.Class
  Current project config.
- params: Params
  Current CLI params.
- args: Partial<Stage.Args.Package>
  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 PackageStage
Overrides AbstractStage.constructor
- Defined in lib/03-stages/classes/PackageStage.ts:102

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:701

uncaughtErrorListener

uncaughtErrorListener(error: unknown): void
Handles uncaught errors in node.
Parameters
- error: unknown
  To handle.
Returns void
Since
0.2.0-alpha
Inherited from AbstractStage.uncaughtErrorListener
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:729

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:502

`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:850
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:865
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:880
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:893

`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:676

`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:746
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:761
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:776
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:789

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:387

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:154

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:230
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:264

Running

`Readonly`subStages

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

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

Source

    public readonly subStages: Stage.SubStage.Package[] = [
        'snapshot',
        'build',
        'copy',
        'zip',
    ];

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:994

startEndNotice

startEndNotice(which: null | "start" | "end"): 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 Promise<void>
Overrides AbstractStage.startEndNotice
- Defined in lib/03-stages/classes/PackageStage.ts:153

`Protected`runCustomDirCopySubStage

runCustomDirCopySubStage(
    subpath: string,
    _distDir?: string,
    logLevelBase?: number,
): Promise<void>
Experimental
This runs a custom sub-stage that only copies a whole folder at the given subpath from the source to the dist directories.

Deletes any existing, logs update messages, etc.
Parameters
- subpath: string
  The subdriectory, relative to src path.
- Optional_distDir: string
  Optionally force a diffrent output directory than the auto-generated one.
- logLevelBase: number = 1
  Base output level for log messages.
Returns Promise<void>
Since
0.1.4-alpha

Since
0.2.0-alpha.1 — Added logLevelBase param.
Inherited from AbstractStage.runCustomDirCopySubStage
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:1104

`Protected`runCustomScssDirSubStage

runCustomScssDirSubStage(
    subpath: string,
    _distDir?: string,
    postCSS?: boolean,
    logLevelBase?: number,
): Promise<void>
Experimental
This runs a custom sub-stage that uses globs to find non-partial scss/sass files and compile them at the given subpath from the source to the dist directories.

Deletes any existing, logs update messages, etc.
Parameters
- subpath: string
  The subdriectory, relative to src path.
- Optional_distDir: string
  Optionally force a diffrent output directory than the auto-generated one.
- postCSS: boolean = true
  Whether to run PostCSS on the output css. Default true.
- logLevelBase: number = 1
  Base output level for log messages.
Returns Promise<void>
Since
0.1.4-alpha

Since
0.2.0-alpha — Added postCSS param and PostCSS compatibility.

Since
0.2.0-alpha.1 — Added logLevelBase param.
Inherited from AbstractStage.runCustomScssDirSubStage
- Defined in lib/03-stages/classes/abstract/AbstractStage.ts:1169

`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:1031

`Protected`runSubStage

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

`Protected`startPrompters

startPrompters(): Promise<void>
Runs the prompters to confirm before starting the substages.

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

Sub-Stages

`Protected`build

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

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

`Protected`copy

copy(): Promise<void>
Copies all project files to the release directory.

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

`Protected`snapshot

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

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

`Protected`zip

zip(): Promise<void>
Zips the release directory.

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

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:113
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:128

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:642
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:647

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:405

Class PackageStage

Since

Hierarchy (View Summary)

Index

Config

Constructor

Errors

Project

Running

Sub-Stages

Utilities

Config

Readonlyargs

Readonlyclr

Readonlyconfig

Readonlyname

Readonlyparams

ARGS_DEFAULT

Returns { utils: {} }

releaseDir

Returns string

buildArgs

Parameters

Returns Stage.Args.Package

getDistDir

Parameters

Returns string

getScriptsPath

Parameters

Returns string

getSrcDir

Parameters

Returns string[]

Parameters

Returns string

isSubStageIncluded

Parameters

Returns boolean

Constructor

constructor

Parameters

Returns PackageStage

Errors

logError

Parameters

Returns BulkMsgs

uncaughtErrorListener

Parameters

Returns void

Since

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

`Readonly`args

`Readonly`clr

`Readonly`config

`Readonly`name

`Readonly`params

`Protected`atry

`Protected`handleError

`Protected`try

`Readonly`subStages

`Protected`runCustomDirCopySubStage

`Protected`runCustomScssDirSubStage

`Protected`runStage

`Protected`runSubStage

`Protected`startPrompters

`Protected`build

`Protected`copy

`Protected`snapshot

`Protected`zip

`Readonly`compiler

`Readonly`console