@amazon-devices/react-native-worklets 1.0.0-rn-83

package/src/WorkletsModule/workletsModuleInstance.ts

@@ -0,0 +1,9 @@
+'use strict';
+
+import { SHOULD_BE_USE_WEB } from '../PlatformChecker';
+import { createJSWorkletsModule } from './JSWorklets';
+import { createNativeWorkletsModule } from './NativeWorklets';
+
+export const WorkletsModule = SHOULD_BE_USE_WEB
+  ? createJSWorkletsModule()
+  : createNativeWorkletsModule();

package/src/WorkletsModule/workletsModuleInstance.web.ts

@@ -0,0 +1,5 @@
+'use strict';
+
+import { createJSWorkletsModule } from './JSWorklets';
+
+export const WorkletsModule = createJSWorkletsModule();

package/src/WorkletsModule/workletsModuleProxy.ts

@@ -0,0 +1,126 @@
+'use strict';
+
+import type { SynchronizableRef } from '../synchronizable';
+import type { SerializableRef, WorkletRuntime } from '../workletTypes';
+
+/** Type of `__workletsModuleProxy` injected with JSI. */
+export interface WorkletsModuleProxy {
+  createSerializable<TValue>(
+    value: TValue,
+    shouldPersistRemote: boolean,
+    nativeStateSource?: object
+  ): SerializableRef<TValue>;
+
+  createSerializableImport<TValue>(
+    source: string,
+    imported: string
+  ): SerializableRef<TValue>;
+
+  createSerializableString(str: string): SerializableRef<string>;
+
+  createSerializableNumber(num: number): SerializableRef<number>;
+
+  createSerializableBoolean(bool: boolean): SerializableRef<boolean>;
+
+  createSerializableBigInt(bigInt: bigint): SerializableRef<bigint>;
+
+  createSerializableUndefined(): SerializableRef<undefined>;
+
+  createSerializableNull(): SerializableRef<null>;
+
+  createSerializableTurboModuleLike<
+    TProps extends object,
+    TProto extends object,
+  >(
+    props: TProps,
+    proto: TProto
+  ): SerializableRef<TProps>;
+
+  createSerializableObject<T extends object>(
+    obj: T,
+    shouldRetainRemote: boolean,
+    nativeStateSource?: object
+  ): SerializableRef<T>;
+
+  createSerializableHostObject<T extends object>(obj: T): SerializableRef<T>;
+
+  createSerializableArray(
+    array: unknown[],
+    shouldRetainRemote: boolean
+  ): SerializableRef<unknown[]>;
+
+  createSerializableMap<TKey, TValue>(
+    keys: TKey[],
+    values: TValue[]
+  ): SerializableRef<Map<TKey, TValue>>;
+
+  createSerializableSet<TValues>(
+    values: TValues[]
+  ): SerializableRef<Set<TValues>>;
+
+  createSerializableInitializer(obj: object): SerializableRef<object>;
+
+  createSerializableFunction<TArgs extends unknown[], TReturn>(
+    func: (...args: TArgs) => TReturn
+  ): SerializableRef<TReturn>;
+
+  createSerializableWorklet(
+    worklet: object,
+    shouldPersistRemote: boolean
+  ): SerializableRef<object>;
+
+  scheduleOnUI<TValue>(serializable: SerializableRef<TValue>): void;
+
+  executeOnUIRuntimeSync<TValue, TReturn>(
+    serializable: SerializableRef<TValue>
+  ): TReturn;
+
+  createWorkletRuntime(
+    name: string,
+    initializer: SerializableRef<() => void>,
+    useDefaultQueue: boolean,
+    customQueue: object | undefined,
+    enableEventLoop: boolean
+  ): WorkletRuntime;
+
+  scheduleOnRuntime<TValue>(
+    workletRuntime: WorkletRuntime,
+    worklet: SerializableRef<TValue>
+  ): void;
+
+  reportFatalErrorOnJS(
+    message: string,
+    stack: string,
+    name: string,
+    jsEngine: string
+  ): void;
+
+  createSynchronizable<TValue>(value: TValue): SynchronizableRef<TValue>;
+
+  synchronizableGetDirty<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>
+  ): TValue;
+
+  synchronizableGetBlocking<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>
+  ): TValue;
+
+  synchronizableSetBlocking<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>,
+    value: SerializableRef<TValue>
+  ): void;
+
+  synchronizableLock<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>
+  ): void;
+
+  synchronizableUnlock<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>
+  ): void;
+
+  getStaticFeatureFlag(name: string): boolean;
+
+  setDynamicFeatureFlag(name: string, value: boolean): void;
+}
+
+export type IWorkletsModule = WorkletsModuleProxy;

