Flat Transform

What it changes

This mode splits statements as aggressively as possible and moves them into a less readable arrangement, dispatched through generated state rather than laid out in order. It also works well with nested-function movement, which means the final file no longer preserves the comfortable visual order of the original source.

The consequence for a reader is that source position stops predicting execution order. In ordinary code, reading top to bottom approximates what happens at runtime, and the nesting of if and loop bodies shows you the branch structure directly. After flattening, the statements are fragments selected by a dispatcher, and reconstructing "what runs after what" means tracing state transitions rather than reading indentation.

This is the same building block VM bytecode interpreters are made of — a dispatch loop over opaque state. VM protection takes it further by moving selected functions out of JavaScript form entirely.

When to use it

• When you want a stronger result than basic name replacement alone.
• When you are willing to test output carefully for compatibility and performance.
• When protecting production code matters more than keeping the transformed file compact or easy to troubleshoot.

The inverse is just as useful to state. Do not reach for this on code whose value is low, on hot paths where the dispatch overhead will show up in a frame budget, or in a project where you cannot run a real test suite against protected output.

Configuration

Flat Transform sits inside the wrapper that Code Transposition creates, so enable both:

{
  "options": {
    "ReorderCode": true,
    "FlatTransform": true
  }
}

Migrating from the open-source javascript-obfuscator package? Its single controlFlowFlattening flag maps to FlatTransform together with DeepObfuscate — one upstream option, two here. See npm migration for the complete table.

Visual reference

Cost, and how to scope it

Flattening is the most expensive transform in the set on both axes. Output grows, because dispatch scaffolding is added around fragments that used to be plain statements. Runtime cost rises, because control flow that was a direct jump becomes a dispatch step.

That makes scoping the difference between a usable build and an unusable one:

• Apply it to what deserves it. Named configuration sets let you flatten src/licensing/** or src/pricing/** and leave marketing pages and vendor code on a lighter preset.
• Narrow further with inline directives when only one function in a file is the asset.
• Keep it off hot loops. Render paths, per-frame game updates, and large-list virtualisation are where dispatch overhead becomes visible. The measured picture per transform family is in does obfuscation slow down JavaScript.
• Measure, do not estimate. Profile the protected build on the paths your users actually exercise.

Rolling it out without a long debugging session

Because this transform restructures control flow, it depends on the engine getting several subtle JavaScript rules exactly right — var hoisting out of blocks, a function declared inside a loop body escaping to its enclosing scope, a class body counting as a nested scope, and carrying a return value out of a restructured loop. Each of those has been a real defect class in control-flow flattening implementations generally, including ours.

So sequence the rollout rather than flipping everything at once:

• Validate your project with the lighter options first — name mangling, then string handling — and get a green test run at each step.
• Enable ReorderCode and FlatTransform as one change, on one scoped part of the tree.
• Build with Code Formatter on so you can read the output when something misbehaves.
• Run compatibility validation, then your full suite. A flattening bug usually produces a wrong value, not a crash, which is exactly why a smoke test is not enough — see verifying an obfuscator did not break your code.
• Keep the identifier map for symbolication; flattened stack traces are unreadable without it.

Related

• VM Bytecode Protection — for selected functions where Flat Transform's static-state-machine is not enough, eligible Corporate and Enterprise accounts can ask about the VM beta.
• Move Nested Function — pairs well with Flat Transform.
• Protect Object Declaration — further hardens the transformed output.
• Deep Obfuscation — the identifier-level counterpart; the two are usually enabled together.