Files, JSON & HTTP (dart:io, dart:convert)

By the end of this lesson you will be able to read and write files the right way (sync vs async, streaming a huge file instead of loading it all into memory), turn JSON text into validated typed Dart objects and back, talk HTTP from complete first principles (what a request/response actually looks like as bytes, status codes, timeouts, retries, streaming), and wire all three together into one real pipeline: fetch JSON from a server, parse it, save it to disk, and read it back. Every claim on this page is executed for real, offline, in verify/d19.dart.

1. Files: reading, writing, streaming

The core file operations you'll use constantly:

• file.readAsString() — reads the whole file into memory as one String (async; returns a Future<String>).
• file.readAsLines() — reads the whole file and splits it into a List<String>, one entry per line.
• file.openRead() — returns a Stream<List<int>> of raw bytes as they arrive, without ever holding the entire file in memory at once — essential for huge files.
• file.writeAsString(text, {mode}) — writes text to the file, async.

Now the "big file" problem. Imagine a 2 GB log file: readAsString() would try to load all 2 GB into memory at once — often a crash, always wasteful if all you need is, say, a word count. openRead() instead streams the bytes in small chunks; piping that through .transform(utf8.decoder) (turns bytes into text) and .transform(const LineSplitter()) (splits text into lines) gives you a Stream<String> you can process one line at a time with await for, holding only ONE line in memory at any instant.

Bytes, UTF-8 and base64. A file (and a socket) is just a list of bytes (whole numbers 0–255). UTF-8 is the rule that turns text into bytes: ASCII letters take 1 byte, accented letters 2, symbols like € 3, emoji 4 — so a string's length (UTF-16 units) is not its byte size. Because a chunk boundary can fall in the middle of a character, always decode a stream with utf8.decoder, never chunk by chunk. base64 re-writes any bytes as safe printable text (3 bytes become 4 characters, so the length is 4·⌈n/3⌉); the URL-safe variant swaps + and / for - and _.

Writing has the same async-by-default shape, plus one extra knob: mode.

await file.writeAsString('a', mode: FileMode.write);   // create/OVERWRITE
await file.writeAsString('b', mode: FileMode.append);  // add to the end
await file.writeAsString('c');                          // mode defaults to FileMode.write!

Errors: a missing file, a permissions problem, or a full disk all throw a subtype of FileSystemException. Reading a file that doesn't exist specifically throws PathNotFoundException (a FileSystemException subtype) — catch that specific type when you want to react to "file not found" differently from other I/O errors.

try {
  await File('missing.txt').readAsString();
} on PathNotFoundException catch (e) {
  print('no such file: ${e.path}');
} on FileSystemException catch (e) {
  print('some other file system error: ${e.message}');
}

Input size → what's feasible: a file up to ≈ 10⁶ bytes (a few MB) → readAsString() / readAsLines() is fine (≈ 2 bytes of memory per character); 5·10⁷ bytes (50 MB) → stream it, because the whole text would cost ≈ 10⁸ bytes; 10¹⁰ bytes (10 GB) → reading it all is ≈ 100 s at 100 MB/s, so stream it or seek into it (the tail question). Use the async API everywhere on a UI isolate.

2. JSON: decode, encode, typed models

dart:convert's jsonDecode(text) turns a JSON string into plain Dart values: an object becomes Map<String, dynamic>, an array becomes List<dynamic>, and everything nests naturally — an object inside an array inside an object all decode the same way, recursively. jsonEncode(value) does the reverse: it turns Dart Map/List/String/num/bool/null values back into a JSON string.

A typed model class needs two things: a fromJson factory that validates and converts, and a toJson method that converts back. D11 taught map patterns (if (value case {...}) {...}) for destructuring — they're a perfect fit here: a single pattern both checks the JSON has the right shape/types AND pulls the values out, all in one step.

class Address {
  final String city;
  final String zip;
  Address({required this.city, required this.zip});

  factory Address.fromJson(Map<String, dynamic> json) {
    if (json case {'city': String city, 'zip': String zip}) {
      return Address(city: city, zip: zip);
    }
    throw FormatException('Invalid Address JSON: $json');
  }

  Map<String, dynamic> toJson() => {'city': city, 'zip': zip};
}

