@clearmist-labs/comic-archive-handler 1.5.0 → 1.7.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.image.concurrency?: number | (() => number)` - How many images to convert at once. Defaults to `1`. A function is called again before each conversion starts, so the limit can follow the caller's load while the archive is converted. Entry order in the output is unchanged. See [`setImageConcurrency`](#setimageconcurrencythreads) for how this interacts with libuv's threadpool.
 - `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**
@@ -121,6 +122,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.
@@ -438,6 +454,7 @@ Re-encodes image entries in an archive and updates their extensions. Non-image e
 - `options.webp`, `options.jpeg`, `options.png` - Format-specific options listed under [`convertImageBuffer`](#convertimagebuffer).
 - `options.tempDir?: string` - Temporary staging directory for ASAR or 7z operations.
 - `options.output?: string | Writable` - Output destination. Without it, returns a `Buffer`.
+- `options.concurrency?: number | (() => number)` - How many images to convert at once, as for `convertArchive`'s `options.image.concurrency`. Defaults to `1`.
 
 **Example**
 
@@ -448,6 +465,22 @@ const webpArchive = await cah.convertArchiveImages(comicBuffer, 'webp', {
 });
 ```
 
+### `setImageConcurrency(threads)`
+
+Sets how many libvips threads process each image and returns the value now in effect. The setting is process-wide and covers every image operation in this package. When you already parallelize across images (for example one worker thread per core), pass `1` so each image doesn't also fan out across every core. sharp's default is the CPU core count, except on glibc Linux without jemalloc, where it is already `1`.
+
+Image work runs on libuv's threadpool, which is shared by every worker thread in the process and defaults to 4 threads. To run more than 4 images at once, raise `UV_THREADPOOL_SIZE` before the process first uses the threadpool. Each image in flight (for example each of `convertArchive`'s `options.image.concurrency` conversions) holds one threadpool thread until it finishes, and a single image uses up to `threads` libvips threads on top of that.
+
+**Options**
+
+- `threads: number` - libvips threads per image.
+
+**Example**
+
+```js
+cah.setImageConcurrency(1);
+```
+
 ### `IMAGE_EXTENSIONS`
 
 Readonly list of recognized image extensions: `jpg`, `jpeg`, `png`, `gif`, `webp`, `bmp`, `tiff`, and `tif`.
@@ -490,6 +523,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)`
@@ -677,6 +738,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.5.0",
+  "version": "1.7.0",
   "description": "Detect, convert, and manipulate comic book archives: container conversion, edit metadata, image re-encoding, perceptual + content hashing.",
   "keywords": [
     "7z",