celox-napi 0.4.1

N-API/WASI simulator handles and frontend adapter API for Celox
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# celox-napi

Rust adapter API and N-API/WASI handles for Celox. This crate is useful to
frontend authors that ship their own native addon and want to expose a
frontend-specific constructor without serializing a Celox artifact as JSON.

The frontend addon accepts its own artifact type, lowers it with
`celox-frontend-sdk`, and returns the standard handle:

```rust
use celox_frontend_sdk::FrontendArtifact;
use celox_napi::NativeSimulatorHandle;
use napi::Result;
use napi_derive::napi;

#[napi(object)]
pub struct MyArtifact {
    // Fields owned by this frontend.
    pub module_name: String,
}

fn lower_to_celox(artifact: MyArtifact) -> Result<FrontendArtifact> {
    # todo!()
}

#[napi]
pub fn from_my_artifact(artifact: MyArtifact) -> Result<NativeSimulatorHandle> {
    NativeSimulatorHandle::from_frontend(lower_to_celox(artifact)?, None)
}
```

The frontend's TypeScript package can expose the API its users expect:

```ts
import { Simulator, type FrontendSimulatorHandle } from "@celox-sim/celox";
import { fromMyArtifact as nativeFromMyArtifact } from "./native.js";

export function fromMyArtifact<P>(artifact: MyArtifact): Simulator<P> {
  const handle: FrontendSimulatorHandle = nativeFromMyArtifact(artifact);
  return Simulator.fromFrontendHandle<P>(handle);
}
```

`MyArtifact` remains the frontend's public model. Its conversion happens inside
Rust, directly into `FrontendArtifact`; the frontend artifact is not transported
as JSON.

See `examples/my-frontend-napi` in the Celox repository for a buildable addon.