Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions lib/node_modules/@stdlib/utils/json-pointer/resolve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,9 @@ out = resolve( obj, '/foo' );

out = resolve( obj, '' );
// returns { 'target': null, 'key': null, 'value': { 'foo': 'bar' } }

out = resolve( obj, '/missing' );
// returns undefined
```

</section>
Expand All @@ -60,6 +63,7 @@ out = resolve( obj, '' );
## Notes

- Per [RFC 6901][rfc-6901], an empty string refers to the root of the document.
- If a pointer references a nonexistent location in the document, the function returns `undefined`.
- The `-` token on the last segment of a pointer targeting an array resolves to the array's length (i.e., past-the-end index).
- Tokens `__proto__`, `constructor`, and `prototype` are rejected to prevent prototype pollution.
- The returned `target` is the parent container (object or array) holding the referenced value. For root pointers, `target` and `key` are both `null`.
Expand Down Expand Up @@ -101,6 +105,9 @@ out = resolve( doc, '/m~0n' );

out = resolve( doc, '' );
// returns { 'target': null, 'key': null, 'value': { 'foo': [ 'bar', 'baz' ], '': 0, 'a/b': 1, 'm~n': 8 } }

out = resolve( doc, '/missing' );
// returns undefined
```

</section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@

Per RFC 6901, an empty string refers to the root of the document.

If a pointer references a nonexistent location in the document, the
function returns `undefined`.

The `-` token on the last segment of a pointer targeting an array resolves
to the array's length (i.e., past-the-end index).

Expand All @@ -21,8 +24,9 @@

Returns
-------
out: Object
Result object.
out: Object|void
Result object or undefined if pointer does not resolve to an existing
location.

out.target: Object|Array|null
Parent container. Null for root pointer.
Expand All @@ -41,6 +45,8 @@
{ 'target': { 'foo': 'bar' }, 'key': 'foo', 'value': 'bar' }
> out = {{alias}}( { 'foo': 'bar' }, '' )
{ 'target': null, 'key': null, 'value': { 'foo': 'bar' } }
> out = {{alias}}( { 'foo': 'bar' }, '/missing' )
undefined

See Also
--------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
/**
* Parent container (object or array). Null for root pointer.
*/
target: Record<string, any> | Array<any> | null;

Check warning on line 28 in lib/node_modules/@stdlib/utils/json-pointer/resolve/docs/types/index.d.ts

View workflow job for this annotation

GitHub Actions / Lint Changed Files

Unexpected any. Specify a different type

Check warning on line 28 in lib/node_modules/@stdlib/utils/json-pointer/resolve/docs/types/index.d.ts

View workflow job for this annotation

GitHub Actions / Lint Changed Files

Unexpected any. Specify a different type

/**
* Final reference key. Null for root pointer.
Expand All @@ -35,7 +35,7 @@
/**
* Value at the pointer location.
*/
value: any;

Check warning on line 38 in lib/node_modules/@stdlib/utils/json-pointer/resolve/docs/types/index.d.ts

View workflow job for this annotation

GitHub Actions / Lint Changed Files

Unexpected any. Specify a different type
}

/**
Expand All @@ -45,15 +45,17 @@
*
* - Implements resolution per RFC 6901.
* - An empty string pointer refers to the root of the document.
* - If a pointer references a nonexistent location in the document, the function returns `undefined`.
* - The `-` token on the last segment of a pointer targeting an array resolves to the array's length (i.e., past-the-end index).
* - Tokens `__proto__`, `constructor`, and `prototype` are rejected to prevent prototype pollution.
*
* @param document - JSON document
* @param pointer - JSON Pointer string
* @throws pointer must resolve to an existing location in the document
* @throws first argument must be an object or an array
* @throws second argument must be a string
* @throws pointer must be an empty string or begin with `/`
* @throws tokens must not be prototype pollution vectors
* @throws array index must be within bounds
* @returns result object
* @returns result
*
* @example
* var out = resolve( { 'foo': [ 'bar', 'baz' ] }, '/foo/0' );
Expand All @@ -66,8 +68,12 @@
* @example
* var out = resolve( { 'foo': 'bar' }, '' );
* // returns { 'target': null, 'key': null, 'value': { 'foo': 'bar' } }
*
* @example
* var out = resolve( { 'foo': 'bar' }, '/missing' );
* // returns undefined
*/
declare function resolve( document: Record<string, any> | Array<any>, pointer: string ): ResolveResult;
declare function resolve( document: Record<string, any> | Array<any>, pointer: string ): ResolveResult | void;

