@formvk/reactive 0.1.0 → 1.0.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # @formvk/reactive
2
+
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - 65c066c: 添加readme.md文档
package/README.md ADDED
@@ -0,0 +1,94 @@
1
+ # @formvk/reactive
2
+
3
+ Reactive runtime built on `@vue/reactivity`. On top of Vue reactivity it adds observable change tracking with paths (`observe`), scheduling (`batch` / `action`), and standard-decorator support (`@observable`, `@computed`, `@shallowRef`).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @formvk/reactive
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ `observable` creates an object whose writes are reported to `observe` with a change path:
14
+
15
+ ```ts
16
+ import { observable, observe } from '@formvk/reactive'
17
+
18
+ const state = observable({ count: 0, step: 1 })
19
+
20
+ const dispose = observe(state, change => {
21
+ console.log(change.path, change.value)
22
+ })
23
+
24
+ state.count += state.step
25
+ dispose()
26
+ ```
27
+
28
+ Use `reactive` / `shallowRef` / `shallow` with `autorun` when you only need dependency tracking:
29
+
30
+ ```ts
31
+ import { autorun, reactive } from '@formvk/reactive'
32
+
33
+ const state = reactive({ count: 0 })
34
+
35
+ const stop = autorun(() => {
36
+ console.log(state.count)
37
+ })
38
+
39
+ state.count++
40
+ stop()
41
+ ```
42
+
43
+ Decorators (TypeScript 5 standard decorators):
44
+
45
+ ```ts
46
+ import { computed, observable, shallowRef } from '@formvk/reactive'
47
+
48
+ class Counter {
49
+ @observable accessor count = 0
50
+
51
+ @shallowRef accessor items: string[] = []
52
+
53
+ @computed get doubled() {
54
+ return this.count * 2
55
+ }
56
+ }
57
+ ```
58
+
59
+ Batch and action group writes so reactions run once:
60
+
61
+ ```ts
62
+ import { action, batch, reactive } from '@formvk/reactive'
63
+
64
+ const state = reactive({ a: 0, b: 0 })
65
+
66
+ batch(() => {
67
+ state.a = 1
68
+ state.b = 2
69
+ })
70
+
71
+ const update = action(() => {
72
+ state.a += 1
73
+ })
74
+ update()
75
+ ```
76
+
77
+ ## API
78
+
79
+ - **Reactive sources** — `observable` (trackable by `observe`), `reactive`, `shallow`, `shallowRef`, `computed`.
80
+ - **Observation** — `observe`, `autorun`, `reaction`, `Tracker`.
81
+ - **Scheduling** — `batch`, `batch.scope`, `batch.endpoint`, `action`, `action.scope`, `untracked`.
82
+ - **Interop** — `toJS`, `contains`, `isObservable`, `isReactive`, `registerSkip`.
83
+ - **Types** — `IChange`, `Observer`, `DataChange`, `Dispose`, `IReactionOptions`, `Boundary`, `IAction`, `IBatch`.
84
+
85
+ Only objects created with `observable()` can be passed to `observe`; `reactive`, `shallow`, `shallowRef` and `computed` are plain Vue reactivity and should be watched with `autorun` / `reaction`.
86
+
87
+ ## Documentation
88
+
89
+ - Reactivity guide: https://formvk.github.io/core/guide/reactivity
90
+ - React bindings: https://formvk.github.io/core/api/react
91
+
92
+ ## License
93
+
94
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@formvk/reactive",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Formvk Shared",
5
5
  "keywords": [
6
6
  "form",
@@ -10,12 +10,16 @@
10
10
  ],
11
11
  "license": "MIT",
12
12
  "author": "yiyunwan",
13
+ "files": [
14
+ "dist",
15
+ "CHANGELOG.md"
16
+ ],
13
17
  "type": "module",
14
18
  "main": "dist/index.js",
15
19
  "module": "dist/index.js",
16
20
  "types": "dist/index.d.ts",
17
21
  "dependencies": {
18
- "@vue/reactivity": "3.6.0-rc.12"
22
+ "@vue/reactivity": "^3.6.0-rc.15"
19
23
  },
