diff --git a/gulpfile.js b/gulpfile.js index 833edfb..09543d5 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -91,8 +91,8 @@ gulp.task('dist', function (done) { gulp.task('docs-ts-raw', function (done) { gulp.src([ - './index.js', - './lib/typedefs.js' + './lib/typedefs.js', + './index.js' ]) .pipe($.jsdoc3({ opts: { @@ -112,6 +112,8 @@ gulp.task('docs-ts', ['docs-ts-raw'], function () { .pipe($.replace('module:json-refs~', '')) .pipe($.replace('module:json-refs.', '')) .pipe($.replace('Promise.<', 'Promise<')) + .pipe($.replace(/declare\smodule\s'uri-js'\s{(?:[\s\S])+?{(?:[\s\S])+?}(?:[\s\S])+?}/, 'import { URIComponents } from \'uri-js\';')) + .pipe($.replace('module:uri-js~', '')) .pipe(gulp.dest('.')); }); diff --git a/index.d.ts b/index.d.ts index 8c1716c..c9cab9e 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,142 +1,10 @@ +import { URIComponents } from 'uri-js'; + /** * Various utilities for JSON References *(http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)* and * JSON Pointers *(https://tools.ietf.org/html/rfc6901)*. */ declare module 'json-refs' { - /** - * Clears the internal cache of remote documents, reference details, etc. - */ - export function clearCache(): void; - - /** - * Takes an array of path segments and decodes the JSON Pointer tokens in them. - * @param path - The array of path segments - * @returns the array of path segments with their JSON Pointer tokens decoded - * @throws if the path is not an `Array` - * @see - */ - export function decodePath(path: string[]): string[]; - - /** - * Takes an array of path segments and encodes the special JSON Pointer characters in them. - * @param path - The array of path segments - * @returns the array of path segments with their JSON Pointer tokens encoded - * @throws if the path is not an `Array` - * @see - */ - export function encodePath(path: string[]): string[]; - - /** - * Finds JSON References defined within the provided array/object. - * @param obj - The structure to find JSON References within - * @param options - The JsonRefs options - * @returns an object whose keys are JSON Pointers - * *(fragment version)* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails}. - * @throws when the input arguments fail validation or if `options.subDocPath` points to an invalid location - */ - export function findRefs(obj: any[] | object, options?: JsonRefsOptions): { [key: string]: (UnresolvedRefDetails|undefined) }; - - /** - * Finds JSON References defined within the document at the provided location. - * - * This API is identical to {@link findRefs} except this API will retrieve a remote document and then - * return the result of {@link findRefs} on the retrieved document. - * @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the - * {@link JsonRefsOptions|options documentation} to see how relative references are handled.)* - * @param options - The JsonRefs options - * @returns a promise that resolves a - * {@link RetrievedRefsResults} and rejects with an `Error` when the input arguments fail validation, - * when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable - * resource - */ - export function findRefsAt(location: string, options?: JsonRefsOptions): Promise; - - /** - * Returns detailed information about the JSON Reference. - * @param obj - The JSON Reference definition - * @returns the detailed information - */ - export function getRefDetails(obj: object): UnresolvedRefDetails; - - /** - * Returns whether the argument represents a JSON Pointer. - * - * A string is a JSON Pointer if the following are all true: - * - * * The string is of type `String` - * * The string must be empty, `#` or start with a `/` or `#/` - * @param ptr - The string to check - * @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value - * provided is invalid - * @returns the result of the check - * @throws when the provided value is invalid and the `throwWithDetails` argument is `true` - * @see - */ - export function isPtr(ptr: string, throwWithDetails?: boolean): boolean; - - /** - * Returns whether the argument represents a JSON Reference. - * - * An object is a JSON Reference only if the following are all true: - * - * * The object is of type `Object` - * * The object has a `$ref` property - * * The `$ref` property is a valid URI *(We do not require 100% strict URIs and will handle unescaped special - * characters.)* - * @param obj - The object to check - * @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value - * provided is invalid - * @returns the result of the check - * @throws when the provided value is invalid and the `throwWithDetails` argument is `true` - * @see - */ - export function isRef(obj: object, throwWithDetails?: boolean): boolean; - - /** - * Returns an array of path segments for the provided JSON Pointer. - * @param ptr - The JSON Pointer - * @returns the path segments - * @throws if the provided `ptr` argument is not a JSON Pointer - */ - export function pathFromPtr(ptr: string): string[]; - - /** - * Returns a JSON Pointer for the provided array of path segments. - * - * **Note:** If a path segment in `path` is not a `String`, it will be converted to one using `JSON.stringify`. - * @param path - The array of path segments - * @param hashPrefix - Whether or not create a hash-prefixed JSON Pointer - * @returns the corresponding JSON Pointer - * @throws if the `path` argument is not an array - */ - export function pathToPtr(path: string[], hashPrefix?: boolean): string; - - /** - * Finds JSON References defined within the provided array/object and resolves them. - * @param obj - The structure to find JSON References within - * @param options - The JsonRefs options - * @returns a promise that resolves a - * {@link ResolvedRefsResults} and rejects with an `Error` when the input arguments fail validation, - * when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable - * resource - */ - export function resolveRefs(obj: any[] | object, options?: JsonRefsOptions): Promise; - - /** - * Resolves JSON References defined within the document at the provided location. - * - * This API is identical to {@link resolveRefs} except this API will retrieve a remote document and - * then return the result of {@link resolveRefs} on the retrieved document. - * @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the - * {@link JsonRefsOptions|options documentation} to see how relative references are handled.)* - * @param options - The JsonRefs options - * @returns a promise that resolves a - * {@link RetrievedResolvedRefsResults} and rejects with an `Error` when the input arguments fail - * validation, when `options.subDocPath` points to an invalid location or when the location argument points to an - * unloadable resource - */ - export function resolveRefsAt(location: string, options?: JsonRefsOptions): Promise; - /** * The options used for various JsonRefs APIs. */ @@ -304,7 +172,7 @@ declare module 'json-refs' { * Detailed information about the URI as provided by * {@link https://github.com/garycourt/uri-js|URI.parse}. */ - uriDetails: object; + uriDetails: URIComponents; /** * The JSON Reference type *(This value can be one of the following: `invalid`, `local`, * `relative` or `remote`.)* @@ -317,5 +185,139 @@ declare module 'json-refs' { warning?: string; } + /** + * Clears the internal cache of remote documents, reference details, etc. + */ + export function clearCache(): void; + + /** + * Takes an array of path segments and decodes the JSON Pointer tokens in them. + * @param path - The array of path segments + * @returns the array of path segments with their JSON Pointer tokens decoded + * @throws if the path is not an `Array` + * @see + */ + export function decodePath(path: string[]): string[]; + + /** + * Takes an array of path segments and encodes the special JSON Pointer characters in them. + * @param path - The array of path segments + * @returns the array of path segments with their JSON Pointer tokens encoded + * @throws if the path is not an `Array` + * @see + */ + export function encodePath(path: string[]): string[]; + + /** + * Finds JSON References defined within the provided array/object. + * @param obj - The structure to find JSON References within + * @param options - The JsonRefs options + * @returns an object whose keys are JSON Pointers + * *(fragment version)* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails}. + * @throws when the input arguments fail validation or if `options.subDocPath` points to an invalid location + */ + export function findRefs(obj: any[] | object, options?: JsonRefsOptions): { [key: string]: (UnresolvedRefDetails|undefined) }; + + /** + * Finds JSON References defined within the document at the provided location. + * + * This API is identical to {@link findRefs} except this API will retrieve a remote document and then + * return the result of {@link findRefs} on the retrieved document. + * @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the + * {@link JsonRefsOptions|options documentation} to see how relative references are handled.)* + * @param options - The JsonRefs options + * @returns a promise that resolves a + * {@link RetrievedRefsResults} and rejects with an `Error` when the input arguments fail validation, + * when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable + * resource + */ + export function findRefsAt(location: string, options?: JsonRefsOptions): Promise; + + /** + * Returns detailed information about the JSON Reference. + * @param obj - The JSON Reference definition + * @returns the detailed information + */ + export function getRefDetails(obj: object): UnresolvedRefDetails; + + /** + * Returns whether the argument represents a JSON Pointer. + * + * A string is a JSON Pointer if the following are all true: + * + * * The string is of type `String` + * * The string must be empty, `#` or start with a `/` or `#/` + * @param ptr - The string to check + * @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value + * provided is invalid + * @returns the result of the check + * @throws when the provided value is invalid and the `throwWithDetails` argument is `true` + * @see + */ + export function isPtr(ptr: string, throwWithDetails?: boolean): boolean; + + /** + * Returns whether the argument represents a JSON Reference. + * + * An object is a JSON Reference only if the following are all true: + * + * * The object is of type `Object` + * * The object has a `$ref` property + * * The `$ref` property is a valid URI *(We do not require 100% strict URIs and will handle unescaped special + * characters.)* + * @param obj - The object to check + * @param throwWithDetails - Whether or not to throw an `Error` with the details as to why the value + * provided is invalid + * @returns the result of the check + * @throws when the provided value is invalid and the `throwWithDetails` argument is `true` + * @see + */ + export function isRef(obj: object, throwWithDetails?: boolean): boolean; + + /** + * Returns an array of path segments for the provided JSON Pointer. + * @param ptr - The JSON Pointer + * @returns the path segments + * @throws if the provided `ptr` argument is not a JSON Pointer + */ + export function pathFromPtr(ptr: string): string[]; + + /** + * Returns a JSON Pointer for the provided array of path segments. + * + * **Note:** If a path segment in `path` is not a `String`, it will be converted to one using `JSON.stringify`. + * @param path - The array of path segments + * @param hashPrefix - Whether or not create a hash-prefixed JSON Pointer + * @returns the corresponding JSON Pointer + * @throws if the `path` argument is not an array + */ + export function pathToPtr(path: string[], hashPrefix?: boolean): string; + + /** + * Finds JSON References defined within the provided array/object and resolves them. + * @param obj - The structure to find JSON References within + * @param options - The JsonRefs options + * @returns a promise that resolves a + * {@link ResolvedRefsResults} and rejects with an `Error` when the input arguments fail validation, + * when `options.subDocPath` points to an invalid location or when the location argument points to an unloadable + * resource + */ + export function resolveRefs(obj: any[] | object, options?: JsonRefsOptions): Promise; + + /** + * Resolves JSON References defined within the document at the provided location. + * + * This API is identical to {@link resolveRefs} except this API will retrieve a remote document and + * then return the result of {@link resolveRefs} on the retrieved document. + * @param location - The location to retrieve *(Can be relative or absolute, just make sure you look at the + * {@link JsonRefsOptions|options documentation} to see how relative references are handled.)* + * @param options - The JsonRefs options + * @returns a promise that resolves a + * {@link RetrievedResolvedRefsResults} and rejects with an `Error` when the input arguments fail + * validation, when `options.subDocPath` points to an invalid location or when the location argument points to an + * unloadable resource + */ + export function resolveRefsAt(location: string, options?: JsonRefsOptions): Promise; + } diff --git a/lib/typedefs.js b/lib/typedefs.js index 9e9b8cf..350f9ba 100644 --- a/lib/typedefs.js +++ b/lib/typedefs.js @@ -2,6 +2,16 @@ * This file contains all type definitions that are purely for documentation purposes. */ +/** + * @module uri-js + */ + +/** + * @typedef {object} URIComponents + * + * @memberof module:uri-js + */ + /** * The options used for various JsonRefs APIs. * @@ -133,7 +143,7 @@ * @property {string} [error] - The error information for invalid JSON Reference definition *(Only present when the * JSON Reference definition is invalid or there was a problem retrieving a remote reference during resolution)* * @property {string} uri - The URI portion of the JSON Reference - * @property {object} uriDetails - Detailed information about the URI as provided by + * @property {module:uri-js~URIComponents} uriDetails - Detailed information about the URI as provided by * {@link https://github.com/garycourt/uri-js|URI.parse}. * @property {string} type - The JSON Reference type *(This value can be one of the following: `invalid`, `local`, * `relative` or `remote`.)*