@scalar/json-magic 0.1.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 (185) hide show
  1. package/.turbo/turbo-build.log +9 -0
  2. package/CHANGELOG.md +7 -0
  3. package/LICENSE +21 -0
  4. package/README.md +356 -0
  5. package/dist/bundle/bundle.d.ts +292 -0
  6. package/dist/bundle/bundle.d.ts.map +1 -0
  7. package/dist/bundle/bundle.js +259 -0
  8. package/dist/bundle/bundle.js.map +7 -0
  9. package/dist/bundle/create-limiter.d.ts +21 -0
  10. package/dist/bundle/create-limiter.d.ts.map +1 -0
  11. package/dist/bundle/create-limiter.js +31 -0
  12. package/dist/bundle/create-limiter.js.map +7 -0
  13. package/dist/bundle/index.d.ts +2 -0
  14. package/dist/bundle/index.d.ts.map +1 -0
  15. package/dist/bundle/index.js +5 -0
  16. package/dist/bundle/index.js.map +7 -0
  17. package/dist/bundle/plugins/browser.d.ts +4 -0
  18. package/dist/bundle/plugins/browser.d.ts.map +1 -0
  19. package/dist/bundle/plugins/browser.js +9 -0
  20. package/dist/bundle/plugins/browser.js.map +7 -0
  21. package/dist/bundle/plugins/fetch-urls/index.d.ts +39 -0
  22. package/dist/bundle/plugins/fetch-urls/index.d.ts.map +1 -0
  23. package/dist/bundle/plugins/fetch-urls/index.js +48 -0
  24. package/dist/bundle/plugins/fetch-urls/index.js.map +7 -0
  25. package/dist/bundle/plugins/node.d.ts +5 -0
  26. package/dist/bundle/plugins/node.d.ts.map +1 -0
  27. package/dist/bundle/plugins/node.js +11 -0
  28. package/dist/bundle/plugins/node.js.map +7 -0
  29. package/dist/bundle/plugins/parse-json/index.d.ts +13 -0
  30. package/dist/bundle/plugins/parse-json/index.d.ts.map +1 -0
  31. package/dist/bundle/plugins/parse-json/index.js +22 -0
  32. package/dist/bundle/plugins/parse-json/index.js.map +7 -0
  33. package/dist/bundle/plugins/parse-yaml/index.d.ts +13 -0
  34. package/dist/bundle/plugins/parse-yaml/index.d.ts.map +1 -0
  35. package/dist/bundle/plugins/parse-yaml/index.js +23 -0
  36. package/dist/bundle/plugins/parse-yaml/index.js.map +7 -0
  37. package/dist/bundle/plugins/read-files/index.d.ts +29 -0
  38. package/dist/bundle/plugins/read-files/index.d.ts.map +1 -0
  39. package/dist/bundle/plugins/read-files/index.js +30 -0
  40. package/dist/bundle/plugins/read-files/index.js.map +7 -0
  41. package/dist/bundle/value-generator.d.ts +79 -0
  42. package/dist/bundle/value-generator.d.ts.map +1 -0
  43. package/dist/bundle/value-generator.js +55 -0
  44. package/dist/bundle/value-generator.js.map +7 -0
  45. package/dist/dereference/dereference.d.ts +45 -0
  46. package/dist/dereference/dereference.d.ts.map +1 -0
  47. package/dist/dereference/dereference.js +37 -0
  48. package/dist/dereference/dereference.js.map +7 -0
  49. package/dist/dereference/index.d.ts +2 -0
  50. package/dist/dereference/index.d.ts.map +1 -0
  51. package/dist/dereference/index.js +5 -0
  52. package/dist/dereference/index.js.map +7 -0
  53. package/dist/diff/apply.d.ts +35 -0
  54. package/dist/diff/apply.d.ts.map +1 -0
  55. package/dist/diff/apply.js +40 -0
  56. package/dist/diff/apply.js.map +7 -0
  57. package/dist/diff/diff.d.ts +56 -0
  58. package/dist/diff/diff.d.ts.map +1 -0
  59. package/dist/diff/diff.js +33 -0
  60. package/dist/diff/diff.js.map +7 -0
  61. package/dist/diff/index.d.ts +5 -0
  62. package/dist/diff/index.d.ts.map +1 -0
  63. package/dist/diff/index.js +9 -0
  64. package/dist/diff/index.js.map +7 -0
  65. package/dist/diff/merge.d.ts +43 -0
  66. package/dist/diff/merge.d.ts.map +1 -0
  67. package/dist/diff/merge.js +61 -0
  68. package/dist/diff/merge.js.map +7 -0
  69. package/dist/diff/trie.d.ts +64 -0
  70. package/dist/diff/trie.d.ts.map +1 -0
  71. package/dist/diff/trie.js +82 -0
  72. package/dist/diff/trie.js.map +7 -0
  73. package/dist/diff/utils.d.ts +63 -0
  74. package/dist/diff/utils.d.ts.map +1 -0
  75. package/dist/diff/utils.js +48 -0
  76. package/dist/diff/utils.js.map +7 -0
  77. package/dist/magic-proxy/index.d.ts +2 -0
  78. package/dist/magic-proxy/index.d.ts.map +1 -0
  79. package/dist/magic-proxy/index.js +6 -0
  80. package/dist/magic-proxy/index.js.map +7 -0
  81. package/dist/magic-proxy/proxy.d.ts +63 -0
  82. package/dist/magic-proxy/proxy.d.ts.map +1 -0
  83. package/dist/magic-proxy/proxy.js +108 -0
  84. package/dist/magic-proxy/proxy.js.map +7 -0
  85. package/dist/polyfills/index.d.ts +2 -0
  86. package/dist/polyfills/index.d.ts.map +1 -0
  87. package/dist/polyfills/index.js +25 -0
  88. package/dist/polyfills/index.js.map +7 -0
  89. package/dist/polyfills/path.d.ts +24 -0
  90. package/dist/polyfills/path.d.ts.map +1 -0
  91. package/dist/polyfills/path.js +174 -0
  92. package/dist/polyfills/path.js.map +7 -0
  93. package/dist/types.d.ts +2 -0
  94. package/dist/types.d.ts.map +1 -0
  95. package/dist/types.js +1 -0
  96. package/dist/types.js.map +7 -0
  97. package/dist/utils/escape-json-pointer.d.ts +7 -0
  98. package/dist/utils/escape-json-pointer.d.ts.map +1 -0
  99. package/dist/utils/escape-json-pointer.js +7 -0
  100. package/dist/utils/escape-json-pointer.js.map +7 -0
  101. package/dist/utils/get-segments-from-path.d.ts +5 -0
  102. package/dist/utils/get-segments-from-path.d.ts.map +1 -0
  103. package/dist/utils/get-segments-from-path.js +11 -0
  104. package/dist/utils/get-segments-from-path.js.map +7 -0
  105. package/dist/utils/is-json-object.d.ts +18 -0
  106. package/dist/utils/is-json-object.d.ts.map +1 -0
  107. package/dist/utils/is-json-object.js +16 -0
  108. package/dist/utils/is-json-object.js.map +7 -0
  109. package/dist/utils/is-object.d.ts +5 -0
  110. package/dist/utils/is-object.d.ts.map +1 -0
  111. package/dist/utils/is-object.js +5 -0
  112. package/dist/utils/is-object.js.map +7 -0
  113. package/dist/utils/is-yaml.d.ts +17 -0
  114. package/dist/utils/is-yaml.d.ts.map +1 -0
  115. package/dist/utils/is-yaml.js +7 -0
  116. package/dist/utils/is-yaml.js.map +7 -0
  117. package/dist/utils/json-path-utils.d.ts +23 -0
  118. package/dist/utils/json-path-utils.d.ts.map +1 -0
  119. package/dist/utils/json-path-utils.js +16 -0
  120. package/dist/utils/json-path-utils.js.map +7 -0
  121. package/dist/utils/normalize.d.ts +5 -0
  122. package/dist/utils/normalize.d.ts.map +1 -0
  123. package/dist/utils/normalize.js +28 -0
  124. package/dist/utils/normalize.js.map +7 -0
  125. package/dist/utils/unescape-json-pointer.d.ts +8 -0
  126. package/dist/utils/unescape-json-pointer.d.ts.map +1 -0
  127. package/dist/utils/unescape-json-pointer.js +7 -0
  128. package/dist/utils/unescape-json-pointer.js.map +7 -0
  129. package/esbuild.ts +13 -0
  130. package/package.json +65 -0
  131. package/src/bundle/bundle.test.ts +1843 -0
  132. package/src/bundle/bundle.ts +758 -0
  133. package/src/bundle/create-limiter.test.ts +28 -0
  134. package/src/bundle/create-limiter.ts +52 -0
  135. package/src/bundle/index.ts +2 -0
  136. package/src/bundle/plugins/browser.ts +4 -0
  137. package/src/bundle/plugins/fetch-urls/index.test.ts +147 -0
  138. package/src/bundle/plugins/fetch-urls/index.ts +94 -0
  139. package/src/bundle/plugins/node.ts +5 -0
  140. package/src/bundle/plugins/parse-json/index.test.ts +22 -0
  141. package/src/bundle/plugins/parse-json/index.ts +30 -0
  142. package/src/bundle/plugins/parse-yaml/index.test.ts +24 -0
  143. package/src/bundle/plugins/parse-yaml/index.ts +31 -0
  144. package/src/bundle/plugins/read-files/index.test.ts +35 -0
  145. package/src/bundle/plugins/read-files/index.ts +55 -0
  146. package/src/bundle/value-generator.test.ts +166 -0
  147. package/src/bundle/value-generator.ts +147 -0
  148. package/src/dereference/dereference.test.ts +137 -0
  149. package/src/dereference/dereference.ts +84 -0
  150. package/src/dereference/index.ts +2 -0
  151. package/src/diff/apply.test.ts +262 -0
  152. package/src/diff/apply.ts +78 -0
  153. package/src/diff/diff.test.ts +328 -0
  154. package/src/diff/diff.ts +94 -0
  155. package/src/diff/index.test.ts +150 -0
  156. package/src/diff/index.ts +5 -0
  157. package/src/diff/merge.test.ts +1109 -0
  158. package/src/diff/merge.ts +136 -0
  159. package/src/diff/trie.test.ts +30 -0
  160. package/src/diff/trie.ts +113 -0
  161. package/src/diff/utils.test.ts +169 -0
  162. package/src/diff/utils.ts +113 -0
  163. package/src/magic-proxy/index.ts +2 -0
  164. package/src/magic-proxy/proxy.test.ts +145 -0
  165. package/src/magic-proxy/proxy.ts +225 -0
  166. package/src/polyfills/index.ts +12 -0
  167. package/src/polyfills/path.ts +248 -0
  168. package/src/types.ts +1 -0
  169. package/src/utils/escape-json-pointer.test.ts +13 -0
  170. package/src/utils/escape-json-pointer.ts +8 -0
  171. package/src/utils/get-segments-from-path.test.ts +17 -0
  172. package/src/utils/get-segments-from-path.ts +17 -0
  173. package/src/utils/is-json-object.ts +31 -0
  174. package/src/utils/is-object.test.ts +27 -0
  175. package/src/utils/is-object.ts +4 -0
  176. package/src/utils/is-yaml.ts +18 -0
  177. package/src/utils/json-path-utils.test.ts +13 -0
  178. package/src/utils/json-path-utils.ts +38 -0
  179. package/src/utils/normalize.test.ts +91 -0
  180. package/src/utils/normalize.ts +34 -0
  181. package/src/utils/unescape-json-pointer.test.ts +23 -0
  182. package/src/utils/unescape-json-pointer.ts +9 -0
  183. package/tsconfig.build.json +12 -0
  184. package/tsconfig.json +16 -0
  185. package/vite.config.ts +8 -0
