@depup/react-native-worklets 0.11.3-depup.0

package/src/memory/serializable.ts

@@ -0,0 +1,36 @@
+'use strict';
+
+import type {
+  FlatSerializableRef,
+  RegistrationData,
+  SerializableRef,
+} from './types';
+
+export function isSerializableRef<TValue = unknown>(
+  value: unknown
+): value is SerializableRef<TValue> {
+  return true;
+}
+
+export function createSerializable<TValue>(
+  value: TValue
+): SerializableRef<TValue> {
+  return value as SerializableRef<TValue>;
+}
+
+export function makeShareableCloneOnUIRecursive<TValue>(
+  value: TValue
+): FlatSerializableRef<TValue> {
+  return value as FlatSerializableRef<TValue>;
+}
+
+export function makeShareable<TValue>(value: TValue): TValue {
+  return value;
+}
+
+export function registerCustomSerializable<
+  TValue extends object,
+  TPacked extends object,
+>(_registrationData: RegistrationData<TValue, TPacked>) {
+  // noop
+}

package/src/memory/serializableMappingCache.native.ts

@@ -0,0 +1,37 @@
+'use strict';
+
+import type { SerializableRef } from './types';
+
+/**
+ * This symbol is used to represent a mapping from the value to itself.
+ *
+ * It's used to prevent converting a serializable that's already converted - for
+ * example a Shared Value that's in worklet's closure.
+ */
+export const serializableMappingFlag = Symbol('serializable flag');
+
+/*
+During a fast refresh, React holds the same instance of a Mutable
+(that's guaranteed by `useRef`) but `serializableCache` gets regenerated and thus
+becoming empty. This happens when editing the file that contains the definition of this cache.
+
+Because of it, `createSerializable` can't find given mapping
+in `serializableCache` 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 = new WeakMap<
+  object,
+  SerializableRef | WeakRef<SerializableRef> | symbol
+>();
+
+export const serializableMappingCache = {
+  set(
+    serializable: object,
+    serializableRef?: SerializableRef | WeakRef<SerializableRef>
+  ): void {
+    cache.set(serializable, serializableRef || serializableMappingFlag);
+  },
+  get: cache.get.bind(cache),
+};

package/src/memory/serializableMappingCache.ts

@@ -0,0 +1,12 @@
+'use strict';
+
+import type { SerializableRef } from './types';
+
+export const serializableMappingCache = {
+  set(_serializable: object, _serializableRef?: SerializableRef): void {
+    // NOOP
+  },
+  get(_key: object): object | symbol | SerializableRef {
+    return null!;
+  },
+};

package/src/memory/shareable.native.ts

@@ -0,0 +1,68 @@
+'use strict';
+
+import { isBundleModeEnabled } from '../debug/bundleMode';
+import { addNoBundleModeGuardImplementation } from '../guardImplementation';
+import { isWorkletFunction } from '../workletFunction';
+import { WorkletsModule } from '../WorkletsModule/NativeWorklets';
+import { createSerializable } from './serializable';
+import type { Shareable, ShareableConfig } from './types';
+
+/**
+ * Creates a new {@link Shareable} holding the provided initial value. You must
+ * explicitly declare which Worklet Runtime will host the Shareable by passing
+ * its `runtimeId`. To host on the UI Runtime, pass {@link UIRuntimeId}.
+ *
+ * @param hostRuntimeId - The `runtimeId` of the Worklet Runtime that will host
+ *   the Shareable.
+ * @param initial - The initial value of the Shareable.
+ * @param config - Optional advanced configuration.
+ * @returns The created {@link Shareable}.
+ * @see {@link https://docs.swmansion.com/react-native-worklets/docs/memory/createShareable | createShareable docs}
+ */
+export function createShareable<
+  TValue = unknown,
+  THostDecorated = unknown,
+  TGuestDecorated = unknown,
+>(
+  hostRuntimeId: number,
+  initial: TValue,
+  config?: ShareableConfig<TValue, THostDecorated, TGuestDecorated>
+): Shareable<TValue, THostDecorated, TGuestDecorated>;
+
+export function createShareable<
+  TValue = unknown,
+  THostDecorated = unknown,
+  TGuestDecorated = unknown,
+>(
+  hostRuntimeId: number,
+  initial: TValue,
+  config?: ShareableConfig<TValue, THostDecorated, TGuestDecorated>
+): Shareable<TValue, THostDecorated, TGuestDecorated> {
+  const { hostDecorator, guestDecorator, initSynchronously } = config || {};
+  if (__DEV__) {
+    if (hostDecorator && !isWorkletFunction(hostDecorator)) {
+      throw new Error('[Worklets] hostDecorator must be a worklet function');
+    }
+    if (guestDecorator && !isWorkletFunction(guestDecorator)) {
+      throw new Error('[Worklets] guestDecorator must be a worklet function');
+    }
+  }
+
+  const shareableRef = WorkletsModule.createShareable(
+    hostRuntimeId,
+    createSerializable(initial),
+    !!initSynchronously,
+    createSerializable(hostDecorator),
+    createSerializable(guestDecorator)
+  );
+
+  return globalThis.__shareableGuestUnpacker(
+    hostRuntimeId,
+    shareableRef,
+    guestDecorator
+  );
+}
+
+if (__DEV__ && !isBundleModeEnabled()) {
+  addNoBundleModeGuardImplementation(createShareable);
+}

