Option Schemas

(no submodules)

Purpose

Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point that accepts options validates them through these schemas before processing. This catches misconfigured callers early and produces descriptive error messages that can be forwarded to end users or logged without additional formatting.

Features

QuantiseOptionsSchema — validates colour count, algorithm, distance formula, and dithering
SpatialCleanupOptionsSchema — validates merge thresholds
AdaptivePipelineOptionsSchema — validates pipeline overrides
Descriptive error messages suitable for structured logging

Usage: Basic Example

import { QuantiseOptionsSchema } from "@suaveplan/image-quantisation/schemas";

const result = QuantiseOptionsSchema.safeParse({ colours: 16 });
if (!result.success) {
    console.log(result.error.issues);
}

Usage: Advanced Example

import {
    AdaptivePipelineOptionsSchema,
    SpatialCleanupOptionsSchema,
} from "@suaveplan/image-quantisation/schemas";

const raw = {
    maxColours: 32,
    spatial: { maxDistance: 20 },
};

const parsed = AdaptivePipelineOptionsSchema.parse(raw);
// parsed.spatial is fully typed and defaults are applied by Zod

API Reference

`QuantiseOptionsSchema`

colours — optional integer 2–256
algorithm — optional enum "neuquant" | "rgbquant" | "wuquant"
distance — optional enum "euclidean" | "manhattan" | "ciede2000"
dither — optional enum "none" | "floyd-steinberg" | "riemersma"

`SpatialCleanupOptionsSchema`

maxDistance — optional non-negative number
maxPoolSize — optional non-negative integer

`AdaptivePipelineOptionsSchema`

maxColours — optional integer 2–256
dither — optional dither enum
spatial — optional nested SpatialCleanupOptionsSchema
skipSpatialCleanup — optional boolean
skipQuantisationForPixelArt — optional boolean

Implementation Notes

Schemas use .optional() for every field so that callers can supply partial options and the implementation supplies defaults. Validation failures throw QuantisationError with code PROCESSING_FAILED. The schemas are co-located with the types they validate to reduce drift. The QuantiseOptionsSchema enforces a minimum of 2 colours because single-colour palettes are not supported by the underlying image-q library. The AdaptivePipelineOptionsSchema nests SpatialCleanupOptionsSchema so that pipeline callers can override cleanup parameters in a single options object.

2.6 KiB Raw Blame History Unescape Escape