Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 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 object or void
Comment thread
kgryte marked this conversation as resolved.
Resolved
*
* @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 resolve result object or void...
Comment thread
kgryte marked this conversation as resolved.
Resolved
{
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
37 changes: 21 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,36 @@ 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 ) );
return void 0;
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 ) );
return void 0;
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 ) );
return void 0;
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 ) );
return void 0;
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 ) );
return void 0;
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 ) );
return void 0;
Comment thread
kgryte marked this conversation as resolved.
Resolved
}
return {
'target': current,
Expand Down
47 changes: 11 additions & 36 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 @@ -329,26 +327,3 @@ 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 ) {
var doc;

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

doc = {
'foo': 42
};
t.throws( badValue2, TypeError, 'throws an error when traversing into a number' );
t.end();

function badValue1() {
resolve( doc, '/foo/baz' );
}

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