vitecache 0.2.1 → 0.4.0

package/dist/vite.js

@@ -0,0 +1,253 @@
+import { appendFile, readdir, rm } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import colors from 'picocolors';
+import picomatch from 'picomatch';
+import { glob } from 'tinyglobby';
+import { createServer, normalizePath } from 'vite';
+import { missing, read } from './disk.js';
+import { discover } from './discover.js';
+import { shared } from './shared.js';
+/** Adds the cache directory to the project's .gitignore, since its entries are generated. */
+async function ignore(root, directory) {
+    const line = `${relative(root, directory).split('\\').join('/')}/*`;
+    const file = join(root, '.gitignore');
+    const contents = new TextDecoder().decode(await read(file));
+    if (contents.split(/\r?\n/).includes(line))
+        return;
+    await appendFile(file, `${contents && !contents.endsWith('\n') ? '\n' : ''}${line}\n`);
+}
+function stack(error) {
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+/** Source files discovery scans, as Tailwind scans for class names, outside dependencies and outputs. */
+const sources = '**/*.{js,jsx,ts,tsx,mjs,mts}';
+/**
+ * Finds cached loader loads in the project's source files and warms them in Node, so that browsers read what Node
+ * saved, then deletes the entries no load uses. In development it scans and warms at startup and again after every
+ * file change, holds cache requests until warming finishes, and deletes entries unused for `pruneAfter`. A build scans
+ * and warms once, checks that a second pass saves nothing, and deletes every entry it did not use.
+ */
+export function vitecache({ pruneAfter = 60_000 } = {}) {
+    // The server a build runs loaders with loads the config, and so this plugin, again.
+    if (shared.running)
+        return { name: 'vitecache' };
+    /** The loads each source file holds. */
+    const files = new Map();
+    let config;
+    let directory;
+    /** Runs loaders: the dev server itself, or in a build a server started for that. */
+    let server;
+    let queue = Promise.resolve();
+    /** Whether a pass is queued but has not started, which the next change then need not queue again. */
+    let queued = false;
+    /** When the latest pass started. Once the queue is idle, every load has used its entry since then. */
+    let started = 0;
+    let failed = false;
+    /** Set once the dev server closes, after which a running pass stops and nothing is pruned. */
+    let closing = false;
+    let timer;
+    /** Project-relative patterns of what is not scanned: dependencies, the build output, and public files. */
+    let excluded;
+    let isSource;
+    /** Records a file's loads. Development logs failures, since a file being edited can fail to parse. */
+    async function scan(file) {
+        try {
+            const code = new TextDecoder().decode(await read(file));
+            if (/Cached\w*Loader/.test(code))
+                files.set(file, discover(code, file));
+            else
+                files.delete(file);
+        }
+        catch (error) {
+            if (config.command === 'build')
+                throw error;
+            log(`${colors.red('cannot scan')} ${error instanceof Error ? error.message : String(error)}`, 'error');
+        }
+    }
+    async function run({ importer, source, name, args }) {
+        if (!server) {
+            shared.running = true;
+            try {
+                server = await createServer({
+                    configFile: config.configFile ?? false,
+                    root: config.root,
+                    mode: config.mode,
+                    logLevel: 'warn',
+                    server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+                });
+            }
+            finally {
+                shared.running = false;
+            }
+        }
+        const resolved = await server.environments.ssr.pluginContainer.resolveId(source, importer);
+        if (!resolved)
+            throw new Error(`vitecache cannot resolve ${source} from ${importer}`);
+        const module = await server.ssrLoadModule(resolved.id);
+        const exported = module[name];
+        if (typeof exported !== 'function')
+            throw new Error(`${source} does not export a class ${name}`);
+        const instance = Reflect.construct(exported, []);
+        const loadable = typeof instance === 'object' && instance !== null && 'loadAsync' in instance;
+        if (!loadable || typeof instance.loadAsync !== 'function')
+            throw new Error(`${name} has no loadAsync method`);
+        await instance.loadAsync(...args);
+    }
+    /** Runs every load once, one at a time, logging progress and failures. */
+    /** Logs as Vite does with a timestamp, but tagged [vitecache], since Vite's own timestamp option tags lines [vite]. */
+    function log(message, level = 'info') {
+        const tag = colors.bold(level === 'info' ? colors.cyan('[vitecache]') : colors.red('[vitecache]'));
+        config.logger[level](`${colors.dim(new Date().toLocaleTimeString())} ${tag} ${message}`);
+    }
+    /** Runs every load once, one at a time. Hits are silent; a load that computes is logged, and announced when slow. */
+    async function pass() {
+        queued = false;
+        started = Date.now();
+        for (const load of [...files.values()].flat()) {
+            if (closing)
+                return;
+            const file = normalizePath(relative(config.root, load.importer));
+            const where = `${load.name} ${colors.dim(`${file}:${load.position}`)}`;
+            const start = Date.now();
+            const saves = shared.saves;
+            const slow = setTimeout(() => log(`${colors.yellow('computing')} ${where}…`), 500);
+            try {
+                await run(load);
+            }
+            catch (error) {
+                failed = true;
+                log(`${colors.red('failed')} ${where}\n${stack(error)}`, 'error');
+                continue;
+            }
+            finally {
+                clearTimeout(slow);
+            }
+            const computed = shared.saves - saves;
+            if (!computed)
+                continue;
+            const time = Date.now() - start;
+            const took = time < 1000 ? `${time} ms` : `${(time / 1000).toFixed(1)} s`;
+            const entries = computed > 1 ? `, ${computed} entries` : '';
+            log(`${colors.green('computed')} ${where} ${colors.dim(`in ${took}${entries}`)}`);
+        }
+    }
+    /** Queues a pass unless one is already waiting. */
+    function warm() {
+        if (!queued) {
+            queued = true;
+            queue = queue.then(pass);
+        }
+        return idle();
+    }
+    async function idle() {
+        let current;
+        do {
+            current = queue;
+            await current;
+        } while (current !== queue);
+    }
+    /** Deletes the entries no load used since `before`. */
+    async function prune(before) {
+        const names = await readdir(directory).catch((error) => {
+            if (missing(error))
+                return [];
+            throw error;
+        });
+        for (const name of names) {
+            const key = /^([a-f0-9]{64})\.(?:bin|json)$/.exec(name)?.[1];
+            if (key && (shared.used.get(key) ?? 0) < before)
+                await rm(join(directory, name), { force: true });
+        }
+    }
+    /** Prunes in development, once idle: entries the latest pass used stay, others until `pruneAfter` past their use. */
+    async function expire() {
+        await idle();
+        if (closing)
+            return;
+        await prune(Math.min(started, Date.now() - pruneAfter));
+    }
+    async function scanAll() {
+        for (const file of await glob(sources, { cwd: config.root, absolute: true, ignore: excluded }))
+            await scan(file);
+    }
+    return {
+        name: 'vitecache',
+        async configResolved(resolved) {
+            config = resolved;
+            if (!config.publicDir)
+                throw new Error('vitecache requires Vite publicDir');
+            // Normalized, as are the files hotUpdate is given.
+            directory = normalizePath(join(config.publicDir, '_vitecache'));
+            shared.root = config.root;
+            shared.directory = directory;
+            const outputs = [config.build.outDir, config.publicDir].map((path) => relative(config.root, resolve(config.root, path)));
+            // An output at the root itself excludes nothing, since the root holds the sources.
+            excluded = ['**/node_modules/**', ...outputs.filter(Boolean).map((path) => `${normalizePath(path)}/**`)];
+            isSource = picomatch(sources, { ignore: excluded });
+            await ignore(config.root, directory);
+        },
+        async buildStart() {
+            if (config.command !== 'build' || this.environment.name !== 'client')
+                return;
+            const start = Date.now();
+            failed = false;
+            try {
+                await scanAll();
+                await warm();
+                if (failed)
+                    throw new Error('vitecache: warming failed, see the errors above.');
+                const saves = shared.saves;
+                await warm();
+                if (failed)
+                    throw new Error('vitecache: warming failed, see the errors above.');
+                if (shared.saves !== saves)
+                    throw new Error('vitecache: a second warming saved entries again, so their keys are not stable.');
+            }
+            finally {
+                await server?.close();
+                server = undefined;
+            }
+            await prune(start);
+        },
+        configureServer(devServer) {
+            server = devServer;
+            const prefix = `${config.base}_vitecache/`;
+            // Serves entries itself, after warming: Vite's public file serving learns of new files only through its watcher.
+            devServer.middlewares.use((request, response, next) => {
+                if (!request.url?.startsWith(prefix))
+                    return next();
+                const name = new URL(request.url, 'http://vitecache').pathname.slice(prefix.length);
+                if (!/^[a-f0-9]{64}\.bin$/.test(name))
+                    return next();
+                void idle()
+                    .then(() => read(join(directory, name)))
+                    .then((bytes) => {
+                    if (!bytes)
+                        return next();
+                    response.setHeader('Content-Type', 'application/octet-stream');
+                    response.setHeader('Cache-Control', 'no-cache');
+                    response.end(bytes);
+                }, next);
+            });
+            const report = (error) => log(stack(error), 'error');
+            // Queued, so that requests wait for the scan too.
+            queue = queue.then(scanAll).catch(report);
+            void warm().then(expire).catch(report);
+            timer = setInterval(() => void expire().catch(report), pruneAfter);
+        },
+        async hotUpdate({ file }) {
+            if (this.environment.name !== 'client' || file.startsWith(directory))
+                return;
+            if (isSource(normalizePath(relative(config.root, file))))
+                await scan(file);
+            // Any file can be an input, and an unchanged entry warms with one load. Saves are file changes too.
+            void warm();
+        },
+        async closeBundle() {
+            closing = true;
+            clearInterval(timer);
+            await idle();
+        },
+    };
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFile, readdir, rm } from 'node:fs/promises';\nimport { join, relative, resolve } from 'node:path';\nimport colors from 'picocolors';\nimport picomatch from 'picomatch';\nimport { glob } from 'tinyglobby';\nimport { createServer, normalizePath, type Plugin, type ResolvedConfig, type ViteDevServer } from 'vite';\nimport { missing, read } from './disk.js';\nimport { discover, type Load } from './discover.js';\nimport { shared } from './shared.js';\n\n/** Adds the cache directory to the project's .gitignore, since its entries are generated. */\nasync function ignore(root: string, directory: string): Promise<void> {\n  const line = `${relative(root, directory).split('\\\\').join('/')}/*`;\n  const file = join(root, '.gitignore');\n  const contents = new TextDecoder().decode(await read(file));\n  if (contents.split(/\\r?\\n/).includes(line)) return;\n  await appendFile(file, `${contents && !contents.endsWith('\\n') ? '\\n' : ''}${line}\\n`);\n}\n\nfunction stack(error: unknown): string {\n  return error instanceof Error ? (error.stack ?? error.message) : String(error);\n}\n\n/** Source files discovery scans, as Tailwind scans for class names, outside dependencies and outputs. */\nconst sources = '**/*.{js,jsx,ts,tsx,mjs,mts}';\n\nexport interface VitecacheOptions {\n  /** Development: milliseconds an entry stays after the last load that used it, so that an undone edit reuses it. */\n  pruneAfter?: number;\n}\n\n/**\n * Finds cached loader loads in the project's source files and warms them in Node, so that browsers read what Node\n * saved, then deletes the entries no load uses. In development it scans and warms at startup and again after every\n * file change, holds cache requests until warming finishes, and deletes entries unused for `pruneAfter`. A build scans\n * and warms once, checks that a second pass saves nothing, and deletes every entry it did not use.\n */\nexport function vitecache({ pruneAfter = 60_000 }: VitecacheOptions = {}): Plugin {\n  // The server a build runs loaders with loads the config, and so this plugin, again.\n  if (shared.running) return { name: 'vitecache' };\n  /** The loads each source file holds. */\n  const files = new Map<string, Load[]>();\n  let config: ResolvedConfig;\n  let directory: string;\n  /** Runs loaders: the dev server itself, or in a build a server started for that. */\n  let server: ViteDevServer | undefined;\n  let queue = Promise.resolve();\n  /** Whether a pass is queued but has not started, which the next change then need not queue again. */\n  let queued = false;\n  /** When the latest pass started. Once the queue is idle, every load has used its entry since then. */\n  let started = 0;\n  let failed = false;\n  /** Set once the dev server closes, after which a running pass stops and nothing is pruned. */\n  let closing = false;\n  let timer: NodeJS.Timeout | undefined;\n\n  /** Project-relative patterns of what is not scanned: dependencies, the build output, and public files. */\n  let excluded: string[];\n  let isSource: (file: string) => boolean;\n\n  /** Records a file's loads. Development logs failures, since a file being edited can fail to parse. */\n  async function scan(file: string): Promise<void> {\n    try {\n      const code = new TextDecoder().decode(await read(file));\n      if (/Cached\\w*Loader/.test(code)) files.set(file, discover(code, file));\n      else files.delete(file);\n    } catch (error) {\n      if (config.command === 'build') throw error;\n      log(`${colors.red('cannot scan')} ${error instanceof Error ? error.message : String(error)}`, 'error');\n    }\n  }\n\n  async function run({ importer, source, name, args }: Load): Promise<void> {\n    if (!server) {\n      shared.running = true;\n      try {\n        server = await createServer({\n          configFile: config.configFile ?? false,\n          root: config.root,\n          mode: config.mode,\n          logLevel: 'warn',\n          server: { middlewareMode: true, hmr: false, ws: false, watch: null },\n        });\n      } finally {\n        shared.running = false;\n      }\n    }\n    const resolved = await server.environments.ssr.pluginContainer.resolveId(source, importer);\n    if (!resolved) throw new Error(`vitecache cannot resolve ${source} from ${importer}`);\n    const module: Record<string, unknown> = await server.ssrLoadModule(resolved.id);\n    const exported = module[name];\n    if (typeof exported !== 'function') throw new Error(`${source} does not export a class ${name}`);\n    const instance: unknown = Reflect.construct(exported, []);\n    const loadable = typeof instance === 'object' && instance !== null && 'loadAsync' in instance;\n    if (!loadable || typeof instance.loadAsync !== 'function') throw new Error(`${name} has no loadAsync method`);\n    await instance.loadAsync(...args);\n  }\n\n  /** Runs every load once, one at a time, logging progress and failures. */\n  /** Logs as Vite does with a timestamp, but tagged [vitecache], since Vite's own timestamp option tags lines [vite]. */\n  function log(message: string, level: 'info' | 'error' = 'info'): void {\n    const tag = colors.bold(level === 'info' ? colors.cyan('[vitecache]') : colors.red('[vitecache]'));\n    config.logger[level](`${colors.dim(new Date().toLocaleTimeString())} ${tag} ${message}`);\n  }\n\n  /** Runs every load once, one at a time. Hits are silent; a load that computes is logged, and announced when slow. */\n  async function pass(): Promise<void> {\n    queued = false;\n    started = Date.now();\n    for (const load of [...files.values()].flat()) {\n      if (closing) return;\n      const file = normalizePath(relative(config.root, load.importer));\n      const where = `${load.name} ${colors.dim(`${file}:${load.position}`)}`;\n      const start = Date.now();\n      const saves = shared.saves;\n      const slow = setTimeout(() => log(`${colors.yellow('computing')} ${where}…`), 500);\n      try {\n        await run(load);\n      } catch (error) {\n        failed = true;\n        log(`${colors.red('failed')} ${where}\\n${stack(error)}`, 'error');\n        continue;\n      } finally {\n        clearTimeout(slow);\n      }\n      const computed = shared.saves - saves;\n      if (!computed) continue;\n      const time = Date.now() - start;\n      const took = time < 1000 ? `${time} ms` : `${(time / 1000).toFixed(1)} s`;\n      const entries = computed > 1 ? `, ${computed} entries` : '';\n      log(`${colors.green('computed')} ${where} ${colors.dim(`in ${took}${entries}`)}`);\n    }\n  }\n\n  /** Queues a pass unless one is already waiting. */\n  function warm(): Promise<void> {\n    if (!queued) {\n      queued = true;\n      queue = queue.then(pass);\n    }\n    return idle();\n  }\n\n  async function idle(): Promise<void> {\n    let current: Promise<void>;\n    do {\n      current = queue;\n      await current;\n    } while (current !== queue);\n  }\n\n  /** Deletes the entries no load used since `before`. */\n  async function prune(before: number): Promise<void> {\n    const names = await readdir(directory).catch((error: unknown) => {\n      if (missing(error)) return [];\n      throw error;\n    });\n    for (const name of names) {\n      const key = /^([a-f0-9]{64})\\.(?:bin|json)$/.exec(name)?.[1];\n      if (key && (shared.used.get(key) ?? 0) < before) await rm(join(directory, name), { force: true });\n    }\n  }\n\n  /** Prunes in development, once idle: entries the latest pass used stay, others until `pruneAfter` past their use. */\n  async function expire(): Promise<void> {\n    await idle();\n    if (closing) return;\n    await prune(Math.min(started, Date.now() - pruneAfter));\n  }\n\n  async function scanAll(): Promise<void> {\n    for (const file of await glob(sources, { cwd: config.root, absolute: true, ignore: excluded })) await scan(file);\n  }\n\n  return {\n    name: 'vitecache',\n    async configResolved(resolved) {\n      config = resolved;\n      if (!config.publicDir) throw new Error('vitecache requires Vite publicDir');\n      // Normalized, as are the files hotUpdate is given.\n      directory = normalizePath(join(config.publicDir, '_vitecache'));\n      shared.root = config.root;\n      shared.directory = directory;\n      const outputs = [config.build.outDir, config.publicDir].map((path) =>\n        relative(config.root, resolve(config.root, path)),\n      );\n      // An output at the root itself excludes nothing, since the root holds the sources.\n      excluded = ['**/node_modules/**', ...outputs.filter(Boolean).map((path) => `${normalizePath(path)}/**`)];\n      isSource = picomatch(sources, { ignore: excluded });\n      await ignore(config.root, directory);\n    },\n    async buildStart() {\n      if (config.command !== 'build' || this.environment.name !== 'client') return;\n      const start = Date.now();\n      failed = false;\n      try {\n        await scanAll();\n        await warm();\n        if (failed) throw new Error('vitecache: warming failed, see the errors above.');\n        const saves = shared.saves;\n        await warm();\n        if (failed) throw new Error('vitecache: warming failed, see the errors above.');\n        if (shared.saves !== saves)\n          throw new Error('vitecache: a second warming saved entries again, so their keys are not stable.');\n      } finally {\n        await server?.close();\n        server = undefined;\n      }\n      await prune(start);\n    },\n    configureServer(devServer) {\n      server = devServer;\n      const prefix = `${config.base}_vitecache/`;\n      // Serves entries itself, after warming: Vite's public file serving learns of new files only through its watcher.\n      devServer.middlewares.use((request, response, next) => {\n        if (!request.url?.startsWith(prefix)) return next();\n        const name = new URL(request.url, 'http://vitecache').pathname.slice(prefix.length);\n        if (!/^[a-f0-9]{64}\\.bin$/.test(name)) return next();\n        void idle()\n          .then(() => read(join(directory, name)))\n          .then((bytes) => {\n            if (!bytes) return next();\n            response.setHeader('Content-Type', 'application/octet-stream');\n            response.setHeader('Cache-Control', 'no-cache');\n            response.end(bytes);\n          }, next);\n      });\n      const report = (error: unknown) => log(stack(error), 'error');\n      // Queued, so that requests wait for the scan too.\n      queue = queue.then(scanAll).catch(report);\n      void warm().then(expire).catch(report);\n      timer = setInterval(() => void expire().catch(report), pruneAfter);\n    },\n    async hotUpdate({ file }) {\n      if (this.environment.name !== 'client' || file.startsWith(directory)) return;\n      if (isSource(normalizePath(relative(config.root, file)))) await scan(file);\n      // Any file can be an input, and an unchanged entry warms with one load. Saves are file changes too.\n      void warm();\n    },\n    async closeBundle() {\n      closing = true;\n      clearInterval(timer);\n      await idle();\n    },\n  };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vitecache",
-  "version": "0.2.1",
-  "description": "Persistent binary caching for expensive computation in browsers and Node.",
+  "version": "0.4.0",
+  "description": "Persistent binary caching for expensive computation, warmed in Node by a Vite plugin and read in browsers and Node.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -22,18 +22,18 @@
     "typescript"
   ],
   "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/browser.js",
+  "types": "./dist/browser.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/browser.d.ts",
       "browser": "./dist/browser.js",
       "node": "./dist/node.js",
       "default": "./dist/browser.js"
     },
     "./vite": {
-      "types": "./dist/vite/index.d.ts",
-      "default": "./dist/vite/index.js"
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
     }
   },
   "files": [
@@ -52,10 +52,16 @@
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit"
   },
   "dependencies": {
-    "@noble/hashes": "^2.0.1"
+    "@noble/hashes": "^2.0.1",
+    "json5": "2.2.3",
+    "picocolors": "1.1.1",
+    "picomatch": "4.0.3",
+    "safe-stable-stringify": "2.5.0",
+    "tinyglobby": "0.2.15",
+    "write-file-atomic": "6.0.0"
   },
   "peerDependencies": {
-    "vite": ">=6.0.0"
+    "vite": ">=8.0.0"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -63,6 +69,8 @@
     }
   },
   "devDependencies": {
+    "@types/picomatch": "4.0.2",
+    "@types/write-file-atomic": "4.0.3",
     "vite": "^8.0.0",
     "vitest": "^4.0.17"
   },

