stormlib-js 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# stormlib-js
+
+Pure TypeScript implementation of [StormLib](https://github.com/ladislav-zezula/StormLib) for reading MPQ (Mo'PaQ) archives. No native bindings, no WASM — just TypeScript.
+
+MPQ is the archive format used by Blizzard Entertainment games including Diablo, StarCraft, Warcraft III, and World of Warcraft.
+
+## Features
+
+- **Read-only** MPQ archive support
+- **MPQ V1 through V4** format support
+- **Pure TypeScript** — no native addons or WASM compilation required
+- **Synchronous API** — simple, straightforward file extraction
+- **Single runtime dependency** — only [pako](https://github.com/nickolaskgas/pako) for zlib
+- **Dual module output** — ships both CommonJS and ESM builds with full type declarations
+
+### Compression algorithms
+
+| Algorithm | Status |
+|---|---|
+| zlib (Deflate) | Supported |
+| PKWARE DCL (Implode) | Supported |
+| Blizzard Huffman | Supported |
+| ADPCM Mono / Stereo | Supported |
+| Sparse (RLE) | Supported |
+| BZIP2 | Not supported |
+| LZMA | Not supported |
+
+> BZIP2 and LZMA are rarely used in practice (only some SC2/HotS archives). If you need them, contributions are welcome.
+
+### Table formats
+
+| Table | Status |
+|---|---|
+| Classic Hash Table | Supported |
+| Classic Block Table | Supported |
+| Hi-Block Table (V2+) | Supported |
+| HET Table (V3+) | Supported |
+| BET Table (V3+) | Supported |
+
+## Installation
+
+```bash
+npm install stormlib-js
+```
+
+## Quick start
+
+```typescript
+import { MpqArchive } from 'stormlib-js';
+
+// Open an archive
+const archive = MpqArchive.open('game.mpq');
+
+// List known files (from internal listfile)
+const files = archive.getFileList();
+console.log(files);
+
+// Extract a file
+const data = archive.extractFile('war3map.j');
+console.log(data.toString('utf-8'));
+
+// Search with wildcards
+const results = archive.findFiles('*.blp');
+for (const entry of results) {
+  console.log(entry.fileName, entry.fileSize);
+}
+
+// Clean up
+archive.close();
+```
+
+## API
+
+### `MpqArchive`
+
+The main class for working with MPQ archives.
+
+#### `MpqArchive.open(path, options?)`
+
+Opens an MPQ archive from a file path.
+
+```typescript
+const archive = MpqArchive.open('archive.mpq');
+
+// With options
+const archive = MpqArchive.open('archive.mpq', {
+  noListfile: false,    // Skip loading internal (listfile)
+  noAttributes: false,  // Skip loading internal (attributes)
+  noHeaderSearch: false, // Don't search for MPQ header (assume offset 0)
+  forceMpqV1: false,    // Force reading as MPQ V1
+});
+```
+
+#### `archive.hasFile(name)`
+
+Returns `true` if the file exists in the archive.
+
+```typescript
+if (archive.hasFile('war3map.j')) {
+  // ...
+}
+```
+
+#### `archive.extractFile(name)`
+
+Extracts a file and returns its contents as a `Buffer`.
+
+```typescript
+const buf = archive.extractFile('war3map.w3i');
+```
+
+#### `archive.openFile(name)`
+
+Opens a file handle for more control over reading.
+
+```typescript
+const file = archive.openFile('units.doo');
+console.log(file.size, file.compressedSize, file.flags);
+const data = file.read();
+file.close();
+```
+
+#### `archive.getFileList()`
+
+Returns an array of known file names (populated from the internal listfile).
+
+```typescript
+const names = archive.getFileList();
+// ['war3map.j', 'war3map.w3e', ...]
+```
+
+#### `archive.findFiles(mask?)`
+
+Searches for files matching a wildcard pattern. Supports `*` and `?`.
+
+```typescript
+const textures = archive.findFiles('*.blp');
+for (const f of textures) {
+  console.log(f.fileName, f.fileSize, f.compSize);
+}
+```
+
+#### `archive.enumerateFiles()`
+
+Lists all file entries including unnamed ones. Unnamed entries are given synthetic names like `File00000001.xxx`.
+
+```typescript
+const all = archive.enumerateFiles();
+console.log(`Total: ${all.length} files`);
+```
+
+#### `archive.addListfile(names)`
+
+Applies an external list of file names to resolve unnamed entries. Useful for archives without an internal `(listfile)`.
+
+```typescript
+const resolved = archive.addListfile([
+  'war3map.j', 'war3map.w3e', 'war3map.w3i',
+]);
+console.log(`${resolved} new names resolved`);
+```
+
+#### `archive.getHeader()`
+
+Returns the parsed MPQ header.
+
+```typescript
+const header = archive.getHeader();
+console.log(`Format: V${header.wFormatVersion + 1}`);
+console.log(`Sector size: ${512 << header.wSectorSize}`);
+```
+
+#### `archive.close()`
+
+Closes the archive and releases the underlying file handle.
+
+### Error classes
+
+All errors extend `MpqError`:
+
+| Class | Description |
+|---|---|
+| `MpqNotFoundError` | File not found in the archive |
+| `MpqCorruptError` | Archive data is corrupt |
+| `MpqUnsupportedError` | Unsupported feature (e.g. BZIP2) |
+| `MpqEncryptionError` | Decryption failure |
+| `MpqCompressionError` | Decompression failure |
+
+```typescript
+import { MpqNotFoundError } from 'stormlib-js';
+
+try {
+  archive.extractFile('nonexistent.txt');
+} catch (err) {
+  if (err instanceof MpqNotFoundError) {
+    console.log('File does not exist');
+  }
+}
+```
+
+## Supported games
+
+This library can read MPQ archives from:
+
+- **Diablo** / **Diablo II** (V1, Huffman/PKWARE compression)
+- **StarCraft** / **Brood War** (V1, Huffman/PKWARE compression)
+- **Warcraft III** / **The Frozen Throne** (V1, zlib compression)
+- **World of Warcraft** (V2, 64-bit offsets)
+- **StarCraft II** (V3/V4, HET/BET tables)
+
+## Advanced usage
+
+Low-level crypto and hashing functions are exported for specialized use cases:
+
+```typescript
+import {
+  hashString, jenkinsHash,
+  decryptBlock, encryptBlock,
+  getStormBuffer,
+  MPQ_HASH_TABLE_INDEX,
+  MPQ_HASH_NAME_A,
+} from 'stormlib-js';
+
+// Compute MPQ hash
+const idx = hashString('(listfile)', MPQ_HASH_TABLE_INDEX);
+
+// Jenkins hash for HET tables
+const hash = jenkinsHash('war3map.j');
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## Acknowledgments
+
+- [Ladislav Zezula](https://github.com/ladislav-zezula) for the original [StormLib](https://github.com/ladislav-zezula/StormLib) C/C++ library and the comprehensive MPQ format documentation
+- [The StormLib documentation](http://www.zezula.net/en/mpq/stormlib.html) for format specifications
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,420 @@
+/** Raw MPQ header as parsed from disk (normalized to V4 superset) */
+interface MpqHeader {
+    /** 'MPQ\x1A' signature */
+    dwID: number;
+    /** Size of the header */
+    dwHeaderSize: number;
+    /** 32-bit archive size (V1) */
+    dwArchiveSize: number;
+    /** Format version: 0=V1, 1=V2, 2=V3, 3=V4 */
+    wFormatVersion: number;
+    /** Sector size shift (sector size = 512 << wSectorSize) */
+    wSectorSize: number;
+    /** Hash table offset (relative to archive start) */
+    dwHashTablePos: number;
+    /** Block table offset (relative to archive start) */
+    dwBlockTablePos: number;
+    /** Number of hash table entries */
+    dwHashTableSize: number;
+    /** Number of block table entries */
+    dwBlockTableSize: number;
+    /** 64-bit hi-block table offset */
+    hiBlockTablePos64: bigint;
+    /** High 16 bits of hash table offset */
+    wHashTablePosHi: number;
+    /** High 16 bits of block table offset */
+    wBlockTablePosHi: number;
+    /** 64-bit archive size */
+    archiveSize64: bigint;
+    /** 64-bit BET table position */
+    betTablePos64: bigint;
+    /** 64-bit HET table position */
+    hetTablePos64: bigint;
+    /** Compressed hash table size */
+    hashTableSize64: bigint;
+    /** Compressed block table size */
+    blockTableSize64: bigint;
+    /** Compressed hi-block table size */
+    hiBlockTableSize64: bigint;
+    /** Compressed HET table size */
+    hetTableSize64: bigint;
+    /** Compressed BET table size */
+    betTableSize64: bigint;
+    /** Raw chunk size for MD5 */
+    dwRawChunkSize: number;
+    /** MD5 checksums (V4) */
+    md5BlockTable: Uint8Array;
+    md5HashTable: Uint8Array;
+    md5HiBlockTable: Uint8Array;
+    md5BetTable: Uint8Array;
+    md5HetTable: Uint8Array;
+    md5MpqHeader: Uint8Array;
+}
+/** User data header that may precede the MPQ header */
+interface MpqUserData {
+    dwID: number;
+    cbUserDataSize: number;
+    dwHeaderOffs: number;
+    cbUserDataHeader: number;
+}
+/** Hash table entry (16 bytes on disk) */
+interface MpqHashEntry {
+    /** Hash of file path (method A) */
+    dwName1: number;
+    /** Hash of file path (method B) */
+    dwName2: number;
+    /** Windows LANGID locale */
+    lcLocale: number;
+    /** Platform (always 0) */
+    platform: number;
+    /** Index into block table (0xFFFFFFFF=free, 0xFFFFFFFE=deleted) */
+    dwBlockIndex: number;
+}
+/** Block table entry (16 bytes on disk) */
+interface MpqBlockEntry {
+    /** File data offset relative to archive start */
+    dwFilePos: number;
+    /** Compressed file size */
+    dwCSize: number;
+    /** Uncompressed file size */
+    dwFSize: number;
+    /** File flags */
+    dwFlags: number;
+}
+/** Unified file entry (in-memory representation) */
+interface FileEntry {
+    /** Jenkins hash (for BET table) */
+    fileNameHash: bigint;
+    /** File data offset relative to MPQ header */
+    byteOffset: bigint;
+    /** File time (FILETIME) from attributes */
+    fileTime: bigint;
+    /** Decompressed size */
+    fileSize: number;
+    /** Compressed size */
+    cmpSize: number;
+    /** File flags */
+    flags: number;
+    /** CRC32 from attributes */
+    crc32: number;
+    /** MD5 from attributes */
+    md5: Uint8Array;
+    /** File name (empty if unknown) */
+    fileName: string;
+}
+/** HET table header */
+interface HetTableHeader {
+    signature: number;
+    version: number;
+    dataSize: number;
+    tableSize: number;
+    maxFileCount: number;
+    hashTableSize: number;
+    hashEntrySize: number;
+    totalIndexSize: number;
+    indexSizeExtra: number;
+    indexSize: number;
+    blockTableSize: number;
+}
+/** BET table header */
+interface BetTableHeader {
+    signature: number;
+    version: number;
+    dataSize: number;
+    tableSize: number;
+    maxFileCount: number;
+    flagCount: number;
+}
+/** File search result */
+interface FileFindData {
+    fileName: string;
+    plainName: string;
+    hashIndex: number;
+    blockIndex: number;
+    fileSize: number;
+    compSize: number;
+    fileFlags: number;
+    locale: number;
+}
+/** Open archive flags */
+interface OpenArchiveOptions {
+    noListfile?: boolean;
+    noAttributes?: boolean;
+    noHeaderSearch?: boolean;
+    forceMpqV1?: boolean;
+    checkSectorCrc?: boolean;
+}
+
+/**
+ * File stream abstraction for reading MPQ archives from disk.
+ * Uses Node.js fs module for synchronous positioned reads.
+ */
+declare class FileStream {
+    private fd;
+    private fileSize;
+    private filePath;
+    private constructor();
+    /**
+     * Open a file for reading.
+     */
+    static open(path: string): FileStream;
+    /**
+     * Read bytes at a given offset.
+     *
+     * @param offset - Byte offset from the beginning of the file
+     * @param length - Number of bytes to read
+     * @returns Buffer containing the read data
+     */
+    read(offset: bigint, length: number): Buffer;
+    /**
+     * Read bytes into an existing buffer.
+     */
+    readInto(offset: bigint, buffer: Buffer, bufOffset: number, length: number): number;
+    /**
+     * Get the total file size.
+     */
+    getSize(): bigint;
+    /**
+     * Get the file path.
+     */
+    getPath(): string;
+    /**
+     * Close the file stream.
+     */
+    close(): void;
+}
+
+/**
+ * MpqFile represents an open file handle within an MPQ archive.
+ * It provides methods to read file data.
+ */
+
+declare class MpqFile {
+    private stream;
+    private archiveOffset;
+    private entry;
+    private sectorSize;
+    private fileKey;
+    private closed;
+    constructor(stream: FileStream, archiveOffset: bigint, entry: FileEntry, sectorSize: number);
+    /** Uncompressed file size */
+    get size(): number;
+    /** Compressed file size */
+    get compressedSize(): number;
+    /** File flags */
+    get flags(): number;
+    /** File name */
+    get name(): string;
+    /** The underlying file entry */
+    get fileEntry(): FileEntry;
+    /**
+     * Read the entire file contents.
+     *
+     * @returns Buffer containing the decompressed file data
+     */
+    read(): Buffer;
+    /**
+     * Close the file handle.
+     */
+    close(): void;
+}
+
+/**
+ * MpqArchive - Main class for reading MPQ archives.
+ *
+ * This is the primary public API for opening and reading MPQ files.
+ */
+
+declare class MpqArchive {
+    private stream;
+    private header;
+    private archiveOffset;
+    private sectorSize;
+    private hashTable;
+    private blockTable;
+    private hiBlockTable;
+    private hetTable;
+    private betTable;
+    private fileEntries;
+    private attributes;
+    private closed;
+    private constructor();
+    /**
+     * Open an MPQ archive from a file path.
+     *
+     * @param path - Path to the MPQ file
+     * @param options - Open options
+     * @returns MpqArchive instance
+     */
+    static open(path: string, options?: OpenArchiveOptions): MpqArchive;
+    /**
+     * Load all archive tables (hash, block, HET, BET).
+     */
+    private loadTables;
+    /**
+     * Load and parse the (listfile) to populate file names.
+     */
+    private loadListfile;
+    /**
+     * Load and parse the (attributes) file.
+     */
+    private loadAttributes;
+    /**
+     * Internal: extract a file by name without relying on the listfile.
+     * Used for bootstrapping (listfile) and (attributes) loading.
+     */
+    private extractFileByName;
+    /**
+     * Check if a file exists in the archive.
+     */
+    hasFile(name: string): boolean;
+    /**
+     * Open a file within the archive for reading.
+     *
+     * @param name - File path within the archive
+     * @returns MpqFile handle
+     */
+    openFile(name: string): MpqFile;
+    /**
+     * Extract a file's contents directly.
+     *
+     * @param name - File path within the archive
+     * @returns Buffer with the file contents
+     */
+    extractFile(name: string): Buffer;
+    /**
+     * Get the list of all known file names (from listfile).
+     */
+    getFileList(): string[];
+    /**
+     * Find files matching a wildcard pattern.
+     *
+     * @param mask - Wildcard pattern (supports '*' and '?')
+     * @returns Array of matching file entries
+     */
+    findFiles(mask?: string): FileFindData[];
+    /**
+     * Apply an external list of file names to resolve unnamed entries.
+     * Equivalent to providing an external listfile to SFileFindFirstFile.
+     *
+     * @param names - Array of file names to try
+     * @returns Number of newly resolved names
+     */
+    addListfile(names: string[]): number;
+    /**
+     * Enumerate all existing file entries, including those without names.
+     * Unnamed entries get a synthetic name like "File00001234.xxx".
+     */
+    enumerateFiles(): FileFindData[];
+    /** Get the archive header */
+    getHeader(): Readonly<MpqHeader>;
+    /** Get the number of file entries */
+    get fileCount(): number;
+    /** Get the sector size */
+    getSectorSize(): number;
+    /**
+     * Close the archive and release resources.
+     */
+    close(): void;
+    /**
+     * Resolve a file name to its FileEntry.
+     */
+    private resolveFile;
+    private ensureOpen;
+}
+
+declare class MpqError extends Error {
+    constructor(message: string);
+}
+declare class MpqNotFoundError extends MpqError {
+    constructor(message?: string);
+}
+declare class MpqCorruptError extends MpqError {
+    constructor(message?: string);
+}
+declare class MpqUnsupportedError extends MpqError {
+    constructor(message?: string);
+}
+declare class MpqEncryptionError extends MpqError {
+    constructor(message?: string);
+}
+declare class MpqCompressionError extends MpqError {
+    constructor(message?: string);
+}
+
+declare const ID_MPQ = 441536589;
+declare const ID_MPQ_USERDATA = 458313805;
+declare const MPQ_FORMAT_VERSION_1 = 0;
+declare const MPQ_FORMAT_VERSION_2 = 1;
+declare const MPQ_FORMAT_VERSION_3 = 2;
+declare const MPQ_FORMAT_VERSION_4 = 3;
+declare const MPQ_FILE_IMPLODE = 256;
+declare const MPQ_FILE_COMPRESS = 512;
+declare const MPQ_FILE_ENCRYPTED = 65536;
+declare const MPQ_FILE_KEY_V2 = 131072;
+declare const MPQ_FILE_SINGLE_UNIT = 16777216;
+declare const MPQ_FILE_EXISTS = 2147483648;
+declare const MPQ_COMPRESSION_HUFFMANN = 1;
+declare const MPQ_COMPRESSION_ZLIB = 2;
+declare const MPQ_COMPRESSION_PKWARE = 8;
+declare const MPQ_COMPRESSION_BZIP2 = 16;
+declare const MPQ_COMPRESSION_LZMA = 18;
+declare const MPQ_COMPRESSION_SPARSE = 32;
+declare const MPQ_COMPRESSION_ADPCM_MONO = 64;
+declare const MPQ_COMPRESSION_ADPCM_STEREO = 128;
+declare const LISTFILE_NAME = "(listfile)";
+declare const SIGNATURE_NAME = "(signature)";
+declare const ATTRIBUTES_NAME = "(attributes)";
+
+/**
+ * Compute MPQ hash of a string. The hashType selects which section of the
+ * StormBuffer to use:
+ * - MPQ_HASH_TABLE_INDEX (0x000): hash table slot
+ * - MPQ_HASH_NAME_A (0x100): file name verification hash 1
+ * - MPQ_HASH_NAME_B (0x200): file name verification hash 2
+ * - MPQ_HASH_FILE_KEY (0x300): encryption key derivation
+ */
+declare function hashString(str: string, hashType: number): number;
+/** Convenience: compute hash table index */
+declare function hashTableIndex(fileName: string): number;
+/** Convenience: compute name hash A */
+declare function hashNameA(fileName: string): number;
+/** Convenience: compute name hash B */
+declare function hashNameB(fileName: string): number;
+/** Convenience: compute file encryption key hash */
+declare function hashFileKey(fileName: string): number;
+/**
+ * Jenkins hashlittle2 - used for HET/BET tables (64-bit hash).
+ * Produces a 64-bit hash as a BigInt.
+ */
+declare function jenkinsHash(str: string): bigint;
+
+/**
+ * Decrypt an MPQ data block in-place.
+ * The buffer must be DWORD-aligned (length must be a multiple of 4).
+ *
+ * @param data - Buffer to decrypt (modified in place)
+ * @param key - Primary encryption key (DWORD)
+ */
+declare function decryptBlock(data: Buffer, key: number): void;
+/**
+ * Encrypt an MPQ data block in-place.
+ *
+ * @param data - Buffer to encrypt (modified in place)
+ * @param key - Primary encryption key (DWORD)
+ */
+declare function encryptBlock(data: Buffer, key: number): void;
+/**
+ * Calculate the decryption key for a file within an MPQ archive.
+ *
+ * @param fileName - Full path of the file within the archive
+ * @param byteOffset - File's offset within the archive (lower 32 bits)
+ * @param fileSize - Uncompressed file size
+ * @param flags - File flags from block table
+ * @returns The file decryption key
+ */
+declare function decryptFileKey(fileName: string, byteOffset: bigint, fileSize: number, flags: number): number;
+
+declare function getStormBuffer(): Uint32Array;
+
+export { ATTRIBUTES_NAME, type BetTableHeader, type FileEntry, type FileFindData, type HetTableHeader, ID_MPQ, ID_MPQ_USERDATA, LISTFILE_NAME, MPQ_COMPRESSION_ADPCM_MONO, MPQ_COMPRESSION_ADPCM_STEREO, MPQ_COMPRESSION_BZIP2, MPQ_COMPRESSION_HUFFMANN, MPQ_COMPRESSION_LZMA, MPQ_COMPRESSION_PKWARE, MPQ_COMPRESSION_SPARSE, MPQ_COMPRESSION_ZLIB, MPQ_FILE_COMPRESS, MPQ_FILE_ENCRYPTED, MPQ_FILE_EXISTS, MPQ_FILE_IMPLODE, MPQ_FILE_KEY_V2, MPQ_FILE_SINGLE_UNIT, MPQ_FORMAT_VERSION_1, MPQ_FORMAT_VERSION_2, MPQ_FORMAT_VERSION_3, MPQ_FORMAT_VERSION_4, MpqArchive, type MpqBlockEntry, MpqCompressionError, MpqCorruptError, MpqEncryptionError, MpqError, MpqFile, type MpqHashEntry, type MpqHeader, MpqNotFoundError, MpqUnsupportedError, type MpqUserData, type OpenArchiveOptions, SIGNATURE_NAME, decryptBlock, decryptFileKey, encryptBlock, getStormBuffer, hashFileKey, hashNameA, hashNameB, hashString, hashTableIndex, jenkinsHash };