@tldraw/state 5.4.0-next.ebc95cf01337 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/DOCS.md +64 -63
  2. package/README.md +35 -36
  3. package/dist-cjs/index.d.ts +25 -26
  4. package/dist-cjs/index.js +1 -1
  5. package/dist-cjs/lib/ArraySet.js +47 -144
  6. package/dist-cjs/lib/ArraySet.js.map +2 -2
  7. package/dist-cjs/lib/Atom.js +10 -25
  8. package/dist-cjs/lib/Atom.js.map +2 -2
  9. package/dist-cjs/lib/Computed.js +36 -61
  10. package/dist-cjs/lib/Computed.js.map +2 -2
  11. package/dist-cjs/lib/EffectScheduler.js +4 -2
  12. package/dist-cjs/lib/EffectScheduler.js.map +2 -2
  13. package/dist-cjs/lib/HistoryBuffer.js +8 -8
  14. package/dist-cjs/lib/HistoryBuffer.js.map +2 -2
  15. package/dist-cjs/lib/capture.js.map +2 -2
  16. package/dist-cjs/lib/constants.js.map +2 -2
  17. package/dist-cjs/lib/helpers.js +3 -11
  18. package/dist-cjs/lib/helpers.js.map +2 -2
  19. package/dist-cjs/lib/localStorageAtom.js +7 -2
  20. package/dist-cjs/lib/localStorageAtom.js.map +2 -2
  21. package/dist-cjs/lib/transactions.js +37 -49
  22. package/dist-cjs/lib/transactions.js.map +2 -2
  23. package/dist-cjs/lib/types.js.map +1 -1
  24. package/dist-esm/index.d.mts +25 -26
  25. package/dist-esm/index.mjs +1 -1
  26. package/dist-esm/lib/ArraySet.mjs +47 -144
  27. package/dist-esm/lib/ArraySet.mjs.map +2 -2
  28. package/dist-esm/lib/Atom.mjs +10 -25
  29. package/dist-esm/lib/Atom.mjs.map +2 -2
  30. package/dist-esm/lib/Computed.mjs +37 -62
  31. package/dist-esm/lib/Computed.mjs.map +2 -2
  32. package/dist-esm/lib/EffectScheduler.mjs +4 -2
  33. package/dist-esm/lib/EffectScheduler.mjs.map +2 -2
  34. package/dist-esm/lib/HistoryBuffer.mjs +8 -8
  35. package/dist-esm/lib/HistoryBuffer.mjs.map +2 -2
  36. package/dist-esm/lib/capture.mjs.map +2 -2
  37. package/dist-esm/lib/constants.mjs.map +2 -2
  38. package/dist-esm/lib/helpers.mjs +3 -11
  39. package/dist-esm/lib/helpers.mjs.map +2 -2
  40. package/dist-esm/lib/localStorageAtom.mjs +7 -2
  41. package/dist-esm/lib/localStorageAtom.mjs.map +2 -2
  42. package/dist-esm/lib/transactions.mjs +37 -49
  43. package/dist-esm/lib/transactions.mjs.map +2 -2
  44. package/dist-esm/lib/types.mjs.map +1 -1
  45. package/package.json +8 -2
  46. package/src/lib/ArraySet.ts +68 -176
  47. package/src/lib/Atom.ts +22 -27
  48. package/src/lib/Computed.ts +68 -95
  49. package/src/lib/EffectScheduler.ts +13 -9
  50. package/src/lib/HistoryBuffer.ts +12 -10
  51. package/src/lib/__tests__/ArraySet.test.ts +39 -13
  52. package/src/lib/__tests__/EffectScheduler.test.ts +69 -0
  53. package/src/lib/__tests__/HistoryBuffer.test.ts +6 -3
  54. package/src/lib/__tests__/computed.test.ts +75 -0
  55. package/src/lib/__tests__/deferAsyncEffects.test.ts +23 -0
  56. package/src/lib/__tests__/errors.test.ts +24 -0
  57. package/src/lib/__tests__/fuzz.tlstate.test.ts +97 -8
  58. package/src/lib/__tests__/helpers.test.ts +7 -11
  59. package/src/lib/__tests__/history.test.ts +32 -2
  60. package/src/lib/__tests__/localStorageAtom.test.ts +15 -0
  61. package/src/lib/__tests__/propagation.test.ts +104 -1
  62. package/src/lib/__tests__/transactions.test.ts +23 -0
  63. package/src/lib/capture.ts +12 -12
  64. package/src/lib/constants.ts +3 -22
  65. package/src/lib/helpers.ts +19 -139
  66. package/src/lib/localStorageAtom.ts +9 -2
  67. package/src/lib/transactions.ts +68 -98
  68. package/src/lib/types.ts +7 -7
