extra-build

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

Property	Description
symbolname	Get symbol name for file.
keywordname	Get keyword name for file.
error	Print error message to stderr with newline.
warn	Print warning message to stderr with newline.
log	Print log message to stdout with newline.
info	Print info message to stdout with newline.
exec	Execute command with output, and print the command.
execStr	Execute command and get its output as string.
readFileText	Read file text with Unix EOL.
writeFileText	Write file text with system EOL.
readJson	Read JSON file as object.
writeJson	Write object to JSON file.
readDocument	Read document.
writeDocument	Write document.
gitCommitPush	Commit new changes and push to remote.
gitSetupBranch	Setup new branch and push to remote.
addBanner	Add banner (header comment) to script text.
bundleScript	Bundle a script file with config.
webifyScript	Webify a script file.
jsdocifyScript	Transform JSDocs in a script file.
parseGithubUrl	Get details from GitHub URL.
updateGithubRepoDetails	Update GitHub repository details.
readMetadata	Read package.json data.
writeMetadata	Write package.json data.
registry	Get current registry.
setRegistry	Set current registry.
latestVersion	Get latest package version.
nextUnpublishedVersion	Get next unpublished version for package.
publish	Publish package to NPM.
publishGithub	Publish package to GitHub.
generateDocs	Generate docs using typedoc.
publishDocs	Publish docs to gh-pages.
docsRefer	Get the reflection that is referred to.
docsName	Get name of a reflection.
docsLocation	Get location of reflection.
docsFlags	Get flags of a reflection.
docsKind	Get kind name of a reflection.
docsChildCount	Get child count of a reflection.
docsParameterCount	Get parameter count of a reflection (function).
docsSignatureCount	Get signature count of a reflection.
docsType	Get type name of a reflection.
docsDescription	Get description of a reflection.
docsReturns	Get returns description of a reflection (function).
docsDetails	Get details of a reflection.
docsReferDetails	Get details of a reflection, referring the necessary details.
loadDocs	Load docs from source file.
wikiCodeReference	Generate reference code block for wiki.
wikiCodeExample	Generate example code block for wiki.
wikiMarkdown	Generate markdown text for wiki.
wikiUpdateIndex	Update the "Index" (property, description) table in markdown text.
wikiUpdateLinkReferences	Update link references in markdown text.
wikiUpdateDescription	Update description in markdown text.
wikiUpdateCodeReference	Update code reference in markdown text.