react-native-worklets 0.0.1-alpha → 0.1.0

package/src/WorkletsModule/JSWorklets.ts

@@ -0,0 +1,57 @@
+/* eslint-disable reanimated/use-reanimated-error */
+'use strict';
+
+import { mockedRequestAnimationFrame } from '../animationFrameQueue/mockedRequestAnimationFrame';
+import { isJest } from '../PlatformChecker';
+import { WorkletsError } from '../WorkletsError';
+import type { ShareableRef, WorkletRuntime } from '../workletTypes';
+import type { IWorkletsModule } from './workletsModuleProxy';
+
+export function createJSWorkletsModule(): IWorkletsModule {
+  return new JSWorklets();
+}
+
+// In Node.js environments (like when static rendering with Expo Router)
+// requestAnimationFrame is unavailable, so we use our mock.
+// It also has to be mocked for Jest purposes (see `initializeUIRuntime`).
+const requestAnimationFrameImpl =
+  isJest() || !globalThis.requestAnimationFrame
+    ? mockedRequestAnimationFrame
+    : globalThis.requestAnimationFrame;
+
+class JSWorklets implements IWorkletsModule {
+  makeShareableClone<TValue>(): ShareableRef<TValue> {
+    throw new WorkletsError(
+      'makeShareableClone should never be called in JSWorklets.'
+    );
+  }
+
+  scheduleOnUI<TValue>(worklet: ShareableRef<TValue>) {
+    // TODO: `requestAnimationFrame` should be used exclusively in Reanimated
+
+    // @ts-ignore web implementation has still not been updated after the rewrite,
+    // this will be addressed once the web implementation updates are ready
+    requestAnimationFrameImpl(worklet);
+  }
+
+  executeOnUIRuntimeSync<T, R>(_shareable: ShareableRef<T>): R {
+    throw new WorkletsError(
+      '`executeOnUIRuntimeSync` is not available in JSWorklets.'
+    );
+  }
+
+  createWorkletRuntime(
+    _name: string,
+    _initializer: ShareableRef<() => void>
+  ): WorkletRuntime {
+    throw new WorkletsError(
+      'createWorkletRuntime is not available in JSWorklets.'
+    );
+  }
+
+  scheduleOnRuntime() {
+    throw new WorkletsError(
+      'scheduleOnRuntime is not available in JSWorklets.'
+    );
+  }
+}

package/src/WorkletsModule/NativeWorklets.ts

@@ -0,0 +1,68 @@
+/* eslint-disable reanimated/use-reanimated-error */
+'use strict';
+
+import { WorkletsTurboModule } from '../specs';
+import { getValueUnpackerCode } from '../valueUnpacker';
+import { WorkletsError } from '../WorkletsError';
+import type { ShareableRef, WorkletRuntime } from '../workletTypes';
+import type { WorkletsModuleProxy } from './workletsModuleProxy';
+
+export interface IWorkletsModule extends WorkletsModuleProxy {}
+
+export function createNativeWorkletsModule(): IWorkletsModule {
+  return new NativeWorklets();
+}
+
+class NativeWorklets {
+  #workletsModuleProxy: WorkletsModuleProxy;
+
+  constructor() {
+    if (global.__workletsModuleProxy === undefined) {
+      const valueUnpackerCode = getValueUnpackerCode();
+      WorkletsTurboModule?.installTurboModule(valueUnpackerCode);
+    }
+    if (global.__workletsModuleProxy === undefined) {
+      throw new WorkletsError(
+        `Native part of Worklets doesn't seem to be initialized.
+See https://docs.swmansion.com/react-native-reanimated/docs/guides/troubleshooting#native-part-of-reanimated-doesnt-seem-to-be-initialized for more details.`
+      );
+    }
+    this.#workletsModuleProxy = global.__workletsModuleProxy;
+  }
+
+  makeShareableClone<TValue>(
+    value: TValue,
+    shouldPersistRemote: boolean,
+    nativeStateSource?: object
+  ) {
+    return this.#workletsModuleProxy.makeShareableClone(
+      value,
+      shouldPersistRemote,
+      nativeStateSource
+    );
+  }
+
+  scheduleOnUI<TValue>(shareable: ShareableRef<TValue>) {
+    return this.#workletsModuleProxy.scheduleOnUI(shareable);
+  }
+
+  executeOnUIRuntimeSync<TValue, TReturn>(
+    shareable: ShareableRef<TValue>
+  ): TReturn {
+    return this.#workletsModuleProxy.executeOnUIRuntimeSync(shareable);
+  }
+
+  createWorkletRuntime(name: string, initializer: ShareableRef<() => void>) {
+    return this.#workletsModuleProxy.createWorkletRuntime(name, initializer);
+  }
+
+  scheduleOnRuntime<T>(
+    workletRuntime: WorkletRuntime,
+    shareableWorklet: ShareableRef<T>
+  ) {
+    return this.#workletsModuleProxy.scheduleOnRuntime(
+      workletRuntime,
+      shareableWorklet
+    );
+  }
+}

