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!

[manimovassagh]

This is a really interesting investigation. A few thoughts on the compatibility question:

The typed mode blockers you identified are fundamental to how Effect is architected — computed property names for Symbol.iterator and type branding ([TypeId]) are not optional patterns, they are core to how the type system and protocol conformance work. Removing them would require rethinking the entire API surface.

For Option 2 (compilation target), this is probably the most viable path. A Babel/SWC transform that:

• Replaces [Symbol.iterator]() with an explicit @@iterator method or a wrapper
• Converts private fields to WeakMap-based implementations
• Desugars optional chaining on calls (foo?.() -> foo != null ? foo() : undefined)

These transforms already exist in the TypeScript/Babel ecosystem (they were needed for older ES targets). The challenge is that Static Hermes typed mode needs to understand the transformed output for type inference — and the WeakMap pattern for private fields would likely lose type information.

For Option 3 (Effect-lite), this might make the most practical sense for React Native scenarios. A minimal subset that covers Effect.gen, Effect.map/flatMap, Option, Either, Schema — the most commonly used features — without the full protocol machinery. Though maintaining two APIs is a significant burden.

Realistically, I think waiting for Static Hermes to expand its supported feature set (Option 1) is the path of least resistance. Computed property names and private fields are standard ECMAScript — not exotic patterns — so the Hermes team will likely need to support them eventually for broader TypeScript compatibility. Filing issues with the Hermes team for computed property names and optional call expressions would be the most impactful next step.

The untyped mode being 3x slower than Node.js is expected since Effect relies heavily on megamorphic call sites and closure allocation, which benefit enormously from V8's JIT optimizations that an AOT compiler cannot replicate without type information.