nitro-patcher 0.2.0 → 0.3.0

package/src/nitro-patch-helper.ts

@@ -1,13 +1,14 @@
 // Native TypeScript port of NitroPatchHelper/PatchHelper.cs, GPL-3.0.
-import { hashDigest, readFile } from '#nitro-runtime';
-import { bytes } from './nitro/binary';
-import { NDSFile } from './nitro/nds-file';
-import { readZip } from './patch/zip';
-import { decodeXdelta } from './patch/xdelta';
+import { hashDigest, readFile } from "#nitro-runtime";
+
+import { bytes } from "./nitro/binary";
+import { NDSFile } from "./nitro/nds-file";
+import { decodeXdelta } from "./patch/xdelta";
+import { extractZipEntry as extractEntry, readZip } from "./patch/zip";
 
 export const PatchReturnValue = Object.freeze({
-  SUCCESS: 'SUCCESS',
-  MD5_MISMATCH: 'MD5_MISMATCH',
+  SUCCESS: "SUCCESS",
+  MD5_MISMATCH: "MD5_MISMATCH",
 } as const);
 export type PatchReturnValue = (typeof PatchReturnValue)[keyof typeof PatchReturnValue];
 
@@ -41,7 +42,7 @@ export interface PatchMetadata {
 }
 
 export interface PatchReadme {
-  format: 'markdown' | 'plaintext';
+  format: "markdown" | "plaintext";
   content: string;
 }
 
@@ -50,7 +51,7 @@ export interface PatchInfo {
   readme: PatchReadme | null;
 }
 
-const md5 = (data: Uint8Array): string => hashDigest('md5', data).toString('hex');
+const md5 = (data: Uint8Array): string => hashDigest("md5", data).toString("hex");
 const invalidMetadata = (message: string): null => {
   console.warn(`忽略 metadata.json：${message}`);
   return null;
@@ -60,43 +61,46 @@ const invalidMetadataField = (field: keyof PatchMetadata, message: string): void
 };
 
 const readMetadata = (files: Map<string, Buffer>): PatchMetadata | null => {
-  const file = files.get('metadata.json');
+  const file = files.get("metadata.json");
   if (!file) return null;
 
   let metadata: unknown;
   try {
-    metadata = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(file));
+    metadata = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(file));
   } catch (error) {
     return invalidMetadata(
       `格式错误，可能是因为补丁包已损坏：${error instanceof Error ? error.message : String(error)}`,
     );
   }
-  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
-    return invalidMetadata('根节点必须是对象。');
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+    return invalidMetadata("根节点必须是对象。");
 
   const value = metadata as Record<string, unknown>;
   const result: PatchMetadata = {};