20
24
  "scripts": {
21
25
  "build": "tsc --noEmit && vite build",
@@ -1,177 +0,0 @@
1
- import { expect, test, vi } from 'vitest'
2
-
3
- import { autorun, reaction } from '../autorun'
4
- import { reactive } from '../reactive'
5
-
6
- test('autorun 立即执行并追踪依赖', () => {
7
- const state = reactive({ count: 0 })
8
- const values: number[] = []
9
-
10
- const dispose = autorun(() => {
11
- values.push(state.count)
12
- })
13
-
14
- expect(values).toEqual([0])
15
- state.count = 1
16
- expect(values).toEqual([0, 1])
17
- state.count = 2
18
- expect(values).toEqual([0, 1, 2])
19
-
20
- dispose()
21
- state.count = 3
22
- expect(values).toEqual([0, 1, 2])
23
- })
24
-
25
- test('autorun 只追踪实际读取的依赖', () => {
26
- const state = reactive({ a: 1, b: 1 })
27
- const values: number[] = []
28
-
29
- autorun(() => {
30
- values.push(state.a)
31
- })
32
-
33
- state.b = 2
34
- expect(values).toEqual([1])
35
- state.a = 2
36
- expect(values).toEqual([1, 2])
37
- })
38
-
39
- test('autorun 追踪嵌套属性', () => {
40
- const state = reactive({ nested: { value: 1 } })
41
- const values: number[] = []
42
-
43
- autorun(() => {
44
- values.push(state.nested.value)
45
- })
46
-
47
- state.nested.value = 2
48
- expect(values).toEqual([1, 2])
49
- })
50
-
51
- test('autorun 支持嵌套调用', () => {
52
- const state = reactive({ outer: 0, inner: 0 })
53
- const values: string[] = []
54
-
55
- autorun(() => {
56
- values.push(`outer:${state.outer}`)
57
- autorun(() => {
58
- values.push(`inner:${state.inner}`)
59
- })
60
- })
61
-
62
- expect(values).toEqual(['outer:0', 'inner:0'])
63
- state.inner = 1
64
- expect(values).toEqual(['outer:0', 'inner:0', 'inner:1'])
65
- })
66
-
67
- test('reaction 首次只执行 tracker', () => {
68
- const state = reactive({ count: 0 })
69
- const tracker = vi.fn(() => state.count)
70
- const subscriber = vi.fn()
71
-
72
- reaction(tracker, subscriber)
73
-
74
- expect(tracker).toHaveBeenCalledTimes(1)
75
- expect(subscriber).not.toHaveBeenCalled()
76
- })
77
-
78
- test('reaction 值变化时触发 subscriber', () => {
79
- const state = reactive({ count: 0 })
80
- const calls: Array<[number, number]> = []
81
-
82
- reaction(
83
- () => state.count,
84
- (value, oldValue) => {
85
- calls.push([value, oldValue])
86
- }
87
- )
88
-
89
- state.count = 1
90
- state.count = 2
91
- expect(calls).toEqual([
92
- [1, 0],
93
- [2, 1],
94
- ])
95
- })
96
-
97
- test('reaction 值未变化不触发 subscriber', () => {
98
- const state = reactive({ count: 0 })
99
- const subscriber = vi.fn()
100
-
101
- reaction(() => state.count > 10, subscriber)
102
-
103
- state.count = 20
104
- expect(subscriber).toHaveBeenCalledTimes(1)
105
- state.count = 30
106
- expect(subscriber).toHaveBeenCalledTimes(1)
107
- state.count = 5
108
- expect(subscriber).toHaveBeenCalledTimes(2)
109
- })
110
-
111
- test('reaction 支持自定义 equals', () => {
112
- const state = reactive({ count: 0 })
113
- const subscriber = vi.fn()
114
-
115
- reaction(() => ({ positive: state.count > 0 }), subscriber, {
116
- equals: (oldValue, newValue) => oldValue.positive === newValue.positive,
117
- })
118
-
119
- state.count = 1
120
- expect(subscriber).toHaveBeenCalledTimes(1)
121
- state.count = 2
122
- expect(subscriber).toHaveBeenCalledTimes(1)
123
- state.count = -1
124
- expect(subscriber).toHaveBeenCalledTimes(2)
125
- })
126
-
127
- test('reaction 支持 fireImmediately', () => {
128
- const state = reactive({ count: 0 })
129
- const subscriber = vi.fn()
130
-
131
- reaction(() => state.count, subscriber, { fireImmediately: true })
132
-
133
- expect(subscriber).toHaveBeenCalledWith(0, 0)
134
- state.count = 1
135
- expect(subscriber).toHaveBeenCalledWith(1, 0)
136
- expect(subscriber).toHaveBeenCalledTimes(2)
137
- })
138
-
139
- test('reaction 不收集 subscriber 中的依赖', () => {
140
- const state = reactive({ count: 0, other: 0 })
141
- const tracker = vi.fn(() => state.count)
142
- const subscriber = vi.fn(() => state.other)
143
-
144
- reaction(tracker, subscriber)
145
-
146
- state.other = 1
147
- expect(tracker).toHaveBeenCalledTimes(1)
148
- expect(subscriber).not.toHaveBeenCalled()
149
-
150
- state.count = 1
151
- expect(tracker).toHaveBeenCalledTimes(2)
152
- expect(subscriber).toHaveBeenCalledTimes(1)
153
- })
154
-
155
- test('reaction dispose 后不再响应', () => {
156
- const state = reactive({ count: 0 })
157
- const subscriber = vi.fn()
158
-
159
- const dispose = reaction(() => state.count, subscriber)
160
- dispose()
161
-
162
- state.count = 1
163
- expect(subscriber).not.toHaveBeenCalled()
164
- })
165
-
166
- test('reaction 不传 subscriber 时变化只重跑 tracker,不抛错', () => {
167
- const state = reactive({ count: 0 })
168
- const tracker = vi.fn(() => state.count)
169
-
170
- const dispose = reaction(tracker)
171
- expect(tracker).toHaveBeenCalledTimes(1)
172
-
173
- state.count = 1
174
- expect(tracker).toHaveBeenCalledTimes(2)
175
-
176
- dispose()
177
- })
@@ -1,325 +0,0 @@
1
- import { expect, test, vi } from 'vitest'
2
-
3
- import { action } from '../action'
4
- import { autorun, reaction } from '../autorun'
5
- import { batch } from '../batch'
6
- import { reactive } from '../reactive'
7
-
8
- test('batch 合并批次内的多次写入', () => {
9
- const state = reactive({ count: 0 })
10
- const handler = vi.fn()
11
-
12
- autorun(() => {
13
- handler(state.count)
14
- })
15
-
16
- state.count = 1
17
- state.count = 2
18
- expect(handler).toHaveBeenCalledTimes(3)
19
-
20
- batch(() => {
21
- state.count = 3
22
- state.count = 4
23
- })
24
- expect(handler).toHaveBeenCalledTimes(4)
25
- expect(handler).toHaveBeenLastCalledWith(4)
26
- })
27
-
28
- test('嵌套 batch 只在最外层结束时刷新', () => {
29
- const state = reactive({ count: 0 })
30
- const handler = vi.fn()
31
-
32
- autorun(() => {
33
- handler(state.count)
34
- })
35
-
36
- batch(() => {
37
- state.count = 1
38
- batch(() => {
39
- state.count = 2
40
- })
41
- expect(handler).toHaveBeenCalledTimes(1)
42
- state.count = 3
43
- expect(handler).toHaveBeenCalledTimes(1)
44
- })
45
-
46
- expect(handler).toHaveBeenCalledTimes(2)
47
- expect(handler).toHaveBeenLastCalledWith(3)
48
- })
49
-
50
- test('batch 回调抛错后仍能正常结束', () => {
51
- const state = reactive({ count: 0 })
52
- const handler = vi.fn()
53
-
54
- autorun(() => {
55
- handler(state.count)
56
- })
57
-
58
- expect(() =>
59
- batch(() => {
60
- throw new Error('boom')
61
- })
62
- ).toThrow('boom')
63
-
64
- state.count = 1
65
- expect(handler).toHaveBeenCalledTimes(2)
66
- })
67
-
68
- test('batch.bound', () => {
69
- const state = reactive({ count: 0 })
70
- const handler = vi.fn()
71
- const context = { step: 10 }
72
-
73
- autorun(() => {
74
- handler(state.count)
75
- })
76
-
77
- const update = batch.bound(function (this: typeof context, delta: number) {
78
- state.count += delta * this.step
79
- state.count += 1
80
- }, context)
81
-
82
- update(2)
83
- expect(handler).toHaveBeenCalledTimes(2)
84
- expect(handler).toHaveBeenLastCalledWith(21)
85
- })
86
-
87
- test('batch.endpoint 在批次结束时执行', () => {
88
- const calls: string[] = []
89
-
90
- batch.endpoint(() => calls.push('immediate'))
91
- expect(calls).toEqual(['immediate'])
92
-
93
- batch(() => {
94
- batch.endpoint(() => calls.push('deferred'))
95
- expect(calls).toEqual(['immediate'])
96
- })
97
- expect(calls).toEqual(['immediate', 'deferred'])
98
- })
99
-
100
- test('batch.scope 在外层 batch 结束前刷新', () => {
101
- const state = reactive({ count: 0 })
102
- const handler = vi.fn()
103
-
104
- autorun(() => {
105
- handler(state.count)
106
- })
107
-
108
- batch(() => {
109
- state.count = 1
110
- batch.scope(() => {
111
- state.count = 2
112
- })
113
- expect(handler).toHaveBeenCalledTimes(2)
114
- expect(handler).toHaveBeenLastCalledWith(2)
115
- state.count = 3
116
- expect(handler).toHaveBeenCalledTimes(2)
117
- })
118
-
119
- expect(handler).toHaveBeenCalledTimes(3)
120
- expect(handler).toHaveBeenLastCalledWith(3)
121
- })
122
-
123
- test('batch 中的 reaction 只触发一次', () => {
124
- const state = reactive({ count: 0 })
125
- const subscriber = vi.fn()
126
-
127
- reaction(() => state.count, subscriber)
128
-
129
- batch(() => {
130
- state.count = 1
131
- state.count = 2
132
- })
133
-
134
- expect(subscriber).toHaveBeenCalledTimes(1)
135
- expect(subscriber).toHaveBeenCalledWith(2, 0)
136
- })
137
-
138
- test('action 合并通知并阻止依赖收集', () => {
139
- const state = reactive({ a: 0, b: 0 })
140
- const handler = vi.fn()
141
-
142
- autorun(() => {
143
- handler(state.a)
144
- action(() => state.b)
145
- })
146
-
147
- expect(handler).toHaveBeenCalledTimes(1)
148
-
149
- state.b = 1
150
- expect(handler).toHaveBeenCalledTimes(1)
151
-
152
- action(() => {
153
- state.a = 1
154
- state.a = 2
155
- })
156
- expect(handler).toHaveBeenCalledTimes(2)
157
- expect(handler).toHaveBeenLastCalledWith(2)
158
- })
159
-
160
- test('action.bound', () => {
161
- const state = reactive({ count: 0 })
162
- const handler = vi.fn()
163
- const context = { step: 5 }
164
-
165
- autorun(() => {
166
- handler(state.count)
167
- })
168
-
169
- const update = action.bound(function (this: typeof context, delta: number) {
170
- state.count += delta * this.step
171
- state.count += 1
172
- }, context)
173
-
174
- update(1)
175
- expect(handler).toHaveBeenCalledTimes(2)
176
- expect(handler).toHaveBeenLastCalledWith(6)
177
- })
178
-
179
- test('action.scope', () => {
180
- const state = reactive({ count: 0 })
181
- const handler = vi.fn()
182
-
183
- autorun(() => {
184
- handler(state.count)
185
- })
186
-
187
- action.scope(() => {
188
- state.count = 1
189
- state.count = 2
190
- })
191
-
192
- expect(handler).toHaveBeenCalledTimes(2)
193
- expect(handler).toHaveBeenLastCalledWith(2)
194
- })
195
-
196
- test('batch 方法装饰器合并写入', () => {
197
- const state = reactive({ count: 0 })
198
- const handler = vi.fn()
199
-
200
- autorun(() => {
201
- handler(state.count)
202
- })
203
-
204
- class Store {
205
- @batch
206
- update() {
207
- state.count = 1
208
- state.count = 2
209
- return state.count
210
- }
211
- }
212
-
213
- const store = new Store()
214
- expect(store.update()).toBe(2)
215
- expect(handler).toHaveBeenCalledTimes(2)
216
- expect(handler).toHaveBeenLastCalledWith(2)
217
- })
218
-
219
- test('batch 字段装饰器包装箭头函数', () => {
220
- const state = reactive({ count: 0 })
221
- const handler = vi.fn()
222
-
223
- autorun(() => {
224
- handler(state.count)
225
- })
226
-
227
- class Store {
228
- @batch
229
- update = () => {
230
- state.count = 1
231
- state.count = 2
232
- }
233
- }
234
-
235
- new Store().update()
236
- expect(handler).toHaveBeenCalledTimes(2)
237
- expect(handler).toHaveBeenLastCalledWith(2)
238
- })
239
-
240
- test('batch.scope 方法装饰器在外层 batch 结束前刷新', () => {
241
- const state = reactive({ count: 0 })
242
- const handler = vi.fn()
243
-
244
- autorun(() => {
245
- handler(state.count)
246
- })
247
-
248
- class Store {
249
- @batch.scope
250
- update() {
251
- state.count = 1
252
- state.count = 2
253
- }
254
- }
255
-
256
- const store = new Store()
257
-
258
- batch(() => {
259
- store.update()
260
- expect(handler).toHaveBeenCalledTimes(2)
261
- expect(handler).toHaveBeenLastCalledWith(2)
262
- })
263
-
264
- expect(handler).toHaveBeenCalledTimes(2)
265
- })
266
-
267
- test('batch 无回调调用也能正常进出批次', () => {
268
- expect(() => batch()).not.toThrow()
269
- })
270
-
271
- test('batch.endpoint 收到非函数入参时静默忽略', () => {
272
- expect(() => (batch.endpoint as any)(undefined)).not.toThrow()
273
- expect(() => (batch.endpoint as any)(123)).not.toThrow()
274
- })
275
-
276
- test('batch 字段装饰器修饰非函数字段时原值透传', () => {
277
- class Store {
278
- @batch flag = true
279
- @batch name = 'store'
280
- }
281
-
282
- const store = new Store()
283
- expect(store.flag).toBe(true)
284
- expect(store.name).toBe('store')
285
- })
286
-
287
- test('batch 收到非函数回调与非 field 装饰器上下文时原样返回', () => {
288
- const raw = { mark: 'x' }
289
-
290
- expect((batch as any)(raw, { kind: 'method' })).toBe(raw)
291
- })
292
-
293
- test('action 方法装饰器合并通知并阻止依赖收集', () => {
294
- const state = reactive({ a: 0, b: 0 })
295
- const handler = vi.fn()
296
-
297
- class Store {
298
- @action
299
- peek() {
300
- return state.b
301
- }
302
-
303
- @action
304
- update() {
305
- state.a = 1
306
- state.a = 2
307
- }
308
- }
309
-
310
- const store = new Store()
311
-
312
- autorun(() => {
313
- handler(state.a)
314
- store.peek()
315
- })
316
-
317
- expect(handler).toHaveBeenCalledTimes(1)
318
-
319
- state.b = 1
320
- expect(handler).toHaveBeenCalledTimes(1)
321
-
322
- store.update()
323
- expect(handler).toHaveBeenCalledTimes(2)
324
- expect(handler).toHaveBeenLastCalledWith(2)
325
- })