typespec-rust-emitter 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-27
+
+### Changed
+
+- **Breaking**: Server trait methods now accept individual parameters instead of request structs
+  - `async fn subjects_create(&self, claims: Self::Claims, request: SubjectsCreateRequest)` → `async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody)`
+  - Path parameters extracted with `Path<T>` extractor
+  - Body extracted with `Json<T>` extractor
+  - Request structs (`SubjectsCreateRequest`, etc.) are no longer generated
+- **Breaking**: Extractor order in handlers follows axum conventions
+  - Order: `State` → `Extension` → `Path` → `Json`
+  - Fixes axum 0.8 `Handler` trait inference issues
+- Removed unused `Query` extractor import from generated code
+- Fixed decorator detection to use `getDecoratorName()` instead of direct property access
+
+### Benefits
+
+- Cleaner server trait API - no boilerplate request structs
+- Direct parameter access in handler implementations
+- Follows axum best practices for extractor ordering
+- Better IDE autocomplete for handler parameters
+
+### Example
+
+**TypeSpec:**
+
+```typespec
+@post
+@route("/groups/{groupId}/subjects")
+op create(@path groupId: int64, @body body: CreateSubjectBody): Subject;
+```
+
+**Before (v0.3.0):**
+
+```rust
+// Server trait
+async fn subjects_create(&self, claims: Self::Claims, request: SubjectsCreateRequest) -> Result<...>;
+
+// Handler
+axum::extract::Query(query): axum::extract::Query<SubjectsCreateRequest>
+let result = service.subjects_create(claims, query).await;
+```
+
+**After (v0.4.0):**
+
+```rust
+// Server trait
+async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody) -> Result<...>;
+
+// Handler
+Extension(claims): Extension<S::Claims>,
+Path(group_id): Path<i64>,
+Json(payload): Json<CreateSubjectBody>
+let result = service.subjects_create(claims, group_id, payload).await;
+```
+
+## [0.3.0] - 2026-03-27
+
+### Added
+
+- `@rustAttr` and `@rustAttrs` decorators for adding custom Rust attributes to models and enums
+  - Example: `@rustAttr("sqlx(type_name = \"user\")")` generates `#[sqlx(type_name = "user")]`
+- Support for `@rustDerive` and `@rustDerives` on enums (previously only models)
+  - Enables sqlx and other derive macros on enum types
+
+### Changed
+
+- Custom attributes are now rendered after `#[derive(...)]` for proper Rust syntax
+- Updated example to demonstrate `@rustDerive` + `@rustAttr` combination on enums
+
+### Example
+
+```typespec
+@rustDerive("sqlx::Type")
+@rustAttr("sqlx(type_name = \"study_status\")")
+enum StudyStatus {
+  Starting,
+  Paused,
+}
+```
+
+Generates:
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, sqlx::Type)]
+#[sqlx(type_name = "study_status")]
+pub enum StudyStatus {
+  #[serde(rename = "Starting")]
+  Starting,
+  #[serde(rename = "Paused")]
+  Paused,
+}
+```
+
 ## [0.2.0] - 2026-03-27
 
 ### Changed

package/QWEN.md

@@ -6,8 +6,8 @@
 
 - **Type**: TypeScript/Node.js project (TypeSpec emitter)
 - **Output**: Generates Rust structs, enums, server traits with serde, thiserror, axum support
-- **Main Entry**: `src/emitter.ts` (1450 lines) - core codegen logic
-- **Package**: `typespec-rust-emitter` v0.2.0
+- **Main Entry**: `src/emitter.ts` - core codegen logic
+- **Package**: `typespec-rust-emitter` v0.3.0
 
 ## Directory Structure
 
@@ -15,12 +15,12 @@
 typespec-emitter/
 ├── src/
 │   ├── emitter.ts          # MAIN: TypeSpec→Rust code generation
-│   ├── index.ts            # Exports ($onEmit, $rustDerive, $rustDerives)
+│   ├── index.ts            # Exports ($onEmit, $rustDerive, $rustDerives, $rustAttr, $rustAttrs)
 │   ├── lib.ts              # TypeSpec library definition
 │   ├── lib.tsp             # Decorator declarations
 │   └── testing/            # Test utilities
 ├── test/
-│   ├── hello.test.ts       # Unit tests (11 tests)
+│   ├── hello.test.ts       # Unit tests
 │   └── test-host.ts        # Test infrastructure (emit() helper)
 ├── example/
 │   ├── main.tsp            # Demo TypeSpec entry
@@ -37,6 +37,7 @@ typespec-emitter/
 ## Build & Run Commands
 
 ### Primary Workflow (Run After Every Change)
+
 ```bash
 just build      # Compile TypeScript (npm run build)
 just test       # Run unit tests (npm test)
