Architecture all 6 written

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123// ---------- DOMAIN ----------------------------------------------------------
// Knows nothing below it. No JSON, no http, no widgets, no Flutter import.

class Task {
  const Task({required this.id, required this.title, required this.done});
  final String id;
  final String title;
  final bool done;

  /// A business rule, and it lives here rather than in a screen or a client.
  Task complete() => Task(id: id, title: title, done: true);
}

/// The port. Declared by the domain, in the domain's own vocabulary.
abstract interface class TaskPort {
  Future<Task?> byId(String id);
  Future<void> save(Task task);
}

/// The use case: one job, and the only place the rules are decided.
class CompleteTask {
  const CompleteTask(this.tasks);
  final TaskPort tasks;

  Future<String> call(String id) async {
    final task = await tasks.byId(id);
    if (task == null) return 'no such task';
    if (task.done) return 'already done';
    await tasks.save(task.complete());
    return 'completed ${task.title}';
  }
}

// ---------- DATA -----------------------------------------------------------
// Knows the wire shape and the mapping. Depends on the domain above. The
// domain does not depend on this.

typedef Row = Map<String, Object?>;

class TaskApi {
  TaskApi(this.rows);
  final List<Row> rows;

  Future<Row?> get(String id) async {
    await Future<void>.delayed(Duration.zero);
    for (final row in rows) {
      if (row['task_id'] == id) return row;
    }
    return null;
  }

  Future<void> put(Row row) async {
    rows.removeWhere((r) => r['task_id'] == row['task_id']);
    rows.add(row);
  }
}

class TaskRepository implements TaskPort {
  TaskRepository(this._api);
  final TaskApi _api;

  /// The mapper IS the boundary. It is a real place in the code, and it is
  /// where the wire's spelling stops.
  Task _toDomain(Row row) => Task(
        id: row['task_id']! as String,
        title: row['task_title']! as String,
        done: row['is_done']! as bool,
      );

  Row _toWire(Task task) => {
        'task_id': task.id,
        'task_title': task.title,
        'is_done': task.done,
      };

  @override
  Future<Task?> byId(String id) async {
    final row = await _api.get(id);
    return row == null ? null : _toDomain(row);
  }

  @override
  Future<void> save(Task task) => _api.put(_toWire(task));
}

// ---------- PRESENTATION ---------------------------------------------------
// Talks to the use case. Formats for a screen. Never sees a Row.

class TaskViewModel {
  TaskViewModel(this._complete);
  final CompleteTask _complete;
  final messages = <String>[];

  Future<void> tapped(String id) async => messages.add(await _complete(id));
}

Future<void> main() async {
  final api = TaskApi([
    {'task_id': 't1', 'task_title': 'buy milk', 'is_done': false},
    {'task_id': 't2', 'task_title': 'call mum', 'is_done': true},
  ]);

  // Wiring, and this is the only place all three layers are named together.
  final screen = TaskViewModel(CompleteTask(TaskRepository(api)));

  await screen.tapped('t1');
  await screen.tapped('t1');
  await screen.tapped('t9');

  print('screen:   ${screen.messages}');
  print('wire row: ${api.rows.firstWhere((r) => r['task_id'] == 't1')}');

  test('the use case applied the rule and wrote', screen.messages[0], 'completed buy milk');
  test('the second tap is answered by the rule, not the network',
      screen.messages[1], 'already done');
  test('a missing id is an answer, not a crash', screen.messages[2], 'no such task');
  test('the data layer wrote the wire shape back',
      api.rows.firstWhere((r) => r['task_id'] == 't1')['is_done'], true);
  test('and the wire spelling never left the data layer',
      api.rows.first.keys.toList(), ['task_id', 'task_title', 'is_done']);
  test('the domain rule is testable with nothing plugged in at all',
      const Task(id: 't', title: 'x', done: false).complete().done, true);
}

screen:   [completed buy milk, already done, no such task]
wire row: {task_id: t1, task_title: buy milk, is_done: true}
ok   the use case applied the rule and wrote
ok   the second tap is answered by the rule, not the network
ok   a missing id is an answer, not a crash
ok   the data layer wrote the wire shape back
ok   and the wire spelling never left the data layer
ok   the domain rule is testable with nothing plugged in at all

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78// ---------- DOMAIN. Written once, and not edited again in this panel. -------
class Rate {
  const Rate(this.pair, this.value);
  final String pair;
  final double value;
}

abstract interface class RatePort {
  Future<Rate> latest(String pair);
}

class ConvertMoney {
  const ConvertMoney(this.rates);
  final RatePort rates;

  Future<String> call(String pair, double amount) async {
    final rate = await rates.latest(pair);
    return '${(amount * rate.value).toStringAsFixed(2)} $pair';
  }
}

// ---------- DATA. Two of them. Neither is known to the domain. -------------
class HttpRates implements RatePort {
  @override
  Future<Rate> latest(String pair) async {
    await Future<void>.delayed(Duration.zero);
    final body = <String, Object?>{'symbol': pair, 'px': 1.25};
    return Rate(body['symbol']! as String, body['px']! as double);
  }
}

class TableRates implements RatePort {
  TableRates(this.rows);
  final List<(String, double)> rows;

  @override
  Future<Rate> latest(String pair) async {
    final row = rows.firstWhere((r) => r.$1 == pair);
    return Rate(row.$1, row.$2);
  }
}

/// And the third implementation, which is a test: three lines, no I/O.
class FakeRates implements RatePort {
  FakeRates(this.fixed);
  final double fixed;

  @override
  Future<Rate> latest(String pair) async => Rate(pair, fixed);
}

/// Reports the type an expression has to the COMPILER, which is not always
/// the type that turns up at run time.
Type declaredType<T>(T _) => T;

Future<void> main() async {
  final overHttp = ConvertMoney(HttpRates());
  final overTable = ConvertMoney(TableRates([('GBPUSD', 1.25)]));

  final fromHttp = await overHttp('GBPUSD', 80);
  final fromTable = await overTable('GBPUSD', 80);

  print('over http:  $fromHttp');
  print('over table: $fromTable');
  print('domain compiled against ${declaredType(overHttp.rates)}, '
      'got ${overHttp.rates.runtimeType}');

  test('the use case, over the network', fromHttp, '100.00 GBPUSD');
  test('and over a local table, the same answer', fromTable, fromHttp);
  test('the two sources are different classes',
      overHttp.rates.runtimeType == overTable.rates.runtimeType, false);
  test('the domain was compiled against the port it wrote',
      declaredType(overHttp.rates), RatePort);
  test('what turned up at run time is a data class it has never heard of',
      overHttp.rates.runtimeType, HttpRates);
  test('and a test is just a third implementation',
      await ConvertMoney(FakeRates(2)).call('GBPUSD', 10), '20.00 GBPUSD');
}

over http:  100.00 GBPUSD
over table: 100.00 GBPUSD
domain compiled against RatePort, got HttpRates
ok   the use case, over the network
ok   and over a local table, the same answer
ok   the two sources are different classes
ok   the domain was compiled against the port it wrote
ok   what turned up at run time is a data class it has never heard of
ok   and a test is just a third implementation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47/// The dependency rule, written down as data: which layer may import which.
const rule = <String, Set<String>>{
  'presentation': {'presentation', 'domain'},
  'domain': {'domain'},
  'data': {'data', 'domain'},
};

String layerOf(String path) => path.split('/')[1];

/// Given every file and what it imports, report the edges that break the rule.
/// This is about fifteen lines and it runs in CI, which is the difference
/// between a layering you have and a layering you only meant.
List<String> violations(Map<String, List<String>> imports) {
  final out = <String>[];
  for (final file in imports.entries) {
    final from = layerOf(file.key);
    for (final target in file.value) {
      final to = layerOf(target);
      if (!rule[from]!.contains(to)) out.add('$from -> $to in ${file.key}');
    }
  }
  return out;
}

