Skip to content

Commit f67b2e6

Browse files
skusnierzskusnierz
authored
feat: Serializable docs (#8043)
## Summary This PR adds the pages `createSerializable` and `isSerializableRef` to `worklets-docs`, marks ‘makeShareableCloneOnUIRecursive’ and “makeShareableCloneRecursive” as deprecated, and updates the glossary. ## Test plan Run `worklets-docs` locally : <img width="879" height="847" alt="image" src="https://github.com/user-attachments/assets/ee1d9230-cdf6-4ee6-b1a2-31e5d7ce0119" /> <img width="897" height="791" alt="image" src="https://github.com/user-attachments/assets/ee0de1f2-4670-485b-809d-8e5c0dd960e9" /> <img width="759" height="844" alt="image" src="https://github.com/user-attachments/assets/02f7344e-f02c-42c1-ad90-8265de73e2b2" />
1 parent fc933cf commit f67b2e6

15 files changed

Lines changed: 122 additions & 86 deletions

‎packages/docs-worklets/docs/fundamentals/glossary.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,10 @@ The plugin performs automatic [workletization](/docs/fundamentals/glossary#to-wo
7979

8080
You can learn the details by reading the [Reanimated Babel plugin README](https://github.com/software-mansion/react-native-reanimated/blob/main/packages/react-native-worklets/plugin/README-dev.md).
8181

82-
## Shareable
82+
## Serializable
8383

84-
<DeprecatedBanner />
84+
A Serializable is an object that represents a JavaScript value that can be copied between [Worklet Runtimes](/docs/fundamentals/glossary/#worklet-runtime). JavaScript values cannot be passed to other runtimes without prior serialization.
8585

86-
A `Shareable` is an object which can be assigned to a specific [Worklet Runtime](/docs/fundamentals/glossary#worklet-runtime), where it's shared across worklets in the same runtime.
86+
## SerializableRef
87+
88+
A `SerializableRef` is a reference to a `Serializable` object.

‎packages/docs-worklets/docs/memory/createSerializabe.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# createSerializable
6+
7+
`createSerializable` recursively converts JavaScript values into serializable references that can be used on different Runtimes than RN Runtime.
8+
The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Serializable`.
9+
It handles various data types including primitives, objects, arrays, functions, and special cases like host objects and worklets.
10+
To prevent misconceptions Worklets library freezes the original value for object-like values and for arrays.
11+
12+
![Serializable](/img/serializable.png)
13+
<figcaption style={{ textAlign: 'center' }}>Serializable flow diagram</figcaption>
14+
15+
**Functions like `runOnUI`, `runOnRuntime`, `runOnJS`, `executeOnUIRuntimeSync` and `runOnUIAsync` automatically convert values to `Serializable` references.**
16+
17+
## Usage
18+
19+
```tsx
20+
import { createSerializable, runOnUI } from 'react-native-worklets';
21+
22+
const object = {
23+
a: 1,
24+
b: 2,
25+
c: 4,
26+
};
27+
28+
object.c = 3; // <-- Correct: you can modify the object before serializing it
29+
30+
createSerializable(object);
31+
32+
object.a = 10; // <-- Warning: You can't mutate the object after serializing it
33+
34+
runOnUI(() => {
35+
object.a = 10; // <-- Warning: You can't mutate the object after serializing it
36+
console.log(object); // { a: 1, b: 2, c: 3 }
37+
})();
38+
```
39+
40+
<details>
41+
<summary>Type definitions</summary>
42+
43+
```typescript
44+
type SerializableRef<T = unknown> = {
45+
__serializableRef: true;
46+
__nativeStateSerializableJSRef: T;
47+
};
48+
49+
function createSerializable<T>(value: T): SerializableRef<T> {
50+
return value as SerializableRef<T>;
51+
}
52+
```
53+
54+
</details>
55+
56+
## Remarks
57+
58+
- The function automatically detects the type of the input value and applies appropriate serialization strategies.
59+
60+
Supported types:
61+
| Type | Supported |
62+
|------|-----------|
63+
| string | ✅ |
64+
| number | ✅ |
65+
| boolean | ✅ |
66+
| object | ✅ |
67+
| array | ✅ |
68+
| function (non-worklet) | ✅ |
69+
| HostObject | ✅ |
70+
| worklet | ✅ |
71+
| Map | ✅ |
72+
| Set | ✅ |
73+
| ArrayBuffer | ✅ |
74+
| RegExp | ✅ |
75+
| Cyclic objects | ❌ |
76+
| Objects with custom prototype | ❌ |
77+
78+
- For objects and arrays, it recursively processes nested properties
79+
- The function includes cycle detection to prevent infinite recursion
80+
- Objects are frozen after serialization to prevent accidental modifications that won't propagate to the Serializable
81+
- Functions that aren't worklets are serialized as references to function instances on the respective runtime

‎packages/docs-worklets/docs/memory/isSerializableRef.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# isSerializableRef
6+
7+
`isSerializableRef` checks if a value is a serializable reference.
8+
9+
## Reference
10+
11+
```javascript
12+
import { isSerializableRef, createSerializable } from 'react-native-worklets';
13+
14+
const object = {
15+
a: 1,
16+
};
17+
18+
const serializableRef = createSerializable(object);
19+
20+
console.log(isSerializableRef(serializableRef)); // true
21+
```
22+
23+
<details>
24+
<summary>Type definitions</summary>
25+
26+
```typescript
27+
function isSerializableRef(value: unknown): value is SerializableRef
28+
```
29+
</details>

‎packages/docs-worklets/docs/memory/makeShareable.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 3
33
---
44

55
# makeShareable

‎packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 5
33
---
44

55
# makeShareableCloneOnUIRecursive
66

7+
<DeprecatedBanner />
8+
79
`makeShareableCloneOnUIRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than UI Runtime.
810
The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`.
911
To prevent misconceptions about it we freeze the original value for object-like values and for arrays.
@@ -49,7 +51,3 @@ function makeShareableCloneOnUIRecursive<T>(
4951
```
5052

5153
</details>
52-
53-
## Platform compatibility
54-
55-
<PlatformCompatibility android ios web />

‎packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 4
33
---
44

55
# makeShareableCloneRecursive
66

7+
<DeprecatedBanner text="⚠️ This function is deprecated and will be removed in the next major release. Use createSerializable instead." />
8+
79
`makeShareableCloneRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than RN Runtime.
810
The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`.
911
To prevent misconceptions about it we freeze the original value for object-like values and for arrays.
@@ -41,7 +43,3 @@ function makeShareableCloneRecursive<T>(value: T): ShareableRef<T> {
4143
```
4244

4345
</details>
44-
45-
## Platform compatibility
46-
47-
<PlatformCompatibility android ios web />

‎packages/docs-worklets/docs/threading/createWorkletRuntime.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,3 @@ An optional worklet that will be run synchronously on the same thread immediatel
7070
- You can use Chrome DevTools to debug the runtime (Hermes only). The runtime will appear in the devices list as `name` passed to `createWorkletRuntime`.
7171

7272
- Shared values are only partially supported in worklet runtimes. If you want to write to a shared value from the RN runtime and read it on the worklet runtime, you need to perform the assignment using [`runOnRuntime`](/docs/threading/runOnRuntime). Otherwise, the value will be updated only in the RN and UI runtimes.
73-
74-
## Platform compatibility
75-
76-
<PlatformCompatibility android ios />

‎packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,3 @@ Don't forget to call the function returned from `executeOnUIRuntimeSync`.
5252
- The callback passed as the argument is automatically [workletized](/docs/fundamentals/glossary#to-workletize) and ready to be run on the [UI thread](/docs/fundamentals/glossary#ui-thread).
5353

5454
- Make sure not to execute `executeOnUIRuntimeSync` on the UI thread as this will result in an error.
55-
56-
## Platform compatibility
57-
58-
<PlatformCompatibility android ios web />

‎packages/docs-worklets/docs/threading/runOnJS.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,3 @@ withTiming(0, {}, () => {
7272
- It's a common mistake to execute function inside of runOnJS like this: ~~`runOnJS(setValue(10))()`~~. Here, the correct usage would be `runOnJS(setValue)(10)`.
7373

7474
- It's safe to run functions via `runOnJS` on the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread), as this has no effect.
75-
76-
## Platform compatibility
77-
78-
<PlatformCompatibility android ios web />

‎packages/docs-worklets/docs/threading/runOnRuntime.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,3 @@ Don't forget to call the function returned from `runOnRuntime`.
6464
- You may call `runOnRuntime` on any runtime, including the RN runtime, UI runtime and other worklet runtimes.
6565

6666
- The function passed to `runOnRuntime` will be added to an execution queue on a separate thread and executed asynchronously on the specified worklet runtime. The functions will be executed in the order they were added to the queue.
67-
68-
## Platform compatibility
69-
70-
<PlatformCompatibility android ios />

0 commit comments

Comments
 (0)