24601/surreal-skills

Surrealism - Extensiones WASM para SurrealDB

Nuevo en SurrealDB 3. Escribe funciones personalizadas en Rust, compílalas a WebAssembly (WASM) y desplegualas como módulos nativos de base de datos invocables desde SurrealQL.

Requisitos previos

• Herramientas de Rust (stable) con el target wasm32-unknown-unknown
• CLI de SurrealDB v3.1.4+ (binario surreal con el subcomando surreal module)
• Familiaridad con SurrealQL DEFINE MODULE y DEFINE BUCKET

Flujo de trabajo de desarrollo

1. Anotar    -- surrealism.toml + #[surrealism] en funciones Rust
2. Compilar  -- surreal module compile  (produce binario .wasm)
3. Registrar -- DEFINE BUCKET + DEFINE MODULE en SurrealQL

Inicio rápido

# Crear un nuevo proyecto Surrealism
cargo new --lib my_extension
cd my_extension

# Agregar el target WASM
rustup target add wasm32-unknown-unknown

# Crear surrealism.toml (manifiesto requerido)
cat > surrealism.toml << 'TOML'
[package]
name = "my_extension"
version = "0.1.0"
TOML

# Escribir la extensión (anotar con #[surrealism])
cat > src/lib.rs << 'RUST'
use surrealism::surrealism;

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

# Compilar a WASM usando la CLI de SurrealDB
surreal module compile

# Registrar en SurrealDB
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

-- Conceder acceso al archivo WASM
DEFINE BUCKET my_bucket;

-- Registrar las funciones del módulo
DEFINE MODULE my_extension FROM 'my_bucket:my_extension.wasm';

-- Usar la función en consultas
SELECT my_extension::greet('Mundo');

Casos de uso

• Funciones escalares personalizadas invocables desde SurrealQL
• Generación de datos falsos/de prueba para testing
• Lógica específica de dominio (procesamiento de lenguaje, finanzas cuantitativas, codificación personalizada)
• Acceso a funcionalidades de crates Rust especializados que son demasiado específicas para el núcleo de SurrealDB
• Analizadores personalizados para búsqueda de texto completo

Estado

Surrealism está en desarrollo activo y aún no es estable. La API puede cambiar entre versiones de SurrealDB 3.x. Envía comentarios a través de issues/PRs de GitHub en el repositorio surrealdb/surrealdb.

Documentación completa

Consulta el archivo de reglas del skill principal para obtener una guía completa:

• rules/surrealism.md -- configuración del proyecto, firmas de funciones Rust, compilación WASM, sintaxis de DEFINE MODULE/BUCKET, despliegue, pruebas y mejores prácticas
• Documentación de Extensiones de SurrealDB -- documentación oficial
• Comando de módulo CLI -- referencia de surreal module