feat: add TypeScript delcarations for module files

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

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}

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<T = any>(
+    text: string,
+    reviver?: ((this: any, key: string, value: any) => any) | null,
+): T
+
+export = parse

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

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

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

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/',