skills/docs/media/image/caddy-imgproxy/src/parse/parse-url.md

parseImgproxyUrl

(no submodules)

Purpose

parseImgproxyUrl parses the compact imgproxy URL grammar used by the Caddy module — /[s|u]<op><gravity><dims><modifiers>/<path>.<format> — into a typed, frozen ParsedImgproxyUrl. It is the canonical entry point for every other helper in the package; the URL builder, the handler, and the dimensions calculator all consume the value it returns.

Behaviour mirrors the upstream Go implementation byte-for-byte so the TypeScript port and the Go module can be tested against a shared fixture corpus. The function never partially succeeds: invalid input throws a CaddyImgproxyError carrying a stable code from CADDY_IMGPROXY_CODES, and the parse-total counter ticks once per call with the matching outcome tag.

Features

• Single-pass regex grammar covering signed / unsigned prefix, five operations (cover, crop, fit, stretch, resize), nine gravities, aspect / pixel / square dimensions, and width / height / quality modifiers in arbitrary order.
• Quality validation built into the grammar (q1..q100) — out-of-band values raise INVALID_URL.
• Operation + dimension constraint enforcement (MISSING_DIMENSIONS).
• Frozen, immutable return value safe to memoise.
• OTel counter on every call (caddy_imgproxy_parse_total).

Usage: Basic

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

const parsed = parseImgproxyUrl("/uv16:9/avatar.png");
parsed.operation; // "cover"
parsed.aspectW;   // 16
parsed.path;      // "avatar"
parsed.format;    // "png"

Usage: Advanced

import {
    CADDY_IMGPROXY_CODES,
    CaddyImgproxyError,
    parseImgproxyUrl,
} from "@suaveplan/caddy-imgproxy";

function tryParse(path: string): string | null {
    try {
        const parsed = parseImgproxyUrl(path);
        return `${parsed.operation || "passthrough"} → ${parsed.path}.${parsed.format}`;
    } catch (err) {
        if (
            err instanceof CaddyImgproxyError &&
            err.code === CADDY_IMGPROXY_CODES.MISSING_DIMENSIONS
        ) {
            return "needs dims";
        }
        throw err;
    }
}

API Reference

parseImgproxyUrl(path: string): ParsedImgproxyUrl

• Parameters: path — the URL path including leading /.
• Returns: a frozen ParsedImgproxyUrl (see types/types.ts).
• Throws:
  • CaddyImgproxyError(INVALID_URL) when the regex rejects the input — bad prefix, malformed dimensions, quality outside 1..100.
  • CaddyImgproxyError(MISSING_DIMENSIONS) when an operation (v|c|f|s|r) is present without any dimension grammar.

Implementation Notes

The grammar regex is a single anchored expression with thirteen capture groups that mirror the field order of the Go regex exactly. The modifier sub-grammar (w<int>, h<int>, q1..100) is extracted via a global secondary regex so order is irrelevant — the last w/h wins (matching Go), and q always wins for quality.

Number.parseInt with radix 10 is used for every numeric extraction to avoid the legacy octal-from-leading-zero behaviour. Defensive defaults are deliberately omitted from branches the regex can never reach so coverage stays honest; the only fallbacks in the function body protect against future grammar evolution (e.g. an empty gravity capture defaulting to "c").