compress-options.schema

(no submodules)

Purpose

Provides a Zod schema (CompressOptionsSchema) that validates and normalises CompressOptions at runtime before any image-processing work begins. Keeping validation in a dedicated schema file separates concerns cleanly: the compressor delegates option-checking to this module and never needs to repeat range guards inline.

Features

format — optional enum restricted to "jpeg" | "png" | "webp" | "avif"
quality — integer 1–100; rejects floats and out-of-range values
width / height — positive integers capped at 32767 (JPEG/PNG spec limit)
resizeMode — optional enum of five Sharp fit strategies
stripMetadata / progressive / lossless — optional booleans
effort — integer 0–6 for compression effort / speed trade-off
Re-exports CompressOptionsInput (pre-parse) and CompressOptionsParsed (post-parse) type aliases for strong typing at call sites

Usage: Basic Example

import { CompressOptionsSchema } from '@suaveplan/compress-image/schemas';

const result = CompressOptionsSchema.safeParse({ quality: 85, format: 'webp' });
if (!result.success) {
  console.error(result.error.issues);
} else {
  const opts = result.data; // CompressOptionsParsed
}

Usage: Advanced Example

import { CompressOptionsSchema } from '@suaveplan/compress-image/schemas';
import type { CompressOptionsInput } from '@suaveplan/compress-image/schemas';

function toCompressOptions(raw: unknown): CompressOptionsInput {
  // Strict parse — throws ZodError on invalid input
  return CompressOptionsSchema.parse(raw);
}

// Combining with ImageCompressor validation:
// The ImageCompressor calls CompressOptionsSchema.safeParse internally and
// maps ZodError issues into a structured CompressImageError(INVALID_OPTIONS).
// Direct use of this schema is useful in API route handlers that want to
// validate options before constructing an ImageCompressor.
const validated = CompressOptionsSchema.safeParse({
  format: 'avif',
  quality: 60,
  width: 1920,
  height: 1080,
  resizeMode: 'cover',
  effort: 4,
  stripMetadata: true,
});

API Reference

`CompressOptionsSchema`

ZodObject schema validating CompressOptions. All fields are optional.

Field	Type	Constraints
`format`	`"jpeg" \| "png" \| "webp" \| "avif"`	enum
`quality`	`number`	int, 1–100
`width`	`number`	int, 1–32767
`height`	`number`	int, 1–32767
`resizeMode`	`ResizeMode`	enum of 5 strategies
`stripMetadata`	`boolean`	optional
`progressive`	`boolean`	optional
`lossless`	`boolean`	optional
`effort`	`number`	int, 0–6

`CompressOptionsInput`

z.input<typeof CompressOptionsSchema> — the shape of data accepted before parsing (all fields optional).

`CompressOptionsParsed`

z.output<typeof CompressOptionsSchema> — the shape returned after successful parsing.

Implementation Notes

The schema intentionally mirrors the CompressOptions interface defined in compress-image.types.ts. No coercion is applied; callers are expected to pass the correct JS types. Integer constraints (z.number().int()) are necessary because Sharp interprets quality as a C int; passing 80.5 would produce unpredictable output.

Effort range 0–6 follows the WebP/AVIF encoder convention. Sharp maps this field directly to the codec's speed parameter, where 0 is fastest (lower quality at equal bit-rate) and 6 is slowest (best compression).

The schema is intentionally stateless and side-effect-free — it is safe to import and reuse across workers, edge functions, and test helpers.

4.1 KiB Raw Permalink Blame History Unescape Escape