The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { createHash } from "node:crypto"; |
| 2 | import { |
| 3 | existsSync, |
| 4 | mkdirSync, |
| 5 | promises as fs, |
| 6 | readFileSync, |
| 7 | renameSync, |
| 8 | unlinkSync, |
| 9 | writeFileSync, |
| 10 | } from "node:fs"; |
| 11 | import os from "node:os"; |
| 12 | import path from "node:path"; |
| 13 | import rolldown from "rolldown/package.json" with { type: "json" }; |
| 14 | import self from "../../package.json" with { type: "json" }; |
| 15 | |
| 16 | /** |
| 17 | * Anything that changes Oxc's output for identical input invalidates every |
| 18 | * entry: the transformer itself (rolldown), this package's transform |
| 19 | * pipeline, and the on-disk entry layout. |
| 20 | */ |
| 21 | const CACHE_VERSION = ["1", self.version, rolldown.version].join("-"); |
| 22 | |
| 23 | /** Entries untouched for this long are swept on the first disk access. */ |
| 24 | const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; |
| 25 | |
| 26 | /** |
| 27 | * How often the sweep runs. Every process on the machine opens the cache, |
| 28 | * and a sweep stats every entry — thousands of files — so a marker file's |
| 29 | * mtime limits it to once per interval. |
| 30 | */ |
| 31 | const SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000; |
| 32 | const SWEEP_MARKER = ".swept"; |
| 33 | |
| 34 | export const TRANSFORM_CACHE_ENV = "ALCHEMY_TRANSFORM_CACHE"; |
| 35 | |
| 36 | /** |
| 37 | * Per-user directory, like tsx's `tsx-<uid>`: `tmpdir()` is shared on |
| 38 | * multi-user machines, and entries are written with the owner's umask. |
| 39 | */ |
| 40 | const defaultDirectory = () => { |
| 41 | const user = process.geteuid?.() ?? os.userInfo().username; |
| 42 | return path.join(os.tmpdir(), `alchemy-oxc-${user}`); |
| 43 | }; |
| 44 | |
| 45 | /** |
| 46 | * The directory to use for the given option, or `undefined` when caching is |
| 47 | * off. `cache: false` and `ALCHEMY_TRANSFORM_CACHE=0` disable it; a string |
| 48 | * (option or env) names the directory; otherwise the per-user default. |
| 49 | */ |
| 50 | export const resolveCacheDirectory = (option: boolean | string | undefined): string | undefined => { |
| 51 | if (option === false) return undefined; |
| 52 | if (typeof option === "string") return option; |
| 53 | const env = process.env[TRANSFORM_CACHE_ENV]; |
| 54 | if (env === "0" || env === "false") return undefined; |
| 55 | if (env !== undefined && env !== "") return env; |
| 56 | return defaultDirectory(); |
| 57 | }; |
| 58 | |
| 59 | /** One transform's output as handed to {@link TransformCache.set}. */ |
| 60 | export interface TransformCacheEntry { |
| 61 | readonly format: "module" | "commonjs"; |
| 62 | readonly code: string; |
| 63 | /** Source map JSON, or `undefined` when the transform produced none. */ |
| 64 | readonly map: string | undefined; |
| 65 | } |
| 66 | |
| 67 | /** A cache hit: the code, and where its source map lives on disk. */ |
| 68 | export interface CachedTransform { |
| 69 | readonly format: "module" | "commonjs"; |
| 70 | readonly code: string; |
| 71 | /** Absolute path of the entry's `.map` file, present when it has one. */ |
| 72 | readonly mapFile: string | undefined; |
| 73 | } |
| 74 | |
| 75 | /** |
| 76 | * On-disk cache of Oxc transform output shared by every process on the |
| 77 | * machine — the `alchemy` CLI, its dev exec child, the local-provider |
| 78 | * sidecars and dev-server runners all load the same source files, and |
| 79 | * without this each of them transpiles the whole graph again. |
| 80 | * |
| 81 | * Modelled on tsx's file cache: entries are keyed by a hash of the source |
| 82 | * file's path, size and mtime, the transform options and the resolved |
| 83 | * tsconfig, so a change to any input is simply a different key; nothing is |
| 84 | * ever invalidated in place. Size plus nanosecond mtime stands in for the |
| 85 | * contents so a hit never reads the source. |
| 86 | * |
| 87 | * An entry is two files: `<key>.code` with the code behind a short header, |
| 88 | * and `<key>.map` with the source map. The map stays on disk and is referenced from the module |
| 89 | * by path rather than inlined — an inline `data:` map is part of the |
| 90 | * script's source text, which V8 keeps for the process lifetime; for a |
| 91 | * graph the size of alchemy's that is hundreds of megabytes per process. |
| 92 | * Node reads the referenced file synchronously as it compiles the module, |
| 93 | * so the map is written (atomically) before `set` returns; the code entry |
| 94 | * is a fire-and-forget write, because a missing one is only a slower |
| 95 | * cache. Reads are synchronous (the loader hook is). Stale entries are |
| 96 | * swept by age at most once a day. |
| 97 | */ |
| 98 | export class TransformCache { |
| 99 | readonly #directory: string; |
| 100 | #ready = false; |
| 101 | #sequence = 0; |
| 102 | |
| 103 | constructor(directory: string) { |
| 104 | this.#directory = directory; |
| 105 | } |
| 106 | |
| 107 | /** The entry key for these transform inputs. */ |
| 108 | key(parts: ReadonlyArray<string>): string { |
| 109 | const hash = createHash("sha1"); |
| 110 | hash.update(CACHE_VERSION); |
| 111 | for (const part of parts) { |
| 112 | // Length-prefixed so adjacent parts cannot run into each other. |
| 113 | hash.update(`\0${part.length}\0`); |
| 114 | hash.update(part); |
| 115 | } |
| 116 | return hash.digest("hex"); |
| 117 | } |
| 118 | |
| 119 | /** |
| 120 | * The cached transform, or `undefined` on a miss. An entry whose map file |
| 121 | * has gone (swept, or never landed) is a miss too: the module would |
| 122 | * otherwise reference a map that is not there. |
| 123 | */ |
| 124 | get(key: string): CachedTransform | undefined { |
| 125 | this.#prepare(); |
| 126 | let raw: string; |
| 127 | try { |
| 128 | raw = readFileSync(this.#file(key, "code"), "utf8"); |
| 129 | } catch { |
| 130 | return undefined; |
| 131 | } |
| 132 | // `<format><map>\n<code>`: the code is stored as is, so a hit is one |
| 133 | // read and a slice rather than a JSON parse of the whole module. |
| 134 | const format = raw[0] === "m" ? "module" : raw[0] === "c" ? "commonjs" : undefined; |
| 135 | if (format === undefined || raw[2] !== "\n" || (raw[1] !== "1" && raw[1] !== "0")) { |
| 136 | return undefined; |
| 137 | } |
| 138 | const mapFile = raw[1] === "1" ? this.#file(key, "map") : undefined; |
| 139 | if (mapFile !== undefined && !existsSync(mapFile)) return undefined; |
| 140 | return { format, code: raw.slice(3), mapFile }; |
| 141 | } |
| 142 | |
| 143 | /** |
| 144 | * Stores one transform. Returns the map file's path once it is on disk, |
| 145 | * or `undefined` when there is no map or it could not be written — the |
| 146 | * caller then falls back to inlining it. |
| 147 | */ |
| 148 | set(key: string, entry: TransformCacheEntry): string | undefined { |
| 149 | this.#prepare(); |
| 150 | let mapFile: string | undefined; |
| 151 | if (entry.map !== undefined) { |
| 152 | mapFile = this.#file(key, "map"); |
| 153 | if (!this.#writeAtomically(mapFile, entry.map)) return undefined; |
| 154 | } |
| 155 | const file = this.#file(key, "code"); |
| 156 | const temporary = this.#temporary(file); |
| 157 | const header = `${entry.format === "module" ? "m" : "c"}${mapFile === undefined ? "0" : "1"}\n`; |
| 158 | // Best effort: a cache that cannot be written is only a slower cache. |
| 159 | fs.writeFile(temporary, header + entry.code) |
| 160 | .then(() => fs.rename(temporary, file)) |
| 161 | .catch(() => fs.unlink(temporary).catch(() => {})); |
| 162 | return mapFile; |
| 163 | } |
| 164 | |
| 165 | #file(key: string, extension: "code" | "map") { |
| 166 | return path.join(this.#directory, `${key}.${extension}`); |
| 167 | } |
| 168 | |
| 169 | #temporary(file: string) { |
| 170 | return `${file}.${process.pid}.${this.#sequence++}.tmp`; |
| 171 | } |
| 172 | |
| 173 | /** Temp file plus rename: concurrent readers never see a partial file. */ |
| 174 | #writeAtomically(file: string, content: string): boolean { |
| 175 | const temporary = this.#temporary(file); |
| 176 | try { |
| 177 | writeFileSync(temporary, content); |
| 178 | renameSync(temporary, file); |
| 179 | return true; |
| 180 | } catch { |
| 181 | try { |
| 182 | unlinkSync(temporary); |
| 183 | } catch {} |
| 184 | return false; |
| 185 | } |
| 186 | } |
| 187 | |
| 188 | #prepare() { |
| 189 | if (this.#ready) return; |
| 190 | this.#ready = true; |
| 191 | try { |
| 192 | mkdirSync(this.#directory, { recursive: true }); |
| 193 | } catch { |
| 194 | return; |
| 195 | } |
| 196 | // Off the hot path: the loader hook that got us here is synchronous. |
| 197 | setImmediate(() => { |
| 198 | this.#sweep().catch(() => {}); |
| 199 | }); |
| 200 | } |
| 201 | |
| 202 | async #sweep() { |
| 203 | const marker = path.join(this.#directory, SWEEP_MARKER); |
| 204 | const swept = await fs.stat(marker).then( |
| 205 | ({ mtimeMs }) => mtimeMs, |
| 206 | () => 0, |
| 207 | ); |
| 208 | if (Date.now() - swept < SWEEP_INTERVAL_MS) return; |
| 209 | await fs.writeFile(marker, ""); |
| 210 | const cutoff = Date.now() - MAX_AGE_MS; |
| 211 | const names = await fs.readdir(this.#directory); |
| 212 | await Promise.all( |
| 213 | names.map(async (name) => { |
| 214 | if (name === SWEEP_MARKER) return; |
| 215 | const file = path.join(this.#directory, name); |
| 216 | try { |
| 217 | const { mtimeMs } = await fs.stat(file); |
| 218 | if (mtimeMs < cutoff) await fs.unlink(file); |
| 219 | } catch {} |
| 220 | }), |
| 221 | ); |
| 222 | } |
| 223 | } |