Storetypetype Store = { readonly root: string; readonly os: Os };The store: its root folder and the system it is on.
The store of the dialect, the host half of an install: a folder of the user's own with a short path, a download kept only where it is the pinned one, one lock for each tool, and an install that is unpacked in a temporary folder inside the store and switched into its place by a rename that is retried where Windows refuses it (an antivirus program or a sync client holds a file). Nothing is written outside the store and no administrator rights are used.
The switch moves an existing copy aside first and removes it only when the new one is in place, so that a switch that fails leaves the old copy as it was. A rename refused with EPERM, EBUSY or EACCES is retried with a pause that grows; any other error ends it at once.
import { toolFolder } from "./store.ts";
// toolFolder(store, "bun", "1.4.4") is <store>/bun/1.4.4, with no platform in the pathStoretypetype Store = { readonly root: string; readonly os: Os };The store: its root folder and the system it is on.
osHerefunctionfunction osHere(): OsThe operating system this process runs on, as the store names it.
platformHerefunctionfunction platformHere(): string | undefinedThe platform this process runs on, named as the packaging ontology names it (linux-x64, macos-arm64, windows-x64), or nothing for one it has no name for.
storeOffunctionfunction storeOf(env: Env, os: Os): Store | undefinedThe store of a user, from the environment: the data folder of the program archon with tools; nothing where no home can be found.
toolFolderfunctionfunction toolFolder(store: Store, name: string, version: string): stringThe folder of a tool at a version: <store>/<name>/<version>, with no platform in it, so that the path stays short.
shimFolderfunctionfunction shimFolder(store: Store): stringThe folder of the shims of the store.
FsOpstypetype FsOps = {
readonly rename: (from: string, to: string) => Promise<void>;
readonly remove: (target: string) => Promise<void>;
readonly exists: (target: string) => Promise<boolean>;
readonly pause: (ms: number) => Promise<void>;
};What the switch does to the file system; a test passes one that fails as Windows does.
realFsconstno test imports itconst realFs: FsOpsThe real file system.
renameRetryingfunctionfunction renameRetrying(ops: FsOps, from: string, to: string, tries?: number): Promise<Result<void, string>>A rename, tried again where it is refused as a busy or guarded file is (EPERM, EBUSY, EACCES), with a pause that grows; any other error ends it.
switchIntofunctionfunction switchInto(ops: FsOps, temp: string, target: string, aside: string): Promise<Result<void, string>>Puts temp in place of target: an existing target is moved aside first and removed once the new one is in place, and where the switch fails the old copy is put back and temp is removed.
Steptypeno test imports ittype Step = "lock" | "download" | "checksum" | "unpack" | "switch";The steps of an install, as a failure names them.
InstallFailuretypeno test imports ittype InstallFailure = { readonly tool: string; readonly step: Step; readonly saw: string; readonly next: string };A failure: the tool, the step, what the step saw and the one action that is next.
describeFailurefunctionno test imports itfunction describeFailure(f: InstallFailure): stringA failure as one sentence.
InstallOptionstypeno test imports ittype InstallOptions = {
readonly retries: Retries;
readonly ops?: FsOps;
/** A word that makes a temporary name unique. */
readonly unique?: () => string;
/** How long to wait for another run that installs the same tool. */
readonly lockTimeoutMs?: number;
};What an install is done with.
Installedtypeno test imports ittype Installed = { readonly folder: string; readonly program: string; readonly record: InstallRecord; readonly fresh: boolean };Where a tool is.
readInstalledfunctionfunction readInstalled(store: Store, name: string, version: string, os?: Os): Promise<Installed | undefined>The record of a tool at a version in the store, where its program is there too.
installToolfunctionfunction installTool(store: Store, spec: InstallSpec, o: InstallOptions): Promise<Result<Installed, InstallFailure>>Installs a tool in the store: under its lock, from the cache or a verified download, unpacked beside its place and switched in; and a copy that is there and as pinned is answered with no network and no write.
Cleanedtypeno test imports ittype Cleaned = { readonly what: string; readonly path: string; readonly bytes: number };What clean removed.
cleanStorefunctionfunction cleanStore(store: Store, o: { readonly programs: boolean; }): Promise<readonly Cleaned[]>Removes what can be got again, each with its size: the cache, the leftover temporary folders and, where asked, the programs of the store.