void main() {
  final good = <String, List<String>>{
    'lib/presentation/task_page.dart': ['lib/domain/complete_task.dart'],
    'lib/domain/complete_task.dart': ['lib/domain/task.dart'],
    'lib/data/task_repository.dart': ['lib/domain/task.dart', 'lib/data/task_api.dart'],
  };

  // One import added in a hurry, six months in.
  final drifted = <String, List<String>>{
    ...good,
    'lib/domain/complete_task.dart': ['lib/domain/task.dart', 'lib/data/task_api.dart'],
  };

  print('clean:   ${violations(good)}');
  print('drifted: ${violations(drifted)}');

  test('presentation reaching into the domain is fine', violations(good), <String>[]);
  test('so is the data layer implementing a domain port', rule['data']!.contains('domain'), true);
  test('the domain may reach exactly one layer, its own', rule['domain'], {'domain'});
  test('the one bad import is caught', violations(drifted).length, 1);
  test('and named, with a direction',
      violations(drifted).first, 'domain -> data in lib/domain/complete_task.dart');
}

clean:   []
drifted: [domain -> data in lib/domain/complete_task.dart]
ok   presentation reaching into the domain is fine
ok   so is the data layer implementing a domain port
ok   the domain may reach exactly one layer, its own
ok   the one bad import is caught
ok   and named, with a direction

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71abstract interface class Mailer {
  Future<void> send(String to, String body);
}

/// The real one. In a unit test this opens a socket, which is exactly why
/// nobody wants it there.
class SmtpMailer implements Mailer {
  @override
  Future<void> send(String to, String body) async =>
      throw StateError('SmtpMailer opened a socket to $to');
}

/// A fake is not a testing trick. It is a second implementation of a contract
/// somebody already wrote down.
class RecordingMailer implements Mailer {
  final sent = <String>[];

  @override
  Future<void> send(String to, String body) async => sent.add('$to: $body');
}

/// Version one: makes its own dependency. Nothing can get between the two.
class SignupSelfMade {
  final Mailer _mailer = SmtpMailer();

  Future<String> register(String email) async {
    await _mailer.send(email, 'welcome');
    return 'registered $email';
  }
}

/// Version two: asks for it. One word different, and now it is testable.
class Signup {
  const Signup(this._mailer);
  final Mailer _mailer;

  Future<String> register(String email) async {
    await _mailer.send(email, 'welcome');
    return 'registered $email';
  }
}

Future<void> main() async {
  // Trying to test the self-made version reaches the real thing.
  String reached;
  try {
    await SignupSelfMade().register('ada@example.com');
    reached = 'no side effect';
  } on StateError catch (e) {
    reached = e.message;
  }

  final fake = RecordingMailer();
  final result = await Signup(fake).register('ada@example.com');

  // Two instances, two collaborators, no global state between them.
  final other = RecordingMailer();
  await Signup(other).register('grace@example.com');

  print('self-made: $reached');
  print('injected:  $result');
  print('recorded:  ${fake.sent}');

  test('the self-made version reaches the real collaborator in a test',
      reached, 'SmtpMailer opened a socket to ada@example.com');
  test('the injected version talks to whatever it was handed',
      result, 'registered ada@example.com');
  test('so the test can read what was sent', fake.sent, ['ada@example.com: welcome']);
  test('and two of them run side by side without interfering',
      [fake.sent.length, other.sent.length], [1, 1]);
}

self-made: SmtpMailer opened a socket to ada@example.com
injected:  registered ada@example.com
recorded:  [ada@example.com: welcome]
ok   the self-made version reaches the real collaborator in a test
ok   the injected version talks to whatever it was handed
ok   so the test can read what was sent
ok   and two of them run side by side without interfering

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77/// A locator is a map from a type to a way of making that type. That is all
/// get_it is, plus about two thousand lines of care.
class Locator {
  final _makers = <Type, Object Function()>{};
  final _cached = <Type, Object>{};
  final _isSingleton = <Type>{};

  /// A new one every time it is asked for.
  void addFactory<T extends Object>(T Function() make) {
    _makers[T] = make;
  }

  /// One, built on first use, then reused for the life of the app.
  void addLazySingleton<T extends Object>(T Function() make) {
    _makers[T] = make;
    _isSingleton.add(T);
  }

  T get<T extends Object>() {
    final ready = _cached[T];
    if (ready != null) return ready as T;
    final make = _makers[T];
    if (make == null) {
      // The cost of the whole approach, in one line: this is a run-time
      // failure where a constructor parameter would have been a compile error.
      throw StateError('nothing registered for $T');
    }
    final made = make() as T;
    if (_isSingleton.contains(T)) _cached[T] = made;
    return made;
  }
}

class ApiClient {
  ApiClient(this.builds) {
    builds.add('ApiClient built');
  }
  final List<String> builds;
}

class Request {
  Request(this.builds) {
    builds.add('Request built');
  }
  final List<String> builds;
}

void main() {
  final builds = <String>[];
  final locator = Locator()
    ..addLazySingleton<ApiClient>(() => ApiClient(builds))
    ..addFactory<Request>(() => Request(builds));

  print('before any get: $builds');

  final a = locator.get<ApiClient>();
  final b = locator.get<ApiClient>();
  final r1 = locator.get<Request>();
  final r2 = locator.get<Request>();

  String missing;
  try {
    locator.get<Locator>();
    missing = 'no error';
  } on StateError catch (e) {
    missing = e.message;
  }

  print('after: $builds');

  test('a lazy singleton is not built until something asks', builds.first, 'ApiClient built');
  test('and then it is the same object every time', identical(a, b), true);
  test('a factory hands back a new one each time', identical(r1, r2), false);
  test('so it was built twice, and the singleton once', builds.length, 3);
  test('and a type nobody registered fails at run time, not at compile time',
      missing, 'nothing registered for Locator');
}

before any get: []
after: [ApiClient built, Request built, Request built]
ok   a lazy singleton is not built until something asks
ok   and then it is the same object every time
ok   a factory hands back a new one each time
ok   so it was built twice, and the singleton once
ok   and a type nobody registered fails at run time, not at compile time

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75/// The locator from above, trimmed, plus the reset that everyone forgets.
class Locator {
  final _makers = <Type, Object Function()>{};

  void add<T extends Object>(T Function() make) => _makers[T] = make;

  T get<T extends Object>() {
    final make = _makers[T];
    if (make == null) throw StateError('nothing registered for $T');
    return make() as T;
  }

  void reset() => _makers.clear();
}

/// Global, because that is the point of a locator and also its problem.
Locator sl = Locator();

abstract interface class Prices {
  int of(String sku);
}

class LivePrices implements Prices {
  @override
  int of(String sku) => 999;
}

class FreePrices implements Prices {
  @override
  int of(String sku) => 0;
}

/// The dependency is nowhere in this signature. You cannot tell from the call
/// site that this reads a global.
int checkout(String sku) => sl.get<Prices>().of(sku);

/// A test that sets up a fake, and forgets to clean up.
int discountDayTest() {
  sl.add<Prices>(FreePrices.new);
  return checkout('tea');
}

/// A test that expects the real price, and registers nothing because the app's
/// bootstrap "already does that".
int normalPriceTest() => checkout('tea');