package/src/bundleUnpacker.ts

@@ -0,0 +1,75 @@
+'use strict';
+import { logger } from './logger';
+import { WorkletsError } from './WorkletsError';
+import type { WorkletFactory, WorkletFunction } from './workletTypes';
+
+const handleCache = new WeakMap<WorkletFunction, unknown>();
+
+export function bundleValueUnpacker(
+  objectToUnpack: ObjectToUnpack,
+  category?: string,
+  remoteFunctionName?: string
+): unknown {
+  const workletHash = objectToUnpack.__workletHash;
+  if (workletHash !== undefined) {
+    return getWorklet(workletHash, objectToUnpack.__closure);
+  } else if (objectToUnpack.__init !== undefined) {
+    let value = handleCache.get(objectToUnpack);
+    if (value === undefined) {
+      value = objectToUnpack.__init();
+      handleCache.set(objectToUnpack, value);
+    }
+    return value;
+  } else if (category === 'RemoteFunction') {
+    const remoteFunctionHolder = () => {
+      const label = remoteFunctionName
+        ? `function \`${remoteFunctionName}\``
+        : 'anonymous function';
+      throw new WorkletsError(`Tried to synchronously call a non-worklet ${label} on the UI thread.
+See https://docs.swmansion.com/react-native-reanimated/docs/guides/troubleshooting#tried-to-synchronously-call-a-non-worklet-function-on-the-ui-thread for more details.`);
+    };
+    remoteFunctionHolder.__remoteFunction = objectToUnpack;
+    return remoteFunctionHolder;
+  } else {
+    throw new WorkletsError(
+      `Data type in category "${category}" not recognized by value unpacker: "${globalThis._toString(
+        objectToUnpack
+      )}".`
+    );
+  }
+}
+
+function getWorklet(
+  workletHash: number,
+  closureVariables: Record<string, unknown>
+): WorkletFunction | undefined {
+  let worklet;
+  if (__DEV__) {
+    try {
+      worklet = getWorkletFromMetroRequire(workletHash, closureVariables);
+    } catch (_e) {
+      logger.error(
+        'Unable to resolve worklet with hash ' +
+          workletHash +
+          '. Try reloading the app.'
+      );
+    }
+  } else {
+    worklet = getWorkletFromMetroRequire(workletHash, closureVariables);
+  }
+  return worklet;
+}
+
+const metroRequire = globalThis.__r;
+
+function getWorkletFromMetroRequire(
+  workletHash: number,
+  closureVariables: Record<string, unknown>
+): WorkletFunction {
+  const factory = metroRequire(workletHash).default as WorkletFactory;
+  return factory(closureVariables);
+}
+
+interface ObjectToUnpack extends WorkletFunction {
+  _recur: unknown;
+}

package/src/callGuard.ts

@@ -0,0 +1,33 @@
+'use strict';
+
+import type { RNError } from './errors';
+
+/** Used only with debug builds. */
+export function callGuardDEV<Args extends unknown[], ReturnValue>(
+  fn: (...args: Args) => ReturnValue,
+  ...args: Args
+): ReturnValue | void {
+  'worklet';
+  try {
+    return fn(...args);
+  } catch (error) {
+    if (globalThis.__workletsModuleProxy) {
+      const { message, stack, name, jsEngine } = error as RNError;
+      globalThis.__workletsModuleProxy.reportFatalErrorOnJS(
+        message,
+        stack ?? '',
+        name ?? 'WorkletsError',
+        jsEngine ?? 'Worklets'
+      );
+    } else {
+      throw error;
+    }
+  }
+}
+
+export function setupCallGuard() {
+  'worklet';
+  if (!globalThis.__callGuardDEV) {
+    globalThis.__callGuardDEV = callGuardDEV;
+  }
+}

package/src/deprecated.ts