package/skills/vitecache/SKILL.md

@@ -1,54 +1,49 @@
 ---
 name: vitecache
-description: Cache expensive computation with vitecache in browsers or Node, connect browser saves to a Vite development server, and reuse cached bytes in deployed apps.
+description: Cache expensive computation with vitecache: wrap it in a cached loader that the Vite plugin finds and computes in Node during development and builds, so browsers and Node read the saved bytes instead of recomputing.
 ---
 
 # vitecache
 
-Use vitecache when recomputing a result costs more than reading its encoded bytes. The application owns encoding and decoding. Declare every input that affects the computation as a named dependency. Use `{ value }` for JSON data and `{ package: "elkjs" }` for an installed library. Package dependencies track the named package’s installed version, so declare transitive packages separately when their versions matter. Bump the computation version for changes beyond what the declared dependencies capture.
+Use vitecache when recomputing a result costs more than reading its encoded bytes. The application owns encoding and decoding.
 
-Give dependencies stable names. Use `{ path: "src/simplify.ts" }` for a project-root-relative path or `{ url: modelUrl }` when you have an asset URL served by the same project origin. Paths resolve from the Node `root` or the Vite project root, never from the importing module, page URL, or cache directory. The Vite plugin resolves served URLs to source paths; Node accepts local file URLs. Keep the plugin in the production build configuration when using served URLs so deployed entries can recover the same source paths. Production mappings cover public files and emitted assets with one backing source. Use `{ path }` when an imported asset is inlined or deduplicated from several source files.
+## Cached loaders
 