package/src/memory/shareable.ts

@@ -0,0 +1,27 @@
+'use strict';
+
+import type { Shareable, ShareableConfig } from './types';
+
+/**
+ * Creates a new {@link Shareable} holding the provided initial value. You must
+ * explicitly declare which Worklet Runtime will host the Shareable by passing
+ * its `runtimeId`. To host on the UI Runtime, pass {@link UIRuntimeId}.
+ *
+ * @param hostRuntimeId - The `runtimeId` of the Worklet Runtime that will host
+ *   the Shareable.
+ * @param initial - The initial value of the Shareable.
+ * @param config - Optional advanced configuration.
+ * @returns The created {@link Shareable}.
+ * @see {@link https://docs.swmansion.com/react-native-worklets/docs/memory/createShareable | createShareable docs}
+ */
+export function createShareable<
+  TValue = unknown,
+  THostDecorated = unknown,
+  TGuestDecorated = unknown,
+>(
+  _hostRuntimeId: number,
+  _initial: TValue,
+  _config?: ShareableConfig<TValue, THostDecorated, TGuestDecorated>
+): Shareable<TValue, THostDecorated, TGuestDecorated> {
+  throw new Error('[Worklets] `createShareable` is not supported on web.');
+}

package/src/memory/shareableGuestUnpacker.native.ts

