diff --git a/packages/docs-worklets/docs/fundamentals/glossary.mdx b/packages/docs-worklets/docs/fundamentals/glossary.mdx index 6eb426b94088..81449fa69812 100644 --- a/packages/docs-worklets/docs/fundamentals/glossary.mdx +++ b/packages/docs-worklets/docs/fundamentals/glossary.mdx @@ -79,8 +79,10 @@ The plugin performs automatic [workletization](/docs/fundamentals/glossary#to-wo 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). -## Shareable +## Serializable - +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. -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. +## SerializableRef + +A `SerializableRef` is a reference to a `Serializable` object. \ No newline at end of file diff --git a/packages/docs-worklets/docs/memory/createSerializabe.mdx b/packages/docs-worklets/docs/memory/createSerializabe.mdx new file mode 100644 index 000000000000..881954b0a684 --- /dev/null +++ b/packages/docs-worklets/docs/memory/createSerializabe.mdx @@ -0,0 +1,81 @@ +--- +sidebar_position: 1 +--- + +# createSerializable + +`createSerializable` recursively converts JavaScript values into serializable references that can be used on different Runtimes than RN Runtime. +The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Serializable`. +It handles various data types including primitives, objects, arrays, functions, and special cases like host objects and worklets. +To prevent misconceptions Worklets library freezes the original value for object-like values and for arrays. + +![Serializable](/img/serializable.png) +
Serializable flow diagram
+ +**Functions like `runOnUI`, `runOnRuntime`, `runOnJS`, `executeOnUIRuntimeSync` and `runOnUIAsync` automatically convert values to `Serializable` references.** + +## Usage + +```tsx +import { createSerializable, runOnUI } from 'react-native-worklets'; + +const object = { + a: 1, + b: 2, + c: 4, +}; + +object.c = 3; // <-- Correct: you can modify the object before serializing it + +createSerializable(object); + +object.a = 10; // <-- Warning: You can't mutate the object after serializing it + +runOnUI(() => { + object.a = 10; // <-- Warning: You can't mutate the object after serializing it + console.log(object); // { a: 1, b: 2, c: 3 } +})(); +``` + +
+Type definitions + +```typescript +type SerializableRef = { + __serializableRef: true; + __nativeStateSerializableJSRef: T; +}; + +function createSerializable(value: T): SerializableRef { + return value as SerializableRef; +} +``` + +
+ +## Remarks + +- The function automatically detects the type of the input value and applies appropriate serialization strategies. + +Supported types: + | Type | Supported | + |------|-----------| + | string | ✅ | + | number | ✅ | + | boolean | ✅ | + | object | ✅ | + | array | ✅ | + | function (non-worklet) | ✅ | + | HostObject | ✅ | + | worklet | ✅ | + | Map | ✅ | + | Set | ✅ | + | ArrayBuffer | ✅ | + | RegExp | ✅ | + | Cyclic objects | ❌ | + | Objects with custom prototype | ❌ | + +- For objects and arrays, it recursively processes nested properties +- The function includes cycle detection to prevent infinite recursion +- Objects are frozen after serialization to prevent accidental modifications that won't propagate to the Serializable +- Functions that aren't worklets are serialized as references to function instances on the respective runtime diff --git a/packages/docs-worklets/docs/memory/isSerializableRef.mdx b/packages/docs-worklets/docs/memory/isSerializableRef.mdx new file mode 100644 index 000000000000..a6e89e8d24fe --- /dev/null +++ b/packages/docs-worklets/docs/memory/isSerializableRef.mdx @@ -0,0 +1,29 @@ +--- +sidebar_position: 2 +--- + +# isSerializableRef + +`isSerializableRef` checks if a value is a serializable reference. + +## Reference + +```javascript +import { isSerializableRef, createSerializable } from 'react-native-worklets'; + +const object = { + a: 1, +}; + +const serializableRef = createSerializable(object); + +console.log(isSerializableRef(serializableRef)); // true +``` + +
+Type definitions + +```typescript +function isSerializableRef(value: unknown): value is SerializableRef +``` +
diff --git a/packages/docs-worklets/docs/memory/makeShareable.mdx b/packages/docs-worklets/docs/memory/makeShareable.mdx index 6c4b7fd04df5..97ebfa52f92a 100644 --- a/packages/docs-worklets/docs/memory/makeShareable.mdx +++ b/packages/docs-worklets/docs/memory/makeShareable.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 3 --- # makeShareable diff --git a/packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx b/packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx index 9dd3d63da785..1ae4dde47fb5 100644 --- a/packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx +++ b/packages/docs-worklets/docs/memory/makeShareableCloneOnUIRecursive.mdx @@ -1,9 +1,11 @@ --- -sidebar_position: 3 +sidebar_position: 5 --- # makeShareableCloneOnUIRecursive + + `makeShareableCloneOnUIRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than UI Runtime. The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`. To prevent misconceptions about it we freeze the original value for object-like values and for arrays. @@ -49,7 +51,3 @@ function makeShareableCloneOnUIRecursive( ``` - -## Platform compatibility - - \ No newline at end of file diff --git a/packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx b/packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx index edb80930a3ee..d5ba42c184af 100644 --- a/packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx +++ b/packages/docs-worklets/docs/memory/makeShareableCloneRecursive.mdx @@ -1,9 +1,11 @@ --- -sidebar_position: 2 +sidebar_position: 4 --- # makeShareableCloneRecursive + + `makeShareableCloneRecursive` recursively converts JavaScript values into shareable references that can be used on different Runtimes than RN Runtime. The reference cannot be manipulated, as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the `Shareable`. To prevent misconceptions about it we freeze the original value for object-like values and for arrays. @@ -41,7 +43,3 @@ function makeShareableCloneRecursive(value: T): ShareableRef { ``` - -## Platform compatibility - - \ No newline at end of file diff --git a/packages/docs-worklets/docs/threading/createWorkletRuntime.mdx b/packages/docs-worklets/docs/threading/createWorkletRuntime.mdx index b639c6ab6873..d6a2b81dcc2e 100644 --- a/packages/docs-worklets/docs/threading/createWorkletRuntime.mdx +++ b/packages/docs-worklets/docs/threading/createWorkletRuntime.mdx @@ -70,7 +70,3 @@ An optional worklet that will be run synchronously on the same thread immediatel - You can use Chrome DevTools to debug the runtime (Hermes only). The runtime will appear in the devices list as `name` passed to `createWorkletRuntime`. - 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. - -## Platform compatibility - - diff --git a/packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx b/packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx index e58318b9aac6..a6142285d17a 100644 --- a/packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx +++ b/packages/docs-worklets/docs/threading/executeOnUIRuntimeSync.mdx @@ -52,7 +52,3 @@ Don't forget to call the function returned from `executeOnUIRuntimeSync`. - 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). - Make sure not to execute `executeOnUIRuntimeSync` on the UI thread as this will result in an error. - -## Platform compatibility - - diff --git a/packages/docs-worklets/docs/threading/runOnJS.mdx b/packages/docs-worklets/docs/threading/runOnJS.mdx index ce2db6fe9438..18f22175d838 100644 --- a/packages/docs-worklets/docs/threading/runOnJS.mdx +++ b/packages/docs-worklets/docs/threading/runOnJS.mdx @@ -72,7 +72,3 @@ withTiming(0, {}, () => { - 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)`. - It's safe to run functions via `runOnJS` on the [JavaScript thread](/docs/fundamentals/glossary#javascript-thread), as this has no effect. - -## Platform compatibility - - diff --git a/packages/docs-worklets/docs/threading/runOnRuntime.mdx b/packages/docs-worklets/docs/threading/runOnRuntime.mdx index 59dae1fe2ba6..890b59d347f8 100644 --- a/packages/docs-worklets/docs/threading/runOnRuntime.mdx +++ b/packages/docs-worklets/docs/threading/runOnRuntime.mdx @@ -64,7 +64,3 @@ Don't forget to call the function returned from `runOnRuntime`. - You may call `runOnRuntime` on any runtime, including the RN runtime, UI runtime and other worklet runtimes. - 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. - -## Platform compatibility - - diff --git a/packages/docs-worklets/docs/threading/runOnUI.mdx b/packages/docs-worklets/docs/threading/runOnUI.mdx index 770463978ec0..6b5cbaa53fe5 100644 --- a/packages/docs-worklets/docs/threading/runOnUI.mdx +++ b/packages/docs-worklets/docs/threading/runOnUI.mdx @@ -72,7 +72,3 @@ import RunOnUISrc from '!!raw-loader!@site/src/examples/RunOnUI'; - Make sure not to execute `runOnUI` on the UI thread as this will result in an error. - In browsers there's no separate UI thread available. Because of that, on the Web, `runOnUI` behaves similarly to `requestAnimationFrame`. It creates a function that, when called, will be scheduled to run with given arguments on next animation frame. - -## Platform compatibility - - diff --git a/packages/docs-worklets/docs/threading/runOnUIAsync.mdx b/packages/docs-worklets/docs/threading/runOnUIAsync.mdx index 671b92b8cdcb..ddf9c582e6db 100644 --- a/packages/docs-worklets/docs/threading/runOnUIAsync.mdx +++ b/packages/docs-worklets/docs/threading/runOnUIAsync.mdx @@ -45,7 +45,3 @@ A reference to a function you want to execute on the UI thread. Arguments to you - 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). - Make sure not to execute `runOnUIAsync` on the UI thread as this will result in an error. - -## Platform compatibility - - diff --git a/packages/docs-worklets/src/components/PlatformCompatibility/index.tsx b/packages/docs-worklets/src/components/PlatformCompatibility/index.tsx deleted file mode 100644 index 3fd17718b11f..000000000000 --- a/packages/docs-worklets/src/components/PlatformCompatibility/index.tsx +++ /dev/null @@ -1,46 +0,0 @@ -import React from 'react'; - -interface BooleanIconProps { - value: boolean; -} - -function BooleanIcon({ value }: BooleanIconProps) { - return <>{value ? '✅' : '❌'}; -} - -interface PlatformCompatibilityProps { - android?: boolean; - ios?: boolean; - web?: boolean; -} - -export default function PlatformCompatibility({ - android = false, - ios = false, - web = false, -}: PlatformCompatibilityProps) { - return ( - - - - - - - - - - - - - - - -
AndroidiOSWeb
- - - - - -
- ); -} diff --git a/packages/docs-worklets/src/theme/MDXComponents.js b/packages/docs-worklets/src/theme/MDXComponents.js index 684c866c0f0a..59db13e9bf4f 100644 --- a/packages/docs-worklets/src/theme/MDXComponents.js +++ b/packages/docs-worklets/src/theme/MDXComponents.js @@ -1,7 +1,6 @@ // Import the original mapper import MDXComponents from '@theme-original/MDXComponents'; import InteractiveExample from '@site/src/components/InteractiveExample'; -import PlatformCompatibility from '@site/src/components/PlatformCompatibility'; import { Yes, No, Version, Spacer } from '@site/src/components/Compatibility'; import Indent from '@site/src/components/Indent'; import DeprecatedBanner from '@site/src/components/DeprecatedBanner'; @@ -12,7 +11,6 @@ export default { // Map the "" tag to our Highlight component // `Highlight` will receive all props that were passed to `` in MDX InteractiveExample, - PlatformCompatibility, Yes, No, Version, diff --git a/packages/docs-worklets/static/img/serializable.png b/packages/docs-worklets/static/img/serializable.png new file mode 100644 index 000000000000..d05a602a149f Binary files /dev/null and b/packages/docs-worklets/static/img/serializable.png differ