ESM bundle

A self-contained ES module — no dependencies, no bundler, no build step. Import it by URL and you get the same encoder and decoder the HTTP API runs, executing locally.

<script type="module">
  import { encode, decode } from 'https://production-transformation-serializer.cloudinary.com/esm/latest/serializer.mjs';

  encode([{ actionType: 'scale', dimensions: { width: 500, height: 300 } }]);
  // → "c_scale,h_300,w_500"
</script>

Try it on the playground, which imports this exact file.

You do not even need the playground: every docs page loads the bundle and exposes encode, decode and serializer on window, so devtools on this page is already a working REPL. The copy loaded here is pinned to the running version rather than latest, so the console always matches the docs you are reading.

Pin a version#

latest is right for a spike and wrong for production. Pin instead:

import { encode } from 'https://production-transformation-serializer.cloudinary.com/esm/v0.1.0/serializer.mjs';

URL	Resolves to	Cached for
`/esm/v0.1.0/serializer.mjs`	exactly that build, forever	1 year, `immutable`
`/esm/v0.1.0`	same file, shorthand	1 year, `immutable`
`/esm/latest/serializer.mjs`	the newest published version	5 minutes
`/esm/index.json`	`{ "latest": "…", "versions": [...] }`	5 minutes
`/esm/v0.1.0/manifest.json`	byte counts and SRI hashes for that build	1 year, `immutable`

The one-year immutable cache is not optimism. A published version directory is byte-frozen: the build refuses to overwrite one, CI re-derives every published bundle's hash from its manifest on every pull request, and a release that changes the output has to change the version. That is what makes it safe for a browser to never revalidate.

Verify what you loaded#

Every build ships an SRI hash in its manifest.json, so you can make the browser enforce the pin rather than trust it:

<link rel="modulepreload"
      href="https://production-transformation-serializer.cloudinary.com/esm/v0.1.0/serializer.mjs"
      integrity="sha384-…"
      crossorigin="anonymous" />

curl -s https://production-transformation-serializer.cloudinary.com/esm/v0.1.0/manifest.json

API#

`encode(model: Transformation): string`#

Model → transformation string. Qualifiers come out alphabetically ordered within each action.

`decode(transformationString: string): Transformation`#

Transformation string → model. Unrecognised segments become custom actions rather than being dropped, so a decode → encode round-trip is lossless.

`serializer`#

{ encode, decode } as one object, for callers that prefer passing the pair around.

TypeScript consumers get Transformation and TransformationSerializer types from the same module. If you would rather generate your own, the JSON Schema is the source of truth those types are built from.

Size and support#

Roughly 68 KB uncompressed, well under 20 KB over the wire with gzip or brotli. Requires ES2020 and native ESM: Chrome/Edge 88+, Firefox 89+, Safari 14.1+.

Which one should I use?#

Use the bundle when the work is interactive — a transformation editor re-encoding as someone types should not make a network call per keystroke, and the round-trip latency is far larger than the parse itself. Use the HTTP API when you are on a server, in another language, or want a single place to upgrade rather than a version pinned into every page.