-Reordering JSON object properties or dependency declarations does not change identity; array order matters. Changing a dependency name, JSON value, resolved path, or package name does. File contents and installed package versions invalidate the existing result when filesystem validation is available; installation paths do not affect identity.
-
-Load once and compute on a miss. Reuse that entry when saving: loading captures file contents and package versions before computation, allowing saving to reject a result if those dependencies changed in the meantime. A new entry or a save without a preceding load cannot establish that relationship. Entries containing only value dependencies can save directly. If saving fails because dependencies changed, load again and recompute before retrying. A dependency without a backing file, such as a server route, a virtual module or a package the app does not install, makes `save()` throw `MissingDependencyError`; catch it to carry on with the uncached result. Use a separate entry for each concurrent computation.
+Put each computation in an exported class whose name matches `Cached…Loader`, with a `loadAsync` method, as a three.js `Loader` has; extending one works. The plugin constructs it without arguments, so let only `loadAsync`'s arguments select the result: constructor options, such as a `LoadingManager`, must not change the bytes it saves. `loadAsync` creates a `CacheEntry`, loads, computes on a miss, and saves with the same entry. Call `load()` on every call, without a memo in front of it: the plugin keeps entries that loads use, and an entry a memo answers for goes unused and is deleted. `save()` records the inputs as the preceding `load()` found them, so one that changes during the computation makes the next load miss instead of serving a stale result. Import the computation lazily inside the miss branch, so pages that hit never download its code.
 
 ```ts
 import { CacheEntry } from "vitecache"
-import modelUrl from "./models/chair.glb?url"
-
-const entry = new CacheEntry({
-  version: "simplify@2",
-  dependencies: {
-    settings: { value: { ratio: 0.5, preserveUVs: true } },
-    algorithm: { path: "src/simplify.ts" },
-    model: { url: modelUrl },
-  },
-})
-
-let bytes = await entry.load()
-
-if (bytes === undefined) {
-  bytes = encodeMesh(await simplify())
-  await entry.save(bytes)
-}
 
-const mesh = decodeMesh(bytes)
+export class CachedMeshLoader {
+  async loadAsync(settings: { ratio: number }): Promise<Mesh> {
+    const entry = new CacheEntry({
+      version: "simplify@2",
+      dependencies: {
+        settings: { value: settings },
+        algorithm: { path: "src/simplify.ts" },
+        engine: { package: "meshoptimizer" },
+      },
+    })
+    let bytes = await entry.load()
+    if (bytes === undefined) {
+      const { simplify } = await import("./simplify.ts")
+      bytes = encodeMesh(await simplify(settings))
+      await entry.save(bytes)
+    }
+    return decodeMesh(bytes)
+  }
+}
 ```
 