void main() {
  sl = Locator()..add<Prices>(LivePrices.new);
  final discountFirst = [discountDayTest(), normalPriceTest()];

  sl = Locator()..add<Prices>(LivePrices.new);
  final normalFirst = [normalPriceTest(), discountDayTest()];

  // The same suite, with reset() between tests.
  sl = Locator();
  String loud;
  try {
    normalPriceTest();
    loud = 'passed for no reason';
  } on StateError catch (e) {
    loud = e.message;
  }

  print('discount first: $discountFirst');
  print('normal first:   $normalFirst');
  print('reset between:  $loud');

  test('the first test gets its fake', discountFirst[0], 0);
  test('and the second inherits it, quietly', discountFirst[1], 0);
  test('reordered, the same second test sees the live price', normalFirst[0], 999);
  test('so the suite result depends on the order the tests ran in',
      [discountFirst.join(','), normalFirst.join(',')], ['0,0', '999,0']);
  test('a locator emptied between tests fails loudly instead',
      loud, 'nothing registered for Prices');
}

discount first: [0, 0]
normal first:   [999, 0]
reset between:  nothing registered for Prices
ok   the first test gets its fake
ok   and the second inherits it, quietly
ok   reordered, the same second test sees the live price
ok   so the suite result depends on the order the tests ran in
ok   a locator emptied between tests fails loudly instead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80enum Life { singleton, transient, scoped }

abstract interface class Closeable {
  void close();
}

/// Per-user or per-screen state. The kind of thing that must not outlive the
/// screen or the login that created it.
class CartSession implements Closeable {
  CartSession(this.id, this._log);
  final String id;
  final List<String> _log;

  @override
  void close() => _log.add('closed $id');
}

class Container {
  final _makers = <Type, Object Function()>{};
  final _lives = <Type, Life>{};
  final _app = <Type, Object>{};
  final _scopes = <Map<Type, Object>>[];

  void register<T extends Object>(Life life, T Function() make) {
    _makers[T] = make;
    _lives[T] = life;
  }

  void openScope() => _scopes.add({});

  /// Closing a scope is the only reason to have one: it disposes what it held.
  void closeScope() {
    for (final held in _scopes.removeLast().values) {
      if (held is Closeable) held.close();
    }
  }

  T get<T extends Object>() {
    if (_lives[T] == Life.transient) return _makers[T]!() as T;
    final home = _lives[T] == Life.singleton || _scopes.isEmpty ? _app : _scopes.last;
    return (home[T] ??= _makers[T]!()) as T;
  }
}

void main() {
  final log = <String>[];
  var carts = 0;
  final c = Container()
    ..register<ApiClient>(Life.singleton, ApiClient.new)
    ..register<Query>(Life.transient, Query.new)
    ..register<CartSession>(Life.scoped, () => CartSession('cart-${++carts}', log));

  final api = c.get<ApiClient>();

  c.openScope();
  final firstCart = c.get<CartSession>();
  final sameCart = c.get<CartSession>();
  c.closeScope();

  c.openScope();
  final secondCart = c.get<CartSession>();
  c.closeScope();

  print('carts made: $carts, log: $log');

  test('a singleton is the same object for the life of the app',
      identical(api, c.get<ApiClient>()), true);
  test('a transient is a fresh object every time',
      identical(c.get<Query>(), c.get<Query>()), false);
  test('a scoped object is shared inside its scope',
      identical(firstCart, sameCart), true);
  test('and the next scope gets its own', identical(firstCart, secondCart), false);
  test('closing the scope disposed what it held', log, ['closed cart-1', 'closed cart-2']);
  test('while the singleton is untouched by any of it',
      identical(api, c.get<ApiClient>()), true);
}

class ApiClient {}

class Query {}

carts made: 2, log: [closed cart-1, closed cart-2]
ok   a singleton is the same object for the life of the app
ok   a transient is a fresh object every time
ok   a scoped object is shared inside its scope
ok   and the next scope gets its own
ok   closing the scope disposed what it held
ok   while the singleton is untouched by any of it

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76/// Sealed, so the compiler knows the list of cases is closed. Two type
/// parameters, because the failure deserves a type as much as the success.
sealed class Result<T, E> {
  const Result();

  /// Change the success. Leave a failure alone.
  Result<U, E> map<U>(U Function(T value) f) => switch (this) {
        Ok(:final value) => Ok(f(value)),
        Err(:final error) => Err(error),
      };

  /// Chain a step that can itself fail. This is the method that makes the type
  /// worth having: the first failure short-circuits and nothing after it runs.
  Result<U, E> then<U>(Result<U, E> Function(T value) f) => switch (this) {
        Ok(:final value) => f(value),
        Err(:final error) => Err(error),
      };

  /// Collapse both sides into one type. Every screen ends in a fold.
  R fold<R>(R Function(T value) onOk, R Function(E error) onErr) => switch (this) {
        Ok(:final value) => onOk(value),
        Err(:final error) => onErr(error),
      };

  T getOrElse(T Function(E error) fallback) => fold((v) => v, fallback);
}

class Ok<T, E> extends Result<T, E> {
  const Ok(this.value);
  final T value;
}

class Err<T, E> extends Result<T, E> {
  const Err(this.error);
  final E error;
}

// Two steps that can each fail, and a log so we can see which of them ran.
final ran = <String>[];

Result<int, String> parseAge(String raw) {
  ran.add('parse');
  final n = int.tryParse(raw);
  if (n == null) return const Err('not a number');
  return Ok(n);
}

Result<String, String> band(int age) {
  ran.add('band');
  if (age < 18) return const Err('under age');
  return Ok(age < 65 ? 'adult' : 'senior');
}

String screen(Result<String, String> r) =>
    r.fold((v) => 'band: $v', (e) => 'sorry: $e');

void main() {
  final good = parseAge('42').then(band);
  final unparseable = parseAge('x').then(band);
  final tooYoung = parseAge('9').then(band);

  print('good:        ${screen(good)}');
  print('unparseable: ${screen(unparseable)}');
  print('too young:   ${screen(tooYoung)}');
  print('steps run:   $ran');

  test('a good value flows through both steps', screen(good), 'band: adult');
  test('the first failure short-circuits', screen(unparseable), 'sorry: not a number');
  test('so the second step ran twice, not three times',
      ran.where((s) => s == 'band').length, 2);
  test('a failure from the second step is carried the same way',
      screen(tooYoung), 'sorry: under age');
  test('map touches the success only', parseAge('7').map((n) => n * 2).getOrElse((_) => -1), 14);
  test('and does nothing at all to a failure',
      parseAge('x').map((n) => n * 2).getOrElse((_) => -1), -1);
}

good:        band: adult
unparseable: sorry: not a number
too young:   sorry: under age
steps run:   [parse, band, parse, parse, band]
ok   a good value flows through both steps
ok   the first failure short-circuits
ok   so the second step ran twice, not three times
ok   a failure from the second step is carried the same way
ok   map touches the success only
ok   and does nothing at all to a failure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67sealed class Result<T, E> {
  const Result();
}

class Ok<T, E> extends Result<T, E> {
  const Ok(this.value);
  final T value;
}

class Err<T, E> extends Result<T, E> {
  const Err(this.error);
  final E error;
}

/// The failure type is a family, and each case carries what the UI needs to
/// act. This is the half of Result that people skip.
sealed class SaveError {
  const SaveError();
}

class Offline extends SaveError {
  const Offline(this.queued);
  final int queued;
}

class Rejected extends SaveError {
  const Rejected(this.field, this.why);
  final String field;
  final String why;
}

class SessionExpired extends SaveError {
  const SessionExpired();
}

/// One switch, four arms, four different things the app should DO. Nested
/// patterns match the Result and the error inside it in one step.
({String show, bool retry, bool signIn}) act(Result<String, SaveError> r) => switch (r) {
      Ok(:final value) => (show: 'saved $value', retry: false, signIn: false),
      Err(error: Offline(:final queued)) =>
        (show: 'saved on this device, $queued waiting', retry: true, signIn: false),
      Err(error: Rejected(:final field, :final why)) =>
        (show: '$field: $why', retry: false, signIn: false),
      Err(error: SessionExpired()) =>
        (show: 'your session ended', retry: false, signIn: true),
    };

