TypeSpec Emitter Framework v2 Documentation

Introduction
Motivation
Core Concepts
Key Differences from v1
Architecture
Getting Started
Advanced Usage
Advanced Patterns
API Reference
Known Implementations
Best Practices
Tips and Tricks
Resources and References
FAQs

Introduction

The TypeSpec Emitter Framework v2 represents a significant redesign of the original emitter framework, addressing limitations discovered during real-world usage. The framework provides a structured approach to converting TypeSpec definitions into various target formats, such as OpenAPI specifications, SDK code, or documentation.

This framework redesign aims to enhance developer experience, improve error handling, and provide more predictable type management for complex emitter scenarios.

Important

The Emitter Framework v2 is currently under active development. This documentation represents the current understanding of its design and features, which may evolve as development progresses.

Motivation

The development of Emitter Framework v2 was driven by several key motivations, uncovered through real-world experience with the original framework:

Real-World Challenges

As identified in PR #2799, the primary motivation came from challenges encountered in projects like:

OpenAPI3 Emitter: Complex specification generation exposed limitations in handling nested references and type management.
Pedanic Project: Advanced type transformation needs revealed edge cases that the original framework couldn't handle gracefully.

Technical Limitations in v1

The v1 framework suffered from several technical limitations:

Crash Vulnerability: Unhandled types or hooks could cause emitter crashes rather than producing clear error diagnostics.
State Management: Mutable state led to unpredictable behavior in complex emission scenarios.
Limited Type Discovery: Navigating complex type relationships was difficult and error-prone.
Tight Coupling: Emitters were tightly coupled to source files, making testing and composition challenging.

Design Goals for v2

The redesign focuses on these key goals:

Robustness: Prevent crashes and improve error handling.
Type Safety: Provide strongly-typed contexts and outputs.
Composability: Support inter-emitter dependencies and modular design.
Developer Experience: Offer better diagnostic tools and interfaces that guide correct implementation.

Core Concepts

Purpose of the Emitter Framework

The TypeSpec Emitter Framework v2 provides a structured way to:

Navigate complex type graphs defined in TypeSpec
Manage references between types (including circular references)
Handle type transformations consistently
Generate output in various formats (code, specifications, etc.)
Control the traversal order of TypeSpec types
Maintain context during the emission process

Key Components

The Emitter Framework v2 is built around these core components:

Context System: Typed, readonly context objects that provide access to program information and configuration
Type Emitters: Specialized handlers for different TypeSpec types
Output Management: Utilities for building and managing output (strings, objects, arrays)
Diagnostic Collection: Systems for gathering and reporting errors and warnings
Transport Name Policies: Utilities for managing naming conventions across emission targets

Key Differences from v1

The v2 framework introduces several significant improvements over the original design:

Comparison Chart

graph TD
    subgraph "Error Handling"
        A1[Limited crash prevention] --> A2[Better protection]
        B1[Basic type discovery] --> B2[Enhanced type discovery]
        C1[Immediate emission on errors] --> C2[Diagnostic collection without emission]
    end
    
    subgraph "Context Management"
        D1[Mutable context] --> D2[Typed, readonly context]
        E1[Limited output typing] --> E2[Per-type output typing]
        F1[Higher risk of state mutation] --> F2[Reduced state mutation risk]
    end
    
    subgraph "Architecture"
        G1[Source file dependencies] --> G2[Independent of source files]
        H1[Limited inter-emitter support] --> H2[Better inter-emitter dependencies]
        I1[Minimal implementation guidance] --> I2[Interfaces guide implementation]
    end

1. Error Handling

Feature	v1	v2
Crash Prevention	Limited prevention mechanisms	Enhanced protection against unhandled types/hooks
Type Discovery	Basic discovery capabilities	Advanced, comprehensive type discovery mechanisms
Error Processing	Immediate emission on errors	Ability to collect diagnostics without immediate emission
Recovery Options	Minimal error recovery	Graceful recovery with fallback options

2. Context and Type Management

Feature	v1	v2
Context Mutability	Mutable context	Typed, readonly context with controlled state changes
Output Typing	Limited output typing	Comprehensive per-type output typing
State Management	Higher risk of state mutation	Significantly reduced state mutation risks
Object Building	Complex object/array building	Simplified object and array building mechanisms
Context Isolation	Limited scope isolation	Enhanced context scoping with proper isolation