-Constructor dependencies select which result an entry holds. When some inputs are only discovered while computing, such as the files a script imported or the textures a model referenced, pass them to `save(bytes, { dependencies })` instead, like a compiler's depfile: paths, URLs and packages only, since anything that selects the result belongs in the constructor. Every later `load()` rechecks them and misses when one changed or disappeared, and the next save replaces the same entry. They are hashed when `save()` runs rather than when the computation read them, so an edit made during a long computation goes unnoticed until the file changes again.
+Declare every input that affects the result, under a stable name. A `{ value }` is JSON that selects which result the entry holds: changing it, a name, a path or a package name changes the key, while reordering object properties does not. File contents and package versions invalidate the entry without changing its key.
 
-```ts
-const entry = new CacheEntry({ version: "bake@1", dependencies: { scene: { url: sceneUrl } } })
-let bytes = await entry.load()
-if (bytes === undefined) {
-  const { result, files } = await bake(sceneUrl) // files: URLs the bake read
-  bytes = encode(result)
-  await entry.save(bytes, { dependencies: Object.fromEntries(files.map((url, i) => [`file:${i}`, { url }])) })
-}
-```
+A `{ path }` is relative to the project root, never to the importing module. A `{ package }` tracks only that package's installed version, so declare transitive packages separately when their versions matter. Bump `version` for changes the dependencies do not capture, such as a linked workspace package changed without a new version.
+
+When inputs are only discovered while computing, such as the textures a model references, pass them to `save()` as its `dependencies`, like a compiler's depfile. They are checked on every load without being part of the key.
+
+## Using loaders
 
