diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/README.md b/lib/node_modules/@stdlib/utils/json-pointer/parse/README.md new file mode 100644 index 000000000000..a640ee52f3ab --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/README.md @@ -0,0 +1,128 @@ + + +# parse + +> Parse a [JSON Pointer][json-pointer] ([RFC 6901][rfc-6901]) string into an array of reference tokens. + +
+ +## Usage + +```javascript +var parse = require( '@stdlib/utils/json-pointer/parse' ); +``` + +#### parse( pointer ) + +Parses a [JSON Pointer][json-pointer] string into an array of unescaped reference tokens. + +```javascript +var tokens = parse( '/foo/bar' ); +// returns [ 'foo', 'bar' ] + +tokens = parse( '/a~1b/c~0d' ); +// returns [ 'a/b', 'c~d' ] + +tokens = parse( '' ); +// returns [] +``` + +
+ + + +
+ +## Notes + +- Per [RFC 6901][rfc-6901], an empty string refers to the root of the document and returns an empty array `[]`. +- Non-empty pointers must begin with a `/` character. +- Escape sequences are decoded sequentially: `~1` is unescaped to `/` before `~0` is unescaped to `~`. + +
+ + + +
+ + + +## Examples + +```javascript +var parse = require( '@stdlib/utils/json-pointer/parse' ); + +var tokens = parse( '/foo/bar' ); +// returns [ 'foo', 'bar' ] + +tokens = parse( '/foo/0' ); +// returns [ 'foo', '0' ] + +tokens = parse( '/a~1b/c~0d' ); +// returns [ 'a/b', 'c~d' ] + +tokens = parse( '/~01' ); +// returns [ '~1' ] + +tokens = parse( '/' ); +// returns [ '' ] + +tokens = parse( '' ); +// returns [] +``` + +
+ + + + + +
+ +## References + +- [RFC 6901 - JavaScript Object Notation (JSON) Pointer][rfc-6901] + +
+ + + + + +
+ +
+ + + + + +
+ +[json-pointer]: https://datatracker.ietf.org/doc/html/rfc6901 + +[rfc-6901]: https://datatracker.ietf.org/doc/html/rfc6901 + + + +
+ + diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/benchmark/benchmark.js b/lib/node_modules/@stdlib/utils/json-pointer/parse/benchmark/benchmark.js new file mode 100644 index 000000000000..05ae0c150c96 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/benchmark/benchmark.js @@ -0,0 +1,105 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var parse = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:shallow', pkg ), function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = parse( '/foo/bar' ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( out.length !== 2 ) { + b.fail( 'should return expected tokens' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:escaped', pkg), function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = parse( '/a~1b/c~0d/foo/0' ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( out.length !== 4 ) { + b.fail( 'should return expected tokens' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:deep', pkg ), function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = parse( '/a/b/c/d/e/f/g/h' ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( out.length !== 8 ) { + b.fail( 'should return expected tokens' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:root', pkg ), function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = parse( '' ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( out.length !== 0 ) { + b.fail( 'should return empty array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/repl.txt b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/repl.txt new file mode 100644 index 000000000000..24b10d9d2f6f --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/repl.txt @@ -0,0 +1,32 @@ + +{{alias}}( pointer ) + Parses a JSON Pointer string into an array of reference tokens. + + Per RFC 6901, an empty string refers to the root and returns an empty array. + Non-empty pointers must begin with a '/' character. + + Escape sequences are decoded: `~1` is unescaped to `/` before `~0` is + unescaped to `~`. + + Parameters + ---------- + pointer: string + JSON Pointer string. + + Returns + ------- + tokens: Array + Array of reference tokens. + + Examples + -------- + > var tokens = {{alias}}( '/foo/bar' ) + [ 'foo', 'bar' ] + > tokens = {{alias}}( '/a~1b/c~0d' ) + [ 'a/b', 'c~d' ] + > tokens = {{alias}}( '' ) + [] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/index.d.ts b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/index.d.ts new file mode 100644 index 000000000000..5cad1c6fdf85 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/index.d.ts @@ -0,0 +1,52 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +// TypeScript Version: 4.1 + +/** +* Parses a JSON Pointer string into an array of reference tokens. +* +* ## Notes +* +* - Implements parsing per RFC 6901. +* - An empty string returns an empty array (refers to the root of the document). +* - Escape sequences are decoded: `~1` is unescaped to `/` before `~0` is unescaped to `~`. +* +* @param pointer - JSON Pointer string +* @throws must provide a string +* @throws pointer must be empty or start with a `/` character +* @returns array of reference tokens +* +* @example +* var tokens = parse( '/foo/bar' ); +* // returns [ 'foo', 'bar' ] +* +* @example +* var tokens = parse( '/a~1b/c~0d' ); +* // returns [ 'a/b', 'c~d' ] +* +* @example +* var tokens = parse( '' ); +* // returns [] +*/ +declare function parse( pointer: string ): Array; + + +// EXPORTS // + +export = parse; diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/test.ts b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/test.ts new file mode 100644 index 000000000000..906503ad538c --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/docs/types/test.ts @@ -0,0 +1,45 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +import parse = require( './index' ); + + +// TESTS // + +// The function returns an array of strings... +{ + parse( '/foo/bar' ); // $ExpectType string[] + parse( '' ); // $ExpectType string[] +} + +// The compiler throws an error if the function is provided an argument which is not a string... +{ + parse( 123 ); // $ExpectError + parse( true ); // $ExpectError + parse( false ); // $ExpectError + parse( null ); // $ExpectError + parse( undefined ); // $ExpectError + parse( [] ); // $ExpectError + parse( {} ); // $ExpectError +} + +// The compiler throws an error if the function is provided an invalid number of arguments... +{ + parse(); // $ExpectError + parse( '/foo', 2 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/examples/index.js b/lib/node_modules/@stdlib/utils/json-pointer/parse/examples/index.js new file mode 100644 index 000000000000..f59755225590 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/examples/index.js @@ -0,0 +1,45 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +var parse = require( './../lib' ); + +var tokens = parse( '/foo/bar' ); +console.log( tokens ); +// => [ 'foo', 'bar' ] + +tokens = parse( '/foo/0' ); +console.log( tokens ); +// => [ 'foo', '0' ] + +tokens = parse( '/a~1b/c~0d' ); +console.log( tokens ); +// => [ 'a/b', 'c~d' ] + +tokens = parse( '/~01' ); +console.log( tokens ); +// => [ '~1' ] + +tokens = parse( '/' ); +console.log( tokens ); +// => [ '' ] + +tokens = parse( '' ); +console.log( tokens ); +// => [] diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/index.js b/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/index.js new file mode 100644 index 000000000000..3afb471ac503 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/index.js @@ -0,0 +1,46 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/** +* Parse a JSON Pointer string into an array of reference tokens. +* +* @module @stdlib/utils/json-pointer/parse +* +* @example +* var parse = require( '@stdlib/utils/json-pointer/parse' ); +* +* var tokens = parse( '/foo/bar' ); +* // returns [ 'foo', 'bar' ] +* +* tokens = parse( '/a~1b/c~0d' ); +* // returns [ 'a/b', 'c~d' ] +* +* tokens = parse( '' ); +* // returns [] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/main.js b/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/main.js new file mode 100644 index 000000000000..2207d52ea643 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/lib/main.js @@ -0,0 +1,85 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var isString = require( '@stdlib/assert/is-string' ).isPrimitive; +var format = require( '@stdlib/string/format' ); + + +// MAIN // + +/** +* Parses a JSON Pointer string into an array of reference tokens. +* +* ## Notes +* +* - Implements parsing per RFC 6901. +* - An empty string returns an empty array (refers to the root of the document). +* - Escape sequences are decoded: `~1` is unescaped to `/` before `~0` is unescaped to `~`. +* +* @param {string} pointer - JSON Pointer string +* @throws {TypeError} must provide a string +* @throws {Error} pointer must be empty or start with a `/` character +* @returns {Array} array of unescaped reference tokens +* +* @example +* var tokens = parse( '/foo/bar' ); +* // returns [ 'foo', 'bar' ] +* +* @example +* var tokens = parse( '/a~1b/c~0d' ); +* // returns [ 'a/b', 'c~d' ] +* +* @example +* var tokens = parse( '' ); +* // returns [] +*/ +function parse( pointer ) { + var tokens; + var i; + + if ( !isString( pointer ) ) { + throw new TypeError( format( 'invalid argument. Must provide a string. Value: `%s`.', pointer ) ); + } + // An empty string refers to the root of the document: + if ( pointer === '' ) { + return []; + } + // Per RFC 6901, a non-empty pointer MUST begin with '/': + if ( pointer.charAt( 0 ) !== '/' ) { + throw new Error( format( 'invalid argument. JSON Pointer must be an empty string or start with a `/` character. Value: `%s`.', pointer ) ); + } + + tokens = pointer.split( '/' ); + tokens = tokens.slice( 1 ); + + // Unescape reference tokens per RFC 6901 (note: '~1' must be replaced before '~0' to avoid corrupting sequences such as '~01'): + for ( i = 0; i < tokens.length; i++ ) { + tokens[ i ] = tokens[ i ].replace( /~1/g, '/' ); + tokens[ i ] = tokens[ i ].replace( /~0/g, '~' ); + } + return tokens; +} + + +// EXPORTS // + +module.exports = parse; diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/package.json b/lib/node_modules/@stdlib/utils/json-pointer/parse/package.json new file mode 100644 index 000000000000..d7856c3ac946 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/package.json @@ -0,0 +1,71 @@ +{ + "name": "@stdlib/utils/json-pointer/parse", + "version": "0.0.0", + "description": "Parse a JSON Pointer string into an array of reference tokens.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdutils", + "stdutil", + "utilities", + "utility", + "utils", + "util", + "json", + "pointer", + "json-pointer", + "rfc6901", + "rfc", + "6901", + "parse", + "tokenize", + "decode", + "reference", + "token" + ] +} diff --git a/lib/node_modules/@stdlib/utils/json-pointer/parse/test/test.js b/lib/node_modules/@stdlib/utils/json-pointer/parse/test/test.js new file mode 100644 index 000000000000..0bd0da858305 --- /dev/null +++ b/lib/node_modules/@stdlib/utils/json-pointer/parse/test/test.js @@ -0,0 +1,131 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var parse = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof parse, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if not provided a string', function test( t ) { + var values; + var i; + + values = [ + 5, + NaN, + true, + null, + void 0, + [], + {}, + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), TypeError, 'throws an error when provided ' + values[ i ] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + parse( value ); + }; + } +}); + +tape( 'the function throws an error if pointer does not start with `/`', function test( t ) { + var values; + var i; + + values = [ + 'foo', + 'foo/bar', + 'a/b/c', + ' ' + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), Error, 'throws an error when provided ' + values[ i ] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + parse( value ); + }; + } +}); + +tape( 'the function returns an empty array for the root pointer ("")', function test( t ) { + var tokens = parse( '' ); + t.deepEqual( tokens, [], 'returns expected value' ); + t.end(); +}); + +tape( 'the function parses a JSON pointer', function test( t ) { + var expected; + var values; + var i; + + values = [ + '/foo/bar', + '/foo', + '/a~1b/c~0d', + '/~01', + '/', + '//', + '/foo/-', + '/foo/0/bar/12', + '/ ', + '/c%d', + '/e^f', + '/g|h', + '/i\\j', + '/k"l' + ]; + expected = [ + [ 'foo', 'bar' ], + [ 'foo' ], + [ 'a/b', 'c~d' ], + [ '~1' ], + [ '' ], + [ '', '' ], + [ 'foo', '-' ], + [ 'foo', '0', 'bar', '12' ], + [ ' ' ], + [ 'c%d' ], + [ 'e^f' ], + [ 'g|h' ], + [ 'i\\j' ], + [ 'k"l' ] + ]; + + for ( i = 0; i < values.length; i++ ) { + t.deepEqual( parse( values[ i ] ), expected[ i ], 'returns expected value' ); + } + t.end(); +});