From 5dba7b2a17a571fbacfe61161c8be39dde9211ce Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Wed, 27 Jan 2021 13:45:57 -0600 Subject: [PATCH 1/2] 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 ad3322e1347132d697d1ce51444ee74e77bd1d44 Mon Sep 17 00:00:00 2001 From: Jordan Tucker Date: Sun, 31 Jan 2021 19:18:01 -0600 Subject: [PATCH 2/2] 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