@@ -1,281 +1,173 @@
1
1
  /**
2
- * The maximum number of items that can be stored in an ArraySet in array mode before switching to Set mode.
3
- *
4
- * @public
5
- * @example
6
- * ```ts
7
- * import { ARRAY_SIZE_THRESHOLD } from '@tldraw/state'
8
- *
9
- * console.log(ARRAY_SIZE_THRESHOLD) // 8
10
- * ```
2
+ * The number of items an ArraySet holds in array mode before switching to a Set.
3
+ * Exported only for tests.
4
+ * @internal
11
5
  */
12
6
  export const ARRAY_SIZE_THRESHOLD = 8
13
7
 
14
8
  /**
15
9
  * An ArraySet operates as an array until it reaches a certain size, after which a Set is used
16
10
  * instead. In either case, the same methods are used to get, set, remove, and visit the items.
11
+ *
12
+ * `set` and `array` are never both non-null. `set` being null means array mode, but the array
13
+ * itself is only allocated on the first `add` (most signals never get a child, and an empty
14
+ * ArraySet is created for every atom and effect, and two for every computed), so array-mode code
15
+ * must handle `array === null`; `arraySize` is 0 in that state. Once promoted to a set, an
16
+ * ArraySet never goes back.
17
17
  * @internal
18
18
  */
