@clearmist-labs/comic-archive-handler 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,584 @@
+import { Writable } from "node:stream";
+//#region src/types.d.ts
+export type ArchiveType = 'zip' | 'rar' | 'tar' | 'asar' | '7z' | 'ace' | 'unknown';
+/** A Buffer of the archive's full bytes, or a filesystem path to it. */
+export type ArchiveInput = Buffer | string;
+export type MetadataSchema = 'ComicInfo' | 'MetronInfo';
+export type ImageOutputFormat = 'webp' | 'jpg' | 'png';
+export interface WebpOptions {
+  /** Default 92. */
+  quality?: number;
+  /** libwebp's `-m` compression method (0-6). Default 6. */
+  effort?: number;
+  /** libwebp's `-sharp_yuv`. Default true. */
+  smartSubsample?: boolean;
+}
+export interface JpegOptions {
+  /** Default 90. */
+  quality?: number;
+}
+export interface PngOptions {
+  /** Only has an effect when `palette` is true. */
+  quality?: number;
+  /** Zlib compression level (0-9). */
+  compressionLevel?: number;
+  /** Enables lossy palette quantization (required for `quality` to matter). */
+  palette?: boolean;
+}
+export interface ImageConvertOptions {
+  webp?: WebpOptions;
+  jpeg?: JpegOptions;
+  png?: PngOptions;
+}
+/** Shared by every archive-producing operation. */
+export interface ArchiveWriteOptions {
+  /**
+   * Directory to stage temporary files in when the source or target format
+   * requires real filesystem access (asar writes, any 7z operation).
+   * Defaults to a fresh directory under `os.tmpdir()`. If that isn't
+   * writable and no override is given, a FilesystemAccessError is thrown.
+   */
+  tempDir?: string;
+  /**
+   * When given, the result is streamed directly here and the function
+   * resolves `Promise<void>` instead of collecting a final Buffer.
+   */
+  output?: string | Writable;
+}
+export interface ConvertArchiveOptions extends ArchiveWriteOptions {
+  image?: {
+    format: ImageOutputFormat;
+    options?: ImageConvertOptions;
+  };
+}
+export interface AddMetadataOptions extends ArchiveWriteOptions {
+  overwrite?: boolean;
+}
+export interface RenameOptions extends ArchiveWriteOptions {
+  start?: number;
+  pad?: number;
+}
+export interface StripOptions extends ArchiveWriteOptions {
+  extraKeepExtensions?: string[];
+}
+export interface ComicCredit {
+  name: string;
+  role: string;
+  /** MetronInfo Credits > Credit > Creator `id` attribute. */
+  creatorId?: string;
+  /** MetronInfo Credits > Credit > Roles > Role `id` attribute for this role. */
+  roleId?: string;
+}
+export interface ComicStoryArc {
+  name: string;
+  number?: number;
+  /** MetronInfo Arcs > Arc `id` attribute. */
+  id?: string;
+}
+export interface ComicPage {
+  index: number;
+  type?: string;
+  doublePage?: boolean;
+  imageSize?: number;
+  imageWidth?: number;
+  imageHeight?: number;
+  key?: string;
+  bookmark?: string;
+}
+export interface ComicDate {
+  year?: number;
+  month?: number;
+  day?: number;
+}
+/**
+ * MetronInfo represents most list values (Genre, Tag, Character, Team,
+ * Location, Reprint, Story, Publisher > Imprint) as an element with a
+ * required text value and an optional `id` attribute linking it back to
+ * Metron's database. Plain strings are accepted anywhere this type is
+ * expected and are written without an `id` attribute.
+ */
+export interface MetronResource {
+  name: string;
+  id?: string;
+}
+export interface ComicAlternativeName extends MetronResource {
+  /** Two-letter language code. Defaults to "en" per the schema. */
+  lang?: string;
+}
+export interface ComicUniverse {
+  name: string;
+  designation?: string;
+  id?: string;
+}
+export interface ComicPrice {
+  amount: number;
+  /** Two-letter ISO country code. */
+  country: string;
+}
+export interface ComicUrl {
+  url: string;
+  primary?: boolean;
+}
+/** MetronInfo IDS > ID: a link to an external database record. */
+export interface ComicIdentifier {
+  source: string;
+  value: string;
+  primary?: boolean;
+}
+/**
+ * Canonical metadata shape: a superset/union of ComicInfo.xml and
+ * MetronInfo.xml fields. Conversion to either schema is intentionally lossy
+ * for fields the target schema has no equivalent for; see
+ * src/metadata/schema.ts for the authoritative field-mapping table.
+ */
+export interface ComicMetadata {
+  title?: string;
+  series?: string;
+  seriesSort?: string;
+  volume?: string;
+  number?: string;
+  /** Shared: ComicInfo `AlternateNumber` <-> MetronInfo `AlternativeNumber`. */
+  alternateNumber?: string;
+  count?: number;
+  pageCount?: number;
+  summary?: string;
+  notes?: string;
+  publisher?: string;
+  imprint?: string;
+  format?: string;
+  language?: string;
+  ageRating?: string;
+  communityRating?: number;
+  coverDate?: ComicDate;
+  storeDate?: ComicDate;
+  genres?: (string | MetronResource)[];
+  tags?: (string | MetronResource)[];
+  characters?: (string | MetronResource)[];
+  teams?: (string | MetronResource)[];
+  locations?: (string | MetronResource)[];
+  storyArcs?: ComicStoryArc[];
+  credits?: ComicCredit[];
+  web?: (string | ComicUrl)[];
+  /** ComicInfo `GTIN`, or MetronInfo `GTIN > ISBN`. */
+  gtin?: string;
+  /** MetronInfo `GTIN > UPC`. MetronInfo allows ISBN and UPC to coexist. */
+  gtinUpc?: string;
+  /** ComicInfo-only. */
+  blackAndWhite?: boolean;
+  /** ComicInfo-only. */
+  manga?: string;
+  pages?: ComicPage[];
+  /** ComicInfo-only: a series this issue is an alternate printing/edition of. */
+  alternateSeries?: string;
+  /** ComicInfo-only: issue count for `alternateSeries`. */
+  alternateCount?: number;
+  /** ComicInfo-only: scanning/rip group notes. */
+  scanInformation?: string;
+  /** ComicInfo-only: umbrella grouping across a series (e.g. a crossover event). */
+  seriesGroup?: string;
+  /** ComicInfo-only. */
+  mainCharacterOrTeam?: string;
+  /** ComicInfo-only: reviewer notes/text. */
+  review?: string;
+  /** MetronInfo-only: external database links (Comic Vine, Metron, etc). */
+  identifiers?: ComicIdentifier[];
+  /** MetronInfo Publisher `id` attribute. */
+  publisherId?: string;
+  /** MetronInfo Publisher > Imprint `id` attribute. */
+  imprintId?: string;
+  /** MetronInfo Series `id` attribute. */
+  seriesId?: string;
+  /** MetronInfo Series `lang` attribute. Defaults to "en" per the schema. */
+  seriesLang?: string;
+  /** MetronInfo Series > StartYear. */
+  seriesStartYear?: number;
+  /** MetronInfo Series > IssueCount. */
+  seriesIssueCount?: number;
+  /** MetronInfo Series > VolumeCount. */
+  seriesVolumeCount?: number;
+  /** MetronInfo Series > AlternativeNames. */
+  seriesAlternativeNames?: ComicAlternativeName[];
+  /** MetronInfo-only: volume label used for manga. */
+  mangaVolume?: string;
+  /** MetronInfo-only. */
+  collectionTitle?: string;
+  /** MetronInfo-only: story titles collected in this issue. */
+  stories?: (string | MetronResource)[];
+  /** MetronInfo-only. */
+  prices?: ComicPrice[];
+  /** MetronInfo-only: other issues this one reprints. */
+  reprints?: (string | MetronResource)[];
+  /** MetronInfo-only. */
+  universes?: ComicUniverse[];
+  /** MetronInfo CommunityRating > RatingCount (pairs with `communityRating` as the average). */
+  communityRatingCount?: number;
+  /** MetronInfo-only, ISO 8601 datetime string. */
+  lastModified?: string;
+  /** Round-trip escape hatch: original ComicInfo-only fields, kept only when source and target schema are the same. */
+  comicInfoExtra?: Record<string, unknown>;
+  /** Round-trip escape hatch: original MetronInfo-only fields, kept only when source and target schema are the same. */
+  metronInfoExtra?: Record<string, unknown>;
+}
+//#endregion
+//#region src/benchmark/types.d.ts
+/** Archive container formats that can actually be written (excludes 'rar', 'ace', and 'unknown'). */
+type WritableArchiveType = Extract<ArchiveType, 'zip' | 'tar' | 'asar' | '7z'>;
+export declare const WRITABLE_ARCHIVE_TYPES: readonly WritableArchiveType[];
+export declare const BENCHMARK_IMAGE_FORMATS: readonly ImageOutputFormat[];
+/** Conventional comic archive extension for each writable container format. */
+export declare const ARCHIVE_TYPE_EXTENSIONS: Record<WritableArchiveType, string>;
+interface BenchmarkArchiveOptions {
+  /** Staging directory for extraction and any asar/7z operations. Defaults to a fresh directory under the OS temp dir. */
+  tempDir?: string;
+  /** Directory the dated report subdirectory is created under. Defaults to "./reports" (relative to `process.cwd()`). */
+  reportsDir?: string;
+  /** Number of timed archive-creation runs to average per variant. Defaults to 3, minimum 1. */
+  creationIterations?: number;
+  /** Number of random single-entry reads to average per variant. Defaults to 10, minimum 1. */
+  seekSamples?: number;
+  /** Image formats to benchmark. Defaults to all of `BENCHMARK_IMAGE_FORMATS` (webp, png, jpg). Must be non-empty. */
+  imageFormats?: ImageOutputFormat[];
+  /** Image encode options applied uniformly across every generated variant. */
+  image?: ImageConvertOptions;
+}
+interface BenchmarkVariantResult {
+  archiveType: WritableArchiveType;
+  imageFormat: ImageOutputFormat;
+  fileName: string;
+  filePath: string;
+  fileSizeBytes: number;
+  pageCount: number;
+  /** Average size of one image entry after conversion, in bytes. Independent of container choice for a given image format. */
+  avgImageSizeBytes: number;
+  /** Average wall-clock time to create this archive, in milliseconds. */
+  avgCreationMs: number;
+  /** Average wall-clock time to read one random image entry, in milliseconds. */
+  avgSeekMs: number;
+}
+interface BenchmarkArchiveResult {
+  sourcePath: string;
+  /** ISO 8601 timestamp of when the benchmark run started. */
+  generatedAt: string;
+  reportDir: string;
+  reportPath: string;
+  /** Every entry from the source archive, extracted here for inspection. */
+  sourceDir: string;
+  archivesDir: string;
+  variants: BenchmarkVariantResult[];
+}
+//#endregion
+//#region src/errors.d.ts
+export declare class UnsupportedOperationError extends Error {
+  constructor(message: string);
+}
+export declare class ArchiveFormatError extends Error {
+  constructor(message: string);
+}
+export declare class MetadataNotFoundError extends Error {
+  constructor(message: string);
+}
+export declare class FilesystemAccessError extends Error {
+  constructor(message: string);
+}
+export declare class SevenZipUnavailableError extends Error {
+  constructor(message: string);
+}
+export declare class NoImagesFoundError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/detect.d.ts
+export declare function detectArchiveType(input: ArchiveInput): Promise<ArchiveType>;
+export declare function isZip(input: ArchiveInput): Promise<boolean>;
+export declare function isRar(input: ArchiveInput): Promise<boolean>;
+export declare function isTar(input: ArchiveInput): Promise<boolean>;
+export declare function isAsar(input: ArchiveInput): Promise<boolean>;
+export declare function is7z(input: ArchiveInput): Promise<boolean>;
+export declare function isAce(input: ArchiveInput): Promise<boolean>;
+//#endregion
+//#region src/convertArchive.d.ts
+export declare function convertArchive(input: ArchiveInput, targetType: Exclude<ArchiveType, 'unknown'>, options?: ConvertArchiveOptions): Promise<Buffer | void>;
+//#endregion
+//#region src/extractArchive.d.ts
+export interface ExtractArchiveOptions {
+  /** Temporary staging directory for archive formats that require real files to read (7z). */
+  tempDir?: string;
+}
+/**
+ * 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.
+ */
+export declare function extractArchive(input: ArchiveInput, destDir: string, options?: ExtractArchiveOptions): Promise<string[]>;
+//#endregion
+//#region src/metadata/comicInfo.d.ts
+export declare function metadataToComicInfoXml(metadata: ComicMetadata): string;
+export declare function comicInfoXmlToMetadata(xml: string | Buffer): ComicMetadata;
+//#endregion
+//#region src/metadata/metronInfo.d.ts
+export declare function metadataToMetronInfoXml(metadata: ComicMetadata): string;
+export declare function metronInfoXmlToMetadata(xml: string | Buffer): ComicMetadata;
+//#endregion
+//#region src/metadata/validate.d.ts
+interface MetadataValidationIssue {
+  message: string;
+  line?: number;
+}
+interface MetadataValidationResult {
+  valid: boolean;
+  issues: MetadataValidationIssue[];
+}
+/**
+ * Validates an XML document against the bundled ComicInfo.xml or
+ * MetronInfo.xml XSD. Returns `{ valid: true, issues: [] }` when the
+ * document conforms, or `{ valid: false, issues }` with one entry per
+ * schema violation (element/attribute name and line number, where
+ * available) otherwise.
+ */
+export declare function validateMetadataXml(xml: string | Buffer, schema: MetadataSchema): Promise<MetadataValidationResult>;
+//#endregion
+//#region src/metadata/schema.d.ts
+/**
+ * Authoritative field-mapping table between the canonical ComicMetadata
+ * shape and each external XML schema (ComicInfo.xml v2.1, MetronInfo.xml
+ * v1.1 — see `schemas/`). Conversion is intentionally lossy in both
+ * directions; a field with no equivalent in the target schema is dropped
+ * unless the source and target schema happen to be the same one (in which
+ * case `comicInfoExtra`/`metronInfoExtra` round-trips it).
+ *
+ * | Canonical field         | ComicInfo.xml                                      | MetronInfo.xml                                |
+ * |-------------------------|-----------------------------------------------------|------------------------------------------------|
+ * | title                   | Title                                               | (no equivalent — dropped)                       |
+ * | series                  | Series                                              | Series > Name                                   |
+ * | seriesSort              | (no equivalent)                                     | Series > SortName                               |
+ * | seriesId / seriesLang   | (no equivalent)                                     | Series `id`/`lang` attributes                   |
+ * | seriesStartYear         | (no equivalent)                                     | Series > StartYear                              |
+ * | seriesIssueCount        | (no equivalent)                                     | Series > IssueCount                             |
+ * | seriesVolumeCount       | (no equivalent)                                     | Series > VolumeCount                            |
+ * | seriesAlternativeNames  | (no equivalent)                                     | Series > AlternativeNames > AlternativeName[]   |
+ * | seriesGroup             | SeriesGroup                                         | (no equivalent — dropped)                       |
+ * | volume                  | Volume                                              | Series > Volume                                 |
+ * | number                  | Number                                              | Number                                          |
+ * | alternateNumber         | AlternateNumber                                     | AlternativeNumber                               |
+ * | alternateSeries         | AlternateSeries                                     | (no equivalent — dropped)                       |
+ * | alternateCount          | AlternateCount                                      | (no equivalent — dropped)                       |
+ * | count                   | Count                                               | (no equivalent)                                 |
+ * | pageCount               | PageCount                                           | PageCount                                       |
+ * | summary                 | Summary                                             | Summary                                         |
+ * | notes                   | Notes                                               | Notes                                           |
+ * | review                  | Review                                              | (no equivalent — dropped)                       |
+ * | scanInformation         | ScanInformation                                     | (no equivalent — dropped)                       |
+ * | publisher / publisherId | Publisher                                           | Publisher > Name / `id` attribute               |
+ * | imprint / imprintId     | Imprint                                             | Publisher > Imprint / `id` attribute            |
+ * | collectionTitle         | (no equivalent)                                     | CollectionTitle                                 |
+ * | mangaVolume             | (no equivalent)                                     | MangaVolume                                     |
+ * | format                  | Format                                              | Series > Format                                 |
+ * | language                | LanguageISO                                         | (no equivalent)                                 |
+ * | ageRating               | AgeRating                                           | AgeRating                                       |
+ * | communityRating(Count)  | CommunityRating                                     | CommunityRating > AverageRating / RatingCount   |
+ * | coverDate               | Year / Month / Day                                  | CoverDate (YYYY-MM-DD)                          |
+ * | storeDate               | (no equivalent)                                     | StoreDate (YYYY-MM-DD)                          |
+ * | lastModified            | (no equivalent)                                     | LastModified                                    |
+ * | genres                  | Genre (comma-separated string)                      | Genres > Genre[] (`id` attribute preserved)     |
+ * | tags                    | Tags (comma-separated string)                       | Tags > Tag[] (`id` attribute preserved)         |
+ * | characters              | Characters (comma-separated string)                 | Characters > Character[] (`id` attribute)       |
+ * | teams                   | Teams (comma-separated string)                      | Teams > Team[] (`id` attribute)                 |
+ * | locations               | Locations (comma-separated string)                  | Locations > Location[] (`id` attribute)         |
+ * | storyArcs               | StoryArc / StoryArcNumber (parallel comma lists)    | Arcs > Arc[] (Name + Number + `id`)             |
+ * | mainCharacterOrTeam     | MainCharacterOrTeam                                 | (no equivalent — dropped)                       |
+ * | stories                 | (no equivalent)                                     | Stories > Story[]                               |
+ * | reprints                | (no equivalent)                                     | Reprints > Reprint[]                            |
+ * | universes               | (no equivalent)                                     | Universes > Universe[]                          |
+ * | identifiers             | (no equivalent)                                     | IDS > ID[]                                      |
+ * | prices                  | (no equivalent)                                     | Prices > Price[]                                |
+ * | credits                 | Writer/Penciller/Inker/Colorist/Letterer/CoverArtist/Editor/Translator (comma-separated per role) | Credits > Credit[] (Creator + Roles > Role[], `id` attributes) |
+ * | web                     | Web (single URL)                                    | URLs > URL[] (`primary` attribute)              |
+ * | gtin                    | GTIN                                                | GTIN > ISBN                                     |
+ * | gtinUpc                 | (no equivalent)                                     | GTIN > UPC                                      |
+ * | blackAndWhite           | BlackAndWhite (Yes/No)                              | (no equivalent — ComicInfo-only)                |
+ * | manga                   | Manga                                               | (no equivalent — ComicInfo-only)                |
+ * | pages                   | Pages > Page[] (Image/Type/DoublePage/... attrs)    | (no equivalent — ComicInfo-only)                |
+ */
+export declare const COMIC_INFO_CREDIT_ROLES: readonly ["Writer", "Penciller", "Inker", "Colorist", "Letterer", "CoverArtist", "Editor", "Translator"];
+type ComicInfoCreditRole = (typeof COMIC_INFO_CREDIT_ROLES)[number];
+/** ComicInfo.xml `YesNo` simple type. */
+export declare const COMIC_INFO_YES_NO_VALUES: readonly ["Unknown", "No", "Yes"];
+/** ComicInfo.xml `Manga` simple type. */
+export declare const COMIC_INFO_MANGA_VALUES: readonly ["Unknown", "No", "Yes", "YesAndRightToLeft"];
+/** ComicInfo.xml `AgeRating` simple type. */
+export declare const COMIC_INFO_AGE_RATING_VALUES: readonly ["Unknown", "Adults Only 18+", "Early Childhood", "Everyone", "Everyone 10+", "G", "Kids to Adults", "M", "MA15+", "Mature 17+", "PG", "R18+", "Rating Pending", "Teen", "X18+"];
+/** ComicInfo.xml `ComicPageType` simple type. */
+export declare const COMIC_INFO_PAGE_TYPE_VALUES: readonly ["FrontCover", "InnerCover", "Roundup", "Story", "Advertisement", "Editorial", "Letters", "Preview", "BackCover", "Other", "Deleted"];
+/** MetronInfo.xml `formatType` simple type (Series > Format). */
+export declare const METRON_FORMAT_VALUES: readonly ["Annual", "Digital Chapter", "Graphic Novel", "Hardcover", "Limited Series", "Omnibus", "One-Shot", "Single Issue", "Trade Paperback"];
+/** MetronInfo.xml `informationSource` simple type (IDS > ID `source` attribute). */
+export declare const METRON_INFORMATION_SOURCE_VALUES: readonly ["AniList", "Comic Vine", "Grand Comics Database", "Kitsu", "MangaDex", "MangaUpdates", "Marvel", "Metron", "MyAnimeList", "League of Comic Geeks"];
+/** MetronInfo.xml `roleValues` simple type (Credits > Credit > Roles > Role). */
+export declare const METRON_ROLE_VALUES: readonly ["Writer", "Script", "Story", "Plot", "Interviewer", "Artist", "Penciller", "Breakdowns", "Illustrator", "Layouts", "Inker", "Embellisher", "Finishes", "Ink Assists", "Colorist", "Color Separations", "Color Assists", "Color Flats", "Digital Art Technician", "Gray Tone", "Letterer", "Cover", "Editor", "Consulting Editor", "Assistant Editor", "Associate Editor", "Group Editor", "Senior Editor", "Managing Editor", "Collection Editor", "Production", "Designer", "Logo Design", "Translator", "Supervising Editor", "Executive Editor", "Editor In Chief", "President", "Publisher", "Chief Creative Officer", "Executive Producer", "Other"];
+/** MetronInfo.xml `ageRatingType` simple type. */
+export declare const METRON_AGE_RATING_VALUES: readonly ["Unknown", "Everyone", "Teen", "Teen Plus", "Mature", "Explicit", "Adult"];
+export declare function splitCommaList(value?: string): string[] | undefined;
+export declare function joinCommaList(values?: string[]): string | undefined;
+/** Extracts the plain text value from a resource that may carry a MetronInfo `id` attribute. */
+export declare function resourceName(item: string | MetronResource): string;
+/** Extracts the MetronInfo `id` attribute from a resource, if any. */
+export declare function resourceId(item: string | MetronResource): string | undefined;
+export declare function joinResourceNames(values?: (string | MetronResource)[]): string | undefined;
+declare namespace index_d_exports {
+  export { COMIC_INFO_AGE_RATING_VALUES, COMIC_INFO_CREDIT_ROLES, COMIC_INFO_MANGA_VALUES, COMIC_INFO_PAGE_TYPE_VALUES, COMIC_INFO_YES_NO_VALUES, ComicInfoCreditRole, METRON_AGE_RATING_VALUES, METRON_FORMAT_VALUES, METRON_INFORMATION_SOURCE_VALUES, METRON_ROLE_VALUES, MetadataValidationIssue, MetadataValidationResult, addMetadataToArchive, comicInfoXmlToMetadata, hasComicMetadata, joinCommaList, joinResourceNames, metadataToComicInfoXml, metadataToMetronInfoXml, metadataToXml, metronInfoXmlToMetadata, readArchiveMetadata, resourceId, resourceName, splitCommaList, validateMetadataXml, xmlToMetadata };
+}
+export declare function metadataToXml(metadata: ComicMetadata, schema: MetadataSchema): string;
+export declare function xmlToMetadata(xml: string | Buffer, schema: MetadataSchema): ComicMetadata;
+export declare function hasComicMetadata(input: ArchiveInput): Promise<{
+  present: boolean;
+  schema?: MetadataSchema;
+  path?: string;
+}>;
+export declare function readArchiveMetadata(input: ArchiveInput): Promise<{
+  schema: MetadataSchema;
+  metadata: ComicMetadata;
+} | null>;
+export declare function addMetadataToArchive(input: ArchiveInput, metadata: ComicMetadata, schema: MetadataSchema, options?: AddMetadataOptions): Promise<Buffer | void>;
+//#endregion
+//#region src/images/convert.d.ts
+export declare function convertImageBuffer(image: Buffer, format: ImageOutputFormat, options?: ImageConvertOptions): Promise<Buffer>;
+export declare function convertArchiveImages(input: ArchiveInput, format: ImageOutputFormat, options?: ImageConvertOptions & ArchiveWriteOptions): Promise<Buffer | void>;
+//#endregion
+//#region src/images/phash.d.ts
+/**
+ * Standard 8x8 DCT perceptual hash: resize to 32x32 greyscale, run a 2D
+ * DCT-II, threshold the top-left 8x8 block against the median of that block
+ * (excluding the DC term at [0][0] from the median calculation, though it is
+ * still included positionally as bit 0). Returned as a bigint since JS
+ * `Number` cannot losslessly represent all 64-bit patterns.
+ */
+export declare function computeImagePHash(image: Buffer): Promise<bigint>;
+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/isImage.d.ts
+export declare const IMAGE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp", "bmp", "tiff", "tif"];
+export declare function getExtension(entryPath: string): string;
+export declare function isImagePath(entryPath: string): boolean;
+//#endregion
+//#region src/hashing/sha256.d.ts
+export declare function sha256ArchiveEntry(input: ArchiveInput, entryPath: string): Promise<string>;
+/**
+ * SHA256 of the whole archive file — except for asar, where only the
+ * content region (bytes after the header) is hashed, so header/index
+ * reordering never changes the content hash.
+ */
+export declare function sha256Archive(input: ArchiveInput): Promise<string>;
+//#endregion
+//#region src/rename.d.ts
+/**
+ * Renames image entries to the standard `P#####` pattern in natural sort
+ * order of their current names, leaving non-image entries (like
+ * ComicInfo.xml/MetronInfo.xml) untouched.
+ *
+ * This requires two passes over the archive: `listEntries` is called once to
+ * collect image paths (metadata only — no content is read, so no
+ * decompression work is wasted) to compute the sort-order rename map, then
+ * called again to stream entries out under their new names. Streaming
+ * adapters (zip in particular) can't be "rewound" mid-read, so the second
+ * pass re-invokes `listEntries` from the start rather than reusing entry
+ * objects collected in the first pass.
+ */
+export declare function renameArchiveImagesSequentially(input: ArchiveInput, options?: RenameOptions): Promise<Buffer | void>;
+//#endregion
+//#region src/strip.d.ts
+export declare function stripNonEssentialFiles(input: ArchiveInput, options?: StripOptions): Promise<Buffer | void>;
+//#endregion
+//#region src/listFiles.d.ts
+export declare function listArchiveFiles(input: ArchiveInput): Promise<string[]>;
+//#endregion
+//#region src/benchmark/benchmarkArchive.d.ts
+/**
+ * Extracts a comic archive, validates it contains image files, then
+ * generates one archive per (writable container format) x (page image
+ * format) combination, benchmarks each variant's creation speed and random
+ * single-file read speed, and writes a markdown report summarizing the
+ * results.
+ *
+ * Images are re-encoded to each target format once per image format, before
+ * any timing starts; `avgCreationMs` measures only packaging already-encoded
+ * entries into the target container, not the image re-encoding cost.
+ *
+ * Throws `ArchiveFormatError` (undetectable format) or
+ * `UnsupportedOperationError` (ACE) if `filePath` is not extractable,
+ * `NoImagesFoundError` if the archive contains no image files, and
+ * `RangeError` if `options.imageFormats` is empty or names an unsupported
+ * format.
+ */
+export declare function benchmarkArchive(filePath: string, options?: BenchmarkArchiveOptions): Promise<BenchmarkArchiveResult>;
+//#endregion
+//#region src/benchmark/report.d.ts
+export declare function renderBenchmarkReportMarkdown(result: BenchmarkArchiveResult): string;
+//#endregion
+//#region src/index.d.ts
+declare const comicArchiveHandler: {
+  convertImageBuffer: typeof convertImageBuffer;
+  convertArchiveImages: typeof convertArchiveImages;
+  computeImagePHash: typeof computeImagePHash;
+  phashToHex: typeof phashToHex;
+  computeArchiveImagePHash: typeof computeArchiveImagePHash;
+  hammingDistance: typeof hammingDistance;
+  IMAGE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp", "bmp", "tiff", "tif"];
+  isImagePath: typeof isImagePath;
+  sha256ArchiveEntry: typeof sha256ArchiveEntry;
+  sha256Archive: typeof sha256Archive;
+  renameArchiveImagesSequentially: typeof renameArchiveImagesSequentially;
+  stripNonEssentialFiles: typeof stripNonEssentialFiles;
+  listArchiveFiles: typeof listArchiveFiles;
+  benchmarkArchive: typeof benchmarkArchive;
+  renderBenchmarkReportMarkdown: typeof renderBenchmarkReportMarkdown;
+  WRITABLE_ARCHIVE_TYPES: readonly WritableArchiveType[];
+  BENCHMARK_IMAGE_FORMATS: readonly ImageOutputFormat[];
+  ARCHIVE_TYPE_EXTENSIONS: Record<WritableArchiveType, string>;
+  metadataToXml(metadata: ComicMetadata, schema: MetadataSchema): string;
+  xmlToMetadata(xml: string | Buffer, schema: MetadataSchema): ComicMetadata;
+  hasComicMetadata(input: ArchiveInput): Promise<{
+    present: boolean;
+    schema?: MetadataSchema;
+    path?: string;
+  }>;
+  readArchiveMetadata(input: ArchiveInput): Promise<{
+    schema: MetadataSchema;
+    metadata: ComicMetadata;
+  } | null>;
+  addMetadataToArchive(input: ArchiveInput, metadata: ComicMetadata, schema: MetadataSchema, options?: AddMetadataOptions): Promise<Buffer | void>;
+  metadataToComicInfoXml: typeof metadataToComicInfoXml;
+  comicInfoXmlToMetadata: typeof comicInfoXmlToMetadata;
+  metadataToMetronInfoXml: typeof metadataToMetronInfoXml;
+  metronInfoXmlToMetadata: typeof metronInfoXmlToMetadata;
+  validateMetadataXml: typeof validateMetadataXml;
+  COMIC_INFO_CREDIT_ROLES: readonly ["Writer", "Penciller", "Inker", "Colorist", "Letterer", "CoverArtist", "Editor", "Translator"];
+  COMIC_INFO_YES_NO_VALUES: readonly ["Unknown", "No", "Yes"];
+  COMIC_INFO_MANGA_VALUES: readonly ["Unknown", "No", "Yes", "YesAndRightToLeft"];
+  COMIC_INFO_AGE_RATING_VALUES: readonly ["Unknown", "Adults Only 18+", "Early Childhood", "Everyone", "Everyone 10+", "G", "Kids to Adults", "M", "MA15+", "Mature 17+", "PG", "R18+", "Rating Pending", "Teen", "X18+"];
+  COMIC_INFO_PAGE_TYPE_VALUES: readonly ["FrontCover", "InnerCover", "Roundup", "Story", "Advertisement", "Editorial", "Letters", "Preview", "BackCover", "Other", "Deleted"];
+  METRON_FORMAT_VALUES: readonly ["Annual", "Digital Chapter", "Graphic Novel", "Hardcover", "Limited Series", "Omnibus", "One-Shot", "Single Issue", "Trade Paperback"];
+  METRON_INFORMATION_SOURCE_VALUES: readonly ["AniList", "Comic Vine", "Grand Comics Database", "Kitsu", "MangaDex", "MangaUpdates", "Marvel", "Metron", "MyAnimeList", "League of Comic Geeks"];
+  METRON_ROLE_VALUES: readonly ["Writer", "Script", "Story", "Plot", "Interviewer", "Artist", "Penciller", "Breakdowns", "Illustrator", "Layouts", "Inker", "Embellisher", "Finishes", "Ink Assists", "Colorist", "Color Separations", "Color Assists", "Color Flats", "Digital Art Technician", "Gray Tone", "Letterer", "Cover", "Editor", "Consulting Editor", "Assistant Editor", "Associate Editor", "Group Editor", "Senior Editor", "Managing Editor", "Collection Editor", "Production", "Designer", "Logo Design", "Translator", "Supervising Editor", "Executive Editor", "Editor In Chief", "President", "Publisher", "Chief Creative Officer", "Executive Producer", "Other"];
+  METRON_AGE_RATING_VALUES: readonly ["Unknown", "Everyone", "Teen", "Teen Plus", "Mature", "Explicit", "Adult"];
+  splitCommaList: typeof splitCommaList;
+  joinCommaList: typeof joinCommaList;
+  resourceName: typeof resourceName;
+  resourceId: typeof resourceId;
+  joinResourceNames: typeof joinResourceNames;
+  convertArchive: typeof convertArchive;
+  extractArchive: typeof extractArchive;
+  detectArchiveType(input: ArchiveInput): Promise<ArchiveType>;
+  isZip(input: ArchiveInput): Promise<boolean>;
+  isRar(input: ArchiveInput): Promise<boolean>;
+  isTar(input: ArchiveInput): Promise<boolean>;
+  isAsar(input: ArchiveInput): Promise<boolean>;
+  is7z(input: ArchiveInput): Promise<boolean>;
+  isAce(input: ArchiveInput): Promise<boolean>;
+};
+//#endregion
+export { type BenchmarkArchiveOptions, type BenchmarkArchiveResult, type BenchmarkVariantResult, type ComicInfoCreditRole, type MetadataValidationIssue, type MetadataValidationResult, type WritableArchiveType, comicArchiveHandler as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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/benchmark/benchmarkArchive.ts","../src/benchmark/report.ts","../src/index.ts"],"mappings":"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"}