@rn-org/react-native-thread 0.1.0

package/lib/typescript/src/NativeReactNativeThread.d.ts

@@ -0,0 +1,20 @@
+import { type TurboModule } from 'react-native';
+export interface Spec extends TurboModule {
+    /**
+     * Create a new isolated JS thread. Returns a numeric thread ID.
+     */
+    createThread(): number;
+    /**
+     * Execute a JS code string on an existing thread.
+     */
+    runOnThread(threadId: number, code: string): void;
+    /**
+     * Destroy a thread and free its resources.
+     */
+    destroyThread(threadId: number): void;
+    addListener(eventName: string): void;
+    removeListeners(count: number): void;
+}
+declare const _default: Spec;
+export default _default;
+//# sourceMappingURL=NativeReactNativeThread.d.ts.map

package/lib/typescript/src/NativeReactNativeThread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeReactNativeThread.d.ts","sourceRoot":"","sources":["../../../src/NativeReactNativeThread.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC;IAEvB;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAGtC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;;AAED,wBAA2E"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,49 @@
+export type ThreadTask = ((args?: any) => void) | string;
+/** Snapshot of a single live thread. */
+export type ThreadInfo = {
+    readonly id: number;
+    readonly name: string;
+};
+export type ThreadHandle = {
+    readonly id: number;
+    readonly name: string;
+    /**
+     * Run a task on this thread.
+     * @param params - Optional JSON-serialisable value passed as the first
+     *                 argument to the thread function.
+     */
+    run(task: ThreadTask, params?: unknown): void;
+    /** Subscribe to messages from this thread. Returns an unsubscribe function. */
+    onMessage(handler: (data: unknown) => void): () => void;
+    /** Returns a Promise that resolves with the next message from this thread. */
+    onMessage(): Promise<unknown>;
+    destroy(): void;
+};
+export declare function runOnJS(task: ThreadTask, params?: unknown): void;
+/**
+ * Runs a task on a brand-new isolated thread and returns a handle to it.
+ * @param name - Optional display name (default: `RNThread-<id>`).
+ */
+export declare function runOnNewJS(task: ThreadTask, params?: unknown, name?: string): ThreadHandle;
+/**
+ * Creates a persistent thread. Optionally give it a name.
+ * @param name - Display name (default: `RNThread-<id>`).
+ */
+export declare function createThread(name?: string): ThreadHandle;
+/**
+ * Returns info about every live thread currently managed by this library,
+ * including the shared `runOnJS` thread once it has been started.
+ */
+export declare function getThreads(): ThreadInfo[];
+/**
+ * Destroy a thread by its numeric ID **or** by its name.
+ * When a name is given, the first matching thread is destroyed.
+ * This is also what `ThreadHandle.destroy()` calls internally.
+ */
+export declare function destroyThread(idOrName: number | string): void;
+export declare function onMessage(handler: (data: unknown, threadId: number) => void): () => void;
+export declare function onMessage(): Promise<{
+    data: unknown;
+    threadId: number;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC;AAEzD,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxD,8EAA8E;IAC9E,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAyDF,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAEhE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,MAAM,GACZ,YAAY,CAMd;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAKxD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,EAAE,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0B7D;AAED,wBAAgB,SAAS,CACvB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GACjD,MAAM,IAAI,CAAC;AACd,wBAAgB,SAAS,IAAI,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "@rn-org/react-native-thread",
+  "version": "0.1.0",
+  "description": "Run JavaScript on real background threads in React Native — no Workers, no Worklets. Uses JavaScriptCore on iOS and Mozilla Rhino on Android. Built as a New Architecture TurboModule.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./babel-plugin": "./src/babel-plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace @rn-org/react-native-thread-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "thread",
+    "background-thread",
+    "multithreading",
+    "javascript-core",
+    "rhino",
+    "turbo-module",
+    "new-architecture",
+    "worker",
+    "postmessage"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rn-org/react-native-thread.git"
+  },
+  "author": "sriharshamadamanchi <sriharshamadamanchiz@gmail.com> (https://github.com/rn-org)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/rn-org/react-native-thread/issues"
+  },
+  "homepage": "https://github.com/rn-org/react-native-thread#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/compat": "^1.3.2",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.35.0",
+    "@react-native/babel-preset": "0.83.0",
+    "@react-native/eslint-config": "0.83.0",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.2.0",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29.7.0",
+    "lefthook": "^2.0.3",
+    "prettier": "^2.8.8",
+    "react": "19.2.0",
+    "react-native": "0.83.0",
+    "react-native-builder-bob": "^0.40.18",
+    "release-it": "^19.0.4",
+    "turbo": "^2.5.6",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "ReactNativeThreadSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.rnorg.reactnativethread"
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.57.2"
+  }
+}

