Spec files

Spec files define the contract between your TypeScript logic and the native platforms. They are the single source of truth for the Yolk Codegen tool.

Structure

A spec file is a standard TypeScript file containing one or more interface exports. By convention, interface names ending in Spec define Native Modules, and interfaces ending in State define the Application State.

// playground.spec.ts
 
/**
 * Defines the reactive state pushed from JS to Native.
 * Codegen will create a Swift Codable struct and Kotlin Data class.
 */
export interface PlaygroundState {
  count: number
  canIncrement: boolean
  canDecrement: boolean
  activity: string
}
 
/**
 * Defines the methods exposed by the native module.
 */
export interface PlaygroundSpec {
  increment(step: number): Promise<PlaygroundState>
  decrement(step: number): Promise<PlaygroundState>
  reset(): Promise<PlaygroundState>
  
  /**
   * Demonstrate zero-copy binary transfer.
   * Maps to Data in Swift and ArrayBuffer in TS.
   */
  processBuffer(buffer: ArrayBuffer): Promise<ArrayBuffer>
  
  /**
   * Standard subscription pattern for SSOT state.
   */
  subscribe(): Promise<void>
}

Type Mapping

Yolk's binary bridge supports a specific set of TypeScript types, which are automatically mapped to their high-performance native equivalents:

Why use spec files?

Spec files allow Yolk to enforce End-to-End Type Safety. Because the native code is generated from the same file as the JS proxy, it is impossible to call a method with the wrong arguments or expect a return type that doesn't exist.

If you change a field name in PlaygroundState, your Swift and Kotlin code will fail to compile until you update your UI bindings, preventing runtime crashes.