@@ -0,0 +1,168 @@
+/* eslint-disable n/no-missing-require */
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable @typescript-eslint/no-require-imports */
+'use strict';
+
+import type {
+  runOnRuntimeAsyncWithId as BundleRunOnRuntimeAsyncWithId,
+  runOnRuntimeSyncWithId as BundleRunOnRuntimeSyncWithId,
+  scheduleOnRuntimeWithId as BundleScheduleOnRuntimeWithId,
+} from '../runtimes';
+import type { WorkletFunction } from '../types';
+import type {
+  SerializableRef,
+  Shareable,
+  ShareableGuest,
+  ShareableGuestDecorator,
+  ShareableHost,
+} from './types';
+
+export function installShareableGuestUnpacker() {
+  'worklet';
+  'no-worklet-closure';
+  let runOnRuntimeSyncFromId: typeof BundleRunOnRuntimeSyncWithId;
+  let runOnRuntimeAsyncFromId: typeof BundleRunOnRuntimeAsyncWithId;
+  let memoize: (
+    unpacked: Shareable<unknown>,
+    serialized: SerializableRef<unknown>
+  ) => void;
+
+  let scheduleOnRuntimeFromId: typeof BundleScheduleOnRuntimeWithId;
+  let serializer: (value: unknown) => SerializableRef<unknown>;
+
+  if (
+    globalThis.__RUNTIME_KIND === 1 ||
+    globalThis._WORKLETS_BUNDLE_MODE_ENABLED
+  ) {
+    serializer = require('./serializable').createSerializable;
+    const { serializableMappingCache } = require('./serializableMappingCache');
+    memoize = serializableMappingCache.set.bind(serializableMappingCache);
+
+    runOnRuntimeSyncFromId = require('../runtimes').runOnRuntimeSyncWithId;
+    runOnRuntimeAsyncFromId = require('../runtimes').runOnRuntimeAsyncWithId;
+    scheduleOnRuntimeFromId = require('../runtimes').scheduleOnRuntimeWithId;
+  } else {
+    // Serializer can't be inlined here because it might be yet undefined
+    // when the unpacker is installed.
+    serializer = (value: unknown) => globalThis.__serializer(value);
+    memoize = () => {
+      // No-op on Worklet Runtimes outside of Bundle Mode.
+    };
+
+    const proxy = globalThis.__workletsModuleProxy;
+    runOnRuntimeSyncFromId = ((
+      hostId: number,
+      worklet: WorkletFunction,
+      ...args: unknown[]
+    ) => {
+      const serializedWorklet = serializer(() => {
+        'worklet';
+        'limit-init-data-hoisting';
+        return globalThis.__serializer(worklet(...args));
+      });
+      return proxy.runOnRuntimeSyncWithId(hostId, serializedWorklet);
+    }) as typeof BundleRunOnRuntimeSyncWithId;
+
+    scheduleOnRuntimeFromId = ((
+      hostId: number,
+      worklet: WorkletFunction,
+      ...args: unknown[]
+    ) => {
+      proxy.scheduleOnRuntimeWithId(
+        hostId,
+        serializer(() => {
+          'worklet';
+          'limit-init-data-hoisting';
+          return globalThis.__serializer(worklet(...args));
+        })
+      );
+    }) as typeof BundleScheduleOnRuntimeWithId;
+
+    runOnRuntimeAsyncFromId = (() => {
+      throw new Error(
+        '[Worklets] `Shareable.getAsync` can only be called on the RN Runtime.'
+      );
+    }) as typeof BundleRunOnRuntimeAsyncWithId;
+  }
+
+  function shareableGuestUnpacker<TValue>(
+    hostId: number,
+    shareableRef: SerializableRef<TValue>,
+    guestDecorator?: ShareableGuestDecorator<TValue>
+  ): Shareable<TValue> {
+    type Host = ShareableHost<TValue>;
+    type Guest = ShareableGuest<TValue>;
+
+    let shareableGuest = shareableRef as unknown as Shareable<TValue>;
+
+    shareableGuest.isHost = false;
+    shareableGuest.__shareableRef = true;
+
+    const get = () => {
+      'worklet';
+      'limit-init-data-hoisting';
+      return (shareableGuest as Host).value;
+    };
+
+    const setWithValue = (value: TValue) => {
+      'worklet';
+      'limit-init-data-hoisting';
+      (shareableGuest as Host).value = value;
+    };
+
+    const setWithSetter = (setter: (prev: TValue) => TValue) => {
+      'worklet';
+      'limit-init-data-hoisting';
+      const currentValue = (shareableGuest as Host).value;
+      const newValue = setter(currentValue);
+      (shareableGuest as Host).value = newValue;
+    };
+
+    shareableGuest.getAsync = () => {
+      return runOnRuntimeAsyncFromId(hostId, get);
+    };
+
+    shareableGuest.getSync = () => {
+      return runOnRuntimeSyncFromId(hostId, get);
+    };
+
+    shareableGuest.setAsync = (value: TValue | ((prev: TValue) => TValue)) => {
+      if (typeof value === 'function') {
+        scheduleOnRuntimeFromId(
+          hostId,
+          setWithSetter,
+          value as (prev: TValue) => TValue
+        );
+      } else {
+        scheduleOnRuntimeFromId(hostId, setWithValue, value);
+      }
+    };
+
+    shareableGuest.setSync = (value: TValue | ((prev: TValue) => TValue)) => {
+      if (typeof value === 'function') {
+        runOnRuntimeSyncFromId(
+          hostId,
+          setWithSetter,
+          value as (prev: TValue) => TValue
+        );
+      } else {
+        runOnRuntimeSyncFromId(hostId, setWithValue, value);
+      }
+    };
+
+    if (guestDecorator) {
+      shareableGuest = guestDecorator(shareableGuest as Guest);
+    }
+
+    memoize(shareableGuest, shareableRef);
+    return shareableGuest;
+  }
+
+  globalThis.__shareableGuestUnpacker = shareableGuestUnpacker;
+}
+
+export type ShareableGuestUnpacker<TValue = unknown> = (
+  hostId: number,
+  shareableRef: SerializableRef<TValue>,
+  decorateGuest?: ShareableGuestDecorator<TValue>
+) => Shareable<TValue>;

