@rn-org/react-native-thread 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 sriharsha-rently
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,440 @@
+# @rn-org/react-native-thread
+
+Run JavaScript on real background threads in React Native — no Workers, no Worklets. Uses **JavaScriptCore** on iOS and **Mozilla Rhino** on Android, each on a dedicated OS-level thread. Built as a New Architecture **TurboModule**.
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Babel plugin (required for Hermes)](#babel-plugin-required-for-hermes)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+  - [runOnJS](#runonjs)
+  - [runOnNewJS](#runnewjs)
+  - [createThread](#createthread)
+  - [getThreads](#getthreads)
+  - [destroyThread](#destroythread)
+  - [onMessage](#onmessage)
+  - [ThreadHandle](#threadhandle)
+  - [ThreadInfo](#threadinfo)
+  - [ThreadTask](#threadtask)
+- [Thread globals](#thread-globals)
+  - [postMessage](#postmessage)
+  - [console](#console)
+- [Hermes & Babel plugin](#hermes--babel-plugin-deep-dive)
+- [Constraints](#constraints)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **True background threads** — each thread runs its own JS engine on an OS-level thread; the main Hermes/JSC runtime is never blocked.
+- **Unlimited threads** — create as many threads as you need; each is isolated.
+- **Shared thread** (`runOnJS`) — fire-and-forget tasks on a single persistent background thread; no teardown required.
+- **Per-thread message passing** — call `postMessage(data)` from any thread, receive it on the main thread with `onMessage` (callback or `await`).
+- **Parameter injection** — pass a JSON-serialisable value from the main thread into the background function as a typed argument `(args) => { ... }`.
+- **Named threads** — give threads friendly names; list or destroy them by name.
+- **Full `console` support** — `console.log/info/warn/error/debug` work inside threads and appear in Logcat / Xcode logs.
+- **Hermes-safe** — ships a Babel plugin that extracts function source at compile time so Hermes bytecode never breaks serialisation.
+- **New Architecture only** — built on the TurboModule / Codegen pipeline.
+
+---
+
+## Requirements
+
+| | Minimum |
+|---|---|
+| React Native | 0.76+ (New Architecture) |
+| iOS | 15.1 |
+| Android | API 24 |
+| Node | 18+ |
+
+---
+
+## Installation
+
+```sh
+npm install @rn-org/react-native-thread
+# or
+yarn add @rn-org/react-native-thread
+```
+
+**iOS** — run pod install:
+
+```sh
+cd ios && pod install
+```
+
+**Android** — the Rhino dependency is declared in the library's `build.gradle`; no extra steps needed.
+
+---
+
+## Babel plugin (required for Hermes)
+
+Hermes compiles your JS to bytecode at build time. That means `fn.toString()` at runtime returns a placeholder (`"function () { [bytecode] }"`) instead of source code. The library includes a Babel plugin that extracts arrow-function / function-expression source at **compile time** and replaces it with a string literal before Hermes ever sees it.
+
+Add the plugin to your app's `babel.config.js`:
+
+```js
+// babel.config.js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: [
+    '@rn-org/react-native-thread/babel-plugin',
+    // ... your other plugins
+  ],
+};
+```
+
+The plugin is a no-op on non-Hermes builds (JSC, V8, etc.).
+
+---
+
+## Quick start
+
+```tsx
+import { runOnJS, createThread, getThreads, destroyThread } from '@rn-org/react-native-thread';
+
+// ── 1. Fire and forget on the shared background thread ──────────────────────
+runOnJS((args) => {
+  console.log('Limit is', args.limit);
+}, { limit: 42 });
+
+// ── 2. Create a named, persistent thread ────────────────────────────────────
+const worker = createThread('MyWorker');
+
+// Send work + params
+worker.run(
+  (args) => {
+    var result = 0;
+    for (var i = 0; i < args.limit; i++) result += i;
+    postMessage({ sum: result });
+  },
+  { limit: 1_000_000 }
+);
+
+// Option A — callback
+const unsubscribe = worker.onMessage((data) => {
+  console.log('Result from worker:', data);
+});
+
+// Option B — promise (resolves on the next message)
+const data = await worker.onMessage();
+console.log('Result from worker:', data);
+
+// ── 3. List all running threads ─────────────────────────────────────────────
+console.log(getThreads());
+// [{ id: 1, name: 'RNOrgThread' }, { id: 2, name: 'MyWorker' }]
+
+// ── 4. Clean up ─────────────────────────────────────────────────────────────
+unsubscribe();
+worker.destroy();               // by handle
+destroyThread('MyWorker');      // by name — same effect
+destroyThread(2);               // by id   — same effect
+```
+
+---
+
+## API reference
+
+### `runOnJS`
+
+```ts
+function runOnJS(task: ThreadTask, params?: unknown): void
+```
+
+Runs `task` on the **shared persistent background thread** (named `"RNOrgThread"`). The thread is created on first use and lives for the lifetime of the module. Ideal for fire-and-forget work where you don't need the overhead of managing a dedicated thread.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `task` | `ThreadTask` | Function or code string to execute. |
+| `params` | `unknown` | Optional JSON-serialisable value passed as the first argument to the function. |
+
+---
+
+### `runOnNewJS`
+
+```ts
+function runOnNewJS(task: ThreadTask, params?: unknown, name?: string): ThreadHandle
+```
+
+Creates a **new isolated thread**, immediately runs `task` on it, and returns a `ThreadHandle`. The thread persists until you call `handle.destroy()` or `destroyThread(...)`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `task` | `ThreadTask` | Function or code string to execute. |
+| `params` | `unknown` | Optional value passed as the first argument to the function. |
+| `name` | `string` | Optional display name. Default: `RNThread-<id>`. |
+
+---
+
+### `createThread`
+
+```ts
+function createThread(name?: string): ThreadHandle
+```
+
+Creates a **new persistent named thread** without immediately running any code. Use the returned `ThreadHandle` to dispatch work at any time.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `name` | `string` | Optional display name. Default: `RNThread-<id>`. |
+
+---
+
+### `getThreads`
+
+```ts
+function getThreads(): ThreadInfo[]
+```
+
+Returns a snapshot of every live thread currently managed by the library, including the `runOnJS` shared thread once it has been started. Threads destroyed via `destroyThread` or `handle.destroy()` are removed from this list immediately.
+
+```ts
+const threads = getThreads();
+// [
+//   { id: 1, name: 'RNOrgThread' },
+//   { id: 2, name: 'MyWorker' },
+// ]
+```
+
+---
+
+### `destroyThread`
+
+```ts
+function destroyThread(idOrName: number | string): void
+```
+
+Destroys a thread and frees its resources. Accepts either the numeric thread ID or the thread's name. When a name is given, the first matching thread is destroyed.
+
+This is the same function called by `ThreadHandle.destroy()`.
+
+```ts
+destroyThread('MyWorker');   // by name
+destroyThread(2);            // by id
+```
+
+In `__DEV__` mode a warning is logged if no matching thread is found.
+
+---
+
+### `onMessage`
+
+```ts
+// Callback — fires on every message from any thread
+function onMessage(
+  handler: (data: unknown, threadId: number) => void
+): () => void
+
+// Promise — resolves once on the next message from any thread
+function onMessage(): Promise<{ data: unknown; threadId: number }>
+```
+
+Global listener that fires whenever **any** thread calls `postMessage(data)`. Prefer `ThreadHandle.onMessage` if you want messages scoped to a single thread.
+
+```ts
+// Callback variant
+const unsub = onMessage((data, threadId) => {
+  console.log(`Thread ${threadId} sent:`, data);
+});
+unsub(); // remove listener
+
+// Promise variant — awaits the next message from any thread
+const { data, threadId } = await onMessage();
+console.log(`Thread ${threadId} sent:`, data);
+```
+
+---
+
+### `ThreadHandle`
+
+Object returned by `createThread` and `runOnNewJS`.
+
+```ts
+type ThreadHandle = {
+  readonly id: number;
+  readonly name: string;
+  run(task: ThreadTask, params?: unknown): void;
+  /** Callback variant — fires on every message. Returns unsubscribe fn. */
+  onMessage(handler: (data: unknown) => void): () => void;
+  /** Promise variant — resolves on the next message from this thread. */
+  onMessage(): Promise<unknown>;
+  destroy(): void;
+};
+```
+
+| Member | Description |
+|---|---|
+| `id` | Numeric ID assigned by the native layer. |
+| `name` | Display name provided at creation (or the default `RNThread-<id>`). |
+| `run(task, params?)` | Execute `task` on this thread. `params` is passed as the first argument to the function. Can be called multiple times. |
+| `onMessage(handler)` | Subscribe to `postMessage` output from **this thread only**. Returns an unsubscribe function. |
+| `onMessage()` | Returns a `Promise` that resolves with the next message from **this thread only**, then auto-unsubscribes. |
+| `destroy()` | Shut down the thread and remove it from the registry. Equivalent to calling `destroyThread(handle.id)`. |
+
+---
+
+### `ThreadInfo`
+
+```ts
+type ThreadInfo = {
+  readonly id: number;
+  readonly name: string;
+};
+```
+
+Returned by `getThreads()`.
+
+---
+
+### `ThreadTask`
+
+```ts
+type ThreadTask = ((args?: any) => void) | string;
+```
+
+Either an arrow function / function expression (transformed by the Babel plugin) or a raw JS code string. When a function is used, `params` is passed as the first argument (`args`).
+
+---
+
+## Thread globals
+
+These globals are available inside every thread function:
+
+### `postMessage`
+
+```ts
+declare function postMessage(data: unknown): void
+```
+
+Sends `data` back to the main JS thread. The value is JSON-serialised in the background thread and JSON-parsed before reaching the `onMessage` handler. Must be JSON-serialisable (`object`, `array`, `string`, `number`, `boolean`, or `null`).
+
+```ts
+worker.run((args) => {
+  postMessage({ status: 'done', value: args.multiply * 2 });
+}, { multiply: 21 });
+
+// Callback
+worker.onMessage((data) => {
+  console.log(data); // { status: 'done', value: 42 }
+});
+
+// Promise
+const data = await worker.onMessage();
+console.log(data); // { status: 'done', value: 42 }
+```
+
+---
+
+### `console`
+
+`console.log`, `.info`, `.warn`, `.error`, and `.debug` are all available and route to:
+
+- **iOS** — `NSLog`, visible in Xcode / Console.app; tagged `[RNThread-<id>]`.
+- **Android** — `android.util.Log`, visible in Logcat; tagged `RNThread-<id>`.
+
+---
+
+### `__params__`
+
+```ts
+declare const __params__: any
+```
+
+Injected by the library when you pass a second argument to `run()`, `runOnJS()`, or `runOnNewJS()`. The value is JSON-serialised on the main thread and prepended to the code string as:
+
+```js
+var __params__ = <JSON>;
+```
+
+Must be JSON-serialisable. If you access `__params__` without passing a value, it will be `undefined`.
+
+```ts
+worker.run(
+  () => {
+    for (var i = 0; i < __params__.iterations; i++) {
+      // ...
+    }
+    postMessage('done');
+  },
+  { iterations: 50_000 }
+);
+```
+
+---
+
+## Hermes & Babel plugin deep dive
+
+### The problem
+
+The Hermes compiler converts your JS bundle to bytecode at build time. Any function whose `.toString()` is called at runtime returns something like:
+
+```
+function () { [bytecode] }
+```
+
+Because this library must *serialise* functions to strings and send them to a separate JS engine, `.toString()` alone doesn't work under Hermes.
+
+### The solution
+
+The included Babel plugin runs at **compile time** — before Hermes touches the code — and replaces arrow-function / function-expression arguments to the thread API with string literals containing the original source wrapped as an IIFE:
+
+```js
+// Input (your source)
+worker.run((args) => {
+  postMessage(args.greeting);
+}, { greeting: 'hello' });
+
+// Output (what Hermes compiles)
+worker.run("((args) => {\n  postMessage(args.greeting);\n})({\"greeting\":\"hello\"})");
+```
+
+The second `params` argument is left untouched; only the first (function) argument is transformed.
+
+### Supported call sites
+
+| Pattern | Transformed |
+|---|---|
+| `runOnJS(() => { ... })` | Yes |
+| `runOnNewJS(() => { ... })` | Yes |
+| `anyHandle.run(() => { ... })` | Yes |
+| Raw code string `run("...")` | No (already a string) |
+
+### Limitations
+
+- Thread functions are **self-contained**: they run in an isolated JS engine with no access to the outer closure, imported modules, or the React tree.
+- All values must be passed explicitly via the `args` parameter or `postMessage`.
+- Thread function bodies must be **ASCII-safe**: Rhino (Android) does not support non-ASCII identifier characters in source mode.
+- The `params` value must be **JSON-serialisable**: functions, `undefined`, `Map`, `Set`, etc. are not supported.
+
+---
+
+## Constraints summary
+
+| Constraint | Reason |
+|---|---|
+| Functions are closure-isolated | They run in a completely separate JS engine |
+| `params` must be JSON-serialisable | Serialised and passed as a function argument |
+| `postMessage` payload must be JSON-serialisable | Transported as a JSON string over the bridge |
+| Function body must be ASCII-safe | Rhino parser limitation |
+| New Architecture required | TurboModule / Codegen only; no bridge fallback |
+
+---
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+---
+
+## License
+
+MIT

package/ReactNativeThread.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeThread"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/sriharsha-rently/rn-org-react-native-thread.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,69 @@
+buildscript {
+  ext.ReactNativeThread = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ReactNativeThread[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.rnorg.reactnativethread"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // Rhino JS engine – provides a self-contained JS runtime for background threads
+  implementation "org.mozilla:rhino:1.7.15"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>