vitecache 0.0.0-stage → 0.1.0

package/dist/vite/resolve.js

@@ -0,0 +1,81 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import * as disk from '../disk.js';
+export class OutsideRootError extends Error {
+    constructor() {
+        super('File dependencies must be inside the project root');
+    }
+}
+export function inside(root, path) {
+    const name = relative(root, path);
+    return name !== '..' && !name.startsWith(`..${sep}`) && !isAbsolute(name);
+}
+export async function confine(root, dependencies) {
+    const canonicalRoot = await realpath(root);
+    for (const dependency of Object.values(dependencies)) {
+        if (!('path' in dependency))
+            continue;
+        const path = resolve(root, dependency.path);
+        if (!inside(root, path))
+            throw new OutsideRootError();
+        try {
+            if (!inside(canonicalRoot, await realpath(path)))
+                throw new OutsideRootError();
+        }
+        catch (error) {
+            if (!disk.missingDependency(error))
+                throw error;
+        }
+    }
+}
+async function exists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        if (!disk.missingDependency(error))
+            throw error;
+        return false;
+    }
+}
+export async function resolveDependencies(server, dependencies, origin) {
+    const entries = [];
+    const base = new URL(server.config.base, origin).pathname;
+    for (const [name, dependency] of Object.entries(dependencies)) {
+        if (!('url' in dependency)) {
+            entries.push([name, dependency]);
+            continue;
+        }
+        const url = new URL(dependency.url, origin);
+        if (url.origin !== origin)
+            throw new TypeError('File dependency URLs must have the Vite server origin');
+        if (!url.pathname.startsWith(base))
+            throw new TypeError('File dependency URL is outside the Vite base');
+        const pathname = decodeURIComponent(`/${url.pathname.slice(base.length)}`);
+        const publicFile = resolve(server.config.publicDir, `.${pathname}`);
+        const rootFile = resolve(server.config.root, `.${pathname}`);
+        let file;
+        if (server.config.publicDir && await exists(publicFile))
+            file = publicFile;
+        else if (pathname.startsWith('/@fs/'))
+            file = pathname.slice('/@fs'.length).replace(/^\/([A-Za-z]:\/)/, '$1');
+        else if (await exists(rootFile))
+            file = rootFile;
+        else {
+            const module = await server.pluginContainer.resolveId(pathname);
+            if (!module || !isAbsolute(module.id))
+                throw new TypeError(`Cannot resolve file dependency URL: ${dependency.url}`);
+            file = module.id.split('?')[0] ?? module.id;
+        }
+        if (!await exists(file))
+            throw new TypeError(`File dependency URL has no backing file: ${dependency.url}`);
+        const path = inside(server.config.root, file)
+            ? relative(server.config.root, file)
+            : relative(await realpath(server.config.root), await realpath(file));
+        entries.push([name, { path: path.split(sep).join('/') }]);
+    }
+    const resolved = Object.fromEntries(entries);
+    await confine(server.config.root, resolved);
+    return resolved;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/vite/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/vite/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,KAAK,IAAI,MAAM,YAAY,CAAC;AAEnC,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;QACE,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAC7D,CAAC;CACF;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,IAAY;IAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,YAAkC;IAC5E,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,MAAM,IAAI,UAAU,CAAC;YAAE,SAAS;QACtC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtD,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAAE,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACjF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;QAClD,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,IAAY;IAChC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAqB,EAAE,YAA0B,EAAE,MAAc;IACzG,MAAM,OAAO,GAAmC,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,CAAC,KAAK,IAAI,UAAU,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;QACxG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;QACxG,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3E,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,QAAQ,EAAE,CAAC,CAAC;QACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC,CAAC;QAC7D,IAAI,IAAY,CAAC;QACjB,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,MAAM,MAAM,CAAC,UAAU,CAAC;YAAE,IAAI,GAAG,UAAU,CAAC;aACtE,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;aACzG,IAAI,MAAM,MAAM,CAAC,QAAQ,CAAC;YAAE,IAAI,GAAG,QAAQ,CAAC;aAC5C,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAChE,IAAI,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAAE,MAAM,IAAI,SAAS,CAAC,uCAAuC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC;YACpH,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,4CAA4C,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3G,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;YAC3C,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;YACpC,CAAC,CAAC,QAAQ,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import { realpath, stat } from 'node:fs/promises';\nimport { isAbsolute, relative, resolve, sep } from 'node:path';\nimport type { ViteDevServer } from 'vite';\nimport type { Dependencies, ResolvedDependencies, ResolvedDependency } from '../types.js';\nimport * as disk from '../disk.js';\n\nexport class OutsideRootError extends Error {\n  constructor() {\n    super('File dependencies must be inside the project root');\n  }\n}\n\nexport function inside(root: string, path: string): boolean {\n  const name = relative(root, path);\n  return name !== '..' && !name.startsWith(`..${sep}`) && !isAbsolute(name);\n}\n\nexport async function confine(root: string, dependencies: ResolvedDependencies): Promise<void> {\n  const canonicalRoot = await realpath(root);\n  for (const dependency of Object.values(dependencies)) {\n    if (!('path' in dependency)) continue;\n    const path = resolve(root, dependency.path);\n    if (!inside(root, path)) throw new OutsideRootError();\n    try {\n      if (!inside(canonicalRoot, await realpath(path))) throw new OutsideRootError();\n    } catch (error) {\n      if (!disk.missingDependency(error)) throw error;\n    }\n  }\n}\n\nasync function exists(path: string): Promise<boolean> {\n  try {\n    return (await stat(path)).isFile();\n  } catch (error) {\n    if (!disk.missingDependency(error)) throw error;\n    return false;\n  }\n}\n\nexport async function resolveDependencies(server: ViteDevServer, dependencies: Dependencies, origin: string): Promise<ResolvedDependencies> {\n  const entries: [string, ResolvedDependency][] = [];\n  const base = new URL(server.config.base, origin).pathname;\n  for (const [name, dependency] of Object.entries(dependencies)) {\n    if (!('url' in dependency)) {\n      entries.push([name, dependency]);\n      continue;\n    }\n    const url = new URL(dependency.url, origin);\n    if (url.origin !== origin) throw new TypeError('File dependency URLs must have the Vite server origin');\n    if (!url.pathname.startsWith(base)) throw new TypeError('File dependency URL is outside the Vite base');\n    const pathname = decodeURIComponent(`/${url.pathname.slice(base.length)}`);\n    const publicFile = resolve(server.config.publicDir, `.${pathname}`);\n    const rootFile = resolve(server.config.root, `.${pathname}`);\n    let file: string;\n    if (server.config.publicDir && await exists(publicFile)) file = publicFile;\n    else if (pathname.startsWith('/@fs/')) file = pathname.slice('/@fs'.length).replace(/^\\/([A-Za-z]:\\/)/, '$1');\n    else if (await exists(rootFile)) file = rootFile;\n    else {\n      const module = await server.pluginContainer.resolveId(pathname);\n      if (!module || !isAbsolute(module.id)) throw new TypeError(`Cannot resolve file dependency URL: ${dependency.url}`);\n      file = module.id.split('?')[0] ?? module.id;\n    }\n    if (!await exists(file)) throw new TypeError(`File dependency URL has no backing file: ${dependency.url}`);\n    const path = inside(server.config.root, file)\n      ? relative(server.config.root, file)\n      : relative(await realpath(server.config.root), await realpath(file));\n    entries.push([name, { path: path.split(sep).join('/') }]);\n  }\n  const resolved = Object.fromEntries(entries);\n  await confine(server.config.root, resolved);\n  return resolved;\n}\n"]}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "vitecache",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Persistent binary caching for expensive computation in browsers and Node.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drawcall-ai/vitecache.git",
+    "directory": "packages/vitecache"
+  },
+  "bugs": {
+    "url": "https://github.com/drawcall-ai/vitecache/issues"
+  },
+  "homepage": "https://github.com/drawcall-ai/vitecache#readme",
+  "keywords": [
+    "vite",
+    "cache",
+    "precompute",
+    "browser",
+    "node",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.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"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "prepack": "pnpm build && pnpm typecheck && pnpm test",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.0.1"
+  },
+  "peerDependencies": {
+    "vite": ">=6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vite": "^8.0.0",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}

package/skills/vitecache/SKILL.md

@@ -0,0 +1,50 @@
+---
+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.
+---
+
+# 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.
+
+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.
+
+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. Use a separate entry for each concurrent computation.
+
+```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)
+```
+
+Use the Vite plugin when browser computation should produce reusable project files:
+
+```ts
+import { defineConfig } from "vite"
+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, so regenerate affected caches before deployment. Calling `save()` there warns and skips persistence.
+
+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.