IF Commons GitHub

store

Written to: 7 requirements: 7 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-native-pinned-store FR-001, 0003-native-pinned-store FR-002, 0003-native-pinned-store FR-003, 0003-native-pinned-store FR-004, 0003-native-pinned-store FR-005, 0003-native-pinned-store FR-006 and 1 more

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 path

Source: commons/archon-dialect-native-pinned/src/store.ts

12 of 19 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Storetype
type Store = { readonly root: string; readonly os: Os };

The store: its root folder and the system it is on.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

osHerefunction
function osHere(): Os

The operating system this process runs on, as the store names it.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

platformHerefunction
function platformHere(): string | undefined

The 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

storeOffunction
function storeOf(env: Env, os: Os): Store | undefined

The store of a user, from the environment: the data folder of the program archon with tools; nothing where no home can be found.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

toolFolderfunction
function toolFolder(store: Store, name: string, version: string): string

The folder of a tool at a version: <store>/<name>/<version>, with no platform in it, so that the path stays short.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

shimFolderfunction
function shimFolder(store: Store): string

The folder of the shims of the store.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

FsOpstype
type 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

realFsconstno test imports it
const realFs: FsOps

The real file system.

renameRetryingfunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

switchIntofunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Steptypeno test imports it
type Step = "lock" | "download" | "checksum" | "unpack" | "switch";

The steps of an install, as a failure names them.

InstallFailuretypeno test imports it
type 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 it
function describeFailure(f: InstallFailure): string

A failure as one sentence.

InstallOptionstypeno test imports it
type 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 it
type Installed = { readonly folder: string; readonly program: string; readonly record: InstallRecord; readonly fresh: boolean };

Where a tool is.

readInstalledfunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

installToolfunction
function 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.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

Cleanedtypeno test imports it
type Cleaned = { readonly what: string; readonly path: string; readonly bytes: number };

What clean removed.

cleanStorefunction
function 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.