@rn-org/react-native-thread 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ Run JavaScript on real background threads in React Native — no Workers, no Wor
 - [Quick start](#quick-start)
 - [API reference](#api-reference)
   - [runOnJS](#runonjs)
-  - [runOnNewJS](#runnewjs)
+  - [runOnNewJS](#runonewjs)
   - [createThread](#createthread)
   - [getThreads](#getthreads)
   - [destroyThread](#destroythread)
@@ -24,6 +24,7 @@ Run JavaScript on real background threads in React Native — no Workers, no Wor
 - [Thread globals](#thread-globals)
   - [postMessage](#postmessage)
   - [console](#console)
+  - [`__params__`](#__params__)
 - [Hermes & Babel plugin](#hermes--babel-plugin-deep-dive)
 - [Constraints](#constraints)
 - [Contributing](#contributing)
@@ -106,10 +107,10 @@ runOnJS((args) => {
 }, { limit: 42 });
 
 // ── 2. Create a named, persistent thread ────────────────────────────────────
-const worker = createThread('MyWorker');
+const thread = createThread('MyThread');
 
 // Send work + params
-worker.run(
+thread.run(
   (args) => {
     var result = 0;
     for (var i = 0; i < args.limit; i++) result += i;
@@ -119,22 +120,22 @@ worker.run(
 );
 
 // Option A — callback
-const unsubscribe = worker.onMessage((data) => {
-  console.log('Result from worker:', data);
+const unsubscribe = thread.onMessage((data) => {
+  console.log('Result from thread:', data);
 });
 
 // Option B — promise (resolves on the next message)
-const data = await worker.onMessage();
-console.log('Result from worker:', data);
+const data = await thread.onMessage();
+console.log('Result from thread:', data);
 
 // ── 3. List all running threads ─────────────────────────────────────────────
 console.log(getThreads());
-// [{ id: 1, name: 'RNOrgThread' }, { id: 2, name: 'MyWorker' }]
+// [{ id: 1, name: 'RNOrgThread' }, { id: 2, name: 'MyThread' }]
 
 // ── 4. Clean up ─────────────────────────────────────────────────────────────
 unsubscribe();
-worker.destroy();               // by handle
-destroyThread('MyWorker');      // by name — same effect
+thread.destroy();               // by handle
+destroyThread('MyThread');      // by name — same effect
 destroyThread(2);               // by id   — same effect
 ```
 
@@ -199,7 +200,7 @@ Returns a snapshot of every live thread currently managed by the library, includ
 const threads = getThreads();
 // [
 //   { id: 1, name: 'RNOrgThread' },
-//   { id: 2, name: 'MyWorker' },
+//   { id: 2, name: 'MyThread' },
 // ]
 ```
 
@@ -216,7 +217,7 @@ Destroys a thread and frees its resources. Accepts either the numeric thread ID
 This is the same function called by `ThreadHandle.destroy()`.
 
 ```ts
-destroyThread('MyWorker');   // by name
+destroyThread('MyThread');   // by name
 destroyThread(2);            // by id
 ```
 
@@ -316,17 +317,17 @@ 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) => {
+thread.run((args) => {
   postMessage({ status: 'done', value: args.multiply * 2 });
 }, { multiply: 21 });
 
 // Callback
-worker.onMessage((data) => {
+thread.onMessage((data) => {
   console.log(data); // { status: 'done', value: 42 }
 });
 
 // Promise
-const data = await worker.onMessage();
+const data = await thread.onMessage();
 console.log(data); // { status: 'done', value: 42 }
 ```
 
@@ -347,16 +348,24 @@ console.log(data); // { status: 'done', value: 42 }
 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:
+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 `var __params__ = <JSON>;`.
 
-```js
-var __params__ = <JSON>;
-```
-
-Must be JSON-serialisable. If you access `__params__` without passing a value, it will be `undefined`.
+You can access the params value in two ways:
 
 ```ts
-worker.run(
+// Option A — args callback parameter
+thread.run(
+  (args) => {
+    for (var i = 0; i < args.iterations; i++) {
+      // ...
+    }
+    postMessage('done');
+  },
+  { iterations: 50_000 }
+);
+
+// Option B — __params__ global (works in both functions and raw code strings)
+thread.run(
   () => {
     for (var i = 0; i < __params__.iterations; i++) {
       // ...
@@ -365,6 +374,12 @@ worker.run(
   },
   { iterations: 50_000 }
 );
+
+// Option C — raw code string (only __params__ is available)
+thread.run(
+  'for (var i = 0; i < __params__.iterations; i++) {} postMessage("done")',
+  { iterations: 50_000 }
+);
 ```
 
 ---
@@ -387,12 +402,12 @@ The included Babel plugin runs at **compile time** — before Hermes touches the
 
 ```js
 // Input (your source)
-worker.run((args) => {
+thread.run((args) => {
   postMessage(args.greeting);
 }, { greeting: 'hello' });
 
 // Output (what Hermes compiles)
-worker.run("((args) => {\n  postMessage(args.greeting);\n})({\"greeting\":\"hello\"})");
+thread.run("((args) => {\n  postMessage(args.greeting);\n})(__params__)", { greeting: 'hello' });
 ```
 
 The second `params` argument is left untouched; only the first (function) argument is transformed.
@@ -409,7 +424,7 @@ The second `params` argument is left untouched; only the first (function) argume
 ### 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`.
+- All values must be passed explicitly via the `args` parameter, `__params__`, 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rn-org/react-native-thread",
-  "version": "0.1.0",
+  "version": "0.2.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",

package/src/globals.d.ts

@@ -23,12 +23,13 @@ declare function postMessage(data: unknown): void;
  * JSON-compatible value.
  *
  * @example
- * worker.run((args) => {
+ * thread.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.
+ * // or via __params__
+ * thread.run(() => {
+ *   console.log(__params__.name); // 'hello'
+ * }, { name: 'hello' });
  */
 declare const __params__: any;