-  for (const field of ['id', 'author', 'name', 'homepage', 'version'] as const) {
-    if (typeof value[field] === 'string') result[field] = value[field];
-    else invalidMetadataField(field, '必须是字符串。');
+  for (const field of ["id", "author", "name", "homepage", "version"] as const) {
+    const fieldValue = value[field];
+    if (fieldValue === undefined) continue;
+    if (typeof fieldValue === "string") result[field] = fieldValue;
+    else invalidMetadataField(field, "必须是字符串。");
   }
-  if (typeof value.isBeta === 'boolean') result.isBeta = value.isBeta;
-  else invalidMetadataField('isBeta', '必须是布尔值。');
+  if (value.isBeta === undefined) return result;
+  if (typeof value.isBeta === "boolean") result.isBeta = value.isBeta;
+  else invalidMetadataField("isBeta", "必须是布尔值。");
 
   return result;
 };
 
 const readReadme = (files: Map<string, Buffer>): PatchReadme | null => {
   for (const [filename, format] of [
-    ['README.md', 'markdown'],
-    ['README.txt', 'plaintext'],
+    ["README.md", "markdown"],
+    ["README.txt", "plaintext"],
   ] as const) {
     const file = files.get(filename.toLowerCase());
     if (!file) continue;
     try {
       return {
         format,
-        content: new TextDecoder('utf-8', { fatal: true }).decode(file),
+        content: new TextDecoder("utf-8", { fatal: true }).decode(file),
       };
     } catch (error) {
       console.warn(
@@ -108,16 +112,12 @@ const readReadme = (files: Map<string, Buffer>): PatchReadme | null => {
 };
 
 /** Read and validate metadata.json from a NitroPatcher ZIP package. */
-export const readPatchMetadata = (
-  patch: Uint8Array,
-  options: PatchOptions = {},
-): PatchMetadata | null => readMetadata(readZip(patch, options));
+export const readPatchMetadata = (patch: Uint8Array, options: PatchOptions = {}): PatchMetadata | null =>
+  readMetadata(readZip(patch, options));
 
 /** Read a root README.md or README.txt from a NitroPatcher ZIP package. */
-export const readPatchReadme = (
-  patch: Uint8Array,
-  options: PatchOptions = {},
-): PatchReadme | null => readReadme(readZip(patch, options));
+export const readPatchReadme = (patch: Uint8Array, options: PatchOptions = {}): PatchReadme | null =>
+  readReadme(readZip(patch, options));
 
 /** Read metadata and README content while parsing the patch package only once. */
 export const readPatchInfo = (patch: Uint8Array, options: PatchOptions = {}): PatchInfo => {
@@ -125,6 +125,10 @@ export const readPatchInfo = (patch: Uint8Array, options: PatchOptions = {}): Pa
   return { metadata: readMetadata(files), readme: readReadme(files) };
 };
 
+/** Extract one file from a ZIP archive entirely in memory. */
+export const extractZipEntry = (archive: Uint8Array, entryName: string, options: PatchOptions = {}): Buffer =>
+  extractEntry(archive, entryName, options);
+
 /** Read metadata.json from a NitroPatcher ZIP package on disk. */
 export const readPatchMetadataFile = async (
   patchPath: string,
@@ -132,40 +136,29 @@ export const readPatchMetadataFile = async (
 ): Promise<PatchMetadata | null> => readPatchMetadata(await readFile(patchPath), options);
 
 /** Read a patch README from disk. */
-export const readPatchReadmeFile = async (
-  patchPath: string,
-  options: PatchOptions = {},
-): Promise<PatchReadme | null> => readPatchReadme(await readFile(patchPath), options);
+export const readPatchReadmeFile = async (patchPath: string, options: PatchOptions = {}): Promise<PatchReadme | null> =>
+  readPatchReadme(await readFile(patchPath), options);
 
 /** Read patch metadata and README content from disk. */
-export const readPatchInfoFile = async (
-  patchPath: string,
-  options: PatchOptions = {},
-): Promise<PatchInfo> => readPatchInfo(await readFile(patchPath), options);
+export const readPatchInfoFile = async (patchPath: string, options: PatchOptions = {}): Promise<PatchInfo> =>
+  readPatchInfo(await readFile(patchPath), options);
 
 /** Apply an existing NitroPatcher ZIP package entirely in memory. */
-export const patchBuffer = (
-  original: Uint8Array,
-  patch: Uint8Array,
-  options: PatchOptions = {},
-): PatchResult => {
-  const input = bytes(original, 'original ROM');
+export const patchBuffer = (original: Uint8Array, patch: Uint8Array, options: PatchOptions = {}): PatchResult => {
+  const input = bytes(original, "original ROM");
   const patches = readZip(patch, options);
   const inputMd5 = md5(input);
   const preprocessing = patches.get(`preprocessing/${inputMd5}.xdelta`);
-  const rom = new NDSFile(
-    preprocessing ? decodeXdelta(input, preprocessing, options) : input,
-    options,
-  );
+  const rom = new NDSFile(preprocessing ? decodeXdelta(input, preprocessing, options) : input, options);
   let matched = true;
-  const md5File = patches.get('md5.txt');
+  const md5File = patches.get("md5.txt");
   if (md5File) {
     matched = false;
-    for (const line of md5File.toString('utf8').split('\n')) {
+    for (const line of md5File.toString("utf8").split("\n")) {
       const expected = line.trim();
-      if (!expected || expected.startsWith('#')) continue;
+      if (!expected || expected.startsWith("#")) continue;
       // Keep the original format contract: exactly 32 characters, case-insensitive comparison.
-      if (expected.length !== 32) throw new Error('md5.txt 格式错误，可能是因为补丁包已损坏。');
+      if (expected.length !== 32) throw new Error("md5.txt 格式错误，可能是因为补丁包已损坏。");
       if (expected.toLowerCase() === inputMd5) {
         matched = true;
         break;
@@ -173,11 +166,9 @@ export const patchBuffer = (
     }
   }
   for (const { path } of rom.listFiles()) {
-    const normalized = path.replaceAll('\\', '/').toLowerCase();
+    const normalized = path.replaceAll("\\", "/").toLowerCase();
     const delta = patches.get(`xdelta/${normalized}`);
-    const replacement = delta
-      ? decodeXdelta(rom.getFile(path), delta, options)
-      : patches.get(normalized);
+    const replacement = delta ? decodeXdelta(rom.getFile(path), delta, options) : patches.get(normalized);
     if (replacement) rom.replaceFile(path, replacement);
   }
   const buffer = rom.toBuffer();
@@ -201,6 +192,7 @@ export const patchIt = async (
 
 /** Namespaced counterpart of the original C# helper, sharing the same typed functions. */
 export const PatchHelper = Object.freeze({
+  extractZipEntry,
   patchBuffer,
   patchIt,
   readPatchInfo,
@@ -210,5 +202,5 @@ export const PatchHelper = Object.freeze({
   readPatchReadme,
   readPatchReadmeFile,
 });
-export { decodeXdelta } from './patch/xdelta';
-export type { XdeltaOptions } from './patch/xdelta';
+export { decodeXdelta } from "./patch/xdelta";
+export type { XdeltaOptions } from "./patch/xdelta";

package/src/patch/xdelta.ts

@@ -11,7 +11,7 @@ class Reader {
   pos = 0;
   constructor(
     readonly bytes: Buffer,
-    readonly label = 'patch',
+    readonly label = "patch",
   ) {}
   get remaining() {
     return this.bytes.length - this.pos;
@@ -31,8 +31,7 @@ class Reader {
     return fail(`invalid variable-length integer in ${this.label}`);
   }
   take(size: number): Buffer {
-    if (size > this.remaining)
-      fail(`truncated ${this.label}: requested ${size} bytes, ${this.remaining} remain`);
+    if (size > this.remaining) fail(`truncated ${this.label}: requested ${size} bytes, ${this.remaining} remain`);
     const result = this.bytes.subarray(this.pos, this.pos + size);
     this.pos += size;
     return result;
@@ -40,24 +39,28 @@ class Reader {
 }
 
 // RFC 3284 section 5.6: (operation, size, COPY address mode), up to two per opcode.
-type Operation = { type: 'ADD' | 'RUN' | 'COPY'; size: number; mode: number };
+interface Operation {
+  type: "ADD" | "RUN" | "COPY";
+  size: number;
+  mode: number;
+}
 const table: Operation[][] = [];
-const op = (type: Operation['type'], size: number, mode = 0): Operation => ({ type, size, mode });
-table.push([op('RUN', 0)]);
-for (let size = 0; size <= 17; size++) table.push([op('ADD', size)]);
+const op = (type: Operation["type"], size: number, mode = 0): Operation => ({ type, size, mode });
+table.push([op("RUN", 0)]);
+for (let size = 0; size <= 17; size++) table.push([op("ADD", size)]);
 for (let mode = 0; mode <= 8; mode++) {
-  table.push([op('COPY', 0, mode)]);
-  for (let size = 4; size <= 18; size++) table.push([op('COPY', size, mode)]);
+  table.push([op("COPY", 0, mode)]);
+  for (let size = 4; size <= 18; size++) table.push([op("COPY", size, mode)]);
 }
 for (let mode = 0; mode <= 5; mode++) {
   for (let add = 1; add <= 4; add++) {
-    for (let copy = 4; copy <= 6; copy++) table.push([op('ADD', add), op('COPY', copy, mode)]);
+    for (let copy = 4; copy <= 6; copy++) table.push([op("ADD", add), op("COPY", copy, mode)]);
   }
 }
 for (let mode = 6; mode <= 8; mode++) {
-  for (let add = 1; add <= 4; add++) table.push([op('ADD', add), op('COPY', 4, mode)]);
+  for (let add = 1; add <= 4; add++) table.push([op("ADD", add), op("COPY", 4, mode)]);
 }
-for (let mode = 0; mode <= 8; mode++) table.push([op('COPY', 4, mode), op('ADD', 1)]);
+for (let mode = 0; mode <= 8; mode++) table.push([op("COPY", 4, mode), op("ADD", 1)]);
 
 function adler32(bytes: Uint8Array): number {
   let a = 1,
@@ -96,22 +99,17 @@ export interface XdeltaOptions {
   maxWindowSize?: number;
 }
 
-export const decodeXdelta = (
-  source: Uint8Array,
-  patch: Uint8Array,
-  options: XdeltaOptions = {},
-): Buffer => {
-  const sourceBytes = asBuffer(source, 'source');
-  const reader = new Reader(asBuffer(patch, 'patch'));
-  const maxOutput = limit(options.maxOutputSize, 1024 * 1024 * 1024, 'maxOutputSize');
-  const maxWindow = limit(options.maxWindowSize, 16 * 1024 * 1024, 'maxWindowSize');
-  if (!reader.take(3).equals(Buffer.from([0xd6, 0xc3, 0xc4]))) fail('invalid file signature');
-  if (reader.byte() !== 0) fail('unsupported version (expected 0)');
+export const decodeXdelta = (source: Uint8Array, patch: Uint8Array, options: XdeltaOptions = {}): Buffer => {
+  const sourceBytes = asBuffer(source, "source");
+  const reader = new Reader(asBuffer(patch, "patch"));
+  const maxOutput = limit(options.maxOutputSize, 1024 * 1024 * 1024, "maxOutputSize");
+  const maxWindow = limit(options.maxWindowSize, 16 * 1024 * 1024, "maxWindowSize");
+  if (!reader.take(3).equals(Buffer.from([0xd6, 0xc3, 0xc4]))) fail("invalid file signature");
+  if (reader.byte() !== 0) fail("unsupported version (expected 0)");
   const header = reader.byte();
-  if (header & ~7) fail('unrecognized header indicator bits');
-  if (header & 1)
-    fail('secondary compression is unsupported; recreate the patch using xdelta3 -S none');
-  if (header & 2) fail('custom code table is unsupported');
+  if (header & ~7) fail("unrecognized header indicator bits");
+  if (header & 1) fail("secondary compression is unsupported; recreate the patch using xdelta3 -S none");
+  if (header & 2) fail("custom code table is unsupported");
   if (header & 4) reader.take(reader.integer());
   const windows: Buffer[] = [];
   let total = 0;
@@ -119,14 +117,14 @@ export const decodeXdelta = (
   while (reader.remaining) {
     const indicator = reader.byte();
     if (indicator & ~7 || (indicator & 3) === 3)
-      fail('invalid window indicator: source and target are mutually exclusive');
+      fail("invalid window indicator: source and target are mutually exclusive");
     let dictionary: Buffer = Buffer.alloc(0);
     if (indicator & 3) {
       const length = reader.integer();
       const offset = reader.integer();
       const available = indicator & 1 ? sourceBytes.length : total;
       if (offset > available || length > available - offset)
-        fail('source segment exceeds available source/target bounds');
+        fail("source segment exceeds available source/target bounds");
       if (indicator & 1) dictionary = sourceBytes.subarray(offset, offset + length);
       else {
         dictionary = Buffer.allocUnsafe(length);
@@ -141,24 +139,22 @@ export const decodeXdelta = (
       }
     }
     const deltaLength = reader.integer();
-    const delta = new Reader(reader.take(deltaLength), 'delta window');
+    const delta = new Reader(reader.take(deltaLength), "delta window");
     const targetLength = delta.integer();
-    if (targetLength > maxWindow)
-      fail(`window size ${targetLength} exceeds maximum limit ${maxWindow}`);
+    if (targetLength > maxWindow) fail(`window size ${targetLength} exceeds maximum limit ${maxWindow}`);
     if (targetLength > maxOutput - total) fail(`output size exceeds maximum limit ${maxOutput}`);
-    if (dictionary.length + targetLength > UINT32_MAX)
-      fail('window address space exceeds 32-bit limit');
+    if (dictionary.length + targetLength > UINT32_MAX) fail("window address space exceeds 32-bit limit");
     const compressed = delta.byte();
-    if (compressed & ~7) fail('unrecognized delta indicator bits');
-    if (compressed) fail('secondary compression in delta sections is unsupported');
+    if (compressed & ~7) fail("unrecognized delta indicator bits");
+    if (compressed) fail("secondary compression in delta sections is unsupported");
     const dataLength = delta.integer(),
       instructionLength = delta.integer(),
       addressLength = delta.integer();
     const checksum = indicator & 4 ? delta.take(4).readUInt32BE() : null;
-    const data = new Reader(delta.take(dataLength), 'data section');
-    const instructions = new Reader(delta.take(instructionLength), 'instruction section');
-    const addresses = new Reader(delta.take(addressLength), 'address section');
-    if (delta.remaining) fail('delta encoding length does not match section lengths');
+    const data = new Reader(delta.take(dataLength), "data section");
+    const instructions = new Reader(delta.take(instructionLength), "instruction section");
+    const addresses = new Reader(delta.take(addressLength), "address section");
+    if (delta.remaining) fail("delta encoding length does not match section lengths");
     const target = Buffer.allocUnsafe(targetLength);
     const near = new Uint32Array(4),
       same = new Uint32Array(768);
@@ -169,9 +165,9 @@ export const decodeXdelta = (
       for (const { type, size: fixedSize, mode } of operations) {
         const size = fixedSize || instructions.integer();
         if (size > targetLength - position) fail(`${type} size exceeds target window length`);
-        if (type === 'ADD') {
+        if (type === "ADD") {
           data.take(size).copy(target, position);
-        } else if (type === 'RUN') {
+        } else if (type === "RUN") {
           target.fill(data.byte(), position, position + size);
         } else {
           const here = dictionary.length + position;
@@ -180,8 +176,7 @@ export const decodeXdelta = (
           else if (mode === 1) address = here - addresses.integer();
           else if (mode < 6) address = near[mode - 2]! + addresses.integer();
           else address = same[(mode - 6) * 256 + addresses.byte()]!;
-          if (address < 0 || address >= here)
-            fail(`COPY address ${address} is outside decoded address space ${here}`);
+          if (address < 0 || address >= here) fail(`COPY address ${address} is outside decoded address space ${here}`);
           near[nearIndex] = address;
           nearIndex = (nearIndex + 1) % near.length;
           same[address % same.length] = address;
@@ -195,7 +190,7 @@ export const decodeXdelta = (
           const from = Math.max(0, address - dictionary.length);
           while (copied < size) {
             const count = Math.min(size - copied, position + copied - from);
-            if (count <= 0) fail('COPY references unavailable target bytes');
+            if (count <= 0) fail("COPY references unavailable target bytes");
             target.copy(target, position + copied, from, from + count);
             copied += count;
           }
@@ -203,10 +198,9 @@ export const decodeXdelta = (
         position += size;
       }
     }
-    if (position !== targetLength)
-      fail(`target window length mismatch: decoded ${position}, expected ${targetLength}`);
-    if (data.remaining || addresses.remaining) fail('unused bytes in data/address section');
-    if (checksum !== null && adler32(target) !== checksum) fail('Adler32 checksum mismatch');
+    if (position !== targetLength) fail(`target window length mismatch: decoded ${position}, expected ${targetLength}`);
+    if (data.remaining || addresses.remaining) fail("unused bytes in data/address section");
+    if (checksum !== null && adler32(target) !== checksum) fail("Adler32 checksum mismatch");
     windows.push(target);
     total += targetLength;
   }

package/src/patch/zip.ts

@@ -1,5 +1,6 @@
-import { inflateRawSync } from '#nitro-runtime';
-import { crc32 } from '../nitro/crc';
+import { inflateRawSync } from "#nitro-runtime";
+
+import { crc32 } from "../nitro/crc";
 
 /** Resource limits apply to every central-directory entry, including duplicates. */
 export interface ZipOptions {
@@ -10,22 +11,21 @@ export interface ZipOptions {
 const fail = (message: string): never => {
   throw new Error(`ZIP: ${message}`);
 };
-const utf8 = new TextDecoder('utf-8', { fatal: true });
+const utf8 = new TextDecoder("utf-8", { fatal: true });
 // IBM code page 437, byte values 0x80..0xff. ASCII bytes retain their literal values.
 const cp437 =
-  'ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■ ';
+  "ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒáíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐└┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■ ";
 
 function decodeUtf8(bytes: Uint8Array): string {
   try {
     return utf8.decode(bytes);
   } catch {
-    return fail('invalid UTF-8 filename');
+    return fail("invalid UTF-8 filename");
   }
 }
 function boundOption(value: number | undefined, fallback: number, label: string): number {
   value ??= fallback;
-  if (!Number.isSafeInteger(value) || value < 0)
-    throw new RangeError(`${label} must be a non-negative safe integer`);
+  if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${label} must be a non-negative safe integer`);
   return value;
 }
 function checkRange(bytes: Buffer, offset: number, length: number, end = bytes.length): void {
@@ -41,7 +41,7 @@ function extras(bytes: Buffer): Map<number, Buffer> {
       length = bytes.readUInt16LE(offset + 2);
     offset += 4;
     checkRange(bytes, offset, length);
-    if (id === 1) fail('ZIP64 archives are unsupported');
+    if (id === 1) fail("ZIP64 archives are unsupported");
     fields.set(id, bytes.subarray(offset, offset + length));
     offset += length;
   }
@@ -52,7 +52,7 @@ function filename(raw: Buffer, flags: number, fields: Map<number, Buffer>): stri
   const unicode = fields.get(0x7075);
   if (unicode && unicode.length >= 5 && unicode[0] === 1 && unicode.readUInt32LE(1) === crc32(raw))
     return decodeUtf8(unicode.subarray(5));
-  let result = '';
+  let result = "";
   for (const byte of raw) result += byte < 128 ? String.fromCharCode(byte) : cp437[byte - 128]!;
   return result;
 }
@@ -65,26 +65,18 @@ function filename(raw: Buffer, flags: number, fields: Map<number, Buffer>): stri
  * Format reference: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
  */
 export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string, Buffer> => {
-  if (!(input instanceof Uint8Array))
-    throw new TypeError('ZIP input must be a Buffer or Uint8Array');
+  if (!(input instanceof Uint8Array)) throw new TypeError("ZIP input must be a Buffer or Uint8Array");
   const bytes = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
-  const maxSize = boundOption(
-    options.maxUncompressedSize,
-    1024 * 1024 * 1024,
-    'maxUncompressedSize',
-  );
-  const maxEntries = boundOption(options.maxEntries, 100000, 'maxEntries');
+  const maxSize = boundOption(options.maxUncompressedSize, 1024 * 1024 * 1024, "maxUncompressedSize");
+  const maxEntries = boundOption(options.maxEntries, 100000, "maxEntries");
   let eocd = -1;
   for (let offset = bytes.length - 22; offset >= Math.max(0, bytes.length - 65557); offset--) {
-    if (
-      bytes.readUInt32LE(offset) === 0x06054b50 &&
-      offset + 22 + bytes.readUInt16LE(offset + 20) === bytes.length
-    ) {
+    if (bytes.readUInt32LE(offset) === 0x06054b50 && offset + 22 + bytes.readUInt16LE(offset + 20) === bytes.length) {
       eocd = offset;
       break;
     }
   }
-  if (eocd < 0) fail('end of central directory not found or truncated');
+  if (eocd < 0) fail("end of central directory not found or truncated");
   const disk = bytes.readUInt16LE(eocd + 4),
     centralDisk = bytes.readUInt16LE(eocd + 6);
   const diskEntries = bytes.readUInt16LE(eocd + 8),
@@ -98,20 +90,19 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
     centralOffset === 0xffffffff ||
     (eocd >= 20 && bytes.readUInt32LE(eocd - 20) === 0x07064b50)
   )
-    fail('ZIP64 archives are unsupported');
-  if (disk || centralDisk || diskEntries !== count)
-    fail('split or multiple-disk archives are unsupported');
+    fail("ZIP64 archives are unsupported");
+  if (disk || centralDisk || diskEntries !== count) fail("split or multiple-disk archives are unsupported");
   if (count > maxEntries) fail(`entry count exceeds limit ${maxEntries}`);
   checkRange(bytes, centralOffset, centralSize, eocd);
-  if (centralOffset + centralSize !== eocd) fail('central directory size/offset mismatch');
-  if (count > Math.floor(centralSize / 46)) fail('entry count exceeds central directory size');
+  if (centralOffset + centralSize !== eocd) fail("central directory size/offset mismatch");
+  if (count > Math.floor(centralSize / 46)) fail("entry count exceeds central directory size");
   const result = new Map<string, Buffer>();
-  const ranges: Array<{ start: number; end: number }> = [];
+  const ranges: { start: number; end: number }[] = [];
   let offset = centralOffset,
     totalSize = 0;
   for (let index = 0; index < count; index++) {
     checkRange(bytes, offset, 46, eocd);
-    if (bytes.readUInt32LE(offset) !== 0x02014b50) fail('invalid central directory signature');
+    if (bytes.readUInt32LE(offset) !== 0x02014b50) fail("invalid central directory signature");
     const flags = bytes.readUInt16LE(offset + 8),
       method = bytes.readUInt16LE(offset + 10);
     const checksum = bytes.readUInt32LE(offset + 16),
@@ -122,40 +113,30 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
       commentLength = bytes.readUInt16LE(offset + 32);
     const startDisk = bytes.readUInt16LE(offset + 34),
       localOffset = bytes.readUInt32LE(offset + 42);
-    if (
-      size === 0xffffffff ||
-      compressedSize === 0xffffffff ||
-      localOffset === 0xffffffff ||
-      startDisk === 0xffff
-    )
-      fail('ZIP64 entry is unsupported');
-    if (startDisk) fail('split or multiple-disk entry is unsupported');
-    if (flags & 0x2041) fail('encrypted entries are unsupported');
-    if (flags & ~0x80e) fail('unsupported general purpose flags');
+    if (size === 0xffffffff || compressedSize === 0xffffffff || localOffset === 0xffffffff || startDisk === 0xffff)
+      fail("ZIP64 entry is unsupported");
+    if (startDisk) fail("split or multiple-disk entry is unsupported");
+    if (flags & 0x2041) fail("encrypted entries are unsupported");
+    if (flags & ~0x80e) fail("unsupported general purpose flags");
     if (method !== 0 && method !== 8) fail(`unsupported compression method ${method}`);
     if (size > maxSize - totalSize) fail(`uncompressed size exceeds limit ${maxSize}`);
     totalSize += size;
     checkRange(bytes, offset + 46, nameLength + extraLength + commentLength, eocd);
     const rawName = bytes.subarray(offset + 46, offset + 46 + nameLength);
-    const fields = extras(
-      bytes.subarray(offset + 46 + nameLength, offset + 46 + nameLength + extraLength),
-    );
-    const name = filename(rawName, flags, fields).replaceAll('\\', '/').toLowerCase();
+    const fields = extras(bytes.subarray(offset + 46 + nameLength, offset + 46 + nameLength + extraLength));
+    const name = filename(rawName, flags, fields).replaceAll("\\", "/").toLowerCase();
     offset += 46 + nameLength + extraLength + commentLength;
 
     checkRange(bytes, localOffset, 30, centralOffset);
-    if (bytes.readUInt32LE(localOffset) !== 0x04034b50) fail('invalid local header signature');
-    if (
-      bytes.readUInt16LE(localOffset + 6) !== flags ||
-      bytes.readUInt16LE(localOffset + 8) !== method
-    )
-      fail('local header flags/compression method mismatch');
+    if (bytes.readUInt32LE(localOffset) !== 0x04034b50) fail("invalid local header signature");
+    if (bytes.readUInt16LE(localOffset + 6) !== flags || bytes.readUInt16LE(localOffset + 8) !== method)
+      fail("local header flags/compression method mismatch");
     const localNameLength = bytes.readUInt16LE(localOffset + 26),
       localExtraLength = bytes.readUInt16LE(localOffset + 28);
     const dataOffset = localOffset + 30 + localNameLength + localExtraLength;
     checkRange(bytes, localOffset + 30, localNameLength + localExtraLength, centralOffset);
     if (!rawName.equals(bytes.subarray(localOffset + 30, localOffset + 30 + localNameLength)))
-      fail('local filename differs from central directory');
+      fail("local filename differs from central directory");
     extras(bytes.subarray(localOffset + 30 + localNameLength, dataOffset));
     if (
       !(flags & 8) &&
@@ -163,7 +144,7 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
         bytes.readUInt32LE(localOffset + 18) !== compressedSize ||
         bytes.readUInt32LE(localOffset + 22) !== size)
     )
-      fail('local header CRC/size mismatch');
+      fail("local header CRC/size mismatch");
     checkRange(bytes, dataOffset, compressedSize, centralOffset);
     let dataEnd = dataOffset + compressedSize;
     if (flags & 8) {
@@ -177,13 +158,13 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
         bytes.readUInt32LE(at + 8) === size;
       if (matches(dataEnd)) dataEnd += 12;
       else if (bytes.readUInt32LE(dataEnd) === 0x08074b50 && matches(dataEnd + 4)) dataEnd += 16;
-      else fail('data descriptor CRC/size mismatch');
+      else fail("data descriptor CRC/size mismatch");
     }
     ranges.push({ start: localOffset, end: dataEnd });
     const compressed = bytes.subarray(dataOffset, dataOffset + compressedSize);
     let data: Buffer;
     if (method === 0) {
-      if (compressedSize !== size) fail('stored entry compressed/uncompressed size mismatch');
+      if (compressedSize !== size) fail("stored entry compressed/uncompressed size mismatch");
       data = Buffer.from(compressed);
     } else {
       try {
@@ -196,11 +177,21 @@ export const readZip = (input: Uint8Array, options: ZipOptions = {}): Map<string
     }
     if (data.length !== size) fail(`uncompressed size mismatch for ${JSON.stringify(name)}`);
     if (crc32(data) !== checksum) fail(`CRC32 mismatch for ${JSON.stringify(name)}`);
-    if (name && !name.endsWith('/')) result.set(name, data);
+    if (name && !name.endsWith("/")) result.set(name, data);
   }
-  if (offset !== eocd) fail('central directory entry count/length mismatch');
+  if (offset !== eocd) fail("central directory entry count/length mismatch");
   ranges.sort((a, b) => a.start - b.start);
   for (let i = 1; i < ranges.length; i++)
-    if (ranges[i]!.start < ranges[i - 1]!.end) fail('overlapping local entry ranges');
+    if (ranges[i]!.start < ranges[i - 1]!.end) fail("overlapping local entry ranges");
   return result;
 };
+
+/** Extract one file using the same normalized, case-insensitive paths as readZip. */
+export const extractZipEntry = (input: Uint8Array, entryName: string, options: ZipOptions = {}): Buffer => {
+  if (typeof entryName !== "string" || !entryName) throw new TypeError("ZIP entry name must be a non-empty string");
+  const normalized = entryName.replaceAll("\\", "/").toLowerCase();
+  if (normalized.endsWith("/")) fail(`entry ${JSON.stringify(entryName)} is a directory`);
+  const entry = readZip(input, options).get(normalized);
+  if (entry === undefined) return fail(`entry ${JSON.stringify(entryName)} not found`);
+  return entry;
+};