# compress-options.schema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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.