# SuperFFI - Multi-Language FFI Binding Generator
[](https://crates.io/crates/superffi)
[](https://docs.rs/superffi)
[](https://github.com/deepbrainspace/superconfig)
**SuperFFI** is a procedural macro that automatically generates FFI bindings for multiple target languages from your Rust code. Write once, run everywhere.
## Features
- **Python bindings** via PyO3 (preserves `snake_case` naming)
- **Node.js bindings** via NAPI-RS (automatic `camelCase` conversion)
- **WebAssembly bindings** via wasm-bindgen (automatic `camelCase` conversion)
- **Automatic naming conversion** for consistent JavaScript APIs
- **Zero-cost abstractions** - only generates code for enabled features
- **Simple annotation** - just add `#[superffi]` to your items
## Installation
```toml
[dependencies]
superffi = { version = "0.1", features = ["python", "nodejs", "wasm"] }
```
**Features:**
- `python` - PyO3 bindings for Python
- `nodejs` - NAPI bindings for Node.js
- `wasm` - wasm-bindgen bindings for WebAssembly (browser + WASI)
- `all` - All target languages
## Quick Start
```rust
use superffi::superffi;
#[superffi]
pub struct Calculator {
pub value: f64,
}
#[superffi]
impl Calculator {
pub fn new(initial_value: f64) -> Self {
Self { value: initial_value }
}
pub fn add(&mut self, other: f64) {
self.value += other;
}
pub fn get_value(&self) -> f64 {
self.value
}
}
#[superffi]
pub fn fibonacci(n: u32) -> u64 {
match n {
0 => 0,
1 => 1,
_ => fibonacci(n - 1) + fibonacci(n - 2),
}
}
```
## Usage
Apply `#[superffi]` to:
- **Structs** → generates class/object bindings
- **Impl blocks** → generates method bindings
- **Functions** → generates standalone function bindings
## Language Usage Examples
### Python
```python
import your_library
calc = your_library.Calculator(10.0)
calc.add(5.0)
print(calc.get_value()) # 15.0
print(your_library.fibonacci(10)) # 55
```
### Node.js
```javascript
const lib = require('./target/release/your_library.node');
const calc = new lib.Calculator(10.0);
calc.add(5.0);
console.log(calc.getValue()); // 15.0 (NAPI converts get_value → getValue)
console.log(lib.fibonacci(10)); // 55
```
### WebAssembly (Browser + WASI)
```javascript
import init, { Calculator, fibonacci } from './pkg/your_library.js';
await init();
const calc = new Calculator(10.0);
calc.add(5.0);
console.log(calc.getValue()); // 15.0 (SuperFFI converts get_value → getValue)
console.log(fibonacci(10)); // 55
```
## 🎯 Language-Specific Usage
### Python
After building your Rust library with the `python` feature:
```python
import your_rust_library
# Create and use structs
calc = your_rust_library.Calculator(10.0)
calc.add(5.0)
calc.multiply(2.0)
print(calc.get_value()) # Output: 30.0
# Use standalone functions
result = your_rust_library.fibonacci(10)
print(result) # Output: 55
```
### Node.js
After building your Rust library with the `nodejs` feature:
```javascript
const lib = require('./target/release/your_rust_library.node');
// Create and use structs
const calc = new lib.Calculator(10.0);
calc.add(5.0);
calc.multiply(2.0);
console.log(calc.getValue()); // Output: 30.0 (get_value → getValue)
// Use standalone functions
const result = lib.fibonacci(10);
console.log(result); // Output: 55
```
### WebAssembly
After building your Rust library with the `wasm` feature:
```javascript
import init, { Calculator, fibonacci } from './pkg/your_rust_library.js';
async function run() {
await init();
// Create and use structs
const calc = new Calculator(10.0);
calc.add(5.0);
calc.multiply(2.0);
console.log(calc.getValue()); // Output: 30.0 (get_value → getValue)
// Use standalone functions
const result = fibonacci(10);
console.log(result); // Output: 55
}
run();
```
## 🔄 Automatic Naming Convention
SuperFFI automatically handles naming conventions for different target languages:
| `get_value()` | `get_value()` | `getValue()` | `getValue()` |
| `set_debug()` | `set_debug()` | `setDebug()` | `setDebug()` |
| `with_file()` | `with_file()` | `withFile()` | `withFile()` |
| `extract_json()` | `extract_json()` | `extractJson()` | `extractJson()` |
- **Python**: Preserves `snake_case` (Pythonic)
- **Node.js**: NAPI automatically converts to `camelCase`
- **WebAssembly**: SuperFFI converts to `camelCase` for JavaScript consistency
This ensures your APIs feel natural in each target language while maintaining consistent functionality.
## 🏗️ Build Configuration
### For Python (PyO3)
Add to your `Cargo.toml`:
```toml
[lib]
name = "your_rust_library"
crate-type = ["cdylib"]
[dependencies]
superffi = { version = "0.1", features = ["python"] }
pyo3 = { version = "0.25", features = ["extension-module"] }
```
Build command:
```bash
maturin develop # For development
maturin build --release # For production
```
### For Node.js (NAPI)
Add to your `package.json`:
```json
{
"napi": {
"name": "your-rust-library",
"triples": {
"defaults": true
}
}
}
```
Build command:
```bash
napi build --platform --release
```
### For WebAssembly
Build command:
```bash
wasm-pack build --target web --out-dir pkg
```
## ⚠️ Limitations
- **Async functions**: Not currently supported across all target languages
- **Complex generics**: May not translate directly to all target languages
- **Advanced lifetimes**: Rust-specific lifetime annotations may not be supported
- **Trait objects**: Not directly supported; use concrete types instead
- **Custom derives**: May conflict with generated bindings
## 🛠️ Supported Types
### Primitive Types
- `bool`, `i8`, `i16`, `i32`, `i64`, `isize`
- `u8`, `u16`, `u32`, `u64`, `usize`
- `f32`, `f64`
- `char`
### Standard Library Types
- `String`
- `Vec<T>` (where T is supported)
- `Option<T>` (where T is supported)
- `HashMap<K, V>` (limited support)
### Custom Types
- Structs annotated with `#[superffi]`
- Enums (limited support, varies by target language)
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Development Setup
1. Clone the repository
2. Install Rust nightly (required for proc-macro development)
3. Run tests: `cargo test`
4. Run examples: `cargo run --example basic`
### Testing
Run the test suite:
```bash
cargo test
cargo test --all-features
```
Test with specific features:
```bash
cargo test --features python
cargo test --features nodejs
cargo test --features wasm
```
## 📄 License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## 🙏 Acknowledgments
- [PyO3](https://github.com/PyO3/pyo3) for Python FFI
- [NAPI-RS](https://github.com/napi-rs/napi-rs) for Node.js FFI
- [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) for WebAssembly FFI
- The Rust community for excellent procedural macro resources
---
**Happy coding! 🦀**