19
19
  export class ArraySet<T> {
20
- private arraySize = 0
20
+ private set: Set<T> | null = null
21
21
 
22
- private array: (T | undefined)[] | null = Array(ARRAY_SIZE_THRESHOLD)
22
+ // Slots [0, arraySize) hold the items; slots beyond are undefined. `add`/`has` scan the whole
23
+ // array with indexOf, which is why `clear` and `remove` must blank vacated slots.
24
+ private array: (T | undefined)[] | null = null
23
25
 
24
- private set: Set<T> | null = null
26
+ private arraySize = 0
25
27
 
26
28
  /**
27
29
  * Get whether this ArraySet has any elements.
28
- *
29
- * @returns True if this ArraySet has any elements, false otherwise.
30
30
  */
31
31
  // eslint-disable-next-line tldraw/no-setter-getter
32
32
  get isEmpty() {
33
- if (this.array) {
34
- return this.arraySize === 0
35
- }
36
-
37
33
  if (this.set) {
38
34
  return this.set.size === 0
39
35
  }
40
36
 
41
- throw new Error('no set or array')
37
+ return this.arraySize === 0
42
38
  }
43
39
 
44
40
  /**
45
41
  * Add an element to the ArraySet if it is not already present.
46
42
  *
47
- * @param elem - The element to add to the set
48
43
  * @returns `true` if the element was added, `false` if it was already present
49
- * @example
50
- * ```ts
51
- * const arraySet = new ArraySet<string>()
52
- *
53
- * console.log(arraySet.add('hello')) // true
54
- * console.log(arraySet.add('hello')) // false (already exists)
55
- * ```
56
44
  */
57
45
  add(elem: T) {
58
- if (this.array) {
59
- const idx = this.array.indexOf(elem)
60
-
61
- // Return false if the element is already in the array.
62
- if (idx !== -1) {
46
+ if (this.set) {
47
+ if (this.set.has(elem)) {
63
48
  return false
64
49
  }
65
50
 
66
- if (this.arraySize < ARRAY_SIZE_THRESHOLD) {
67
- // If the array is below the size threshold, push items into the array.
68
-
69
- // Insert the element into the array's next available slot.
70
- this.array[this.arraySize] = elem
71
- this.arraySize++
72
-
73
- return true
74
- } else {
75
- // If the array is full, convert it to a set and remove the array.
76
- this.set = new Set(this.array as any)
77
- this.array = null
78
- this.set.add(elem)
51
+ this.set.add(elem)
52
+ return true
53
+ }
79
54
 
80
- return true
81
- }
55
+ if (!this.array) {
56
+ this.array = Array(ARRAY_SIZE_THRESHOLD)
57
+ } else if (this.array.indexOf(elem) !== -1) {
58
+ return false
82
59
  }
83
60
 
84
- if (this.set) {
85
- // Return false if the element is already in the set.
86
- if (this.set.has(elem)) {
87
- return false
88
- }
61
+ if (this.arraySize < ARRAY_SIZE_THRESHOLD) {
62
+ this.array[this.arraySize] = elem
63
+ this.arraySize++
89
64
 
90
- this.set.add(elem)
91
65
  return true
92
66
  }
93
67
 
94
- throw new Error('no set or array')
68
+ // The array is full: promote to a set.
69
+ this.set = new Set(this.array as T[])
70
+ this.set.add(elem)
71
+ this.array = null
72
+ this.arraySize = 0
73
+
74
+ return true
95
75
  }
96
76
 
97
77
  /**
98
78
  * Remove an element from the ArraySet if it is present.
99
79
  *
100
- * @param elem - The element to remove from the set
101
80
  * @returns `true` if the element was removed, `false` if it was not present
102
- * @example
103
- * ```ts
104
- * const arraySet = new ArraySet<string>()
105
- * arraySet.add('hello')
106
- *
107
- * console.log(arraySet.remove('hello')) // true
108
- * console.log(arraySet.remove('hello')) // false (not present)
109
- * ```
110
81
  */
111
82
  remove(elem: T) {
112
- if (this.array) {
113
- const idx = this.array.indexOf(elem)
114
-
115
- // If the item is not in the array, return false.
116
- if (idx === -1) {
117
- return false
118
- }
83
+ if (this.set) {
84
+ return this.set.delete(elem)
85
+ }
119
86
 
120
- this.array[idx] = undefined
121
- this.arraySize--
87
+ if (!this.array) {
88
+ return false
89
+ }
122
90
 
123
- if (idx !== this.arraySize) {
124
- // If the item is not the last item in the array, move the last item into the
125
- // removed item's slot.
126
- this.array[idx] = this.array[this.arraySize]
127
- this.array[this.arraySize] = undefined
128
- }
91
+ const idx = this.array.indexOf(elem)
129
92
 
130
- return true
93
+ if (idx === -1) {
94
+ return false
131
95
  }
132
96
 
133
- if (this.set) {
134
- // If the item is not in the set, return false.
135
- if (!this.set.has(elem)) {
136
- return false
137
- }
97
+ this.arraySize--
138
98
 
139
- this.set.delete(elem)
99
+ // Move the last item into the vacated slot so the items stay dense.
100
+ this.array[idx] = this.array[this.arraySize]
101
+ this.array[this.arraySize] = undefined
140
102
 
141
- return true
142
- }
143
-
144
- throw new Error('no set or array')
103
+ return true
145
104
  }
146
105
 
147
106
  /**
148
107
  * Execute a callback function for each element in the ArraySet.
149
- *
150
- * @param visitor - A function to call for each element in the set
151
- * @example
152
- * ```ts
153
- * const arraySet = new ArraySet<string>()
154
- * arraySet.add('hello')
155
- * arraySet.add('world')
156
- *
157
- * arraySet.visit((item) => {
158
- * console.log(item) // 'hello', 'world'
159
- * })
160
- * ```
161
108
  */
162
109
  visit(visitor: (item: T) => void) {
163
- if (this.array) {
164
- for (let i = 0; i < this.arraySize; i++) {
165
- const elem = this.array[i]
166
-
167
- if (typeof elem !== 'undefined') {
168
- visitor(elem)
169
- }
170
- }
110
+ if (this.set) {
111
+ this.set.forEach(visitor)
171
112
 
172
113
  return
173
114
  }
174
115
 
175
- if (this.set) {
176
- this.set.forEach(visitor)
177
-
116
+ if (!this.array) {
178
117
  return
179
118
  }
180
119
 
181
- throw new Error('no set or array')
120
+ for (let i = 0; i < this.arraySize; i++) {
121
+ visitor(this.array[i]!)
122
+ }
182
123
  }
183
124
 
184
125
  /**
185
126
  * Make the ArraySet iterable, allowing it to be used in for...of loops and with spread syntax.
186
- *
187
- * @returns An iterator that yields each element in the set
188
- * @example
189
- * ```ts
190
- * const arraySet = new ArraySet<number>()
191
- * arraySet.add(1)
192
- * arraySet.add(2)
193
- *
194
- * for (const item of arraySet) {
195
- * console.log(item) // 1, 2
196
- * }
197
- *
198
- * const items = [...arraySet] // [1, 2]
199
- * ```
200
127
  */
201
128
  *[Symbol.iterator]() {
202
- if (this.array) {
129
+ if (this.set) {
130
+ yield* this.set
131
+ } else if (this.array) {
203
132
  for (let i = 0; i < this.arraySize; i++) {
204
- const elem = this.array[i]
205
-
206
- if (typeof elem !== 'undefined') {
207
- yield elem
208
- }
133
+ yield this.array[i]!
209
134
  }
210
- } else if (this.set) {
211
- yield* this.set
212
- } else {
213
- throw new Error('no set or array')
214
135
  }
215
136
  }
216
137
 
217
138
  /**
218
139
  * Check whether an element is present in the ArraySet.
219
- *
220
- * @param elem - The element to check for
221
- * @returns `true` if the element is present, `false` otherwise
222
- * @example
223
- * ```ts
224
- * const arraySet = new ArraySet<string>()
225
- * arraySet.add('hello')
226
- *
227
- * console.log(arraySet.has('hello')) // true
228
- * console.log(arraySet.has('world')) // false
229
- * ```
230
140
  */
231
141
  has(elem: T) {
232
- if (this.array) {
233
- return this.array.indexOf(elem) !== -1
234
- } else {
235
- return this.set!.has(elem)
142
+ if (this.set) {
143
+ return this.set.has(elem)
236
144
  }
145
+
146
+ return this.array ? this.array.indexOf(elem) !== -1 : false
237
147
  }
238
148
 
239
149
  /**
240
150
  * Remove all elements from the ArraySet.
241
- *
242
- * @example
243
- * ```ts
244
- * const arraySet = new ArraySet<string>()
245
- * arraySet.add('hello')
246
- * arraySet.add('world')
247
- *
248
- * arraySet.clear()
249
- * console.log(arraySet.size()) // 0
250
- * ```
251
151
  */
252
152
  clear() {
253
153
  if (this.set) {
254
154
  this.set.clear()
255
- } else {
155
+ } else if (this.array) {
156
+ // Blank the used slots in place rather than allocating a new array: this runs on every
157
+ // computed derive and effect run.
158
+ this.array.fill(undefined, 0, this.arraySize)
256
159
  this.arraySize = 0
257
- this.array = []
258
160
  }
259
161
  }
260
162
 
261
163
  /**
262
164
  * Get the number of elements in the ArraySet.
263
- *
264
- * @returns The number of elements in the set
265
- * @example
266
- * ```ts
267
- * const arraySet = new ArraySet<string>()
268
- * console.log(arraySet.size()) // 0
269
- *
270
- * arraySet.add('hello')
271
- * console.log(arraySet.size()) // 1
272
- * ```
273
165
  */
274
166
  size() {
275
167
  if (this.set) {
276
168
  return this.set.size
277
- } else {
278
- return this.arraySize
279
169
  }
170
+
171
+ return this.arraySize
280
172
  }
281
173
  }
package/src/lib/Atom.ts CHANGED
@@ -13,7 +13,7 @@ export interface AtomOptions<Value, Diff> {
13
13
  /**
14
14
  * The maximum number of diffs to keep in the history buffer.
15
15
  *
16
- * If you don't need to compute diffs, or if you will supply diffs manually via {@link Atom.set}, you can leave this as `undefined` and no history buffer will be created.
16
+ * If you don't need diffs, leave this as `undefined` and no history buffer will be created. Diffs passed to {@link Atom.set} or produced by {@link AtomOptions.computeDiff} are only recorded when this is set.
17
17
  *
18
18
  * If you expect the value to be part of an active effect subscription all the time, and to not change multiple times inside of a single transaction, you can set this to a relatively low number (e.g. 10).
19
19
  *
@@ -87,34 +87,19 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
87
87
  this.computeDiff = options.computeDiff
88
88
  }
89
89
 
90
- /**
91
- * Custom equality function for comparing values, or null to use default equality.
92
- * @internal
93
- */
90
+ /** @internal */
94
91
  readonly isEqual: null | ((a: any, b: any) => boolean)
95
92
 
96
- /**
97
- * Optional function to compute diffs between old and new values.
98
- * @internal
99
- */
93
+ /** @internal */
100
94
  computeDiff?: ComputeDiff<Value, Diff>
101
95
 
102
- /**
103
- * The global epoch when this atom was last changed.
104
- * @internal
105
- */
96
+ /** @internal */
106
97
  lastChangedEpoch = getGlobalEpoch()
107
98
 
108
- /**
109
- * Set of child signals that depend on this atom.
110
- * @internal
111
- */
99
+ /** @internal */
112
100
  children = new ArraySet<Child>()
113
101
 
114
- /**
115
- * Optional history buffer for tracking changes over time.
116
- * @internal
117
- */
102
+ /** @internal */
118
103
  historyBuffer?: HistoryBuffer<Diff>
119
104
 
120
105
  /**
@@ -163,6 +148,21 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
163
148
  return this.current
164
149
  }
165
150
 
151
+ // `computeDiff` is user code: run it before ticking the epoch, so that any signal it reads is
152
+ // checked against the epoch this write has not yet happened in. Reading a dependent computed
153
+ // after the tick would stamp it as checked at the new epoch while the atom was still being
154
+ // written, and it would then never see the change. Only `undefined` means "no diff
155
+ // supplied"; `null` can be a legitimate diff.
156
+ let historyDiff: Diff | RESET_VALUE | undefined
157
+ if (this.historyBuffer) {
158
+ historyDiff =
159
+ diff !== undefined
160
+ ? diff
161
+ : this.computeDiff
162
+ ? this.computeDiff(this.current, value, this.lastChangedEpoch, getGlobalEpoch() + 1)
163
+ : RESET_VALUE
164
+ }
165
+
166
166
  // Tick forward the global epoch. This write belongs to that one epoch, so read it once and
167
167
  // use it everywhere below — otherwise a `computeDiff` that touches other atoms could leave
168
168
  // the history entry and `lastChangedEpoch` disagreeing.
@@ -171,11 +171,7 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
171
171
 
172
172
  // Add the diff to the history buffer.
173
173
  if (this.historyBuffer) {
174
- this.historyBuffer.pushEntry(
175
- this.lastChangedEpoch,
176
- epoch,
177
- diff ?? this.computeDiff?.(this.current, value, this.lastChangedEpoch, epoch) ?? RESET_VALUE
178
- )
174
+ this.historyBuffer.pushEntry(this.lastChangedEpoch, epoch, historyDiff)
179
175
  }
180
176
 
181
177
  // Update the atom's record of the epoch when last changed.
@@ -216,7 +212,6 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
216
212
  getDiffSince(epoch: number): RESET_VALUE | Diff[] {
217
213
  maybeCaptureParent(this)
218
214
 
219
- // If no changes have occurred since the given epoch, return an empty array.
220
215
  if (epoch >= this.lastChangedEpoch) {
221
216
  return EMPTY_ARRAY
222
217
  }