[Feature Request] API for `jsi::Symbol::wellKnown(...)` - e.g. `Symbol.dispose`
- 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
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