Static Hermes Typed Mode Compatibility - Investigation & Tracking

[schickling]

Summary

This discussion tracks the compatibility between Effect and Static Hermes typed mode - Facebook's ahead-of-time compiler that can compile TypeScript to native binaries with C/C++-like performance.

TL;DR: Effect is currently incompatible with Static Hermes typed mode due to several JavaScript patterns that the typed compiler doesn't support. This discussion documents the specific blockers and potential paths forward.

---

What is Static Hermes Typed Mode?

Static Hermes offers two compilation modes:

1. Untyped mode: Compiles JS to native binary but preserves dynamic JS semantics (essentially an AOT-compiled interpreter)
2. Typed mode (shermes -typed): Uses TypeScript/Flow type annotations to generate truly optimized native code, eliminating dynamic dispatch and enabling aggressive inlining

The typed mode is the interesting one for performance-critical applications, as it promises "predictable performance on par with C/C++".

---

Current Status: ❌ Incompatible

When attempting to compile bundled Effect code with shermes -typed, the compiler fails with 20+ errors before giving up.

Blocking Issues

1. Computed Property Names in Classes

Error: ft: computed property names in classes are unsupported

// Effect uses this pattern extensively for iterables and type branding
class SomeClass {
  [Symbol.iterator]() { /* ... */ }  // ❌ Not supported
  [TypeId] = TypeId;                  // ❌ Not supported
}

This is fundamental to how Effect implements iterables and type branding throughout the codebase.

2. Private Class Fields

Error: ft: unsupported class member ClassPrivateProperty

class SomeClass {
  #privateField;  // ❌ Not supported
}

3. Optional Chaining on Calls

Error: ft: optional call expression not supported

someFunction()?.method()  // ❌ Not supported

4. Dynamic Property Access

Error: ft: unsupported

globalThis[dynamicKey] = value  // ❌ Not supported

5. Complex Type Inference Patterns

The typed compiler falls back to any for many closure patterns and use of arguments, losing type benefits:

// Effect's dual() function triggers warnings like:
// "local variable may be used prior to declaration, assuming 'any'"

---

What Works: Untyped Mode ✅

Effect does work with Static Hermes untyped mode. All major features pass:

• Effect.succeed/fail/map/flatMap/gen/all/forEach
• Option, Either, Chunk
• Context, Layer (dependency injection)
• Schema (with TextDecoder/TextEncoder polyfills)
• Stream

However, untyped mode is ~3x slower than Node.js for Effect operations, making it less attractive for performance-focused use cases.

---

Potential Paths Forward

Option 1: Wait for Static Hermes to Expand Support

Static Hermes is under active development. Relevant tracking issues:

• Computed property names support: No specific issue filed
• facebook/hermes#1349: Type inference for untyped JS

Option 2: Effect Compilation Target

Create a build/compilation step that transforms Effect's patterns into typed-mode-compatible code:

• Replace [Symbol.iterator]() with explicit iterator implementations
• Replace private fields with closures or WeakMaps
• Eliminate optional chaining on calls

This would be complex and require maintaining a parallel "static-hermes-compatible" build.

Option 3: Effect-lite for Static Hermes

Create a minimal subset of Effect that avoids incompatible patterns, designed specifically for AOT compilation scenarios.

Option 4: Alternative AOT Compilers

Explore other TypeScript-to-native paths:

• Bun's native compilation (experimental)
• Other emerging AOT compilers

---

Experiment Details

Full experiment report with test code, benchmarks, and detailed error analysis:
https://gist.github.com/schickling/e53f0e65b772c0e62492c99afe3ae2cf

Environment

• Static Hermes: static_h branch (December 2025)
• Effect: 3.19.12
• Platform: macOS arm64

Reproduction

# Clone and build Static Hermes
git clone --branch static_h https://github.com/facebook/hermes.git
cmake -S hermes -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build ./build

# Bundle Effect code
esbuild ./app.ts --bundle --outfile=./dist/app.js --platform=neutral --format=esm

# Attempt typed compilation (will fail with Effect)
./build/bin/shermes -typed -exec ./dist/app.js

---

Questions for Discussion

1. Is AOT native compilation a priority use case for Effect?
2. Would a "static-hermes-compatible" build target be valuable?
3. Are there other AOT compilation approaches the community is interested in?

---

This discussion was created based on experimental investigation. Please share any additional findings or alternative approaches!