# tsnp-metric-api

**ts-native plugin for [metric-api](https://crates.io/crates/metric-api)**

This directory contains auto-generated configuration files for using the `metric-api` Rust crate with ts-native runtime. These files enable TypeScript code to call Rust FFI functions directly without Node.js.

## Generated Files

| File | Description |
|------|-------------|
| `ts-native.toml` | Plugin configuration: function mappings, library linkage |
| `index.d.ts` | TypeScript type definitions for FFI functions |
| `README.md` | This documentation file |

## Quick Start

### 1. Add Rust Dependency

Add the crate to your project's `Cargo.toml`:

```toml
[dependencies]
metric-api = "0.1.0"
```

### 2. Build Native Library

Build your Rust project to generate the native library (`.dll` / `.so` / `.dylib`):

```bash
cargo build --release
```

### 3. Import in TypeScript

Use the generated type definitions in your TypeScript code:

```typescript
import { /* function names */ } from "tsnp-metric-api";

// Example (replace with actual function names):
// const result = someFunction(arg1, arg2);
```

### 4. Configure ts-native Runtime

Ensure ts-native runtime can locate the native library. The runtime will:
- Load the library specified in `[link].lib`
- Resolve function names according to `[functions]` mapping
- Handle type conversions between TypeScript and Rust

## Manual Configuration

If the auto-generated configuration is incomplete or incorrect, edit `ts-native.toml`:

### Adding Functions

```toml
[functions]
"tsFunctionName" = { impl_name = "rust_function_name" }
```

### Changing Library Name

```toml
[link]
lib = "custom-lib-name"
```

### Multiple Libraries

```toml
[link]
libs = ["lib1", "lib2"]
```

## Type Mapping Reference

| Rust Type | TypeScript Type |
|-----------|-----------------|
| `i32`, `u32`, `i64`, `u64` | `number` |
| `f32`, `f64` | `number` |
| `*const c_char`, `*mut c_char` | `string` |
| `*const T`, `*mut T` | `number` (pointer) |
| `()` | `void` |

**Unsupported Types** (require manual wrappers):
- `Option<T>`, `Result<T, E>`
- `Vec<T>`, `String` (by value)
- Structs with non-POD fields
- Callbacks / function pointers

## Troubleshooting

### "Library not found"
- Ensure the Rust crate is built with `cargo build --release`
- Check that `[link].lib` matches the actual library name
- Verify library search path configuration in ts-native runtime

### "Function not found"
- Verify the function is marked with `#[no_mangle]` and `extern "C"`
- Check the function name in `[functions]` matches exactly
- Use `nm` or `objdump` to list exported symbols

### Type mismatch errors
- Review the type mapping table above
- Add manual wrappers for unsupported types
- Check that Rust and TypeScript types are compatible

## Regenerating Files

To regenerate these files with updated FFI functions:

```bash
cargo tsnp gen metric-api
```

## Links

- [ts-native Runtime](https://github.com/itszzl-sudo/ts-native)
- [Original crate on crates.io](https://crates.io/crates/metric-api)
- [tsnp Tool](https://github.com/itszzl-sudo/tsnp)

---
*Generated by tsnp - TypeScript Native Plugin Generator*
