@clearmist-labs/comic-archive-handler 1.4.0 → 1.6.0

package/dist/index.d.mts

@@ -50,6 +50,15 @@ export interface ConvertArchiveOptions extends ArchiveWriteOptions {
     format: ImageOutputFormat;
     options?: ImageConvertOptions;
   };
+  /**
+   * Replaces the source's embedded comic metadata in the output. The source's
+   * `ComicInfo.xml`/`MetronInfo.xml` entries (and, for an asar source, its
+   * header metadata) are dropped, then each schema given here is written the
+   * way the target format stores it: an asar header key, or a root-level
+   * `{schema}.xml` entry for every other format. When omitted, entries are
+   * copied as-is and an asar source's header metadata is not carried over.
+   */
+  metadata?: Partial<Record<MetadataSchema, ComicMetadata>>;
 }
 export interface AddMetadataOptions extends ArchiveWriteOptions {
   overwrite?: boolean;
@@ -475,6 +484,20 @@ export declare function phashToHex(hash: bigint): string;
 export declare function hammingDistance(a: bigint, b: bigint): number;
 export declare function computeArchiveImagePHash(input: ArchiveInput, entryPath: string): Promise<bigint>;
 //#endregion
+//#region src/images/dimensions.d.ts
+export interface ImageDimensions {
+  width: number;
+  height: number;
+}
+export interface ImageInfo extends ImageDimensions {
+  /** The format detected from the image's contents (not its file extension), such as `jpeg`, `png`, `webp`, or `bmp`. */
+  type: string;
+}
+/** Reads an image's format and pixel dimensions from its header without decoding it; `null` when the buffer isn't a readable image. */
+export declare function readImageInfo(buffer: Buffer): Promise<ImageInfo | null>;
+/** Reads an image's pixel dimensions from its header without decoding it; `null` when the buffer isn't a readable image. */
+export declare function readImageDimensions(buffer: Buffer): Promise<ImageDimensions | null>;
+//#endregion
 //#region src/images/isImage.d.ts
 export declare const IMAGE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp", "bmp", "tiff", "tif"];
 export declare function getExtension(entryPath: string): string;
@@ -535,6 +558,27 @@ export interface ReadArchiveEntriesResult {
  */
 export declare function readArchiveEntries(input: ArchiveInput): AsyncGenerator<ReadArchiveEntriesResult>;
 //#endregion
+//#region src/readArchiveImageInfo.d.ts
+export interface ArchiveImageInfo {
+  /** The entry's file name, without its directory. */
+  name: string;
+  /** The entry's full path inside the archive. */
+  path: string;
+  /** Pixel width, or `null` when the entry's contents aren't a readable image. */
+  width: number | null;
+  /** Pixel height, or `null` when the entry's contents aren't a readable image. */
+  height: number | null;
+  /** The format detected from the entry's contents (not its extension), or `null` when the contents aren't a readable image. */
+  type: string | null;
+}
+/**
+ * Returns the name, path, dimensions, and format of every image entry in an
+ * archive, in archive iteration order. Image entries are identified by
+ * extension (see `isImagePath`); non-image entries are skipped without being
+ * read. Everything is gathered in a single pass over the archive.
+ */
+export declare function readArchiveImageInfo(input: ArchiveInput): Promise<ArchiveImageInfo[]>;
+//#endregion
 //#region src/removeArchiveEntry.d.ts
 export declare function removeArchiveEntry(input: ArchiveInput, entryPath: string, options?: RemoveEntryOptions): Promise<Buffer | void>;
 //#endregion
@@ -571,6 +615,8 @@ declare const comicArchiveHandler: {
   hammingDistance: typeof hammingDistance;
   IMAGE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp", "bmp", "tiff", "tif"];
   isImagePath: typeof isImagePath;
+  readImageDimensions: typeof readImageDimensions;
+  readImageInfo: typeof readImageInfo;
   sha256ArchiveEntry: typeof sha256ArchiveEntry;
   sha256Archive: typeof sha256Archive;
   renameArchiveImagesSequentially: typeof renameArchiveImagesSequentially;
@@ -578,6 +624,7 @@ declare const comicArchiveHandler: {
   listArchiveFiles: typeof listArchiveFiles;
   readArchiveEntry: typeof readArchiveEntry;
   readArchiveEntries: typeof readArchiveEntries;
+  readArchiveImageInfo: typeof readArchiveImageInfo;
   removeArchiveEntry: typeof removeArchiveEntry;
   benchmarkArchive: typeof benchmarkArchive;
   renderBenchmarkReportMarkdown: typeof renderBenchmarkReportMarkdown;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/benchmark/types.ts","../src/errors.ts","../src/detect.ts","../src/convertArchive.ts","../src/extractArchive.ts","../src/metadata/comicInfo.ts","../src/metadata/metronInfo.ts","../src/metadata/validate.ts","../src/metadata/schema.ts","../src/metadata/index.ts","../src/images/convert.ts","../src/images/phash.ts","../src/images/isImage.ts","../src/hashing/sha256.ts","../src/rename.ts","../src/strip.ts","../src/listFiles.ts","../src/readArchiveEntry.ts","../src/readArchiveEntries.ts","../src/removeArchiveEntry.ts","../src/benchmark/benchmarkArchive.ts","../src/benchmark/report.ts","../src/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/benchmark/types.ts","../src/errors.ts","../src/detect.ts","../src/convertArchive.ts","../src/extractArchive.ts","../src/metadata/comicInfo.ts","../src/metadata/metronInfo.ts","../src/metadata/validate.ts","../src/metadata/schema.ts","../src/metadata/index.ts","../src/images/convert.ts","../src/images/phash.ts","../src/images/dimensions.ts","../src/images/isImage.ts","../src/hashing/sha256.ts","../src/rename.ts","../src/strip.ts","../src/listFiles.ts","../src/readArchiveEntry.ts","../src/readArchiveEntries.ts","../src/readArchiveImageInfo.ts","../src/removeArchiveEntry.ts","../src/benchmark/benchmarkArchive.ts","../src/benchmark/report.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -14,10 +14,10 @@ import * as os from "node:os";
 import { spawn } from "node:child_process";
 import sevenBin from "7zip-bin-full";
 import sharp from "sharp";
-import { pipeline } from "node:stream/promises";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 import { validateXML } from "xmllint-wasm";
 import { fileURLToPath } from "node:url";
+import { pipeline } from "node:stream/promises";
 import { createHash } from "node:crypto";
 //#region src/errors.ts
 var UnsupportedOperationError = class extends Error {
@@ -644,6 +644,13 @@ const asarAdapter = {
 			}
 			const outputFile = path.join(tempDir, "output.asar");
 			await createPackage(stagingDir, outputFile);
+			const comicMetadata = options?.comicMetadata;
+			if (comicMetadata && Object.keys(comicMetadata).length > 0) {
+				await writeAsarHeaderPatch(outputFile, (header) => {
+					header.comicMetadata = comicMetadata;
+				}, { output: destination });
+				return;
+			}
 			await new Promise((resolve, reject) => {
 				const readStream = fs.createReadStream(outputFile);
 				readStream.on("error", reject);
@@ -873,54 +880,6 @@ async function convertArchiveImages(input, format, options = {}) {
 	return withOutput(output, (destination) => adapter.write(entries(), destination, { tempDir }));
 }
 //#endregion
-//#region src/convertArchive.ts
-function replaceExtension(entryPath, format) {
-	return `${entryPath.replace(/\.[^./\\]+$/, "")}.${format}`;
-}
-async function convertArchive(input, targetType, options = {}) {
-	const sourceType = await detectArchiveType(input);
-	if (sourceType === "unknown") throw new ArchiveFormatError("Could not determine the source archive type.");
-	const sourceAdapter = getAdapter(sourceType);
-	const targetAdapter = getAdapter(targetType);
-	const image = options.image;
-	async function* entries() {
-		for await (const entry of sourceAdapter.listEntries(input, { tempDir: options.tempDir })) if (image && isImagePath(entry.path) && getExtension(entry.path) !== (image.format === "jpg" ? "jpg" : image.format)) {
-			const converted = await convertImageBuffer(await streamToBuffer(entry.openReadStream()), image.format, image.options);
-			yield {
-				path: replaceExtension(entry.path, image.format === "jpg" ? "jpg" : image.format),
-				size: converted.length,
-				content: Readable.from(converted)
-			};
-		} else yield {
-			path: entry.path,
-			size: entry.size,
-			content: entry.openReadStream()
-		};
-	}
-	return withOutput(options.output, (destination) => targetAdapter.write(entries(), destination, { tempDir: options.tempDir }));
-}
-//#endregion
-//#region src/extractArchive.ts
-/**
-* Extracts every entry in an archive to real files under `destDir`,
-* preserving relative paths (`destDir` is created if missing). Throws
-* `ArchiveFormatError` for an undetectable/unknown format, or
-* `UnsupportedOperationError` for ACE. Returns the archive-relative entry
-* paths that were written, in archive iteration order.
-*/
-async function extractArchive(input, destDir, options = {}) {
-	const adapter = getAdapter(await detectArchiveType(input));
-	await fs.promises.mkdir(destDir, { recursive: true });
-	const written = [];
-	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
-		const target = resolveSafeEntryPath(destDir, entry.path);
-		await fs.promises.mkdir(path.dirname(target), { recursive: true });
-		await pipeline(entry.openReadStream(), fs.createWriteStream(target));
-		written.push(entry.path);
-	}
-	return written;
-}
-//#endregion
 //#region src/removeArchiveEntry.ts
 async function removeArchiveEntry(input, entryPath, options = {}) {
 	const adapter = getAdapter(await detectArchiveType(input));
@@ -1928,6 +1887,72 @@ async function removeComicMetadata(input, schema, options = {}) {
 	throw new ArchiveFormatError(`Archive does not contain ${fileName}.`);
 }
 //#endregion
+//#region src/convertArchive.ts
+const METADATA_FILE_NAMES = /* @__PURE__ */ new Set(["ComicInfo.xml", "MetronInfo.xml"]);
+function replaceExtension(entryPath, format) {
+	return `${entryPath.replace(/\.[^./\\]+$/, "")}.${format}`;
+}
+async function convertArchive(input, targetType, options = {}) {
+	const sourceType = await detectArchiveType(input);
+	if (sourceType === "unknown") throw new ArchiveFormatError("Could not determine the source archive type.");
+	const sourceAdapter = getAdapter(sourceType);
+	const targetAdapter = getAdapter(targetType);
+	const image = options.image;
+	const metadata = options.metadata;
+	async function* entries() {
+		for await (const entry of sourceAdapter.listEntries(input, { tempDir: options.tempDir })) {
+			if (metadata && METADATA_FILE_NAMES.has(entry.path.split("/").pop() ?? "")) continue;
+			if (image && isImagePath(entry.path) && getExtension(entry.path) !== (image.format === "jpg" ? "jpg" : image.format)) {
+				const converted = await convertImageBuffer(await streamToBuffer(entry.openReadStream()), image.format, image.options);
+				yield {
+					path: replaceExtension(entry.path, image.format === "jpg" ? "jpg" : image.format),
+					size: converted.length,
+					content: Readable.from(converted)
+				};
+			} else yield {
+				path: entry.path,
+				size: entry.size,
+				content: entry.openReadStream()
+			};
+		}
+		if (metadata && targetType !== "asar") for (const schema of Object.keys(metadata)) {
+			const value = metadata[schema];
+			if (!value) continue;
+			const xml = Buffer.from(metadataToXml(value, schema), "utf8");
+			yield {
+				path: `${schema}.xml`,
+				size: xml.length,
+				content: Readable.from(xml)
+			};
+		}
+	}
+	return withOutput(options.output, (destination) => targetAdapter.write(entries(), destination, {
+		tempDir: options.tempDir,
+		...metadata && targetType === "asar" ? { comicMetadata: metadata } : {}
+	}));
+}
+//#endregion
+//#region src/extractArchive.ts
+/**
+* Extracts every entry in an archive to real files under `destDir`,
+* preserving relative paths (`destDir` is created if missing). Throws
+* `ArchiveFormatError` for an undetectable/unknown format, or
+* `UnsupportedOperationError` for ACE. Returns the archive-relative entry
+* paths that were written, in archive iteration order.
+*/
+async function extractArchive(input, destDir, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	await fs.promises.mkdir(destDir, { recursive: true });
+	const written = [];
+	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
+		const target = resolveSafeEntryPath(destDir, entry.path);
+		await fs.promises.mkdir(path.dirname(target), { recursive: true });
+		await pipeline(entry.openReadStream(), fs.createWriteStream(target));
+		written.push(entry.path);
+	}
+	return written;
+}
+//#endregion
 //#region src/images/phash.ts
 const HASH_SIZE = 32;
 const BLOCK_SIZE = 8;
@@ -1997,6 +2022,41 @@ async function computeArchiveImagePHash(input, entryPath) {
 	throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
 }
 //#endregion
+//#region src/images/dimensions.ts
+const BMP_HEADER_SIZE = 26;
+/** `sharp` can't read BMP, so read a BMP's dimensions straight from its `BITMAPINFOHEADER`. Height is negative for top-down bitmaps. */
+function readBmpInfo(buffer) {
+	if (buffer.length < BMP_HEADER_SIZE || buffer.toString("latin1", 0, 2) !== "BM") return null;
+	const width = buffer.readInt32LE(18);
+	const height = Math.abs(buffer.readInt32LE(22));
+	return width > 0 && height > 0 ? {
+		width,
+		height,
+		type: "bmp"
+	} : null;
+}
+/** Reads an image's format and pixel dimensions from its header without decoding it; `null` when the buffer isn't a readable image. */
+async function readImageInfo(buffer) {
+	try {
+		const { width, height, format } = await sharp(buffer).metadata();
+		return width !== void 0 && height !== void 0 ? {
+			width,
+			height,
+			type: format
+		} : null;
+	} catch {
+		return readBmpInfo(buffer);
+	}
+}
+/** Reads an image's pixel dimensions from its header without decoding it; `null` when the buffer isn't a readable image. */
+async function readImageDimensions(buffer) {
+	const info = await readImageInfo(buffer);
+	return info ? {
+		width: info.width,
+		height: info.height
+	} : null;
+}
+//#endregion
 //#region src/hashing/asarContent.ts
 /**
 * Locates the byte range of an asar archive's content region (everything
@@ -2151,6 +2211,30 @@ async function* readArchiveEntries(input) {
 	}
 }
 //#endregion
+//#region src/readArchiveImageInfo.ts
+/**
+* Returns the name, path, dimensions, and format of every image entry in an
+* archive, in archive iteration order. Image entries are identified by
+* extension (see `isImagePath`); non-image entries are skipped without being
+* read. Everything is gathered in a single pass over the archive.
+*/
+async function readArchiveImageInfo(input) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const images = [];
+	for await (const entry of adapter.listEntries(input)) {
+		if (!isImagePath(entry.path)) continue;
+		const info = await readImageInfo(await streamToBuffer(entry.openReadStream()));
+		images.push({
+			name: path.posix.basename(entry.path.replaceAll("\\", "/")),
+			path: entry.path,
+			width: info?.width ?? null,
+			height: info?.height ?? null,
+			type: info?.type ?? null
+		});
+	}
+	return images;
+}
+//#endregion
 //#region src/benchmark/timing.ts
 /** Runs `run` `iterations` times and returns the average duration in milliseconds. */
 async function averageDuration(iterations, run) {
@@ -2389,6 +2473,8 @@ const comicArchiveHandler = {
 	hammingDistance,
 	IMAGE_EXTENSIONS,
 	isImagePath,
+	readImageDimensions,
+	readImageInfo,
 	sha256ArchiveEntry,
 	sha256Archive,
 	renameArchiveImagesSequentially,
@@ -2396,6 +2482,7 @@ const comicArchiveHandler = {
 	listArchiveFiles,
 	readArchiveEntry,
 	readArchiveEntries,
+	readArchiveImageInfo,
 	removeArchiveEntry,
 	benchmarkArchive,
 	renderBenchmarkReportMarkdown,
@@ -2404,6 +2491,6 @@ const comicArchiveHandler = {
 	ARCHIVE_TYPE_EXTENSIONS
 };
 //#endregion
-export { ARCHIVE_TYPE_EXTENSIONS, ArchiveFormatError, BENCHMARK_IMAGE_FORMATS, COMIC_INFO_AGE_RATING_VALUES, COMIC_INFO_CREDIT_ROLES, COMIC_INFO_MANGA_VALUES, COMIC_INFO_PAGE_TYPE_VALUES, COMIC_INFO_YES_NO_VALUES, FilesystemAccessError, IMAGE_EXTENSIONS, METRON_AGE_RATING_VALUES, METRON_FORMAT_VALUES, METRON_INFORMATION_SOURCE_VALUES, METRON_ROLE_VALUES, MetadataNotFoundError, NoImagesFoundError, SevenZipUnavailableError, UnsupportedOperationError, WRITABLE_ARCHIVE_TYPES, addMetadataToArchive, benchmarkArchive, comicInfoXmlToMetadata, computeArchiveImagePHash, computeImagePHash, convertArchive, convertArchiveImages, convertImageBuffer, comicArchiveHandler as default, detectArchiveType, extractArchive, getExtension, hammingDistance, hasComicMetadata, is7z, isAce, isAsar, isImagePath, isRar, isTar, isZip, joinCommaList, joinResourceNames, listArchiveFiles, metadataToComicInfoXml, metadataToMetronInfoXml, metadataToXml, metronInfoXmlToMetadata, phashToHex, readArchiveEntries, readArchiveEntry, readArchiveMetadata, removeArchiveEntry, removeComicMetadata, renameArchiveImagesSequentially, renderBenchmarkReportMarkdown, resourceId, resourceName, sha256Archive, sha256ArchiveEntry, splitCommaList, stripNonEssentialFiles, validateMetadataXml, xmlToMetadata };
+export { ARCHIVE_TYPE_EXTENSIONS, ArchiveFormatError, BENCHMARK_IMAGE_FORMATS, COMIC_INFO_AGE_RATING_VALUES, COMIC_INFO_CREDIT_ROLES, COMIC_INFO_MANGA_VALUES, COMIC_INFO_PAGE_TYPE_VALUES, COMIC_INFO_YES_NO_VALUES, FilesystemAccessError, IMAGE_EXTENSIONS, METRON_AGE_RATING_VALUES, METRON_FORMAT_VALUES, METRON_INFORMATION_SOURCE_VALUES, METRON_ROLE_VALUES, MetadataNotFoundError, NoImagesFoundError, SevenZipUnavailableError, UnsupportedOperationError, WRITABLE_ARCHIVE_TYPES, addMetadataToArchive, benchmarkArchive, comicInfoXmlToMetadata, computeArchiveImagePHash, computeImagePHash, convertArchive, convertArchiveImages, convertImageBuffer, comicArchiveHandler as default, detectArchiveType, extractArchive, getExtension, hammingDistance, hasComicMetadata, is7z, isAce, isAsar, isImagePath, isRar, isTar, isZip, joinCommaList, joinResourceNames, listArchiveFiles, metadataToComicInfoXml, metadataToMetronInfoXml, metadataToXml, metronInfoXmlToMetadata, phashToHex, readArchiveEntries, readArchiveEntry, readArchiveImageInfo, readArchiveMetadata, readImageDimensions, readImageInfo, removeArchiveEntry, removeComicMetadata, renameArchiveImagesSequentially, renderBenchmarkReportMarkdown, resourceId, resourceName, sha256Archive, sha256ArchiveEntry, splitCommaList, stripNonEssentialFiles, validateMetadataXml, xmlToMetadata };
 
 //# sourceMappingURL=index.mjs.map