skills/docs/media/image/caddy-imgproxy/src/operation/operation.md

operationToImgproxy

(no submodules)

Purpose

operationToImgproxy converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-string segment that sits between the /<signature>/ prefix and the /plain/s3://…@<fmt> suffix. It is the bridge between the compact grammar's abstract operations and imgproxy's concrete URL DSL.

The five operations behave exactly as the upstream Go module: cover and crop require a gravity prefix so anchoring takes effect during cropping; fit ignores gravity (it always preserves aspect ratio); stretch always emits rs:force:W:H; resize is the single-axis variant of fit. Passthrough ("") and unknown operations emit an empty string so the URL builder skips the processing segment entirely.

Features

• Total function — every input returns a defined string, never throws.
• Mirrors the Go switch table byte-for-byte.
• Single-axis fallbacks (g:<g>/w:W, w:W, h:H) so callers can produce auto-axis resizes without re-implementing the table.
• Empty-string fallback drives the URL builder to skip the segment.

Usage: Basic

import { operationToImgproxy } from "@suaveplan/caddy-imgproxy";

operationToImgproxy("cover", 1920, 1080, "t");
// → "g:no/rs:fill:1920:1080"

operationToImgproxy("fit", 800, 0, "c");
// → "w:800"

Usage: Advanced

import {
    calculateDimensions,
    operationToImgproxy,
    parseImgproxyUrl,
} from "@suaveplan/caddy-imgproxy";

const parsed = parseImgproxyUrl("/ucbl4:3w1920/photo.png");
const { width, height } = calculateDimensions(parsed, 800);
operationToImgproxy(parsed.operation, width, height, parsed.gravity);
// → "g:sowe/c:1920:1440"

API Reference

operationToImgproxy(op: ImgproxyOperation, width: number, height: number, gravity: string): string

• Parameters:
  • op — one of ""|cover|crop|fit|stretch|resize.
  • width, height — non-negative integers; either may be zero.
  • gravity — a grammar code accepted by gravityToImgproxy.
• Returns: the imgproxy processing string, or "" when the operation cannot be expressed (e.g. crop without both dims).

Implementation Notes

The switch is exhaustive over the ImgproxyOperation union; the TypeScript compiler verifies no case escapes. Gravity is resolved once at the top of the function so the cover/crop branches share a single translation step. The empty-operation case returns "" explicitly rather than falling through so the exhaustiveness check stays clean.