package/src/NativeReactNativeThread.ts

@@ -0,0 +1,24 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  /**
+   * Create a new isolated JS thread. Returns a numeric thread ID.
+   */
+  createThread(): number;
+
+  /**
+   * Execute a JS code string on an existing thread.
+   */
+  runOnThread(threadId: number, code: string): void;
+
+  /**
+   * Destroy a thread and free its resources.
+   */
+  destroyThread(threadId: number): void;
+
+  // Required by NativeEventEmitter
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('ReactNativeThread');

package/src/babel-plugin.js

@@ -0,0 +1,77 @@
+/**
+ * Babel plugin for @rn-org/react-native-thread
+ *
+ * Hermes compiles JS to bytecode at build time, so fn.toString() at runtime
+ * returns a placeholder ("bytecode") rather than the original source.
+ *
+ * This plugin runs at compile time and replaces arrow-function / function-
+ * expression arguments passed to the thread API with string literals that
+ * contain the source wrapped as an IIFE.  The background thread engine
+ * (JSC on iOS, Rhino on Android) can then simply eval() the string.
+ *
+ * Transforms:
+ *   runOnJS((args) => { ... })         → runOnJS("((args) => { ... })(__params__)")
+ *   runOnNewJS((args) => { ... })      → runOnNewJS("((args) => { ... })(__params__)")
+ *   thread.run((args) => { ... })      → thread.run("((args) => { ... })(__params__)")
+ *
+ * Add to your app's babel.config.js:
+ *   plugins: ['@rn-org/react-native-thread/babel-plugin']
+ */
+
+'use strict';
+
+// Top-level function names that take a fn-or-code as their first argument.
+const TOP_LEVEL_API = new Set(['runOnJS', 'runOnNewJS']);
+
+// Method names on a ThreadHandle that take a fn-or-code as their first arg.
+const METHOD_API = new Set(['run']);
+
+module.exports = function reactNativeThreadPlugin({ types: t }) {
+  /**
+   * If `argNode` is an arrow function or function expression, replace the
+   * argument at `index` with a string literal `"(<source>)()"`.
+   */
+  function maybeTransformArg(callPath, state, argNode, index) {
+    if (
+      !t.isArrowFunctionExpression(argNode) &&
+      !t.isFunctionExpression(argNode)
+    ) {
+      return;
+    }
+
+    const originalCode = state.file.code;
+    const fnSource = originalCode.slice(argNode.start, argNode.end);
+    const iife = `(${fnSource})(__params__)`;
+
+    callPath.node.arguments[index] = t.stringLiteral(iife);
+  }
+
+  return {
+    name: 'react-native-thread',
+    visitor: {
+      CallExpression(path, state) {
+        const { callee, arguments: args } = path.node;
+
+        // runOnJS(() => {}) / runOnNewJS(() => {})
+        if (t.isIdentifier(callee) && TOP_LEVEL_API.has(callee.name)) {
+          if (args.length >= 1) {
+            maybeTransformArg(path, state, args[0], 0);
+          }
+          return;
+        }
+
+        // someThread.run(() => {})
+        if (
+          t.isMemberExpression(callee) &&
+          !callee.computed &&
+          t.isIdentifier(callee.property) &&
+          METHOD_API.has(callee.property.name)
+        ) {
+          if (args.length >= 1) {
+            maybeTransformArg(path, state, args[0], 0);
+          }
+        }
+      },
+    },
+  };
+};

