@mixen/compat-chronodivide

Compatibility helpers for integrating mixen into ChronoDivide-style code with minimal changes.

Includes:

• MixFile + setChronoDivideVirtualFileFactory() — drop-in MixFile replacement (configure once, then swap in).
• VirtualFileSystem — drop-in VirtualFileSystem replacement with hash-aware lookup caching, and passes filename into new MixFile(stream, filename) (enables sidecar/index features without changing callers).
• configureChronoDivideMixen() — optional opt-in tuning (sidecar index, integrity checks, etc) while keeping open-file output identical.
  • validateBounds defaults to false to match ChronoDivide’s behavior; enable it if you want stricter parsing of potentially-corrupted mixes.
• packMixFromFiles() — repacking helper (outputs standard, readable Westwood .mix).
  • By default, embeds the __mixen_index.bin entry (disable with { embedIndex: false }).
• installVfsLookupCache() — patches a ChronoDivide-style VirtualFileSystem to cache lookup results (major runtime win with a tiny diff).
  • We avoid lowercasing/normalizing names for cache keys when you have case-sensitive archives (e.g. MemArchive); if you must, pass unsafeNormalizeNameForNameArchives: true.
  • Also forwards the archive id into archive.setMixId(id) when available (lets MixFile pick up sidecar/index optimizations even if it was constructed without a filename, e.g. CDN-loaded bytes).

This package is browser-safe (no Node-only APIs). You inject ChronoDivide’s VirtualFile.factory at integration time.

SystemJS / ChronoDivide integration

ChronoDivide’s shipped modules are System.register(...) bundles (SystemJS). This package will automatically use globalThis.SystemJS.import(...) when present, so most apps don’t need any loader wiring.

If you are not running under SystemJS, you can provide your own loader via setChronoDivideModuleLoader((id) => import(id)), or pass the needed constructors (MixFile, IdxFile, AudioBagFile, MemArchive) via VirtualFileSystem options.

Integration levels

• MixFile-only (fast hashing, optional sidecar/index): swap ChronoDivide’s MixFile class for this package’s MixFile.
• Cache-only (tiny diff): keep ChronoDivide’s VirtualFileSystem, but call installVfsLookupCache(vfs) after construction.
• VFS drop-in (biggest runtime win): swap ChronoDivide’s VirtualFileSystem for this package’s VirtualFileSystem.
  • Requires passing ChronoDivide’s FileNotFoundError constructor so downstream instanceof FileNotFoundError checks keep working.

Example (VFS drop-in):

import { VirtualFileSystem } from "@mixen/compat-chronodivide";
import { FileNotFoundError } from "data/vfs/FileNotFoundError";

const vfs = new VirtualFileSystem(rfs, logger, { FileNotFoundError });

Extra APIs (opt-in)

VirtualFileSystem adds a couple of opt-in helper methods that ChronoDivide’s original VFS doesn’t have:

• saveFile(...): persist generated mixes (or other files) back to the underlying storage, via rfs.writeFile(...) (e.g. RealFileSystemDir).
• invalidateCaches(): clears internal lookup caches (only needed if an archive mutates after it’s added, or if you manually reorder archivesByPriority).

Example:

// Save a newly generated/partitioned mix to storage (requires rfs.writeFile).
await vfs.saveFile(mixBytes, "expand02.mix");

// If you mutate an archive after adding it (uncommon), make new entries visible:
vfs.invalidateCaches();