package/src/WorkletsModule/index.ts

@@ -0,0 +1,7 @@
+'use strict';
+
+export { WorkletsModule } from './workletsModuleInstance';
+export type {
+  IWorkletsModule,
+  WorkletsModuleProxy,
+} from './workletsModuleProxy';

package/src/WorkletsModule/workletsModuleInstance.ts

@@ -0,0 +1,9 @@
+'use strict';
+
+import { shouldBeUseWeb } from '../PlatformChecker';
+import { createJSWorkletsModule } from './JSWorklets';
+import { createNativeWorkletsModule } from './NativeWorklets';
+
+export const WorkletsModule = shouldBeUseWeb()
+  ? 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,30 @@
+'use strict';
+
+import type { ShareableRef, WorkletRuntime } from '../workletTypes';
+
+/** Type of `__workletsModuleProxy` injected with JSI. */
+export interface WorkletsModuleProxy {
+  makeShareableClone<TValue>(
+    value: TValue,
+    shouldPersistRemote: boolean,
+    nativeStateSource?: object
+  ): ShareableRef<TValue>;
+
+  scheduleOnUI<TValue>(shareable: ShareableRef<TValue>): void;
+
+  executeOnUIRuntimeSync<TValue, TReturn>(
+    shareable: ShareableRef<TValue>
+  ): TReturn;
+
+  createWorkletRuntime(
+    name: string,
+    initializer: ShareableRef<() => void>
+  ): WorkletRuntime;
+
+  scheduleOnRuntime<TValue>(
+    workletRuntime: WorkletRuntime,
+    worklet: ShareableRef<TValue>
+  ): void;
+}
+
+export interface IWorkletsModule extends WorkletsModuleProxy {}

package/src/animationFrameQueue/mockedRequestAnimationFrame.ts

@@ -0,0 +1,11 @@
+'use strict';
+
+/**
+ * This is Jest implementation of `requestAnimationFrame` that is required by
+ * React Native for test purposes.
+ */
+export function mockedRequestAnimationFrame(
+  callback: (timestamp: number) => void
+): ReturnType<typeof setTimeout> {
+  return setTimeout(() => callback(performance.now()), 0);
+}

package/src/animationFrameQueue/requestAnimationFrame.ts

@@ -0,0 +1,41 @@
+'use strict';
+
+import { callMicrotasks } from '../threads';
+
+export function setupRequestAnimationFrame() {
+  'worklet';
+
+  // Jest mocks requestAnimationFrame API and it does not like if that mock gets overridden
+  // so we avoid doing requestAnimationFrame batching in Jest environment.
+  const nativeRequestAnimationFrame = global.requestAnimationFrame;
+
+  let animationFrameCallbacks: Array<(timestamp: number) => void> = [];
+  let flushRequested = false;
+
+  global.__flushAnimationFrame = (frameTimestamp: number) => {
+    const currentCallbacks = animationFrameCallbacks;
+    animationFrameCallbacks = [];
+    currentCallbacks.forEach((f) => f(frameTimestamp));
+    callMicrotasks();
+  };
+
+  global.requestAnimationFrame = (
+    callback: (timestamp: number) => void
+  ): number => {
+    animationFrameCallbacks.push(callback);
+    if (!flushRequested) {
+      flushRequested = true;
+      nativeRequestAnimationFrame((timestamp) => {
+        flushRequested = false;
+        global.__frameTimestamp = timestamp;
+        global.__flushAnimationFrame(timestamp);
+        global.__frameTimestamp = undefined;
+      });
+    }
+    // Reanimated currently does not support cancelling callbacks requested with
+    // requestAnimationFrame. We return -1 as identifier which isn't in line
+    // with the spec but it should give users better clue in case they actually
+    // attempt to store the value returned from rAF and use it for cancelling.
+    return -1;
+  };
+}

