Your rule is just a function

August 5, 2026 · Mergic development notes

The day the modifier shipped, we already knew the next question: how do I hook my own logic in?

Every tool that grows a template language meets this moment. The usual answers are a plugin API, a scripts folder, a config DSL that slowly reinvents a programming language. We picked none of them. In Mergic, a custom rule is one JavaScript function.

The hook fills a token, not the whole path

The tempting design is to let user code compute the entire destination path. We refused, for the same reason the modifier itself does not touch conflict handling: composition is the feature. A custom token slots into the template like any built-in one:

${YEAR}/${custom:project|Misc}/${ORIGINAL_FILENAME}

Your function returns a string — that is the token's value. It returns null — the token is unresolvable, and everything you already know applies: the |Misc fallback if you declared one, a logged failure and a skipped file if you did not. The output passes through the same sanitization that strips .. and empty segments, so a custom rule cannot write outside the destination, not even by accident. Conflicts at the computed path? Same MD5 machinery, same name-2.ext, same idempotent re-runs. One new concept, zero new rules.

The whole EXIF object, not our selection of it

The built-in tokens cover capture date and camera make/model, because those are what most people sort by. But the moment you allow code, curating fields becomes a bottleneck: whatever we pick, someone needs the one we did not. So the function receives everything ImageIO can read, as one object:

(file) => {
  if (file.exif.GPS && file.exif.GPS.Latitude > 45) return "North";
  if (file.exif.Exif && file.exif.Exif.FNumber <= 2.0) return "FastGlass";
  return file.exif.TIFF ? file.exif.TIFF.Make : null;
}

file.exif is the full metadata dictionary — TIFF, Exif, GPS, IPTC, every group, every attribute. Alongside it: relativePath, name, dir, ext, size, mtime, and captureDate with the same EXIF-first precedence the built-in date tokens use. Route by aperture, by GPS hemisphere, by a client name embedded in the folder structure — we no longer have to predict what your rule needs.

The sandbox is a promise, not a limitation

The function runs in a bare JavaScriptCore context: no filesystem, no network, no timers. It can only compute from the object we hand it. That sounds restrictive until you notice what it buys: the function is pure by construction. Dry run executes your custom tokens for real — it must, to show you real paths — and a pure function makes that safe by definition, not by documentation. There is no "please don't do side effects in your hook" paragraph in our manual, because there is nothing to do them with.

The while-true problem

Arbitrary user code means someone will eventually write an infinite loop, and a merge of a million files cannot hang on file number three. JavaScriptCore has an execution-time limit API — in a private header, which a Mac App Store app cannot touch. So the public-API version: all JS runs on a dedicated queue, each call guarded by a watchdog timeout. A call that blows the budget marks the engine dead; that token and all subsequent ones resolve as unresolvable, which flows into the fallback/failed semantics you already know. The test suite runs a while (true) {} token over a real merge: the merge completes, files take their fallbacks, and exactly one worker thread is sacrificed to the runaway script. The merge never hangs. That is the contract.

Mergic merges folders safely on macOS — mergic.foldic.app.