Skip to content

Commit 63143ea

Browse files
medfreemanmedfreeman
committed
fix: change uriDetails type to URIComponents from uri-js package
1 parent 3371c1e commit 63143ea

File tree

3 files changed

+152
-138
lines changed

3 files changed

+152
-138
lines changed

‎gulpfile.js‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,8 @@ gulp.task('dist', function (done) {
9191

9292
gulp.task('docs-ts-raw', function (done) {
9393
gulp.src([
94-
'./index.js',
95-
'./lib/typedefs.js'
94+
'./lib/typedefs.js',
95+
'./index.js'
9696
])
9797
.pipe($.jsdoc3({
9898
opts: {
@@ -112,6 +112,8 @@ gulp.task('docs-ts', ['docs-ts-raw'], function () {
112112
.pipe($.replace('module:json-refs~', ''))
113113
.pipe($.replace('module:json-refs.', ''))
114114
.pipe($.replace('Promise.<', 'Promise<'))
115+
.pipe($.replace(/declare\smodule\s'uri-js'\s{(?:[\s\S])+?{(?:[\s\S])+?}(?:[\s\S])+?}/, 'import { URIComponents } from \'uri-js\';'))
116+
.pipe($.replace('module:uri-js~', ''))
115117
.pipe(gulp.dest('.'));
116118
});
117119

‎index.d.ts‎

Lines changed: 137 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,10 @@
1+
import { URIComponents } from 'uri-js';
2+
13
/**
24
* Various utilities for JSON References *(http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)* and
35
* JSON Pointers *(https://tools.ietf.org/html/rfc6901)*.
46
*/
57
declare module 'json-refs' {
6-
/**
7-
* Clears the internal cache of remote documents, reference details, etc.
8-
*/
9-
export function clearCache(): void;
10-
11-
/**
12-
* Takes an array of path segments and decodes the JSON Pointer tokens in them.
13-
* @param path - The array of path segments
14-
* @returns the array of path segments with their JSON Pointer tokens decoded
15-
* @throws if the path is not an `Array`
16-
* @see
17-
*/
18-
export function decodePath(path: string[]): string[];
19-
20-
/**
21-
* Takes an array of path segments and encodes the special JSON Pointer characters in them.
22-
* @param path - The array of path segments
23-
* @returns the array of path segments with their JSON Pointer tokens encoded
24-
* @throws if the path is not an `Array`
25-
* @see
26-
*/
27-
export function encodePath(path: string[]): string[];
28-
29-
/**
30-
* Finds JSON References defined within the provided array/object.
31-
* @param obj - The structure to find JSON References within
32-
* @param options - The JsonRefs options
33-
* @returns an object whose keys are JSON Pointers
34-
* *(fragment version)* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails}.
35-
* @throws when the input arguments fail validation or if `options.subDocPath` points to an invalid location
36-
*/
37-
export function findRefs(obj: any[] | object, options?: JsonRefsOptions): { [key: string]: (UnresolvedRefDetails|undefined) };
38-
39-
/**
40-
* Finds JSON References defined within the document at the provided location.
41-
*
42-
* This API is identical to {@link findRefs} except this API will retrieve a remote document and then
43-
* return the result of {@link findRefs} on the retrieved document.
44-
* @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
45-
* {@link JsonRefsOptions|options documentation} to see how relative references are handled.)*
46-
* @param options - The JsonRefs options
47-
* @returns a promise that resolves a
48-
* {@link RetrievedRefsResults} and rejects with an `Error` when the input arguments fail validation,
49-
* when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable
50-
* resource
51-
*/
52-
export function findRefsAt(location: string, options?: JsonRefsOptions): Promise<RetrievedRefsResults>;
53-
54-
/**
55-
* Returns detailed information about the JSON Reference.
56-
* @param obj - The JSON Reference definition
57-
* @returns the detailed information
58-
*/
59-
export function getRefDetails(obj: object): UnresolvedRefDetails;
60-
61-
/**
62-
* Returns whether the argument represents a JSON Pointer.
63-
*
64-
* A string is a JSON Pointer if the following are all true:
65-
*
66-
* * The string is of type `String`
67-
* * The string must be empty, `#` or start with a `/` or `#/`
68-
* @param ptr - The string to check
69-
* @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value
70-
* provided is invalid
71-
* @returns the result of the check
72-
* @throws when the provided value is invalid and the `throwWithDetails` argument is `true`
73-
* @see
74-
*/
75-
export function isPtr(ptr: string, throwWithDetails?: boolean): boolean;
76-
77-
/**
78-
* Returns whether the argument represents a JSON Reference.
79-
*
80-
* An object is a JSON Reference only if the following are all true:
81-
*
82-
* * The object is of type `Object`
83-
* * The object has a `$ref` property
84-
* * The `$ref` property is a valid URI *(We do not require 100% strict URIs and will handle unescaped special
85-
* characters.)*
86-
* @param obj - The object to check
87-
* @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value
88-
* provided is invalid
89-
* @returns the result of the check
90-
* @throws when the provided value is invalid and the `throwWithDetails` argument is `true`
91-
* @see
92-
*/
93-
export function isRef(obj: object, throwWithDetails?: boolean): boolean;
94-
95-
/**
96-
* Returns an array of path segments for the provided JSON Pointer.
97-
* @param ptr - The JSON Pointer
98-
* @returns the path segments
99-
* @throws if the provided `ptr` argument is not a JSON Pointer
100-
*/
101-
export function pathFromPtr(ptr: string): string[];
102-
103-
/**
104-
* Returns a JSON Pointer for the provided array of path segments.
105-
*
106-
* **Note:** If a path segment in `path` is not a `String`, it will be converted to one using `JSON.stringify`.
107-
* @param path - The array of path segments
108-
* @param hashPrefix - Whether or not create a hash-prefixed JSON Pointer
109-
* @returns the corresponding JSON Pointer
110-
* @throws if the `path` argument is not an array
111-
*/
112-
export function pathToPtr(path: string[], hashPrefix?: boolean): string;
113-
114-
/**
115-
* Finds JSON References defined within the provided array/object and resolves them.
116-
* @param obj - The structure to find JSON References within
117-
* @param options - The JsonRefs options
118-
* @returns a promise that resolves a
119-
* {@link ResolvedRefsResults} and rejects with an `Error` when the input arguments fail validation,
120-
* when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable
121-
* resource
122-
*/
123-
export function resolveRefs(obj: any[] | object, options?: JsonRefsOptions): Promise<ResolvedRefsResults>;
124-
125-
/**
126-
* Resolves JSON References defined within the document at the provided location.
127-
*
128-
* This API is identical to {@link resolveRefs} except this API will retrieve a remote document and
129-
* then return the result of {@link resolveRefs} on the retrieved document.
130-
* @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
131-
* {@link JsonRefsOptions|options documentation} to see how relative references are handled.)*
132-
* @param options - The JsonRefs options
133-
* @returns a promise that resolves a
134-
* {@link RetrievedResolvedRefsResults} and rejects with an `Error` when the input arguments fail
135-
* validation, when `options.subDocPath` points to an invalid location or when the location argument points to an
136-
* unloadable resource
137-
*/
138-
export function resolveRefsAt(location: string, options?: JsonRefsOptions): Promise<RetrievedResolvedRefsResults>;
139-
1408
/**
1419
* The options used for various JsonRefs APIs.
14210
*/
@@ -304,7 +172,7 @@ declare module 'json-refs' {
304172
* Detailed information about the URI as provided by
305173
* {@link https://github.com/garycourt/uri-js|URI.parse}.
306174
*/
307-
uriDetails: object;
175+
uriDetails: URIComponents;
308176
/**
309177
* The JSON Reference type *(This value can be one of the following: `invalid`, `local`,
310178
* `relative` or `remote`.)*
@@ -317,5 +185,139 @@ declare module 'json-refs' {
317185
warning?: string;
318186
}
319187

188+
/**
189+
* Clears the internal cache of remote documents, reference details, etc.
190+
*/
191+
export function clearCache(): void;
192+
193+
/**
194+
* Takes an array of path segments and decodes the JSON Pointer tokens in them.
195+
* @param path - The array of path segments
196+
* @returns the array of path segments with their JSON Pointer tokens decoded
197+
* @throws if the path is not an `Array`
198+
* @see
199+
*/
200+
export function decodePath(path: string[]): string[];
201+
202+
/**
203+
* Takes an array of path segments and encodes the special JSON Pointer characters in them.
204+
* @param path - The array of path segments
205+
* @returns the array of path segments with their JSON Pointer tokens encoded
206+
* @throws if the path is not an `Array`
207+
* @see
208+
*/
209+
export function encodePath(path: string[]): string[];
210+
211+
/**
212+
* Finds JSON References defined within the provided array/object.
213+
* @param obj - The structure to find JSON References within
214+
* @param options - The JsonRefs options
215+
* @returns an object whose keys are JSON Pointers
216+
* *(fragment version)* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails}.
217+
* @throws when the input arguments fail validation or if `options.subDocPath` points to an invalid location
218+
*/
219+
export function findRefs(obj: any[] | object, options?: JsonRefsOptions): { [key: string]: (UnresolvedRefDetails|undefined) };
220+
221+
/**
222+
* Finds JSON References defined within the document at the provided location.
223+
*
224+
* This API is identical to {@link findRefs} except this API will retrieve a remote document and then
225+
* return the result of {@link findRefs} on the retrieved document.
226+
* @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
227+
* {@link JsonRefsOptions|options documentation} to see how relative references are handled.)*
228+
* @param options - The JsonRefs options
229+
* @returns a promise that resolves a
230+
* {@link RetrievedRefsResults} and rejects with an `Error` when the input arguments fail validation,
231+
* when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable
232+
* resource
233+
*/
234+
export function findRefsAt(location: string, options?: JsonRefsOptions): Promise<RetrievedRefsResults>;
235+
236+
/**
237+
* Returns detailed information about the JSON Reference.
238+
* @param obj - The JSON Reference definition
239+
* @returns the detailed information
240+
*/
241+
export function getRefDetails(obj: object): UnresolvedRefDetails;
242+
243+
/**
244+
* Returns whether the argument represents a JSON Pointer.
245+
*
246+
* A string is a JSON Pointer if the following are all true:
247+
*
248+
* * The string is of type `String`
249+
* * The string must be empty, `#` or start with a `/` or `#/`
250+
* @param ptr - The string to check
251+
* @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value
252+
* provided is invalid
253+
* @returns the result of the check
254+
* @throws when the provided value is invalid and the `throwWithDetails` argument is `true`
255+
* @see
256+
*/
257+
export function isPtr(ptr: string, throwWithDetails?: boolean): boolean;
258+
259+
/**
260+
* Returns whether the argument represents a JSON Reference.
261+
*
262+
* An object is a JSON Reference only if the following are all true:
263+
*
264+
* * The object is of type `Object`
265+
* * The object has a `$ref` property
266+
* * The `$ref` property is a valid URI *(We do not require 100% strict URIs and will handle unescaped special
267+
* characters.)*
268+
* @param obj - The object to check
269+
* @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value
270+
* provided is invalid
271+
* @returns the result of the check
272+
* @throws when the provided value is invalid and the `throwWithDetails` argument is `true`
273+
* @see
274+
*/
275+
export function isRef(obj: object, throwWithDetails?: boolean): boolean;
276+
277+
/**
278+
* Returns an array of path segments for the provided JSON Pointer.
279+
* @param ptr - The JSON Pointer
280+
* @returns the path segments
281+
* @throws if the provided `ptr` argument is not a JSON Pointer
282+
*/
283+
export function pathFromPtr(ptr: string): string[];
284+
285+
/**
286+
* Returns a JSON Pointer for the provided array of path segments.
287+
*
288+
* **Note:** If a path segment in `path` is not a `String`, it will be converted to one using `JSON.stringify`.
289+
* @param path - The array of path segments
290+
* @param hashPrefix - Whether or not create a hash-prefixed JSON Pointer
291+
* @returns the corresponding JSON Pointer
292+
* @throws if the `path` argument is not an array
293+
*/
294+
export function pathToPtr(path: string[], hashPrefix?: boolean): string;
295+
296+
/**
297+
* Finds JSON References defined within the provided array/object and resolves them.
298+
* @param obj - The structure to find JSON References within
299+
* @param options - The JsonRefs options
300+
* @returns a promise that resolves a
301+
* {@link ResolvedRefsResults} and rejects with an `Error` when the input arguments fail validation,
302+
* when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable
303+
* resource
304+
*/
305+
export function resolveRefs(obj: any[] | object, options?: JsonRefsOptions): Promise<ResolvedRefsResults>;
306+
307+
/**
308+
* Resolves JSON References defined within the document at the provided location.
309+
*
310+
* This API is identical to {@link resolveRefs} except this API will retrieve a remote document and
311+
* then return the result of {@link resolveRefs} on the retrieved document.
312+
* @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
313+
* {@link JsonRefsOptions|options documentation} to see how relative references are handled.)*
314+
* @param options - The JsonRefs options
315+
* @returns a promise that resolves a
316+
* {@link RetrievedResolvedRefsResults} and rejects with an `Error` when the input arguments fail
317+
* validation, when `options.subDocPath` points to an invalid location or when the location argument points to an
318+
* unloadable resource
319+
*/
320+
export function resolveRefsAt(location: string, options?: JsonRefsOptions): Promise<RetrievedResolvedRefsResults>;
321+
320322
}
321323

‎lib/typedefs.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22
* This file contains all type definitions that are purely for documentation purposes.
33
*/
44

5+
/**
6+
* @module uri-js
7+
*/
8+
9+
/**
10+
* @typedef {object} URIComponents
11+
*
12+
* @memberof module:uri-js
13+
*/
14+
515
/**
616
* The options used for various JsonRefs APIs.
717
*
@@ -133,7 +143,7 @@
133143
* @property {string} [error] - The error information for invalid JSON Reference definition *(Only present when the
134144
* JSON Reference definition is invalid or there was a problem retrieving a remote reference during resolution)*
135145
* @property {string} uri - The URI portion of the JSON Reference
136-
* @property {object} uriDetails - Detailed information about the URI as provided by
146+
* @property {module:uri-js~URIComponents} uriDetails - Detailed information about the URI as provided by
137147
* {@link https://github.com/garycourt/uri-js|URI.parse}.
138148
* @property {string} type - The JSON Reference type *(This value can be one of the following: `invalid`, `local`,
139149
* `relative` or `remote`.)*

0 commit comments

Comments
 (0)