void main() {
  final saved = act(const Ok('draft-9'));
  final offline = act(const Err(Offline(3)));
  final rejected = act(const Err(Rejected('email', 'already in use')));
  final expired = act(const Err(SessionExpired()));

  print('saved:    $saved');
  print('offline:  $offline');
  print('rejected: $rejected');
  print('expired:  $expired');

  test('success shows the id', saved.show, 'saved draft-9');
  test('offline is the only one that offers a retry',
      [offline.retry, rejected.retry, expired.retry], [true, false, false]);
  test('and it can say how much is queued, because the case carries the number',
      offline.show, 'saved on this device, 3 waiting');
  test('a rejection points at the field the user must fix', rejected.show, 'email: already in use');
  test('and only one failure sends them to a login screen',
      [saved.signIn, offline.signIn, expired.signIn], [false, false, true]);
}

saved:    (retry: false, show: saved draft-9, signIn: false)
offline:  (retry: true, show: saved on this device, 3 waiting, signIn: false)
rejected: (retry: false, show: email: already in use, signIn: false)
expired:  (retry: false, show: your session ended, signIn: true)
ok   success shows the id
ok   offline is the only one that offers a retry
ok   and it can say how much is queued, because the case carries the number
ok   a rejection points at the field the user must fix
ok   and only one failure sends them to a login screen

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74sealed class Result<T> {
  const Result();

  R fold<R>(R Function(T value) onOk, R Function(String error) onErr) => switch (this) {
        Ok(:final value) => onOk(value),
        Err(:final error) => onErr(error),
      };
}

class Ok<T> extends Result<T> {
  const Ok(this.value);
  final T value;
}

class Err<T> extends Result<T> {
  const Err(this.error);
  final String error;
}

/// A real bug: <= where < was meant. It is in the domain, and it is not a
/// failure mode - it is wrong code.
int sumOf(List<int> prices) {
  var total = 0;
  for (var i = 0; i <= prices.length; i++) {
    total += prices[i];
  }
  return total;
}

/// Policy A: never throw, whatever happens. Popular, and it hides the bug.
Result<int> catchEverything(List<int> prices) {
  try {
    return Ok(sumOf(prices));
  } catch (_) {
    return const Err('could not total the basket');
  }
}

/// Policy B: only the failures the domain expects become a Result. Anything
/// else is left alone, so it reaches the crash reporter.
Result<int> expectedOnly(List<int> prices) {
  if (prices.isEmpty) return const Err('empty basket');
  return Ok(sumOf(prices));
}

void main() {
  final reported = <String>[];

  final friendly = catchEverything([100, 250]).fold((v) => 'total $v', (e) => e);
  final quietSoFar = reported.length;

  String outcome;
  try {
    expectedOnly([100, 250]);
    outcome = 'no crash';
  } catch (e) {
    reported.add(e.runtimeType.toString());
    outcome = 'crashed';
  }

  final realFailure = expectedOnly([]).fold((v) => 'total $v', (e) => e);

  print('policy A: $friendly');
  print('policy B: $outcome, reported $reported');
  print('expected failure: $realFailure');

  test('the catch-all turned a programming bug into a domain failure',
      friendly, 'could not total the basket');
  test('and told nobody about it', quietSoFar, 0);
  test('without the catch-all the same bug crashes', outcome, 'crashed');
  test('so it reaches whatever you report crashes with', reported.length, 1);
  test('while a failure the domain actually expects is still a Result',
      realFailure, 'empty basket');
}

policy A: could not total the basket
policy B: crashed, reported [RangeError]
expected failure: empty basket
ok   the catch-all turned a programming bug into a domain failure
ok   and told nobody about it
ok   without the catch-all the same bug crashes
ok   so it reaches whatever you report crashes with
ok   while a failure the domain actually expects is still a Result

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72sealed class SaveError {
  const SaveError();
}

class Offline extends SaveError {
  const Offline();
}

class Rejected extends SaveError {
  const Rejected(this.field);
  final String field;
}

sealed class Result<T, E> {
  const Result();

  R fold<R>(R Function(T value) onOk, R Function(E error) onErr) => switch (this) {
        Ok(:final value) => onOk(value),
        Err(:final error) => onErr(error),
      };

  /// The shortcut. Note what it does to E: a typed value becomes a message.
  T getOrThrow() => fold((v) => v, (e) => throw Exception('save failed: $e'));
}

class Ok<T, E> extends Result<T, E> {
  const Ok(this.value);
  final T value;
}

class Err<T, E> extends Result<T, E> {
  const Err(this.error);
  final E error;
}

/// The version the type was designed for: the failure is still a value, so the
/// caller can decide between a retry and a field highlight.
({String show, bool retry}) viaFold(Result<String, SaveError> r) => r.fold(
      (v) => (show: v, retry: false),
      (e) => switch (e) {
        Offline() => (show: 'offline', retry: true),
        Rejected(:final field) => (show: 'fix $field', retry: false),
      },
    );

/// The version everyone writes by the third sprint.
({String show, bool retry}) viaThrow(Result<String, SaveError> r) {
  try {
    return (show: r.getOrThrow(), retry: false);
  } catch (e) {
    return (show: 'something went wrong', retry: e is SaveError);
  }
}

/// The static type of an expression, which is what a reviewer sees.
Type declaredType<T>(T _) => T;

void main() {
  const failure = Err<String, SaveError>(Offline());

  print('fold:  ${viaFold(failure)}');
  print('throw: ${viaThrow(failure)}');

  test('the fold version knows this failure is worth retrying',
      viaFold(failure).retry, true);
  test('the throw version cannot tell, because a typed error became a message',
      viaThrow(failure).retry, false);
  test('so the best it can offer is a generic apology',
      viaThrow(failure).show, 'something went wrong');
  test('both are declared identically, so a reviewer sees no difference',
      declaredType(viaFold) == declaredType(viaThrow), true);
}

fold:  (retry: true, show: offline)
throw: (retry: false, show: something went wrong)
ok   the fold version knows this failure is worth retrying
ok   the throw version cannot tell, because a typed error became a message
ok   so the best it can offer is a generic apology
ok   both are declared identically, so a reviewer sees no difference

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83import 'dart:async';

class Profile {
  const Profile(this.id, this.name);
  final String id;
  final String name;
}

/// The fake remote. It counts calls, because "did that hit the network" is the
/// only interesting question you can ask a cache.
class ProfileApi {
  ProfileApi(this._name);
  String _name;
  int calls = 0;

  Future<Profile> fetch(String id) async {
    calls++;
    await Future<void>.delayed(Duration.zero);
    return Profile(id, _name);
  }

  /// Someone edits the record elsewhere. The cache cannot know.
  void editedElsewhere(String name) => _name = name;
}

/// Injected time, so a five minute TTL is testable in a microsecond.
class Clock {
  Duration _t = Duration.zero;
  Duration get now => _t;
  void advance(Duration d) => _t += d;
}

class ProfileRepository {
  ProfileRepository(this._api, this._clock, {this.ttl = const Duration(minutes: 5)});
  final ProfileApi _api;
  final Clock _clock;
  final Duration ttl;

  Profile? _value;
  Duration? _storedAt;

  bool get stale => _storedAt == null || _clock.now - _storedAt! >= ttl;

  Future<Profile> profile(String id, {bool force = false}) async {
    if (!force && _value != null && !stale) return _value!;
    final fresh = await _api.fetch(id);
    _value = fresh;
    _storedAt = _clock.now;
    return fresh;
  }
}

