TypeScript to Dart 3 Conversion Guide
Goal
Provide clear, idiomatic mappings from TypeScript syntax and patterns to modern Dart 3 equivalents. Every conversion should produce code that feels native to Dart — not a line-by-line transliteration.
Instructions
1. Type System Mapping
1.1 Primitive Types
TypeScript and Dart share similar primitives but with different names.
// TypeScript
let name: string = "Zack";
let age: number = 25;
let active: boolean = true;
let items: string[] = ["a", "b"];
let pair: [string, number] = ["age", 25];
// Dart 3
final name = 'Zack';
final age = 25;
final active = true;
final items = ['a', 'b'];
final pair = ('age', 25); // Record instead of Tuple
Key mappings:
| TypeScript | Dart |
|---|
string | String |
number | int / double / num |
boolean | bool |
any | dynamic (avoid when possible) |
unknown | Object? |
void | void |
null / undefined | null (Dart has no undefined) |
never | Never |
T[] / Array<T> | List<T> |
[A, B] (Tuple) | (A, B) (Record) |
Record<K, V> / { [key: string]: V } | Map<K, V> |
Set<T> | Set<T> |
Promise<T> | Future<T> |
Observable<T> | Stream<T> |
1.2 Union Types
Dart has no direct union type. Convert using sealed classes for complex cases, or Object + pattern matching for simple ones.
// TypeScript
type Result = Success | Failure;
type StringOrNum = string | number;
// Dart 3 — sealed class for ADTs
sealed class Result {}
class Success extends Result { final String data; Success(this.data); }
class Failure extends Result { final String error; Failure(this.error); }
// Simple union — use pattern matching
void process(Object value) {
switch (value) {
case String s: print('String: $s');
case int n: print('Int: $n');
}
}
1.3 Literal Types and Enums
// TypeScript
type Direction = "up" | "down" | "left" | "right";
enum Status { Active = "ACTIVE", Inactive = "INACTIVE" }
// Dart 3 — enhanced enum
enum Direction { up, down, left, right }
enum Status {
active('ACTIVE'),
inactive('INACTIVE');
final String value;
const Status(this.value);
}
2. Interface and Type Conversion
2.1 Interface → Class
Dart has no interface keyword. Every class implicitly defines an interface.
// TypeScript
interface User {
readonly id: string;
name: string;
email?: string;
greet(): string;
}
// Dart 3 — abstract interface class
abstract interface class User {
String get id;
String get name;
set name(String value);
String? get email;
String greet();
}
// Or as a concrete data class (more common)
class User {
final String id;
String name;
final String? email;
User({required this.id, required this.name, this.email});
String greet() => 'Hello, $name';
}
2.2 Type Alias → typedef / Record
// TypeScript
type Point = { x: number; y: number };
type Callback = (data: string) => void;
// Dart 3
typedef Point = ({double x, double y});
typedef Callback = void Function(String data);
2.3 Generic Constraints
// TypeScript
function merge<T extends object>(a: T, b: Partial<T>): T { ... }
// Dart 3
T merge<T extends Object>(T a, T b) { ... }
3. Class Features
3.1 Constructor Shorthand
Dart constructors are more concise than TypeScript's.
// TypeScript
class User {
readonly id: string;
name: string;
constructor(id: string, name: string) {
this.id = id;
this.name = name;
}
}
// Dart 3 — initializing formals
class User {
final String id;
String name;
User(this.id, this.name);
}
3.2 Access Modifiers
TypeScript uses private/protected/public. Dart uses _ prefix for library-private.
| TypeScript | Dart |
|---|
public | (default, no prefix) |
private | _ prefix |
protected | _ prefix (no true protected) |
readonly | final |
static | static |
abstract | abstract |
3.3 Inheritance Patterns
// TypeScript
abstract class Shape {
abstract area(): number;
}
class Circle extends Shape {
constructor(private radius: number) { super(); }
area(): number { return Math.PI * this.radius ** 2; }
}
// Dart 3
abstract class Shape {
double area();
}
class Circle extends Shape {
final double radius;
Circle(this.radius);
@override
double area() => pi * radius * radius; // import 'dart:math';
}
4. Functions and Async
4.1 Function Syntax
// TypeScript
const greet = (name: string, age?: number): string => {
return age != null ? `${name} is ${age}` : name;
};
// Dart 3
String greet(String name, [int? age]) =>
age != null ? '$name is $age' : name;
4.2 Named vs Positional Parameters
TypeScript object destructuring → Dart named parameters.
// TypeScript
function createUser({ name, age = 18 }: { name: string; age?: number }) { ... }
createUser({ name: "Zack" });
// Dart 3
void createUser({required String name, int age = 18}) { ... }
createUser(name: 'Zack');
4.3 Async / Await
Nearly identical, but Promise → Future, Promise.all → Future.wait.
// TypeScript
async function fetchUsers(): Promise<User[]> {
const res = await fetch("/api/users");
return res.json();
}
// Dart 3
Future<List<User>> fetchUsers() async {
final res = await http.get(Uri.parse('/api/users'));
return (jsonDecode(res.body) as List).map(User.fromJson).toList();
}
4.4 Stream (Observable equivalent)
// TypeScript (RxJS)
observable$.pipe(map(x => x * 2), filter(x => x > 5)).subscribe(console.log);
// Dart 3
stream.map((x) => x * 2).where((x) => x > 5).listen(print);
5. Null Safety
Both languages support strict null checking, with similar operators.
| TypeScript | Dart | Purpose |
|---|
x?.prop | x?.prop | Optional chaining |
x ?? y | x ?? y | Null coalescing |
x! | x! | Non-null assertion |
x?.prop ?? default | x?.prop ?? default | Chaining + fallback |
x ??= y | x ??= y | Null-aware assignment |
Key difference: Dart's null safety is sound — the compiler guarantees a non-nullable variable is never null at runtime. Prefer type promotion (if (x != null)) over the bang operator !.
6. Collections and Iteration
6.1 Array → List
// TypeScript
const nums = [1, 2, 3];
const doubled = nums.map(n => n * 2);
const evens = nums.filter(n => n % 2 === 0);
const sum = nums.reduce((a, b) => a + b, 0);
const hasNeg = nums.some(n => n < 0);
// Dart 3
final nums = [1, 2, 3];
final doubled = nums.map((n) => n * 2).toList();
final evens = nums.where((n) => n % 2 == 0).toList();
final sum = nums.fold(0, (a, b) => a + b);
final hasNeg = nums.any((n) => n < 0);
Method mapping:
| TypeScript | Dart |
|---|
.map() | .map().toList() |
.filter() | .where().toList() |
.reduce() | .fold() (with initial value) / .reduce() |
.some() | .any() |
.every() | .every() |
.find() | .firstWhere() |
.findIndex() | .indexWhere() |
.includes() | .contains() |
.flat() | .expand((e) => e).toList() |
.push() | .add() |
.splice() | .removeRange() / .insertAll() |
[...a, ...b] | [...a, ...b] |
6.2 Object → Map
// TypeScript
const config: Record<string, number> = { timeout: 30, retries: 3 };
Object.entries(config).forEach(([k, v]) => console.log(k, v));
// Dart 3
final config = <String, int>{'timeout': 30, 'retries': 3};
config.forEach((k, v) => print('$k $v'));
7. Pattern Matching (Dart 3 Exclusive Power)
Dart 3 pattern matching is more powerful than TypeScript's type narrowing. Lean into it during conversion.
// TypeScript — type narrowing
function describe(shape: Shape) {
if (shape instanceof Circle) {
return `Circle r=${shape.radius}`;
} else if (shape instanceof Rect) {
return `Rect ${shape.w}x${shape.h}`;
}
return "Unknown";
}
// Dart 3 — exhaustive switch expression
String describe(Shape shape) => switch (shape) {
Circle(:final radius) => 'Circle r=$radius',
Rect(:final w, :final h) => 'Rect ${w}x$h',
};
8. Module System
| TypeScript | Dart |
|---|
import { X } from './x' | import 'x.dart' (imports all public) |
import * as lib from './x' | import 'x.dart' as lib |
import { X as Y } from './x' | import 'x.dart' show X (rename not needed often) |
export { X } | Top-level public declarations are auto-exported |
export default X | No equivalent; just import the library |
import type { X } | Not needed; Dart imports are already type-aware |
9. Error Handling
// TypeScript
try {
await riskyOp();
} catch (e: unknown) {
if (e instanceof HttpError) { ... }
throw e;
}
// Dart 3
try {
await riskyOp();
} on HttpError catch (e) {
// handle
} catch (e, stackTrace) {
rethrow;
}
10. Common Patterns Quick Reference
| TypeScript Pattern | Dart 3 Equivalent |
|---|
JSON.stringify(obj) | jsonEncode(obj) |
JSON.parse(str) | jsonDecode(str) |
console.log(x) | print(x) / debugPrint(x) |
typeof x === 'string' | x is String |
x instanceof Foo | x is Foo |
setTimeout(fn, ms) | Future.delayed(Duration(milliseconds: ms), fn) |
setInterval(fn, ms) | Timer.periodic(Duration(milliseconds: ms), (_) => fn()) |
Date.now() | DateTime.now() |
Math.max(a, b) | max(a, b) (from dart:math) |
Object.keys(obj) | map.keys.toList() |
Array.from({length: n}, (_, i) => i) | List.generate(n, (i) => i) |
str.startsWith('x') | str.startsWith('x') |
str.split(',') | str.split(',') |
`Hello ${name}` | 'Hello $name' |
Constraints
- Always produce idiomatic Dart 3 — never write Java-style or TypeScript-style Dart.
- Prefer
final over var when the variable is not reassigned.
- Use Records for lightweight multi-value returns; avoid creating throwaway classes.
- Use
sealed classes for union type / ADT conversions — never fall back to raw Object + casting when the domain is bounded.
- Use
switch expressions with destructuring over if-else chains for type narrowing.
- Preserve the original code's intent and naming conventions, adapting to Dart's
lowerCamelCase / UpperCamelCase rules.
- Omit explicit type annotations where Dart's type inference handles it.