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

---
status: accepted
---

# Use Signals for reactive API

## Context and Problem Statement

Development of ef.js has started as Signals + DOM library.
However, I noticed Signals does not work well outside of synchronous function call stack, during implementing the library.

Are there any tricks covers this drawback?
Can other API design style work well with `el` function?

## Decision Drivers

- Less unexpected behaviours on usage inside async and/or generator function.
- Sophisticated and specialized API for the web platform.

## Considered Options

- Signals
- Observer pattern
- Signals-like API with manual scope management

## Decision Outcome

Chosen option "Signals", because of the simplicity and ease of use.
This option also is least error-prone compared to the other two.

## Pros and Cons of the Options

### Signals

The original plan.
API design pattern implemented in S.js, Solid.js, Preact, etc.

```ts
// Create a reactive value.
const $age = signal(10);

// Create a derived reactive value, which is read-only.
const $isLegalToDrink = derived(() => {
  // NOTE: This is the drinking age in Japan.
  return $age.get() >= 20;
});

// Runs a function everytime the reactive values inside the function got changed.
effect(() => {
  console.log($isLegalToDrink.get());
});

el("div", [attr("data-legal", $isLegalToDrink)]);

setTimeout(() => {
  $age.set(21);
}, 1_000);
```

- Good, because dependency is built implicitly by value getter
- Good, because the consumer of reactive values does not need a reference for the reactive value wrappers
- Bad, because it heavily relies on mutable global variable, which is the reason this does not work in async/generator function
- Bad, because it needs to explicitly pass around computation scope in order to work-around the async/generator function problem

### Observer pattern

Simple Observer class and Derived class (equivalent for `derived` function).

```ts
const $age = new Observable(10);

// `as const` is required
const $isLegalToDrink = new Derived([$age] as const, (age) => {
  return age >= 20;
});

$isLegalToDrink.subscribe((isLegalToDrink) => {
  console.log(isLegalToDrink);
});

el("div", [attr("data-legal", $isLegalToDrink)]);

setTimeout(() => {
  $age.write(21);
}, 1_000);
```

- Good, because it's simple and dependencies are clear
- Good, because it's an mature and established pattern
- Bad, because it too needs mutable global variable for ownership detection
- Bad, because manually passing dependency is verbose, especially with TypeScript

### Signals-like API with manual scope management

Eliminating the need of mutable global variable by exposing the internal computation scope.

```ts
const { effect, signal, derived, write } = scope();

const $age = signal(10);

const $isLegalToDrink = derived(({ read }) => {
  return read($age) >= 20;
});

effect(({ read }) => {
  console.log(read($isLegalToDrink));
});

el("div", [attr("data-legal", $isLegalToDrink)]);

setTimeout(() => {
  write($age, 21);
}, 1_000);
```

- Good, because dependencies and ownership is extreamly clear and visible
- Bad, because users can't just import functions
- Bad, because resulting code would be shadowing-hell or too noisy due to property access especially when nesting, which is so error-prone