Future<void> main() async {
  final api = ProfileApi('Ada');
  final clock = Clock();
  final repo = ProfileRepository(api, clock);

  final first = await repo.profile('u1');
  final second = await repo.profile('u1');
  final afterTwoReads = api.calls;

  clock.advance(const Duration(minutes: 4));
  await repo.profile('u1');
  final insideTtl = api.calls;

  api.editedElsewhere('Ada L');
  clock.advance(const Duration(minutes: 2));      // six minutes in total
  final afterExpiry = await repo.profile('u1');

  await repo.profile('u1', force: true);

  print('calls: $afterTwoReads then $insideTtl then ${api.calls}');
  print('name after expiry: ${afterExpiry.name}');

  test('two reads, one request', afterTwoReads, 1);
  test('and both callers hold the same object, not two copies',
      identical(first, second), true);
  test('inside the TTL it is still a cache hit', insideTtl, 1);
  test('past the TTL it goes back to the network', afterExpiry.name, 'Ada L');
  test('force ignores the TTL, which is what pull-to-refresh needs', api.calls, 3);
  test('the caller never learned where any of that came from',
      first.runtimeType, Profile);
}

calls: 1 then 1 then 3
name after expiry: Ada L
ok   two reads, one request
ok   and both callers hold the same object, not two copies
ok   inside the TTL it is still a cache hit
ok   past the TTL it goes back to the network
ok   force ignores the TTL, which is what pull-to-refresh needs
ok   the caller never learned where any of that came from

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92import 'dart:async';

class Profile {
  const Profile(this.name);
  final String name;
}

class ProfileApi {
  ProfileApi(this._name);
  String _name;
  int calls = 0;

  Future<Profile> fetch() async {
    calls++;
    await Future<void>.delayed(Duration.zero);
    return Profile(_name);
  }

  void editedElsewhere(String name) => _name = name;
}

class Clock {
  Duration _t = Duration.zero;
  Duration get now => _t;
  void advance(Duration d) => _t += d;
}

class SwrRepository {
  SwrRepository(this._api, this._clock, this.ttl);
  final ProfileApi _api;
  final Clock _clock;
  final Duration ttl;

  Profile? _value;
  Duration? _storedAt;
  Future<Profile>? _inFlight;

  bool get _stale => _storedAt == null || _clock.now - _storedAt! >= ttl;

  /// Synchronous on purpose. The UI gets whatever exists right now, and a
  /// refresh happens beside it. No await, so no spinner over good data.
  ({String? now, bool refreshing}) read() {
    if (_stale) _refresh();
    return (now: _value?.name, refreshing: _inFlight != null);
  }

  /// Single flight: the first caller starts the request, the rest join it.
  Future<Profile> _refresh() => _inFlight ??= _api.fetch().then((fresh) {
        _value = fresh;
        _storedAt = _clock.now;
        _inFlight = null;
        return fresh;
      });

  Future<void> settle() async {
    while (_inFlight != null) {
      await _inFlight;
    }
  }
}

Future<void> main() async {
  final api = ProfileApi('Ada');
  final clock = Clock();
  final repo = SwrRepository(api, clock, const Duration(minutes: 5));

  final cold = repo.read();
  await repo.settle();
  final warm = repo.read();

  api.editedElsewhere('Ada L');
  clock.advance(const Duration(minutes: 6));

  // Three widgets build in the same frame, all asking for the profile.
  final stale = [repo.read(), repo.read(), repo.read()];
  await repo.settle();
  final fresh = repo.read();

  print('cold:  $cold');
  print('stale: ${stale.first}');
  print('fresh: $fresh');
  print('requests: ${api.calls}');

  test('a cold read has nothing to draw yet, and starts a fetch',
      [cold.now == null, cold.refreshing], [true, true]);
  test('once it lands the read is instant', [warm.now, warm.refreshing], ['Ada', false]);
  test('past the TTL the read still returns the old value at once',
      stale.first.now, 'Ada');
  test('three widgets in one frame is still one request', api.calls, 2);
  test('and the read after it sees the new value', fresh.now, 'Ada L');
  test('with nothing in flight any more', fresh.refreshing, false);
}

cold:  (now: null, refreshing: true)
stale: (now: Ada, refreshing: true)
fresh: (now: Ada L, refreshing: false)
requests: 2
ok   a cold read has nothing to draw yet, and starts a fetch
ok   once it lands the read is instant
ok   past the TTL the read still returns the old value at once
ok   three widgets in one frame is still one request
ok   and the read after it sees the new value
ok   with nothing in flight any more

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56/// The repository. Everyone agrees this is the source of truth.
class PriceRepository {
  final _pence = <String, int>{'tea': 250};
  final _listeners = <void Function(int)>[];

  int priceOf(String sku) => _pence[sku]!;

  void write(String sku, int pence) {
    _pence[sku] = pence;
    for (final tell in _listeners) {
      tell(pence);
    }
  }

  void watch(void Function(int) onChange) => _listeners.add(onChange);
}

/// A screen that copied the value at open time, because it needed it in a
/// field and that was one line. It is now a second cache.
class CopyingScreen {
  CopyingScreen(PriceRepository repo, String sku) : shown = repo.priceOf(sku);
  int shown;
}

/// The same screen, subscribing instead of copying. One extra line.
class WatchingScreen {
  WatchingScreen(PriceRepository repo, String sku) : shown = repo.priceOf(sku) {
    repo.watch((pence) => shown = pence);
  }
  int shown;
}

void main() {
  final repo = PriceRepository();

  final basket = CopyingScreen(repo, 'tea');
  final watched = WatchingScreen(repo, 'tea');
  final agreedAtFirst = [basket.shown, watched.shown, repo.priceOf('tea')];

  // A price change arrives: another screen saved, or a push notification did.
  repo.write('tea', 300);

  // And a second copy of the same screen, opened after the change.
  final reopened = CopyingScreen(repo, 'tea');

  print('at first: $agreedAtFirst');
  print('after the write: basket ${basket.shown}, reopened ${reopened.shown}, '
      'watched ${watched.shown}, repo ${repo.priceOf('tea')}');

  test('everyone agreed to begin with', agreedAtFirst, [250, 250, 250]);
  test('the repository has the new price', repo.priceOf('tea'), 300);
  test('the screen that copied still shows the old one', basket.shown, 250);
  test('so two copies of one screen disagree with each other',
      [basket.shown, reopened.shown], [250, 300]);
  test('the subscribing screen agrees with the repository', watched.shown, 300);
}

at first: [250, 250, 250]
after the write: basket 250, reopened 300, watched 300, repo 300
ok   everyone agreed to begin with
ok   the repository has the new price
ok   the screen that copied still shows the old one
ok   so two copies of one screen disagree with each other
ok   the subscribing screen agrees with the repository

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83import 'dart:async';

class Profile {
  const Profile(this.name);
  final String name;
}

class ProfileApi {
  int calls = 0;

  Future<Profile> fetch() async {
    calls++;
    await Future<void>.delayed(Duration.zero);
    return const Profile('Ada');
  }

  Future<Profile> rename(String name) async {
    await Future<void>.delayed(Duration.zero);
    return Profile(name);
  }
}

/// The source of truth: one held value, one broadcast stream, and writes that
/// go through here so there is nowhere else for the value to live.
class ProfileRepository {
  ProfileRepository(this._api);
  final ProfileApi _api;
  final _out = StreamController<Profile>.broadcast();

  Profile? _value;

  /// A late subscriber gets the current value first, then the changes. That
  /// replay is what stops a widget from having to keep its own copy.
  Stream<Profile> watch() async* {
    final held = _value;
    if (held != null) yield held;
    yield* _out.stream;
  }

  Future<void> load() async => _publish(await _api.fetch());

  Future<void> rename(String name) async => _publish(await _api.rename(name));

  void _publish(Profile p) {
    _value = p;
    _out.add(p);
  }

  Future<void> close() => _out.close();
}

