@osdlc/tiered-dirs 0.0.0-stage → 0.3.0

package/dist/base-dirs.d.ts

@@ -0,0 +1,311 @@
+/**
+ * The horizontal axis: how durable a piece of state is. The vertical axis —
+ * who shares it — is the tier (see `tiered-dirs.ts`).
+ *
+ * A caller names both: `suite('notes').cache()`.
+ *
+ * Exhaustive on purpose, as in the Rust twin: a new home changes every
+ * caller's layout, so adding one is a breaking (0.x minor) release.
+ *
+ * Stable in 0.x.
+ */
+export type Home = 'durable' | 'config' | 'cache' | 'state' | 'logs' | 'runtime';
+/**
+ * Every {@link Home}, in table order.
+ *
+ * Stable in 0.x.
+ */
+export declare const HOMES: readonly Home[];
+/**
+ * Which per-OS table the homes come from when no override moves them. The two
+ * differ on macOS only: `native` is Apple's places, `xdg` is the XDG Base
+ * Directory rules. Linux uses XDG under both, and on Windows `xdg` means
+ * `native`. A CLI or developer tool uses `xdg`; a GUI app uses `native`. The
+ * Rust twin's `Convention` has the same two.
+ *
+ * A minor release may add a convention, as the Rust `Convention` is
+ * `#[non_exhaustive]`. A `switch` over it needs a `default` arm.
+ *
+ * Stable in 0.x.
+ */
+export type Convention = 'native' | 'xdg';
+/**
+ * Every {@link Convention}. The first is the default.
+ *
+ * Stable in 0.x.
+ */
+export declare const CONVENTIONS: readonly Convention[];
+/**
+ * Parse a {@link Convention}: exactly `native` or `xdg`, in lower case,
+ * untrimmed. The Rust twin's `Convention::from_str` is the same rule.
+ *
+ * Throws {@link TieredDirsError} with code `INVALID_CONVENTION` for any other
+ * value. {@link EnvVars.convention} is read differently: it is trimmed first.
+ *
+ * Stable in 0.x.
+ */
+export declare function parseConvention(value: string): Convention;
+/**
+ * The per-OS roots the whole package is built on.
+ *
+ * This is the injectable seam. Nothing below it reads the environment: a
+ * `TieredDirs` resolves its roots once, at construction, and every path after that
+ * is pure string work. That is what lets a server that cannot read the
+ * environment hand in roots from its own configuration, while a command-line
+ * program builds them from the environment.
+ *
+ * Every field is `readonly`: build a new value to change a root, as
+ * {@link rootedBaseDirs} and the `overrides` option do.
+ *
+ * Stable in 0.x.
+ */
+export interface BaseDirs {
+    /** Long-lived state that must survive a cache purge. */
+    readonly durable: string;
+    /** User-editable configuration. */
+    readonly config: string;
+    /** Regenerable data. The OS may delete this at any time. */
+    readonly cache: string;
+    /** State that should outlive a restart but is not user data: history, trust markers. */
+    readonly state: string;
+    /** Log files. Never folded into `cache` — the OS purges cache. */
+    readonly logs: string;
+    /** Pidfiles, sockets, locks. Never under `cache`; see {@link systemBaseDirs}. */
+    readonly runtime: string;
+    /**
+     * The platform temp directory. Not a {@link Home}: nothing here outlives the
+     * call that wrote it, so it is untiered and reached through `TieredDirs.scratch()`
+     * rather than through a tier.
+     */
+    readonly scratch: string;
+}
+/**
+ * The names of the environment variables that move base directories. Build one
+ * with {@link envVars}, which derives every name from a prefix.
+ *
+ * A minor release may add a name, as the Rust `EnvVars` is
+ * `#[non_exhaustive]`. An object built by hand would then miss it, so build
+ * one with {@link envVars}. `dirs[home]` is the Rust `EnvVars::dir`.
+ *
+ * Stable in 0.x.
+ */
+export interface EnvVars {
+    /**
+     * Moves every base directory not moved by its own variable into the
+     * {@link rootedBaseDirs} layout under the named root.
+     */
+    readonly root: string;
+    /** The variable that moves one base directory. */
+    readonly dirs: Readonly<Record<keyof BaseDirs, string>>;
+    /**
+     * When set (non-empty), {@link systemBaseDirs} throws instead of falling back
+     * to an OS home. A test runner sets it, and a child process inherits it.
+     */
+    readonly requireOverride: string;
+    /**
+     * Picks the {@link Convention}, over the one the caller passed: `native` or
+     * `xdg`. Moves no directory itself.
+     */
+    readonly convention: string;
+}
+/**
+ * {@link EnvVars} named from one prefix: `<P>_ROOT`, `<P>_DURABLE_DIR`,
+ * `<P>_CONFIG_DIR`, `<P>_CACHE_DIR`, `<P>_STATE_DIR`, `<P>_LOGS_DIR`,
+ * `<P>_RUNTIME_DIR`, `<P>_SCRATCH_DIR`, `<P>_REQUIRE_OVERRIDE` and
+ * `<P>_CONVENTION`. The Rust twin's `env_vars!` derives the same names.
+ *
+ * Stable in 0.x.
+ */
+export declare function envVars(prefix: string): EnvVars;
+/**
+ * Every variable that moves a base directory: the root and the seven
+ * per-directory names. Excludes {@link EnvVars.requireOverride} and
+ * {@link EnvVars.convention}, which move nothing.
+ *
+ * Stable in 0.x.
+ */
+export declare function overrideVars(vars: EnvVars): readonly string[];
+/**
+ * Whether `env` sets any of {@link overrideVars} to a non-empty value. The
+ * Rust twin's `EnvVars::is_overridden` is the same test.
+ *
+ * Stable in 0.x.
+ */
+export declare function isOverridden(vars: EnvVars, env?: Record<string, string | undefined>): boolean;
+/**
+ * Every base directory under one stub root: `<root>/durable`, `<root>/config`,
+ * `<root>/cache`, `<root>/state`, `<root>/logs`, `<root>/scratch`, and runtime
+ * at `<root>/durable/run`.
+ *
+ * The test and parity-fixture seam, and the layout {@link EnvVars.root} selects. The
+ * Rust twin's `BaseDirs::rooted` has the same layout, so a fixture row asserts
+ * identical absolute paths on both arms.
+ *
+ * Stable in 0.x.
+ */
+export declare function rootedBaseDirs(root: string): BaseDirs;
+/**
+ * How {@link systemBaseDirs} and `TieredDirs.fromEnv` resolve. Every input is
+ * optional and injectable. The Rust twin's `ResolveOptions` has `convention`
+ * and `testRoot`; `platform`, `env`, `home` and `overrides` are this twin's
+ * own seams.
+ *
+ * Stable in 0.x.
+ */
+export interface ResolveOptions {
+    /** Defaults to `process.platform`. */
+    platform?: string;
+    /**
+     * The per-OS table to use. Defaults to `native`. {@link EnvVars.convention}
+     * beats it when set.
+     */
+    convention?: Convention;
+    /**
+     * Defaults to `process.env`. Injecting this means the supplied environment
+     * is the whole story: the host's real home directory is not consulted. The
+     * override variables are read from it too.
+     */
+    env?: Record<string, string | undefined>;
+    /** Home directory. Overrides `HOME` / `USERPROFILE` when given. */
+    home?: string;
+    /**
+     * Replace individual roots, ahead of the environment. An overridden root is
+     * taken as-is and needs no home directory. It is not a base for the others:
+     * overriding `durable` here leaves `runtime` and `logs` where the
+     * environment and the per-OS table put them.
+     */
+    overrides?: Partial<BaseDirs>;
+    /**
+     * Whether an unset root variable reads as {@link testRoot} in a test runner
+     * process. Defaults to `true`. With `false`, resolution runs as it would
+     * outside a test runner: {@link EnvVars.root} and
+     * {@link EnvVars.requireOverride} still apply. Has no effect when `env` or
+     * `home` is injected, since neither test rule runs then.
+     */
+    testRoot?: boolean;
+}
+/**
+ * Resolve the base directories. Each takes the first answer in this order:
+ *
+ * 1. `opts.overrides`.
+ * 2. The root's own variable, `vars.dirs[key]` ({@link EnvVars.dirs}).
+ * 3. `vars.root` ({@link EnvVars.root}) — the {@link rootedBaseDirs} layout.
+ * 4. The per-OS table below, for the convention: {@link EnvVars.convention}
+ *    when set, else `opts.convention`, else `native`. The variable is
+ *    trimmed, then must be exactly `native` or `xdg`; anything else throws.
+ *
+ * Runtime follows durable: when the runtime variable is unset but durable is
+ * moved by step 2 or 3, runtime is `<durable>/run`, never the OS runtime
+ * directory. An empty variable counts as unset; a relative one throws. The
+ * Rust twin's `BaseDirs::from_env` resolves steps 2–4 the same way, held to it
+ * by the parity fixture's `env_cases`.
+ *
+ * The per-OS table this package owns so no caller has to. Linux, and macOS
+ * under `xdg`, use the XDG column; Windows uses its column under both.
+ *
+ * | home    | macOS, `native`                | XDG (Linux/other; macOS `xdg`)  | Windows              |
+ * |---------|--------------------------------|---------------------------------|----------------------|
+ * | durable | `~/Library/Application Support`| `$XDG_DATA_HOME`, `~/.local/share` | `%APPDATA%`, `<home>/AppData/Roaming` |
+ * | config  | `~/Library/Application Support`| `$XDG_CONFIG_HOME`, `~/.config` | `%APPDATA%`, `<home>/AppData/Roaming` |
+ * | cache   | `~/Library/Caches`             | `$XDG_CACHE_HOME`, `~/.cache`   | `%LOCALAPPDATA%`, `<home>/AppData/Local` |
+ * | state   | `~/Library/Application Support`| `$XDG_STATE_HOME`, `~/.local/state` | `<local>/state`, where `<local>` is the cache cell |
+ * | logs    | `~/Library/Logs`               | `$XDG_STATE_HOME`, `~/.local/state` | `<durable>/logs` |
+ * | runtime | `<durable>/run`                | `$XDG_RUNTIME_DIR`, `<durable>/run` | `<durable>/run`  |
+ * | scratch | `$TMPDIR`, `/tmp`              | `$TMPDIR`, `/tmp`               | `%TEMP%`, `%TMP%`, `<home>/AppData/Local/Temp` |
+ *
+ * A relative `XDG_*` value is ignored, as the XDG spec says, and `~` is not
+ * expanded. Under XDG, logs and state share one directory.
+ *
+ * Two of those cells need care:
+ *
+ * - `logs` has no cross-platform library equivalent. macOS wants
+ *   `~/Library/Logs`; where the OS offers nothing, logs land at
+ *   `<durable>/logs`. They are never folded into `cache`.
+ * - `runtime` is real only under the XDG table (Linux, and macOS under
+ *   `xdg`), and only when `XDG_RUNTIME_DIR` is set. Everywhere else it
+ *   resolves under `<durable>/run` — deliberately not under cache, because the
+ *   OS may purge cache while the process a pidfile describes is still alive.
+ *   State is never cache either: on Windows it is `<local>/state`, beside
+ *   each tier's cache folder. The reserved segment names keep them apart.
+ *
+ * `scratch` is resolved from the injected environment rather than by calling
+ * `os.tmpdir()`, which reads the real `process.env` and would make an injected
+ * environment stop being the whole story. The Rust twin asks its own platform
+ * the same question; the two roots need not match, because parity pins only
+ * what sits below a root.
+ *
+ * Throws {@link TieredDirsError}. Its `code` is `MISSING_BASE_DIR` when a
+ * root falls back to the home directory and none can be found,
+ * `RELATIVE_OVERRIDE` when an override variable is not absolute,
+ * `INVALID_CONVENTION` when {@link EnvVars.convention} names no convention,
+ * and `OVERRIDE_REQUIRED` as the second test rule below says. Headless CI and
+ * sandboxes do not always have a home directory.
+ *
+ * Two test rules run first, and only when neither `env` nor `home` is
+ * injected (an injected environment is the whole story):
+ *
+ * - In a test runner process with the root variable unset and `HOME` not
+ *   moved, the root reads as {@link testRoot}:
+ *   `<tmp>/tiered-dirs-test-<pid>-<start ms>`, unique per process and
+ *   cached per module instance (per test file under Vitest's default isolation).
+ *   `opts.testRoot: false` turns this rule off; the next one still applies.
+ *   A test runner process has a test file as its entry point and runs
+ *   under `NODE_ENV=test`, `NODE_TEST_CONTEXT` (set by `node --test`), Bun, or
+ *   a Vitest worker. Bun counts on its own because `bun test` keeps a
+ *   `NODE_ENV` that is already set. A Vitest worker has `VITEST_WORKER_ID` or
+ *   `VITEST_POOL_ID` set, and its entry point is a file in the `dist/workers`
+ *   folder of the `vitest` package (Vitest 4 and later) or tinypool's
+ *   `dist/entry/process.js` or `dist/entry/worker.js` (Vitest 3 and earlier),
+ *   not the test file, so a worker counts by that entry point instead of the
+ *   test-file check. A child a test spawns
+ *   inherits the Vitest variables but has a different entry point, so it gets
+ *   no default. A test that points `HOME` at a fixture, in-process or for a child,
+ *   keeps it.
+ * - With {@link EnvVars.requireOverride} set, a root that would fall back to
+ *   the per-OS table throws a {@link TieredDirsError} naming the fix.
+ *
+ * The Rust twin's `BaseDirs::from_env` applies the same two rules, with two
+ * differences. It detects a test by its cargo test binary rather than by the
+ * environment. And the "`HOME` not moved" condition exists only here: a
+ * TypeScript test can point `HOME` at a fixture to redirect the home, which a
+ * Rust test cannot do through `dirs`, so the TypeScript rule yields to it.
+ * The cost is that a CI job whose `HOME` differs from the passwd home, such as
+ * a GitHub Actions container job (`HOME=/github/home`, passwd home `/root`),
+ * gets no test-root default. Set `<P>_ROOT` there.
+ *
+ * Stable in 0.x.
+ */
+export declare function systemBaseDirs(vars: EnvVars, opts?: ResolveOptions): BaseDirs;
+/**
+ * `<tmp>/tiered-dirs-test-<pid>-<start ms>` when this process is a test runner
+ * process, else `undefined`. Resolved once per module instance: once per test
+ * file under Vitest's default isolation, and once per installed copy of the
+ * package.
+ *
+ * A test runner process is the one {@link systemBaseDirs} describes: a test
+ * file as its entry point under `NODE_ENV=test`, `NODE_TEST_CONTEXT` or Bun,
+ * or a Vitest worker. A child a test spawns is not one.
+ *
+ * The start time keeps a later process that reuses the pid off this one's
+ * leftover state. Callers that read the environment themselves, such as a
+ * product-tier layer, use this to apply the same default. The Rust twin's
+ * `test_root()` is the same per-process root, detected by its cargo test
+ * binary.
+ *
+ * Stable in 0.x.
+ */
+export declare function testRoot(): string | undefined;
+/** Whether this process is a test runner running a test file (see {@link systemBaseDirs}). */
+export declare function isTestRunnerProcess(env: Record<string, string | undefined>, entry?: string): boolean;
+/**
+ * The XDG layout under `home`, with the `XDG_*` variables read from `env`: the
+ * `xdg` table, on any host. Each home is its `XDG_*` variable when that holds
+ * an absolute path, else its default under `home`. Logs share the state home.
+ * Scratch is `$TMPDIR`, else `/tmp`.
+ *
+ * The Rust twin's `BaseDirs::xdg` builds the same layout, held to it by the
+ * parity fixture's `convention_cases`.
+ *
+ * Stable in 0.x.
+ */
+export declare function xdgBaseDirs(home: string, env: Record<string, string | undefined>): BaseDirs;