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

package/docs/API.md

@@ -58,6 +58,7 @@ Converts an archive to `zip`, `rar`, `tar`, `asar`, or `7z`. Entries are copied
 - `options.image?: { format: ImageOutputFormat; options?: ImageConvertOptions }` - Re-encode image entries while converting the archive.
 - `options.image.format` - `'webp'`, `'jpg'`, or `'png'`.
 - `options.image.options` - Image format options described under [`convertImageBuffer`](#convertimagebuffer).
+- `options.metadata?: Partial<Record<MetadataSchema, ComicMetadata>>` - Replaces the source's embedded comic metadata. The source's `ComicInfo.xml`/`MetronInfo.xml` entries are dropped (an ASAR source's header metadata is never copied), then each given schema is written as an ASAR header key when the target is `asar`, or as a root-level `ComicInfo.xml`/`MetronInfo.xml` entry otherwise. Without it, an ASAR source's header metadata is not carried into the output.
 
 **Example**
 
@@ -68,6 +69,10 @@ const output = await convertArchive('/books/example.cbr', 'zip', {
   output: '/books/example.cbz',
   image: { format: 'webp', options: { webp: { quality: 92 } } },
 });
+
+// Move a ComicInfo.xml entry into the ASAR header
+const { metadata } = await readArchiveMetadata('/books/example.cbz', 'ComicInfo');
+await convertArchive('/books/example.cbz', 'asar', { output: '/books/example.cbas', metadata: { ComicInfo: metadata } });
 ```
 
 ### `listArchiveFiles(input)`
@@ -116,6 +121,21 @@ for await (const entry of cah.readArchiveEntries(comicBuffer)) {
 }
 ```
 
+### `readArchiveImageInfo(input)`
+
+Returns `{ name, path, width, height, type }` for every image entry in an archive, in archive iteration order. Image entries are identified by extension (see `isImagePath`), and non-image entries are skipped without being read. `name` is the file name without its directory, and `type` is the format detected from the entry's contents rather than its extension (`jpeg`, `png`, `gif`, `webp`, `tiff`, `bmp`, and so on). When an entry's contents are not a readable image, `width`, `height`, and `type` are `null`.
+
+**Options**
+
+- `input: ArchiveInput` - A filesystem path or archive `Buffer`.
+
+**Example**
+
+```js
+const images = await cah.readArchiveImageInfo(comicBuffer);
+console.log(images[0]); // { name: 'P00001.jpg', path: 'pages/P00001.jpg', width: 1988, height: 3056, type: 'jpeg' }
+```
+
 ### `renameArchiveImagesSequentially(input, options?)`
 
 Renames image entries in natural-sort order to `P#####.<extension>`, while leaving other entries unchanged.
@@ -485,6 +505,34 @@ Returns whether an archive entry path has an extension in `IMAGE_EXTENSIONS`.
 if (cah.isImagePath('P00001.jpg')) console.log('page image');
 ```
 
+### `readImageInfo(image)`
+
+Reads an image's format and pixel dimensions from its header without decoding it, returning `{ width, height, type }`. Returns `null` when the buffer is not a readable image.
+
+**Options**
+
+- `image: Buffer` - Image bytes.
+
+**Example**
+
+```js
+const info = await cah.readImageInfo(imageBytes); // { width: 1988, height: 3056, type: 'jpeg' }
+```
+
+### `readImageDimensions(image)`
+
+Like `readImageInfo`, but returns only `{ width, height }`.
+
+**Options**
+
+- `image: Buffer` - Image bytes.
+
+**Example**
+
+```js
+const { width, height } = await cah.readImageDimensions(imageBytes);
+```
+
 ## Perceptual hashing
 
 ### `computeImagePHash(image)`
@@ -672,6 +720,9 @@ The following types are exported for TypeScript consumers.
 - `MetadataValidationResult` - `{ valid: boolean; issues: MetadataValidationIssue[] }`, returned by `validateMetadataXml`.
 - `MetadataValidationIssue` - `{ message: string; line?: number }`.
 - `ExtractArchiveOptions` - `{ tempDir?: string }`.
+- `ArchiveImageInfo` - `{ name, path, width, height, type }`, returned by `readArchiveImageInfo`. `width`, `height`, and `type` are `null` for unreadable images.
+- `ImageDimensions` - `{ width: number; height: number }`.
+- `ImageInfo` - `ImageDimensions & { type: string }`, returned by `readImageInfo`.
 - `WritableArchiveType` - `'zip' | 'tar' | 'asar' | '7z'`.
 - `BenchmarkArchiveOptions` - `{ tempDir?, reportsDir?, creationIterations?, seekSamples?, imageFormats?, image? }`; see [`benchmarkArchive`](#benchmarkarchivefilepath-options).
 - `BenchmarkVariantResult` - One generated variant's stats: `{ archiveType, imageFormat, fileName, filePath, fileSizeBytes, pageCount, avgImageSizeBytes, avgCreationMs, avgSeekMs }`. `avgImageSizeBytes` (average size of one converted page) depends only on `imageFormat`, not `archiveType`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearmist-labs/comic-archive-handler",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Detect, convert, and manipulate comic book archives: container conversion, edit metadata, image re-encoding, perceptual + content hashing.",
   "keywords": [
     "7z",