Future<void> main() async {
  final api = ProfileApi();
  final repo = ProfileRepository(api);

  final early = <String>[];
  final subEarly = repo.watch().listen((p) => early.add(p.name));

  await repo.load();
  await Future<void>.delayed(Duration.zero);

  // A second screen opens well after the load.
  final later = <String>[];
  final subLater = repo.watch().listen((p) => later.add(p.name));
  await Future<void>.delayed(Duration.zero);

  await repo.rename('Ada L');
  await Future<void>.delayed(Duration.zero);

  print('early: $early');
  print('later: $later');
  print('fetches: ${api.calls}');

  test('the first subscriber saw the load and the rename', early, ['Ada', 'Ada L']);
  test('the later one was handed the current value immediately', later.first, 'Ada');
  test('and then followed the same changes', later, ['Ada', 'Ada L']);
  test('so both screens end on the same value', early.last, later.last);
  test('and the second screen cost no extra request', api.calls, 1);

  await subEarly.cancel();
  await subLater.cancel();
  await repo.close();
}

early: [Ada, Ada L]
later: [Ada, Ada L]
fetches: 1
ok   the first subscriber saw the load and the rename
ok   the later one was handed the current value immediately
ok   and then followed the same changes
ok   so both screens end on the same value
ok   and the second screen cost no extra request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98/// A write the user made. The id comes from the device, before any network
/// call exists, which is what makes replaying it safe.
class Op {
  const Op(this.id, this.kind, this.sku);
  final String id;
  final String kind;
  final String sku;

  @override
  String toString() => '$kind $sku';
}

class Server {
  bool reachable = false;

  final basket = <String>[];
  final log = <String>[];
  final _applied = <String>{};
  int duplicates = 0;

  Future<bool> apply(Op op) async {
    await Future<void>.delayed(Duration.zero);
    if (!reachable) return false;
    // Seen this id before? Say yes and do nothing. Six lines, and it is the
    // difference between a safe replay and a double charge.
    if (_applied.contains(op.id)) {
      duplicates++;
      return true;
    }
    _applied.add(op.id);
    log.add(op.toString());
    if (op.kind == 'add') basket.add(op.sku);
    if (op.kind == 'remove') basket.remove(op.sku);
    return true;
  }
}

class Outbox {
  Outbox(this._server);
  final Server _server;
  final _queue = <Op>[];

  int get pending => _queue.length;

  /// Accepted locally, always. The user is not waiting for anyone.
  void write(Op op) => _queue.add(op);

  /// Replay in order, and keep anything that did not land.
  Future<int> flush() async {
    var sent = 0;
    while (_queue.isNotEmpty) {
      if (!await _server.apply(_queue.first)) break;
      _queue.removeAt(0);
      sent++;
    }
    return sent;
  }
}

Future<void> main() async {
  final server = Server();
  final outbox = Outbox(server);

  // On a train, in a tunnel.
  outbox.write(const Op('op-1', 'add', 'tea'));
  outbox.write(const Op('op-2', 'add', 'jam'));
  outbox.write(const Op('op-3', 'remove', 'jam'));

  final sentWhileOffline = await outbox.flush();
  final serverSawNothing = server.log.isEmpty;
  final stillQueued = outbox.pending;

  server.reachable = true;
  final sentOnReconnect = await outbox.flush();

  // The app was killed after the server applied these but before the queue was
  // cleared, so on next launch the same three ops are still there.
  final replayed = Outbox(server)
    ..write(const Op('op-1', 'add', 'tea'))
    ..write(const Op('op-2', 'add', 'jam'))
    ..write(const Op('op-3', 'remove', 'jam'));
  await replayed.flush();

  print('server log: ${server.log}');
  print('basket:     ${server.basket}');
  print('duplicates ignored: ${server.duplicates}');

  test('nothing left the device while it was offline', sentWhileOffline, 0);
  test('and all three writes are still waiting', [serverSawNothing, stillQueued],
      [true, 3]);
  test('on reconnect all three land, in the order they were made',
      server.log, ['add tea', 'add jam', 'remove jam']);
  test('so the basket is what the user built, and nothing is queued',
      [server.basket, sentOnReconnect, outbox.pending], [['tea'], 3, 0]);
  test('replaying the same three changes nothing', server.basket, ['tea']);
  test('because the server recognised the ids it had already applied',
      server.duplicates, 3);
}

server log: [add tea, add jam, remove jam]
basket:     [tea]
duplicates ignored: 3
ok   nothing left the device while it was offline
ok   and all three writes are still waiting
ok   on reconnect all three land, in the order they were made
ok   so the basket is what the user built, and nothing is queued
ok   replaying the same three changes nothing
ok   because the server recognised the ids it had already applied

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47typedef Contact = ({String name, String phone, int at});

/// Last write wins: keep the whole record with the newest timestamp.
Contact lww(Contact a, Contact b) => a.at >= b.at ? a : b;

/// Field level merge: for each field, prefer the version that actually
/// changed. It needs the common ancestor, which is why you keep it.
Contact merge(Contact base, Contact a, Contact b) => (
      name: a.name != base.name ? a.name : b.name,
      phone: a.phone != base.phone ? a.phone : b.phone,
      at: a.at > b.at ? a.at : b.at,
    );

List<String> changed(Contact base, Contact edit) => [
      if (edit.name != base.name) 'name',
      if (edit.phone != base.phone) 'phone',
    ];

void main() {
  const base = (name: 'Ada Lovelace', phone: '0100', at: 10);

  // The phone fixed the name. The tablet fixed the number. Neither saw the
  // other, and the tablet synced second.
  const fromPhone = (name: 'Ada L', phone: '0100', at: 20);
  const fromTablet = (name: 'Ada Lovelace', phone: '0200', at: 25);

  final byLww = lww(fromPhone, fromTablet);
  final byMerge = merge(base, fromPhone, fromTablet);

  // And the case no rule can fix: both edited the same field.
  const bothNamed = (name: 'A. Lovelace', phone: '0100', at: 30);
  final sameField = merge(base, fromPhone, bothNamed);

  print('last write wins: $byLww');
  print('field merge:     $byMerge');
  print('same field:      $sameField');

  test('each device changed exactly one field',
      [changed(base, fromPhone), changed(base, fromTablet)], [['name'], ['phone']]);
  test('last write wins keeps the newer record whole', byLww.phone, '0200');
  test('and throws away the name edit, silently', byLww.name, 'Ada Lovelace');
  test('the merge keeps both edits', [byMerge.name, byMerge.phone], ['Ada L', '0200']);
  test('but when both edited the same field a rule can only pick one',
      sameField.name, 'Ada L');
  test('so that edit is lost too, and only the user could have decided',
      sameField.name == bothNamed.name, false);
}

last write wins: (at: 25, name: Ada Lovelace, phone: 0200)
field merge:     (at: 25, name: Ada L, phone: 0200)
same field:      (at: 30, name: Ada L, phone: 0100)
ok   each device changed exactly one field
ok   last write wins keeps the newer record whole
ok   and throws away the name edit, silently
ok   the merge keeps both edits
ok   but when both edited the same field a rule can only pick one
ok   so that edit is lost too, and only the user could have decided

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54typedef Vector = Map<String, int>;

int at(Vector v, String device) => v[device] ?? 0;

Set<String> _keys(Vector a, Vector b) => {...a.keys, ...b.keys};

bool same(Vector a, Vector b) => _keys(a, b).every((d) => at(a, d) == at(b, d));

bool dominates(Vector a, Vector b) =>
    !same(a, b) && _keys(a, b).every((d) => at(a, d) >= at(b, d));

/// The only question that matters on sync: does one of these already contain
/// the other, or did they genuinely happen side by side?
String relation(Vector a, Vector b) {
  if (same(a, b)) return 'identical';
  if (dominates(a, b)) return 'a already has b';
  if (dominates(b, a)) return 'b already has a';
  return 'concurrent';
}