3. Framework Architecture

Feature	v1	v2
File Dependencies	Strong source file dependencies	Detached from requiring source files
Emitter Composition	Limited inter-emitter support	First-class support for inter-emitter dependencies
Implementation Guidance	Minimal implementation guidance	Strong interfaces to guide proper implementation
Output Handling	Manual output handling	Automatic output handling for noEmit scenarios
Testability	Difficult to test in isolation	Designed for testability and mocking

4. Additional Improvements

Feature	v1	v2
Source Tracing	Limited source tracing	Enhanced declaration source tracing
Duplicate Detection	Basic duplicate detection	Improved duplicate declaration detection
Reference Management	Limited reference ordering	Better reference order understanding and control
Testing Support	Limited testing capabilities	Comprehensive unit testing infrastructure
Performance	Limited caching options	Enhanced caching and performance optimizations
Metadata Support	Basic metadata	Rich, typed metadata association capabilities

Architecture

High-Level Overview

The Emitter Framework v2 follows a component-based architecture:

graph TD
    A[TypeSpec Program] --> B[Emitter Framework]
    B --> C[Context System]
    B --> D[Type Emitters]
    B --> E[Output Management]
    B --> F[Diagnostics]
    C --> G[Name Policy]
    C --> H[State Management]
    D --> I[Model Emitter]
    D --> J[Enum Emitter]
    D --> K[Operation Emitter]
    E --> L[Generated Code/Specs]
    F --> M[Warnings]
    F --> N[Errors]

Context System

The v2 Context System introduces immutable, typed contexts that provide:

classDiagram
    class EmitterContext {
        +readonly program: Program
        +readonly options: Options
        +withScope(name, fn): T
        +setState(key, value): void
        +getState(key): T|undefined
        +hasEmittedType(type): boolean
        +registerEmittingType(type): void
        +setMetadata(type, metadata): void
        +reportDiagnostic(diagnostic): void
    }
    
    class ScopedContext {
        +readonly parent: EmitterContext
        +readonly scopeName: string
        +setState(key, value): void
        +getState(key): T|undefined
    }
    
    EmitterContext <-- ScopedContext

The Context System provides:

Access to the TypeSpec program
Configuration settings
Output management utilities
Diagnostic collection
Named context scopes for better organization

Name Policy System

The name policy system helps manage naming conventions across different targets:

classDiagram
    class TransformNamePolicy {
        +getTransportName(type): string
        +getApplicationName(type): string
    }
    
    class HasName~T~ {
        +name: string | symbol
    }
    
    TransformNamePolicy ..> HasName

The name policy system enables:

Consistent naming conventions (e.g., camelCase, PascalCase)
Name conflict resolution
Special character handling
Reserved word detection and mitigation

Type Emitters

Type Emitters are specialized handlers for converting TypeSpec types to target format representations:

classDiagram
    class TypeEmitter~TOutput~ {
        +emitModel(context, model, name): TOutput
        +emitEnum(context, enum_, name): TOutput
        +emitOperation(context, operation, name): TOutput
        +emitScalar(context, scalar, name): TOutput
        +emitUnion(context, union, name): TOutput
        +emitTypeReference(context, type): TOutput
        +emitProgram(context): Promise~EmitterResult~
        +createEmptyOutput(): TOutput
        +combineOutputs(outputs): TOutput
    }

    class ModelEmitter~TOutput~ {
        +emitModel(context, model, name): TOutput
        +emitProperties(context, model): TOutput[]
    }
    
    class EnumEmitter~TOutput~ {
        +emitEnum(context, enum_, name): TOutput
        +emitMembers(context, enum_): TOutput[]
    }

    TypeEmitter <|-- ModelEmitter
    TypeEmitter <|-- EnumEmitter

Each emitter can be customized with specific transformation logic while maintaining a consistent interface.

Output Management

The Output Management system provides utilities for different output formats:

graph TD
    A[Output Management] --> B[String Output]
    A --> C[Object Output]
    A --> D[Array Output]
    B --> E[Code Generation]
    C --> F[JSON/YAML Specs]
    D --> G[Collections]
    A --> H[Metadata Association]

Getting Started

Installation

To use the Emitter Framework v2 in your TypeSpec project:

npm install @typespec/emitter-framework

Basic Emitter Structure

Here's a simplified example of a v2 emitter:

import { createTypeSpecLibrary } from "@typespec/compiler";
import { EmitterContext, TypeEmitter, writeOutput } from "@typespec/emitter-framework";

// Define your emitter options
export interface MyEmitterOptions {
  outputFile: string;
}

// Create your type emitter
class MyTypeEmitter extends TypeEmitter<string> {
  // Handle model types
  emitModel(context, model, name) {
    // Implementation for model emission
    return `interface ${name} { /* properties */ }`;
  }
  
  // Handle other type kinds...
}

// Create your library
export const $lib = createTypeSpecLibrary({
  name: "my-emitter",
  diagnostics: {
    // Your diagnostic definitions
  },
});

// Define your emit handler
export async function $onEmit(context: EmitterContext<MyEmitterOptions>) {
  const { program } = context;
  
  const emitter = new TypeEmitter(program, {
    // Configuration
  });
  
  const result = await emitter.emit();
  
  await writeOutput(result, context.options.outputFile || "output.ts");
}

Component Workflow

sequenceDiagram
    participant User
    participant TypeSpecCompiler as TypeSpec Compiler
    participant EmitterPlugin as Emitter Plugin
    participant TypeEmitter as Type Emitter
    participant OutputSystem as Output System
    
    User->>TypeSpecCompiler: Run tsp compile
    TypeSpecCompiler->>EmitterPlugin: Invoke $onEmit
    EmitterPlugin->>TypeEmitter: Create and configure
    EmitterPlugin->>TypeEmitter: emit()
    
    loop For each type
        TypeEmitter->>TypeEmitter: emitType(type)
        alt if Model
            TypeEmitter->>TypeEmitter: emitModel(model)
        else if Enum
            TypeEmitter->>TypeEmitter: emitEnum(enum)
        else if Operation
            TypeEmitter->>TypeEmitter: emitOperation(operation)
        end
    end
    
    TypeEmitter->>EmitterPlugin: Return result
    EmitterPlugin->>OutputSystem: writeOutput(result)
    OutputSystem->>User: Generated files

Advanced Usage

Type-Specific Emission

Handle different TypeSpec constructs with specialized emitters:

// For models/interfaces
emitModel(context, model, name) {
  const properties = model.properties.map(/* ... */);
  return `interface ${name} {\n${properties.join("\n")}\n}`;
}

// For enums
emitEnum(context, enum_, name) {
  const values = enum_.members.map(/* ... */);
  return `enum ${name} {\n${values.join(",\n")}\n}`;
}

// For operations
emitOperation(context, operation, name) {
  // Generate function/method definition
}

Managing References

Handle circular references and type dependencies:

emitModel(context, model, name) {
  // Check if this model has been processed before
  if (context.hasEmittedType(model)) {
    // Return reference instead of full definition
    return context.getEmittedTypeReference(model);
  }
  
  // Register that we're processing this model
  context.registerEmittingType(model);
  
  // Process model properties
  const properties = [];
  for (const prop of model.properties.values()) {
    const propType = this.emitTypeReference(context, prop.type);
    properties.push(`${prop.name}: ${propType};`);
  }
  
  // Complete model emission
  const result = `interface ${name} {\n  ${properties.join("\n  ")}\n}`;
  
  // Register completed model
  context.registerEmittedType(model, result);
  
  return result;
}

Circular Reference Management

graph TD
    A[Begin Emit] --> B{Already Emitted?}
    B -- Yes --> C[Return Reference]
    B -- No --> D[Mark as Emitting]
    D --> E[Process Type]
    E --> F[Register as Emitted]
    F --> G[Return Result]

    subgraph "Circular Reference Handling"
        H[Type A] -->|references| I[Type B]
        I -->|references| H
        H -->|during emission| J[Emit A]
        J -->|calls| K[Emit B]
        K -->|calls| L[Emit A]
        L -->|already emitting| M[Return Reference to A]
    end

Diagnostics

Report issues during emission:

if (!isValidName(name)) {
  context.reportDiagnostic({
    code: "invalid-name",
    target: model,
    message: `Invalid name: ${name}`,
  });
  return "/* Invalid name */";
}

Advanced Patterns

Context Scoping

The v2 framework supports nested context scopes for more granular control:

function emitComplexModel(context, model, name) {
  // Create a new scope for this model emission
  return context.withScope(`model:${name}`, scopedContext => {
    // Operations within this scope have access to scope-specific state
    scopedContext.setState("currentModel", model);
    
    // Process model contents
    const properties = processProperties(scopedContext, model);
    const methods = processMethods(scopedContext, model);
    
    // Combine results
    return buildModelOutput(scopedContext, name, properties, methods);
  });
}

Context Scope Relationship

graph TD
    A[Root Context] --> B[Model Scope]
    A --> C[Enum Scope]
    B --> D[Property Scope]
    B --> E[Method Scope]
    
    subgraph "State Isolation"
        F[Model A State]
        G[Model B State]
    end

Decorators Influence on Emission

Handle TypeSpec decorators to customize output:

function emitModel(context, model, name) {
  // Check for decorators that might influence emission
  const formatDecorator = context.program.getDecoratorOnType(model, "format");
  const visibility = context.program.getDecoratorOnType(model, "visibility");
  
  // Adjust output based on decorators
  let modifiers = "";
  if (visibility?.args[0]?.value === "internal") {
    modifiers = "internal ";
  }
  
  // Generate model with appropriate formats
  const result = `${modifiers}interface ${name} { /* ... */ }`;
  
  if (formatDecorator) {
    // Apply additional formatting based on decorator arguments
  }
  
  return result;
}

Decorator Influence Flow

sequenceDiagram
    participant TypeSpec as TypeSpec Source
    participant Compiler as TypeSpec Compiler
    participant Emitter as Emitter
    participant Output as Generated Output
    
    TypeSpec->>Compiler: @format @visibility decorators
    Compiler->>Emitter: Decorated types
    Emitter->>Emitter: Check for decorators
    Emitter->>Emitter: Adjust output based on decorators
    Emitter->>Output: Modified output

Metadata-Driven Emission

Associate metadata with emitted types for post-processing:

function emitModel(context, model, name) {
  // Generate the model output
  const modelOutput = `interface ${name} { /* ... */ }`;
  
  // Associate metadata with this output
  context.setMetadata(model, {
    name,
    isPublic: !hasInternalVisibility(model),
    dependencies: getDependencies(model),
    sourcePath: context.program.sourceFile(model).path,
  });
  
  return modelOutput;
}

// Later in the emission process:
function finalizeOutput(context) {
  // Collect all emitted models with their metadata
  const allModels = context.getEmittedTypes().filter(t => t.kind === "Model");
  
  // Generate additional files like indices or documentation based on metadata
  const indexContent = generateIndex(
    allModels.map(model => context.getMetadata(model))
  );
  
  // Write the index file
  context.writeOutput("index.ts", indexContent);
}

Custom Traversal Strategies

Define custom traversal order for type emission:

class DependencyOrderEmitter extends TypeEmitter<string> {
  async emitProgram(context) {
    // Analyze the dependency graph
    const graph = buildDependencyGraph(context.program);
    
    // Sort types in dependency order (least dependent first)
    const sortedTypes = toposort(graph);
    
    // Emit types in the calculated order
    for (const type of sortedTypes) {
      await this.emitType(context, type);
    }
    
    // Return the final result
    return context.getResult();
  }
}

Dependency Order Emission

graph TD
    A[Build Dependency Graph] --> B[Sort Types Topologically]
    B --> C[Emit in Dependency Order]
    
    subgraph "Example Dependency Graph"
        D[StringLiteral] --> E[ModelProperty]
        F[NumberLiteral] --> E
        E --> G[Model]
        E --> H[Operation]
    end

Composing Multiple Emitters

Use multiple specialized emitters together:

async function $onEmit(context) {
  // Create specialized emitters
  const modelEmitter = new ModelEmitter(context);
  const operationEmitter = new OperationEmitter(context);
  const documentationEmitter = new DocumentationEmitter(context);
  
  // Emit different aspects of the program
  const models = await modelEmitter.emit();
  const operations = await operationEmitter.emit();
  
  // Use outputs from earlier emissions as input to later ones
  const docs = await documentationEmitter.emit({
    models,
    operations,
  });
  
  // Write results to files
  await writeOutputs(context, {
    models,
    operations,
    docs,
  });
}

Multi-Emitter Composition