Check warning on line 76 in lib/node_modules/@stdlib/utils/json-pointer/resolve/docs/types/index.d.ts

View workflow job for this annotation

GitHub Actions / Lint Changed Files

Unexpected any. Specify a different type

Check warning on line 76 in lib/node_modules/@stdlib/utils/json-pointer/resolve/docs/types/index.d.ts

View workflow job for this annotation

GitHub Actions / Lint Changed Files

Unexpected any. Specify a different type


// EXPORTS //
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ import resolve = require( './index' );

// TESTS //

// The function returns a resolve result object...
// The function returns a result object or `undefined`...
{
resolve( { 'foo': 'bar' }, '/foo' ); // $ExpectType ResolveResult
resolve( [ 1, 2, 3 ], '/0' ); // $ExpectType ResolveResult
resolve( { 'foo': 'bar' }, '' ); // $ExpectType ResolveResult
resolve( { 'foo': 'bar' }, '/foo' ); // $ExpectType void | ResolveResult
resolve( [ 1, 2, 3 ], '/0' ); // $ExpectType void | ResolveResult
resolve( { 'foo': 'bar' }, '' ); // $ExpectType void | ResolveResult
}

// The compiler throws an error if the function is provided a first argument which is not an object or array...
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,7 @@ console.log( out );
out = resolve( doc, '' );
console.log( out );
// => { 'target': null, 'key': null, 'value': { ... } }