@@ -45,6 +46,7 @@ just check-rust # Verify Rust compiles (cargo check)
 ```
 
 ### Individual Commands
+
 ```bash
 # Development
 npm run build       # tsc compile
@@ -61,47 +63,52 @@ just publish        # build + npm publish
 
 ## Type Mappings (TypeSpec → Rust)
 
-| TypeSpec | Rust |
-|----------|------|
-| `string` | `String` |
-| `int8/16/32/64` | `i8/i16/i32/i64` |
-| `uint8/16/32/64` | `u8/u16/u32/u64` |
-| `float32/64` | `f32/f64` |
-| `boolean` | `bool` |
-| `bytes` | `Vec<u8>` |
-| `T[]` | `Vec<T>` |
-| `Record<T>` | `HashMap<String, T>` |
-| `T \| null` | `Option<T>` |
+| TypeSpec         | Rust                 |
+| ---------------- | -------------------- |
+| `string`         | `String`             |
+| `int8/16/32/64`  | `i8/i16/i32/i64`     |
+| `uint8/16/32/64` | `u8/u16/u32/u64`     |
+| `float32/64`     | `f32/f64`            |
+| `boolean`        | `bool`               |
+| `bytes`          | `Vec<u8>`            |
+| `T[]`            | `Vec<T>`             |
+| `Record<T>`      | `HashMap<String, T>` |
+| `T \| null`      | `Option<T>`          |
 
 ### Format Mappings
-| `@format()` | Rust Type |
-|-------------|-----------|
-| `"uuid"` | `uuid::Uuid` |
-| `"date"` | `chrono::NaiveDate` |
-| `"time"` | `chrono::NaiveTime` |
+
+| `@format()`   | Rust Type               |
+| ------------- | ----------------------- |
+| `"uuid"`      | `uuid::Uuid`            |
+| `"date"`      | `chrono::NaiveDate`     |
+| `"time"`      | `chrono::NaiveTime`     |
 | `"date-time"` | `chrono::DateTime<Utc>` |
 
 ## Decorators
 
-| Decorator | Effect |
-|-----------|--------|
-| `@error` | Adds `thiserror::Error` derive + `#[error("{code}: {message}")]` |
-| `@pattern("regex")` | Generates `TryFrom<String>` with regex validation |
-| `@rustDerive("...")` | Adds custom derive (e.g., `sqlx::FromRow`) |
-| `@rustDerives("...", "...")` | Adds multiple custom derives |
-| `@doc("...")` | Generates `///` doc comments |
-| `@useAuth(BearerAuth)` | Marks operation as protected (adds `Claims` param) |
-| `@maxLength(n)` | Documentation only |
+| Decorator                    | Effect                                                                       |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `@error`                     | Adds `thiserror::Error` derive + `#[error("{code}: {message}")]`             |
+| `@pattern("regex")`          | Generates `TryFrom<String>` with regex validation                            |
+| `@rustDerive("...")`         | Adds custom derive (models & enums, e.g., `sqlx::FromRow`, `sqlx::Type`)     |
+| `@rustDerives("...", "...")` | Adds multiple custom derives (models & enums)                                |
+| `@rustAttr("...")`           | Adds custom Rust attribute (models & enums, e.g., `sqlx(type_name = "...")`) |
+| `@rustAttrs("...", "...")`   | Adds multiple custom attributes (models & enums)                             |
+| `@doc("...")`                | Generates `///` doc comments                                                 |
+| `@useAuth(BearerAuth)`       | Marks operation as protected (adds `Claims` param)                           |
+| `@maxLength(n)`              | Documentation only                                                           |
 
 ## Output Files
 
 ### types.rs
