diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e6d09c9..5b9aa0d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,16 @@ +### 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.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]) + ### 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 +355,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 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 diff --git a/lib/index.d.ts b/lib/index.d.ts new file mode 100644 index 00000000..1c45bca5 --- /dev/null +++ b/lib/index.d.ts @@ -0,0 +1,4 @@ +import parse = require('./parse') +import stringify = require('./stringify') + +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-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 9c5b82ea..31c43e5f 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,12 @@ { "name": "json5", - "version": "2.1.3", + "version": "2.2.0", "description": "JSON for humans.", "main": "lib/index.js", "module": "dist/index.mjs", "bin": "lib/cli.js", "browser": "dist/index.js", + "types": "lib/index.d.ts", "files": [ "lib/", "dist/" diff --git a/package.json5 b/package.json5 index f3fc10bd..afcfbe26 100644 --- a/package.json5 +++ b/package.json5 @@ -1,12 +1,13 @@ // 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', bin: 'lib/cli.js', browser: 'dist/index.js', + types: 'lib/index.d.ts', files: [ 'lib/', 'dist/',