out = resolve( doc, '/missing' );
console.log( out );
// => undefined
43 changes: 27 additions & 16 deletions lib/node_modules/@stdlib/utils/json-pointer/resolve/lib/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,17 @@ var resolveToken = require( '@stdlib/utils/json-pointer/base/resolve-token' );
*
* - Implements resolution per RFC 6901.
* - An empty string pointer refers to the root of the document.
* - If a pointer references a nonexistent location in the document, the function returns `undefined`.
* - The `-` token on the last segment of a pointer targeting an array resolves to the array's length (i.e., past-the-end index).
* - Tokens `__proto__`, `constructor`, and `prototype` are rejected to prevent prototype pollution.
*
* @param {(Object|Array)} document - JSON document
* @param {string} pointer - JSON Pointer string
* @throws {TypeError} first argument must be an object or array
* @throws {TypeError} first argument must be an object or an array
* @throws {TypeError} second argument must be a string
* @throws {Error} pointer must resolve to an existing location in the document
* @throws {Error} pointer must be an empty string or begin with `/`
* @throws {Error} tokens must not be prototype pollution vectors
* @throws {RangeError} array index must be within bounds
* @returns {Object} result object
* @returns {(Object|void)} result object or undefined
*
* @example
* var out = resolve( { 'foo': [ 'bar', 'baz' ] }, '/foo/0' );
Expand All @@ -61,6 +61,10 @@ var resolveToken = require( '@stdlib/utils/json-pointer/base/resolve-token' );
* @example
* var out = resolve( { 'foo': 'bar' }, '' );
* // returns { 'target': null, 'key': null, 'value': { 'foo': 'bar' } }
*
* @example
* var out = resolve( { 'foo': 'bar' }, '/missing' );
* // returns undefined
*/
function resolve( document, pointer ) {
var current;
Expand All @@ -76,6 +80,13 @@ function resolve( document, pointer ) {
}
tokens = parse( pointer );

// Validate all tokens upfront for security to guarantee deterministic rejection:
for ( i = 0; i < tokens.length; i++ ) {
if ( !isSafeToken( tokens[ i ] ) ) {
throw new Error( format( 'invalid argument. Pointer contains an unsafe token. Value: `%s`.', tokens[ i ] ) );
}
}

// An empty pointer refers to the root:
if ( tokens.length === 0 ) {
return {
Expand All @@ -91,42 +102,42 @@ function resolve( document, pointer ) {
// Traverse all tokens except the last to find the target:
for ( i = 0; i < last; i++ ) {
token = tokens[ i ];
if ( !isSafeToken( token ) ) {
throw new Error( format( 'invalid argument. Pointer contains an unsafe token. Value: `%s`.', token ) );
}
if ( isArray( current ) ) {
idx = resolveToken( current, token );
if ( idx >= current.length ) {
throw new RangeError( format( 'invalid argument. Array index out of bounds. Index: `%d`. Length: `%d`.', idx, current.length ) );
// Array index is out-of-bounds...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
current = current[ idx ];
} else if ( isPlainObject( current ) ) {
if ( !hasOwnProp( current, token ) ) {
throw new Error( format( 'invalid argument. Pointer references a nonexistent property. Value: `%s`.', token ) );
// Pointer references a nonexistent property...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
current = current[ token ];
} else {
throw new TypeError( format( 'invalid argument. Pointer references a non-traversable value. Value: `%s`.', token ) );
// Pointer references a non-traversable value...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
}

// Handle the last token to determine the final key and value:
token = tokens[ last ];
if ( !isSafeToken( token ) ) {
throw new Error( format( 'invalid argument. Pointer contains an unsafe token. Value: `%s`.', token ) );
}
if ( isArray( current ) ) {
key = resolveToken( current, token );
if ( token !== '-' && key >= current.length ) {
throw new RangeError( format( 'invalid argument. Array index out of bounds. Index: `%d`. Length: `%d`.', key, current.length ) );
// Array index is out-of-bounds...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
} else if ( isPlainObject( current ) ) {
if ( !hasOwnProp( current, token ) ) {
throw new Error( format( 'invalid argument. Pointer references a nonexistent property. Value: `%s`.', token ) );
// Pointer references a nonexistent property...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
key = token;
} else {
throw new TypeError( format( 'invalid argument. Pointer references a non-traversable value. Value: `%s`.', token ) );
// Pointer references a non-traversable value...
return;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
return {
'target': current,
Expand Down
41 changes: 15 additions & 26 deletions lib/node_modules/@stdlib/utils/json-pointer/resolve/test/test.js
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,10 @@ tape( 'the function throws an error for unsafe tokens', function test( t ) {
'/constructor',
'/prototype',
'/foo/__proto__',
'/foo/constructor'
'/foo/constructor',
'/missing/__proto__',
'/missing/constructor',
'/a/b/c/prototype'
];
for ( i = 0; i < values.length; i++ ) {
t.throws( badValue( values[ i ] ), Error, 'throws an error when provided ' + values[ i ] );
Expand All @@ -276,32 +279,27 @@ tape( 'the function throws an error for unsafe tokens', function test( t ) {
}
});

tape( 'the function throws an error for nonexistent object properties', function test( t ) {
tape( 'the function returns undefined for nonexistent object properties', function test( t ) {
var doc;

doc = {
'foo': 'bar'
};
t.throws( badValue, Error, 'throws an error when provided /missing' );
t.strictEqual( resolve( doc, '/missing' ), void 0, 'returns expected value' );
t.strictEqual( resolve( doc, '/missing/nested' ), void 0, 'returns expected value' );
t.end();

function badValue() {
resolve( doc, '/missing' );
}
});

tape( 'the function throws an error for out-of-bounds array indices', function test( t ) {
tape( 'the function returns undefined for out-of-bounds array indices', function test( t ) {
var doc;

doc = {
'foo': [ 1, 2, 3 ]
};
t.throws( badValue, RangeError, 'throws an error when provided /foo/5' );
t.strictEqual( resolve( doc, '/foo/3' ), void 0, 'returns expected value' );
t.strictEqual( resolve( doc, '/foo/5' ), void 0, 'returns expected value' );
t.strictEqual( resolve( doc, '/foo/5/bar' ), void 0, 'returns expected value' );
t.end();

function badValue() {
resolve( doc, '/foo/5' );
}
});

tape( 'the function throws an error for invalid array indices', function test( t ) {
Expand Down Expand Up @@ -330,25 +328,16 @@ tape( 'the function throws an error for invalid array indices', function test( t
}
});
Comment thread
kgryte marked this conversation as resolved.
Resolved

tape( 'the function throws an error when traversing into a primitive', function test( t ) {
tape( 'the function returns undefined when attempting to traverse into a primitive', function test( t ) {
var doc;

doc = {
'foo': 'bar'
};
t.throws( badValue1, TypeError, 'throws an error when traversing into a string' );

t.strictEqual( resolve( doc, '/foo/baz' ), void 0, 'returns expected value' );
doc = {
'foo': 42
};
t.throws( badValue2, TypeError, 'throws an error when traversing into a number' );
t.end();

function badValue1() {
resolve( doc, '/foo/baz' );
}
t.strictEqual( resolve( doc, '/foo/bar' ), void 0, 'returns expected value' );

function badValue2() {
resolve( doc, '/foo/bar' );
}
t.end();
});
Loading