+
 - All models → `pub struct` with serde derives
 - Enums → `pub enum` with serde rename
 - Unions → `Option<T>` for nullable, or sum types
 - Scalars → `pub type` or `pub struct` (if pattern validation)
 
 ### server.rs
+
 - `Server` trait with `type Claims` associated type
 - Request structs per operation
 - Response enums with status code variants
@@ -110,6 +117,7 @@ just publish        # build + npm publish
 ## Key Implementation Details
 
 ### emitter.ts Architecture
+
 1. `navigateProgram()` - Walks TypeSpec AST
 2. Collects: models, enums, unions, scalars, operations
 3. Processes decorators (`@error`, `@pattern`, `@rustDerive`)
@@ -117,15 +125,19 @@ just publish        # build + npm publish
 5. Emits files to configured output directory
 
 ### Server Trait Generation
+
 - Generates `Server` trait with `type Claims: Send + Sync + 'static` associated type
-- Handler functions: `pub async fn {op}_handler<S>(...)` with `<S>` generics only
+- Handler functions accept individual parameters (path params, body) directly
+- Path params extracted with `Path<T>`
+- Body extracted with `Json<T>`
 - Protected routes (`@useAuth`) receive `claims: Self::Claims` via `Extension<Self::Claims>`
-- Public routes don't require claims
+- Extractor order: `State` → `Extension` → `Path` → `Json`
 - `create_router<S, M>(service: S, middleware: M)` accepts middleware function
 - Middleware wraps protected routes: `middleware(protected)`
 - Router merges public/protected, applies `.with_state(service)` once at end
 
 ### Test Pattern
+
 ```typescript
 import { emit } from "./test-host.js";
 const results = await emit(`model User { name: string; }`);
@@ -136,15 +148,18 @@ strictEqual(output.includes("pub struct User"), true);
 ## Dependencies
 
 ### Peer (Required)
+
 - `@typespec/compiler` >=1.0.0
 - `@typespec/emitter-framework` ^0.17.0
 
 ### Dev
+
 - `typescript` ^5.3.3
 - `eslint` ^9.15.0
 - `prettier` ^3.3.3
 
 ### Generated Rust (example/output-rust/Cargo.toml)
+
 ```toml
 serde = { version = "1.0", features = ["derive"] }
 thiserror = "2.0"
@@ -161,6 +176,7 @@ tokio = { version = "1.50", features = ["full"] }
 ## Configuration Files
 
 ### tspconfig.yaml
+
 ```yaml
 emit:
   - "@typespec/openapi3"
@@ -171,6 +187,7 @@ options:
 ```
 
 ### tsconfig.json
+
 - Target: ES2022
 - Module: NodeNext
 - Strict: true
@@ -194,9 +211,67 @@ options:
 
 ## Recent Changes
 
