Fetch an executable, but only if needed
Intended for use downloading exact versions of executables and storing them on a per-project basis, rather than relying on a globally stored version being good enough for everything.
npm i --save fetch-executable
Then:
import { fetchExecutable } from 'fetch-executable';
await fetchExecutable({
target: './my-exec',
url: 'https://example.com/download/my-exec/{version}',
version: '1.2.3',
versionExecArgs: ['--version'],
});This will:
- run
./my-exec --versionand check if the output is1.2.3 - if so, then done
- if not (because the output was the wrong version, or it errored, or the file just wasn't there)
- download the file from
https://example.com/download/my-exec/1.2.3 - save it to
./my-exec - make it executable
- check it now passes the version check
- download the file from
There is a selection of executables for which the steps to download and check the version are bundled. These can be installed with eg:
import { kubectl } from 'fetch-executable/executables';
await kubectl('./kubectl', '1.23.0');The full set is as follows, where the name of the function to download matches the name of the tool. Note also that these functions take an optional third argument that allow overriding of any options in the full set of options (see below).
kubectlsopshelmfilehelmeksctlminikubegomplatemysqlshusqlterraformjqvagrantyqkubentflux
This is the full set of options that can be passed to
fetchExecutable (or as the optional third argument to any of the
shortcuts, but with no required options).
Required?: yes
Type: string
The target local path on disk, either absolute, or relative to working directory.
Required?: yes
Type: string (is formatted)
URL from which to download if required.
Required?: must set one of: execIsOk; version; hashValueUrl
Type: (filepath: string) => Promise<boolean>
Given a filepath to an executable that might be the right one, return
true if it is, false if it is not. If this is set in addition to
either of version or hashValueUrl, then all tests must pass for
the local executable to be considered "ok".
Required?: must set one of: execIsOk; version; hashValueUrl
Type: string
The desired version. Used with versionExecArgs to determine if the
version of a local executable is as desired. Passed to
formatted.
Required?: no, defaults to []. Only relevant if version is set.
Type: Array<string>
Command line arguments to pass to the local executable to make it print its version.
Required?: no, defaults capturing stdout
Type: boolean
If set to true, capture stderr from the executed command. Otherwise,
captures stdout.
Required?: no, defaults to no post processing. Only relevant if version is set.
Type: (execOutput: string) => string
Given the string output from running the local executable (with
versionExecArgs), process it to return the version number for
comparison with the value set for version.
Required?: no, defaults to saving the downloaded file as-is
Type: string (is formatted)
If set, treat the downloaded file as a tar archive, and extract the
file at the given path. Can be used in conjunction with gzExtract: true to
handle .tar.gz files.
Required?: no, defaults to saving the downloaded file as-is
Type: string (is formatted)
If set, treat the downloaded file as a zip archive, and extract the
file at the given path.
Required?: no, defaults to assuming the desired executable is a file
at pathInTar. Only relevant if pathInTar is set (not yet supported
with pathInZip).
Type: string (is formatted)
If set, treats pathInTar as a directory, and extracts the contents
to a directory created at target. The executable itself is then at
${target}/${executableSubPathInDir}.
Required?: no, defaults to no symlink created.
Type: string
If set, creates a symlink from the given path to the executable at
${target}/${executableSubPathInDir}.
Required?: no, defaults to saving the downloaded file as-is
Type: boolean
If set to true, gzip-extract the downloaded file. Can be used in
conjunction with pathInTar to handle .tar.gz files.
Required?: no, defaults to saving the downloaded file as-is
Type: boolean
If set to true, bz2-extract the downloaded file. Can be used in
conjunction with pathInTar to handle .tar.bz2 files.
Note: if bz2Extract and gzExtract are both set to true, will
gzip-extract then bz2-extract, but this is not expected to be a real
use case.
Required?: must set one of: execIsOk; version; hashValueUrl
Type: string (is formatted)
URL that returns checksum data about the executable file. Possibly
with hashMethod and hashChecksumFileMatchFilepath, use this to
check if the local file is the correct version by comparing its hash
with a published, expected hash. Note that need for the hash of the
executable itself to be published at this URL, not of the archive used
to distribute it.
Required?: no, by default uses sha256. Only relevant if hashValueUrl is set.
Type: string
A hash algorithm that node's crypto.createHash understands.
Required?: no, by default the value fetched from hashValueUrl
as-is. Only relevant if hashValueUrl is set.
Type: string (is formatted)
If the data returned from hashValueUrl is not a single hash, but
rather a list of hashes as returned by a utility like sha256sum,
that lists hashes and filenames, use this to identify the filename
whose hash to use.
Required?: no
Type: (message: FetchExecutableMessage) => void
A function that is called when fetchExecutable does things. Intended
to allow for communication with the user about what is going on, for
example, when downloading a potentially large file over a potentially
slow network connection.
Note that this takes precedence over messageHandlerBuiltin.
Note that FetchExecutableMessage is exported and has the form:
interface FetchExecutableMessage {
message: string;
kind: string;
target: string;
isVerbose: boolean;
}The kind string attribute will be one of:
'executable_is_ok', when the pre-existing executable has been checked and is OK'fetching', when starting to fetch'fetch_progress', progress during fetch'saving', when starting to save'done', when saved and made executable
Deprecated alias for messageHandler.
Required?: no
Type: string (one of: 'string', 'json')
Shortcuts for some simple builtin messageHandlers.
'string': just prints themessageattribute'json': just prints the whole message as a JSON object
If a string other than the above options is passed, is ignored.
Deprecated alias for messageHandlerBuiltin.
Required?: no, by default verbose messages not included. Only relevant
if messageHandlerBuiltin is set.
Type: boolean
Whether the builtin messageHandlers should include the messages that have
isVerbose: true.
Deprecated alias for messageHandlerBuiltinVerbose.
Required?: no, by default messages are printed to
process.stderr. Only relevant if messageHandlerBuiltin is set.
Type: stream.Writable
The stream to which messages from the builtin messageHandler are written.
Deprecated alias for messageHandlerBuiltinStream.
As a convenience, for the string options noted above, can perform formatting with the following variables:
version, value of theversionoption, if setplatform, value ofprocess.platformarch, value ofprocess.arch
Also, the following transformers are available:
capitalize, upper-case the first characterx64ToAmd64, if the passed value is'x64', return'amd64'(intended for use witharch)
Eg:
url: 'https://example.com/download/my-exec/{version}/{platform!capitalize}.tar.gz',
version: '1.2.3',
gzExtract: true,
pathInTar: '{arch!x64ToAmd64}/my-exec',
On a Linux, 64-bit OS, would retrieve the file from
https://example.com/download/my-exec/1.2.3/Linux.tar.gz, and gzip
extract, and retrieve the file from amd64/my-exec.