Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
11 changes: 9 additions & 2 deletions lib/node_modules/@stdlib/utils/json-pointer/resolve/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ limitations under the License.

# resolve

> Resolve a [JSON Pointer][json-pointer] ([RFC 6901][rfc-6901]) against a document and return the target, key, and value.
> Resolve a [JSON Pointer][json-pointer] ([RFC 6901][rfc-6901]) against a document and return the target, key, and value, or undefined if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved

<section class="usage">

Expand All @@ -32,7 +32,7 @@ var resolve = require( '@stdlib/utils/json-pointer/resolve' );

#### resolve( document, pointer )

Resolves a [JSON Pointer][json-pointer] against a document and returns an object with `target`, `key`, and `value` properties.
Resolves a [JSON Pointer][json-pointer] against a document and returns an object with `target`, `key`, and `value` properties, or `undefined` if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved

```javascript
var obj = {
Expand All @@ -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
@@ -1,10 +1,13 @@

{{alias}}( document, pointer )
Resolves a JSON Pointer against a document and returns the target
container, key, and value.
container, key, and value, or undefined if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved

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,25 +35,27 @@
/**
* 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
}

/**
* Resolves a JSON Pointer against a document and returns the target, key, and value.
* Resolves a JSON Pointer against a document and returns the target, key, and value, or undefined if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved
*
* ## Notes
*
* - 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
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
'use strict';

/**
* Resolve a JSON Pointer against a document and return the target, key, and value.
* Resolve a JSON Pointer against a document and return the target, key, and value, or undefined if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved
*
* @module @stdlib/utils/json-pointer/resolve
*
Expand Down
39 changes: 22 additions & 17 deletions lib/node_modules/@stdlib/utils/json-pointer/resolve/lib/main.js
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,23 @@ var resolveToken = require( '@stdlib/utils/json-pointer/base/resolve-token' );
// MAIN //

/**
* Resolves a JSON Pointer against a document and returns the target, key, and value.
* Resolves a JSON Pointer against a document and returns the target, key, and value, or undefined if the pointer cannot be resolved.
Comment thread
kgryte marked this conversation as resolved.
Resolved
*
* ## Notes
*
* - 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
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@stdlib/utils/json-pointer/resolve",
"version": "0.0.0",
"description": "Resolve a JSON Pointer against a document and return the target, key, and value.",
"description": "Resolve a JSON Pointer against a document and return the target, key, and value, or undefined if the pointer cannot be resolved.",
Comment thread
kgryte marked this conversation as resolved.
Resolved
"license": "Apache-2.0",
"author": {
"name": "The Stdlib Authors",
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