+### 2026-03-27: v0.4.0 - Individual Parameters Instead of Request Structs
+
+**Breaking Changes**:
+
+- Server trait methods now accept individual parameters instead of request structs
+  - `async fn subjects_create(&self, claims: Self::Claims, request: SubjectsCreateRequest)` → `async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody)`
+- Request structs (`SubjectsCreateRequest`, etc.) are no longer generated
+- Handler extractor order follows axum conventions: `State` → `Extension` → `Path` → `Json`
+
+**Benefits**:
+
+- Cleaner server trait API - no boilerplate request structs
+- Direct parameter access in handler implementations
+- Follows axum best practices for extractor ordering
+- Better IDE autocomplete for handler parameters
+
+**Example**:
+
+```typespec
+@post
+@route("/groups/{groupId}/subjects")
+op create(@path groupId: int64, @body body: CreateSubjectBody): Subject;
+```
+
+```rust
+// Server trait
+async fn subjects_create(&self, claims: Self::Claims, group_id: i64, body: CreateSubjectBody) -> Result<...>;
+
+// Handler
+Extension(claims): Extension<S::Claims>,
+Path(group_id): Path<i64>,
+Json(payload): Json<CreateSubjectBody>
+let result = service.subjects_create(claims, group_id, payload).await;
+```
+
+### 2026-03-27: v0.3.0 - Custom Attributes & Enum Derives
+
+**New Features**:
+
+- `@rustAttr` / `@rustAttrs` decorators for custom Rust attributes (models & enums)
+- `@rustDerive` / `@rustDerives` now work on enums (previously models only)
+- Attributes render after `#[derive(...)]` for proper Rust syntax
+
+**Example**:
+
+```typespec
+@rustDerive("sqlx::Type")
+@rustAttr("sqlx(type_name = \"study_status\")")
+enum StudyStatus { Starting, Paused }
+```
+
+```rust
+#[derive(..., sqlx::Type)]
+#[sqlx(type_name = "study_status")]
+pub enum StudyStatus { ... }
+```
+
 ### 2026-03-27: v0.2.0 - Server Trait Refactoring
 
 **Changes**:
+
 - `pub trait Server<Claims>` → `pub trait Server` with `type Claims` associated type
 - Removed generated `Claims` struct from `types.rs` (users define their own)
 - `create_router<S, M>(service: S, middleware: M)` now accepts middleware function
@@ -204,6 +279,7 @@ options:
 - Single `.with_state(service)` call at end of router creation
 
 **Benefits**:
+
 - Cleaner API - Claims type defined by user, not generated
 - Flexible middleware - any function `FnOnce(Router<S>) -> Router<S>`
 - No duplicate `.with_state(service.clone())` calls

package/README.md

@@ -18,7 +18,8 @@ A TypeSpec emitter that generates idiomatic Rust types and structs from TypeSpec
 - **Inheritance**: Supports model inheritance with `getAllProperties()`
 - **Error Models**: Generates `thiserror::Error` derive with `#[error(...)]` attributes
 - **Pattern Validation**: Supports `@pattern` decorators with `TryFrom<String>` validation
-- **Custom Derives**: Add arbitrary Rust derive macros via `@rustDerive` decorator
+- **Custom Derives**: Add arbitrary Rust derive macros via `@rustDerive` decorator (models & enums)
+- **Custom Attributes**: Add arbitrary Rust attributes via `@rustAttr` decorator (models & enums)
 - **Server Trait**: Generates axum server trait and router from HTTP operations
 
 ## Installation
@@ -178,6 +179,44 @@ pub struct GroupStatistics {
 }
 ```
 
+### Custom Attributes
+
+```typespec
+import "typespec-emitter";
+
+@rustAttr("sqlx(type_name = \"user\")")
+model User {
+  name: string;
+}
+
+@rustDerive("sqlx::Type")
+@rustAttr("sqlx(type_name = \"study_status\")")
+enum StudyStatus {
+  Starting,
+  Paused,
+}
+```
+
+Generates:
+
+```rust
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+#[sqlx(type_name = "user")]
+pub struct User {
+    #[serde(rename = "name")]
+    pub name: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, sqlx::Type)]
+#[sqlx(type_name = "study_status")]
+pub enum StudyStatus {
+    #[serde(rename = "Starting")]
+    Starting,
+    #[serde(rename = "Paused")]
+    Paused,
+}
+```
+
 ## Server Trait Generation
 
 The emitter can generate a complete axum server trait and router from TypeSpec HTTP operations.
@@ -209,9 +248,9 @@ namespace Groups {
 pub trait Server: Send + Sync {
     type Claims: Send + Sync + 'static;
 
-    async fn groups_list(&self, request: GroupsListRequest) -> Result<GroupsListResponse>;
-    async fn groups_create(&self, claims: Self::Claims, request: GroupsCreateRequest) -> Result<GroupsCreateResponse>;
-    async fn groups_get_by_id(&self, request: GroupsGetByIdRequest) -> Result<GroupsGetByIdResponse>;
+    async fn groups_list(&self) -> Result<GroupsListResponse>;
+    async fn groups_create(&self, claims: Self::Claims, body: CreateGroupBody) -> Result<GroupsCreateResponse>;
+    async fn groups_get_by_id(&self, id: i64) -> Result<GroupsGetByIdResponse>;
 }
 ```
 
