nish/release
What the newest release of a project on GitHub is, whether it is newer than the one running, and a small cache so a program asks at most once a day.
import {
ReleaseCache,
ReleaseVersion,
releaseBaseAllowed,
releaseCacheFresh,
releaseCacheParse,
releaseCacheRead,
releaseCacheWrite,
releaseCheckCached,
releaseCompare,
releaseFetchInstaller,
releaseFileTrusted,
releaseIsNewer,
releaseLatest,
releaseParseVersion,
releaseTagFromLocation,
releaseValidVersion,
} from "nish/release";
import { releaseCheckCached, releaseLatest } from "nish/release"
const latest: string | null = releaseLatest("https://github.com/owner/repo", 2000)
const newer: string | null = releaseCheckCached(
"https://github.com/owner/repo", "1.2.0", "/home/me/.cache/app/latest", 86400000, 2000)
releaseBaseAllowed
Whether base is a URL this module will ask: https://, or http:// only to this machine (127.0.0.1, localhost or [::1]), which is what a test server listens on.
releaseCacheFresh
Whether a cache checked at checkedMs still answers at nowMs: younger than maxAgeMs, and not dated in the future, which a clock set back or a planted file would give.
releaseCacheParse
The cache's text as a ReleaseCache, or null when it is not exactly the two lines checked <ms> and latest <version> (the version empty or valid), with at most a final newline after them.
releaseCacheRead
The cache at path, or null when there is none, it cannot be believed (see releaseFileTrusted; its directory, too, must be a directory this user owns that no one else can write, so nobody else can swap the file between the check and the read) or it does not parse.
releaseCacheWrite
Writes the cache at path: its directory is created mode 0700 when missing (its parent must exist), the text goes to a new temporary file beside it of mode 0600, and that is renamed over path, so a reader sees the old cache or the new one and a link planted at path is replaced, never followed.
releaseCheckCached
The newest release when it is newer than current, from the cache at cachePath while it is fresh and believed, else from releaseLatest, whose answer (or its failure, as "") is written back so the next call within maxAgeMs asks nothing.
releaseCompare
Two versions in semantic-version order: the numbers, then the prerelease, where a prerelease sorts below its release; build metadata is ignored.
releaseFetchInstaller
The install.sh of release version, fetched from <rawBase>/v<version>/install.sh and written to path.
releaseFileTrusted
Whether the file at path may be believed: a regular file (a symbolic link is not followed), owned by this process's effective user, and writable by neither its group nor every user.
releaseIsNewer
Whether candidate is strictly newer than current.
releaseLatest
The newest release of the repository at base, read from where <base>/releases/latest redirects.
releaseParseVersion
v as a semantic version, major.minor.patch with an optional -pre and +build, or null when it is not one.
releaseTagFromLocation
The version a /releases/latest redirect names: location must be exactly <base>/releases/tag/v<version>, and the version must parse.
releaseValidVersion
Whether v may be put in a URL as a release version: not empty, starting with a digit, holding only ASCII letters, digits, ., - and +, and never ...
ReleaseCache
The cache's contents: when the check ran and what it found.
ReleaseVersion
A parsed semantic version.
-
releaseValidVersion(v)— whethervis a version that may go in a URL: it starts with a digit and holds only letters, digits,.,-and+, with no... The same rule asinstall.sh'snish_valid_version. -
releaseParseVersion(v)andreleaseCompare(a, b)— semantic versions,major.minor.patch[-pre][+build]. A prerelease sorts below its release and build metadata is ignored. -
releaseIsNewer(candidate, current)— true only when both parse and the candidate is strictly newer, so a version that does not parse is never newer and nothing here ever proposes a downgrade. -
releaseTagFromLocation(base, location)— the version a/releases/latestredirect names, or null for anything that is not exactly<base>/releases/tag/v<version>. -
releaseLatest(base, timeoutMs)— asks<base>/releases/latestonce, without following the redirect, and answers its version or null. Every failure is null: a server that is down, slow, refuses, or answers anything but a redirect to a release tag. -
releaseCacheRead,releaseCacheWriteandreleaseCheckCached— the answer kept in a file the program names, believed only when it is a regular file this user owns that no one else can write, and only formaxAgeMs(a check dated in the future counts as stale). -
releaseFetchInstaller(rawBase, version, path, timeoutMs)— theinstall.shof one release tag, written to a file for the caller to run, never piped into a shell.
Nothing here runs under a wasm32 build: it reaches the network and reads file
owners. The record of what it defends against is docs/security/release.md.
Functions
releaseBaseAllowed
Whether base is a URL this module will ask: https://, or http:// only
to this machine (127.0.0.1, localhost or [::1]), which is what a test
server listens on.
const releaseBaseAllowed: (base: string) => boolean
basestringrequiredThe URL.
returnsbooleanTrue when the URL may be fetched.
releaseCacheFresh
Whether a cache checked at checkedMs still answers at nowMs: younger
than maxAgeMs, and not dated in the future, which a clock set back or a
planted file would give.
const releaseCacheFresh: (
cache: ReleaseCache,
nowMs: i64,
maxAgeMs: i64,
) => boolean
cacheReleaseCacherequiredThe cache.
nowMsi64requiredThe time now, in milliseconds since 1970.
maxAgeMsi64requiredHow long an answer stays fresh.
returnsbooleanTrue when the cache need not be refreshed.
releaseCacheParse
The cache's text as a ReleaseCache, or null when it is not exactly the two
lines checked <ms> and latest <version> (the version empty or valid),
with at most a final newline after them.
const releaseCacheParse: (
text: string,
) => ReleaseCache | null
textstringrequiredThe file's contents.
returnsReleaseCache | nullThe parsed cache, or null.
releaseCacheRead
The cache at path, or null when there is none, it cannot be believed (see
releaseFileTrusted; its directory, too, must be a directory this user
owns that no one else can write, so nobody else can swap the file between
the check and the read) or it does not parse. Its format is two lines,
checked <ms> and latest <version>, the version empty when the check found
none.
const releaseCacheRead: (
path: string,
) => ReleaseCache | null
pathstringrequiredThe cache file.
returnsReleaseCache | nullWhat the cache holds, or null.
releaseCacheWrite
Writes the cache at path: its directory is created mode 0700 when missing
(its parent must exist), the text goes to a new temporary file beside it of
mode 0600, and that is renamed over path, so a reader sees the old cache or
the new one and a link planted at path is replaced, never followed.
const releaseCacheWrite: (
path: string,
latest: string,
nowMs: i64,
) => boolean
pathstringrequiredThe cache file.
lateststringrequiredThe version found, or "" for none.
nowMsi64requiredWhen the check ran, in milliseconds since 1970.
returnsbooleanTrue when the cache was written.
releaseCheckCached
The newest release when it is newer than current, from the cache at
cachePath while it is fresh and believed, else from releaseLatest, whose
answer (or its failure, as "") is written back so the next call within
maxAgeMs asks nothing.
const releaseCheckCached: (
base: string,
current: string,
cachePath: string,
maxAgeMs: i64,
timeoutMs: i32,
) => string | null
basestringrequiredThe repository URL, as releaseLatest takes it.
currentstringrequiredThe version running now.
cachePathstringrequiredThe cache file; its directory's parent must exist.
maxAgeMsi64requiredHow long an answer stays fresh, e.g. 86400000 for a day.
timeoutMsi32requiredThe most milliseconds a check may take.
returnsstring | nullThe newer version, or null when there is none or none is known.
releaseCompare
Two versions in semantic-version order: the numbers, then the prerelease, where a prerelease sorts below its release; build metadata is ignored. A version that does not parse sorts below every one that does, and two that do not parse compare equal.
const releaseCompare: (a: string, b: string) => i32
astringrequiredThe first version, without a leading v.
bstringrequiredThe second version, without a leading v.
returnsi32-1, 0 or 1 as a is older than, the same as, or newer than b.
releaseFetchInstaller
The install.sh of release version, fetched from
<rawBase>/v<version>/install.sh and written to path. It is the script of
that tag, never of a branch, and it goes to a file so the caller runs it with
sh <path> — nothing fetched is ever piped into a shell. path should be in
a directory only this user can write.
const releaseFetchInstaller: (
rawBase: string,
version: string,
path: string,
timeoutMs: i32,
) => boolean
rawBasestringrequiredThe raw-content URL, e.g. https://raw.githubusercontent.com/owner/repo: https, or http to this machine.
versionstringrequiredThe release to fetch, without a v; refused unless releaseValidVersion.
pathstringrequiredWhere to write the script.
timeoutMsi32requiredThe most milliseconds the whole request may take.
returnsbooleanTrue when a 200 answer was written to path.
releaseFileTrusted
Whether the file at path may be believed: a regular file (a symbolic link
is not followed), owned by this process's effective user, and writable by
neither its group nor every user.
const releaseFileTrusted: (path: string) => boolean
pathstringrequiredThe file.
returnsbooleanTrue when the file may be read and believed.
releaseIsNewer
Whether candidate is strictly newer than current. Both must parse: a
version that does not is never newer, and neither is the same release or an
older one, so the answer never suggests a downgrade.
const releaseIsNewer: (
candidate: string,
current: string,
) => boolean
candidatestringrequiredThe version that might be newer.
currentstringrequiredThe version running now.
returnsbooleanTrue only when both parse and candidate is the newer.
releaseLatest
The newest release of the repository at base, read from where
<base>/releases/latest redirects. The redirect is not followed and needs
no token. Null when the server cannot be reached within timeoutMs, answers
anything but a 3xx, or redirects anywhere but a release tag of base.
const releaseLatest: (
base: string,
timeoutMs: i32,
) => string | null
basestringrequiredThe repository URL, e.g. https://github.com/owner/repo: https, or http to this machine.
timeoutMsi32requiredThe most milliseconds the whole request may take.
returnsstring | nullThe newest version, without a v, or null.
releaseParseVersion
v as a semantic version, major.minor.patch with an optional -pre and
+build, or null when it is not one. A leading v is not accepted; strip
it first.
const releaseParseVersion: (
v: string,
) => ReleaseVersion | null
vstringrequiredThe version text.
returnsReleaseVersion | nullThe parsed version, or null.
releaseTagFromLocation
The version a /releases/latest redirect names: location must be exactly
<base>/releases/tag/v<version>, and the version must parse. A redirect anywhere else — another repository, a login
page, the releases list when there is no release, a query or fragment — names
none.
const releaseTagFromLocation: (
base: string,
location: string,
) => string | null
basestringrequiredThe repository URL, e.g. https://github.com/owner/repo, with no trailing slash.
locationstringrequiredThe redirect's Location header.
returnsstring | nullThe version, without a v, or null.
releaseValidVersion
Whether v may be put in a URL as a release version: not empty, starting
with a digit, holding only ASCII letters, digits, ., - and +, and
never ... What it rules out is a version that reaches past the tag in a
path — a /, a .., a ?, a #, a %, whitespace.
const releaseValidVersion: (v: string) => boolean
vstringrequiredThe version, without a leading v.
returnsbooleanTrue when the version is safe to put in a release URL.
Classes
ReleaseCache
The cache's contents: when the check ran and what it found.
class ReleaseCache
| Member | |
|---|---|
new ReleaseCache() |
|
checkedMs: i64 |
When the check ran, in milliseconds since 1970 (Date.now()'s clock). |
latest: string |
The version the check found, or "" when it found none. |
ReleaseVersion
A parsed semantic version. pre is the prerelease after the -, empty for a
release; build metadata after the + is dropped, as it never orders.
class ReleaseVersion
| Member | |
|---|---|
new ReleaseVersion() |
|
major: i64 |
The major number. |
minor: i64 |
The minor number. |
patch: i64 |
The patch number. |
pre: string |
The prerelease identifiers, dot-separated, or "" for a release. |