package/src/memory/shareableHostUnpacker.native.ts

@@ -0,0 +1,31 @@
+'use strict';
+
+import type { Shareable, ShareableHost, ShareableHostDecorator } from './types';
+
+export function installShareableHostUnpacker() {
+  'worklet';
+  function shareableHostUnpacker<TValue = unknown>(
+    initial: TValue,
+    hostDecorator?: ShareableHostDecorator<TValue>
+  ): Shareable<TValue> {
+    let hostShareable = {
+      isHost: true,
+      __shareableRef: true,
+      value: initial,
+    } as ShareableHost<TValue>;
+
+    if (hostDecorator) {
+      hostShareable = hostDecorator(hostShareable);
+    }
+
+    const shareable = hostShareable;
+    return shareable;
+  }
+
+  globalThis.__shareableHostUnpacker = shareableHostUnpacker;
+}
+
+export type ShareableHostUnpacker<TValue = unknown> = (
+  initial: TValue,
+  decorateHost?: ShareableHostDecorator<TValue>
+) => Shareable<TValue>;

package/src/memory/synchronizable.native.ts

@@ -0,0 +1,17 @@
+'use strict';
+
+import { WorkletsModule } from '../WorkletsModule/NativeWorklets';
+import { createSerializable } from './serializable';
+import type { Synchronizable } from './types';
+
+export function createSynchronizable<TValue = unknown>(
+  initialValue: TValue
+): Synchronizable<TValue> {
+  const synchronizableRef = WorkletsModule.createSynchronizable(
+    createSerializable(initialValue)
+  );
+
+  return globalThis.__synchronizableUnpacker(
+    synchronizableRef
+  ) as unknown as Synchronizable<TValue>;
+}

package/src/memory/synchronizable.ts

@@ -0,0 +1,9 @@
+'use strict';
+
+import type { Synchronizable } from './types';
+
+export function createSynchronizable<TValue = unknown>(
+  _value: TValue
+): Synchronizable<TValue> {
+  throw new Error('[Worklets] `createSynchronizable` is not supported on web.');
+}

package/src/memory/synchronizableUnpacker.native.ts

@@ -0,0 +1,65 @@
+/* eslint-disable n/no-missing-require */
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable @typescript-eslint/no-require-imports */
+'use strict';
+
+import { type Synchronizable, type SynchronizableRef } from './types';
+
+export function installSynchronizableUnpacker() {
+  'worklet';
+  'no-worklet-closure';
+  // TODO: Add cache for synchronizables.
+  const serializer =
+    globalThis.__RUNTIME_KIND === 1 || globalThis._WORKLETS_BUNDLE_MODE_ENABLED
+      ? require('./serializable').createSerializable
+      : (value: unknown) => globalThis.__serializer(value);
+
+  function synchronizableUnpacker<TValue>(
+    synchronizableRef: SynchronizableRef<TValue>
+  ): Synchronizable<TValue> {
+    const synchronizable =
+      synchronizableRef as unknown as Synchronizable<TValue>;
+    const proxy = globalThis.__workletsModuleProxy;
+
+    synchronizable.__synchronizableRef = true;
+    synchronizable.getDirty = () => {
+      return proxy.synchronizableGetDirty(synchronizable);
+    };
+    synchronizable.getBlocking = () => {
+      return proxy.synchronizableGetBlocking(synchronizable);
+    };
+    synchronizable.setBlocking = (
+      valueOrFunction: TValue | ((prev: TValue) => TValue)
+    ) => {
+      let newValue: TValue;
+      if (typeof valueOrFunction === 'function') {
+        const func = valueOrFunction as (prev: TValue) => TValue;
+        synchronizable.lock();
+        const prev = synchronizable.getBlocking();
+        newValue = func(prev);
+
+        proxy.synchronizableSetBlocking(synchronizable, serializer(newValue));
+
+        synchronizable.unlock();
+      } else {
+        const value = valueOrFunction;
+        newValue = value;
+        proxy.synchronizableSetBlocking(synchronizable, serializer(newValue));
+      }
+    };
+    synchronizable.lock = () => {
+      proxy.synchronizableLock(synchronizable);
+    };
+    synchronizable.unlock = () => {
+      proxy.synchronizableUnlock(synchronizable);
+    };
+
+    return synchronizable;
+  }
+
+  globalThis.__synchronizableUnpacker = synchronizableUnpacker;
+}
+
+export type SynchronizableUnpacker = <TValue>(
+  synchronizableRef: SynchronizableRef<TValue>
+) => Synchronizable<TValue>;

