Comparing version 3.0.8 to 3.0.9
276
index.d.ts
@@ -7,2 +7,136 @@ /** | ||
/** | ||
* 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): object; | ||
/** | ||
* 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<RetrievedRefsResults>; | ||
/** | ||
* 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<ResolvedRefsResults>; | ||
/** | ||
* Resolves JSON References defined within the document at the provided location. | ||
* | ||
* This API is identical to {@link module:json-refs.resolveRefs} except this API will retrieve a remote document and | ||
* then return the result of {@link module:json-refs.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<RetrievedResolvedRefsResults>; | ||
/** | ||
* The options used for various JsonRefs APIs. | ||
@@ -14,3 +148,3 @@ */ | ||
* References *(If this value is a single string or an array of strings, the value(s) are expected to be the `type(s)` | ||
* you are interested in collecting as described in {@link getRefDetails}. If it is a function, it is | ||
* you are interested in collecting as described in {@link module:json-refs.getRefDetails}. If it is a function, it is | ||
* expected that the function behaves like {@link RefDetailsFilter}.)* | ||
@@ -66,3 +200,3 @@ */ | ||
*/ | ||
declare type RefDetailsFilter = (refDetails: UnresolvedRefDetails, path: string[])=>boolean; | ||
export type RefDetailsFilter = (refDetails: UnresolvedRefDetails, path: string[])=>boolean; | ||
@@ -75,3 +209,3 @@ /** | ||
*/ | ||
declare type RefPreProcessor = (obj: object, path: string[])=>object; | ||
export type RefPreProcessor = (obj: object, path: string[])=>object; | ||
@@ -84,3 +218,3 @@ /** | ||
*/ | ||
declare type RefPostProcessor = (refDetails: UnresolvedRefDetails, path: string[])=>object; | ||
export type RefPostProcessor = (refDetails: UnresolvedRefDetails, path: string[])=>object; | ||
@@ -98,4 +232,3 @@ /** | ||
* The fully-qualified version of the `uri` property for | ||
* {@link UnresolvedRefDetails} but with the value being relative to the root | ||
* document | ||
* {@link UnresolvedRefDetails} but with the value being relative to the root document | ||
*/ | ||
@@ -194,134 +327,3 @@ fqURI: 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): object; | ||
/** | ||
* 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<RetrievedRefsResults>; | ||
/** | ||
* 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<ResolvedRefsResults>; | ||
/** | ||
* 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<RetrievedResolvedRefsResults>; | ||
} | ||
164
index.js
@@ -1125,127 +1125,2 @@ /* | ||
/** | ||
* The options used for various JsonRefs APIs. | ||
* | ||
* @typedef {object} JsonRefsOptions | ||
* | ||
* @property {string|string[]|function} [filter=function () {return true;}] - The filter to use when gathering JSON | ||
* References *(If this value is a single string or an array of strings, the value(s) are expected to be the `type(s)` | ||
* you are interested in collecting as described in {@link getRefDetails}. If it is a function, it is | ||
* expected that the function behaves like {@link RefDetailsFilter}.)* | ||
* @property {boolean} [includeInvalid=false] - Whether or not to include invalid JSON Reference details *(This will | ||
* make it so that objects that are like JSON Reference objects, as in they are an `Object` and the have a `$ref` | ||
* property, but fail validation will be included. This is very useful for when you want to know if you have invalid | ||
* JSON Reference definitions. This will not mean that APIs will process invalid JSON References but the reasons as to | ||
* why the JSON References are invalid will be included in the returned metadata.)* | ||
* @property {object} [loaderOptions] - The options to pass to | ||
* {@link https://github.com/whitlockjc/path-loader/blob/master/docs/API.md#module_PathLoader.load|PathLoader~load} | ||
* @property {string} [location=root.json] - The location of the document being processed *(This property is only | ||
* useful when resolving references as it will be used to locate relative references found within the document being | ||
* resolved. If this value is relative, {@link https://github.com/whitlockjc/path-loader|path-loader} will use | ||
* `window.location.href` for the browser and `process.cwd()` for Node.js.)* | ||
* @property {RefPreProcessor} [refPreProcessor] - The callback used to pre-process a JSON Reference like | ||
* object *(This is called prior to validating the JSON Reference like object and getting its details)* | ||
* @property {RefPostProcessor} [refPostProcessor] - The callback used to post-process the JSON Reference | ||
* metadata *(This is called prior filtering the references)* | ||
* @property {boolean} [resolveCirculars=false] - Whether to resolve circular references | ||
* @property {string|string[]} [subDocPath=[]] - The JSON Pointer or array of path segments to the sub document | ||
* location to search from | ||
*/ | ||
/** | ||
* Simple function used to filter out JSON References. | ||
* | ||
* @typedef {function} RefDetailsFilter | ||
* | ||
* @param {UnresolvedRefDetails} refDetails - The JSON Reference details to test | ||
* @param {string[]} path - The path to the JSON Reference | ||
* | ||
* @returns {boolean} whether the JSON Reference should be filtered *(out)* or not | ||
*/ | ||
/** | ||
* Simple function used to pre-process a JSON Reference like object. | ||
* | ||
* @typedef {function} RefPreProcessor | ||
* | ||
* @param {object} obj - The JSON Reference like object | ||
* @param {string[]} path - The path to the JSON Reference like object | ||
* | ||
* @returns {object} the processed JSON Reference like object | ||
*/ | ||
/** | ||
* Simple function used to post-process a JSON Reference details. | ||
* | ||
* @typedef {function} RefPostProcessor | ||
* | ||
* @param {UnresolvedRefDetails} refDetails - The JSON Reference details to test | ||
* @param {string[]} path - The path to the JSON Reference | ||
* | ||
* @returns {object} the processed JSON Reference details object | ||
*/ | ||
/** | ||
* Detailed information about resolved JSON References. | ||
* | ||
* @typedef {UnresolvedRefDetails} ResolvedRefDetails | ||
* | ||
* @property {boolean} [circular] - Whether or not the JSON Reference is circular *(Will not be set if the JSON | ||
* Reference is not circular)* | ||
* @property {string} fqURI - The fully-qualified version of the `uri` property for | ||
* {@link UnresolvedRefDetails} but with the value being relative to the root | ||
* document | ||
* @property {boolean} [missing] - Whether or not the referenced value was missing or not *(Will not be set if the | ||
* referenced value is not missing)* | ||
* @property {*} [value] - The referenced value *(Will not be set if the referenced value is missing)* | ||
*/ | ||
/** | ||
* The results of resolving the JSON References of an array/object. | ||
* | ||
* @typedef {object} ResolvedRefsResults | ||
* | ||
* @property {ResolvedRefDetails} refs - An object whose keys are JSON Pointers *(fragment version)* | ||
* to where the JSON Reference is defined and whose values are {@link ResolvedRefDetails} | ||
* @property {object} resolved - The array/object with its JSON References fully resolved | ||
*/ | ||
/** | ||
* An object containing the retrieved document and detailed information about its JSON References. | ||
* | ||
* @typedef {ResolvedRefsResults} RetrievedRefsResults | ||
* | ||
* @property {object} value - The retrieved document | ||
*/ | ||
/** | ||
* An object containing the retrieved document, the document with its references resolved and detailed information | ||
* about its JSON References. | ||
* | ||
* @typedef {object} RetrievedResolvedRefsResults | ||
* | ||
* @property {UnresolvedRefDetails} refs - An object whose keys are JSON Pointers *(fragment version)* | ||
* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails} | ||
* @property {ResolvedRefsResults} - An object whose keys are JSON Pointers *(fragment version)* | ||
* to where the JSON Reference is defined and whose values are {@link ResolvedRefDetails} | ||
* @property {object} value - The retrieved document | ||
*/ | ||
/** | ||
* Detailed information about unresolved JSON References. | ||
* | ||
* @typedef {object} UnresolvedRefDetails | ||
* | ||
* @property {object} def - The JSON Reference definition | ||
* @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 | ||
* {@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`.)* | ||
* @property {string} [warning] - The warning information *(Only present when the JSON Reference definition produces a | ||
* warning)* | ||
*/ | ||
/** | ||
@@ -1292,3 +1167,3 @@ * Clears the internal cache of remote documents, reference details, etc. | ||
* @param {array|object} obj - The structure to find JSON References within | ||
* @param {JsonRefsOptions} [options] - The JsonRefs options | ||
* @param {module:json-refs~JsonRefsOptions} [options] - The JsonRefs options | ||
* | ||
@@ -1319,8 +1194,9 @@ * @returns {object} an object whose keys are JSON Pointers *(fragment version)* to where the JSON Reference is defined | ||
* @param {string} 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 {JsonRefsOptions} [options] - The JsonRefs options | ||
* {@link module:json-refs~JsonRefsOptions|options documentation} to see how relative references are handled.)* | ||
* @param {module:json-refs~JsonRefsOptions} [options] - The JsonRefs options | ||
* | ||
* @returns {Promise<RetrievedRefsResults>} 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 | ||
* @returns {Promise<module:json-refs~RetrievedRefsResults>} a promise that resolves a | ||
* {@link module:json-refs~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 | ||
* | ||
@@ -1350,3 +1226,3 @@ * @example | ||
* | ||
* @returns {UnresolvedRefDetails} the detailed information | ||
* @returns {module:json-refs~UnresolvedRefDetails} the detailed information | ||
*/ | ||
@@ -1462,7 +1338,8 @@ module.exports.getRefDetails = function (obj) { | ||
* @param {array|object} obj - The structure to find JSON References within | ||
* @param {JsonRefsOptions} [options] - The JsonRefs options | ||
* @param {module:json-refs~JsonRefsOptions} [options] - The JsonRefs options | ||
* | ||
* @returns {Promise<ResolvedRefsResults>} 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 | ||
* @returns {Promise<module:json-refs~ResolvedRefsResults>} a promise that resolves a | ||
* {@link module:json-refs~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 | ||
* | ||
@@ -1490,12 +1367,13 @@ * @example | ||
* | ||
* 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. | ||
* This API is identical to {@link module:json-refs.resolveRefs} except this API will retrieve a remote document and | ||
* then return the result of {@link module:json-refs.resolveRefs} on the retrieved document. | ||
* | ||
* @param {string} 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 {JsonRefsOptions} [options] - The JsonRefs options | ||
* {@link module:json-refs~JsonRefsOptions|options documentation} to see how relative references are handled.)* | ||
* @param {module:json-refs~JsonRefsOptions} [options] - The JsonRefs options | ||
* | ||
* @returns {Promise<RetrievedResolvedRefsResults>} 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 | ||
* @returns {Promise<module:json-refs~RetrievedResolvedRefsResults>} a promise that resolves a | ||
* {@link module:json-refs~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 | ||
* | ||
@@ -1502,0 +1380,0 @@ * @example |
{ | ||
"name": "json-refs", | ||
"version": "3.0.8", | ||
"version": "3.0.9", | ||
"description": "Various utilities for JSON References (http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).", | ||
@@ -57,2 +57,3 @@ "main": "index.js", | ||
"gulp-nsp": "^2.4.2", | ||
"gulp-replace": "^1.0.0", | ||
"gulp-uglify": "^3.0.0", | ||
@@ -59,0 +60,0 @@ "karma": "^1.6.0", |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
70941
29
1476