-Use the Vite plugin when browser computation should produce reusable project files:
+Add the plugin:
 
 ```ts
 import { defineConfig } from "vite"
@@ -57,6 +52,20 @@ import { vitecache } from "vitecache/vite"
 export default defineConfig({ plugins: [vitecache()] })
 ```
 
-Generate caches during development or from Node before building when deployed users should download precomputed results. Include the generated public files in the build or deployment even when Git ignores them. The plugin writes files during development; it does not supply a production write server. Browsers without the plugin assume files and package versions unchanged, saved dependencies included, so regenerate affected caches before deployment. Calling `save()` there warns and skips persistence. The plugin answers a missing entry without an HTTP error, but a static host answers it with 404, which the browser console shows; each one marks a result the deployment lacks, so precompute what deployed users will request.
+A load is a `loadAsync` call with literal JSON arguments on `new CachedMeshLoader()`, or on a variable initialized with it, as in `new CachedMeshLoader().loadAsync({ ratio: 0.5 })` or `const meshes = new CachedMeshLoader()` and later `meshes.loadAsync({ ratio: 0.5 })`. Any other use fails the build, and in development is logged: passing a loader or such a variable around, exporting or reassigning it, calling another of its methods such as `setPath`, subclassing the loader, or loading with a variable. To serve several fixed variants, write one literal load per variant.
+
+The plugin finds loads by scanning the project's JavaScript and TypeScript files, as Tailwind scans for class names, and matches the loader's imported name through aliases and namespace imports. It skips `node_modules`, the build output and `publicDir`, so a library's loaders are warmed only where the app uses them. It does not read `.vue` or `.svelte` files, and it warms a load in a file the app never imports, such as a test. Since variables are matched by name in the module, give a loader variable a name no other variable in that module uses.
+
+The plugin repeats each load in Node by importing the loader's module through Vite's SSR loading. That module and its top-level imports must load without browser globals, and whatever the loader does after loading, such as decoding, runs in Node too. A build loads the Vite config file again to run the loaders, so configure plugins they rely on there rather than inline in a programmatic build.
+
+In development the plugin warms every load at startup and again after every file change, and the page's cache requests wait for it, so the browser normally hits. It deletes entries no load uses: at startup, those left from earlier sessions, and later, an entry replaced by an edit once it has gone unused for `pruneAfter`, a minute by default, so that undoing the edit within that time reuses it. A build warms every load, then repeats them all and fails if that second pass saves anything, which means a key that changes between runs, such as one built from a timestamp. It then deletes every entry the build did not use, so the deployment holds exactly what the app requests.
+
+Development and builds log each load that computes, by loader and source location, and announce a load still running after half a second; loads that hit are silent.
+
+## Browsers and deployment
+
+Browsers only read entries. A browser that misses, for a load the plugin could not see, computes the result itself each time, and `save()` warns once per version instead of writing. A deployed app serves entries without checking their inputs, so build again after changing them.
+
+Entries keep their file names when their contents change, so browsers revalidate them before each use. Serve the cache directory with `ETag` or `Last-Modified`, as most static hosts do, and do not mark it immutable. When deploying below a URL prefix, pass that prefix with the cache path as `basePath`, such as `/app/_vitecache/`; the entry does not infer Vite's base.
 