package/src/memory/types.ts

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * The below type is used for HostObjects returned by the JSI API that don't
+ * have any accessible fields or methods but can carry data that is accessed
+ * from the c++ side. We add a field to the type to make it possible for
+ * typescript to recognize which JSI methods accept those types as arguments and
+ * to be able to correctly type check other methods that may use them. However,
+ * this field is not actually defined nor should be used for anything else as
+ * assigning any data to those objects will throw an error.
+ */
+export type SerializableRef<TValue = unknown> = {
+  __serializableRef: true;
+  __nativeStateSerializableJSRef: TValue;
+};
+
+// In case of objects with depth or arrays of objects or arrays of arrays etc.
+// we add this utility type that makes it a `SharaebleRef` of the outermost type.
+export type FlatSerializableRef<TValue> =
+  TValue extends SerializableRef<infer TRecursive>
+    ? SerializableRef<TRecursive>
+    : SerializableRef<TValue>;
+
+export type SynchronizableRef<TValue = unknown> = {
+  __synchronizableRef: true;
+  __nativeStateSynchronizableJSRef: TValue;
+};
+
+export type Synchronizable<TValue = unknown> = SerializableRef<TValue> &
+  SynchronizableRef<TValue> & {
+    __synchronizableRef: true;
+    getDirty(): TValue;
+    getBlocking(): TValue;
+    setBlocking(value: TValue | ((prev: TValue) => TValue)): void;
+    lock(): void;
+    unlock(): void;
+  };
+
+/**
+ * Registration data for
+ * [registerCustomSerializable](https://docs.swmansion.com/react-native-worklets/docs/memory/registerCustomSerializable)
+ * function.
+ */
+export type RegistrationData<TValue extends object, TPacked = unknown> = {
+  /**
+   * A unique name for the Custom Serializable. It's used to prevent duplicate
+   * registrations of the same Custom Serializable. You will get warned if you
+   * attempt to register a Custom Serializable with a name that has already been
+   * used.
+   */
+  name: string;
+  /**
+   * A worklet that checks whether a given JavaScript value is of the type
+   * handled by this Custom Serializable.
+   */
+  determine: (value: object) => value is TValue;
+  /**
+   * A worklet that packs the JavaScript value of type `TValue` into a value
+   * that can be serialized by default as Serializable. The function must return
+   * a [supported type for
+   * Serialization](https://docs.swmansion.com/react-native-worklets/docs/memory/serializable#supported-types).
+   */
+  pack: (value: TValue) => TPacked;
+  /**
+   * A worklet that unpacks the packed value, after it's been deserialized from
+   * it's packed form, back into the JavaScript value of type `TValue`.
+   */
+  unpack: (value: TPacked) => TValue;
+};
+
+export type SerializationData<TValue extends object, TPacked = unknown> = Omit<
+  RegistrationData<TValue, TPacked>,
+  'name'
+> & {
+  /** Only defined on the RN Runtime. */
+  name?: string;
+};
+
+export type CustomSerializationRegistry = SerializationData<object, unknown>[];
+
+export type ShareableHostProps<TValue = unknown> = {
+  value: TValue;
+};
+
+export type ShareableHostMeta = {
+  isHost: true;
+  __shareableRef: true;
+};
+
+/**
+ * A worklet that takes the created {@link ShareableHost} and decorates it with
+ * additional properties or methods. It must return the same reference it
+ * received.
+ */
+export type ShareableHostDecorator<TValue = unknown, TDecorated = unknown> = (
+  shareable: ShareableHost<TValue> & TDecorated
+) => ShareableHost<TValue> & TDecorated;
+
+export type ShareableGuestMeta = {
+  isHost: false;
+  __shareableRef: true;
+};
+
+export type ShareableGuestProps<TValue = unknown> = {
+  getAsync(): Promise<TValue>;
+  getSync(): TValue;
+  setAsync(value: TValue | ((prev: TValue) => TValue)): void;
+  setSync(value: TValue | ((prev: TValue) => TValue)): void;
+};
+
+/**
+ * A worklet that decorates each {@link ShareableGuest} created for the Shareable
+ * with additional properties or methods. It must return the same reference it
+ * received.
+ */
+export type ShareableGuestDecorator<TValue = unknown, TDecorated = unknown> = (
+  shareable: ShareableGuest<TValue> & TDecorated
+) => ShareableGuest<TValue> & TDecorated;
+
+/**
+ * The host-side representation of a {@link Shareable}, living on the
+ * {@link https://docs.swmansion.com/react-native-worklets/docs/fundamentals/runtimeKinds#worklet-runtime | Worklet Runtime}
+ * that hosts the Shareable.
+ */
+export type ShareableHost<
+  TValue = unknown,
+  THostDecorated = unknown,
+> = ShareableHostMeta &
+  ShareableHostProps<TValue> &
+  (THostDecorated extends object ? THostDecorated : object);
+
+/**
+ * A guest-side representation of a {@link Shareable}, used on any runtime other
+ * than the host runtime.
+ */
+export type ShareableGuest<
+  TValue = unknown,
+  TGuestDecorated = unknown,
+> = ShareableGuestMeta &
+  ShareableGuestProps<TValue> &
+  (TGuestDecorated extends object ? TGuestDecorated : object);
+
+/**
+ * A type of shared memory tied to a given runtime, called the Host Runtime.
+ * Depending on the context it's either a {@link ShareableHost} (on the hosting
+ * Worklet Runtime) or a {@link ShareableGuest} (on every other runtime).
+ *
+ * @see {@link https://docs.swmansion.com/react-native-worklets/docs/memory/shareable | Shareable docs}
+ */
+export type Shareable<
+  TValue = unknown,
+  THostDecorated = unknown,
+  TGuestDecorated = unknown,
+> =
+  | (ShareableHost<TValue, THostDecorated> &
+      Partial<
+        ShareableGuestProps<TValue> &
+          (TGuestDecorated extends object ? Partial<TGuestDecorated> : object)
+      >)
+  | (ShareableGuest<TValue, TGuestDecorated> &
+      Partial<
+        ShareableHostProps<TValue> &
+          (THostDecorated extends object ? Partial<THostDecorated> : object)
+      >);
+
+/** Optional advanced configuration for a {@link Shareable}. */
+export type ShareableConfig<TValue, THostDecorated, TGuestDecorated> = {
+  /**
+   * A worklet that decorates the {@link ShareableHost} with additional
+   * properties or methods.
+   */
+  hostDecorator?: ShareableHostDecorator<TValue, THostDecorated>;
+  /**
+   * A worklet that decorates each {@link ShareableGuest} with additional
+   * properties or methods.
+   */
+  guestDecorator?: ShareableGuestDecorator<TValue, TGuestDecorated>;
+  /**
+   * When `true`, the {@link ShareableHost} is created synchronously during the
+   * call to `createShareable` instead of lazily on first access. Use this when
+   * the host initialization triggers side effects that must happen eagerly.
+   *
+   * @defaultValue `false`
+   */
+  initSynchronously?: boolean;
+};
+
+export interface RemoteFunction extends SerializableRef {
+  /** Defined when extracted on a Guest Runtime. */
+  __remoteFunction: true | undefined;
+}