package/src/globals.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Global injected by react-native-thread into every background JS runtime.
+ * Call this from inside a `runOnJS`, `runOnNewJS`, or `thread.run()` callback
+ * to send data back to the main JS thread.
+ *
+ * The value is automatically JSON-serialised before being sent and
+ * JSON-parsed when received by the `onMessage` handler.
+ *
+ * @example
+ * thread.run(() => {
+ *   const result = heavyWork();
+ *   postMessage({ result });
+ * });
+ */
+declare function postMessage(data: unknown): void;
+
+/**
+ * Parameters passed by the caller via the optional second argument of
+ * `thread.run(fn, params)`, `runOnJS(fn, params)`, or `runOnNewJS(fn, params)`.
+ *
+ * The value is whatever was passed in — it is JSON-serialised on the main
+ * thread and parsed before the thread function runs, so it must be a
+ * JSON-compatible value.
+ *
+ * @example
+ * worker.run((args) => {
+ *   console.log(args.name); // 'hello'
+ * }, { name: 'hello' });
+ *
+ * @deprecated Use the callback argument instead: `thread.run((args) => { ... }, params)`.
+ * `__params__` is still injected for raw code strings but no longer needed for
+ * function callbacks.
+ */
+declare const __params__: any;

package/src/index.tsx

