react-native-worklets 0.0.1-alpha → 0.1.0

package/src/logger/logger.ts

@@ -0,0 +1,155 @@
+'use strict';
+import type { LogBoxLogLevel, LogData } from './LogBox';
+import { addLogBoxLog } from './LogBox';
+
+const DOCS_URL =
+  'https://docs.swmansion.com/react-native-reanimated/docs/debugging/logger-configuration';
+const DOCS_REFERENCE = `If you don't want to see this message, you can disable the \`strict\` mode. Refer to:\n${DOCS_URL} for more details.`;
+
+type LogFunction = (data: LogData) => void;
+
+export enum LogLevel {
+  warn = 1,
+  error = 2,
+}
+
+export type LoggerConfig = {
+  level?: LogLevel;
+  strict?: boolean;
+};
+
+export type LoggerConfigInternal = {
+  logFunction: LogFunction;
+} & Required<LoggerConfig>;
+
+function logToConsole(data: LogData) {
+  'worklet';
+  switch (data.level) {
+    case 'warn':
+      console.warn(data.message.content);
+      break;
+    case 'error':
+    case 'fatal':
+    case 'syntax':
+      console.error(data.message.content);
+      break;
+  }
+}
+
+export const DEFAULT_LOGGER_CONFIG: LoggerConfigInternal = {
+  logFunction: logToConsole,
+  level: LogLevel.warn,
+  strict: true,
+};
+
+function formatMessage(message: string) {
+  'worklet';
+  return `[Worklets] ${message}`;
+}
+
+function createLog(level: LogBoxLogLevel, message: string): LogData {
+  'worklet';
+  const formattedMessage = formatMessage(message);
+
+  return {
+    level,
+    message: {
+      content: formattedMessage,
+      substitutions: [],
+    },
+    category: formattedMessage,
+    componentStack: [],
+    componentStackType: null,
+    // eslint-disable-next-line reanimated/use-worklets-error
+    stack: new Error().stack,
+  };
+}
+
+/**
+ * Function that logs to LogBox and console. Used to replace the default console
+ * logging with logging to LogBox on the UI thread when runOnJS is available.
+ *
+ * @param data - The details of the log.
+ */
+export function logToLogBoxAndConsole(data: LogData) {
+  addLogBoxLog(data);
+  logToConsole(data);
+}
+
+/**
+ * Registers the logger configuration. use it only for Worklet runtimes.
+ *
+ * @param config - The config to register.
+ */
+export function registerLoggerConfig(config: LoggerConfigInternal) {
+  'worklet';
+  global.__workletsLoggerConfig = config;
+}
+
+/**
+ * Replaces the default log function with a custom implementation.
+ *
+ * @param logFunction - The custom log function.
+ */
+export function replaceLoggerImplementation(logFunction: LogFunction) {
+  'worklet';
+  registerLoggerConfig({ ...global.__workletsLoggerConfig, logFunction });
+}
+
+/**
+ * Updates logger configuration.
+ *
+ * @param options - The new logger configuration to apply.
+ *
+ *   - Level: The minimum log level to display.
+ *   - Strict: Whether to log warnings and errors that are not strict. Defaults to
+ *       false.
+ */
+export function updateLoggerConfig(options?: Partial<LoggerConfig>) {
+  'worklet';
+  registerLoggerConfig({
+    ...global.__workletsLoggerConfig,
+    // Don't reuse previous level and strict values from the global config
+    level: options?.level ?? DEFAULT_LOGGER_CONFIG.level,
+    strict: options?.strict ?? DEFAULT_LOGGER_CONFIG.strict,
+  });
+}
+
+type LogOptions = {
+  strict?: boolean;
+};
+
+function handleLog(
+  level: Exclude<LogBoxLogLevel, 'syntax' | 'fatal'>,
+  message: string,
+  options: LogOptions
+) {
+  'worklet';
+  const config = global.__workletsLoggerConfig;
+  if (
+    // Don't log if the log is marked as strict-only and the config doesn't
+    // enable strict logging
+    (options.strict && !config.strict) ||
+    // Don't log if the log level is below the minimum configured level
+    LogLevel[level] < config.level
+  ) {
+    return;
+  }
+
+  if (options.strict) {
+    message += `\n\n${DOCS_REFERENCE}`;
+  }
+
+  config.logFunction(createLog(level, message));
+}
+
+export const logger = {
+  warn(message: string, options: LogOptions = {}) {
+    'worklet';
+    handleLog('warn', message, options);
+  },
+  error(message: string, options: LogOptions = {}) {
+    'worklet';
+    handleLog('error', message, options);
+  },
+};

