fresh-plugin-api-macros 0.1.83

Proc macros for Fresh plugin API type-safe bindings
Documentation

Fresh Plugin API Macros

Proc macros for generating TypeScript definitions from Rust QuickJS API implementations.

Overview

This crate provides the #[plugin_api_impl] attribute macro that:

  1. Parses method signatures from a JsEditorApi impl block
  2. Generates TypeScript type definitions (.d.ts)
  3. Automatically writes to plugins/lib/fresh.d.ts during compilation

Usage

use fresh_plugin_api_macros::{plugin_api, plugin_api_impl};

#[plugin_api_impl]
#[rquickjs::methods(rename_all = "camelCase")]
impl JsEditorApi {
    /// Get the active buffer ID (0 if none)
    pub fn get_active_buffer_id(&self) -> u32 { ... }

    /// Create a virtual buffer (async)
    #[plugin_api(async_promise, js_name = "createVirtualBuffer", ts_return = "number")]
    #[qjs(rename = "_createVirtualBufferStart")]
    pub fn create_virtual_buffer_start(&self, opts: Object) -> u64 { ... }
}

Attributes

#[plugin_api_impl]

Apply to the impl block to enable TypeScript generation. Generates:

  • {IMPL_NAME}_TYPESCRIPT_DEFINITIONS: &str - Full .d.ts content
  • {IMPL_NAME}_JS_METHODS: &[&str] - List of all JS method names

#[plugin_api(...)]

Apply to individual methods for customization:

Attribute Description Example
skip Exclude from TypeScript #[plugin_api(skip)]
js_name = "..." Custom JS method name #[plugin_api(js_name = "myMethod")]
async_promise Returns Promise<T> #[plugin_api(async_promise)]
async_thenable Returns ProcessHandle<T> (cancellable) #[plugin_api(async_thenable)]
ts_type = "..." Custom TypeScript type for parameter #[plugin_api(ts_type = "BufferInfo")]
ts_return = "..." Custom TypeScript return type #[plugin_api(ts_return = "string")]

Type Mapping

Rust Type TypeScript Type Notes
u8, u16, u32, i32, etc. number All numeric types
bool boolean
String, &str string
() void
Option<T> T | null
Vec<T> T[]
rquickjs::Ctx<'js> (skipped) Runtime context
rquickjs::function::Opt<T> T? Optional parameter
rquickjs::function::Rest<T> ...T[] Variadic parameter
rquickjs::Result<T> T Unwrapped
rquickjs::Object<'js> Record<string, unknown> Use ts_type for specifics

Async Methods

Async methods must be explicitly marked with #[plugin_api(async_promise)] or #[plugin_api(async_thenable)]. There is no heuristic-based detection.

  • async_promise: For operations that complete with a result
  • async_thenable: For cancellable operations (e.g., process spawning)

File Output

The macro automatically writes plugins/lib/fresh.d.ts when:

  1. Building the main crate (not the macro crate)
  2. The content has changed (avoids unnecessary rebuilds)

Design Principles

  1. Single Source of Truth: API defined once in Rust, TypeScript generated
  2. Explicit Over Implicit: No magic naming conventions, use attributes
  3. Deterministic Output: Same input always produces same output
  4. Preserve Original Code: Macro passes through impl block unchanged
  5. Clear Errors: Compile-time errors with helpful messages