From eef0999e6c47bb7779789a8884dd95cc03effc58 Mon Sep 17 00:00:00 2001 From: George Pickering <29524044+geopic@users.noreply.github.com> Date: Sun, 31 Jan 2021 18:47:42 +0000 Subject: [PATCH 1/6] feat: add types declaration file with entry in package.json --- lib/index.d.ts | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + 2 files changed, 77 insertions(+) create mode 100644 lib/index.d.ts diff --git a/lib/index.d.ts b/lib/index.d.ts new file mode 100644 index 00000000..c2b002af --- /dev/null +++ b/lib/index.d.ts @@ -0,0 +1,76 @@ +declare type StringifyOptions = Partial<{ + /** + * A function that alters the behavior of the stringification process, or an + * array of String and Number objects that serve as a whitelist for + * selecting/filtering the properties of the value object to be included in + * the JSON5 string. If this value is null or not provided, all properties + * of the object are included in the resulting JSON5 string. + */ + replacer: ((this: any, key: string, value: any) => any) | (string | number)[]; + + /** + * A String or Number object that's used to insert white space into the + * output JSON5 string for readability purposes. If this is a Number, it + * indicates the number of space characters to use as white space; this + * number is capped at 10 (if it is greater, the value is just 10). Values + * less than 1 indicate that no space should be used. If this is a String, + * the string (or the first 10 characters of the string, if it's longer than + * that) is used as white space. If this parameter is not provided (or is + * null), no white space is used. If white space is used, trailing commas + * will be used in objects and arrays. + */ + space: string | number; + + /** + * A String representing the quote character to use when serializing strings. + */ + quote: string; +}> + +/** + * Parses a JSON5 string, constructing the JavaScript value or object described + * by the string. An optional reviver function can be provided to perform a + * transformation on the resulting object before it is returned. + * @param text The string to parse as JSON5. + * @param reviver If a function, this prescribes how the value originally + * produced by parsing is transformed, before being returned. + */ +export function parse(text: string, reviver?: (this: any, key: string, value: any) => any): any; + +/** + * Converts a JavaScript value to a JSON5 string, optionally replacing values + * if a replacer function is specified, or optionally including only the + * specified properties if a replacer array is specified. + * @param value The value to convert to a JSON5 string. + * @param replacer A function that alters the behavior of the stringification + * process, or an array of String and Number objects that serve as a whitelist + * for selecting/filtering the properties of the value object to be included in + * the JSON5 string. If this value is null or not provided, all properties of + * the object are included in the resulting JSON5 string. + * @param space A String or Number object that's used to insert white space + * into the output JSON5 string for readability purposes. If this is a Number, + * it indicates the number of space characters to use as white space; this + * number is capped at 10 (if it is greater, the value is just 10). Values less + * than 1 indicate that no space should be used. If this is a String, the + * string (or the first 10 characters of the string, if it's longer than that) + * is used as white space. If this parameter is not provided (or is null), no + * white space is used. If white space is used, trailing commas will be used in + * objects and arrays. + */ +export function stringify(value: any, replacer?: ((this: any, key: string, value: any) => any) | (string | number)[], space?: string | number): string; + +/** + * Converts a JavaScript value to a JSON5 string, optionally replacing values + * if a replacer function is specified, or optionally including only the + * specified properties if a replacer array is specified. + * @param value The value to convert to a JSON5 string. + * @param options An object with the following properties: + * + * `replacer`: Same as the `replacer` parameter. + * + * `space`: Same as the `space` parameter. + * + * `quote`: A String representing the quote character to use when serializing + * strings. + */ +export function stringify(value: any, options?: StringifyOptions): string; diff --git a/package.json b/package.json index 9c5b82ea..3b3b79a5 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "module": "dist/index.mjs", "bin": "lib/cli.js", "browser": "dist/index.js", + "types": "lib/index.d.ts", "files": [ "lib/", "dist/" From 3dd26ac0bdec7db3a0ae54a6f22ebb7c197ce924 Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Wed, 27 Jan 2021 13:45:57 -0600 Subject: [PATCH 2/6] feat: add TypeScript delcarations for module files --- CHANGELOG.md | 10 ++++++ lib/index.d.ts | 78 ++-------------------------------------- lib/parse.d.ts | 15 ++++++++ lib/stringify.d.ts | 89 ++++++++++++++++++++++++++++++++++++++++++++++ lib/unicode.d.ts | 3 ++ lib/util.d.ts | 5 +++ package.json5 | 1 + 7 files changed, 126 insertions(+), 75 deletions(-) create mode 100644 lib/parse.d.ts create mode 100644 lib/stringify.d.ts create mode 100644 lib/unicode.d.ts create mode 100644 lib/util.d.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e6d09c9..538e9a5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +### Unreleased [[code][c-unreleased], [diff][d-unreleased]] + +[c-unreleased]: https://github.com/json5/json5/tree/master +[d-unreleased]: https://github.com/json5/json5/compare/v2.1.3...HEAD + +- New: Accurate and documented TypeScript declarations are now included. There + is no need to install `@types/json5`. ([#236], [#244]) + ### v2.1.3 [[code][c2.1.3], [diff][d2.1.3]] [c2.1.3]: https://github.com/json5/json5/tree/v2.1.3 @@ -342,3 +350,5 @@ parser for the regular JSON format. [#196]: https://github.com/json5/json5/issues/196 [#208]: https://github.com/json5/json5/issues/208 [#210]: https://github.com/json5/json5/issues/210 +[#236]: https://github.com/json5/json5/issues/236 +[#244]: https://github.com/json5/json5/issues/244 diff --git a/lib/index.d.ts b/lib/index.d.ts index c2b002af..1c45bca5 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -1,76 +1,4 @@ -declare type StringifyOptions = Partial<{ - /** - * A function that alters the behavior of the stringification process, or an - * array of String and Number objects that serve as a whitelist for - * selecting/filtering the properties of the value object to be included in - * the JSON5 string. If this value is null or not provided, all properties - * of the object are included in the resulting JSON5 string. - */ - replacer: ((this: any, key: string, value: any) => any) | (string | number)[]; +import parse = require('./parse') +import stringify = require('./stringify') - /** - * A String or Number object that's used to insert white space into the - * output JSON5 string for readability purposes. If this is a Number, it - * indicates the number of space characters to use as white space; this - * number is capped at 10 (if it is greater, the value is just 10). Values - * less than 1 indicate that no space should be used. If this is a String, - * the string (or the first 10 characters of the string, if it's longer than - * that) is used as white space. If this parameter is not provided (or is - * null), no white space is used. If white space is used, trailing commas - * will be used in objects and arrays. - */ - space: string | number; - - /** - * A String representing the quote character to use when serializing strings. - */ - quote: string; -}> - -/** - * Parses a JSON5 string, constructing the JavaScript value or object described - * by the string. An optional reviver function can be provided to perform a - * transformation on the resulting object before it is returned. - * @param text The string to parse as JSON5. - * @param reviver If a function, this prescribes how the value originally - * produced by parsing is transformed, before being returned. - */ -export function parse(text: string, reviver?: (this: any, key: string, value: any) => any): any; - -/** - * Converts a JavaScript value to a JSON5 string, optionally replacing values - * if a replacer function is specified, or optionally including only the - * specified properties if a replacer array is specified. - * @param value The value to convert to a JSON5 string. - * @param replacer A function that alters the behavior of the stringification - * process, or an array of String and Number objects that serve as a whitelist - * for selecting/filtering the properties of the value object to be included in - * the JSON5 string. If this value is null or not provided, all properties of - * the object are included in the resulting JSON5 string. - * @param space A String or Number object that's used to insert white space - * into the output JSON5 string for readability purposes. If this is a Number, - * it indicates the number of space characters to use as white space; this - * number is capped at 10 (if it is greater, the value is just 10). Values less - * than 1 indicate that no space should be used. If this is a String, the - * string (or the first 10 characters of the string, if it's longer than that) - * is used as white space. If this parameter is not provided (or is null), no - * white space is used. If white space is used, trailing commas will be used in - * objects and arrays. - */ -export function stringify(value: any, replacer?: ((this: any, key: string, value: any) => any) | (string | number)[], space?: string | number): string; - -/** - * Converts a JavaScript value to a JSON5 string, optionally replacing values - * if a replacer function is specified, or optionally including only the - * specified properties if a replacer array is specified. - * @param value The value to convert to a JSON5 string. - * @param options An object with the following properties: - * - * `replacer`: Same as the `replacer` parameter. - * - * `space`: Same as the `space` parameter. - * - * `quote`: A String representing the quote character to use when serializing - * strings. - */ -export function stringify(value: any, options?: StringifyOptions): string; +export {parse, stringify} diff --git a/lib/parse.d.ts b/lib/parse.d.ts new file mode 100644 index 00000000..8c8d883a --- /dev/null +++ b/lib/parse.d.ts @@ -0,0 +1,15 @@ +/** + * Parses a JSON5 string, constructing the JavaScript value or object described + * by the string. + * @template T The type of the return value. + * @param text The string to parse as JSON5. + * @param reviver A function that prescribes how the value originally produced + * by parsing is transformed before being returned. + * @returns The JavaScript value converted from the JSON5 string. + */ +declare function parse( + text: string, + reviver?: ((this: any, key: string, value: any) => any) | null, +): T + +export = parse diff --git a/lib/stringify.d.ts b/lib/stringify.d.ts new file mode 100644 index 00000000..3c348389 --- /dev/null +++ b/lib/stringify.d.ts @@ -0,0 +1,89 @@ +declare type StringifyOptions = { + /** + * A function that alters the behavior of the stringification process, or an + * array of String and Number objects that serve as a allowlist for + * selecting/filtering the properties of the value object to be included in + * the JSON5 string. If this value is null or not provided, all properties + * of the object are included in the resulting JSON5 string. + */ + replacer?: + | ((this: any, key: string, value: any) => any) + | (string | number)[] + | null + + /** + * A String or Number object that's used to insert white space into the + * output JSON5 string for readability purposes. If this is a Number, it + * indicates the number of space characters to use as white space; this + * number is capped at 10 (if it is greater, the value is just 10). Values + * less than 1 indicate that no space should be used. If this is a String, + * the string (or the first 10 characters of the string, if it's longer than + * that) is used as white space. If this parameter is not provided (or is + * null), no white space is used. If white space is used, trailing commas + * will be used in objects and arrays. + */ + space?: string | number | null + + /** + * A String representing the quote character to use when serializing + * strings. + */ + quote?: string | null +} + +/** + * Converts a JavaScript value to a JSON5 string. + * @param value The value to convert to a JSON5 string. + * @param replacer A function that alters the behavior of the stringification + * process. If this value is null or not provided, all properties of the object + * are included in the resulting JSON5 string. + * @param space A String or Number object that's used to insert white space into + * the output JSON5 string for readability purposes. If this is a Number, it + * indicates the number of space characters to use as white space; this number + * is capped at 10 (if it is greater, the value is just 10). Values less than 1 + * indicate that no space should be used. If this is a String, the string (or + * the first 10 characters of the string, if it's longer than that) is used as + * white space. If this parameter is not provided (or is null), no white space + * is used. If white space is used, trailing commas will be used in objects and + * arrays. + * @returns The JSON5 string converted from the JavaScript value. + */ +declare function stringify( + value: any, + replacer?: ((this: any, key: string, value: any) => any) | null, + space?: string | number | null, +): string + +/** + * Converts a JavaScript value to a JSON5 string. + * @param value The value to convert to a JSON5 string. + * @param replacer An array of String and Number objects that serve as a + * allowlist for selecting/filtering the properties of the value object to be + * included in the JSON5 string. If this value is null or not provided, all + * properties of the object are included in the resulting JSON5 string. + * @param space A String or Number object that's used to insert white space into + * the output JSON5 string for readability purposes. If this is a Number, it + * indicates the number of space characters to use as white space; this number + * is capped at 10 (if it is greater, the value is just 10). Values less than 1 + * indicate that no space should be used. If this is a String, the string (or + * the first 10 characters of the string, if it's longer than that) is used as + * white space. If this parameter is not provided (or is null), no white space + * is used. If white space is used, trailing commas will be used in objects and + * arrays. + * @returns The JSON5 string converted from the JavaScript value. + */ +declare function stringify( + value: any, + replacer: (string | number)[], + space?: string | number | null, +): string + +/** + * Converts a JavaScript value to a JSON5 string. + * @param value The value to convert to a JSON5 string. + * @param options An object specifying options. + * @returns The JSON5 string converted from the JavaScript value. + */ +declare function stringify(value: any, options: StringifyOptions): string + +export = stringify diff --git a/lib/unicode.d.ts b/lib/unicode.d.ts new file mode 100644 index 00000000..610f8057 --- /dev/null +++ b/lib/unicode.d.ts @@ -0,0 +1,3 @@ +export declare const Space_Separator: RegExp +export declare const ID_Start: RegExp +export declare const ID_Continue: RegExp diff --git a/lib/util.d.ts b/lib/util.d.ts new file mode 100644 index 00000000..a940cead --- /dev/null +++ b/lib/util.d.ts @@ -0,0 +1,5 @@ +export declare function isSpaceSeparator(c?: string): boolean +export declare function isIdStartChar(c?: string): boolean +export declare function isIdContinueChar(c?: string): boolean +export declare function isDigit(c?: string): boolean +export declare function isHexDigit(c?: string): boolean diff --git a/package.json5 b/package.json5 index f3fc10bd..f890d644 100644 --- a/package.json5 +++ b/package.json5 @@ -7,6 +7,7 @@ module: 'dist/index.mjs', bin: 'lib/cli.js', browser: 'dist/index.js', + types: 'lib/index.d.ts', files: [ 'lib/', 'dist/', From 4d0560c1b16d827f46339dc7cf2ea05500298b5f Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Sun, 31 Jan 2021 19:18:01 -0600 Subject: [PATCH 3/6] docs: add missing links to CHANGELOG --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 538e9a5e..86ec7b20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -350,5 +350,8 @@ parser for the regular JSON format. [#196]: https://github.com/json5/json5/issues/196 [#208]: https://github.com/json5/json5/issues/208 [#210]: https://github.com/json5/json5/issues/210 +[#222]: https://github.com/json5/json5/issues/222 +[#228]: https://github.com/json5/json5/issues/228 +[#229]: https://github.com/json5/json5/issues/229 [#236]: https://github.com/json5/json5/issues/236 [#244]: https://github.com/json5/json5/issues/244 From 39ad97c006ae8c961cd2e5910bb032bce8ac2264 Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Sun, 31 Jan 2021 19:48:27 -0600 Subject: [PATCH 4/6] docs: update Travis CI badge --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4f803270..6049d02c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # JSON5 – JSON for Humans -[![Build Status](https://travis-ci.org/json5/json5.svg)][Build Status] +[![Build Status](https://travis-ci.com/json5/json5.svg)][Build Status] [![Coverage Status](https://coveralls.io/repos/github/json5/json5/badge.svg)][Coverage Status] @@ -12,7 +12,7 @@ some productions from [ECMAScript 5.1]. This JavaScript library is the official reference implementation for JSON5 parsing and serialization libraries. -[Build Status]: https://travis-ci.org/json5/json5 +[Build Status]: https://travis-ci.com/json5/json5 [Coverage Status]: https://coveralls.io/github/json5/json5 From a14feb050fddd5ced20596355a2531273b986b09 Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Sun, 31 Jan 2021 19:52:45 -0600 Subject: [PATCH 5/6] docs: update CHANGELOG for v2.2.0 --- CHANGELOG.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86ec7b20..5b9aa0d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,12 @@ ### Unreleased [[code][c-unreleased], [diff][d-unreleased]] [c-unreleased]: https://github.com/json5/json5/tree/master -[d-unreleased]: https://github.com/json5/json5/compare/v2.1.3...HEAD +[d-unreleased]: https://github.com/json5/json5/compare/v2.2.0...HEAD + +### v2.2.0 [[code][c2.2.0], [diff][d2.2.0]] + +[c2.2.0]: https://github.com/json5/json5/tree/v2.2.0 +[d2.2.0]: https://github.com/json5/json5/compare/v2.1.3...v2.2.0 - New: Accurate and documented TypeScript declarations are now included. There is no need to install `@types/json5`. ([#236], [#244]) From 4cf57da675f55c619f959132eb58a5683ca4a9c7 Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Sun, 31 Jan 2021 19:53:09 -0600 Subject: [PATCH 6/6] 2.2.0 --- package-lock.json | 2 +- package.json | 2 +- package.json5 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 92d5e881..56c0f4de 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "json5", - "version": "2.1.3", + "version": "2.2.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 3b3b79a5..31c43e5f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "json5", - "version": "2.1.3", + "version": "2.2.0", "description": "JSON for humans.", "main": "lib/index.js", "module": "dist/index.mjs", diff --git a/package.json5 b/package.json5 index f890d644..afcfbe26 100644 --- a/package.json5 +++ b/package.json5 @@ -1,7 +1,7 @@ // This is a generated file. Do not edit. { name: 'json5', - version: '2.1.3', + version: '2.2.0', description: 'JSON for humans.', main: 'lib/index.js', module: 'dist/index.mjs',