-For custom locations, coordinate the filesystem destination with the URL used by browser callers. A filesystem path and a browser URL are different values. When deploying below a URL prefix, include that prefix in the browser cache path; the client does not infer Vite's base URL. Node jobs should select the same project root as the Vite app when launched from a different working directory.
+The plugin adds the cache directory, `public/_vitecache/`, to `.gitignore`. A Node script outside Vite can use the same loaders. Its entries use `public/_vitecache/` below the working directory, or below `root` when passed.

package/dist/dependencies.d.ts

@@ -1,15 +0,0 @@
-import type { Dependencies, Hashes, JsonValue, Paths, ResolvedDependencies, SavedDependencies } from './types.js';
-/** A file or package dependency has no backing file or installation, so its state cannot be checked. */
-export declare class MissingDependencyError extends Error {
-    name: string;
-}
-export declare function record(value: unknown): Record<string, unknown>;
-export declare function paths(value: unknown): Paths;
-/** Validate and snapshot JSON before asynchronous dependency resolution starts. */
-export declare function json(value: unknown, ancestors?: Set<object>): JsonValue;
-export declare function dependencies(value: unknown): Dependencies;
-export declare function resolvedDependencies(value: unknown): ResolvedDependencies;
-/** Saved dependencies are rechecked later, so they cannot be values: values select the result and belong to the key. */
-export declare function savedDependencies(value: unknown): SavedDependencies;
-export declare function hashes(value: unknown): Hashes;
-export declare function equalHashes(first: Hashes, second: Hashes): boolean;

