facebook / facebook/hermes

[Feature Request] API for `jsi::Symbol::wellKnown(...)` - e.g. `Symbol.dispose`

Open
#1,807 6 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
11.3k
Forks
859
Avg merge
1h 30m
Merged PRs (30d)
3

Description

## Problem

Currently it's super hard to expose a native property using a `Symbol` as a name. `Symbol`s are generally pretty impossible to work with on the native side.

For example, in ES2023 (ES14) the `Symbol.dispose` (and the `using ...` syntax) was introduced in JS. In [Nitro](https://github.com/mrousavy/nitro) I actually have `dispose()` methods for every HybridObject, but they are literally just methods exposed under a property that has the string key `"dispose"`.

I would want to expose them using the `Symbol.dispose` key, which is a well-known symbol.

In JSI, there is no way to achieve this unless you use `eval` or `global()`.
This would be the current solution in JSI:

```cpp
auto symbol = runtime.global().getPropertyAsObject(runtime, "Symbol");
auto dispose = symbol.getProperty(runtime, "dispose").asSymbol(runtime);
```

## Solution

Would be super useful if we could add `jsi::Symbol::wellKnown(...)`, which would be a more convenient way of looking up well-known Symbols, and potentially also a faster, cached way of doing so.

```cpp
auto dispose = jsi::Symbol::wellKnown(runtime, "dispose");
```

## Additional Context

There's [many well known Symbols in JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols) - with this new API, overriding some of those symbols on native objects would be much easier - e.g. `Symbol.toStringTag` (for `toString()`), `Symbol.iterator` (for loops), `Symbol.hasInstance` (for `instanceof`), and more.

Contributor guide

Open the contributing guide

Research direction

Read the JSI Symbol API and trace the existing runtime.global().getPropertyAsObject(...).getProperty(...).asSymbol(...) lookup shown in the issue. Done means native callers can resolve well-known symbols such as Symbol.dispose, Symbol.toStringTag, and Symbol.iterator through the proposed API, with behavior and caching expectations clarified.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, javascript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.