@@ -0,0 +1,32 @@
+'use strict';
+
+import {
+  createSerializable,
+  isSerializableRef,
+  makeShareable,
+  makeShareableCloneOnUIRecursive,
+} from './serializable';
+import { serializableMappingCache } from './serializableMappingCache';
+import type { SerializableRef } from './workletTypes';
+
+/** @deprecated Use {@link SerializableRef} instead. */
+export type ShareableRef<T> = SerializableRef<T>;
+
+export { makeShareable, makeShareableCloneOnUIRecursive };
+
+/** @deprecated It will be removed in the next major version. */
+export type MakeShareableClone = <T>(
+  value: T,
+  shouldPersistRemote?: boolean,
+  depth?: number
+) => ShareableRef<T>;
+
+/** @deprecated Use {@link createSerializable} instead. */
+export const makeShareableCloneRecursive: MakeShareableClone =
+  createSerializable;
+
+/** @deprecated Use {@link isSerializableRef} instead. */
+export const isShareableRef = isSerializableRef;
+
+/** @deprecated Use {@link serializableMappingCache} instead. */
+export const shareableMappingCache = serializableMappingCache;

package/src/errors.ts

@@ -0,0 +1,80 @@
+'use strict';
+
+import { WorkletsError } from './WorkletsError';
+import type { WorkletStackDetails } from './workletTypes';
+
+const _workletStackDetails = new Map<number, WorkletStackDetails>();
+
+export function registerWorkletStackDetails(
+  hash: number,
+  stackDetails: WorkletStackDetails
+) {
+  _workletStackDetails.set(hash, stackDetails);
+}
+
+function getBundleOffset(error: Error): [string, number, number] {
+  const frame = error.stack?.split('\n')?.[0];
+  if (frame) {
+    const parsedFrame = /@([^@]+):(\d+):(\d+)/.exec(frame);
+    if (parsedFrame) {
+      const [, file, line, col] = parsedFrame;
+      return [file, Number(line), Number(col)];
+    }
+  }
+  return ['unknown', 0, 0];
+}
+
+function processStack(stack?: string): string | undefined {
+  if (stack === '' || stack === undefined) {
+    return undefined;
+  }
+  const workletStackEntries = stack.match(/worklet_(\d+):(\d+):(\d+)/g);
+  let result = stack;
+  workletStackEntries?.forEach((match) => {
+    const [, hash, origLine, origCol] = match.split(/:|_/).map(Number);
+    const errorDetails = _workletStackDetails.get(hash);
+    if (!errorDetails) {
+      return;
+    }
+    const [error, lineOffset, colOffset] = errorDetails;
+    const [bundleFile, bundleLine, bundleCol] = getBundleOffset(error);
+    const line = origLine + bundleLine + lineOffset;
+    const col = origCol + bundleCol + colOffset;
+
+    result = result.replace(match, `${bundleFile}:${line}:${col}`);
+  });
+  return result;
+}
+
+export interface RNError extends Error {
+  jsEngine: string;
+}
+
+/**
+ * Remote error is an error coming from a Worklet Runtime that we bubble up to
+ * the RN Runtime.
+ */
+export function reportFatalRemoteError(
+  { message, stack, name, jsEngine }: RNError,
+  force: boolean
+): void {
+  const error = new WorkletsError() as RNError;
+  error.message = message;
+  error.stack = processStack(stack);
+  error.name = name;
+  error.jsEngine = jsEngine;
+  if (force) {
+    throw error;
+  } else {
+    // @ts-expect-error React Native's `ErrorUtils` are hidden from the global scope.
+    globalThis.ErrorUtils.reportFatalError(error);
+  }
+}
+
+/**
+ * Registers `reportFatalRemoteError` function in global scope to allow to
+ * invoke it from C++.
+ */
+export function registerReportFatalRemoteError() {
+  globalThis.__reportFatalRemoteError = reportFatalRemoteError;
+}

package/src/featureFlags/index.ts