sequenceDiagram
    participant Coordinator as Coordinator Emitter
    participant ModelEmitter as Model Emitter
    participant OpEmitter as Operation Emitter
    participant DocEmitter as Documentation Emitter
    
    Coordinator->>ModelEmitter: emit()
    ModelEmitter-->>Coordinator: models
    Coordinator->>OpEmitter: emit()
    OpEmitter-->>Coordinator: operations
    Coordinator->>DocEmitter: emit(models, operations)
    DocEmitter-->>Coordinator: documentation
    Coordinator->>Coordinator: Write outputs to files

API Reference

EmitterContext

The central context object for emission operations:

interface EmitterContext<TOptions = EmitterOptions> {
  // Access to TypeSpec program
  readonly program: Program;
  
  // Configuration options
  readonly options: TOptions;
  
  // Output directory
  readonly outputDir: string;
  
  // Scope management
  withScope<T>(name: string, fn: (scopedContext: ScopedContext) => T): T;
  
  // State management
  setState<T>(key: string, value: T): void;
  getState<T>(key: string): T | undefined;
  
  // Type tracking
  hasEmittedType(type: Type): boolean;
  registerEmittingType(type: Type): void;
  registerEmittedType(type: Type, result: any): void;
  getEmittedTypeReference(type: Type): any;
  
  // Metadata
  setMetadata(type: Type, metadata: any): void;
  getMetadata<T>(type: Type): T;
  
  // Diagnostics
  reportDiagnostic(diagnostic: Diagnostic): void;
  
  // Output management
  writeOutput(path: string, content: string): Promise<void>;
}

TypeEmitter

Base class for emitting TypeSpec types:

abstract class TypeEmitter<TOutput> {
  constructor(program: Program, options?: TypeEmitterOptions);
  
  // Main emission methods (to be implemented)
  abstract emitModel(context: EmitterContext, model: Model, name: string): TOutput;
  abstract emitEnum(context: EmitterContext, enum_: Enum, name: string): TOutput;
  abstract emitOperation(context: EmitterContext, operation: Operation, name: string): TOutput;
  abstract emitUnion(context: EmitterContext, union: Union, name: string): TOutput;
  abstract emitScalar(context: EmitterContext, scalar: Scalar, name: string): TOutput;
  
  // Helper methods
  emitTypeReference(context: EmitterContext, type: Type): TOutput;
  emitProgram(context: EmitterContext): Promise<EmitterResult<TOutput>>;
  
  // Type discovery
  getReferencedTypes(type: Type): Type[];
  
  // Result management
  createEmptyOutput(): TOutput;
  combineOutputs(outputs: TOutput[]): TOutput;
}

TransformNamePolicy

Controls naming conventions across different emission targets:

interface TransformNamePolicy {
  // Convert a TypeSpec name to target language name
  getTransportName<T extends HasName<Type>>(type: T): string;
  
  // Get application-friendly name 
  getApplicationName<T extends HasName<Type>>(type: T): string;
}

// Create a custom policy
function createTransformNamePolicy(options: {
  transportNamer: <T extends HasName<Type>>(type: T) => string;
  applicationNamer: <T extends HasName<Type>>(type: T) => string;
}): TransformNamePolicy;

TypeTransformer Components

The TypeSpec Emitter Framework v2 includes JSX-based TypeScript components for type transformations:

// Type transform declaration
export function TypeTransformDeclaration(props: TypeTransformProps) {
  // Generates a function for transforming between application and transport formats
}

// Model transform expression
export function ModelTransformExpression(props: ModelTransformExpressionProps) {
  // Creates object expressions for model transformations
}

// Transform reference
function TransformReference(props: TransformReferenceProps) {
  // Creates references to transform functions
}

// Type transform call
export function TypeTransformCall(props: TypeTransformCallProps) {
  // Calls the appropriate transform function for a type
}

Known Implementations

While the Emitter Framework v2 is still in active development, here are implementation examples that demonstrate its usage or are preparing to adopt it:

Current Implementations

HTTP Client JS Emitter: A fully-featured implementation that generates JavaScript/TypeScript HTTP clients from TypeSpec definitions.
- Package: @typespec/http-client-js
- Features:
  - Uses JSX for component-based code generation
  - Implements type transformations for JavaScript/TypeScript targets
  - Generates complete client libraries with proper TypeScript typings
  - Demonstrates integration with the emitter framework's context system
- Example Usage: tsp compile . --emit=@typespec/http-client-js

Related Implementations

Asset Emitter: A legacy emitter framework that will eventually be replaced by the Emitter Framework v2.
- Package: @typespec/asset-emitter
- Status: Legacy/transitional
- Features:
  - Handles circular references in output generation
  - Supports various emission patterns (class per file, namespace-based, etc.)
  - Includes helpers for TypeScript code emission
  - Shares similar concepts with Emitter Framework v2
- Note: While not using v2 directly, the Asset Emitter provides valuable patterns and concepts that influenced v2's design

Planned or In-Progress Implementations

OpenAPI3 Emitter: The TypeSpec OpenAPI3 emitter is one of the primary use cases driving the v2 design requirements.
- Package: @typespec/openapi3
- Features:
  - Handles complex reference management and specification generation
  - Manages circular references in OpenAPI specifications
  - Preserves TypeSpec decorators as OpenAPI extensions
Pedanic: A TypeSpec project that has helped identify limitations in the v1 framework.
- Has complex type transformation needs that influenced the v2 design
- Demonstrates advanced usage patterns for type handling
TypeScript Emitter: The internal TypeScript code generation capabilities in TypeSpec will likely adopt the v2 framework.
- TypeScript Components
- Showcases organization of language-specific emission components
- Provides reusable TypeScript emission primitives
REST to TypeScript: Targeted generation of TypeSpec REST API definitions to TypeScript clients.
- Demonstrates how to handle operation parameters and response types
- Shows parameter transformation and client-side validation generation

Note that as v2 is still evolving, most existing implementations are still using v1 or are in the process of migrating. The HTTP Client JS emitter serves as a good reference implementation for those looking to adopt the new framework design.

Best Practices

Emitter Structure

Separate Concerns: Keep type emission logic separate from output writing logic
Use Typed Contexts: Leverage TypeScript's type system for better development experience
Handle All Cases: Implement handlers for all relevant TypeSpec constructs
Modular Design: Split complex emitters into focused components
Use Context Scoping: Create appropriate context scopes for different emission phases
Favor Composition: Build complex emitters from simpler components

Error Handling

Report, Don't Throw: Use the diagnostic system instead of throwing exceptions
Validate Inputs: Check inputs before processing
Provide Clear Messages: Ensure diagnostic messages are helpful
Location Information: Include source location details in diagnostics
Support Recovery: Design emitters to continue after encountering problems
Progressive Enhancement: Emit valid partial output even when some types fail

Error Recovery Process

flowchart TD
    A[Begin Type Emission] --> B{Valid Type?}
    B -- No --> C[Report Diagnostic]
    C --> D[Return Fallback Output]
    D --> G[Continue Processing]
    B -- Yes --> E[Process Type]
    E --> F{Processing Error?}
    F -- Yes --> C
    F -- No --> G
    G --> H[Return Output]

Performance

Cache Results: Avoid re-processing types that have been processed
Use References: Generate references to types rather than duplicating output
Optimize Traversal: Consider traversal order to minimize redundant operations
Lazy Processing: Only process types that are actually needed
Batch Operations: Group similar operations for efficiency
Memory Management: Release intermediate results when no longer needed

Tips and Tricks

Debugging Emission

Use Context Metadata

// Add debug information during emission
context.setMetadata(type, { debugInfo: "Processing complex model" });

// Retrieve it later
const debugInfo = context.getMetadata(type)?.debugInfo;

Create Debug Outputs

if (context.options.debug) {
  // Write intermediate outputs for debugging
  await context.writeOutput(
    `debug/${name}.json`,
    JSON.stringify(intermediateResult, null, 2)
  );
}

Implement toString for Custom Objects

class MyCustomOutput {
  constructor(private data: any) {}
  
  // Helps with debugging
  toString() {
    return `CustomOutput(${JSON.stringify(this.data)})`;
  }
}

Handling Complex Types

Decompose Complex Models

function emitComplexModel(context, model) {
  // Break down complex models into smaller, manageable pieces
  const baseEmission = emitBaseStructure(context, model);
  const propertyEmissions = emitProperties(context, model);
  const methodEmissions = emitMethods(context, model);
  
  // Compose the final result
  return combineResults(baseEmission, propertyEmissions, methodEmissions);
}

Use Template Helpers

// Create reusable template functions
function modelTemplate(name: string, properties: string[]) {
  return `
    interface ${name} {
      ${properties.join("\n  ")}
    }
  `;
}

Handle Type Aliases and Specializations