Vector join(Vector a, Vector b) => {
      for (final d in _keys(a, b)) d: at(a, d) > at(b, d) ? at(a, d) : at(b, d),
    };

/// A single server-side version, for comparison. It can reject a stale write,
/// which is useful, but that is all it can do.
String ifMatch({required int clientSaw, required int serverHas}) =>
    clientSaw == serverHas ? 'accepted' : 'conflict, refetch';

void main() {
  // The phone wrote twice; the tablet wrote once, having seen the phone's first
  // write. So the tablet's version already contains the phone's.
  const phoneOnly = {'phone': 2};
  const tabletAfterPhone = {'phone': 1, 'tablet': 1};
  const phoneAndTablet = {'phone': 2, 'tablet': 1};

  print('plain version: ${ifMatch(clientSaw: 3, serverHas: 4)}');
  print('phoneOnly vs tabletAfterPhone: ${relation(phoneOnly, tabletAfterPhone)}');
  print('phoneAndTablet vs tabletAfterPhone: '
      '${relation(phoneAndTablet, tabletAfterPhone)}');

  test('a single version can spot a stale write',
      ifMatch(clientSaw: 3, serverHas: 4), 'conflict, refetch');
  test('and says nothing when the client is up to date',
      ifMatch(clientSaw: 4, serverHas: 4), 'accepted');
  test('a vector can tell that one edit already contains the other',
      relation(phoneAndTablet, tabletAfterPhone), 'a already has b');
  test('which a single number would have called a conflict',
      ifMatch(clientSaw: 2, serverHas: 3), 'conflict, refetch');
  test('and it still recognises a real one', relation(phoneOnly, tabletAfterPhone),
      'concurrent');
  test('after merging, the vector is the pointwise maximum of both',
      join(phoneOnly, tabletAfterPhone), {'phone': 2, 'tablet': 1});
}

plain version: conflict, refetch
phoneOnly vs tabletAfterPhone: concurrent
phoneAndTablet vs tabletAfterPhone: a already has b
ok   a single version can spot a stale write
ok   and says nothing when the client is up to date
ok   a vector can tell that one edit already contains the other
ok   which a single number would have called a conflict
ok   and it still recognises a real one
ok   after merging, the vector is the pointwise maximum of both

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82class Server {
  String stored = 'Ada';

  /// Rejects anything too short. The delay is per call, so a slow first
  /// request can answer after a fast second one - which is the whole point.
  Future<bool> rename(String next, int ms) async {
    await Future<void>.delayed(Duration(milliseconds: ms));
    if (next.length < 3) return false;
    stored = next;
    return true;
  }
}

/// The obvious version: keep what was there, put it back on rejection.
class NaiveScreen {
  NaiveScreen(this._server);
  final Server _server;

  String shown = 'Ada';
  String? banner;

  Future<void> rename(String next, int ms) async {
    final previous = shown;
    shown = next;                          // the frame the user sees
    if (!await _server.rename(next, ms)) {
      shown = previous;                    // and the bug
      banner = 'could not rename';
    }
  }
}

/// The same thing, with a revision counter. Only undo if nothing newer has
/// happened since; otherwise leave the newer value alone.
class GuardedScreen {
  GuardedScreen(this._server);
  final Server _server;

  String shown = 'Ada';
  String? banner;
  int _revision = 0;

  Future<void> rename(String next, int ms) async {
    final previous = shown;
    final mine = ++_revision;
    shown = next;
    if (!await _server.rename(next, ms)) {
      if (_revision == mine) shown = previous;
      banner = 'could not rename';
    }
  }
}

Future<void> main() async {
  // One edit, rejected. Both versions behave the same, and correctly.
  final simple = GuardedScreen(Server());
  final inFlight = simple.rename('Ad', 5);
  final immediately = simple.shown;
  await inFlight;

  // Two edits: a slow one that will be rejected, then a fast one that is fine.
  final naiveServer = Server();
  final naive = NaiveScreen(naiveServer);
  await Future.wait([naive.rename('Ad', 30), naive.rename('Ada Lovelace', 5)]);

  final guardedServer = Server();
  final guarded = GuardedScreen(guardedServer);
  await Future.wait([guarded.rename('Ad', 30), guarded.rename('Ada Lovelace', 5)]);

  print('optimistic frame: $immediately');
  print('naive:   shows ${naive.shown}, server has ${naiveServer.stored}');
  print('guarded: shows ${guarded.shown}, server has ${guardedServer.stored}');

  test('the UI showed the change before the server had answered', immediately, 'Ad');
  test('a rejection puts it back, and says so', [simple.shown, simple.banner],
      ['Ada', 'could not rename']);
  test('with two edits in flight the naive rollback undoes the good one',
      naive.shown, 'Ada');
  test('so the screen disagrees with the server it just talked to',
      naive.shown == naiveServer.stored, false);
  test('the guarded version leaves the newer edit alone', guarded.shown, 'Ada Lovelace');
  test('and agrees with the server', guarded.shown, guardedServer.stored);
}

optimistic frame: Ad
naive:   shows Ada, server has Ada Lovelace
guarded: shows Ada Lovelace, server has Ada Lovelace
ok   the UI showed the change before the server had answered
ok   a rejection puts it back, and says so
ok   with two edits in flight the naive rollback undoes the good one
ok   so the screen disagrees with the server it just talked to
ok   the guarded version leaves the newer edit alone
ok   and agrees with the server

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108/// The model on day one. Four hand-written members, and every one of them is a
/// second copy of the field list.
class Contact {
  const Contact({required this.id, required this.name});

  final String id;
  final String name;

  factory Contact.fromJson(Map<String, Object?> json) => Contact(
        id: json['id']! as String,
        name: json['name']! as String,
      );

  Map<String, Object?> toJson() => {'id': id, 'name': name};

  Contact copyWith({String? id, String? name}) =>
      Contact(id: id ?? this.id, name: name ?? this.name);

  @override
  bool operator ==(Object other) =>
      other is Contact && other.id == id && other.name == name;

  @override
  int get hashCode => Object.hash(id, name);
}

/// Six weeks later, with an email address. fromJson and toJson were updated,
/// because a missing required argument is a compile error and a missing key
/// shows up the first time anyone looks at the payload.
///
/// == and hashCode were not, because nothing anywhere fails when they are
/// wrong. That asymmetry is the entire lesson.
class ContactV2 {
  const ContactV2({required this.id, required this.name, required this.email});

  final String id;
  final String name;
  final String email;

  factory ContactV2.fromJson(Map<String, Object?> json) => ContactV2(
        id: json['id']! as String,
        name: json['name']! as String,
        email: json['email']! as String,
      );

  Map<String, Object?> toJson() => {'id': id, 'name': name, 'email': email};

  @override
  bool operator ==(Object other) =>
      other is ContactV2 && other.id == id && other.name == name;

  @override
  int get hashCode => Object.hash(id, name);
}

/// Every state container has this guard under some name — Cubit's emit,
/// ValueNotifier's setter, a Riverpod notifier's assignment. If the new state
/// equals the old one, no listener is told anything.
class Store {
  Store(this._state);

  ContactV2 _state;
  final shown = <String>[];

  void emit(ContactV2 next) {
    if (next == _state) return;
    _state = next;
    shown.add('${next.name} <${next.email}>');
  }
}