Person.fromJson nests Address.fromJson inside its own pattern, plus a manual check for the optional email field (patterns can't express "String or null" quite as neatly, so a plain if handles that one):

factory Person.fromJson(Map<String, dynamic> json) {
  if (json case {'name': String name, 'age': int age, 'address': Map<String, dynamic> addressJson}) {
    final email = json['email'];
    if (email != null && email is! String) {
      throw FormatException('Person.email must be a String or null, got ${email.runtimeType}');
    }
    return Person(name: name, age: age, address: Address.fromJson(addressJson), email: email as String?);
  }
  throw FormatException('Invalid Person JSON: $json');
}

For pretty, human-readable JSON (logging, config files, debugging), use JsonEncoder.withIndent instead of plain jsonEncode:

final pretty = const JsonEncoder.withIndent('  ').convert({'a': 1, 'b': [1, 2]});
// pretty ==
// {
//   "a": 1,
//   "b": [
//     1,
//     2
//   ]
// }

Input size → what's feasible: a document of ≈ 10⁶ nodes (a few MB) → jsonDecode costs roughly 10 ms per MB on a typical laptop (measure on your own device), fine on any isolate; 10⁸ bytes (100 MB) → ≈ 1 s of decoding plus ≈ 10⁹ bytes of tree, so decode in a background isolate (D15) or switch to JSON Lines and stream (section 3); depth up to 10⁴ is safe because the parser is iterative.

3. HTTP from zero

The status code is a 3-digit number telling you, at a glance, how the request went:

Dart's dart:io gives you both sides for free, no package needed: HttpServer.bind(address, port) starts listening for connections; HttpClient makes outgoing requests.

// SERVER
final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
server.listen((HttpRequest request) async {
  request.response.headers.contentType = ContentType.json;
  request.response.write(jsonEncode({'msg': 'hi'}));
  await request.response.close();          // you MUST close every response
});

// CLIENT
final client = HttpClient();
final request = await client.getUrl(Uri.parse('http://127.0.0.1:${server.port}/hello'));
final response = await request.close();
final body = await utf8.decoder.bind(response).join();
print(jsonDecode(body));                    // {msg: hi}
client.close();                             // you MUST close the client when done

Real networks are unreliable: a server can hang, a connection can drop. .timeout(Duration) on any Future makes it fail with a TimeoutException instead of waiting forever if it doesn't settle in time — critically, it must wrap the network call itself (request.close()), not something you already finished awaiting. Note that .timeout() only stops YOU from waiting; it does not cancel the request that is still in flight, which is why the panel below also closes the client with force: true.

try {
  final response = await request.close().timeout(Duration(milliseconds: 40));
} on TimeoutException {
  print('server took too long');
}

A single timeout just fails fast — production code usually also retries, ideally with a growing delay between attempts (exponential backoff) so a struggling server gets breathing room instead of an instant flood of retries.

A response body doesn't have to arrive all at once. If the server never sets an exact length (no Content-Length header), the connection uses HTTP/1.1's chunked transfer-encoding and the client sees response.contentLength == -1 ("unknown ahead of time — just keep reading the stream until it ends"). HttpClientResponse IS a Stream<List<int>>, so you can process it incrementally with await for instead of buffering the whole thing with .join() — exactly the same streaming idea as reading a big file in section 1, just over a socket instead of a disk.

Streaming a body one JSON value per line (a "JSON Lines" / .jsonl feed, common for large API exports and log pipelines) raises a new question: what stops a fast producer from piling up thousands of unprocessed records in memory while a slow consumer catches up? The answer is backpressure — and in Dart, await for gives it to you automatically.

Input size → what's feasible: ≈ 10² requests of 50 ms each → start them together with Future.wait on ONE HttpClient (one after another would cost 10² · 50 ms = 5 s, together ≈ 50 ms); 10⁴ or more → cap the number in flight (a pool of ~8–32) instead of opening 10⁴ sockets; a response ≥ 10⁸ bytes → stream it with await for, never join() it.

4. Processes & stdin/stdout

Process.run(command, arguments) (from dart:io) launches another program as a subprocess, waits for it to finish, and gives you back a ProcessResult with its exitCode, stdout, and stderr as strings — perfect for "run this one tool and grab its output" scripts (a linter, git, a compiler). If you instead need to react to a long-running subprocess's output as it streams in, Process.start returns a live handle whose stdout/stderr are Stream<List<int>>, the same streaming shape as everything else in this lesson.

final result = await Process.run('echo', ['hello from Process.run']);
print(result.exitCode);            // 0
print(result.stdout);              // "hello from Process.run\n"

This example runs echo as a real program, which exists on macOS and Linux; on Windows echo is a shell built-in, so you would pass runInShell: true or pick a real executable.

stdout (the global IOSink that print() itself writes to) exposes the same two methods any IOSink does — the exact ones you already used on a file's openWrite() sink in section 1: write(x), which writes x with no automatic newline, and writeln(x), which always adds exactly one. print(x) is essentially stdout.writeln(x) plus a little extra handling for very long strings.

stdout.write('loading');
stdout.write('.');
stdout.write('.');
stdout.write('.');
stdout.writeln();   // finally move to a new line
// prints: loading...

Input size → what's feasible: a command printing ≤ 10⁶ bytes → Process.run (it buffers all of stdout and stderr in memory) is fine; a long-running command or one printing ≥ 10⁸ bytes → Process.start and stream stdout; always read stderr as well, or the child can block on a full pipe.

5. Putting it together: fetch → parse → save → read back

Every idea in this lesson combines into one realistic pipeline: fetch a JSON array of users from a server, parse each one into a typed UserModel, save the whole collection to disk as pretty-printed JSON, then read the file back and reconstruct the exact same models — proving the round trip is lossless.

// 1) fetch
final request = await client.getUrl(Uri.parse('http://127.0.0.1:${server.port}/users'));
final response = await request.close();
final raw = jsonDecode(await utf8.decoder.bind(response).join()) as List<dynamic>;

// 2) parse into typed models
final users = raw.map((j) => UserModel.fromJson(j as Map<String, dynamic>)).toList();

// 3) save to a file, pretty-printed
final pretty = const JsonEncoder.withIndent('  ').convert(users.map((u) => u.toJson()).toList());
await file.writeAsString(pretty);

// 4) read it back and reconstruct the models
final reloadedRaw = jsonDecode(await file.readAsString()) as List<dynamic>;
final reloaded = reloadedRaw.map((j) => UserModel.fromJson(j as Map<String, dynamic>)).toList();

What can go wrong in that pipeline, and the exception type each failure raises:

Input size → what's feasible: n ≤ 10⁴ users (≈ 1 MB) → exactly this pipeline (fetch whole, parse whole, write whole) is fine; n = 10⁶ records (≈ 10⁸ bytes) → keep them as JSON Lines and stream one record at a time (O(1) memory, section 3); the one thing never to skip at any size is the single validated fromJson at the boundary.

Quiz

Interview questions

Cheat sheet