Skip to content

nodef/extra-build

Repository files navigation

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.


ORG DOI