@@ -0,0 +1,211 @@
+import { NativeEventEmitter } from 'react-native';
+import ReactNativeThread from './NativeReactNativeThread';
+
+export type ThreadTask = ((args?: any) => void) | string;
+
+/** Snapshot of a single live thread. */
+export type ThreadInfo = {
+  readonly id: number;
+  readonly name: string;
+};
+
+export type ThreadHandle = {
+  readonly id: number;
+  readonly name: string;
+  /**
+   * Run a task on this thread.
+   * @param params - Optional JSON-serialisable value passed as the first
+   *                 argument to the thread function.
+   */
+  run(task: ThreadTask, params?: unknown): void;
+  /** Subscribe to messages from this thread. Returns an unsubscribe function. */
+  onMessage(handler: (data: unknown) => void): () => void;
+  /** Returns a Promise that resolves with the next message from this thread. */
+  onMessage(): Promise<unknown>;
+  destroy(): void;
+};
+
+const _emitter = new NativeEventEmitter(ReactNativeThread);
+const RN_THREAD_MESSAGE_EVENT = 'RNThreadMessage';
+
+// ─── Thread registry (JS-layer; names are a JS concept) ──────────────────────
+const _registry = new Map<number, ThreadInfo>();
+
+function _register(id: number, name: string): void {
+  _registry.set(id, { id, name });
+}
+
+function _unregister(id: number): void {
+  _registry.delete(id);
+}
+
+function toCode(task: ThreadTask, params?: unknown): string {
+  if (typeof task === 'string') {
+    // Always declare __params__ so Babel-transformed strings can pass it as
+    // an argument to the function, and raw code strings that reference
+    // __params__ directly continue to work.
+    const paramsJson =
+      params !== undefined ? JSON.stringify(params) : 'undefined';
+    return `var __params__ = ${paramsJson};\n${task}`;
+  }
+
+  const src = task.toString();
+  if (
+    src.includes('[bytecode]') ||
+    /^\s*function\s*\(\)\s*\{\s*bytecode\s*\}/.test(src)
+  ) {
+    if (__DEV__) {
+      console.warn(
+        '[react-native-thread] fn.toString() returned a Hermes bytecode placeholder. ' +
+          "Add the Babel plugin: plugins: ['@rn-org/react-native-thread/babel-plugin']"
+      );
+    }
+    return '/* bytecode: no-op */';
+  }
+
+  const argsStr = params !== undefined ? JSON.stringify(params) : '';
+  return `(${src})(${argsStr})`;
+}
+
+// ─── Shared thread (runOnJS) ──────────────────────────────────────────────────
+
+const SHARED_THREAD_NAME = 'RNOrgThread';
+let _sharedThreadId: number | null = null;
+
+function getSharedThread(): number {
+  if (_sharedThreadId === null) {
+    _sharedThreadId = ReactNativeThread.createThread();
+    _register(_sharedThreadId, SHARED_THREAD_NAME);
+  }
+  return _sharedThreadId;
+}
+
+export function runOnJS(task: ThreadTask, params?: unknown): void {
+  ReactNativeThread.runOnThread(getSharedThread(), toCode(task, params));
+}
+
+/**
+ * Runs a task on a brand-new isolated thread and returns a handle to it.
+ * @param name - Optional display name (default: `RNThread-<id>`).
+ */
+export function runOnNewJS(
+  task: ThreadTask,
+  params?: unknown,
+  name?: string
+): ThreadHandle {
+  const id = ReactNativeThread.createThread();
+  const resolvedName = name ?? `RNThread-${id}`;
+  _register(id, resolvedName);
+  ReactNativeThread.runOnThread(id, toCode(task, params));
+  return createThreadHandle(id, resolvedName);
+}
+
+/**
+ * Creates a persistent thread. Optionally give it a name.
+ * @param name - Display name (default: `RNThread-<id>`).
+ */
+export function createThread(name?: string): ThreadHandle {
+  const id = ReactNativeThread.createThread();
+  const resolvedName = name ?? `RNThread-${id}`;
+  _register(id, resolvedName);
+  return createThreadHandle(id, resolvedName);
+}
+
+/**
+ * Returns info about every live thread currently managed by this library,
+ * including the shared `runOnJS` thread once it has been started.
+ */
+export function getThreads(): ThreadInfo[] {
+  return Array.from(_registry.values());
+}
+
+/**
+ * Destroy a thread by its numeric ID **or** by its name.
+ * When a name is given, the first matching thread is destroyed.
+ * This is also what `ThreadHandle.destroy()` calls internally.
+ */
+export function destroyThread(idOrName: number | string): void {
+  let targetId: number | undefined;
+
+  if (typeof idOrName === 'number') {
+    if (_registry.has(idOrName)) targetId = idOrName;
+  } else {
+    for (const info of _registry.values()) {
+      if (info.name === idOrName) {
+        targetId = info.id;
+        break;
+      }
+    }
+  }
+
+  if (targetId === undefined) {
+    if (__DEV__) {
+      console.warn(
+        `[react-native-thread] destroyThread: no thread found for "${idOrName}"`
+      );
+    }
+    return;
+  }
+
+  _unregister(targetId);
+  if (targetId === _sharedThreadId) _sharedThreadId = null;
+  ReactNativeThread.destroyThread(targetId);
+}
+
+export function onMessage(
+  handler: (data: unknown, threadId: number) => void
+): () => void;
+export function onMessage(): Promise<{ data: unknown; threadId: number }>;
+export function onMessage(
+  handler?: (data: unknown, threadId: number) => void
+): (() => void) | Promise<{ data: unknown; threadId: number }> {
+  if (handler) {
+    const sub = _emitter.addListener(RN_THREAD_MESSAGE_EVENT, (event: any) => {
+      let parsed: unknown = event.data;
+      try {
+        parsed = JSON.parse(event.data);
+      } catch {}
+      handler(parsed, event.threadId as number);
+    });
+    return () => sub.remove();
+  }
+
+  return new Promise<{ data: unknown; threadId: number }>((resolve) => {
+    const sub = _emitter.addListener(RN_THREAD_MESSAGE_EVENT, (event: any) => {
+      let parsed: unknown = event.data;
+      try {
+        parsed = JSON.parse(event.data);
+      } catch {}
+      sub.remove();
+      resolve({ data: parsed, threadId: event.threadId as number });
+    });
+  });
+}
+
+function createThreadHandle(id: number, name: string): ThreadHandle {
+  return {
+    id,
+    name,
+    run(task: ThreadTask, params?: unknown) {
+      ReactNativeThread.runOnThread(id, toCode(task, params));
+    },
+    onMessage: function (handler?: (data: unknown) => void) {
+      if (handler) {
+        return onMessage((data, threadId) => {
+          if (threadId === id) handler(data);
+        });
+      }
+      return new Promise<unknown>((resolve) => {
+        const unsub = onMessage((data, threadId) => {
+          if (threadId === id) {
+            unsub();
+            resolve(data);
+          }
+        });
+      });
+    } as ThreadHandle['onMessage'],
+    destroy() {
+      destroyThread(id);
+    },
+  };
+}