@@ -0,0 +1,72 @@
+'use strict';
+import { logger } from '../logger';
+import { WorkletsModule } from '../WorkletsModule';
+import type StaticFeatureFlagsJSON from './staticFlags.json';
+
+type DynamicFlagsType = {
+  EXAMPLE_DYNAMIC_FLAG: boolean;
+  init(): void;
+  setFlag(name: DynamicFlagName, value: boolean): void;
+};
+type DynamicFlagName = keyof Omit<Omit<DynamicFlagsType, 'setFlag'>, 'init'>;
+
+export const DynamicFlags: DynamicFlagsType = {
+  EXAMPLE_DYNAMIC_FLAG: true,
+
+  init() {
+    Object.keys(DynamicFlags).forEach((key) => {
+      if (key !== 'init' && key !== 'setFlag') {
+        WorkletsModule.setDynamicFeatureFlag(
+          key,
+          DynamicFlags[key as DynamicFlagName]
+        );
+      }
+    });
+  },
+  setFlag(name, value) {
+    if (name in DynamicFlags) {
+      DynamicFlags[name] = value;
+      WorkletsModule.setDynamicFeatureFlag(name, value);
+    } else {
+      logger.warn(
+        `The feature flag: '${name}' no longer exists, you can safely remove invocation of \`setDynamicFeatureFlag('${name}')\` from your code.`
+      );
+    }
+  },
+};
+DynamicFlags.init();
+// Public API function to update a feature flag
+export function setDynamicFeatureFlag(
+  name: DynamicFlagName,
+  value: boolean
+): void {
+  DynamicFlags.setFlag(name, value);
+}
+
+/**
+ * This constant is needed for typechecking and preserving static typechecks in
+ * generated .d.ts files. Without it, the static flags resolve to an object
+ * without specific keys.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const DefaultStaticFeatureFlags = {
+  RUNTIME_TEST_FLAG: false,
+  IOS_DYNAMIC_FRAMERATE_ENABLED: false,
+} as const satisfies typeof StaticFeatureFlagsJSON;
+
+type StaticFeatureFlagsSchema = {
+  -readonly [K in keyof typeof DefaultStaticFeatureFlags]: boolean;
+};
+
+const staticFeatureFlags: Partial<StaticFeatureFlagsSchema> = {};
+
+export function getStaticFeatureFlag(
+  name: keyof StaticFeatureFlagsSchema
+): boolean {
+  if (name in staticFeatureFlags) {
+    return staticFeatureFlags[name]!;
+  }
+  const featureFlagValue = WorkletsModule.getStaticFeatureFlag(name);
+  staticFeatureFlags[name] = featureFlagValue;
+  return featureFlagValue;
+}

package/src/featureFlags/staticFlags.json

@@ -0,0 +1,4 @@
+{
+  "RUNTIME_TEST_FLAG": false,
+  "IOS_DYNAMIC_FRAMERATE_ENABLED": true
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+'use strict';
+
+import './publicGlobals';
+
+import { init } from './initializers';
+import { bundleModeInit } from './workletRuntimeEntry';
+
+init();
+
+export type { MakeShareableClone, ShareableRef } from './deprecated';
+export {
+  isShareableRef,
+  makeShareable,
+  makeShareableCloneOnUIRecursive,
+  makeShareableCloneRecursive,
+  shareableMappingCache,
+} from './deprecated';
+export { getStaticFeatureFlag, setDynamicFeatureFlag } from './featureFlags';
+export { isSynchronizable } from './isSynchronizable';
+export { getRuntimeKind, RuntimeKind } from './runtimeKind';
+export { createWorkletRuntime, runOnRuntime } from './runtimes';
+export { createSerializable, isSerializableRef } from './serializable';
+export { serializableMappingCache } from './serializableMappingCache';
+export type { Synchronizable } from './synchronizable';
+export { createSynchronizable } from './synchronizable';
+export {
+  callMicrotasks,
+  executeOnUIRuntimeSync,
+  runOnJS,
+  runOnUI,
+  runOnUIAsync,
+  runOnUISync,
+  scheduleOnRN,
+  scheduleOnUI,
+  // eslint-disable-next-line camelcase
+  unstable_eventLoopTask,
+} from './threads';
+export { isWorkletFunction } from './workletFunction';
+export type { IWorkletsModule, WorkletsModuleProxy } from './WorkletsModule';
+export { WorkletsModule } from './WorkletsModule';
+export type {
+  SerializableRef,
+  WorkletFunction,
+  WorkletRuntime,
+  WorkletStackDetails,
+} from './workletTypes';
+
+// @ts-expect-error We must trick the bundler to include
+// the `workletRuntimeEntry` file the way it cannot optimize it out.
+if (globalThis._ALWAYS_FALSE) {
+  // Bundle mode.
+  bundleModeInit();
+}