1 | ;
|
2 |
|
3 | module.exports = Pointer;
|
4 |
|
5 | var $Ref = require('./ref'),
|
6 | url = require('./util/url'),
|
7 | ono = require('ono'),
|
8 | slashes = /\//g,
|
9 | tildes = /~/g,
|
10 | escapedSlash = /~1/g,
|
11 | escapedTilde = /~0/g;
|
12 |
|
13 | /**
|
14 | * This class represents a single JSON pointer and its resolved value.
|
15 | *
|
16 | * @param {$Ref} $ref
|
17 | * @param {string} path
|
18 | * @param {string} [friendlyPath] - The original user-specified path (used for error messages)
|
19 | * @constructor
|
20 | */
|
21 | function Pointer ($ref, path, friendlyPath) {
|
22 | /**
|
23 | * The {@link $Ref} object that contains this {@link Pointer} object.
|
24 | * @type {$Ref}
|
25 | */
|
26 | this.$ref = $ref;
|
27 |
|
28 | /**
|
29 | * The file path or URL, containing the JSON pointer in the hash.
|
30 | * This path is relative to the path of the main JSON schema file.
|
31 | * @type {string}
|
32 | */
|
33 | this.path = path;
|
34 |
|
35 | /**
|
36 | * The original path or URL, used for error messages.
|
37 | * @type {string}
|
38 | */
|
39 | this.originalPath = friendlyPath || path;
|
40 |
|
41 | /**
|
42 | * The value of the JSON pointer.
|
43 | * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
|
44 | * @type {?*}
|
45 | */
|
46 | this.value = undefined;
|
47 |
|
48 | /**
|
49 | * Indicates whether the pointer references itself.
|
50 | * @type {boolean}
|
51 | */
|
52 | this.circular = false;
|
53 |
|
54 | /**
|
55 | * The number of indirect references that were traversed to resolve the value.
|
56 | * Resolving a single pointer may require resolving multiple $Refs.
|
57 | * @type {number}
|
58 | */
|
59 | this.indirections = 0;
|
60 | }
|
61 |
|
62 | /**
|
63 | * Resolves the value of a nested property within the given object.
|
64 | *
|
65 | * @param {*} obj - The object that will be crawled
|
66 | * @param {$RefParserOptions} options
|
67 | *
|
68 | * @returns {Pointer}
|
69 | * Returns a JSON pointer whose {@link Pointer#value} is the resolved value.
|
70 | * If resolving this value required resolving other JSON references, then
|
71 | * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
|
72 | * of the resolved value.
|
73 | */
|
74 | Pointer.prototype.resolve = function (obj, options) {
|
75 | var tokens = Pointer.parse(this.path);
|
76 |
|
77 | // Crawl the object, one token at a time
|
78 | this.value = obj;
|
79 | for (var i = 0; i < tokens.length; i++) {
|
80 | if (resolveIf$Ref(this, options)) {
|
81 | // The $ref path has changed, so append the remaining tokens to the path
|
82 | this.path = Pointer.join(this.path, tokens.slice(i));
|
83 | }
|
84 |
|
85 | var token = tokens[i];
|
86 | if (this.value[token] === undefined) {
|
87 | throw ono.syntax('Error resolving $ref pointer "%s". \nToken "%s" does not exist.', this.originalPath, token);
|
88 | }
|
89 | else {
|
90 | this.value = this.value[token];
|
91 | }
|
92 | }
|
93 |
|
94 | // Resolve the final value
|
95 | resolveIf$Ref(this, options);
|
96 | return this;
|
97 | };
|
98 |
|
99 | /**
|
100 | * Sets the value of a nested property within the given object.
|
101 | *
|
102 | * @param {*} obj - The object that will be crawled
|
103 | * @param {*} value - the value to assign
|
104 | * @param {$RefParserOptions} options
|
105 | *
|
106 | * @returns {*}
|
107 | * Returns the modified object, or an entirely new object if the entire object is overwritten.
|
108 | */
|
109 | Pointer.prototype.set = function (obj, value, options) {
|
110 | var tokens = Pointer.parse(this.path);
|
111 | var token;
|
112 |
|
113 | if (tokens.length === 0) {
|
114 | // There are no tokens, replace the entire object with the new value
|
115 | this.value = value;
|
116 | return value;
|
117 | }
|
118 |
|
119 | // Crawl the object, one token at a time
|
120 | this.value = obj;
|
121 | for (var i = 0; i < tokens.length - 1; i++) {
|
122 | resolveIf$Ref(this, options);
|
123 |
|
124 | token = tokens[i];
|
125 | if (this.value && this.value[token] !== undefined) {
|
126 | // The token exists
|
127 | this.value = this.value[token];
|
128 | }
|
129 | else {
|
130 | // The token doesn't exist, so create it
|
131 | this.value = setValue(this, token, {});
|
132 | }
|
133 | }
|
134 |
|
135 | // Set the value of the final token
|
136 | resolveIf$Ref(this, options);
|
137 | token = tokens[tokens.length - 1];
|
138 | setValue(this, token, value);
|
139 |
|
140 | // Return the updated object
|
141 | return obj;
|
142 | };
|
143 |
|
144 | /**
|
145 | * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
|
146 | * and returns an array of the pointer's tokens.
|
147 | * (e.g. "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
|
148 | *
|
149 | * The pointer is parsed according to RFC 6901
|
150 | * {@link https://tools.ietf.org/html/rfc6901#section-3}
|
151 | *
|
152 | * @param {string} path
|
153 | * @returns {string[]}
|
154 | */
|
155 | Pointer.parse = function (path) {
|
156 | // Get the JSON pointer from the path's hash
|
157 | var pointer = url.getHash(path).substr(1);
|
158 |
|
159 | // If there's no pointer, then there are no tokens,
|
160 | // so return an empty array
|
161 | if (!pointer) {
|
162 | return [];
|
163 | }
|
164 |
|
165 | // Split into an array
|
166 | pointer = pointer.split('/');
|
167 |
|
168 | // Decode each part, according to RFC 6901
|
169 | for (var i = 0; i < pointer.length; i++) {
|
170 | pointer[i] = decodeURIComponent(pointer[i].replace(escapedSlash, '/').replace(escapedTilde, '~'));
|
171 | }
|
172 |
|
173 | if (pointer[0] !== '') {
|
174 | throw ono.syntax('Invalid $ref pointer "%s". Pointers must begin with "#/"', pointer);
|
175 | }
|
176 |
|
177 | return pointer.slice(1);
|
178 | };
|
179 |
|
180 | /**
|
181 | * Creates a JSON pointer path, by joining one or more tokens to a base path.
|
182 | *
|
183 | * @param {string} base - The base path (e.g. "schema.json#/definitions/person")
|
184 | * @param {string|string[]} tokens - The token(s) to append (e.g. ["name", "first"])
|
185 | * @returns {string}
|
186 | */
|
187 | Pointer.join = function (base, tokens) {
|
188 | // Ensure that the base path contains a hash
|
189 | if (base.indexOf('#') === -1) {
|
190 | base += '#';
|
191 | }
|
192 |
|
193 | // Append each token to the base path
|
194 | tokens = Array.isArray(tokens) ? tokens : [tokens];
|
195 | for (var i = 0; i < tokens.length; i++) {
|
196 | var token = tokens[i];
|
197 | // Encode the token, according to RFC 6901
|
198 | base += '/' + encodeURIComponent(token.replace(tildes, '~0').replace(slashes, '~1'));
|
199 | }
|
200 |
|
201 | return base;
|
202 | };
|
203 |
|
204 | /**
|
205 | * If the given pointer's {@link Pointer#value} is a JSON reference,
|
206 | * then the reference is resolved and {@link Pointer#value} is replaced with the resolved value.
|
207 | * In addition, {@link Pointer#path} and {@link Pointer#$ref} are updated to reflect the
|
208 | * resolution path of the new value.
|
209 | *
|
210 | * @param {Pointer} pointer
|
211 | * @param {$RefParserOptions} options
|
212 | * @returns {boolean} - Returns `true` if the resolution path changed
|
213 | */
|
214 | function resolveIf$Ref (pointer, options) {
|
215 | // Is the value a JSON reference? (and allowed?)
|
216 |
|
217 | if ($Ref.isAllowed$Ref(pointer.value, options)) {
|
218 | var $refPath = url.resolve(pointer.path, pointer.value.$ref);
|
219 |
|
220 | if ($refPath === pointer.path) {
|
221 | // The value is a reference to itself, so there's nothing to do.
|
222 | pointer.circular = true;
|
223 | }
|
224 | else {
|
225 | var resolved = pointer.$ref.$refs._resolve($refPath, options);
|
226 | pointer.indirections += resolved.indirections + 1;
|
227 |
|
228 | if ($Ref.isExtended$Ref(pointer.value)) {
|
229 | // This JSON reference "extends" the resolved value, rather than simply pointing to it.
|
230 | // So the resolved path does NOT change. Just the value does.
|
231 | pointer.value = $Ref.dereference(pointer.value, resolved.value);
|
232 | return false;
|
233 | }
|
234 | else {
|
235 | // Resolve the reference
|
236 | pointer.$ref = resolved.$ref;
|
237 | pointer.path = resolved.path;
|
238 | pointer.value = resolved.value;
|
239 | }
|
240 |
|
241 | return true;
|
242 | }
|
243 | }
|
244 | }
|
245 |
|
246 | /**
|
247 | * Sets the specified token value of the {@link Pointer#value}.
|
248 | *
|
249 | * The token is evaluated according to RFC 6901.
|
250 | * {@link https://tools.ietf.org/html/rfc6901#section-4}
|
251 | *
|
252 | * @param {Pointer} pointer - The JSON Pointer whose value will be modified
|
253 | * @param {string} token - A JSON Pointer token that indicates how to modify `obj`
|
254 | * @param {*} value - The value to assign
|
255 | * @returns {*} - Returns the assigned value
|
256 | */
|
257 | function setValue (pointer, token, value) {
|
258 | if (pointer.value && typeof pointer.value === 'object') {
|
259 | if (token === '-' && Array.isArray(pointer.value)) {
|
260 | pointer.value.push(value);
|
261 | }
|
262 | else {
|
263 | pointer.value[token] = value;
|
264 | }
|
265 | }
|
266 | else {
|
267 | throw ono.syntax('Error assigning $ref pointer "%s". \nCannot set "%s" of a non-object.', pointer.path, token);
|
268 | }
|
269 | return value;
|
270 | }
|