Fix falsy option arguments skipping validation

[11bit]

Third and last finding from the audit that produced #89 and #90: optional arguments guarded with if (value) and rendered with value || "", so any falsy value was treated as "not provided" — including invalid ones.

watermarkSize.build({ wms: { width: null, height: 100 } })
// before: "wms::100"   (silently accepted)
// after:  throws "watermark_size.width is not a number"

Swept across 11 modules: resize, size, watermark, watermarkSize, trim, unsharpMasking, pngOptions, jpegOptions, colorize, monochrome, gravity.

What changes

• Invalid falsy values now raise. null, "" and out-of-range 0 reach their guards instead of slipping past them.
• Explicit 0 is rendered rather than dropped. { resize: { resizing_type: "fit", width: 0, height: 100 } } now builds rs:fit:0:100 instead of rs:fit::100. Both forms mean the same thing to imgproxy — 0 and an omitted argument are both "calculate this dimension" — so no URL changes meaning. This is unlike Fix gradient dropping optional arguments set to 0 #89, where the dropped 0 genuinely differed from the default.
• colorize.color and monochrome.color are now validated as hex colors. Neither had any type validation at all; they now match trim.color and gradient.color.
• gravity offset checks use presence, so { type: "sm", x_offset: 0 } correctly raises gravity.type is invalid — previously only a non-zero offset triggered that check.

Bug found while sweeping

jpeg_options threw "progressive must be true if optimize_scans is true" whenever optimize_scans was merely present. With the truthiness guard that was masked; converting it to a presence check exposed it, so the cross-check is now tied to optimize_scans actually being enabled. { progressive: false, optimize_scans: false } is valid and now builds jpgo:false::::false.

Second commit: Gravity is now an exclusive union (minor)

The gravity builder's cross-variant checks needed six @ts-expect-error suppressions, because fields like x_offset or class_names exist on only one member of the Gravity union. Instead of suppressing, the union is now exclusive: each variant types the other variants' fields as ?: never.

• Invalid combinations such as { type: "sm", x_offset: 0 } or { type: "no", x: 0.5 } are now compile-time errors for TypeScript users. They have always thrown at runtime, so any code this breaks was already broken — it just failed later.
• All six suppressions in src/options/gravity.ts are removed; runtime behavior is unchanged.
• Ships as a minor changeset (type-level breaking only), separate from the patch changeset for the validation fixes.

Verification

• tsc --noEmit clean, eslint src tests clean
• vitest run → 97 files / 1114 tests passing (19 new, at least one per swept module)
• No existing test needed changing for the validation fixes, which suggests the truthiness behavior was never deliberate. The exclusive-union commit adds one @ts-expect-error to an existing test — the stricter union now flags y: 0.5 on a non-fp gravity independently of x, which previously slipped past the excess-property check.

Related

• Fix gradient dropping optional arguments set to 0 #89 — the same pattern in gradient, where it changed the resulting image
• Fix video_thumbnail_animation undefined frame size and zoom 0 #90 — video_thumbnail_animation emitting undefined, and zoom: 0 being dropped

🤖 Generated with Claude Code

https://claude.ai/code/session_014gcu8oHhTciugXNPUYNoqK