@rejaul/react-native-rust 1.0.1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of Conduct
+
+## Our standard
+
+Everyone participating in this project is expected to help make its community respectful, constructive, and welcoming to people with different backgrounds and experience levels.
+
+Examples of behavior that supports this standard include:
+
+- Being considerate and respectful in discussions and reviews.
+- Giving and receiving technical feedback constructively.
+- Focusing criticism on code and ideas, not people.
+- Respecting differing viewpoints and experiences.
+
+Unacceptable behavior includes harassment, discriminatory language, personal attacks, and deliberate disruption of project discussions.
+
+## Reporting
+
+Report conduct concerns to the project maintainers through the repository's contact options: https://github.com/DeveloperRejaul/react-native-rust. Maintainers will review reports and take appropriate action.
+
+## Scope
+
+This policy applies in project issues, pull requests, discussions, and other spaces used for project participation.

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for helping improve `@rejaul/react-native-rust`.
+
+## Project scope
+
+This repository contains an npm CLI for React Native library authors. It targets the C++ TurboModule template produced by `create-react-native-library` and generates Rust handlers plus C ABI, C++, and TypeScript glue from the library's TypeScript `Spec`.
+
+The current supported method types are synchronous `number` (`f64`), `boolean` (`bool`), and `void`. Unsupported signatures should fail with a clear error before generated files are changed. Do not claim support for strings, collections, promises, callbacks, or other unsupported types without implementing and testing the complete native mapping.
+
+## Development setup
+
+Requirements: Node.js 18 or newer and npm.
+
+```sh
+npm install
+npm test
+```
+
+The test suite uses temporary C++ TurboModule fixtures; it does not require Rust, Xcode, or the Android NDK. To check the publish contents:
+
+```sh
+npm pack --dry-run
+```
+
+## Code generation changes
+
+- Treat the TypeScript `Spec` as the source of truth.
+- Keep generated C ABI declarations, C++ methods, and TypeScript wrappers consistent with each other.
+- Preserve user-authored Rust handler bodies when `generate` is run again.
+- Validate all signatures and existing handler compatibility before writing generated files.
+- Add tests for supported type mappings, unsupported types, signature changes, repeat generation, and files that must not be overwritten.
+- Keep generator output deterministic so a second generation with an unchanged `Spec` produces no diff.
+
+## Manual platform validation
+
+For changes affecting native linking, try the relevant platform build when the toolchain is available.
+
+Android requires Rust Android targets, `cargo-ndk`, Android SDK/NDK, and an emulator or device:
+
+```sh
+rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
+cargo install cargo-ndk
+react-native-rust build android
+```
+
+iOS requires macOS, Xcode, and Rust Apple targets:
+
+```sh
+rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+react-native-rust build ios
+```
+
+If a platform build cannot be run, say which prerequisite is unavailable and rely on the fixture tests for the parts they cover.
+
+## Pull requests
+
+- Keep changes focused and explain the user-visible behavior or generator contract being changed.
+- Include or update tests for behavior changes.
+- Update the README when commands, supported types, platform requirements, or generated outputs change.
+- Run `npm test`, `npm pack --dry-run`, and `git diff --check` before submitting when possible.
+- Do not commit `node_modules`, Rust `target/` output, Android build output, or generated binaries.
+
+## Reporting issues
+
+For bugs or feature requests, include the CLI command, the relevant TypeScript `Spec` signature, operating system, toolchain versions, and the complete error output. Remove credentials and other private information before posting logs.

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026, DeveloperRejaul
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @rejaul/react-native-rust
+
+Generate Rust functions and native bindings from a React Native TurboModule TypeScript `Spec`. Write the API in TypeScript, implement its logic in Rust, and use the generated C ABI and C++ TurboModule bridge to call it from React Native.
+
+The CLI currently targets the **C++ TurboModule** template created by [`create-react-native-library`](https://www.npmjs.com/package/create-react-native-library).
+
+## Contents
+
+- [Requirements](#requirements)
+- [Create a library](#create-a-library)
+- [Add Rust functions](#add-rust-functions)
+- [Build and run](#build-and-run)
+- [Supported types](#supported-types)
+- [Publish](#publish)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Code of conduct](#code-of-conduct)
+- [Contact](#contact)
+- [License](#license)
+
+## Requirements
+
+- Node.js 18 or newer for the CLI. Use a Node.js version supported by `create-react-native-library` when scaffolding a project.
+- Rust stable (`rustup`, `cargo`).
+- Android builds: Android SDK/NDK and `cargo-ndk`.
+- iOS builds: macOS, Xcode command-line tools, and the Rust Apple targets.
+
+## Create a library
+
+Run from the parent folder where you want the library created:
+
+```sh
+npx --yes @rejaul/react-native-rust create react-native-awesome-library
+```
+
+The command runs `create-react-native-library`. In its prompts, select a **TurboModule using C++**. The CLI then initializes Rust from the generated TypeScript `Spec` and configures the C ABI, C++ methods, TypeScript wrappers, iOS CocoaPods linkage, Android CMake linkage, npm scripts, and Rust output ignore rules.
+
+Install the generated project's dependencies:
+
+```sh
+cd react-native-awesome-library
+yarn install
+```
+
+To run the CLI from its source checkout before publishing, use the checkout's path from the desired parent folder:
+
+```sh
+node /path/to/rust_to_cpp/bin/react-native-rust.js create react-native-awesome-library
+```
+
+To add Rust support to an existing C++ TurboModule library, install the CLI and initialize it from that library's root:
+
+```sh
+npm install --save-dev @rejaul/react-native-rust
+npx react-native-rust init
+```
+
+`init` refuses unsupported templates and existing `rust/` directories rather than overwriting them.
+
+## Add Rust functions
+
+The TypeScript `Spec` is the API source of truth. For example, declare a method in `src/NativeAwesomeLibrary.ts`:
+
+```ts
+export interface Spec extends TurboModule {
+  multiply(a: number, b: number): number;
+}
+```
+
+Generate Rust and native glue from the library root:
+
+```sh
+yarn rust:generate
+```
+
+The CLI creates a handler in `rust/src/api/multiply.rs`. Add the implementation there:
+
+```rust
+pub fn multiply(a: f64, b: f64) -> f64 {
+    a * b
+}
+```
+
+The generated Rust ABI wrapper, C++ TurboModule method, and TypeScript wrapper connect this function to React Native. Do not hand-edit generated C++ or wrapper code. After changing the `Spec`, run `yarn rust:generate` again. Existing Rust function bodies are preserved, and signature mismatches are reported.
+
+Run Rust tests with:
+
+```sh
+yarn rust:test
+```
+
+## Build and run
+
+Run these commands from the library root. Generate TurboModule Codegen output with `yarn prepare` before building the host app.
+
+### Android
+
+Install the Rust Android targets and `cargo-ndk` once:
+
+```sh
+rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
+cargo install cargo-ndk
+```
+
+Build the Rust archives and generate native Codegen output:
+
+```sh
+yarn rust:build:android
+yarn prepare
+```
+
+With an emulator running, start Metro in one terminal and launch Android from another:
+
+```sh
+cd example && yarn start --reset-cache
+```
+
+```sh
+cd example && yarn android
+```
+
+The example command builds only for the connected device's ABI. Rust archives are generated for `arm64-v8a`, `armeabi-v7a`, `x86`, and `x86_64`.
+
+### iOS
+
+Build the Rust XCFramework and generate native Codegen output:
+
+```sh
+yarn rust:build:ios
+yarn prepare
+```
+
+Install pods for the example app:
+
+```sh
+cd example/ios && pod install
+```
+
+Start Metro in one terminal and launch an iOS simulator from another:
+
+```sh
+cd example && yarn start --reset-cache
+```
+
+```sh
+cd example && yarn ios --simulator "iPhone 17 Pro"
+```
+
+Rust outputs are written under `rust/build/` and included in the generated library's npm package configuration. Build each platform on a machine with its native toolchain.
+
+The example screen in `example/src/App.tsx` exercises the supported scalar, JSON, Promise, and callback signatures.
+
+## Supported types
+
+The generator supports these TypeScript-to-Rust/C++ mappings:
+
+| TypeScript | Rust | C++ |
+| --- | --- | --- |
+| `number` | `f64` | `double` |
+| `boolean` | `bool` | `bool` |
+| `string` | `String` | `jsi::String` |
+| `T[]`, `Array<T>`, `ReadonlyArray<T>` | `serde_json::Value` | `jsi::Array` |
+| `CodegenTypes.UnsafeObject` | `serde_json::Value` | `jsi::Object` |
+| `void` return | `()` | `void` |
+| `Promise<T>` return | `Result<T, String>` | `jsi::Value` |
+| `(args) => void` parameter | `&mut dyn FnMut(args)` | `jsi::Function` |
+
+Arrays and `UnsafeObject` values cross the native boundary as JSON, so their contents must be JSON-safe. Promise results may use supported payload types, but nested Promises are not supported. Callbacks are invoked synchronously during the Rust handler call and may have up to four explicitly typed parameters; they must not be retained or called later. Promise methods cannot accept callbacks.
+
+Typed object structs, optional or rest parameters, destructured parameters, generic methods, and overloads are not supported. Unsupported signatures fail before generated files are changed.
+
+## Publish
+
+Before publishing a generated React Native library, generate its TypeScript/native outputs and build the Rust artifacts for the platforms you intend to ship:
+
+```sh
+yarn prepare
+yarn rust:build:ios
+yarn rust:build:android
+npm pack --dry-run
+```
+
+To validate and publish this CLI package:
+
+```sh
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+Pushing a version tag such as `v1.0.1` runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which tests and publishes the matching package version. Configure npm trusted publishing for this repository and workflow before using the action; it publishes with provenance and does not require an `NPM_TOKEN` secret.
+
+## Troubleshooting
+
+- `cargo: command not found`: install Rust with `rustup`, then open a new terminal or run `source "$HOME/.cargo/env"`.
+- Android CMake cannot find `android/generated/jni`: run `yarn prepare` from the library root.
+- Android CMake cannot find a Rust `.a` archive: run `yarn rust:build:android` before launching the example.
+- iOS reports a missing Rust XCFramework: run `yarn rust:build:ios`, then `pod install` in `example/ios`.
+- A React Native type is reported as unsupported: check the mappings and signature restrictions in [Supported types](#supported-types).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines. Bug reports, feature requests, and pull requests are welcome. For code changes, run the CLI test suite and package check before submitting:
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+When changing type mappings or generated output, include tests for supported signatures, regeneration behavior, and unsupported signatures.
+
+## Code of conduct
+
+Participation in this project follows the [Code of Conduct](CODE_OF_CONDUCT.md). Please report conduct concerns through the repository's contact options.
+
+## Contact
+
+- Issues and feature requests: [GitHub Issues](https://github.com/DeveloperRejaul/react-native-rust/issues)
+- Repository and maintainer: [DeveloperRejaul/react-native-rust](https://github.com/DeveloperRejaul/react-native-rust)
+
+## License
+
+This project is distributed under the [ISC License](LICENSE).

package/bin/codegen/constants.js

@@ -0,0 +1,39 @@
+const ts = require('typescript');
+
+const HEADER_START = '// react-native-rust:generated-methods:start';
+const HEADER_END = '// react-native-rust:generated-methods:end';
+const SOURCE_START = '// react-native-rust:generated-methods:start';
+const SOURCE_END = '// react-native-rust:generated-methods:end';
+
+const rustKeywords = new Set([
+  'as', 'async', 'await', 'break', 'const', 'continue', 'crate', 'dyn', 'else', 'enum', 'extern', 'false',
+  'fn', 'for', 'if', 'impl', 'in', 'let', 'loop', 'match', 'mod', 'move', 'mut', 'pub', 'ref', 'return',
+  'self', 'Self', 'static', 'struct', 'super', 'trait', 'true', 'type', 'unsafe', 'use', 'where', 'while',
+]);
+
+const cppKeywords = new Set([
+  'alignas', 'alignof', 'and', 'asm', 'auto', 'bool', 'break', 'case', 'catch', 'char', 'class', 'const',
+  'continue', 'default', 'delete', 'do', 'double', 'else', 'enum', 'explicit', 'export', 'extern', 'false',
+  'float', 'for', 'friend', 'goto', 'if', 'inline', 'int', 'long', 'namespace', 'new', 'noexcept', 'not',
+  'nullptr', 'operator', 'or', 'private', 'protected', 'public', 'register', 'return', 'short', 'signed',
+  'sizeof', 'static', 'struct', 'switch', 'template', 'this', 'throw', 'true', 'try', 'typedef', 'typename',
+  'union', 'unsigned', 'using', 'virtual', 'void', 'volatile', 'while', 'xor',
+]);
+
+const supportedTypes = new Map([
+  [ts.SyntaxKind.NumberKeyword, { kind: 'number', typescript: 'number', rust: 'f64', cpp: 'double', defaultValue: '0.0' }],
+  [ts.SyntaxKind.BooleanKeyword, { kind: 'boolean', typescript: 'boolean', rust: 'bool', cpp: 'bool', defaultValue: 'false' }],
+  [ts.SyntaxKind.StringKeyword, { kind: 'json', typescript: 'string', rust: 'String', cpp: 'jsi::String', defaultValue: 'String::new()' }],
+  [ts.SyntaxKind.VoidKeyword, { kind: 'void', typescript: 'void', rust: '()', cpp: 'void', defaultValue: null }],
+]);
+
+module.exports = {
+  HEADER_START,
+  HEADER_END,
+  SOURCE_START,
+  SOURCE_END,
+  rustKeywords,
+  cppKeywords,
+  supportedTypes,
+  ts,
+};

package/bin/codegen/index.js

@@ -0,0 +1,9 @@
+const { parseSpec } = require('./spec');
+const { renderRustFfiModule } = require('./renderers');
+const { renderProjectBindings } = require('./project');
+
+module.exports = {
+  parseSpec,
+  renderRustFfiModule,
+  renderProjectBindings,
+};

package/bin/codegen/project.js

@@ -0,0 +1,168 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  HEADER_START,
+  HEADER_END,
+  SOURCE_START,
+  SOURCE_END,
+} = require('./constants');
+const { renderCppMethods, renderRustExports, renderRustHandler, renderRustModuleList, renderWrappers } = require('./renderers');
+
+function replaceMarkedRegion(source, startMarker, endMarker, generated) {
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker);
+  if (start < 0 || end < start) return null;
+  const block = `${startMarker}\n${generated}\n${endMarker}`;
+  return `${source.slice(0, start)}${block}${source.slice(end + endMarker.length)}`;
+}
+
+function replaceTemplateMethod(source, markerStart, markerEnd, generated, methodNeedle) {
+  const functionIndex = source.indexOf(methodNeedle);
+  if (functionIndex < 0) throw new Error(`Could not locate C++ template method "${methodNeedle}".`);
+  const lineStart = source.lastIndexOf('\n', functionIndex) + 1;
+  const bodyStart = source.indexOf('{', functionIndex);
+  if (bodyStart < 0) throw new Error(`Could not locate the body for C++ method "${methodNeedle}".`);
+  let depth = 0;
+  let bodyEnd = -1;
+  for (let index = bodyStart; index < source.length; index += 1) {
+    if (source[index] === '{') depth += 1;
+    if (source[index] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        bodyEnd = index + 1;
+        break;
+      }
+    }
+  }
+  if (bodyEnd < 0) throw new Error(`Could not find the end of C++ method "${methodNeedle}".`);
+  const block = `${markerStart}\n${generated}\n${markerEnd}`;
+  return `${source.slice(0, lineStart)}${block}${source.slice(bodyEnd)}`;
+}
+
+function hasDefaultMultiplyBody(source, moduleName) {
+  const methodIndex = source.indexOf(`${moduleName}Impl::multiply(`);
+  if (methodIndex < 0) return false;
+  const bodyStart = source.indexOf('{', methodIndex);
+  if (bodyStart < 0) return false;
+  let depth = 0;
+  for (let index = bodyStart; index < source.length; index += 1) {
+    if (source[index] === '{') depth += 1;
+    if (source[index] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return source.slice(bodyStart + 1, index).replace(/\s+/g, '') === 'returna*b;';
+      }
+    }
+  }
+  return false;
+}
+
+function updateCppFile(source, markers, generated, templateMethod, methodNeedle, includeRustHeader = false) {
+  let updated = source;
+  if (includeRustHeader && !updated.includes('../rust/include/rust_api.h')) {
+    if (!updated.includes('#pragma once')) throw new Error('Unsupported C++ module header template.');
+    updated = updated.replace('#pragma once', '#pragma once\n\n#include "../rust/include/rust_api.h"');
+  }
+  const marked = replaceMarkedRegion(updated, markers[0], markers[1], generated);
+  if (marked !== null) return marked;
+  if (updated.includes(markers[0]) || updated.includes(markers[1])) {
+    throw new Error('Incomplete react-native-rust generated markers found in C++ source.');
+  }
+  if (!templateMethod) throw new Error('C++ generated markers are missing; refusing to overwrite the module.');
+  if (methodNeedle.endsWith(';')) {
+    const count = updated.split(methodNeedle).length - 1;
+    if (count !== 1) throw new Error('Could not uniquely locate the C++ template method declaration.');
+    return updated.replace(methodNeedle, `${markers[0]}\n${generated}\n${markers[1]}`);
+  }
+  return replaceTemplateMethod(updated, markers[0], markers[1], generated, methodNeedle);
+}
+
+function normalizeSignature(text) {
+  return text.replace(/\s+/g, '');
+}
+
+function validateExistingHandler(filePath, method) {
+  const contents = fs.readFileSync(filePath, 'utf8');
+  const signaturePattern = new RegExp(`pub\\s+fn\\s+${method.rustName}\\s*\\(([^)]*)\\)\\s*->\\s*([^\\{]+)\\{`);
+  const match = contents.match(signaturePattern);
+  const args = method.params.map((param) => {
+    if (param.kind !== 'callback') return `${param.name}: ${param.rust}`;
+    const callbackTypes = param.params.map((callbackParam) => callbackParam.rust).join(', ');
+    return `${param.name}: &mut dyn FnMut(${callbackTypes})`;
+  }).join(', ');
+  const returnType = method.returnType.promise
+    ? `Result<${method.returnType.rust}, String>`
+    : method.returnType.rust;
+  const expected = `${method.rustName}(${args}) -> ${returnType}`;
+    const expectedSignature = `pub fn ${expected} {`;
+    if (normalizeSignature(contents).includes(normalizeSignature(expectedSignature))) return;
+  if (!match || normalizeSignature(match[0].replace(/^pub\s+fn\s+/, '').replace(/\{\s*$/, '')) !== normalizeSignature(expected)) {
+    throw new Error(`Rust handler ${path.relative(process.cwd(), filePath)} does not match the TypeScript Spec. Update its signature before regenerating.`);
+  }
+}
+
+function renderProjectBindings(root, moduleName, methods, initialize) {
+  const headerPath = path.join(root, 'cpp', `${moduleName}Impl.h`);
+  const sourcePath = path.join(root, 'cpp', `${moduleName}Impl.cpp`);
+  const header = fs.readFileSync(headerPath, 'utf8');
+  const source = fs.readFileSync(sourcePath, 'utf8');
+  if (initialize && !hasDefaultMultiplyBody(source, moduleName)) {
+    throw new Error('The C++ multiply demo was customized; move its logic into Rust before running init. No files were changed.');
+  }
+  const cpp = renderCppMethods(methods, moduleName);
+  const generatedIncludes = cpp.source.match(/^#include .+$/gm) || [];
+  const cppSource = cpp.source.replace(/^#include .+\n/gm, '');
+  const headerTemplateMethod = 'double multiply(jsi::Runtime& rt, double a, double b);';
+  const sourceTemplateMethod = `${moduleName}Impl::multiply(`;
+  const updatedHeader = updateCppFile(header, [HEADER_START, HEADER_END], cpp.header, initialize, headerTemplateMethod, true);
+  let updatedSource = updateCppFile(source, [SOURCE_START, SOURCE_END], cppSource, initialize, sourceTemplateMethod);
+  if (generatedIncludes.length > 0) {
+    const namespaceIndex = updatedSource.indexOf('\nnamespace facebook::react {');
+    if (namespaceIndex < 0) throw new Error('Could not locate the C++ namespace for generated includes.');
+    const missingIncludes = generatedIncludes.filter((include) => !updatedSource.includes(include));
+    if (missingIncludes.length > 0) {
+      const insertionPoint = namespaceIndex + 1;
+      updatedSource = `${updatedSource.slice(0, insertionPoint)}${missingIncludes.join('\n')}\n${updatedSource.slice(insertionPoint)}`;
+    }
+  }
+
+  const rustDirectory = path.join(root, 'rust', 'src');
+  const moduleList = renderRustModuleList(methods);
+  const updates = new Map([
+    [headerPath, updatedHeader],
+    [sourcePath, updatedSource],
+    [path.join(rustDirectory, 'lib.rs'), renderRustExports(methods)],
+    [path.join(rustDirectory, 'api', 'mod.rs'), moduleList],
+  ]);
+  for (const method of methods) {
+    const handlerPath = path.join(rustDirectory, 'api', `${method.rustName}.rs`);
+    if (fs.existsSync(handlerPath)) validateExistingHandler(handlerPath, method);
+    else updates.set(handlerPath, renderRustHandler(method));
+  }
+
+  const wrappers = renderWrappers(methods, moduleName);
+  const generatedModulePath = path.join(root, 'src', 'rust-generated');
+  updates.set(`${generatedModulePath}.tsx`, wrappers.fallback);
+  updates.set(`${generatedModulePath}.native.tsx`, wrappers.native);
+  const indexPath = path.join(root, 'src', 'index.tsx');
+  let index = fs.readFileSync(indexPath, 'utf8');
+  for (const method of methods) {
+    const oldExport = new RegExp(`^export\\s*\\{\\s*${method.name}\\s*\\}\\s*from\\s*['"]\\./${method.name}['"];?\\s*$`, 'm');
+    index = index.replace(oldExport, '');
+  }
+  if (!index.includes("export * from './rust-generated';")) {
+    index = `${index.trimEnd()}\nexport * from './rust-generated';\n`;
+  }
+  updates.set(indexPath, index);
+  return updates;
+}
+
+module.exports = {
+  replaceMarkedRegion,
+  replaceTemplateMethod,
+  hasDefaultMultiplyBody,
+  updateCppFile,
+  normalizeSignature,
+  validateExistingHandler,
+  renderProjectBindings,
+};