optiq-image / node

node

optiq-image/node — Node.js support (tests, benchmarks, server-side use). jSquash fetches its .wasm via fetch(import.meta.url), which does not work for file: URLs in Node, so compile the modules from disk and hand them over explicitly.

Interfaces

CodecBackend

Properties

Property	Modifier	Type
name	readonly	string

Methods

codecName()

codecName(format, settings): string;

Human-readable codec label for reports, e.g. "mozjpeg".

Parameters

Parameter	Type
format	OutputFormat
settings	EncodeSettings

Returns

string

decode()

decode(format, bytes): Promise<RawImage>;

Decode to 8-bit RGBA without applying EXIF orientation.

Parameters

Parameter	Type
format	"jpeg" | "png" | "webp" | "avif"
bytes	Uint8Array

Returns

Promise<RawImage>

encode()

encode(
   format, 
   img, 
   settings
): Promise<Uint8Array<ArrayBufferLike>>;

Parameters

Parameter	Type
format	OutputFormat
img	RawImage
settings	EncodeSettings

Returns

Promise<Uint8Array<ArrayBufferLike>>

optimisePng()?

optimisePng?(bytes, settings): Promise<Uint8Array<ArrayBufferLike>>;

Lossless PNG re-compression of existing PNG bytes (keeps ancillary chunks).

Parameters

Parameter	Type
bytes	Uint8Array
settings	EncodeSettings

Returns

Promise<Uint8Array<ArrayBufferLike>>

resize()?

resize?(
   img, 
   width, 
   height
): Promise<RawImage>;

Parameters

Parameter	Type
img	RawImage
width	number
height	number

Returns

Promise<RawImage>

---

DiskFileResult

Properties

Property	Type	Description
after?	number	-
before?	number	-
error?	string	CODE: message when this file failed; other files are unaffected.
file	string	Absolute input path.
from?	string	-
quality?	number | "exact"	SSIM of the result, or "exact" when pixels are verified identical (or the file is unchanged).
saved?	number	1 − after / before.
to?	DetectedFormat	-
usedOriginal?	boolean	The original was kept (already optimal, already optimised by Optiq, or the saving was below the threshold).
warnings?	string[]	-
written?	string	Absolute path written, if any.

---

DiskOptions

Properties

Property	Type	Description
concurrency?	number	Worker threads. Default: available cores − 1.
inPlace?	boolean	Overwrite the inputs (write to a temp file, then rename). Use with allowFormatConversion: false.
onResult?	(file, done, total) => void	-
out?	string	Write results to this folder, mirroring each input folder's structure.
signal?	AbortSignal	-

---

DiskResult

Properties

Property	Type
files	DiskFileResult[]
totals	object
totals.after	number
totals.before	number
totals.errors	number
totals.files	number
totals.saved	number
totals.seconds	number

---

EngineContext

Properties

Property	Type	Description
backend	CodecBackend & object	-
now?	() => number	-
onProgress?	(e) => void	-
onTiming?	(phase, ms) => void	Profiling hook: wall time per pipeline phase (used by the benchmark audit; no effect when absent).
signal?	AbortSignal	-

---

EngineOutput

Properties

Property	Type	Description
bytes?	Uint8Array<ArrayBufferLike>	Output bytes; undefined when the result is the unmodified input.
report	EngineReport	-

---

RawImage

8-bit RGBA, non-premultiplied, row-major. Structurally compatible with ImageData.

Properties

Property	Type
data	Uint8ClampedArray
height	number
width	number

Type Aliases

EncodeSettings

type EncodeSettings = Record<string, number | boolean | string>;

Codec-specific settings; also reported verbatim in CandidateReport.settings.

---

EngineReport

type EngineReport = Omit<CompressionResult, "blob" | "fileName">;

---

TimingPhase

type TimingPhase = 
  | "probe"
  | "decode"
  | "orient"
  | "resize"
  | "classify"
  | "encode"
  | "verify-decode"
  | "ssim"
  | "exact-compare"
  | "container";

Variables

IMAGE_EXTENSIONS

const IMAGE_EXTENSIONS: readonly string[];

Functions

collectImages()

function collectImages(paths): Promise<object[]>;

Expand files and folders (recursively, skipping dot-entries) into image files, each with the root it came from.

Parameters

Parameter	Type
paths	string[]

Returns

Promise<object[]>

---

createWasmBackend()

function createWasmBackend(): CodecBackend;

WASM codecs from jSquash (Squoosh builds): MozJPEG, libwebp, libavif (C/C++ via Emscripten), and the Rust crates png, oxipng and resize (via wasm-bindgen).

Returns

CodecBackend

---

initNodeCodecs()

function initNodeCodecs(): Promise<void>;

Returns

Promise<void>

---

optimizeFilesOnDisk()

function optimizeFilesOnDisk(
   paths, 
   options, 
   disk?
): Promise<DiskResult>;

Optimise files on disk. Without out or inPlace nothing is written (dry run). Per-file failures are reported in the result, not thrown; invalid options and missing paths throw before any work starts.

Parameters

Parameter	Type
paths	string[]
options	OptiqOptions
disk?	DiskOptions

Returns

Promise<DiskResult>

---

optimizeInNode()

function optimizeInNode(
   input, 
   options?, 
   ctx?
): Promise<EngineOutput>;

Optimise bytes in Node with the WASM codecs (single-threaded; no Worker).

Parameters

Parameter	Type
input	Uint8Array
options?	OptiqOptions
ctx?	Partial<EngineContext>

Returns

Promise<EngineOutput>