# Minifier Assumptions

The Oxc minifier makes certain assumptions about JavaScript code to achieve optimal compression. These assumptions are standard for typical JavaScript but may not hold for unusual code patterns.

These assumptions are validated using ECMAScript operations from [`oxc_ecmascript`](../oxc_ecmascript), which implements spec-compliant behavior for type conversions, side effect analysis, and constant evaluation.

## Core Assumptions

These assumptions are held regardless of the options.

### No Monkey-Patching Built-ins

[Built-in objects and their methods and properties](https://tc39.es/ecma262/multipage/global-object.html#sec-global-object) behave as specified in ECMAScript.

```javascript
// The minifier assumes this never happens:
Array.prototype.push = function () {
  console.log("hijacked!");
};
Object.defineProperty(Number.prototype, "toString", { value: () => "hijacked!" });
```

### No `document.all` Usage

The deprecated [`document.all`](https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-IsHTMLDDA-internal-slot) with its special typeof behavior is not used.

```javascript
// The minifier assumes this never happens:
typeof document.all === "undefined"; // true in browsers
document.all && console.log("exists but falsy");
```

### No `with` Statement

Code does not use `with` statements which create ambiguous scope.

```
// The minifier assumes this never happens:
with (obj) {
  x = 1; // Is this obj.x or a global x?
}
```

### Coercion Methods Are Pure

`.toString()`, `.valueOf()`, and `[Symbol.toPrimitive]()` have no side effects. The minifier uses `oxc_ecmascript` type conversion utilities that assume standard coercion behavior.

```javascript
// The minifier assumes this never happens:
const obj = {
  toString() {
    console.log("side effect!");
    return "";
  },
};
String(obj); // Would trigger side effect
```

### No TDZ Violation

Code doesn't violate Temporal Dead Zones.

```javascript
// The minifier assumes this never happens:
console.log(x); // TDZ violation
let x = 1;
```

### No errors from Array/String/TypedArray Maximum Length

Creating strings, arrays, or typed arrays that exceed maximum length can be moved or removed.

```javascript
// The minifier may change when this error occurs:
try {
  new Array(2 ** 32); // RangeError
} catch {
  console.log("caught");
}
```

This also lets an unused `new Int8Array(n)` (or any TypedArray) with a numeric-literal `n` be dropped: a valid length allocates a zeroed buffer with no observable effect, and a too-large literal only throws a maximum-length `RangeError`. A non-literal, negative (`new Int8Array(-1)`), `BigInt` (`new Int8Array(0n)`), or object argument is kept.

### Coercion to a primitive does not throw for non-Symbol arguments

Pure global functions and methods that coerce their arguments (`parseInt`, `isNaN`, `Math.*`, `Date.UTC`, `String.fromCharCode`, …) are treated as side-effect-free, so an unused call is dropped. A Symbol argument would make `ToString` / `ToNumber` throw a `TypeError`, but the minifier assumes a non-Symbol argument when it cannot prove the type — so `Math.abs(x)` / `parseInt(x)` stay droppable.

```javascript
// The minifier assumes this never happens:
Math.abs(Symbol.iterator); // TypeError: Cannot convert a Symbol value to a number
```

A call is still kept when an argument _provably_ throws:

- `ToNumber` on a `BigInt` (`Math.abs(10n)`, `isNaN(10n)`, `Date.UTC(10n)`).
- `String.fromCodePoint(cp)` with a code point outside `[0, 0x10FFFF]` (`String.fromCodePoint(-1)`) — an "invalid code point" `RangeError`, distinct from the droppable maximum-length errors above.
- A missing or invalid required argument (`String.raw()`, `Symbol.keyFor()`, `URL.canParse()`).

### No side effects from extending a class

Extending a class does not have a side effect.

```javascript
const v = [];
class A extends v {} // TypeError
```

### Variables declared in direct `eval` are not referenced outside the eval

Variables declared in direct `eval` are not referenced outside the eval, which is only allowed in non-strict mode.

```javascript
// The minifier assumes this never happens:
eval("var x = 1");
console.log(x); // 1
```

### Known globals exist and are side-effect-free to access

Accessing known global identifiers (e.g. `Math`, `Array`, `Object`, `console`, `document`, `window`, DOM classes, etc.) does not throw a `ReferenceError` and has no side effects. Reading their properties (e.g. `Math.PI`, `Object.keys`) and select 3-level chains (e.g. `Object.prototype.hasOwnProperty`) are also side-effect-free. This list is ported from Rolldown's `GLOBAL_IDENT` set, which mirrors Rollup's [`knownGlobals`](https://github.com/rollup/rollup/blob/e3d65918b7527c24093534d9f8a10e715f6c30c3/src/ast/nodes/shared/knownGlobals.ts#L171), and includes browser/host-specific APIs intentionally.

```javascript
// The minifier assumes these are always available:
Math.PI; // side-effect-free
Array.isArray; // side-effect-free
console; // side-effect-free to access (calling methods may still have side effects)
```

### No side effects from accessing to a global variable named `arguments`

Accessing a global variable named `arguments` does not have a side effect. We intend to change this assumption to optional in the future.

```javascript
// The minifier assumes this never happens:
console.log(arguments); // ReferenceError: arguments is not defined
```

### Property writes to provably-unused local bindings are effect-free

In full-minify mode, a plain `=` write to a property of a local binding is
dropped when the binding is provably unused: it holds a fresh value (object /
array / function / class literal with no getters, setters, or `__proto__`), is
not exported, and every reference to it is itself a property-write target
(terser parity — `function A() {} A.from = () => {};` is removed entirely).

This assumes `Object.prototype` / `Function.prototype` / `Array.prototype`
properties are not setters with side effects that such writes would trigger (the
same class of assumption as the `property_write_side_effects: false` tree-shaking
option, but applied only to this narrow provably-unused case). This is the only
unsoundness in this optimization.

Writes that would themselves throw a strict-mode `TypeError` or have an
observable value-domain effect are kept via a kind-aware key denylist: the
non-writable own `name` / `length` and the `caller` / `arguments` poison of a
function or class, a class's non-writable `prototype`, an instance-private
brand-check write (`o.#x = 1`), and an `Array` `length` write (which can throw a
`RangeError` or run a `valueOf` coercion). A plain function's `prototype` is
writable, so `f.prototype = {...}` still drops.

Writes are NOT dropped when any other operation on the binding could observe
them: compound / logical assignments and updates (`o.x += 1` reads the
property), chained writes (`a.b.c = 1` reads `a.b`), `delete` of a nested
member, or writes through `__proto__` / non-literal computed keys (which may
install setters).

```javascript
// The minifier assumes this never happens:
Object.defineProperty(Object.prototype, "x", {
  set() {
    console.log("side effect!");
  },
});
var o = {};
o.x = 1; // dropped — would have logged
```

### `Function.prototype.toString` is not relied on

Code does not depend on [`Function.prototype.toString()`](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-function.prototype.tostring) returning specific source text. Minification renames variables and parameters, simplifies expressions (`true` → `!0`), restructures statements (fusing with the comma operator, converting `while` to `for`), removes whitespace, and may eliminate function bodies entirely (e.g. IIFE inlining). All of these change the string returned by `.toString()`.

```javascript
const serialize = (fn) => fn.toString();
serialize((x) => {
  return x * 2;
}); // Relied on to contain "return"
```

## Optional Assumptions

### No Reliance on Function.prototype.name

Code doesn't depend on function names being preserved. This assumption is held by default. This can be changed by settings `keepNames` option.

```javascript
// The minifier assumes this never happens:
function myFunc() {}
if (myFunc.name !== "myFunc") throw Error();
```

## Configuration

Optional assumptions can be configured in the minifier options if your code requires different behavior.

```rust
pub struct CompressOptions {
    // Control optimization behavior
    pub drop_console: bool,
    pub drop_debugger: bool,
    pub join_vars: bool,
    pub sequences: bool,
    pub unused: CompressOptionsUnused,
    pub keep_names: CompressOptionsKeepNames,

    // Tree-shaking options affect side effect analysis
    pub treeshake: TreeShakeOptions,
}

pub struct TreeShakeOptions {
    // Whether property reads have side effects
    pub property_read_side_effects: PropertyReadSideEffects,
    // Whether property writes have side effects
    pub property_write_side_effects: bool,
    // Whether accessing unknown globals has side effects
    pub unknown_global_side_effects: bool,
    // Respect pure annotations like /* @__PURE__ */
    pub annotations: bool,
}
```

## Validation

To ensure your code works with these assumptions:

1. **Test thoroughly**: Run your test suite on minified code
2. **Use conformance tests**: `cargo coverage` runs test262, Babel, TypeScript tests
3. **Node.js compatibility**: The minifier is validated against Node.js compatibility tables
4. **Try real-world code**: Test with your actual application
5. **Report issues**: If valid code breaks, file an issue

### Node.js Compatibility Testing

The minifier includes comprehensive validation against Node.js compatibility tables to ensure optimizations work correctly across different Node.js versions and environments.

## When Assumptions Don't Hold

If your code violates these assumptions, you may:

1. Refactor code to follow standard patterns
2. Disable specific optimizations
3. Use a different minifier configuration
4. Report the issue for consideration