void main() {
  const wire = <String, Object?>{'id': 'c1', 'name': 'Ada'};

  final parsed = Contact.fromJson(wire);
  final renamed = parsed.copyWith(name: 'Ada Lovelace');
  final parsedAgain = Contact.fromJson(wire);
  final deduped = <Contact>{parsed, parsedAgain};

  // The same person, three ways. Only the email differs between the first two.
  const ada = ContactV2(id: 'c1', name: 'Ada', email: 'ada@example.com');
  const newEmail = ContactV2(id: 'c1', name: 'Ada', email: 'ada@lovelace.org');
  const newName = ContactV2(id: 'c1', name: 'Ada Lovelace', email: 'ada@lovelace.org');

  final store = Store(ada);
  store.emit(newEmail);
  store.emit(newName);

  print('round-trip:   ${parsed.toJson()}');
  print('copyWith:     ${renamed.toJson()}');
  print('v1 in a set:  ${deduped.length}');
  print('v2 equality:  ${ada == newEmail}  <- their emails are different');
  print('v2 in a set:  ${<ContactV2>{ada, newEmail}.length}');
  print('store showed: ${store.shown}');

  test('the hand-written pair round-trips a payload', parsed.toJson(), wire);
  test('and copyWith changes one field and keeps the other',
      renamed.toJson(), {'id': 'c1', 'name': 'Ada Lovelace'});
  test('two separate parses of the same payload are equal', parsed == parsedAgain, true);
  test('so a Set folds them into one, which needs hashCode to agree as well',
      deduped.length, 1);
  test('but once the model gained a field, two different contacts are equal',
      ada == newEmail, true);
  test('so a Set keeps the first and drops the second, silently',
      <ContactV2>{ada, newEmail}.length, 1);
  test('and the store never showed the new email until an unrelated field moved',
      store.shown, ['Ada Lovelace <ada@lovelace.org>']);
}

round-trip:   {id: c1, name: Ada}
copyWith:     {id: c1, name: Ada Lovelace}
v1 in a set:  1
v2 equality:  true  <- their emails are different
v2 in a set:  1
store showed: [Ada Lovelace <ada@lovelace.org>]
ok   the hand-written pair round-trips a payload
ok   and copyWith changes one field and keeps the other
ok   two separate parses of the same payload are equal
ok   so a Set folds them into one, which needs hashCode to agree as well
ok   but once the model gained a field, two different contacts are equal
ok   so a Set keeps the first and drops the second, silently
ok   and the store never showed the new email until an unrelated field moved

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54/// A sentinel: a value no caller can produce and no field can hold, so seeing
/// it means the argument was not passed. A plain const Object() is enough.
const _absent = Object();

class Profile {
  const Profile({required this.name, this.nickname});

  final String name;
  final String? nickname;

  /// What almost everyone writes by hand. The ?? is the bug: an omitted
  /// argument and an explicit null are the same value here.
  Profile naive({String? name, String? nickname}) =>
      Profile(name: name ?? this.name, nickname: nickname ?? this.nickname);

  /// The version that works, and the reason a generated copyWith takes Object?
  /// parameters with a const sentinel default rather than typed ones.
  ///
  /// Note which parameter needed it. [name] is non-nullable, so null there can
  /// only mean absent and ?? is correct. Only the nullable field is ambiguous,
  /// and that is the rule: sentinels exactly where null is a legal value.
  Profile copyWith({String? name, Object? nickname = _absent}) => Profile(
        name: name ?? this.name,
        nickname: identical(nickname, _absent) ? this.nickname : nickname as String?,
      );

  String show() => '$name / ${nickname ?? "no nickname"}';
}

void main() {
  const ada = Profile(name: 'Ada', nickname: 'Countess');

  final naiveRename = ada.naive(name: 'Ada Lovelace');
  final naiveClear = ada.naive(nickname: null);

  final rename = ada.copyWith(name: 'Ada Lovelace');
  final clear = ada.copyWith(nickname: null);
  final reset = ada.copyWith(nickname: 'Ada');

  print('naive rename: ${naiveRename.show()}');
  print('naive clear:  ${naiveClear.show()}   <- asked for null, got the old value');
  print('rename:       ${rename.show()}');
  print('clear:        ${clear.show()}');
  print('set:          ${reset.show()}');

  test('the naive copyWith can change a field', naiveRename.name, 'Ada Lovelace');
  test('and it leaves the arguments you omitted alone', naiveRename.nickname, 'Countess');
  test('but asking it for null hands back the old value', naiveClear.nickname, 'Countess');
  test('the sentinel version also leaves omitted arguments alone', rename.nickname, 'Countess');
  test('and it can actually clear the field', clear.nickname, null);
  test('while still setting one when asked', reset.nickname, 'Ada');
  test('so omitted and null are two different things now, and were not before',
      [naiveClear.nickname == null, clear.nickname == null], [false, true]);
}

naive rename: Ada Lovelace / Countess
naive clear:  Ada / Countess   <- asked for null, got the old value
rename:       Ada Lovelace / Countess
clear:        Ada / no nickname
set:          Ada / Ada
ok   the naive copyWith can change a field
ok   and it leaves the arguments you omitted alone
ok   but asking it for null hands back the old value
ok   the sentinel version also leaves omitted arguments alone
ok   and it can actually clear the field
ok   while still setting one when asked
ok   so omitted and null are two different things now, and were not before

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54/// The members a value model needs, how many times a NEW field has to be
/// named inside each, and whether the compiler catches you forgetting.
class Member {
  const Member(this.name, this.mentions, {required this.loud});

  final String name;
  final int mentions;
  final bool loud;
}

const model = <Member>[
  Member('the field declaration', 1, loud: true),
  Member('the constructor parameter', 1, loud: true),
  Member('fromJson', 2, loud: true), // a required argument goes missing
  Member('toJson', 2, loud: false), // the key is simply absent on the wire
  Member('==', 2, loud: false),
  Member('hashCode', 1, loud: false),
  Member('copyWith', 3, loud: false), // parameter, argument, and the ?? this.x
  Member('toString', 1, loud: false),
];

/// Seconds, from a mid-sized app with roughly ninety generated files.
/// Substitute your own numbers; it is the shape of the answer that transfers.
const cold = 95; // build_runner build, no cache, as CI runs it
const warm = 3; // build_runner watch, one file touched
const prsPerMonth = 40;
const prsTouchingAModel = 5; // about one in eight, in any real codebase

int get edits => model.fold(0, (n, m) => n + m.mentions);
List<String> get silent => [for (final m in model) if (!m.loud) m.name];

void main() {
  const everyPr = prsPerMonth * cold;
  const cachedProperly = prsTouchingAModel * cold;

  print('edits for one new field: $edits');
  print('places that rot quietly: $silent');
  print('cold vs incremental:     ${(cold / warm).toStringAsFixed(1)}x');
  print('CI per month: ${everyPr ~/ 60}m ${everyPr % 60}s regenerating always, '
      '${cachedProperly ~/ 60}m ${cachedProperly % 60}s cached');

  test('one new field is thirteen edits across eight members', edits, 13);
  test('and the compiler catches you in only three of the eight places',
      model.where((m) => m.loud).length, 3);
  test('so five places can go stale with no diagnostic at all', silent.length, 5);
  test('which is five eighths of the work', close(silent.length * 100 / model.length, 62.5),
      true);
  test('a cold generator run costs about thirty-two incremental ones',
      close(cold / warm, 31.667, 0.001), true);
  test('regenerating on every pull request is sixty-three minutes of CI a month',
      everyPr ~/ 60, 63);
  test('caching it, so you pay only when a model changes, is under eight minutes',
      cachedProperly ~/ 60, 7);
}

edits for one new field: 13
places that rot quietly: [toJson, ==, hashCode, copyWith, toString]
cold vs incremental:     31.7x
CI per month: 63m 20s regenerating always, 7m 55s cached
ok   one new field is thirteen edits across eight members
ok   and the compiler catches you in only three of the eight places
ok   so five places can go stale with no diagnostic at all
ok   which is five eighths of the work
ok   a cold generator run costs about thirty-two incremental ones
ok   regenerating on every pull request is sixty-three minutes of CI a month
ok   caching it, so you pay only when a model changes, is under eight minutes