@lynx-js/react 0.105.0 → 0.105.2

package/runtime/src/snapshot/ref.ts

@@ -3,13 +3,13 @@
 // LICENSE file in the root directory of this source tree.
 import type { Worklet, WorkletRef } from '@lynx-js/react/worklet-runtime/bindings';
 
-import { nextCommitTaskId } from '../lifecycle/patchUpdate.js';
+import { nextCommitTaskId } from '../lifecycle/patch/commit.js';
 import { SnapshotInstance, backgroundSnapshotInstanceManager } from '../snapshot.js';
 import { workletUnRef } from './workletRef.js';
 
 let globalRefPatch: Record<string, number | null> = {};
-let globalRefsToRemove: Map</* commitId */ number, Map</* sign */ string, /* ref */ any>> = /* @__PURE__ */ new Map();
-let globalRefsToSet: Map</* commitId */ number, Record<string, number>> = /* @__PURE__ */ new Map();
+const globalRefsToRemove: Map</* commitId */ number, Map</* sign */ string, /* ref */ any>> = /* @__PURE__ */ new Map();
+const globalRefsToSet: Map</* commitId */ number, Record<string, number>> = /* @__PURE__ */ new Map();
 let nextRefId = 1;
 
 function unref(snapshot: SnapshotInstance, recursive: boolean): void {
@@ -35,7 +35,7 @@ function unref(snapshot: SnapshotInstance, recursive: boolean): void {
 function applyRef(ref: any, value: any) {
   // TODO: ref: exceptions thrown in user functions should be able to be caught by an Error Boundary
   if (typeof ref == 'function') {
-    let hasRefUnmount = typeof ref._unmount == 'function';
+    const hasRefUnmount = typeof ref._unmount == 'function';
     if (hasRefUnmount) {
       // @ts-ignore TS doesn't like moving narrowing checks into variables
       ref._unmount();
@@ -54,7 +54,7 @@ function updateBackgroundRefs(commitId: number): void {
   const oldRefMap = globalRefsToRemove.get(commitId);
   if (oldRefMap) {
     globalRefsToRemove.delete(commitId);
-    for (let ref of oldRefMap.values()) {
+    for (const ref of oldRefMap.values()) {
       applyRef(ref, null);
     }
   }
@@ -65,10 +65,7 @@ function updateBackgroundRefs(commitId: number): void {
       const ref = backgroundSnapshotInstanceManager.getValueBySign(sign);
       if (ref) {
         // TODO: ref: support __REF_FIRE_IMMEDIATELY__
-        const v = newRefMap[sign]
-          && lynx.createSelectorQuery().selectUniqueID(
-            newRefMap[sign],
-          );
+        const v = newRefMap[sign] && lynx.createSelectorQuery().selectUniqueID(newRefMap[sign]);
         applyRef(ref, v);
       }
     }

package/runtime/src/snapshot.ts

@@ -6,7 +6,7 @@ import type { Worklet, WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bin
 import type { BackgroundSnapshotInstance } from './backgroundSnapshot.js';
 import { ListUpdateInfoRecording, __pendingListUpdates, snapshotDestroyList } from './list.js';
 import { unref } from './snapshot/ref.js';
-import { SnapshotOperation, __globalSnapshotPatch } from './snapshotPatch.js';
+import { SnapshotOperation, __globalSnapshotPatch } from './lifecycle/patch/snapshotPatch.js';
 import { isDirectOrDeepEqual } from './utils.js';
 
 export const enum DynamicPartType {

package/runtime/src/worklet/ctx.ts

@@ -3,20 +3,20 @@
 // LICENSE file in the root directory of this source tree.
 import type { Worklet } from '@lynx-js/react/worklet-runtime/bindings';
 
-import { lynxWorkletJsImpl } from './jsImpl.js';
+import { isMtsEnabled, isRunOnBackgroundEnabled } from './functionality.js';
+import { registerWorkletCtx } from './runOnBackground.js';
 
 /**
  * @internal
  */
 export function onPostWorkletCtx(afterValue: Worklet | null): Worklet | null {
-  const impl = lynxWorkletJsImpl();
-  if (!impl && afterValue) {
+  if (!isMtsEnabled() && afterValue) {
     lynx.reportError(new Error('Main thread script requires Lynx sdk version 2.14'));
     return null;
   }
-  if (!afterValue) {
+  if (!afterValue || !isRunOnBackgroundEnabled()) {
     return afterValue;
   }
-  impl?._workletExecIdMap?.add(afterValue);
+  registerWorkletCtx(afterValue);
   return afterValue;
 }

package/runtime/src/worklet/destroy.ts

@@ -0,0 +1,16 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { takeWorkletRefInitValuePatch } from './workletRefPool.js';
+
+export const destroyTasks: (() => void)[] = [];
+
+export function destroyWorklet(): void {
+  takeWorkletRefInitValuePatch();
+
+  for (const task of destroyTasks) {
+    task();
+  }
+  destroyTasks.length = 0;
+}

package/runtime/src/worklet/functionCall.ts

@@ -0,0 +1,42 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+import type { RunWorkletCtxRetData } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { destroyTasks } from './destroy.js';
+import { IndexMap } from './indexMap.js';
+
+let resolveMap: IndexMap<(value: any) => void> | undefined;
+
+function initReturnValueListener(): void {
+  const context: RuntimeProxy = __JS__ ? lynx.getCoreContext!() : lynx.getJSContext!();
+
+  resolveMap = new IndexMap();
+  context.addEventListener(WorkletEvents.FunctionCallRet, onFunctionCallRet);
+
+  destroyTasks.push(() => {
+    context.removeEventListener(WorkletEvents.FunctionCallRet, onFunctionCallRet);
+    resolveMap = undefined;
+  });
+}
+
+/**
+ * @internal
+ */
+function onFunctionCall(resolve: (value: any) => void): number {
+  if (!resolveMap) {
+    initReturnValueListener();
+  }
+  return resolveMap!.add(resolve);
+}
+
+function onFunctionCallRet(event: RuntimeProxy.Event): void {
+  const data = JSON.parse(event.data as string) as RunWorkletCtxRetData;
+  const resolve = resolveMap!.get(data.resolveId)!;
+  resolveMap!.remove(data.resolveId);
+  resolve(data.returnValue);
+}
+
+export { onFunctionCall };

package/runtime/src/worklet/functionality.ts

@@ -4,9 +4,32 @@
 
 import { isSdkVersionGt } from '../utils.js';
 
+let mtsEnabled: boolean | undefined;
+let runOnBackgroundEnabled: boolean | undefined;
+
 /**
  * @internal
  */
-export function enableRunOnBackground(): boolean {
-  return isSdkVersionGt(2, 15);
+function isMtsEnabled(): boolean {
+  if (mtsEnabled === undefined) {
+    mtsEnabled = isSdkVersionGt(2, 13);
+  }
+  return mtsEnabled;
 }
+
+/**
+ * @internal
+ */
+function isRunOnBackgroundEnabled(): boolean {
+  if (runOnBackgroundEnabled === undefined) {
+    runOnBackgroundEnabled = isSdkVersionGt(2, 15);
+  }
+  return runOnBackgroundEnabled;
+}
+
+function clearConfigCacheForTesting(): void {
+  mtsEnabled = undefined;
+  runOnBackgroundEnabled = undefined;
+}
+
+export { isMtsEnabled, isRunOnBackgroundEnabled, clearConfigCacheForTesting };

package/runtime/src/worklet/hmr.ts

@@ -1,7 +1,7 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import { SnapshotOperation, __globalSnapshotPatch } from '../snapshotPatch.js';
+import { SnapshotOperation, __globalSnapshotPatch } from '../lifecycle/patch/snapshotPatch.js';
 
 const workletHashSet: Set<string> = /* @__PURE__ */ new Set();
 

package/runtime/src/worklet/runOnBackground.ts

@@ -0,0 +1,125 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import type { JsFnHandle, RunWorkletCtxRetData, Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { destroyTasks } from './destroy.js';
+import { WorkletExecIdMap } from './execMap.js';
+import { isRunOnBackgroundEnabled } from './functionality.js';
+import { onFunctionCall } from './functionCall.js';
+
+/**
+ * @internal
+ */
+interface RunOnBackgroundData {
+  obj: JsFnHandle;
+  params: unknown[];
+  resolveId: number;
+}
+
+let execIdMap: WorkletExecIdMap | undefined;
+
+function init() {
+  'background only';
+  if (execIdMap) {
+    return;
+  }
+
+  execIdMap = new WorkletExecIdMap();
+  lynx.getCoreContext!().addEventListener(WorkletEvents.runOnBackground, runJSFunction);
+  lynx.getCoreContext!().addEventListener(WorkletEvents.releaseBackgroundWorkletCtx, releaseBackgroundWorkletCtx);
+
+  destroyTasks.push(() => {
+    lynx.getCoreContext!().removeEventListener(WorkletEvents.runOnBackground, runJSFunction);
+    lynx.getCoreContext!().removeEventListener(WorkletEvents.releaseBackgroundWorkletCtx, releaseBackgroundWorkletCtx);
+    execIdMap = undefined;
+  });
+}
+
+/**
+ * @internal
+ */
+function runJSFunction(event: RuntimeProxy.Event): void {
+  'background only';
+  const data = JSON.parse(event.data as string) as RunOnBackgroundData;
+  const obj = execIdMap!.findJsFnHandle(data.obj._execId!, data.obj._jsFnId);
+  const f = obj?._fn;
+  if (!f) {
+    throw new Error('runOnBackground: JS function not found: ' + JSON.stringify(data.obj));
+  }
+  const returnValue = f(...data.params);
+  lynx.getCoreContext!().dispatchEvent({
+    type: WorkletEvents.FunctionCallRet,
+    data: JSON.stringify({
+      resolveId: data.resolveId,
+      returnValue,
+    } as RunWorkletCtxRetData),
+  });
+}
+
+function releaseBackgroundWorkletCtx(event: RuntimeProxy.Event): void {
+  'background only';
+  for (const id of event.data) {
+    execIdMap!.remove(id as number);
+  }
+}
+
+/**
+ * @internal
+ */
+function registerWorkletCtx(ctx: Worklet): void {
+  'background only';
+  init();
+  execIdMap!.add(ctx);
+}
+
+/**
+ * `runOnBackground` allows triggering js functions on the background thread asynchronously.
+ * @param f - The js function to be called.
+ * @returns A function. Calling which with the arguments to be passed to the js function to trigger it on the background thread. This function returns a promise that resolves to the return value of the js function.
+ * @example
+ * ```ts
+ * import { runOnBackground } from '@lynx-js/react';
+ *
+ * async function someMainthreadFunction() {
+ *   'main thread';
+ *   const fn = runOnBackground(() => {
+ *     return 'hello';
+ *   });
+ *   const result = await fn();
+}
+ * ```
+ * @public
+ */
+function runOnBackground<R, Fn extends (...args: any[]) => R>(f: Fn): (...args: Parameters<Fn>) => Promise<R> {
+  if (!isRunOnBackgroundEnabled()) {
+    throw new Error('runOnBackground requires Lynx sdk version 2.16.');
+  }
+  if (__JS__) {
+    throw new Error('runOnBackground can only be used on the main thread.');
+  }
+  const obj = f as any as JsFnHandle;
+  if (obj._error) {
+    throw new Error(obj._error);
+  }
+  return async (...params: any[]): Promise<R> => {
+    return new Promise((resolve) => {
+      const resolveId = onFunctionCall(resolve);
+      lynx.getJSContext!().dispatchEvent({
+        type: WorkletEvents.runOnBackground,
+        data: JSON.stringify({
+          obj: {
+            _jsFnId: obj._jsFnId,
+            _execId: obj._execId!,
+          },
+          params,
+          resolveId,
+        } as RunOnBackgroundData),
+      });
+    });
+  };
+}
+
+export { registerWorkletCtx, runJSFunction, runOnBackground };

package/runtime/src/worklet/runOnMainThread.ts

@@ -0,0 +1,50 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { RunWorkletCtxData, Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
+
+import { onPostWorkletCtx } from './ctx.js';
+import { isMtsEnabled } from './functionality.js';
+import { onFunctionCall } from './functionCall.js';
+
+/**
+ * `runOnMainThread` allows triggering main thread functions on the main thread asynchronously.
+ * @param fn - The main thread functions to be called.
+ * @returns A function. Calling which with the arguments to be passed to the main thread function to trigger it on the main thread. This function returns a promise that resolves to the return value of the main thread function.
+ * @example
+ * ```ts
+ * import { runOnMainThread } from '@lynx-js/react';
+ *
+ * async function someFunction() {
+ *   const fn = runOnMainThread(() => {
+ *     'main thread';
+ *     return 'hello';
+ *   });
+ *   const result = await fn();
+ * }
+ * ```
+ * @public
+ */
+export function runOnMainThread<R, Fn extends (...args: any[]) => R>(fn: Fn): (...args: Parameters<Fn>) => Promise<R> {
+  if (__LEPUS__) {
+    throw new Error('runOnMainThread can only be used on the background thread.');
+  }
+  if (!isMtsEnabled()) {
+    throw new Error('runOnMainThread requires Lynx sdk version 2.14.');
+  }
+  return async (...params: any[]): Promise<R> => {
+    return new Promise((resolve) => {
+      onPostWorkletCtx(fn as any as Worklet);
+      const resolveId = onFunctionCall(resolve);
+      lynx.getCoreContext!().dispatchEvent({
+        type: WorkletEvents.runWorkletCtx,
+        data: JSON.stringify({
+          worklet: fn as any as Worklet,
+          params,
+          resolveId,
+        } as RunWorkletCtxData),
+      });
+    });
+  };
+}

package/runtime/src/worklet/transformToWorklet.ts

@@ -0,0 +1,26 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { JsFnHandle } from '@lynx-js/react/worklet-runtime/bindings';
+
+let lastId = 0;
+
+/**
+ * transform args of `runOnBackground()`.
+ *
+ * @internal
+ */
+export function transformToWorklet(obj: (...args: any[]) => any): JsFnHandle {
+  const id = ++lastId;
+  if (typeof obj !== 'function') {
+    // We save the error message in the object, so that we can throw it later when the function is called on the main thread.
+    return {
+      _jsFnId: id,
+      _error: `Argument of runOnBackground should be a function, but got [${typeof obj}] instead`,
+    };
+  }
+  return {
+    _jsFnId: id,
+    _fn: obj,
+  };
+}

package/runtime/src/worklet/workletRef.ts

@@ -6,10 +6,11 @@ import type { RefObject } from 'react';
 import type { WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bindings';
 import { WorkletEvents } from '@lynx-js/react/worklet-runtime/bindings';
 
-import { lynxWorkletJsImpl } from './jsImpl.js';
 import { addWorkletRefInitValue } from './workletRefPool.js';
 import { useMemo } from '../hooks/react.js';
 
+let lastId = 0;
+
 abstract class WorkletRef<T> {
   /**
    * @internal
@@ -33,8 +34,7 @@ abstract class WorkletRef<T> {
    */
   protected constructor(initValue: T, type: string) {
     if (__JS__) {
-      const impl = lynxWorkletJsImpl();
-      this._id = impl ? ++impl._workletRefLastId : 0;
+      this._id = ++lastId;
       this._initValue = initValue;
       this._type = type;
       addWorkletRefInitValue(this._id, initValue);
@@ -89,7 +89,7 @@ export class MainThreadRef<T> extends WorkletRef<T> {
     super(initValue, 'main-thread');
     if (__JS__) {
       const id = this._id;
-      this._lifecycleObserver = lynx.getNativeApp().createJSObjectDestructionObserver(() => {
+      this._lifecycleObserver = lynx.getNativeApp().createJSObjectDestructionObserver?.(() => {
         lynx.getCoreContext?.().dispatchEvent({
           type: WorkletEvents.releaseWorkletRef,
           data: {

package/runtime/src/worklet/workletRefPool.ts

@@ -1,25 +1,29 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import { lynxWorkletJsImpl } from './jsImpl.js';
 
+import { isMtsEnabled } from './functionality.js';
+
+let initValuePatch: [number, unknown][] = [];
+const initValueIdSet = /*#__PURE__*/ new Set<number>();
+
+/**
+ * @internal
+ */
 export function addWorkletRefInitValue(id: number, value: unknown): void {
-  const impl = lynxWorkletJsImpl();
-  if (!impl) {
+  if (!isMtsEnabled()) {
     return;
   }
 
-  impl._workletRefInitValueSet.add(id);
-  impl._workletRefInitValuePatch.push([id, value]);
+  initValueIdSet.add(id);
+  initValuePatch.push([id, value]);
 }
 
+/**
+ * @internal
+ */
 export function takeWorkletRefInitValuePatch(): [number, unknown][] {
-  const impl = lynxWorkletJsImpl(false);
-  if (!impl) {
-    return [];
-  }
-
-  const res = impl._workletRefInitValuePatch;
-  impl._workletRefInitValuePatch = [];
+  const res = initValuePatch;
+  initValuePatch = [];
   return res;
 }