Skip to content

Commit 13f1fd4

Browse files
dmaccormackdmaccormack
committed
feat: Add typescript declaration file
1 parent 4c058cc commit 13f1fd4

File tree

2 files changed

+351
-0
lines changed

2 files changed

+351
-0
lines changed

‎jsonurl.d.ts‎

Lines changed: 350 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
2+
/**
3+
* GetMissingValue function signature
4+
*/
5+
type GetMissingValue = {
6+
(key: string): any;
7+
};
8+
9+
/**
10+
* Options for the JsonURL.stringify function.
11+
*
12+
* @see https://github.com/jsonurl/specification#291-implied-arrays
13+
* @see https://github.com/jsonurl/specification#292-implied-objects
14+
* @see https://github.com/jsonurl/specification#293-x-www-form-urlencoded-arrays-and-objects
15+
* @see https://github.com/jsonurl/specification#295-empty-objects-and-arrays
16+
* @see https://github.com/jsonurl/specification#296-address-bar-query-string-friendly
17+
*/
18+
type JsonURLStringifyOptions = {
19+
/**
20+
* @type {boolean} [allowEmptyUnquotedKeys] Normally an empty string
21+
* value is represented as `''` (two single quotes). If this
22+
* is true the stringifier will omit a value rather than writing an
23+
* empty string.
24+
*/
25+
allowEmptyUnquotedValues?: boolean,
26+
/**
27+
* @type {boolean} [allowEmptyUnquotedKeys] Normally a key whose value is
28+
* the empty string is represented as `''` (two single quotes). If this
29+
* is true the stringifier will omit a value rather than writing an
30+
* empty string.
31+
*/
32+
allowEmptyUnquotedKeys?: boolean,
33+
/**
34+
* @type {boolean} [AQF] Enable the address bar query string friendly
35+
* (AQF) syntax option, and emit a string as oulined in section
36+
* 2.9.6 of the JSON→URL specification.
37+
*/
38+
AQF?: boolean,
39+
/**
40+
* @type {boolean} [coerceNullToEmptyString] Normally the stringifier will
41+
* emit a `null` value as a literal `null`. If this is true `null`
42+
* values will be coerced to the empty string.
43+
*/
44+
coerceNullToEmptyString?: boolean,
45+
/**
46+
* @type {Array<any>} [impliedArray] Emit an implied array
47+
* as oulined in section 2.9.1 of the JSON&#x2192;URL specification.
48+
*/
49+
impliedArray?: boolean,
50+
/**
51+
* @type {Object} [impliedObject] Emit an implied object
52+
* as oulined in section 2.9.1 of the JSON&#x2192;URL specification.
53+
*/
54+
impliedObject?: boolean,
55+
/**
56+
* @type {boolean} [impliedStringLiterals] If true the stringifier will
57+
* emit JSON&#x2192;URL text that assumes all literals are
58+
* strings.
59+
*/
60+
impliedStringLiterals?: boolean,
61+
/**
62+
* @type {boolean} [noEmptyComposite] Emit JSON&#x2192;URL text as
63+
* oulined in section 2.9.4 of the JSON&#x2192;URL specification.
64+
*/
65+
noEmptyComposite?: boolean,
66+
/**
67+
* @type {boolean} [wwwFormUrlEncoded] Emit x-www-form-urlencoded content
68+
* as oulined in section 2.9.3 of the JSON&#x2192;URL specification.
69+
*/
70+
wwwFormUrlEncoded?: boolean,
71+
/**
72+
* @type {boolean} [callFunctions] The stringifier will inspect each
73+
* value to see if it's a function.
74+
* If `callFunctions` is true then functions will be called to resolve
75+
* the value; otherwise, they will be omitted.
76+
*/
77+
callFunctions?: boolean,
78+
/**
79+
* @deprecated
80+
* @type {boolean} [isImplied] Emit an implied object or array. For
81+
* consistency with parse() use `impliedArray` or `impliedObject`.
82+
*/
83+
isImplied?: boolean,
84+
/**
85+
* @type {boolean} [ignoreNullArrayMembers=false] Ignore null array members.
86+
* This is `true` by default if impliedStringLiterals is true,
87+
* and `false` by default otherwise.
88+
*/
89+
ignoreNullArrayMembers?: boolean,
90+
/**
91+
* @type {boolean} [ignoreNullObjectMembers=false] Ignore null object
92+
* members. This is `true` by default if impliedStringLiterals is true,
93+
* and `false` by default otherwise.
94+
*/
95+
ignoreNullObjectMembers?: boolean,
96+
/**
97+
* @type {boolean} [ignoreUndefinedArrayMembers] Ignore undefined array
98+
* members. This is `true` by default if impliedStringLiterals is true,
99+
* and `false` by default otherwise. Undefined values will be stringified
100+
* as `null` because `undefined` is not a valid JSON value.
101+
*/
102+
ignoreUndefinedArrayMembers?: boolean,
103+
/**
104+
* @type {boolean} [ignoreUndefinedObjectMembers] Ignore undefined object
105+
* members. This is `true` by default if impliedStringLiterals is true,
106+
* and `false` by default otherwise. Undefined values will be stringified
107+
* as `null` because `undefined` is not a valid JSON value.
108+
*/
109+
ignoreUndefinedObjectMembers?: boolean,
110+
}
111+
112+
/**
113+
* Options for the JsonURL.parse function.
114+
*
115+
* @see https://github.com/jsonurl/specification#291-implied-arrays
116+
* @see https://github.com/jsonurl/specification#292-implied-objects
117+
* @see https://github.com/jsonurl/specification#293-x-www-form-urlencoded-arrays-and-objects
118+
* @see https://github.com/jsonurl/specification#294-implied-object-missing-values
119+
* @see https://github.com/jsonurl/specification#295-empty-objects-and-arrays
120+
* @see https://github.com/jsonurl/specification#296-address-bar-query-string-friendly
121+
*/
122+
type JsonURLParseOptions = {
123+
/**
124+
* @type {boolean} [allowEmptyUnquotedValues] Normally the empty string
125+
* is represented as `''` (two single quotes). This option allows the
126+
* parser to recognize an omitted value as the empty string. Note, in the
127+
* case of an object value the separator is still required.
128+
*/
129+
allowEmptyUnquotedValues?: boolean,
130+
/**
131+
* @type {boolean} [allowEmptyUnquotedKeys] Normally the empty string
132+
* is represented as `''` (two single quotes). This option allows the
133+
* parser to recognize an omitted object key as the empty string. Note,
134+
* the separator is still required.
135+
*/
136+
allowEmptyUnquotedKeys?: boolean,
137+
/**
138+
* @type {boolean} [AQF] Enable the address bar query string friendly
139+
* (AQF) syntax option, and implement the grammar oulined in section
140+
* 2.9.6 of the JSON&#x2192;URL specification.
141+
*/
142+
AQF?: boolean,
143+
/**
144+
* @type {boolean} [coerceNullToEmptyString] Normally the `null` literal
145+
* is parsed as a JavaScript `null` value, however, if this is true
146+
* then `null` literals will be coerced to the empty string.
147+
*/
148+
coerceNullToEmptyString?: boolean,
149+
/**
150+
* @type {Array<any>} [impliedArray] An implied array.
151+
*
152+
* If provied, parse will implement a parser for the grammar oulined in
153+
* section 2.9.1 of the JSON&#x2192;URL specification. The given parse
154+
* text is assumed to be an array, and the leading and trailing parens
155+
* must not be present. The given array value will be populated and
156+
* returned.
157+
*/
158+
impliedArray?: Array<any>,
159+
/**
160+
* @type {Object} [impliedObject] An implied object.
161+
*
162+
* If provided, parse will implement the grammar oulined in section 2.9.2
163+
* of the JSON&#x2192;URL specification. The given parse text is assumed
164+
* to be an object, and the leading and trailing parens must not be
165+
* present. The given object value will be populated and returned.
166+
*/
167+
impliedObject?: object,
168+
/**
169+
* @type {boolean} [impliedStringLiterals] Instruct the parser to assume
170+
* that all literals are strings. In this case, the single quote character
171+
* loses its significance and is parsed as-is.
172+
*/
173+
impliedStringLiterals?: boolean,
174+
/**
175+
* @type {boolean} [noEmptyComposite] Implement the grammar
176+
* oulined in section 2.9.4 of the JSON&#x2192;URL specification.
177+
*
178+
* If true, the parser will distinguish between empty array and empty
179+
* object. Empty array is back-to-back parens, e.g. `()`. Empty object
180+
* is two parens with a single colon inside, e.g. `(:)`. Note that this
181+
* prevents the parser from recognizing `(:)` as an object with a single
182+
* member whose key and value is the unquoted empty string when
183+
* `allowEmptyUnquotedValues` and `allowEmptyUnquotedValues` are also
184+
* both true.
185+
*/
186+
noEmptyComposite?: boolean,
187+
/**
188+
* @type {boolean} [wwwFormUrlEncoded] Implement the grammar oulined in
189+
* section 2.9.3 of the JSON&#x2192;URL specification.
190+
*
191+
* The given parse text is may use ampersand and equal characters as the
192+
* value and member separator characters, respetively, at the top-level.
193+
* This may be combined with `impliedArray` or `impliedObject`.
194+
*/
195+
wwwFormUrlEncoded?: boolean,
196+
/**
197+
* @param {*} [emptyValue] The value which represents the empty composite.
198+
* This may be any type. If it is a function then it will be called
199+
* until it resolves to something that is not a function. The default
200+
* is an empty Object.
201+
*/
202+
emptyValue?: any,
203+
/**
204+
* @type {function} [getMissingValue] Implement the grammar oulined in
205+
* section 2.9.4 of the JSON&#x2192;URL specification.
206+
*
207+
* This function provides a missing top-level value for the given key.
208+
*/
209+
getMissingValue?: GetMissingValue,
210+
/**
211+
* @type {*} [nullValue=null] The value which represents the `null` value.
212+
* This may be any type. If it is a function then it will be called
213+
* until it resolves to something that is not a function. The default
214+
* is `null`.
215+
*/
216+
nullValue?: any,
217+
/**
218+
* @type {number} [maxParseChars=65535] Maximum number of characters to
219+
* parse. The parse() method will throw an Error if it parses more than
220+
* this number of characters. The default is 64K.
221+
*/
222+
maxParseChars?: number,
223+
/**
224+
* @type {number} [maxParseDepth=64] Maximum parse depth.
225+
* The parse() method will throw an Error if the depth
226+
* of the input exceeds this value. The default is 64.
227+
*/
228+
maxParseDepth?: number,
229+
/**
230+
* @type {number} [maxParseValues=4096] Maximum number of values to parse.
231+
* The parse() method will throw an Error if it parses more than this
232+
* number of values. The default is 4096.
233+
*/
234+
maxParseValues?: number,
235+
}
236+
237+
declare class JsonURL {
238+
/**
239+
* Construct a new JsonURL class.
240+
*
241+
* Each instance of this class contains a number of properties that manage
242+
* the behavior of the parser and the values it returns; these are documented
243+
* below. The class instance does not manage parse state -- that is local to
244+
* the parse() function itself. As long as you don't need different
245+
* properties (e.g. limits, null value, etc) you may re-use the same Parser
246+
* instance, even by multiple Workers.
247+
* @param {Object} [prop] Initialization properties.
248+
* @deprecated this constructior will be removed and the JsonURL class
249+
* will simply have two static functions (mirroring the interface
250+
* of the JSON Object). These properties may be sent as options to
251+
* parse() and stringify().
252+
*/
253+
constructor(prop?: {
254+
/**
255+
* @type {number} [maxParseDepth=64] Maximum parse depth.
256+
* The parse() method will throw an Error if the depth
257+
* of the input exceeds this value. The default is 64.
258+
*/
259+
maxParseDepth?: number;
260+
/**
261+
* @type {number} [maxParseValues=4096] Maximum number of values to parse.
262+
* The parse() method will throw an Error if it parses more than this
263+
* number of values. The default is 4K.
264+
*/
265+
maxParseValues?: number;
266+
/**
267+
* @type {number} [maxParseChars=65535] Maximum number of characters to
268+
* parse. The parse() method will throw an Error if it parses more than
269+
* this number of characters. The default is 64K.
270+
*/
271+
maxParseChars?: number;
272+
/**
273+
* @param {*} [emptyValue] The value which represents the empty composite.
274+
* This may be any type. If it is a function then it will be called
275+
* until it resolves to something that is not a function. The default
276+
* is an empty Object.
277+
*/
278+
emptyValue?: any;
279+
/**
280+
* @type {*} [nullValue=null] The value which represents the `null` value.
281+
* This may be any type. If it is a function then it will be called
282+
* until it resolves to something that is not a function. The default
283+
* is `null`.
284+
*/
285+
nullValue?: any;
286+
});
287+
288+
/**
289+
* Parse JSON&#x2192;URL text and return a JavaScript value.
290+
*
291+
* The `text` parameter must be provided. The second parameter may be
292+
* either the index into `text` where the parse should start (a number)
293+
* or parse options. If an offset is provided then the third parameter
294+
* may be either the index into `text` where the parse should end (a
295+
* number) or parse options. If the an end index is provided then the
296+
* forth parameter may be parse options.
297+
*
298+
* @public
299+
* @param {string} text The text to parse.
300+
* @param {number|JsonURLParseOptions} [startOrOpt] index into `text`
301+
* where parse should start (a number) or parse options.
302+
* @param {number|JsonURLParseOptions} [endOrOpt] index into `text`
303+
* where parse should end (a number) or parse options.
304+
* @param {JsonURLParseOptions} [options] parse options.
305+
* @return {any} the parsed value
306+
* @throws SyntaxError if there is a syntax error in the given text
307+
* @throws Error if a limit given in the constructor (or its default)
308+
* is exceeded.
309+
*/
310+
static parse(text: string, startOrOpt?: number | JsonURLParseOptions, endOrOpt?: number | JsonURLParseOptions, options?: JsonURLParseOptions): any;
311+
312+
/**
313+
* Parse JSON&#x2192;URL text and return a JavaScript value.
314+
*
315+
* The `text` parameter must be provided. The second parameter may be
316+
* either the index into `text` where the parse should start (a number)
317+
* or parse options. If an offset is provided then the third parameter
318+
* may be either the index into `text` where the parse should end (a
319+
* number) or parse options. If the an end index is provided then the
320+
* forth parameter may be parse options.
321+
*
322+
* @param {string} text The text to parse.
323+
* @param {number|JsonURLParseOptions} [startOrOpt] index into `text`
324+
* where parse should start (a number) or parse options.
325+
* @param {number|JsonURLParseOptions} [endOrOpt] index into `text`
326+
* where parse should end (a number) or parse options.
327+
* @param {JsonURLParseOptions} [options] parse options.
328+
* @return {any} the parsed value
329+
* @throws SyntaxError if there is a syntax error in the given text
330+
* @throws Error if a limit given in the constructor (or its default)
331+
* is exceeded.
332+
* @deprecated this function will be removed and the JsonURL class
333+
* will simply have two static functions (mirroring the interface
334+
* of the JSON Object). Call `JsonURL.parse()` instead.
335+
*/
336+
parse(text: string, startOrOpt?: number | JsonURLParseOptions, endOrOpt?: number | JsonURLParseOptions, options?: JsonURLParseOptions): any;
337+
338+
/**
339+
* A static method for coverting a JavaScript value to JSON&#x2192;URL text.
340+
* @public
341+
* @param {*} value Any value
342+
* @param {JsonURLStringifyOptions} [options] stringify options.
343+
* @returns {string} JSON&#x2192;URL text, or `undefined` if the given value
344+
* is `undefined`.
345+
*/
346+
static stringify(value: any, options?: JsonURLStringifyOptions): string | undefined;
347+
}
348+
349+
export default JsonURL;
350+

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
"main": "dist/jsonurl.common.js",
99
"browser": "dist/jsonurl.min.js",
1010
"moduleName": "JsonURL",
11+
"types": "./jsonurl.d.ts",
1112
"scripts": {
1213
"build": "rollup -c",
1314
"test": "jest",

0 commit comments

Comments
 (0)