arkts-static-spec

ArkTS Static Language Specification

Complete reference for the ArkTS programming language, including official specification and TypeScript migration guide.

⚠️ Usage Principles (Important)

When using this skill to answer questions,you must strictly followthe following principles:

Answer strictly according to the content of the skill documentation
- All answers must be based on the documentation content in the spec/ and cookbook/ directories
- Do not add assumptions or inferences beyond the documentation
Clearly mark content not explained in the documentation
- If a feature is not explicitly explained in the skill documentation, you must mark it in the answer:
  - "⚠️ Not explicitly explained in the skill documentation; the user must confirm it themselves"
- Do not make assumptions based on features of TypeScript or other languages

Treat ArkTS as an independent static language
- ArkTS is an independent static language,not a superset of TypeScript
- Do not assume that TypeScript features are all supported in ArkTS
- Use the official ArkTS specification as the standard, not TypeScript syntax

Directory Structure

This skill is divided into two main parts:

arkts-static-spec/
├── spec/              # ArkTS 语言规范
│   ├── types.md       # 类型系统
│   ├── classes.md     # 类声明
│   ├── expressions.md # 表达式和运算符
│   ├── statements.md  # 语句和控制流
│   ├── generics.md    # 泛型
│   ├── annotations.md # 注解和装饰器
│   ├── modules.md     # 模块系统
│   ├── lexical.md     # 词法结构
│   ├── names.md       # 声明和作用域
│   ├── conversions.md # 类型转换
│   ├── interfaces.md  # 接口
│   ├── enums.md       # 枚举
│   ├── errors.md      # 错误处理
│   ├── concurrency.md # 并发和异步
│   ├── stdlib.md      # 标准库
│   └── experimental.md# 实验性特性
│
└── cookbook/          # TypeScript 迁移指南
    ├── index.md       # 迁移指南总览
    ├── recipes.md     # 详细迁移食谱（144+ 项）
    └── compatibility.md # TypeScript vs ArkTS 兼容性详情

Part One: ArkTS Language Specification (spec/)

Official ArkTS language specification reference, organized by topic.

Core Specification Files

File	Content	Applicable Scenarios
types.md	Type system, predefined types	Querying types, type inference, default values
classes.md	Class declarations, access modifiers, inheritance	Defining classes, implementing interfaces, inheritance
expressions.md	Operators, precedence	Expression evaluation, operator usage
statements.md	Control flow, loops, try-catch	if/else, for, while, exception handling
generics.md	Generic types and functions	Writing generic code, type constraints
annotations.md	Decorators and metadata	Using @Decorator
modules.md	Import/export, namespaces	Module organization, import and export
lexical.md	Identifiers, keywords, literals	Lexical analysis, syntax rules
names.md	Declarations, scope, visibility	Variable scope, naming conflicts
conversions.md	Type conversion and context	Type conversion rules
interfaces.md	Interface declarations and implementations	Defining interfaces, implementing contracts
enums.md	Enum types	Using enums
errors.md	Error handling and try statements	Exception handling, throw statements
concurrency.md	Async/await、TaskPool	Asynchronous programming, concurrency
stdlib.md	Standard library API	Built-in objects and functions
experimental.md	Experimental features	FixedArray, char, function overloading, etc.

Part Two: TypeScript Migration Guide (cookbook/)

A complete guide for migrating from TypeScript to ArkTS, including 144+ detailed migration recipes and compatibility notes.

Migration Guide Files

File	Content	Applicable Scenarios
index.md	Migration guide overview	Understanding migration reasons, design principles, quick start
recipes.md	144+ detailed migration recipes	How specific syntax is converted, common problem solutions
compatibility.md	TypeScript vs ArkTS compatibility details	Learn about behavioral differences, numeric semantics, array assignment, etc.

Quick Start

ArkTS Type Annotations

let num: number = 42
const str: string = "hello"
let arr: number[] = [1, 2, 3]

ArkTS Class Declarations

class Person {
  private name: string
  public age: number

  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }

  public introduce(): string {
    return `I'm ${this.name}, ${this.age} years old`
  }
}

Generic Functions

function identity<T>(value: T): T {
  return value
}

let num = identity<number>(42)
let str = identity<string>("hello")

Async Functions

async function fetchData(): Promise<string> {
  const response = await fetch("https://example.com")
  return await response.text()
}

Type System Quick Reference

Predefined Types

Category	Type	Description
Numeric	`byte`, `short`, `int`, `long`, `float`, `double`, `number`, `bigint`	Integers and floating-point numbers
Boolean	`boolean`	true/false
Character	`char`	Experimental, use `c'A'` syntax
String	`string`	Text data
Special	`void`, `null`, `undefined`, `never`	Special purpose
Object	`Object`, `object`	Object type

Note：any and unknown are not supported in ArkTS; explicit types must be used.

Type Operators

