surrealism

# Surrealism -- WASM Extensions for SurrealDB

New in SurrealDB 3. Write custom functions in Rust, compile them to WebAssembly
(WASM), and deploy them as native database modules callable from SurrealQL.

## Prerequisites

- Rust toolchain (stable) with `wasm32-unknown-unknown` target
- SurrealDB CLI v3.0.0+ (`surreal` binary with `surreal module` subcommand)
- Familiarity with SurrealQL `DEFINE MODULE` and `DEFINE BUCKET`

## Development Workflow

```
1. Annotate   -- surrealism.toml + #[surrealism] on Rust functions
2. Compile    -- surreal module compile  (produces .wasm binary)
3. Register   -- DEFINE BUCKET + DEFINE MODULE in SurrealQL
```

## Quick Start

```bash
# Create a new Surrealism project
cargo new --lib my_extension
cd my_extension

# Add the WASM target
rustup target add wasm32-unknown-unknown

# Create surrealism.toml (required manifest)
cat > surrealism.toml << 'TOML'
[package]
name = "my_extension"
version = "0.1.0"
TOML

# Write your extension (annotate with #[surrealism])
cat > src/lib.rs << 'RUST'
use surrealism::surrealism;

#[surrealism]
fn greet(name: String) -> String {
    format!("Hello, {}!", name)
}
RUST

# Compile to WASM using SurrealDB CLI
surreal module compile

# Register in SurrealDB
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test
```

```surql
-- Grant access to the WASM file
DEFINE BUCKET my_bucket;

-- Register the module functions
DEFINE MODULE my_extension FROM 'my_bucket:my_extension.wasm';

-- Use the function in queries
SELECT my_extension::greet('World');
```

## Use Cases

- Custom scalar functions callable from SurrealQL
- Fake/mock data generation for testing
- Domain-specific logic (language processing, quantitative finance, custom encoding)
- Access to niche Rust crate functionality too specific for core SurrealDB
- Custom analyzers for full-text search

## Status

Surrealism is actively in development and not yet stable. The API may change
between SurrealDB 3.x releases. File feedback via GitHub issues/PRs on the
[surrealdb/surrealdb](https://github.com/surrealdb/surrealdb) repository.

## Full Documentation

See the main skill's rule file for complete guidance:
- **[rules/surrealism.md](../../rules/surrealism.md)** -- project setup, Rust function signatures, WASM compilation, DEFINE MODULE/BUCKET syntax, deployment, testing, and best practices
- **[SurrealDB Extensions Docs](https://surrealdb.com/docs/surrealdb/extensions)** -- official documentation
- **[CLI module command](https://surrealdb.com/docs/surrealdb/cli/module)** -- `surreal module` reference