@emdzej/bimmerz-vfs

Read-only virtual file system for bimmerz tools — one interface, two backends:

| Backend | Class | Source | |---|---|---| | Local | FsaDirectory | File System Access API / OPFS (FileSystemDirectoryHandle) | | Remote | HttpDirectory | HTTP server + index.json directory listings |

Both implement VirtualDirectory. All lookups are case-insensitive.

Install

npm i @emdzej/bimmerz-vfs

Quick start

import { FsaDirectory, HttpDirectory, drillPath, listFiles } from '@emdzej/bimmerz-vfs';

// ---- Local (File System Access API / OPFS) ----
const handle = await showDirectoryPicker();
const local = new FsaDirectory(handle);

// ---- Remote (HTTP + index.json) ----
const remote = new HttpDirectory('https://files.example.com/inpa-bundle');

// ---- Same API for both ----
const ecu = await drillPath(remote, 'EDIABAS', 'Ecu');   // case-insensitive
const ipos = await listFiles(ecu!, '.ipo');               // [{ name: 'MS43.IPO', size: 12345 }]
const file = await ecu!.file('ms43.prg');                 // case-insensitive
const bytes = await file!.arrayBuffer();

API

VirtualDirectory

interface VirtualDirectory {
  readonly name: string;

  /** Case-insensitive. Returns null if not found. */
  file(name: string): Promise<VirtualFile | null>;

  /** Case-insensitive. Returns null if not found. */
  dir(name: string): Promise<VirtualDirectory | null>;

  /**
   * Flat listing of direct children.
   * Note: FsaDirectory returns size=0 for files — call file(name) for the real size.
   */
  entries(): Promise<VirtualEntry[]>;
}

type VirtualEntry =
  | { kind: 'file'; name: string; size: number }
  | { kind: 'dir';  name: string };

VirtualFile

interface VirtualFile {
  readonly name: string;   // original-cased full basename: "MS43.IPO"
  readonly size: number;
  arrayBuffer(): Promise<ArrayBuffer>;
}

FsaDirectory(handle)

Wraps a FileSystemDirectoryHandle (File System Access API or OPFS). Both sources return the same handle type, so this class works for both.

// File System Access API (user picks a folder)
const root = new FsaDirectory(await showDirectoryPicker());

// OPFS (pre-extracted bundle)
const opfsRoot = await navigator.storage.getDirectory();
const root = new FsaDirectory(opfsRoot);

entries() does not call getFile() per entry (no extra I/O for listings). Call file(name) when you need the actual size.

HttpDirectory(baseUrl, options?)

Navigates a remote tree using index.json files generated by bimmerz data index.

const root = new HttpDirectory('https://cdn.example.com/inpa', {
  indexFile: 'index.json',  // default
  fetch: customFetch,       // inject auth headers, mock in tests, etc.
});

How it works:

1. On first access entries() / file() / dir() fetches {baseUrl}/index.json and caches it.
2. file(name) finds the matching entry (case-insensitive on fullName) and returns an HttpFile that fetches {baseUrl}/{originalFullName} on arrayBuffer().
3. dir(name) returns a new HttpDirectory rooted at {baseUrl}/{originalFullName}/, which lazily fetches its own index.json.

The index.json format is the one written by bimmerz data index — both fullName (lowercase) and originalFullName (original casing) are present in every entry. The lookup uses fullName for matching and originalFullName for the fetch URL, so the original casing of the server's files is preserved in HTTP requests.

link entries (symlinks recorded by bimmerz data index) are treated as files.

drillPath(root, ...segments)

Walk down a path segment by segment, case-insensitively. Returns null at the first missing segment.

const cfgdat = await drillPath(root, 'EC-APPS', 'INPA', 'CFGDAT');
// equivalent to:
// root.dir('EC-APPS') → .dir('INPA') → .dir('CFGDAT')

listFiles(dir, ext?)

Return all file entries in dir, optionally filtered by extension (case-insensitive, dot required).

const ipos = await listFiles(cfgdat, '.ipo');
// [{ kind: 'file', name: 'MS43.IPO', size: 512 }, ...]

Returns Array<{ kind: 'file'; name: string; size: number }> — lightweight entry objects. Call dir.file(name) to open one.

Serving an install remotely

Use bimmerz data index to write index.json files into the extracted install tree, then serve the whole directory over HTTP (nginx, GitHub Pages, any static host):

bimmerz data index ~/inpa-extracted
# → writes index.json in every subdirectory

# Serve with any static file server
npx serve ~/inpa-extracted

Then point HttpDirectory at the server root:

const root = new HttpDirectory('http://localhost:3000');
const cfgdat = await drillPath(root, 'EC-APPS', 'INPA', 'CFGDAT');
const ipo = await cfgdat!.file('MS43.IPO');
const bytes = await ipo!.arrayBuffer();

Notes

• Read-only — no write operations. External write-back (fault-store reports, etc.) is application-layer concern.
• No runtime dependencies — FSA is a browser built-in; HTTP uses fetch. Works in any environment with fetch (browsers, Node ≥ 18, Deno, Bun).
• Index caching — each HttpDirectory instance fetches its index.json at most once. Create a new instance to force a refresh.