function emitTypeReference(context, type) {
  // Check if this is an alias to another type
  const aliasedType = getAliasTarget(type);
  if (aliasedType) {
    return emitTypeReference(context, aliasedType);
  }
  
  // Handle specialized types
  if (isSpecializedType(type)) {
    return handleSpecializedType(context, type);
  }
  
  // Regular type handling
  return emitRegularType(context, type);
}

Testing Emitters

Create Test Harnesses

import { TestEmitterHost } from "@typespec/emitter-framework/testing";

function testEmission(typespec: string, options = {}) {
  const host = new TestEmitterHost();
  const program = host.compileString(typespec);
  const emitter = new MyEmitter(program, options);
  
  return emitter.emit();
}

Snapshot Testing

it("should emit a model correctly", async () => {
  const result = await testEmission(`
    model Person {
      name: string;
      age: int32;
    }
  `);
  
  expect(result).toMatchSnapshot();
});

Test Edge Cases

it("should handle circular references", async () => {
  const result = await testEmission(`
    model Person {
      name: string;
      friends: Person[];
    }
  `);
  
  expect(result).toContain("Person[]");
});

JSX-based Components

The Emitter Framework supports JSX-based components for more declarative code generation:

// Array expression component
export function ArrayExpression({ elementType }: ArrayExpressionProps) {
  return ay.code`Array<${(<TypeExpression type={elementType} />)}>`;
}

// Enum declaration component
export function EnumDeclaration({ type }: EnumDeclarationProps) {
  return (
    <ts.EnumDeclaration
      name={namePolicy.getName(type.name, "enum")}
      refkey={refkey(type)}
      members={Array.from(type.members.entries()).map(([name, member]) => ({
        name,
        value: member.value,
        refkey: refkey(member),
      }))}
    />
  );
}

Resources and References

Official Documentation

TypeSpec Repository
- GitHub Repository
- Primary source for TypeSpec development and documentation
Emitter Framework Documentation
- Emitter Framework Documentation
- Current documentation on the emitter framework concepts
TypeSpec Website
- TypeSpec Documentation
- Official documentation site for TypeSpec

Key Pull Requests and Issues

Emitter Framework v2 WIP PR
- PR #2799
- Original work-in-progress PR for the v2 framework
Merge EFv2 to Main
- Integration efforts of the framework to main branch
Compiler/Emitter Consistency Issues
- Issues highlighting the need for improved emitter behavior

Related Packages

@typespec/compiler
- Core TypeSpec compiler package
@typespec/openapi3
- OpenAPI3 emitter using TypeSpec
@typespec/rest
- REST protocol bindings for TypeSpec
@typespec/http
- HTTP protocol definitions for TypeSpec

Example Implementations

OpenAPI3 Emitter
- Source Code
- Example of a complex emitter
TypeScript Components
- Source Code
- TypeScript-specific emission components

Community Resources

TypeSpec GitHub Discussions
- Discussions
- Community questions and answers about TypeSpec
Microsoft Developer Blog
- Occasional posts about TypeSpec development and features

FAQs

Q: When will Emitter Framework v2 be fully released?

A: The Emitter Framework v2 is under active development. For the most current status, check the TypeSpec GitHub repository.

Q: Can I use v1 and v2 together?

A: While it may be possible during migration periods, it's recommended to standardize on one version to avoid confusion and potential conflicts.

Q: What's the most important improvement in v2?

A: The typed, readonly context system and improved error handling are considered the most significant improvements, addressing pain points reported by users of v1.

Q: How do I migrate from v1 to v2?

A: A comprehensive migration guide will be provided when v2 is officially released. Key changes will involve adapting to the new context system and updating type emitter implementations.

Q: Is v2 backward compatible with v1?

A: No, the v2 framework has significant architectural differences that require adapting existing emitters. The changes are intentional to address fundamental limitations in the v1 design.

Q: Will existing TypeSpec code need to change to work with emitters using v2?

A: No, the changes are primarily in the emitter implementation, not in the TypeSpec language itself. Existing TypeSpec definitions should continue to work with v2-based emitters.

Q: How can I contribute to the development of v2?

A: You can contribute by testing early versions, providing feedback on GitHub issues, and submitting pull requests for bug fixes or enhancements.

This documentation is based on the current understanding of the Emitter Framework v2 design and implementation. As development progresses, certain details may change.

btiernay/EMITTER_FRAMEWORK_V2.md