TypeScript Type Notation Specification

Overview

TypeScript Type Notation (TTN) is a specification for expressing TypeScript type information in a consistent, portable format that can be used across documentation systems, IDEs, and development tools.

🎯 Precise

Captures the full expressiveness of TypeScript's type system

📝 Human-Readable

Easy to write and understand in documentation

🔧 Tool-Friendly

Parseable by external tools and IDEs

Basic Syntax

Primitive Types

string
number
boolean
null
undefined
void
never
unknown
any

Object Types

{ name: string; age: number }
{ readonly id: string; optional?: boolean }

Array and Tuple Types

string[]
Array<number>
[string, number]
[string, ...number[]]

Union and Intersection Types

string | number
{ a: string } & { b: number }

Examples

Function Types

(x: number, y: number) => number
<T>(items: T[]) => T | undefined
(callback: (error: Error | null, result?: string) => void) => void

Generic Types

Promise<string>
Map<string, number>
Record<string, unknown>
Partial<User>
Pick<User, 'id' | 'name'>

Complex Types

interface User {
  id: string;
  name: string;
  email?: string;
  roles: Role[];
}

type APIResponse<T> = {
  data: T;
  error: null;
} | {
  data: null;
  error: string;
}

Grammar

The complete EBNF grammar for TypeScript Type Notation:

Type ::= UnionType

UnionType ::= IntersectionType ('|' IntersectionType)*

IntersectionType ::= PrimaryType ('&' PrimaryType)*

PrimaryType ::= 
    | PrimitiveType
    | ObjectType  
    | ArrayType
    | TupleType
    | FunctionType
    | GenericType
    | ParenthesizedType
    | LiteralType

PrimitiveType ::= 
    | 'string' | 'number' | 'boolean' | 'null' 
    | 'undefined' | 'void' | 'never' | 'unknown' | 'any'

ObjectType ::= '{' ObjectMember* '}'

ObjectMember ::= 
    | PropertySignature
    | MethodSignature
    | IndexSignature

PropertySignature ::= 
    | 'readonly'? PropertyName '?'? ':' Type ';'?

ArrayType ::= PrimaryType '[]' | 'Array' '<' Type '>'

TupleType ::= '[' TupleElement* ']'

FunctionType ::= TypeParameters? '(' ParameterList? ')' '=>' Type