Type generation

surrealkit typegen introspects a live database and emits a structured description of its schema. JSON is the primary output; TypeScript interfaces for the SurrealDB JavaScript SDK can be generated alongside it.

surrealkit typegen --user root --pass secret

By default this writes a JSON document to database/types/schema.json. SurrealKit's internal bookkeeping tables (__entity, __rollout) are excluded from the output.

Command flags

# Pretty-printed JSON to the default location
surrealkit typegen --user root --pass secret

# Pipe compact JSON into another tool
surrealkit typegen --stdout --compact --user root --pass secret

The JSON document includes the namespace, database, generation timestamp, and a typed description of every table, field, and function in the schema.

TypeScript output

TypeScript generation is opt-in through the [typegen] section of surrealkit.toml. Set typescript to the directory where the generated index.ts should be written:

[typegen]
typescript = "./src/types"
format = "biome check --write"

With typescript configured, surrealkit typegen writes both the JSON document and an index.ts:

// Generated by SurrealKit — do not edit.
// Run `surrealkit typegen` to regenerate.

import type { RecordId } from 'surrealdb';

export interface User {
  id: RecordId<'user'>;
  name: string;
  email: string;
}

The emitter targets the SurrealDB JavaScript SDK (v2): one interface per table, every record carrying a typed `id: RecordId`, with schema field types mapped to the SDK's wrapper types.

Formatter

When format is set, SurrealKit appends the generated file path to the command and runs it, so the output matches your project's house style. The command inherits the working directory so the formatter discovers your project's own config. Formatter failures (a missing binary or a non-zero exit) are reported as warnings and never fail typegen or sync --watch.

Regenerating on sync

When [typegen] typescript is configured, surrealkit sync --watch regenerates the TypeScript types whenever the schema changes, so your types stay current with the schema during local development:

surrealkit sync --watch --user root --pass secret

Regeneration is gated on actual schema changes (or a missing output file), so idle watch ticks do not re-introspect the database.

Library API

Type generation is also available from the surrealkit::typegen module when embedding SurrealKit in Rust:

use surrealkit::typegen::{generate, render_typescript, write_typescript};
use surrealkit::Surreal;
use surrealkit::engine::any::Any;

async fn run(db: &Surreal<Any>) -> anyhow::Result<()> {
    // Introspect the database into a structured document (no filesystem IO).
    let doc = generate(db).await?;

    // Render TypeScript as a string …
    let ts = render_typescript(&doc)?;
    println!("{ts}");

    // … or write it to `<dir>/index.ts`.
    write_typescript(&doc, std::path::Path::new("src/types"))?;
    Ok(())
}

generate returns a SchemaTypes document that the JSON and TypeScript emitters share, so a single introspection can produce both formats. write_typescript_formatted writes the file and runs an optional formatter command in the same call.

Next steps

• •

  Sync: keep the database aligned with your schema files

• •

  Using SurrealKit as a library: drive SurrealKit from Rust