package/src/privateGlobals.d.ts

@@ -0,0 +1,41 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable no-var */
+'use strict';
+
+// This file works by accident - currently Builder Bob doesn't move `.d.ts` files to output types.
+// If it ever breaks, we should address it so we'd not pollute the user's global namespace.
+import type { callGuardDEV } from './initializers';
+import type { WorkletsModuleProxy } from './WorkletsModule';
+
+declare global {
+  var __workletsCache: Map<string, any>;
+  var __handleCache: WeakMap<object, any>;
+  var evalWithSourceMap:
+    | ((js: string, sourceURL: string, sourceMap: string) => any)
+    | undefined;
+  var evalWithSourceUrl: ((js: string, sourceURL: string) => any) | undefined;
+  var _toString: (value: unknown) => string;
+  var __workletsModuleProxy: WorkletsModuleProxy | undefined;
+  var _WORKLET: boolean | undefined;
+  var _makeShareableClone: <T>(
+    value: T,
+    nativeStateSource?: object
+  ) => FlatShareableRef<T>;
+  var __callMicrotasks: () => void;
+  var _scheduleHostFunctionOnJS: (fun: (...args: A) => R, args?: A) => void;
+  var _scheduleRemoteFunctionOnJS: (fun: (...args: A) => R, args?: A) => void;
+  var __ErrorUtils: {
+    reportFatalError: (error: Error) => void;
+  };
+  var __callGuardDEV: typeof callGuardDEV | undefined;
+  var __flushAnimationFrame: (timestamp: number) => void;
+  var __frameTimestamp: number | undefined;
+  var __workletsLoggerConfig: LoggerConfigInternal;
+  var _log: (value: unknown) => void;
+  var _getAnimationTimestamp: () => number;
+  var _scheduleOnRuntime: (
+    runtime: WorkletRuntime,
+    worklet: ShareableRef<() => void>
+  ) => void;
+  var _microtaskQueueFinalizers: (() => void)[];
+}

package/src/runtimes.ts

