format-png 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,371 +1,5 @@
-export type ColorType = "grayscale" | "rgb" | "indexed" | "grayscale-alpha" | "rgba";
-export interface PngHeader {
-    width: number;
-    height: number;
-    bitDepth: number;
-    colorType: ColorType;
-    interlaced: boolean;
-}
-export type RenderingIntent = "perceptual" | "relative-colorimetric" | "saturation" | "absolute-colorimetric";
-/** A CIE 1931 chromaticity, for example `{ x: 0.3127, y: 0.329 }`. */
-export interface Chromaticity {
-    x: number;
-    y: number;
-}
-/** `cHRM`: the chromaticities of the white point and the primaries. */
-export interface Chromaticities {
-    white: Chromaticity;
-    red: Chromaticity;
-    green: Chromaticity;
-    blue: Chromaticity;
-}
-/**
- * `pHYs`: pixels per unit. With unit "meter" this is the intended pixel size;
- * with "unknown" only the ratio of `x` to `y` means anything.
- */
-export interface PhysicalDimensions {
-    x: number;
-    y: number;
-    unit: "meter" | "unknown";
-}
-/** `tIME`: when the image was last modified, in UTC. `month` is 1 to 12. */
-export interface PngTime {
-    year: number;
-    month: number;
-    day: number;
-    hour: number;
-    minute: number;
-    second: number;
-}
-/** A `tEXt`, `zTXt` or `iTXt` chunk, decoded to a string whatever its encoding. */
-export interface PngText {
-    /** For example "Title", "Author" or "Comment". */
-    keyword: string;
-    text: string;
-    /** `iTXt` only, for example "en" or "nb-NO"; otherwise empty. */
-    languageTag: string;
-    /** `iTXt` only: the keyword in that language; otherwise empty. */
-    translatedKeyword: string;
-    chunkType: "tEXt" | "zTXt" | "iTXt";
-    /** Whether the text was zlib-compressed in the file. */
-    compressed: boolean;
-}
-/** `iCCP`: an embedded ICC color profile. */
-export interface IccProfile {
-    /** Only meaningful to people, for example "ICC Profile". 1 to 79 characters of printable Latin-1. */
-    name: string;
-    /** The ICC profile, decompressed. Pass it to a color management library to apply it. */
-    profile: Uint8Array;
-}
-/**
- * `cICP`: the color space as ITU-T H.273 code points, as video uses. sRGB is
- * primaries 1 and transfer 13; Display P3 is 12 and 13; HDR PQ is 9 and 16.
- * Takes precedence over every other color chunk.
- */
-export interface Cicp {
-    colorPrimaries: number;
-    transferFunction: number;
-    /** Always 0 (RGB) in PNG. */
-    matrixCoefficients: number;
-    /** Whether samples use the full range, as almost all PNGs do, rather than video's narrow range. */
-    fullRange: boolean;
-}
-/** `eXIf`: Exif metadata, such as the camera and orientation, kept raw. */
-export interface PngExif {
-    /** Starts with a TIFF header; pass it to an Exif library to read the tags. */
-    data: Uint8Array;
-    byteOrder: "big-endian" | "little-endian";
-}
-/**
- * The known ancillary chunks, parsed. A field is absent if the image doesn't
- * have that chunk, or if it was invalid or misplaced and `strictAncillary` is off.
- */
-export interface PngMetadata {
-    /** `gAMA`, for example 0.45455 (1/2.2). */
-    gamma?: number;
-    chromaticities?: Chromaticities;
-    /** `sRGB`: the image is sRGB, with this rendering intent. */
-    srgb?: RenderingIntent;
-    physicalDimensions?: PhysicalDimensions;
-    time?: PngTime;
-    /** `tEXt`, `zTXt` and `iTXt`, in file order. A keyword may repeat. */
-    text: PngText[];
-    iccProfile?: IccProfile;
-    cicp?: Cicp;
-    exif?: PngExif;
-}
-export type ChunkPosition = "before-palette" | "before-image-data" | "after-image-data";
-/** A raw ancillary chunk, including private and unknown ones. */
-export interface PngChunk {
-    /** The four-letter type, for example "tEXt". */
-    type: string;
-    /** The chunk's data, without length, type and CRC. */
-    data: Uint8Array;
-    /** Where the chunk was relative to `PLTE` and the image data. */
-    position: ChunkPosition;
-}
-/** One chunk as it is in the file, from `readChunks`. */
-export interface PngRawChunk {
-    /** The four-letter type, for example "IHDR" or "tEXt". */
-    type: string;
-    /** Where the chunk starts in the input: its length field. */
-    offset: number;
-    /** The chunk's data, without length, type and CRC. A view into the input, not a copy. */
-    data: Uint8Array;
-    /** The CRC stored in the file. */
-    crc: number;
-    /** Whether format-png parses this chunk type. */
-    known: boolean;
-    /** Uppercase first letter: needed to display the image. */
-    critical: boolean;
-    /** Uppercase second letter: defined or registered by the PNG spec, not private. */
-    public: boolean;
-    /** Lowercase fourth letter: editors may copy it even after changing the image. */
-    safeToCopy: boolean;
-}
-/**
- * `tRNS`: one fully transparent gray value or RGB color, in the image's bit
- * depth, or an alpha per palette entry (entries past the end are opaque).
- */
-export type PngTransparency = {
-    kind: "gray";
-    value: number;
-} | {
-    kind: "rgb";
-    value: [number, number, number];
-} | {
-    kind: "palette";
-    alpha: Uint8Array;
-};
-/** Every chunk of a PNG, read and parsed without decompressing the image data. */
-export interface PngChunks {
-    header: PngHeader;
-    /** `PLTE`, as `[r, g, b]` entries in index order. Indexed images always have one. */
-    palette?: [number, number, number][];
-    transparency?: PngTransparency;
-    /** Always collected, whatever `preserveMetadata` says. */
-    metadata: PngMetadata;
-    /** Every chunk from `IHDR` to `IEND`, in file order, including unknown ones. */
-    chunks: PngRawChunk[];
-}
-/** Options for `readChunks`. */
-export interface ReadChunksOptions {
-    /** Check each chunk's CRC. Default true. */
-    validateCrc?: boolean;
-    /** Throw for an invalid, misplaced or repeated metadata chunk instead of skipping it. Default false. */
-    strictAncillary?: boolean;
-}
-export interface DecodeOptions {
-    /** Check each chunk's CRC. Default true. */
-    validateCrc?: boolean;
-    /** Parse known ancillary chunks into `metadata`. Default false. */
-    preserveMetadata?: boolean;
-    /** Keep a raw copy of every ancillary chunk in `chunks`. Default false. */
-    preserveChunks?: boolean;
-    /** Throw for an invalid, misplaced or repeated metadata chunk instead of skipping it. Default false. */
-    strictAncillary?: boolean;
-}
-/** 8-bit RGBA pixels, not premultiplied, rows packed with no padding. */
-export interface RgbaImage {
-    width: number;
-    height: number;
-    data: Uint8ClampedArray;
-    /** Empty unless decoded with `preserveMetadata`. */
-    metadata: PngMetadata;
-    /** In file order. Empty unless decoded with `preserveChunks`. */
-    chunks: PngChunk[];
-}
-/**
- * Text to write as a `tEXt`, `zTXt` or `iTXt` chunk. A `PngText` from decoding
- * works as it is.
- */
-export interface PngTextInput {
-    /** 1 to 79 characters of printable Latin-1, for example "Title" or "Author". */
-    keyword: string;
-    /** Latin-1 only for `tEXt` and `zTXt`; any Unicode for `iTXt`. */
-    text: string;
-    /** Default "tEXt". `zTXt` is always compressed. */
-    chunkType?: PngText["chunkType"];
-    /** `iTXt` only: whether to zlib-compress the text. Default false. */
-    compressed?: boolean;
-    /** `iTXt` only, for example "en" or "nb-NO". */
-    languageTag?: string;
-    /** `iTXt` only: the keyword in that language. */
-    translatedKeyword?: string;
-}
-/** The metadata chunks to write. A `PngMetadata` from decoding works as it is. */
-export interface PngMetadataInput {
-    gamma?: number;
-    chromaticities?: Chromaticities;
-    srgb?: RenderingIntent;
-    physicalDimensions?: PhysicalDimensions;
-    time?: PngTime;
-    /** Written in order. */
-    text?: PngTextInput[];
-    /** The profile is given uncompressed; the encoder compresses it. */
-    iccProfile?: IccProfile;
-    cicp?: Cicp;
-    /** Its TIFF header is checked; `byteOrder` is read from it, so it can be left out. */
-    exif?: {
-        data: Uint8Array;
-        byteOrder?: PngExif["byteOrder"];
-    };
-}
-/**
- * An image to encode, in the PNG's own pixel format: rows top to bottom with
- * each padded to a whole byte, 16-bit samples big-endian, pixels under 8 bits
- * packed most significant bits first, and palette indices for indexed images.
- */
-export interface PngImage {
-    header: PngHeader;
-    data: Uint8Array;
-    /** `PLTE`, as `[r, g, b]` entries. Indexed images need one; grayscale images must not have one. */
-    palette?: [number, number, number][];
-    /** `tRNS`. Images with an alpha channel must not have one. */
-    transparency?: PngTransparency;
-    metadata?: PngMetadataInput;
-    /** Raw ancillary chunks, written at their positions; see `EncodeOptions.keepUnsafeChunks`. */
-    chunks?: PngChunk[];
-}
-/**
- * An image decoded in the file's own format by `decode`, without conversion:
- * 16-bit samples stay 16-bit (big-endian bytes, as in the file), so passing it
- * to `encode` writes the same pixels back.
- */
-export interface RawImage extends PngImage {
-    /** Empty unless decoded with `preserveMetadata`. */
-    metadata: PngMetadata;
-    /** In file order. Empty unless decoded with `preserveChunks`. */
-    chunks: PngChunk[];
-}
-/** 8-bit RGBA pixels to encode. An `RgbaImage` from decoding, or an `ImageData`, works as it is. */
-export interface RgbaImageInput {
-    width: number;
-    height: number;
-    /** `width * height * 4` bytes, rows packed with no padding. */
-    data: Uint8Array | Uint8ClampedArray;
-    metadata?: PngMetadataInput;
-    chunks?: PngChunk[];
-    /** Write Adam7 interlaced. Default false. */
-    interlaced?: boolean;
-}
-export type FilterType = "none" | "sub" | "up" | "average" | "paeth";
-export interface EncodeOptions {
-    /** 0 (none) to 9 (smallest). Default 6. */
-    compression?: number;
-    /**
-     * The kind of DEFLATE blocks. "dynamic" (the default) gives the smallest
-     * files, "fixed" is a little faster, "stored" doesn't compress.
-     */
-    compressionStrategy?: "dynamic" | "fixed" | "stored";
-    /**
-     * How each row is filtered before compressing. "adaptive" (the default)
-     * picks a filter per row; the others use that filter for every row.
-     */
-    filter?: "adaptive" | FilterType;
-    /**
-     * Also write raw chunks that aren't safe to copy, such as `bKGD`, whose data
-     * depends on the pixels. Default false. Turn it on when re-encoding an image
-     * with its pixels, header and palette unchanged.
-     */
-    keepUnsafeChunks?: boolean;
-    /**
-     * "auto" writes 8-bit RGB and RGBA images with at most 256 colors, counting
-     * alpha, as indexed color at the smallest bit depth that fits. Lossless, and
-     * often several times smaller for logos, icons and screenshots; unsafe-to-copy
-     * chunks are then dropped, as they describe the old color type. Default "keep".
-     */
-    palette?: PaletteMode;
-    /** Which ancillary chunks to leave out to make the file smaller. Default "keep". */
-    strip?: StripChunks;
-}
-export type PaletteMode = "keep" | "auto";
-/**
- * Which ancillary chunks the encoder leaves out. `tRNS` and an indexed image's
- * palette are always kept.
- *
- * - "keep": write everything given.
- * - "safe": keep what changes how the image looks: `cICP`, `iCCP`, `sRGB`,
- *   `gAMA`, `cHRM` and `pHYs`. Drop text, `tIME`, `eXIf`, raw chunks and an
- *   RGB image's suggested palette. Exif orientation is lost with it.
- * - "all": keep nothing optional, for the smallest file. Colors may look
- *   different in color-managed viewers such as browsers.
- */
-export type StripChunks = "keep" | "safe" | "all";
-/** Thrown for malformed PNGs; `message` says what's wrong. */
-export declare class PngError extends Error {
-    name: string;
-}
-/**
- * Loads the WebAssembly module. Call it once before anything else; later calls
- * return the same promise.
- *
- * With no argument it uses the copy embedded in this package, in browsers,
- * bundlers and Node alike: nothing is fetched. You can instead pass a
- * `WebAssembly.Module` compiled from it, for example one a page compiled once
- * and posted to its workers.
- */
-export declare function init(source?: BufferSource | WebAssembly.Module | Response | Promise<Response>): Promise<void>;
-/**
- * Decodes a PNG in its own format, without conversion: every bit depth and
- * color type as stored, with its palette and transparency. Pass the result to
- * `encode` to re-encode it losslessly. Use `decodeRgba8` to display it.
- */
-export declare function decode(bytes: Uint8Array, options?: DecodeOptions): RawImage;
-/** Decodes a PNG to 8-bit RGBA. Pass options to also read metadata or raw chunks. */
-export declare function decodeRgba8(bytes: Uint8Array, options?: DecodeOptions): RgbaImage;
-/**
- * Reads and parses every chunk without decompressing the image data, which is
- * much faster than decoding. Known chunks are parsed; every chunk, including
- * private and unknown ones, is also returned raw in file order.
- */
-export declare function readChunks(bytes: Uint8Array, options?: ReadChunksOptions): PngChunks;
-/** Parses the data of a `tEXt`, `zTXt` or `iTXt` chunk on its own, for example one from `readChunks`. */
-export declare function parseText(type: PngText["chunkType"], data: Uint8Array): PngText;
-/** Pixels per inch from `pHYs`, or undefined if its unit isn't meters. */
-export declare function pixelsPerInch(dimensions: PhysicalDimensions): {
-    x: number;
-    y: number;
-} | undefined;
-/** Reads the image header without decoding pixels. */
-export declare function readHeader(bytes: Uint8Array): PngHeader;
-/**
- * Encodes an image in any PNG pixel format, with its palette, transparency,
- * metadata and raw chunks.
- */
-export declare function encode(image: PngImage, options?: EncodeOptions): Uint8Array;
-/**
- * Encodes 8-bit RGBA pixels: the reverse of `decodeRgba8`. Pass a decoded
- * `RgbaImage` to re-encode it with its metadata and chunks, or the `ImageData`
- * of a canvas.
- */
-export declare function encodeRgba8(image: RgbaImageInput, options?: EncodeOptions): Uint8Array;
-/** Wraps an image for `CanvasRenderingContext2D.putImageData`. Browser only. */
-export declare function toImageData(image: RgbaImage): ImageData;
-/**
- * A decoder for many images: it keeps its buffers in wasm memory between calls.
- * Call `free()` when you're done with it.
- */
-export declare class PngDecoder {
-    #private;
-    constructor(options?: DecodeOptions);
-    decodeRgba8(bytes: Uint8Array): RgbaImage;
-    /** Like the `decode` function. */
-    decode(bytes: Uint8Array): RawImage;
-    /** Like the `readChunks` function. Only the `validateCrc` and `strictAncillary` options apply. */
-    readChunks(bytes: Uint8Array): PngChunks;
-    free(): void;
-}
-/**
- * An encoder for many images: it keeps its compressor and buffers in wasm
- * memory between calls. Call `free()` when you're done with it.
- */
-export declare class PngEncoder {
-    #private;
-    constructor(options?: EncodeOptions);
-    /** Like the `encode` function, with this encoder's options. */
-    encode(image: PngImage): Uint8Array;
-    /** Like the `encodeRgba8` function, with this encoder's options. */
-    encodeRgba8(image: RgbaImageInput): Uint8Array;
-    free(): void;
-}
+export type * from "./core.js";
+export { PngDecoder, PngEncoder, PngError, decode, decodeRgba8, encode, encodeRgba8, init, parseText, pixelsPerInch, readChunks, readHeader, toImageData, } from "./core.js";
+export { createWorkerPool, WorkerPoolError } from "./pool.js";
+export type { JobOptions, NodeWorkerLike, WorkerPool, WorkerPoolOptions } from "./pool.js";
+export { decodeAsync, decodeRgba8Async, defaultWorkerPool, encodeAsync, encodeRgba8Async, parseTextAsync, readChunksAsync, readHeaderAsync, terminateDefaultWorkerPool, } from "./async.js";