first commit

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

@@ -0,0 +1,76 @@
+# operationToImgproxy
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## 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
+
+```ts
+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
+
+```ts
+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.