package/src/errors.ts

@@ -0,0 +1,103 @@
+'use strict';
+
+import type { WorkletStackDetails } from './workletTypes';
+
+export type CustomError<TName extends string> = Error & { name: TName }; // signed type
+
+export interface CustomErrorConstructor<TName extends string> extends Error {
+  new (message?: string): CustomError<TName>;
+  (message?: string): CustomError<TName>;
+  readonly prototype: CustomError<TName>;
+}
+
+export function createCustomError<TName extends string>(
+  name: TName
+): CustomErrorConstructor<TName> {
+  const constructor = function CustomError(message?: string) {
+    'worklet';
+    const prefix = `[${name}]`;
+    // eslint-disable-next-line reanimated/use-worklets-error
+    const errorInstance = new Error(message ? `${prefix} ${message}` : prefix);
+    errorInstance.name = `${name}Error`;
+    return errorInstance;
+  };
+
+  Object.defineProperty(constructor, 'name', { value: `${name}Error` });
+
+  return constructor as CustomErrorConstructor<TName>;
+}
+
+/** Registers custom errors in global scope. Use it only for Worklet runtimes. */
+export function registerCustomError<TName extends string>(
+  constructor: CustomErrorConstructor<TName>,
+  name: TName
+) {
+  'worklet';
+  if (!_WORKLET) {
+    // eslint-disable-next-line reanimated/use-worklets-error
+    throw new Error(
+      '[Worklets] registerCustomError() must be called on a Worklet runtime'
+    );
+  }
+  (global as Record<string, unknown>)[`${name}Error`] = constructor;
+}
+
+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 {
+  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 function reportFatalErrorOnJS({
+  message,
+  stack,
+  moduleName,
+}: {
+  message: string;
+  stack?: string;
+  moduleName: string;
+}) {
+  // eslint-disable-next-line reanimated/use-worklets-error
+  const error = new Error();
+  error.message = message;
+  error.stack = stack ? processStack(stack) : undefined;
+  error.name = `${moduleName}Error`;
+  // @ts-ignore React Native's ErrorUtils implementation extends the Error type with jsEngine field
+  error.jsEngine = moduleName;
+  // @ts-ignore the reportFatalError method is an internal method of ErrorUtils not exposed in the type definitions
+  global.ErrorUtils.reportFatalError(error);
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+'use strict';
+
+import { initializeUIRuntime } from './initializers';
+import { WorkletsModule } from './WorkletsModule';
+
+// TODO: Specify the initialization pipeline since now there's no
+// universal source of truth for it.
+initializeUIRuntime(WorkletsModule);
+
+export type { CustomError } from './errors';
+export { createCustomError, registerCustomError } from './errors';
+export type { LoggerConfig } from './logger';
+export {
+  logger,
+  LogLevel,
+  registerLoggerConfig,
+  updateLoggerConfig,
+} from './logger';
+export { createWorkletRuntime, runOnRuntime } from './runtimes';
+export { shareableMappingCache } from './shareableMappingCache';
+export {
+  makeShareable,
+  makeShareableCloneOnUIRecursive,
+  makeShareableCloneRecursive,
+} from './shareables';
+export {
+  callMicrotasks,
+  executeOnUIRuntimeSync,
+  runOnJS,
+  runOnUI,
+  runOnUIImmediately,
+} from './threads';
+export { isWorkletFunction } from './workletFunction';
+export type { IWorkletsModule, WorkletsModuleProxy } from './WorkletsModule';
+export { WorkletsModule } from './WorkletsModule';
+export type {
+  ShareableRef,
+  WorkletFunction,
+  WorkletFunctionDev,
+  WorkletRuntime,
+  WorkletStackDetails,
+} from './workletTypes';

package/src/initializers.ts

@@ -0,0 +1,175 @@
+'use strict';
+
+import { mockedRequestAnimationFrame } from './animationFrameQueue/mockedRequestAnimationFrame';
+import { setupRequestAnimationFrame } from './animationFrameQueue/requestAnimationFrame';
+import { reportFatalErrorOnJS } from './errors';
+import {
+  DEFAULT_LOGGER_CONFIG,
+  logToLogBoxAndConsole,
+  registerLoggerConfig,
+  replaceLoggerImplementation,
+} from './logger';
+import {
+  isChromeDebugger,
+  isJest,
+  isWeb,
+  shouldBeUseWeb,
+} from './PlatformChecker';
+import { executeOnUIRuntimeSync, runOnJS, setupMicrotasks } from './threads';
+import { registerWorkletsError, WorkletsError } from './WorkletsError';
+import type { IWorkletsModule } from './WorkletsModule';
+
+const IS_JEST = isJest();
+const SHOULD_BE_USE_WEB = shouldBeUseWeb();
+const IS_CHROME_DEBUGGER = isChromeDebugger();
+
+// Override the logFunction implementation with the one that adds logs
+// with better stack traces to the LogBox (need to override it after `runOnJS`
+// is defined).
+function overrideLogFunctionImplementation() {
+  'worklet';
+  replaceLoggerImplementation((data) => {
+    'worklet';
+    runOnJS(logToLogBoxAndConsole)(data);
+  });
+}
+
+// Register logger config and replace the log function implementation in
+// the React runtime global scope
+registerLoggerConfig(DEFAULT_LOGGER_CONFIG);
+overrideLogFunctionImplementation();
+
+// this is for web implementation
+if (SHOULD_BE_USE_WEB) {
+  global._WORKLET = false;
+  global._log = console.log;
+  global._getAnimationTimestamp = () => performance.now();
+} else {
+  // Register WorkletsError and logger config in the UI runtime global scope.
+  // (we are using `executeOnUIRuntimeSync` here to make sure that the changes
+  // are applied before any async operations are executed on the UI runtime)
+  executeOnUIRuntimeSync(registerWorkletsError)();
+  executeOnUIRuntimeSync(registerLoggerConfig)(DEFAULT_LOGGER_CONFIG);
+  executeOnUIRuntimeSync(overrideLogFunctionImplementation)();
+}
+
+// callGuard is only used with debug builds
+export function callGuardDEV<Args extends unknown[], ReturnValue>(
+  fn: (...args: Args) => ReturnValue,
+  ...args: Args
+): ReturnValue | void {
+  'worklet';
+  try {
+    return fn(...args);
+  } catch (e) {
+    if (global.__ErrorUtils) {
+      global.__ErrorUtils.reportFatalError(e as Error);
+    } else {
+      throw e;
+    }
+  }
+}
+
+export function setupCallGuard() {
+  'worklet';
+  global.__callGuardDEV = callGuardDEV;
+  global.__ErrorUtils = {
+    reportFatalError: (error: Error) => {
+      runOnJS(reportFatalErrorOnJS)({
+        message: error.message,
+        moduleName: 'Worklets',
+        stack: error.stack,
+      });
+    },
+  };
+}
+
+/**
+ * Currently there seems to be a bug in the JSI layer which causes a crash when
+ * we try to copy some of the console methods, i.e. `clear` or `dirxml`.
+ *
+ * The crash happens only in React Native 0.75. It's not reproducible in neither
+ * 0.76 nor 0.74. It also happens only in the configuration of a debug app and
+ * production bundle.
+ *
+ * I haven't yet discovered what exactly causes the crash. It's tied to the
+ * console methods sometimes being `HostFunction`s. Therefore, as a workaround
+ * we don't copy the methods as they are in the original console object, we copy
+ * JavaScript wrappers instead.
+ */
+function createMemorySafeCapturableConsole(): typeof console {
+  const consoleCopy = Object.fromEntries(
+    Object.entries(console).map(([methodName, method]) => {
+      const methodWrapper = function methodWrapper(...args: unknown[]) {
+        return method(...args);
+      };
+      if (method.name) {
+        /**
+         * Set the original method name as the wrapper name if available.
+         *
+         * It might be unnecessary but if we want to fully mimic the console
+         * object we should take into the account the fact some code might rely
+         * on the method name.
+         */
+        Object.defineProperty(methodWrapper, 'name', {
+          value: method.name,
+          writable: false,
+        });
+      }
+      return [methodName, methodWrapper];
+    })
+  );
+
+  return consoleCopy as unknown as typeof console;
+}
+
+// We really have to create a copy of console here. Function runOnJS we use on elements inside
+// this object makes it not configurable
+const capturableConsole = createMemorySafeCapturableConsole();
+
+export function setupConsole() {
+  'worklet';
+  if (!IS_CHROME_DEBUGGER) {
+    // @ts-ignore TypeScript doesn't like that there are missing methods in console object, but we don't provide all the methods for the UI runtime console version
+    global.console = {
+      /* eslint-disable @typescript-eslint/unbound-method */
+      assert: runOnJS(capturableConsole.assert),
+      debug: runOnJS(capturableConsole.debug),
+      log: runOnJS(capturableConsole.log),
+      warn: runOnJS(capturableConsole.warn),
+      error: runOnJS(capturableConsole.error),
+      info: runOnJS(capturableConsole.info),
+      /* eslint-enable @typescript-eslint/unbound-method */
+    };
+  }
+}
+
+export function initializeUIRuntime(WorkletsModule: IWorkletsModule) {
+  if (isWeb()) {
+    return;
+  }
+  if (!WorkletsModule) {
+    throw new WorkletsError(
+      'Worklets are trying to initialize the UI runtime without a valid WorkletsModule'
+    );
+  }
+  if (IS_JEST) {
+    // requestAnimationFrame react-native jest's setup is incorrect as it polyfills
+    // the method directly using setTimeout, therefore the callback doesn't get the
+    // expected timestamp as the only argument: https://github.com/facebook/react-native/blob/main/packages/react-native/jest/setup.js#L28
+    // We override this setup here to make sure that callbacks get the proper timestamps
+    // when executed. For non-jest environments we define requestAnimationFrame in setupRequestAnimationFrame
+    // @ts-ignore TypeScript uses Node definition for rAF, setTimeout, etc which returns a Timeout object rather than a number
+    globalThis.requestAnimationFrame = mockedRequestAnimationFrame;
+  }
+
+  if (!SHOULD_BE_USE_WEB) {
+    executeOnUIRuntimeSync(() => {
+      'worklet';
+      setupCallGuard();
+      setupConsole();
+      setupMicrotasks();
+      setupRequestAnimationFrame();
+    })();
+  }
+}

package/src/logger/LogBox.ts

@@ -0,0 +1,55 @@
+'use strict';
+/**
+ * Copied from: react-native/Libraries/LogBox/Data/LogBoxData.js
+ * react-native/Libraries/LogBox/Data/parseLogBoxLog.js
+ */
+
+import type { LogBoxStatic } from 'react-native';
+import { LogBox as RNLogBox } from 'react-native';
+
+export type LogBoxLogLevel = 'warn' | 'error' | 'fatal' | 'syntax';
+
+type Message = {
+  content: string;
+  substitutions: { length: number; offset: number }[];
+};
+
+type Category = string;
+
+interface Location {
+  row: number;
+  column: number;
+}
+
+interface CodeFrame {
+  content: string;
+  location?: Location | null;
+  fileName: string;
+  collapse?: boolean;
+}
+
+type ComponentStack = CodeFrame[];
+
+type ComponentStackType = 'legacy' | 'stack';
+
+export type LogData = {
+  level: LogBoxLogLevel;
+  message: Message;
+  category: Category;
+  componentStack: ComponentStack;
+  componentStackType: ComponentStackType | null;
+  stack?: string;
+};
+
+interface LogBoxExtended extends LogBoxStatic {
+  addLog(data: LogData): void;
+}
+
+const LogBox = RNLogBox as LogBoxExtended;
+
+const noop = () => {
+  // do nothing
+};
+
+// Do nothing when addLogBoxLog is called if LogBox is not available
+export const addLogBoxLog = LogBox?.addLog?.bind(LogBox) ?? noop;

package/src/logger/index.ts

@@ -0,0 +1,3 @@
+'use strict';
+export * from './LogBox';
+export * from './logger';