@e-mc/compress

Interface

View Source
import type { IModule, ModuleConstructor } from "./index";
import type { BrotliCompressLevel, BufferResult, CompressFormat, CompressLevel, TryFileCompressor } from "./compress";
import type { CompressModule, CompressSettings } from "./settings";

import type { WriteStream } from "node:fs";
import type { Readable } from "node:stream";
import type { BrotliCompress, BrotliOptions, Gzip, ZlibOptions } from "node:zlib";

interface ICompress extends IModule {
    module: CompressModule;
    level: Record<string, number>;
    compressors: Record<string, TryFileCompressor>;
    init(...args: unknown[]): this;
    register(format: string, callback: TryFileCompressor): void;
    getLevel(value: string, fallback?: number): number | undefined;
    getReadable(file: string | URL | Buffer): Readable;
    createGzip(file: string | Buffer, options?: CompressLevel): Gzip;
    createBrotliCompress(file: string | Buffer, options?: BrotliCompressLevel): BrotliCompress;
    createWriteStreamAsGzip(file: string | Buffer, output: string, options?: CompressLevel): WriteStream;
    createWriteStreamAsBrotli(file: string | Buffer, output: string, options?: BrotliCompressLevel): WriteStream;
    intoGzipStream(output: string, options?: ZlibOptions): WriteStream;
    intoBrotliStream(output: string, options?: BrotliOptions): WriteStream;
    writeGzip(file: string | Buffer, output: string, options?: CompressLevel): Promise<void>;
    writeBrotli(file: string | Buffer, output: string, options?: CompressLevel): Promise<void>;
    tryFile(file: string | Buffer, options: CompressFormat): Promise<BufferResult>;
    tryFile(file: string | Buffer, output: string, options?: CompressFormat): Promise<BufferResult>;
    tryImage(file: string, options: CompressFormat): Promise<BufferResult>;
    tryImage(file: string | Buffer, output: string, options?: CompressFormat): Promise<BufferResult>;
    hasPermission(type: string, options?: unknown): boolean;
    set chunkSize(value: number | string | undefined): void;
    get chunkSize(): number | undefined;
    get settings(): CompressSettings;
}

interface CompressConstructor extends ModuleConstructor {
    singleton(): ICompress;
    asBuffer(data: Buffer | Uint8Array): Buffer;
    readonly prototype: ICompress;
    new(module?: CompressModule): ICompress;
}

Changelog

Added in version 0.14.0:

  • ICompress function tryFile options property format as zst is conditionally supported.

Note

NodeJS 22.15

Removed in version 0.14.0:

  • ICompress compression format zopfli as gzip is no longer supported.

Added in version 0.13.0:

  • ICompress interface CompressLevel has extended ZlibOptions.

  • ICompress interface BrotliCompressLevel has extended BrotliOptions.

Added in version 0.12.0:

  • ICompress function intoGzipStream | intoBrotliStream were created.

  • CompressConstructor function asBuffer was created.

Changed in version 0.12.0:

  • ICompress function tryFile | tryImage enforce read (file) and write (output) permissions.

  • BREAKING type PluginCompressor argument mimeType as string was replaced with metadata as PlainObject.

Changed in version 0.10.0:

  • ICompress property chunkSize was converted into a 1KB aligned accessor.

Added in version 0.9.0:

  • ICompress function writeGzip | writeBrotli were created.

Removed in version 0.9.0:

  • ICompress function tryFile | tryImage argument callback as function is no longer available.

Settings

View JSON
import type { CacheDirAction } from "./settings";

import type { BrotliOptions, ZlibOptions, ZstdOptions } from "node:zlib";

interface CompressModule {
    gzip?: ZlibOptions;
    brotli?: BrotliOptions;
    zstd?: ZstdOptions;
    settings?: {
        broadcast_id?: string | string[];
        cache?: boolean | CacheDirAction & { font?: string | number | boolean; image?: string | number | boolean; };
        cache_expires?: number | string;
        gzip_level?: number;
        brotli_quality?: number;
        zstd_compression_level?: number | string;
        chunk_size?: number | string;
    };
}

Changelog

Added in version 0.14.0:

  • CompressModule settings for Zstandard compression format (experimental) is supported.

Removed in version 0.14.0:

  • CompressModule settings for zopfli compression format were deleted.

Changed in version 0.13.0:

  • CompressModule settings property cache as CacheDirAction for categorized cache expiration was implemented.

Removed in version 0.10.0:

  • Tinify was converted into an optional plugin named @pi-r/tinify.

interface CompressModule {
    tinify?: {
        api_key?: string;
        proxy?: string;
    };
}

Example usage

const Compress = require("@e-mc/compress");

const instance = new Compress({
  gzip: {
    memLevel: 1,
    windowBits: 16
  },
  tinify: {
    api_key: "**********"
  },
  settings: {
    gzip_level: 9, // Lowest priority
    brotli_quality: 11,
    chunk_size: "16kb" // All compression types
  }
});
instance.init();

const stream = instance.createWriteStreamAsGzip("/tmp/archive.tar", "/path/output/archive.tar.gz", { level: 5, chunkSize: 4 * 1024 }); // Override settings
stream
  .on("finish", () => console.log("finish"))
  .on("error", err => console.error(err));

const options = {
  plugin: "@pi-r/tinify",
  format: "png", // Optional with extension
  timeout: 60 * 1000, // 1m
  options: {
    apiKey: "**********" // Override settings
  }
};
instance.tryImage("/tmp/image.png", "/path/output/compressed.png", options)
  .then(data => {
    console.log(Buffer.byteLength(data));
  })
  .catch(err => console.error(err));

References