gear-mesh ⚙️

Next-generation Rust to TypeScript type definition sharing library.

Features

Feature	Description
Branded Types	Convert Rust newtype patterns to TypeScript Branded Types
Doc Comments	Rust doc comments → JSDoc
Validation	Generate runtime validation functions
Zod Schema	Generate Zod schemas for runtime validation
BigInt Support	Automatically use bigint for u64/i64

Installation

Add to your Cargo.toml:

[dependencies]
gear-mesh = "0.1"

Quick Start

1. Define your types

use gear_mesh::GearMesh;

#[derive(GearMesh)]
#[gear_mesh(branded)]
struct UserId(i32);

/// User information
#[derive(GearMesh)]
struct User {
    /// User's unique identifier
    id: UserId,
    /// User's display name
    name: String,
}

2. Generate TypeScript

Create a main.rs (or a separate binary/test) to run the generation:

fn main() {
    // Generate TypeScript types to the "generated" directory
    gear_mesh::generate_types_to_dir("generated")
        .expect("Failed to generate TypeScript types");
}

3. Generated TypeScript

// Branded Type helper
type Brand<T, B> = T & { readonly __brand: B };

export type UserId = Brand<number, "UserId">;
export const UserId = (value: number): UserId => value as UserId;

/**
 * User information
 */
export interface User {
    /** User's unique identifier */
    id: UserId;
    /** User's display name */
    name: string;
}

Configuration

You can customize the generation by using GeneratorConfig:

use gear_mesh::{GeneratorConfig, generate_with_config};

fn main() {
    let config = GeneratorConfig::new()
        .with_bigint(true)
        .with_branded(true)
        .with_zod(true) // Generate Zod schemas
        .with_validation(true); // Generate validation functions

    gear_mesh::generate_with_config("generated", config)
        .expect("Failed to generate");
}

Validation

gear-mesh supports automatic generation of Zod schemas with validation rules from Rust attributes.

Available Validation Rules

Validation	Rust Attribute	Generated Zod	Description
Range	#[validate(range(min = 0, max = 100))]	.min(0).max(100)	Numeric range validation
Length	#[validate(length(min = 1, max = 20))]	.min(1).max(20)	String length validation
Email	#[validate(email)]	.email()	Email format validation
URL	#[validate(url)]	.url()	URL format validation
Pattern	#[validate(pattern = "^[A-Z]")]	.regex(/^[A-Z]/)	Regex pattern matching

Usage Example

use gear_mesh::GearMesh;

#[derive(GearMesh)]
struct User {
    /// User's display name (1-20 characters)
    #[validate(length(min = 1, max = 20))]
    pub name: String,
    
    /// User's email address
    #[validate(email)]
    pub email: String,
    
    /// User's age (1-150)
    #[validate(range(min = 1, max = 150))]
    pub age: i32,
    
    /// User's website (optional)
    #[validate(url)]
    pub website: Option<String>,
}

Generated Zod Schema

import { z } from 'zod';

export interface User {
    /** User's display name (1-20 characters) */
    name: string;
    /** User's email address */
    email: string;
    /** User's age (1-150) */
    age: number;
    /** User's website (optional) */
    website?: string | null;
}

export const UserSchema = z.object({
    name: z.string().min(1).max(20),
    email: z.string().email(),
    age: z.number().min(1).max(150),
    website: z.string().url().nullable(),
});

BigInt Validation

When using use_bigint configuration, range validations automatically use BigInt literals:

#[derive(GearMesh)]
struct Transaction {
    #[validate(range(min = 0, max = 1000000000))]
    pub amount: u64,  // Automatically becomes bigint in TypeScript
}

Generated TypeScript:

export const TransactionSchema = z.object({
    amount: z.bigint().min(0n).max(1000000000n),
});

Comparison with Existing Crates

Feature	ts-rs	typeshare	specta	gear-mesh
Basic type conversion	✅	✅	✅	✅
Branded Types	❌	❌	❌	✅
Doc comment conversion	❌	❌	❌	✅
Zod Schema	❌	❌	❌	✅
Validation embedding	❌	❌	❌	✅
Auto BigInt	Manual	Manual	Manual	✅ Auto

Crate Structure

• gear-mesh - Main crate with re-exports
• gear-mesh-core - Intermediate representation (IR)
• gear-mesh-derive - #[derive(GearMesh)] proc-macro
• gear-mesh-generator - TypeScript code generator

Implementation Status

gear-mesh v0.1.0 implements:

• ✅ Basic type conversion
• ✅ Branded Type generation
• ✅ Doc comment conversion
• ✅ BigInt support
• ✅ Zod Schema generation
• ✅ Validation rules

See docs/IMPLEMENTATION_STATUS.md for detailed status and docs/FUTURE_ISSUES.md for planned features.

Testing

gear-mesh has comprehensive test coverage updated regularly.

• Unit tests covering core logic, generator, and derive macros.
• Integration tests validation the full pipeline from Rust types to TypeScript output.
• E2E tests ensuring compatibility with real TypeScript projects using Docker.

Run all tests:

cargo test --workspace

Or using moonrepo:

moon run :test

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.