Skip to content

Commit

Permalink
FAQ. Add new item concerning unsafeCast & asDynamic (#2255)
Browse files Browse the repository at this point in the history
* FAQ. Add new question & answer

* FAQ. Wrappers -> external declarations

* FAQ. Describe the purpose of `unsafeCast` and `asDynamic`

* FAQ. Define responsibility area for factories creation

* FAQ. Add a link for issue creation

* FAQ. Add a list for typical use cases. Blockquote for a opaque alias definition

* FAQ. & -> or

* FAQ. Fix link

* FAQ. Make an answer more consise

* FAQ. `or` -> `and`

* FAQ. `library author` -> `author of declarations`

* FAQ. `author of declarations` -> `declarations' owner`

* FAQ. Wording
  • Loading branch information
porotkin committed May 13, 2024
1 parent 4f4efa9 commit 1ff0d83
Showing 1 changed file with 27 additions and 1 deletion.
28 changes: 27 additions & 1 deletion FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,30 @@ JS equivalent:
const instance = {
foo: "bar",
}
```
```

_Q_: Why should I avoid `unsafeCast` & `asDynamic` when working with Wrappers?
_A_: First of all, `unsafeCast` and `asDynamic` are not recommended for external declarations, unless you are a declarations' owner. \
Some types' instances cannot be created by constructor invocation or interface implementation. For such types, we
provide a strict factory functions. It is a responsibility of library authors.
Example:

```kotlin
sealed external interface ClassName

inline fun ClassName(
value: String,
): ClassName =
value.unsafeCast<ClassName>()

val value = ClassName("my-class")
```

If there is no strict factory function for a type of this kind, please, [create an issue](https://github.com/JetBrains/kotlin-wrappers/issues).
Otherwise, when you use `unsafeCast` or `asDynamic`, the type can be incorrect when a library updates.

Typical use cases are:
- `JSO` (look at the previous item for JSO creation example)
- Opaque alias
> **Opaque alias** is the interface that mimicry another external interface but incapsulates some logic inside (e.g.,
a `String` opaque interface without any string operations).

0 comments on commit 1ff0d83

Please sign in to comment.