Union type:T | U
Intersection type:T & U
Array type:T[] or Array<T>
Readonly array:readonly T[]

TypeScript Migration Quick Reference

Common conversions

TypeScript	ArkTS	Description
`var x = 10`	`let x: number = 10`	Must use `let`, specify the type explicitly
`let x: any`	`let x: SpecificType`	Prohibit `any`, use concrete types
`let {a, b} = obj`	`let a = obj.a; let b = obj.b`	Object destructuring is not supported
`"prop" in obj`	`obj instanceof Class`	Not supported `in` operator
`import m = require("mod")`	`import * as m from "mod"`	Use ES6 import

Code retention rate

Fully supported(no modification needed): 90% - 97%
Partially supported(minor refactoring): about 2% - 8%
Not supported(refactoring needed): about 1%

Lookup Guide

Look up the ArkTS language specification

Select the corresponding specification file by topic:

Type-related questions: see spec/types.md、spec/conversions.md
Object-oriented features: see spec/classes.md、spec/interfaces.md、spec/enums.md
Syntax-related questions: see spec/lexical.md、spec/expressions.md、spec/statements.md
Generic programming: see spec/generics.md
Module system: see spec/modules.md
Concurrent programming: see spec/concurrency.md
Decorators and annotations: see spec/annotations.md
Standard library API: see spec/stdlib.md
Experimental features: see spec/experimental.md

Look up TypeScript migration questions

Migration overview and principles: see cookbook/index.md
How specific syntax is converted: see cookbook/recipes.md
Behavioral differences and compatibility: see cookbook/compatibility.md

Key differences between ArkTS vs TypeScript

1. Static type enforcement

Feature	TypeScript	ArkTS
Static typing	Optional	Mandatory
`any` type	Allowed	Prohibited
`unknown` type	Allowed	Prohibited
Type inference	Optional	Required

2. Fixed object layout

Feature	TypeScript	ArkTS
Add properties at runtime	Allowed (use `as any` to bypass)	Prohibited
Delete properties	Allowed (use `as any` to bypass)	Prohibited
Object layout	Mutable	Fixed

3. Null safety

Feature	TypeScript	ArkTS
`null` Assigning to non-null types	Prohibited in optional mode	Strictly prohibited
`undefined` As a value	Allowed	Strictly restricted

4. Numeric semantics

let n = 1
console.log(n / 2)

// TypeScript: 0.5（浮点除法）
// ArkTS: 0（整数除法）

Access modifiers

Modifier	Accessibility
`public`	Anywhere (default)
`private`	Within the class only
`protected`	Class and subclasses
`readonly`	Immutable after initialization
`static`	Class level, not instance level

Common design patterns

Singleton pattern

class Singleton {
  private static instance: Singleton
  private constructor() {}

  public static getInstance(): Singleton {
    if (!Singleton.instance) {
      Singleton.instance = new Singleton()
    }
    return Singleton.instance
  }
}

Factory pattern

interface Product {
  operation(): string
}

class ConcreteProductA implements Product {
  operation(): string {
    return "Product A"
  }
}

class Factory {
  static create(type: string): Product {
    if (type === "A") {
      return new ConcreteProductA()
    }
    throw new Error("Unknown product type")
  }
}

Why choose ArkTS?

Advantages

Program stability
- Strict type checking reduces runtime errors
- Compile-time type verification
- Fields must be initialized
Program performance
- Compiles to bytecode for faster execution
- Eliminates runtime type-checking overhead
- Optimized for mobile devices
Code readability
- Static typing makes code intent clear
- Fixed object layout with predictable behavior

Migration cost

Code retention rate: 90% - 97% (following best practices)
Main adjustments: Remove any, use let instead of var
Learning curve: Easy for TypeScript developers to get started

Control flow quick reference

if-else

if (condition) {
  // ...
} else {
  // ...
}

Loops

// while 循环
while (condition) {
  // ...
}

// for 循环
for (let i: int = 0; i < 10; i++) {
  // ...
}

// for-of 循环
for (const item of array) {
  // ...
}

Error handling

try {
  // 可能抛出错误的代码
} catch (e: Error) {
  // 处理错误
} finally {
  // 清理（总是执行）
}

Migration checklist

Priority 1: Must fix (ERROR level)

Replace all var with let
Remove all any / unknown types
Remove Symbol() API usage
Remove private # identifiers
Ensure type and namespace names are unique
Remove non-identifier property names
Remove call signature and construct signature types
Remove in operators
Remove object destructuring
Replace require with standard import
Remove export = syntax

Priority 2: Code improvement suggestions (WARNING level)

Check field initialization
Review object property access patterns
Ensure type safety

Complete reference

ArkTS language specification：spec/
TypeScript migration guide：cookbook/
Original specification document：D:\arkcompiler\runtime_core\static_core\plugins\ets\doc\spec\
Original Cookbook：D:\arkcompiler\runtime_core\static_core\plugins\ets\doc\cookbook\