@formvk/path 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/path
2
+
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - 65c066c: 添加readme.md文档
package/README.md ADDED
@@ -0,0 +1,50 @@
1
+ # @formvk/path
2
+
3
+ Path parsing and data access utilities used by Formvk to address fields. Supports dot paths, array indices, wildcard match patterns, relative paths and reusable matchers.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @formvk/path
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { Path } from '@formvk/path'
15
+
16
+ const values = { user: { name: 'alice' } }
17
+
18
+ Path.getIn(values, 'user.name') // 'alice'
19
+ Path.setIn(values, 'user.name', 'bob')
20
+ Path.existIn(values, 'user.name') // true
21
+ Path.deleteIn(values, 'user.name')
22
+
23
+ new Path('user.*').match('user.name') // true
24
+ new Path('user.name').includes('user') // true
25
+ Path.transform('user.name', /name/, key => key.toUpperCase()) // 'NAME'
26
+ ```
27
+
28
+ `Path.match` creates a matcher that can be passed to `Form.query`:
29
+
30
+ ```ts
31
+ form.query(Path.match('user.*')).forEach(field => {
32
+ field.setPattern('disabled')
33
+ })
34
+ ```
35
+
36
+ ## API
37
+
38
+ - **Instance** — `segments`, `entire`, `length`, `toString`, `toArr`, `concat`, `push`, `slice`, `pop`, `splice`, `parent`, `forEach`, `map`, `reduce`, `includes`, `match`, `matchAliasGroup`, `transform`, `getIn`, `setIn`, `deleteIn`, `existIn`, `ensureIn`.
39
+ - **Static** — `Path.parse`, `Path.getIn`, `Path.setIn`, `Path.deleteIn`, `Path.existIn`, `Path.ensureIn`, `Path.match`, `Path.transform`, `Path.isPathPattern`.
40
+ - **Types** — `Pattern`, `MatcherFunction`.
41
+
42
+ `@formvk/shared` re-exports the class as `FormPath` together with the `FormPathPattern` type.
43
+
44
+ ## Documentation
45
+
46
+ https://formvk.github.io/core/api/core
47
+
48
+ ## License
49
+
50
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@formvk/path",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Formvk Path",
5
5
  "keywords": [
6
6
  "form",
@@ -10,6 +10,10 @@
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",
@@ -1,429 +0,0 @@
1
- import { expect, test } from 'vitest'
2
-
3
- import { Path } from '..'
4
-
5
- const { getIn, setIn } = Path
6
-
7
- test('test getIn null parent', () => {
8
- const value = { aa: null }
9
- expect(getIn(value, 'aa')).toEqual(null)
10
- expect(getIn(value, 'aa.bb.cc')).toEqual(undefined)
11
- })
12
-
13
- test('test getIn and setIn', () => {
14
- const value = { a: { b: { c: 2, d: 333 } } }
15
- expect(getIn(value, 'a.b.c')).toEqual(2)
16
- setIn(value, 'a.b.c', 1111)
17
- expect(getIn(value, 'a.b.c')).toEqual(1111)
18
- })
19
-
20
- test('test getIn with destructor', () => {
21
- const value = { array: [{ aa: 123, bb: 321 }] }
22
- expect(getIn(value, 'array.0.[aa,bb]')).toEqual([123, 321])
23
- })
24
-
25
- test('test setIn auto create array', () => {
26
- const value = { array: null }
27
- setIn(value, 'array[0].bb[2]', 'hello world')
28
- expect(value).toEqual({
29
- array: [
30
- {
31
- bb: [undefined, undefined, 'hello world'],
32
- },
33
- ],
34
- })
35
- expect(getIn(undefined, 'aa.bb.cc')).toEqual(undefined)
36
- setIn(undefined, 'aa.bb.cc', 123)
37
- })
38
-
39
- test('map', () => {
40
- const value = { map: new Map() }
41
- setIn(value, 'map.aa.bb.cc', 123)
42
- expect(getIn(value, 'map.aa.bb.cc')).toEqual(123)
43
- })
44
-
45
- test('test setIn array properties', () => {
46
- const value = { array: [] }
47
- setIn(value, 'array.xxx', 'hello world')
48
- expect(value).toEqual({ array: [] })
49
- })
50
-
51
- test('test setIn dose not affect other items', () => {
52
- const value = {
53
- aa: [
54
- {
55
- dd: [
56
- {
57
- ee: '是',
58
- },
59
- ],
60
- cc: '1111',
61
- },
62
- ],
63
- }
64
-
65
- setIn(value, 'aa.1.dd.0.ee', '否')
66
- expect(value.aa[0]).toEqual({
67
- dd: [
68
- {
69
- ee: '是',
70
- },
71
- ],
72
- cc: '1111',
73
- })
74
- })
75
-
76
- test('destruct getIn', () => {
77
- // getIn 通过解构表达式从扁平数据转为复合嵌套数据
78
- const value = { a: { b: { c: 2, d: 333 } } }
79
- expect(getIn({ a: { b: { kk: 2, mm: 333 } } }, 'a.b.{c:kk,d:mm}')).toEqual({
80
- c: 2,
81
- d: 333,
82
- })
83
-
84
- expect(
85
- getIn(
86
- { kk: 2, mm: 333 },
87
- `{
88
- a : {
89
- b : {
90
- c : kk,
91
- d : mm
92
- }
93
- }
94
- }`
95
- )
96
- ).toEqual(value)
97
- expect(getIn({ bb: undefined, dd: undefined }, `[{aa:bb,cc:dd}]`)).toEqual([])
98
- expect(
99
- getIn(
100
- { kk: undefined, mm: undefined },
101
- `{
102
- a : {
103
- b : {
104
- c : kk,
105
- d : mm
106
- }
107
- }
108
- }`
109
- )
110
- ).toEqual({})
111
- })
112
-
113
- test('destruct setIn', () => {
114
- const value = { a: { b: { c: 2, d: 333 } } }
115
- // setIn 从复杂嵌套结构中解构数据出来对其做赋值处理
116
- expect(
117
- setIn(
118
- {},
119
- `{
120
- a : {
121
- b : {
122
- c,
123
- d
124
- }
125
- }
126
- }`,
127
- value
128
- )
129
- ).toEqual({ c: 2, d: 333 })
130
-
131
- expect(
132
- setIn(
133
- {},
134
- `
135
- [aa,bb]
136
- `,
137
- [123, 444]
138
- )
139
- ).toEqual({ aa: 123, bb: 444 })
140
- expect(setIn({}, 'aa.bb.ddd.[aa,bb]', [123, 444])).toEqual({
141
- aa: { bb: { ddd: { aa: 123, bb: 444 } } },
142
- })
143
-
144
- expect(setIn({}, 'aa.bb.ddd.[{cc:aa,bb}]', [{ cc: 123, bb: 444 }])).toEqual({
145
- aa: { bb: { ddd: { aa: 123, bb: 444 } } },
146
- })
147
- })
148
-
149
- test('setIn with a.b.c.{aaa,bbb}', () => {
150
- expect(Path.setIn({}, 'a.b.c.{aaa,bbb}', { aaa: 123, bbb: 321 })).toEqual({
151
- a: { b: { c: { aaa: 123, bbb: 321 } } },
152
- })
153
- })
154
-
155
- test('getIn with a.b.c.{aaa,bbb}', () => {
156
- expect(Path.getIn({ a: { b: { c: { aaa: 123, bbb: 321 } } } }, 'a.b.c.{aaa,bbb}')).toEqual({ aaa: 123, bbb: 321 })
157
- })
158
-
159
- test('setIn with a.b.c.{aaa,bbb} source has extra property', () => {
160
- expect(
161
- Path.setIn({ a: { b: { c: { kkk: 'ddd' } } } }, 'a.b.c.{aaa,bbb}', {
162
- aaa: 123,
163
- bbb: 321,
164
- })
165
- ).toEqual({ a: { b: { c: { aaa: 123, bbb: 321, kkk: 'ddd' } } } })
166
- })
167
-
168
- test('getIn with a.b.c.{aaa,bbb} source has extra property', () => {
169
- expect(Path.getIn({ a: { b: { c: { aaa: 123, bbb: 321, kkk: 'ddd' } } } }, 'a.b.c.{aaa,bbb}')).toEqual({
170
- aaa: 123,
171
- bbb: 321,
172
- })
173
- })
174
-
175
- test('setIn with a.b.c.{aaa:ooo,bbb}', () => {
176
- expect(
177
- Path.setIn({ a: { b: { c: { kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb}', {
178
- aaa: 123,
179
- bbb: 321,
180
- })
181
- ).toEqual({ a: { b: { c: { ooo: 123, bbb: 321, kkk: 'ddd' } } } })
182
- })
183
-
184
- test('getIn with a.b.c.{aaa:ooo,bbb}', () => {
185
- expect(Path.getIn({ a: { b: { c: { ooo: 123, bbb: 321, kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb}')).toEqual({
186
- aaa: 123,
187
- bbb: 321,
188
- })
189
- })
190
-
191
- test('setIn with a.b.c.[aaa,bbb]', () => {
192
- expect(Path.setIn({}, 'a.b.c.[aaa,bbb]', [123, 321])).toEqual({
193
- a: { b: { c: { aaa: 123, bbb: 321 } } },
194
- })
195
- })
196
-
197
- test('getIn with a.b.c.[aaa,bbb]', () => {
198
- expect(Path.getIn({ a: { b: { c: { aaa: 123, bbb: 321 } } } }, 'a.b.c.[aaa,bbb]')).toEqual([123, 321])
199
- })
200
-
201
- test('setIn with a.b.c.[aaa,bbb] source has extra property', () => {
202
- expect(Path.setIn({ a: { b: { c: { kkk: 'ddd' } } } }, 'a.b.c.[aaa,bbb]', [123, 321])).toEqual({
203
- a: { b: { c: { aaa: 123, bbb: 321, kkk: 'ddd' } } },
204
- })
205
- })
206
-
207
- test('getIn with a.b.c.[aaa,bbb] source has extra property', () => {
208
- expect(Path.getIn({ a: { b: { c: { aaa: 123, bbb: 321, kkk: 'ddd' } } } }, 'a.b.c.[aaa,bbb]')).toEqual([123, 321])
209
- })
210
-
211
- test('setIn with a.b.c.[{ddd,kkk:mmm},bbb]', () => {
212
- expect(Path.setIn({}, 'a.b.c.[{ddd,kkk:mmm},bbb]', [{ ddd: 123, kkk: 'hhh' }, 321])).toEqual({
213
- a: { b: { c: { ddd: 123, bbb: 321, mmm: 'hhh' } } },
214
- })
215
- })
216
-
217
- test('getIn with a.b.c.[{ddd,kkk:mmm},bbb]', () => {
218
- expect(Path.getIn({ a: { b: { c: { ddd: 123, bbb: 321, mmm: 'hhh' } } } }, 'a.b.c.[{ddd,kkk:mmm},bbb]')).toEqual([
219
- { ddd: 123, kkk: 'hhh' },
220
- 321,
221
- ])
222
- })
223
-
224
- test('setIn with a.b.c.{aaa:ooo,bbb:[ccc,ddd]}', () => {
225
- expect(
226
- Path.setIn({ a: { b: { c: { kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb:[ccc,ddd]}', { aaa: 123, bbb: [123, 321] })
227
- ).toEqual({ a: { b: { c: { ooo: 123, ccc: 123, ddd: 321, kkk: 'ddd' } } } })
228
- })
229
-
230
- test('getIn with a.b.c.{aaa:ooo,bbb:[ccc,ddd]}', () => {
231
- expect(
232
- Path.getIn({ a: { b: { c: { ooo: 123, ccc: 123, ddd: 321, kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb:[ccc,ddd]}')
233
- ).toEqual({ aaa: 123, bbb: [123, 321] })
234
- })
235
-
236
- test('existIn with a.b.c', () => {
237
- expect(Path.existIn({ a: { b: { c: 123123 } } }, 'a.b.c')).toEqual(true)
238
- expect(Path.existIn({ a: { b: { c: 123123 } } }, 'a.b.c.d')).toEqual(false)
239
- expect(Path.existIn({ a: 123 }, 'a.b.c.d')).toEqual(false)
240
- expect(
241
- Path.existIn({ a: { b: { c: { ooo: 123, ccc: 123, ddd: 321, kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb:[ccc,ddd]}')
242
- ).toEqual(true)
243
- expect(
244
- Path.existIn({ a: { b: { c: { ooo: 123, ccc: 123, kkk: 'ddd' } } } }, 'a.b.c.{aaa:ooo,bbb:[ccc,ddd]}')
245
- ).toEqual(false)
246
- expect(Path.existIn({ a: [{}] }, 'a.0')).toEqual(true)
247
- })
248
-
249
- test('existIn with start Path', () => {
250
- expect(Path.existIn({ a: [{}] }, 'a.0', Path.parse('a'))).toEqual(false)
251
- expect(Path.existIn({ a: [{}] }, 'b.a.0', Path.parse('b'))).toEqual(true)
252
- })
253
-
254
- test('deleteIn', () => {
255
- expect(Path.deleteIn({ a: { b: { c: { ooo: 123, ccc: 234 } } } }, 'a.b.c.ccc')).toEqual({
256
- a: { b: { c: { ooo: 123 } } },
257
- })
258
-
259
- expect(Path.deleteIn({ a: { b: { c: { ooo: 123, ccc: 234 } } } }, null as any)).toEqual({
260
- a: { b: { c: { ooo: 123, ccc: 234 } } },
261
- })
262
-
263
- expect(Path.deleteIn({ a: { b: { c: { ooo: 123, ccc: 234 } } } }, [])).toEqual({
264
- a: { b: { c: { ooo: 123, ccc: 234 } } },
265
- })
266
-
267
- expect(Path.deleteIn({ a: { b: { c: 'c' } } }, 'a.b.c.ccc')).toEqual({
268
- a: { b: { c: 'c' } },
269
- })
270
-
271
- expect(Path.deleteIn({ a: 1, b: 2 }, '{ a }')).toEqual({ b: 2 })
272
- expect(Path.deleteIn([1, 2], '[0]')).toEqual([undefined, 2])
273
- })
274
-
275
- test('ensureIn', () => {
276
- expect(Path.parse('a.b').ensureIn({}, 'default')).toEqual('default')
277
- expect(Path.parse('a.b').ensureIn({ a: { b: 'value' } }, 'default')).toEqual('value')
278
- expect(Path.ensureIn({}, 'a.b.c', 'default')).toEqual('default')
279
- })
280
-
281
- test('complex destructing', () => {
282
- expect(
283
- Path.setIn({}, '{aa:{bb:{cc:destructor1,dd:[destructor2,destructor3],ee}}}', {
284
- aa: {
285
- bb: {
286
- cc: 123,
287
- dd: [333, 444],
288
- ee: 'abcde',
289
- },
290
- },
291
- })
292
- ).toEqual({
293
- destructor1: 123,
294
- destructor2: 333,
295
- destructor3: 444,
296
- ee: 'abcde',
297
- })
298
- expect(
299
- Path.getIn(
300
- {
301
- destructor1: 123,
302
- destructor2: 333,
303
- destructor3: 444,
304
- ee: 'abcde',
305
- },
306
- '{aa:{bb:{cc:destructor1,dd:[destructor2,destructor3],ee}}}'
307
- )
308
- ).toEqual({
309
- aa: {
310
- bb: {
311
- cc: 123,
312
- dd: [333, 444],
313
- ee: 'abcde',
314
- },
315
- },
316
- })
317
- })
318
-
319
- test('test getIn with invalid value', () => {
320
- const value = {
321
- array: [null, undefined, { nil: null, undef: undefined }],
322
- nil: null,
323
- undef: undefined,
324
- }
325
- expect(getIn(value, 'array.0')).toBeNull()
326
- expect(getIn(value, 'array.1')).toBeUndefined()
327
- expect(getIn(value, 'array.2.nil')).toBeNull()
328
- expect(getIn(value, 'array.2.undef')).toBeUndefined()
329
- expect(getIn(value, 'nil')).toBeNull()
330
- expect(getIn(value, 'undef')).toBeUndefined()
331
- })
332
-
333
- test('test setIn with invalid value', () => {
334
- const value = {
335
- a: 1,
336
- b: 2,
337
- array: [null, undefined, { nil: null, undef: undefined }],
338
- nil: null,
339
- undef: undefined,
340
- }
341
- setIn(value, 'a', null)
342
- setIn(value, 'b', undefined)
343
- // undefined 与 null 互转
344
- setIn(value, 'array.0', undefined)
345
- setIn(value, 'array.1', null)
346
- setIn(value, 'array.2.nil', undefined)
347
- setIn(value, 'array.2.undef', null)
348
- setIn(value, 'nil', undefined)
349
- setIn(value, 'undef', null)
350
-
351
- expect(getIn(value, 'a')).toBeNull()
352
- expect(getIn(value, 'b')).toBeUndefined()
353
- expect(getIn(value, 'array.0')).toBeUndefined()
354
- expect(getIn(value, 'array.1')).toBeNull()
355
- expect(getIn(value, 'array.2.nil')).toBeUndefined()
356
- expect(getIn(value, 'array.2.undef')).toBeNull()
357
- expect(getIn(value, 'nil')).toBeUndefined()
358
- expect(getIn(value, 'undef')).toBeNull()
359
- })
360
-
361
- test('path arguments', () => {
362
- const path = new Path('a.b.c')
363
- expect(new Path(path).segments).toEqual(['a', 'b', 'c'])
364
-
365
- const matchPath = Path.match('a.b.c')
366
- expect(new Path(matchPath).segments).toEqual(['a', 'b', 'c'])
367
-
368
- expect(new Path(undefined as any).segments).toEqual([])
369
- })
370
-
371
- test('path methods', () => {
372
- const path = Path.parse('a.b.c')
373
-
374
- expect(path.concat(Path.parse('d.e')).segments).toEqual(['a', 'b', 'c', 'd', 'e'])
375
-
376
- expect(Path.parse(['a', 'b', 'c']).toString()).toEqual('a.b.c')
377
- expect(Path.parse(['a', 'b', 'c']).length).toEqual(3)
378
-
379
- const matchPath = Path.parse('*')
380
- const regexPath = Path.parse(/.+/)
381
- expect(() => matchPath.concat('a')).toThrowError()
382
- expect(() => regexPath.concat('a')).toThrowError()
383
- expect(() => matchPath.slice()).toThrowError()
384
- expect(() => regexPath.slice()).toThrowError()
385
- expect(() => matchPath.pop()).toThrowError()
386
- expect(() => regexPath.pop()).toThrowError()
387
- expect(() => matchPath.splice(0, 1)).toThrowError()
388
- expect(() => regexPath.splice(0, 1)).toThrowError()
389
- expect(() => matchPath.forEach(() => {})).toThrowError()
390
- expect(() => regexPath.forEach(() => {})).toThrowError()
391
- expect(() => matchPath.map(() => {})).toThrowError()
392
- expect(() => regexPath.map(() => {})).toThrowError()
393
- expect(() => matchPath.reduce(p => p, '')).toThrowError()
394
- expect(() => regexPath.reduce(p => p, '')).toThrowError()
395
-
396
- expect(path.slice().segments).toEqual(['a', 'b', 'c'])
397
- expect(path.push('d').segments).toEqual(['a', 'b', 'c', 'd'])
398
- expect(path.pop().segments).toEqual(['a', 'b'])
399
- expect(path.splice(0, 1).segments).toEqual(['b', 'c'])
400
-
401
- let key = ''
402
- path.forEach(p => (key += p + '_'))
403
- expect(key).toEqual('a_b_c_')
404
- expect(path.map(p => p)).toEqual(['a', 'b', 'c'])
405
- expect(path.reduce((str, p) => str + p, '')).toEqual('abc')
406
- expect(path.parent().segments).toEqual(['a', 'b'])
407
-
408
- expect(() => Path.parse('*').includes('*')).toThrowError()
409
- expect(() => Path.parse('*').includes('*')).toThrowError()
410
- expect(() => Path.parse('a.b').includes('*')).toThrowError()
411
- expect(Path.parse('*').includes('a.b')).toBeTruthy()
412
- expect(Path.parse('a.b').includes('a.b')).toBeTruthy()
413
- expect(Path.parse('a.b').includes('a.c')).toBeFalsy()
414
- expect(Path.parse('a.b').includes('a.b.c')).toBeFalsy()
415
-
416
- expect(Path.parse('a.b.c').transform(/[a-z]/, (...result) => result)).toEqual(['a', 'b', 'c'])
417
- expect(Path.parse('a.b.c').transform(/[a-b]/, (...result) => result)).toEqual(['a', 'b'])
418
- expect(Path.parse('a.b.c').transform('', null as any)).toEqual('')
419
- expect(() => Path.parse('*').transform('', () => {})).toThrowError()
420
- expect(Path.transform('a.b.c', /[a-z]/, (...result) => result)).toEqual(['a', 'b', 'c'])
421
-
422
- expect(Path.parse('a.b.c').match('*')).toBeTruthy()
423
- expect(() => Path.parse('*').match('*')).toThrowError()
424
- expect(Path.match('*')('a.b.c')).toBeTruthy()
425
- expect(Path.match('a.b')('a.b.c')).toBeFalsy()
426
-
427
- const matcher = Path.match('a.b.c')
428
- expect(Path.parse(matcher).segments).toEqual(['a', 'b', 'c'])
429
- })
@@ -1,14 +0,0 @@
1
- import { expect, test } from 'vitest'
2
-
3
- import { Path } from '../'
4
-
5
- const { isPathPattern, match } = Path
6
-
7
- test('isPathPattern', () => {
8
- expect(isPathPattern('obj')).toBeTruthy()
9
- expect(isPathPattern(['obj', 'aa'])).toBeTruthy()
10
- expect(isPathPattern(/^obj/)).toBeTruthy()
11
-
12
- const matcher = match('obj.aa')
13
- expect(isPathPattern(matcher)).toBeTruthy()
14
- })