@@ -231,10 +270,7 @@ pub struct MyServer {
 impl Server for MyServer {
     type Claims = Claims; // Your custom claims type
 
-    async fn groups_list(
-        &self,
-        _request: GroupsListRequest,
-    ) -> eyre::Result<GroupsListResponse> {
+    async fn groups_list(&self) -> eyre::Result<GroupsListResponse> {
         let groups = sqlx::query_as::<_, Group>("SELECT * FROM groups")
             .fetch_all(&self.state.db)
             .await?;
@@ -244,19 +280,29 @@ impl Server for MyServer {
     async fn groups_create(
         &self,
         claims: Self::Claims,
-        request: GroupsCreateRequest,
+        body: CreateGroupBody,
     ) -> eyre::Result<GroupsCreateResponse> {
-        // claims.sub contains the authenticated user ID
+        // Direct access to body fields
         let group = sqlx::query_as::<_, Group>(
             "INSERT INTO groups (name, owner_id) VALUES ($1, $2) RETURNING *"
         )
-        .bind(&request.body.name)
+        .bind(&body.name)
         .bind(&claims.sub)
         .fetch_one(&self.state.db)
         .await?;
         Ok(GroupsCreateResponse::Created(Json(group)))
     }
 
+    async fn groups_get_by_id(&self, id: i64) -> eyre::Result<GroupsGetByIdResponse> {
+        // Direct access to path parameter
+        let group = sqlx::query_as::<_, Group>("SELECT * FROM groups WHERE id = $1")
+            .bind(id)
+            .fetch_optional(&self.state.db)
+            .await?
+            .ok_or_else(|| GroupsGetByIdResponse::NotFound)?;
+        Ok(GroupsGetByIdResponse::Ok(Json(group)))
+    }
+
     // ... implement other methods
 }
 ```
@@ -337,8 +383,10 @@ Public routes do not receive claims and are not wrapped with auth middleware.
 | ---------------------------- | ----------------------------------------------------- |
 | `@error`                     | Adds `thiserror::Error` derive with error message     |
 | `@pattern("regex")`          | Generates `TryFrom<String>` with regex validation     |
-| `@rustDerive("...")`         | Adds a custom derive macro (e.g., `sqlx::FromRow`)    |
-| `@rustDerives("...", "...")` | Adds multiple custom derive macros                    |
+| `@rustDerive("...")`         | Adds a custom derive macro (models & enums)           |
+| `@rustDerives("...", "...")` | Adds multiple custom derive macros (models & enums)   |
+| `@rustAttr("...")`           | Adds a custom Rust attribute (models & enums)         |
+| `@rustAttrs("...", "...")`   | Adds multiple custom Rust attributes (models & enums) |
 | `@doc("...")`                | Generates `///` doc comments                          |
 | `@useAuth(AuthType)`         | Marks operation as protected, adds `Claims` parameter |
 

package/dist/src/emitter.d.ts

@@ -4,4 +4,6 @@ export interface RustEmitterOptions {
 }
 export declare function $rustDerive(context: DecoratorContext, target: Type, derive: string): void;
 export declare function $rustDerives(context: DecoratorContext, target: Type, ...derives: string[]): void;
+export declare function $rustAttr(context: DecoratorContext, target: Type, attr: string): void;
+export declare function $rustAttrs(context: DecoratorContext, target: Type, ...attrs: string[]): void;
 export declare function $onEmit(context: EmitContext<RustEmitterOptions>, _options?: RustEmitterOptions): Promise<void>;