package/dist/dependencies.js

@@ -1,131 +0,0 @@
-/** A file or package dependency has no backing file or installation, so its state cannot be checked. */
-export class MissingDependencyError extends Error {
-    name = 'MissingDependencyError';
-}
-export function record(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new TypeError('Expected a named dependency record.');
-    }
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null)
-        throw new TypeError('Expected a plain dependency record.');
-    if (Object.getOwnPropertySymbols(value).length)
-        throw new TypeError('Dependency names must be strings.');
-    return Object.fromEntries(Object.keys(value).sort().map((name) => {
-        const property = Object.getOwnPropertyDescriptor(value, name);
-        if (!property || !('value' in property))
-            throw new TypeError('Dependency getters are not supported.');
-        const item = property.value;
-        return [name, item];
-    }));
-}
-function path(value) {
-    if (typeof value !== 'string' || !value || value.includes('\0'))
-        throw new TypeError('File dependencies require nonempty paths.');
-    if (/^(?:[\\/]|[a-z]:|[a-z][a-z\d+.-]*:\/\/)/i.test(value)) {
-        throw new TypeError('File dependency paths must be relative to the project root.');
-    }
-    const parts = [];
-    for (const part of value.replace(/\\/g, '/').split('/')) {
-        if (!part || part === '.')
-            continue;
-        if (part !== '..') {
-            parts.push(part);
-            continue;
-        }
-        if (!parts.length)
-            throw new TypeError('File dependency paths must stay inside the project root.');
-        parts.pop();
-    }
-    if (!parts.length)
-        throw new TypeError('File dependencies must identify files, not the project root.');
-    return parts.join('/');
-}
-export function paths(value) {
-    return Object.freeze(Object.fromEntries(Object.entries(record(value)).map(([name, value]) => {
-        if (!name)
-            throw new TypeError('File dependencies require nonempty names.');
-        return [name, path(value)];
-    })));
-}
-/** Validate and snapshot JSON before asynchronous dependency resolution starts. */
-export function json(value, ancestors = new Set()) {
-    if (value === null || typeof value === 'string' || typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number' && Number.isFinite(value))
-        return value;
-    if (typeof value !== 'object')
-        throw new TypeError('Dependency values must contain only JSON values.');
-    if (ancestors.has(value))
-        throw new TypeError('Dependency values must not contain cycles.');
-    ancestors.add(value);
-    try {
-        if (!Array.isArray(value))
-            return Object.freeze(Object.fromEntries(Object.entries(record(value)).map(([name, item]) => [name, json(item, ancestors)])));
-        if (Object.getOwnPropertySymbols(value).length)
-            throw new TypeError('Dependency values must not contain symbol properties.');
-        const items = [];
-        for (let index = 0; index < value.length; index++) {
-            const property = Object.getOwnPropertyDescriptor(value, index);
-            if (!property || !('value' in property))
-                throw new TypeError('Dependency values must not contain sparse arrays or getters.');
-            const item = property.value;
-            items.push(json(item, ancestors));
-        }
-        return Object.freeze(items);
-    }
-    finally {
-        ancestors.delete(value);
-    }
-}
-export function dependencies(value) {
-    const entries = Object.entries(record(value)).map(([name, value]) => {
-        if (!name)
-            throw new TypeError('Dependencies require nonempty names.');
-        const source = record(value);
-        if (Object.keys(source).length !== 1)
-            throw new TypeError('Each dependency must have exactly one value, path, url, or package.');
-        if (Object.hasOwn(source, 'value'))
-            return [name, Object.freeze({ value: json(source.value) })];
-        if (Object.hasOwn(source, 'path'))
-            return [name, Object.freeze({ path: path(source.path) })];
-        if (Object.hasOwn(source, 'url') && typeof source.url === 'string' && source.url && !source.url.includes('\0')) {
-            return [name, Object.freeze({ url: source.url })];
-        }
-        if (Object.hasOwn(source, 'package') && typeof source.package === 'string' && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i.test(source.package)) {
-            return [name, Object.freeze({ package: source.package })];
-        }
-        throw new TypeError('Each dependency must have a JSON value, root-relative path, nonempty URL, or package name without a subpath.');
-    });
-    return Object.freeze(Object.fromEntries(entries));
-}
-export function resolvedDependencies(value) {
-    const entries = Object.entries(dependencies(value)).map(([name, dependency]) => {
-        if (dependency.url !== undefined)
-            throw new TypeError('Expected resolved dependencies, not URLs.');
-        return [name, dependency];
-    });
-    return Object.freeze(Object.fromEntries(entries));
-}
-/** Saved dependencies are rechecked later, so they cannot be values: values select the result and belong to the key. */
-export function savedDependencies(value) {
-    const entries = Object.entries(dependencies(value)).map(([name, dependency]) => {
-        if (dependency.value !== undefined)
-            throw new TypeError('Saved dependencies cannot be values: values select the result; pass them to the constructor.');
-        return [name, dependency];
-    });
-    return Object.freeze(Object.fromEntries(entries));
-}
-export function hashes(value) {
-    return Object.freeze(Object.fromEntries(Object.entries(record(value)).map(([name, hash]) => {
-        if (!name || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) {
-            throw new TypeError('Invalid file dependency hash.');
-        }
-        return [name, hash];
-    })));
-}
-export function equalHashes(first, second) {
-    const names = Object.keys(first);
-    return names.length === Object.keys(second).length && names.every((name) => first[name] === second[name]);
-}
-//# sourceMappingURL=dependencies.js.map