@@ -0,0 +1,92 @@
+'use strict';
+
+import { setupCallGuard, setupConsole } from './initializers';
+import { registerLoggerConfig } from './logger';
+import { shouldBeUseWeb } from './PlatformChecker';
+import {
+  makeShareableCloneOnUIRecursive,
+  makeShareableCloneRecursive,
+} from './shareables';
+import { isWorkletFunction } from './workletFunction';
+import { registerWorkletsError, WorkletsError } from './WorkletsError';
+import { WorkletsModule } from './WorkletsModule';
+import type { WorkletFunction, WorkletRuntime } from './workletTypes';
+
+const SHOULD_BE_USE_WEB = shouldBeUseWeb();
+
+/**
+ * Lets you create a new JS runtime which can be used to run worklets possibly
+ * on different threads than JS or UI thread.
+ *
+ * @param name - A name used to identify the runtime which will appear in
+ *   devices list in Chrome DevTools.
+ * @param initializer - An optional worklet that will be run synchronously on
+ *   the same thread immediately after the runtime is created.
+ * @returns WorkletRuntime which is a
+ *   `jsi::HostObject<worklets::WorkletRuntime>` - {@link WorkletRuntime}
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/threading/createWorkletRuntime
+ */
+// @ts-expect-error Check `runOnUI` overload.
+export function createWorkletRuntime(
+  name: string,
+  initializer?: () => void
+): WorkletRuntime;
+
+export function createWorkletRuntime(
+  name: string,
+  initializer?: WorkletFunction<[], void>
+): WorkletRuntime {
+  // Assign to a different variable as __workletsLoggerConfig is not a captured
+  // identifier in the Worklet runtime.
+  const config = __workletsLoggerConfig;
+  return WorkletsModule.createWorkletRuntime(
+    name,
+    makeShareableCloneRecursive(() => {
+      'worklet';
+      registerWorkletsError();
+      registerLoggerConfig(config);
+      setupCallGuard();
+      setupConsole();
+      initializer?.();
+    })
+  );
+}
+
+// @ts-expect-error Check `runOnUI` overload.
+export function runOnRuntime<Args extends unknown[], ReturnValue>(
+  workletRuntime: WorkletRuntime,
+  worklet: (...args: Args) => ReturnValue
+): WorkletFunction<Args, ReturnValue>;
+/** Schedule a worklet to execute on the background queue. */
+export function runOnRuntime<Args extends unknown[], ReturnValue>(
+  workletRuntime: WorkletRuntime,
+  worklet: WorkletFunction<Args, ReturnValue>
+): (...args: Args) => void {
+  'worklet';
+  if (__DEV__ && !SHOULD_BE_USE_WEB && !isWorkletFunction(worklet)) {
+    throw new WorkletsError(
+      'The function passed to `runOnRuntime` is not a worklet.' +
+        (_WORKLET
+          ? ' Please make sure that `processNestedWorklets` option in Reanimated Babel plugin is enabled.'
+          : '')
+    );
+  }
+  if (_WORKLET) {
+    return (...args) =>
+      global._scheduleOnRuntime(
+        workletRuntime,
+        makeShareableCloneOnUIRecursive(() => {
+          'worklet';
+          worklet(...args);
+        })
+      );
+  }
+  return (...args) =>
+    WorkletsModule.scheduleOnRuntime(
+      workletRuntime,
+      makeShareableCloneRecursive(() => {
+        'worklet';
+        worklet(...args);
+      })
+    );
+}

package/src/shareableMappingCache.ts

@@ -0,0 +1,44 @@
+'use strict';
+import { shouldBeUseWeb } from './PlatformChecker';
+import type { ShareableRef } from './workletTypes';
+
+const SHOULD_BE_USE_WEB = shouldBeUseWeb();
+
+/**
+ * This symbol is used to represent a mapping from the value to itself.
+ *
+ * It's used to prevent converting a shareable that's already converted - for
+ * example a Shared Value that's in worklet's closure.
+ */
+export const shareableMappingFlag = Symbol('shareable flag');
+
+/*
+During a fast refresh, React holds the same instance of a Mutable
+(that's guaranteed by `useRef`) but `shareableCache` gets regenerated and thus
+becoming empty. This happens when editing the file that contains the definition of this cache.
+
+Because of it, `makeShareableCloneRecursive` can't find given mapping
+in `shareableCache` for the Mutable and tries to clone it as if it was a regular JS object.
+During cloning we use `Object.entries` to iterate over the keys which throws an error on accessing `_value`.
+For convenience we moved this cache to a separate file so it doesn't scare us with red squiggles.
+*/
+
+const cache = SHOULD_BE_USE_WEB
+  ? null
+  : new WeakMap<object, ShareableRef | symbol>();
+
+export const shareableMappingCache = SHOULD_BE_USE_WEB
+  ? {
+      set() {
+        // NOOP
+      },
+      get() {
+        return null;
+      },
+    }
+  : {
+      set(shareable: object, shareableRef?: ShareableRef): void {
+        cache!.set(shareable, shareableRef || shareableMappingFlag);
+      },
+      get: cache!.get.bind(cache),
+    };