Initial Commit

packages/media/image/compress-image/src/schemas/compress-options.schema.md

@@ -0,0 +1,103 @@
+# 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.