2.2.43 ā€¢ Published 9 months ago

extra-build v2.2.43

Weekly downloads
5
License
MIT
Repository
github
Last release
9 months ago

Common build tools for extra-* packages. šŸ“¦ Node.js, šŸ“œ Files, šŸ“° Docs.

Why do packages need to be built? For TypeScript-based source libraries (such as this) our main priority is to generate JavaScript file(s) which can be imported from the runtime (Node.js), and publish them to a package registry such as NPM. In addition we might like to generate associated type declarations (.d.ts file), which is one of the reasons behind choosing to write in TypeScript. We might also like to bundle all scripts (and type declarations) into a single file to help reduce package size, dependencies, or eliminate unused code.

Documentation plays a key role in reducing the amount of time spent on Stack Overflow, and thus must be maintained at all costs. Instead of manually updating it, most developers choose to generate this from documentation comments in the code. An Index can be added to the README file that links to documention. Thus we have a new build step. In addition, we might like to update package metadata (in package.json or GitHub repo), build source files for another platform (such as the web), update package version automatically, generate wiki files (for code examples), or publish to GitHub packages.

This package provides utility functions for all of these operations, and more. The previous version of this package provided a CLI for all of these operations, but was inflexible in its design (it could only be used when the source code was arranged is a very specific way). This redesigned version provides a JavaScipt API instead that allows for significant customization, in addition to providing a number of helper functions commonly used in build steps. Build steps can be written in a script file, say build.js, and executed on a CI system such as GitHub Actions using .github/workflows/*.yml.

Standalone symbol name of a package, such as @package/submodule, can be obtained with symbolname (i.e., package_submodule). This is necessary when webifying (making it accessible with a script tag) a package. Keyword name for an identifier can be procured with keywordname, which can then be used to set the keywords of a package in the metadata file package.json.

Logging of error, warning, log, and info messages with colors is provided with error, warn, log, and info respectively. A shell command can be executed (displaying the command and its output) with exec. The output of a command can be obtained as a string with execStr. Reading/writing of text/JSON files is possible with convenience methods readFileText, writeFileText, readJson, and writeJson. To save the status and contents of a file (without having to do any existence check) is possible with readDocument and writeDocument. They are useful when it is required to update a file temporarily and restore it later (if it exists, or remove if it did not exist).

Helper git commands for commit+push, and setting up a new branch and pushing to remote (for gh-pages) is available as gitCommitPush and gitSetupBranch. A JavaScript file can be bundled (to a single file) with bundleScript, and webified (for access on the web) with webifyScript. A banner can be added to the generated script with addBanner. To parse a GitHub URL (for example from the repository.url field in package.json) parseGithubUrl can be used. GitHub repository details can be updated (by default from package.json) with updateGithubRepoDetails.

The metadata file of a package (package.json) can be read/written with readMetadata and writeMetadata respectively. The current registry being used for publishing to NPM (in .npmrc file) can be obtained with registry, and modified with setRegistry. The latest version of a package can be obtained with latestVersion, and the next unpublished version (based on the latest package version, and the version mentioned in package.json) can be obtained with nextUnpublishedVersion.

JsDoc for a package can be generated with generateDocs, and published with publishDocs. Reflection information of docs can be obtained from the source file (through typedoc) with loadDocs. This can then used to obtain detailed information on exported symbols using docsName, docsLocation, docsFlags, docsKind, docsChildCount, docsParameterCount, docsSignatureCount, docsType, docsDescription, and docsReturns. For reference symbols, the referred to symbol (which has all the type information) can be obtained with docsRefer. Simplified details of a reflection (symbol) can be obtained with docsDetails and docsReferDetails (get details of referred to symbol).

Reference code block for wiki can be generated with wikiCodeReference, example code block can be generated with wikiCodeExample, and full markdown text can be generated with wikiMarkdown. The "Index" table of wiki or README.md can be updated (using simplified details of exported symbols) with wikiUpdateIndex, and link references (named links in markdown) can be updated with wikiUpdateLinkReferences. Finally a package can be published to NPM with publish, and to GitHub with publishGithub.

Behind the dial, these are the gears that make this package tick. TypeScript is compiled with tsc, bundled with rollup, webified with browserify and terser. Documentation is generated with typedoc, which is also used to obtain DocsDetails in order to update index table in README using extra-markdown-text, generate wiki files, and update package metadata locally and on GitHub repo using @octokit/rest. Updating of package versions is achieved with npm view and semver. To spice up the console with colors, kleur is used.

The goals for the future include generating example file for RunKit, linking wiki from JsDoc, and duplicating example code from wiki to JsDoc. Did you find a bug? Or have a feature request?

Stability: Experimental.

const xbuild = require('extra-build');


// 1. Set version and publish package.
var m = xbuild.readMetadata('.');
// ā†’ {name, version, description, ...}
m.version = '2.0.0';
xbuild.writeMetadata('.', m);
xbuild.publish('.');
xbuild.publishGithub('.', 'owner');


// 2. Publish next version, update github details.
var m   = xbuild.readMetadata('.');
var ver = xbuild.nextUnpublishedVersion(m.name, m.version);
m.version = ver;
xbuild.writeMetadata('.', m);
xbuild.publish('.');
xbuild.publishGithub('.', 'owner');
xbuild.updateGithubRepoDetails();


// 3. Update keywords for package.
var m  = xbuild.readMetadata('.');
var p  = xbuild.loadDocs(['src/index.ts']);
var ds = p.children.map(xbuild.docsDetails);
var s = new Set([...m.keywords, ...ds.map(d => d.name)]);
m.keywords = Array.from(s);
xbuild.writeMetadata('.', m);


// 4. Restore package.json after publishing with updated version.
var _package = xbuild.readDocument('package.json');
var m = xbuild.readMetadata('.');
m.version = '2.0.0';
xbuild.writeMetadata('.', m);
xbuild.publish('.');
xbuild.writeDocument(_package);


// 5. Update README index table.
var owner = 'owner', repo = 'repo';
var p  = xbuild.loadDocs(['src/index.ts']);
var ds = p.children.map(xbuild.docsDetails);
var re = /namespace|function/i;
var dm = new Map(ds.map(d => [d.name, d]));
var txt = xbuild.readFileText('README.md');
txt = xbuild.wikiUpdateIndex(txt, dm, d => re.test(d.kind));
txt = xbuild.wikiUpdateLinkReferences(txt, dm, {owner, repo});
xbuild.writeFileText('README.md', txt);

Index

PropertyDescription
symbolnameGet symbol name for file.
keywordnameGet keyword name for file.
errorPrint error message to stderr with newline.
warnPrint warning message to stderr with newline.
logPrint log message to stdout with newline.
infoPrint info message to stdout with newline.
execExecute command with output, and print the command.
execStrExecute command and get its output as string.
readFileTextRead file text with Unix EOL.
writeFileTextWrite file text with system EOL.
readJsonRead JSON file as object.
writeJsonWrite object to JSON file.
readDocumentRead document.
writeDocumentWrite document.
gitCommitPushCommit new changes and push to remote.
gitSetupBranchSetup new branch and push to remote.
addBannerAdd banner (header comment) to script text.
bundleScriptBundle a script file with config.
webifyScriptWebify a script file.
jsdocifyScriptTransform JSDocs in a script file.
parseGithubUrlGet details from GitHub URL.
updateGithubRepoDetailsUpdate GitHub repository details.
readMetadataRead package.json data.
writeMetadataWrite package.json data.
registryGet current registry.
setRegistrySet current registry.
latestVersionGet latest package version.
nextUnpublishedVersionGet next unpublished version for package.
publishPublish package to NPM.
publishGithubPublish package to GitHub.
generateDocsGenerate docs using typedoc.
publishDocsPublish docs to gh-pages.
docsReferGet the reflection that is referred to.
docsNameGet name of a reflection.
docsLocationGet location of reflection.
docsFlagsGet flags of a reflection.
docsKindGet kind name of a reflection.
docsChildCountGet child count of a reflection.
docsParameterCountGet parameter count of a reflection (function).
docsSignatureCountGet signature count of a reflection.
docsTypeGet type name of a reflection.
docsDescriptionGet description of a reflection.
docsReturnsGet returns description of a reflection (function).
docsDetailsGet details of a reflection.
docsReferDetailsGet details of a reflection, referring the necessary details.
loadDocsLoad docs from source file.
wikiCodeReferenceGenerate reference code block for wiki.
wikiCodeExampleGenerate example code block for wiki.
wikiMarkdownGenerate markdown text for wiki.
wikiUpdateIndexUpdate the "Index" (property, description) table in markdown text.
wikiUpdateLinkReferencesUpdate link references in markdown text.
wikiUpdateDescriptionUpdate description in markdown text.
wikiUpdateCodeReferenceUpdate code reference in markdown text.

npm.io ORG DOI

2.2.43

9 months ago

2.2.42

12 months ago

2.2.40

1 year ago

2.2.41

1 year ago

2.2.39

1 year ago

2.2.37

1 year ago

2.2.38

1 year ago

2.2.35

1 year ago

2.2.36

1 year ago

2.2.33

1 year ago

2.2.34

1 year ago

2.2.31

1 year ago

2.2.32

1 year ago

2.2.30

1 year ago

2.2.28

2 years ago

2.2.29

2 years ago

2.2.1

2 years ago

2.2.0

2 years ago

2.2.3

2 years ago

2.2.2

2 years ago

2.2.5

2 years ago

2.2.4

2 years ago

2.2.7

2 years ago

2.2.6

2 years ago

2.1.2

2 years ago

2.1.1

2 years ago

2.1.4

2 years ago

2.1.3

2 years ago

2.1.6

2 years ago

2.1.5

2 years ago

2.1.8

2 years ago

2.1.7

2 years ago

2.1.0

2 years ago

2.2.9

2 years ago

2.2.8

2 years ago

2.0.35

2 years ago

2.0.36

2 years ago

2.0.33

2 years ago

2.0.34

2 years ago

2.0.32

2 years ago

2.1.16

2 years ago

2.0.48

2 years ago

2.1.17

2 years ago

2.1.14

2 years ago

2.0.46

2 years ago

2.1.15

2 years ago

2.0.47

2 years ago

2.1.12

2 years ago

2.0.44

2 years ago

2.1.13

2 years ago

2.0.45

2 years ago

2.1.10

2 years ago

2.0.42

2 years ago

2.1.11

2 years ago

2.0.43

2 years ago

2.0.41

2 years ago

2.1.18

2 years ago

2.1.19

2 years ago

2.1.27

2 years ago

2.1.28

2 years ago

2.1.25

2 years ago

2.1.26

2 years ago

2.1.23

2 years ago

2.1.24

2 years ago

2.1.21

2 years ago

2.1.22

2 years ago

2.1.20

2 years ago

2.1.29

2 years ago

2.1.34

2 years ago

2.1.32

2 years ago

2.1.33

2 years ago

2.1.30

2 years ago

2.1.31

2 years ago

2.2.17

2 years ago

2.2.18

2 years ago

2.2.15

2 years ago

2.2.16

2 years ago

2.2.13

2 years ago

2.2.14

2 years ago

2.2.11

2 years ago

2.2.12

2 years ago

2.2.10

2 years ago

2.2.19

2 years ago

2.2.26

2 years ago

2.2.27

2 years ago

2.2.24

2 years ago

2.2.25

2 years ago

2.2.22

2 years ago

2.2.23

2 years ago

2.2.20

2 years ago

2.2.21

2 years ago

2.1.9

2 years ago

2.0.26

2 years ago

2.0.27

2 years ago

2.0.24

2 years ago

2.0.25

2 years ago

2.0.22

2 years ago

2.0.23

2 years ago

2.0.28

2 years ago

2.0.29

2 years ago

2.0.31

2 years ago

2.0.30

2 years ago

2.0.15

2 years ago

2.0.16

2 years ago

2.0.13

2 years ago

2.0.14

2 years ago

2.0.11

2 years ago

2.0.12

2 years ago

2.0.19

2 years ago

2.0.17

2 years ago

2.0.18

2 years ago

2.0.20

2 years ago

1.4.8

2 years ago

2.0.21

2 years ago

1.4.7

2 years ago

1.4.6

2 years ago

1.4.5

2 years ago

1.4.4

2 years ago

1.4.3

3 years ago

1.4.2

3 years ago

1.3.32

3 years ago

1.3.35

3 years ago

1.3.33

3 years ago

1.3.34

3 years ago

1.4.1

3 years ago

1.4.0

3 years ago

1.3.31

3 years ago

1.3.30

3 years ago

1.3.29

3 years ago

1.3.28

3 years ago

1.3.27

3 years ago

1.3.19

3 years ago

1.3.20

3 years ago

1.3.21

3 years ago

1.3.24

3 years ago

1.3.25

3 years ago

1.3.22

3 years ago

1.3.23

3 years ago

1.3.26

3 years ago

1.3.17

3 years ago

1.3.18

3 years ago

1.3.16

3 years ago

1.3.15

3 years ago

1.3.13

3 years ago

1.3.14

3 years ago

1.3.11

3 years ago

1.3.12

3 years ago

1.3.7

3 years ago

1.3.6

3 years ago

1.3.5

3 years ago

1.3.4

3 years ago

1.3.3

3 years ago

1.3.2

3 years ago

1.3.1

3 years ago

1.3.0

3 years ago

1.2.91

3 years ago

1.2.90

3 years ago

1.2.89

3 years ago

1.2.88

3 years ago

1.2.87

3 years ago

1.2.86

3 years ago

1.2.85

3 years ago

1.2.84

3 years ago

1.2.83

3 years ago

1.2.82

3 years ago

1.2.81

3 years ago

1.2.80

3 years ago

1.2.79

3 years ago

1.2.78

3 years ago

1.2.76

3 years ago

1.2.77

3 years ago

1.2.75

3 years ago

1.2.74

3 years ago

1.2.73

3 years ago

1.2.71

3 years ago

1.2.72

3 years ago

1.2.70

3 years ago

1.2.69

3 years ago

1.2.68

3 years ago

1.2.60

3 years ago

1.2.63

3 years ago

1.2.64

3 years ago

1.2.61

3 years ago

1.2.62

3 years ago

1.2.67

3 years ago

1.2.65

3 years ago

1.2.66

3 years ago

1.2.41

3 years ago

1.2.42

3 years ago

1.2.40

3 years ago

1.2.45

3 years ago

1.2.46

3 years ago

1.2.43

3 years ago

1.2.44

3 years ago

1.2.49

3 years ago

1.2.47

3 years ago

1.2.48

3 years ago

1.2.52

3 years ago

1.2.53

3 years ago

1.2.50

3 years ago

1.2.51

3 years ago

1.2.56

3 years ago

1.2.57

3 years ago

1.2.54

3 years ago

1.2.55

3 years ago

1.2.58

3 years ago

1.2.59

3 years ago

1.2.38

3 years ago

1.2.39

3 years ago

1.2.37

3 years ago

1.2.34

3 years ago

1.2.35

3 years ago

1.2.36

3 years ago

1.2.33

3 years ago

1.2.32

3 years ago

1.2.31

3 years ago

1.2.29

3 years ago

1.2.30

3 years ago

1.2.28

3 years ago

1.2.27

3 years ago

1.2.26

3 years ago

1.2.25

3 years ago

1.2.24

3 years ago

1.2.23

3 years ago

1.2.22

3 years ago

1.2.18

3 years ago

1.2.19

3 years ago

1.2.20

3 years ago

1.2.21

3 years ago

1.2.17

3 years ago

1.2.16

3 years ago

1.2.15

3 years ago

1.2.12

3 years ago

1.2.13

3 years ago

1.2.11

3 years ago

1.2.14

3 years ago

1.2.10

3 years ago

1.2.9

3 years ago

1.2.8

3 years ago

1.2.7

3 years ago

1.2.6

3 years ago

1.2.5

3 years ago

1.2.4

3 years ago

1.2.3

3 years ago

1.2.2

3 years ago

1.2.1

3 years ago

1.2.0

3 years ago

1.1.28

3 years ago

1.1.27

4 years ago

1.1.26

4 years ago

1.1.25

4 years ago

1.1.24

4 years ago

1.1.23

4 years ago

1.1.22

4 years ago

1.1.19

4 years ago

1.1.21

4 years ago

1.1.20

4 years ago

1.1.16

4 years ago

1.1.15

4 years ago

1.1.14

4 years ago

1.1.18

4 years ago

1.1.17

4 years ago

1.1.13

4 years ago

1.1.12

4 years ago

1.1.9

4 years ago

1.1.11

4 years ago

1.1.10

4 years ago

1.1.8

4 years ago

1.1.7

4 years ago

1.1.6

4 years ago

1.1.1

4 years ago

1.1.0

4 years ago

1.1.5

4 years ago

1.1.4

4 years ago

1.1.3

4 years ago

1.1.2

4 years ago

1.0.225

4 years ago

1.0.224

4 years ago

1.0.223

4 years ago

1.0.220

4 years ago

1.0.222

4 years ago

1.0.221

4 years ago

1.0.219

4 years ago

1.0.217

4 years ago

1.0.218

4 years ago

1.0.216

4 years ago

1.0.215

4 years ago

1.0.214

4 years ago

1.0.213

4 years ago

1.0.212

4 years ago

1.0.208

4 years ago

1.0.207

4 years ago

1.0.211

4 years ago

1.0.210

4 years ago

1.0.209

4 years ago

1.0.206

4 years ago

1.0.205

4 years ago

1.0.204

4 years ago

1.0.203

4 years ago

1.0.202

4 years ago

1.0.201

4 years ago

1.0.200

4 years ago

1.0.199

4 years ago

1.0.198

4 years ago

1.0.197

4 years ago

1.0.196

4 years ago

1.0.195

4 years ago

1.0.194

4 years ago

1.0.193

4 years ago

1.0.190

4 years ago

1.0.192

4 years ago

1.0.191

4 years ago

1.0.189

4 years ago

1.0.188

4 years ago

1.0.187

4 years ago

1.0.186

4 years ago

1.0.185

4 years ago

1.0.183

4 years ago

1.0.184

4 years ago

1.0.182

4 years ago

1.0.181

4 years ago

1.0.180

4 years ago

1.0.178

4 years ago

1.0.179

4 years ago

1.0.177

4 years ago

1.0.176

4 years ago

1.0.175

4 years ago

1.0.174

4 years ago

1.0.173

4 years ago

1.0.172

4 years ago

1.0.171

4 years ago

1.0.170

4 years ago

1.0.165

4 years ago

1.0.167

4 years ago

1.0.166

4 years ago

1.0.169

4 years ago

1.0.168

4 years ago

1.0.164

4 years ago

1.0.163

4 years ago

1.0.162

4 years ago

1.0.161

4 years ago

1.0.160

4 years ago

1.0.159

4 years ago

1.0.158

4 years ago

1.0.157

4 years ago

1.0.156

4 years ago

1.0.155

4 years ago

1.0.154

4 years ago

1.0.153

4 years ago

1.0.152

4 years ago

1.0.151

4 years ago

1.0.149

4 years ago

1.0.150

4 years ago

1.0.148

4 years ago

1.0.147

4 years ago

1.0.146

4 years ago

1.0.145

4 years ago

1.0.144

4 years ago

1.0.143

4 years ago

1.0.142

4 years ago

1.0.141

4 years ago

1.0.140

4 years ago

1.0.139

4 years ago

1.0.138

4 years ago

1.0.132

4 years ago

1.0.131

4 years ago

1.0.134

4 years ago

1.0.133

4 years ago

1.0.130

4 years ago

1.0.136

4 years ago

1.0.135

4 years ago

1.0.137

4 years ago

1.0.129

4 years ago

1.0.128

4 years ago

1.0.127

4 years ago

1.0.126

4 years ago

1.0.125

4 years ago

1.0.124

4 years ago

1.0.123

4 years ago

1.0.121

4 years ago

1.0.120

4 years ago

1.0.122

4 years ago

1.0.119

4 years ago

1.0.118

4 years ago

1.0.117

4 years ago

1.0.116

4 years ago

1.0.107

4 years ago

1.0.106

4 years ago

1.0.109

4 years ago

1.0.108

4 years ago

1.0.105

4 years ago

1.0.110

4 years ago

1.0.112

4 years ago

1.0.111

4 years ago

1.0.114

4 years ago

1.0.113

4 years ago

1.0.115

4 years ago

1.0.101

4 years ago

1.0.103

4 years ago

1.0.102

4 years ago

1.0.104

4 years ago

1.0.100

4 years ago

1.0.99

4 years ago

1.0.98

4 years ago

1.0.97

4 years ago

1.0.96

4 years ago

1.0.66

4 years ago

1.0.69

4 years ago

1.0.68

4 years ago

1.0.67

4 years ago

1.0.73

4 years ago

1.0.72

4 years ago

1.0.71

4 years ago

1.0.70

4 years ago

1.0.77

4 years ago

1.0.76

4 years ago

1.0.75

4 years ago

1.0.74

4 years ago

1.0.79

4 years ago

1.0.78

4 years ago

1.0.80

4 years ago

1.0.84

4 years ago

1.0.83

4 years ago

1.0.82

4 years ago

1.0.81

4 years ago

1.0.88

4 years ago

1.0.87

4 years ago

1.0.86

4 years ago

1.0.85

4 years ago

1.0.89

4 years ago

1.0.91

4 years ago

1.0.90

4 years ago

1.0.95

4 years ago

1.0.94

4 years ago

1.0.93

4 years ago

1.0.62

4 years ago

1.0.61

4 years ago

1.0.60

4 years ago

1.0.65

4 years ago

1.0.64

4 years ago

1.0.63

4 years ago

1.0.48

4 years ago

1.0.47

4 years ago

1.0.49

4 years ago

1.0.51

4 years ago

1.0.50

4 years ago

1.0.55

4 years ago

1.0.54

4 years ago

1.0.53

4 years ago

1.0.52

4 years ago

1.0.59

4 years ago

1.0.58

4 years ago

1.0.57

4 years ago

1.0.56

4 years ago

1.0.46

4 years ago

1.0.44

4 years ago

1.0.45

4 years ago

1.0.39

4 years ago

1.0.40

4 years ago

1.0.43

4 years ago

1.0.42

4 years ago

1.0.41

4 years ago

1.0.38

4 years ago

1.0.37

4 years ago

1.0.36

4 years ago

1.0.35

4 years ago

1.0.19

4 years ago

1.0.2

4 years ago

1.0.18

4 years ago

1.0.1

4 years ago

1.0.17

4 years ago

1.0.0

4 years ago

1.0.16

4 years ago

1.0.9

4 years ago

1.0.8

4 years ago

1.0.7

4 years ago

1.0.6

4 years ago

1.0.5

4 years ago

1.0.4

4 years ago

1.0.3

4 years ago

1.0.22

4 years ago

1.0.21

4 years ago

1.0.20

4 years ago

1.0.26

4 years ago

1.0.25

4 years ago

1.0.24

4 years ago

1.0.23

4 years ago

1.0.29

4 years ago

1.0.28

4 years ago

1.0.27

4 years ago

1.0.33

4 years ago

0.0.26

4 years ago

1.0.32

4 years ago

0.0.27

4 years ago

1.0.31

4 years ago

0.0.28

4 years ago

1.0.30

4 years ago

1.0.34

4 years ago

1.0.11

4 years ago

1.0.10

4 years ago

1.0.15

4 years ago

1.0.14

4 years ago

1.0.13

4 years ago

1.0.12

4 years ago

0.0.24

4 years ago

0.0.25

4 years ago

0.0.22

4 years ago

0.0.23

4 years ago

0.0.21

4 years ago

0.0.20

4 years ago

0.0.19

4 years ago

0.0.15

4 years ago

0.0.11

4 years ago

0.0.12

4 years ago

0.0.13

4 years ago

0.0.14

4 years ago

0.0.10

4 years ago

0.0.9

4 years ago

0.0.8

4 years ago

0.0.7

4 years ago

0.0.6

4 years ago

0.0.5

4 years ago

0.0.4

4 years ago

0.0.3

4 years ago

0.0.2

4 years ago

0.0.1

4 years ago