@@ -0,0 +1,9 @@
1
+
2
+ > @scalar/json-magic@0.1.0 build /home/runner/work/scalar/scalar/packages/json-magic
3
+ > scalar-build-esbuild
4
+
5
+ @scalar/json-magic: Build completed in 90.13ms
6
+
7
+ > @scalar/json-magic@0.1.0 types:build /home/runner/work/scalar/scalar/packages/json-magic
8
+ > scalar-types-build
9
+
package/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # @scalar/json-magic
2
+
3
+ ## 0.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 952bde2: feat(json-magic): move json tooling to the new package
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-present Scalar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,356 @@
1
+ # json-magic
2
+
3
+ [![Version](https://img.shields.io/npm/v/%40scalar/json-magic)](https://www.npmjs.com/package/@scalar/json-magic)
4
+ [![Downloads](https://img.shields.io/npm/dm/%40scalar/json-magic)](https://www.npmjs.com/package/@scalar/json-magic)
5
+ [![License](https://img.shields.io/npm/l/%40scalar%2Fjson-magic)](https://www.npmjs.com/package/@scalar/json-magic)
6
+ [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
7
+
8
+
9
+ A collection of utilities for working with JSON objects, including diffing, conflict resolution, bundling and more.
10
+
11
+ ## bundle
12
+
13
+ Bundle external references in a json object
14
+
15
+ ### Quick start
16
+
17
+ ```ts
18
+ import { bundle } from '@scalar/json-magic/bundle'
19
+ import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
20
+
21
+ const result = await bundle({
22
+ $ref: 'http://example.com/document.json'
23
+ }, {
24
+ plugins: [fetchUrls()],
25
+ treeShake: false,
26
+ })
27
+
28
+ // get the bundled json object
29
+ console.log(result)
30
+ ```
31
+
32
+ #### Plugins
33
+
34
+ If you are on a browser environment import plugins from `@scalar/json-magic/bundle/plugins/browser` while if you are on a node environment you can import from `@scalar/json-magic/bundle/plugins/node`
35
+
36
+ ##### fetchUrls
37
+ This plugins handles all external urls. It works for both node.js and browser environment
38
+
39
+ ```ts
40
+ import { bundle } from '@scalar/json-magic/bundle'
41
+ import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
42
+
43
+ const document = {
44
+ openapi: '3.1.0',
45
+ info: { title: 'Bundled API', version: '1.0.0' },
46
+ paths: {},
47
+ components: {
48
+ schemas: {
49
+ User: { $ref: 'https://example.com/user-schema.json#' }
50
+ }
51
+ }
52
+ }
53
+
54
+ // This will bundle all external documents and turn all references from external into internal
55
+ await bundle(document, {
56
+ plugins: [fetchUrls()],
57
+ treeShake: true // <------ This flag will try to remove any unused part of the external document
58
+ })
59
+
60
+ console.log(document)
61
+ ```
62
+
63
+ ###### Limiting the number of concurrent requests
64
+
65
+ ```ts
66
+ await bundle(document, {
67
+ plugins: [
68
+ fetchUrls({
69
+ limit: 10, // it should run at most 10 requests at the same time
70
+ }),
71
+ ],
72
+ treeShake: false
73
+ })
74
+
75
+ ```
76
+
77
+ ###### Custom headers
78
+ To pass custom headers to requests for specific domains you can configure the fetch plugin like the example
79
+
80
+ ```ts
81
+ await bundle(
82
+ document,
83
+ {
84
+ plugins: [
85
+ fetchUrls({
86
+ // Pass custom headers
87
+ // The header will only be attached to the list of domains
88
+ headers: [
89
+ {
90
+ domains: ['example.com'],
91
+ headers: {
92
+ 'Authorization': 'Bearer <TOKEN>'
93
+ }
94
+ }
95
+ ]
96
+ }),
97
+ readFiles(),
98
+ ],
99
+ treeShake: false
100
+ },
101
+ )
102
+ ```
103
+
104
+ ###### Custom fetch function
105
+ For advanced use cases like proxying requests or implementing custom network logic, you can provide your own fetch implementation. This allows you to handle things like CORS restrictions, custom authentication flows, or request/response transformations.
106
+
107
+ ```ts
108
+ await bundle(
109
+ document,
110
+ {
111
+ plugins: [
112
+ fetchUrls({
113
+ // Custom fetcher function
114
+ fetch: async (input, init) => {
115
+ console.log('Custom fetch logic')
116
+ return fetch(input, init)
117
+ },
118
+ })
119
+ readFiles(),
120
+ ],
121
+ treeShake: false
122
+ },
123
+ )
124
+ ```
125
+
126
+ ###### Bundle from remote url
127
+
128
+ ```ts
129
+ const result = await bundle(
130
+ 'https://example.com/openapi.json',
131
+ {
132
+ plugins: [
133
+ fetchUrls(),
134
+ ],
135
+ treeShake: false
136
+ },
137
+ )
138
+
139
+ // Bundled document
140
+ console.log(result)
141
+ ```
142
+
143
+ ##### readFiles
144
+ This plugins handles local files. Only works on node.js environment
145
+
146
+ ```ts
147
+ import { bundle } from '@scalar/json-magic/bundle'
148
+ import { readFiles } from '@scalar/json-magic/bundle/plugins/node'
149
+
150
+ const document = {
151
+ openapi: '3.1.0',
152
+ info: { title: 'Bundled API', version: '1.0.0' },
153
+ paths: {},
154
+ components: {
155
+ schemas: {
156
+ User: { $ref: './user-schema.json#' }
157
+ }
158
+ }
159
+ }
160
+
161
+ // This will bundle all external documents and turn all references from external into internal
162
+ await bundle(document, {
163
+ plugins: [readFiles()],
164
+ treeShake: false
165
+ })
166
+
167
+ console.log(document)
168
+ ```
169
+
170
+ ###### Bundle from local file
171
+ You can pass the file path directly but make sure to have the correct plugins to handle reading from the local files
172
+
173
+ ```ts
174
+ const result = await bundle(
175
+ './input.json',
176
+ {
177
+ plugins: [
178
+ readFiles(),
179
+ ],
180
+ treeShake: false
181
+ },
182
+ )
183
+
184
+ // Bundled document
185
+ console.log(result)
186
+ ```
187
+
188
+ ##### parseJson
189
+
190
+ You can pass raw json string as input
191
+ ```ts
192
+ import { bundle } from '@scalar/json-magic/bundle'
193
+ import { parseJson } from '@scalar/json-magic/bundle/plugins/browser'
194
+
195
+ const result = await bundle(
196
+ '{ "openapi": "3.1.1" }',
197
+ {
198
+ plugins: [
199
+ parseJson(),
200
+ ],
201
+ treeShake: false
202
+ },
203
+ )
204
+
205
+ // Bundled document
206
+ console.log(result)
207
+ ```
208
+
209
+ ##### parseYaml
210
+
211
+ You can pass raw yaml string as input
212
+ ```ts
213
+ import { bundle } from '@scalar/json-magic/bundle'
214
+ import { parseYaml } from '@scalar/json-magic/bundle/plugins/browser'
215
+
216
+ const result = await bundle(
217
+ 'openapi: "3.1.1"\n',
218
+ {
219
+ plugins: [
220
+ parseYaml(),
221
+ ],
222
+ treeShake: false
223
+ },
224
+ )
225
+
226
+ // Bundled document
227
+ console.log(result)
228
+ ```
229
+
230
+ #### Bundler Options
231
+
232
+ ##### depth
233
+
234
+ The `depth` option controls how deeply the bundler will resolve `$ref` references. When you set `depth` to a number, the bundler will only follow references up to that level of nesting. This is useful for creating partial bundles or limiting resource usage.
235
+
236
+ **Note:** When using `depth`, the resulting bundle may not be fully self-contained—some nested references deeper than the specified depth may remain unresolved. If you use `depth` together with the `visitedNodes` option, be aware that parent nodes may be marked as visited even if their child references have not been fully resolved yet. Use this option with care if you require a complete bundle.
237
+
238
+ ```ts
239
+ import { bundle } from '@scalar/openapi-parser'
240
+ import { fetchUrls } from '@scalar/openapi-parser/plugins-browser'
241
+
242
+ await bundle(input, {
243
+ plugins: [fetchUrls()],
244
+ treeShake: false,
245
+ depth: 2,
246
+ })
247
+ ```
248
+
249
+
250
+ ## dereference
251
+
252
+ Dereference all `$ref` pointers in a JSON object, resolving both internal and external references.
253
+
254
+ The `dereference` function can operate in two modes:
255
+
256
+ - **Synchronous (`sync: true`)**: Only internal references (within the same object) are resolved. The result is wrapped in a magic proxy for reactive access. No network requests are made.
257
+ - **Asynchronous (`sync: false` or omitted)**: Both internal and external references (e.g., URLs) are resolved. The function returns a Promise that resolves to the fully dereferenced object, also wrapped in a magic proxy.
258
+
259
+ ### Options
260
+
261
+ - `sync` (`boolean`):
262
+ - If `true`, resolves only internal references synchronously.
263
+ - If `false` (default), resolves both internal and external references asynchronously and returns a Promise.
264
+
265
+ The result is an object with a `success` property. If dereferencing fails (e.g., due to unresolved external references), the result will include an `errors` array describing the issues encountered.
266
+
267
+ ```ts
268
+ import { dereference } from '@scalar/json-magic/dereference'
269
+
270
+ const result = dereference({ a: 'hello', b: { $ref: '#/a' } }, { sync: true })
271
+
272
+ // Resolve internal references synchronously
273
+ console.log(result)
274
+ ```
275
+
276
+ To resolve also external references you need to set `sync: false`
277
+
278
+ ```ts
279
+ import { dereference } from '@scalar/json-magic/dereference'
280
+
281
+ const result = await dereference({ a: 'hello', b: { $ref: 'http://example.com/document.json#/somepath' } }, { sync: false })
282
+
283
+ // Result with all internal and external references resolved
284
+ console.log(result)
285
+ ```
286
+
287
+ ## diff
288
+
289
+ This package provides a way to compare two json objects and get the differences, resolve conflicts and return conflicts that need to be resolved manually.
290
+
291
+ ### Quickstart
292
+
293
+
294
+ ```ts
295
+ import { apply, diff, merge } from '@scalar/json-magic/diff'
296
+
297
+ const baseObject = {
298
+ openapi: '3.0.0',
299
+ info: {
300
+ title: 'Simple API',
301
+ description: 'A small OpenAPI specification example',
302
+ version: '1.0.0',
303
+ },
304
+ }
305
+
306
+ const objectV1 = {
307
+ openapi: '3.0.0',
308
+ info: {
309
+ title: 'Simple API',
310
+ description: 'A small OpenAPI specification example',
311
+ version: '1.0.0',
312
+ },
313
+ change: 'This is a new property',
314
+ }
315
+
316
+ const objectV2 = {
317
+ openapi: '3.0.0',
318
+ info: {
319
+ title: 'Simple API',
320
+ description: 'A small OpenAPI specification example',
321
+ version: '1.0.1',
322
+ },
323
+ }
324
+
325
+ // Merge the changes of both versions with the same parent object
326
+ const { diffs, conflicts } = merge(
327
+ diff(baseObject, objectV1),
328
+ diff(baseObject, objectV2),
329
+ )
330
+
331
+ // Apply changes from v1 and v2 to the parent object to get the final object
332
+ const finalDocument = apply(baseObject, diffs)
333
+ ```
334
+
335
+
336
+ ## magic-proxy
337
+
338
+ A javascript proxy which resolves internal references when accessing a property
339
+
340
+ ### Quick start
341
+
342
+ ```ts
343
+ import { createMagicProxy, getRaw } from '@scalar/json-magic/magic-proxy'
344
+
345
+ const result = createMagicProxy({
346
+ a: 'hello',
347
+ b: '#/a'
348
+ })
349
+
350
+ // Resolved internal references for the input object
351
+ console.log(result)
352
+
353
+ const rawObject = getRaw(result)
354
+ // Get the raw version of the object (unwrap it from the magic proxy)
355
+ console.log(rawObject)
356
+ ```
@@ -0,0 +1,292 @@
1
+ import type { UnknownObject } from '../types.js';
2
+ /**
3
+ * Checks if a string is a remote URL (starts with http:// or https://)
4
+ * @param value - The URL string to check
5
+ * @returns true if the string is a remote URL, false otherwise
6
+ * @example
7
+ * ```ts
8
+ * isRemoteUrl('https://example.com/schema.json') // true
9
+ * isRemoteUrl('http://api.example.com/schemas/user.json') // true
10
+ * isRemoteUrl('#/components/schemas/User') // false
11
+ * isRemoteUrl('./local-schema.json') // false
12
+ * ```
13
+ */
14
+ export declare function isRemoteUrl(value: string): boolean;
15
+ /**
16
+ * Checks if a string represents a file path by ensuring it's not a remote URL,
17
+ * YAML content, or JSON content.
18
+ *
19
+ * @param value - The string to check
20
+ * @returns true if the string appears to be a file path, false otherwise
21
+ * @example
22
+ * ```ts
23
+ * isFilePath('./schemas/user.json') // true
24
+ * isFilePath('https://example.com/schema.json') // false
25
+ * isFilePath('{"type": "object"}') // false
26
+ * isFilePath('type: object') // false
27
+ * ```
28
+ */
29
+ export declare function isFilePath(value: string): boolean;
30
+ /**
31
+ * Checks if a string is a local reference (starts with #)
32
+ * @param value - The reference string to check
33
+ * @returns true if the string is a local reference, false otherwise
34
+ * @example
35
+ * ```ts
36
+ * isLocalRef('#/components/schemas/User') // true
37
+ * isLocalRef('https://example.com/schema.json') // false
38
+ * isLocalRef('./local-schema.json') // false
39
+ * ```
40
+ */
41
+ export declare function isLocalRef(value: string): boolean;
42
+ export type ResolveResult = {
43
+ ok: true;
44
+ data: unknown;
45
+ } | {
46
+ ok: false;
47
+ };
48
+ /**
49
+ * Retrieves a nested value from an object using an array of property segments.
50
+ * @param target - The target object to traverse
51
+ * @param segments - Array of property names representing the path to the desired value
52
+ * @returns The value at the specified path, or undefined if the path doesn't exist
53
+ * @example
54
+ * const obj = { foo: { bar: { baz: 42 } } };
55
+ * getNestedValue(obj, ['foo', 'bar', 'baz']); // returns 42
56
+ */
57
+ export declare function getNestedValue(target: Record<string, any>, segments: string[]): any;
58
+ /**
59
+ * Sets a value at a specified path in an object, creating intermediate objects/arrays as needed.
60
+ * This function traverses the object structure and creates any missing intermediate objects
61
+ * or arrays based on the path segments. If the next segment is a numeric string, it creates
62
+ * an array instead of an object.
63
+ *
64
+ * ⚠️ Warning: Be careful with object keys that look like numbers (e.g. "123") as this function
65
+ * will interpret them as array indices and create arrays instead of objects. If you need to
66
+ * use numeric-looking keys, consider prefixing them with a non-numeric character.
67
+ *
68
+ * @param obj - The target object to set the value in
69
+ * @param path - The JSON pointer path where the value should be set
70
+ * @param value - The value to set at the specified path
71
+ * @throws {Error} If attempting to set a value at the root path ('')
72
+ *
73
+ * @example
74
+ * const obj = {}
75
+ * setValueAtPath(obj, '/foo/bar/0', 'value')
76
+ * // Result:
77
+ * // {
78
+ * // foo: {
79
+ * // bar: ['value']
80
+ * // }
81
+ * // }
82
+ *
83
+ * @example
84
+ * const obj = { existing: { path: 'old' } }
85
+ * setValueAtPath(obj, '/existing/path', 'new')
86
+ * // Result:
87
+ * // {
88
+ * // existing: {
89
+ * // path: 'new'
90
+ * // }
91
+ * // }
92
+ *
93
+ * @example
94
+ * // ⚠️ Warning: This will create an array instead of an object with key "123"
95
+ * setValueAtPath(obj, '/foo/123/bar', 'value')
96
+ * // Result:
97
+ * // {
98
+ * // foo: [
99
+ * // undefined,
100
+ * // undefined,
101
+ * // undefined,
102
+ * // { bar: 'value' }
103
+ * // ]
104
+ * // }
105
+ */
106
+ export declare function setValueAtPath(obj: any, path: string, value: any): void;
107
+ /**
108
+ * Prefixes an internal JSON reference with a given path prefix.
109
+ * Takes a local reference (starting with #) and prepends the provided prefix segments.
110
+ *
111
+ * @param input - The internal reference string to prefix (must start with #)
112
+ * @param prefix - Array of path segments to prepend to the reference
113
+ * @returns The prefixed reference string
114
+ * @throws Error if input is not a local reference
115
+ * @example
116
+ * prefixInternalRef('#/components/schemas/User', ['definitions'])
117
+ * // Returns: '#/definitions/components/schemas/User'
118
+ */
119
+ export declare function prefixInternalRef(input: string, prefix: string[]): string;
120
+ /**
121
+ * Updates internal references in an object by adding a prefix to their paths.
122
+ * Recursively traverses the input object and modifies any local $ref references
123
+ * by prepending the given prefix to their paths. This is used when embedding external
124
+ * documents to maintain correct reference paths relative to the main document.
125
+ *
126
+ * @param input - The object to update references in
127
+ * @param prefix - Array of path segments to prepend to internal reference paths
128
+ * @returns void
129
+ * @example
130
+ * ```ts
131
+ * const input = {
132
+ * foo: {
133
+ * $ref: '#/components/schemas/User'
134
+ * }
135
+ * }
136
+ * prefixInternalRefRecursive(input, ['definitions'])
137
+ * // Result:
138
+ * // {
139
+ * // foo: {
140
+ * // $ref: '#/definitions/components/schemas/User'
141
+ * // }
142
+ * // }
143
+ * ```
144
+ */
145
+ export declare function prefixInternalRefRecursive(input: unknown, prefix: string[]): void;
146
+ /**
147
+ * Represents a plugin that handles resolving references from external sources.
148
+ * Plugins are responsible for fetching and processing data from different sources
149
+ * like URLs or the filesystem. Each plugin must implement validation to determine
150
+ * if it can handle a specific reference, and an execution function to perform
151
+ * the actual resolution.
152
+ *
153
+ * @property validate - Determines if this plugin can handle the given reference
154
+ * @property exec - Fetches and processes the reference, returning the resolved data
155
+ */
156
+ export type Plugin = {
157
+ validate: (value: string) => boolean;
158
+ exec: (value: string) => Promise<ResolveResult>;
159
+ };
160
+ /**
161
+ * Configuration options for the bundler.
162
+ * Controls how external references are resolved and processed during bundling.
163
+ */
164
+ type Config = {
165
+ /**
166
+ * Array of plugins that handle resolving references from different sources.
167
+ * Each plugin is responsible for fetching and processing data from specific sources
168
+ * like URLs or the filesystem.
169
+ */
170
+ plugins: Plugin[];
171
+ /**
172
+ * Optional root object that serves as the base document when bundling a subpart.
173
+ * This allows resolving references relative to the root document's location,
174
+ * ensuring proper path resolution for nested references.
175
+ */
176
+ root?: UnknownObject;
177
+ /**
178
+ * Optional maximum depth for reference resolution.
179
+ * Limits how deeply the bundler will follow and resolve nested $ref pointers.
180
+ * Useful for preventing infinite recursion or excessive resource usage.
181
+ */
182
+ depth?: number;
183
+ /**
184
+ * Optional cache to store promises of resolved references.
185
+ * Helps avoid duplicate fetches/reads of the same resource by storing
186
+ * the resolution promises for reuse.
187
+ */
188
+ cache?: Map<string, Promise<ResolveResult>>;
189
+ /**
190
+ * Cache of visited nodes during partial bundling.
191
+ * Used to prevent re-bundling the same tree multiple times when doing partial bundling,
192
+ * improving performance by avoiding redundant processing of already bundled sections.
193
+ */
194
+ visitedNodes?: Set<unknown>;
195
+ /**
196
+ * Enable tree shaking to optimize the bundle size.
197
+ * When enabled, only the parts of external documents that are actually referenced
198
+ * will be included in the final bundle.
199
+ */
200
+ treeShake: boolean;
201
+ /**
202
+ * Optional flag to generate a URL map.
203
+ * When enabled, tracks the original source URLs of bundled references
204
+ * in an x-ext-urls section for reference mapping.
205
+ */
206
+ urlMap?: boolean;
207
+ /**
208
+ * Optional function to compress input URLs or file paths before bundling.
209
+ * Returns either a Promise resolving to the compressed string or the compressed string directly.
210
+ */
211
+ compress?: (value: string) => Promise<string> | string;
212
+ /**
213
+ * Optional hooks to monitor the bundler's lifecycle.
214
+ * Allows tracking the progress and status of reference resolution.
215
+ */
216
+ hooks?: Partial<{
217
+ /** Called when starting to resolve a reference */
218
+ onResolveStart: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
219
+ /** Called when a reference resolution fails */
220
+ onResolveError: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
221
+ /** Called when a reference is successfully resolved */
222
+ onResolveSuccess: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
223
+ }>;
224
+ };
225
+ /**
226
+ * Bundles an OpenAPI specification by resolving all external references.
227
+ * This function traverses the input object recursively and embeds external $ref
228
+ * references into an x-ext section. External references can be URLs or local files.
229
+ * The original $refs are updated to point to their embedded content in the x-ext section.
230
+ * If the input is an object, it will be modified in place by adding an x-ext
231
+ * property to store resolved external references.
232
+ *
233
+ * @param input - The OpenAPI specification to bundle. Can be either an object or string.
234
+ * If a string is provided, it will be resolved using the provided plugins.
235
+ * If no plugin can process the input, the onReferenceError hook will be invoked
236
+ * and an error will be emitted to the console.
237
+ * @param config - Configuration object containing plugins and options for bundling OpenAPI specifications
238
+ * @returns A promise that resolves to the bundled specification with all references embedded
239
+ * @example
240
+ * // Example with object input
241
+ * const spec = {
242
+ * paths: {
243
+ * '/users': {
244
+ * $ref: 'https://example.com/schemas/users.yaml'
245
+ * }
246
+ * }
247
+ * }
248
+ *
249
+ * const bundled = await bundle(spec, {
250
+ * plugins: [fetchUrls()],
251
+ * treeShake: true,
252
+ * urlMap: true,
253
+ * hooks: {
254
+ * onResolveStart: (ref) => console.log('Resolving:', ref.$ref),
255
+ * onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),
256
+ * onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)
257
+ * }
258
+ * })
259
+ * // Result:
260
+ * // {
261
+ * // paths: {
262
+ * // '/users': {
263
+ * // $ref: '#/x-ext/abc123'
264
+ * // }
265
+ * // },
266
+ * // 'x-ext': {
267
+ * // 'abc123': {
268
+ * // // Resolved content from users.yaml
269
+ * // }
270
+ * // },
271
+ * // 'x-ext-urls': {
272
+ * // 'https://example.com/schemas/users.yaml': 'abc123'
273
+ * // }
274
+ * // }
275
+ *
276
+ * // Example with URL input
277
+ * const bundledFromUrl = await bundle('https://example.com/openapi.yaml', {
278
+ * plugins: [fetchUrls()],
279
+ * treeShake: true,
280
+ * urlMap: true,
281
+ * hooks: {
282
+ * onResolveStart: (ref) => console.log('Resolving:', ref.$ref),
283
+ * onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),
284
+ * onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)
285
+ * }
286
+ * })
287
+ * // The function will first fetch the OpenAPI spec from the URL,
288
+ * // then bundle all its external references into the x-ext section
289
+ */
290
+ export declare function bundle(input: UnknownObject | string, config: Config): Promise<object>;
291
+ export {};
292
+ //# sourceMappingURL=bundle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle/bundle.ts"],"names":[],"mappings":"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"}