Socket
Socket
Sign inDemoInstall

json-refs

Package Overview
Dependencies
Maintainers
1
Versions
60
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

json-refs - npm Package Compare versions

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>;
}

@@ -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",

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc