schema-fun/dist/json-refs.d.ts

JSON schema tools

/**
 * Detailed information about resolved JSON References.
 *
 * @typedef {module:json-refs.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 module:json-refs.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)*
 *
 * @memberof module:json-refs
 */
export interface UnresolvedRefDetails {
    /** Whether or not the JSON Reference is circular *(Will not be set if the JSON Reference is not circular). */
    circular?: boolean;
    /**
     * The fully-qualified version of the `uri` property for UnresolvedRefDetails but with the value being relative to the
     * root document. */
    fqURI: string;
    /**
     * Whether or not the referenced value was missing or not *(Will not be set if the referenced value is not missing)*.
     */
    missing: boolean;
    /** The referenced value *(Will not be set if the referenced value is missing)*. */
    value: any;
}
/**
 * Takes an array of path segments and decodes the JSON Pointer tokens in them.
 *
 * @param {string[]} path - The array of path segments
 *
 * @returns {string[]} the array of path segments with their JSON Pointer tokens decoded
 *
 * @throws {Error} if the path is not an `Array`
 *
 * @see {@link https://tools.ietf.org/html/rfc6901#section-3}
 */
export declare function decodePath(path: any): any[];
/**
 * Takes an array of path segments and encodes the special JSON Pointer characters in them.
 *
 * @param {string[]} path - The array of path segments
 *
 * @returns {string[]} the array of path segments with their JSON Pointer tokens encoded
 *
 * @throws {Error} if the path is not an `Array`
 *
 * @see {@link https://tools.ietf.org/html/rfc6901#section-3}
 */
export declare function encodePath(path: any): any[];
/**
 * Finds JSON References defined within the provided array/object.
 *
 * @param {array|object} obj - The structure to find JSON References within
 * @param {module:json-refs.JsonRefsOptions} [options] - The JsonRefs options
 *
 * @returns {Object.<string, module:json-refs.UnresolvedRefDetails|undefined>} an object whose keys are JSON Pointers
 * *(fragment version)* to where the JSON Reference is defined and whose values are {@link UnresolvedRefDetails}.
 *
 * @throws {Error} when the input arguments fail validation or if `options.subDocPath` points to an invalid location
 *
 * @example
 * // Finding all valid references
 * let allRefs = JsonRefs.findRefs(obj);
 * // Finding all remote references
 * let remoteRefs = JsonRefs.findRefs(obj, {filter: ['relative', 'remote']});
 * // Finding all invalid references
 * let invalidRefs = JsonRefs.findRefs(obj, {filter: 'invalid', includeInvalid: true});
 */
export declare function findRefs(obj: any, options: any): {};
/**
 * 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 {string} location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
 * {@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<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
 *
 * @example
 * // Example that only resolves references within a sub document
 * JsonRefs.findRefsAt('http://petstore.swagger.io/v2/swagger.json', {
 *     subDocPath: '#/definitions'
 *   })
 *   .then(function (res) {
 *      // Do something with the response
 *      //
 *      // res.refs: JSON Reference locations and details
 *      // res.value: The retrieved document
 *   }, function (err) {
 *     console.log(err.stack);
 *   });
 */
export declare function findRefsAt(location: any, options: any): Promise<void>;
/**
 * Returns detailed information about the JSON Reference.
 *
 * @param {object} obj - The JSON Reference definition
 *
 * @returns {module:json-refs.UnresolvedRefDetails} the detailed information
 */
export declare function getRefDetails(obj: any): {
    def: any;
};
/**
 * 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 {string} ptr - The string to check
 * @param {boolean} [throwWithDetails=false] - Whether or not to throw an `Error` with the details as to why the value
 * provided is invalid
 *
 * @returns {boolean} the result of the check
 *
 * @throws {error} when the provided value is invalid and the `throwWithDetails` argument is `true`
 *
 * @see {@link https://tools.ietf.org/html/rfc6901#section-3}
 *
 * @example
 * // Separating the different ways to invoke isPtr for demonstration purposes
 * if (isPtr(str)) {
 *   // Handle a valid JSON Pointer
 * } else {
 *   // Get the reason as to why the value is not a JSON Pointer so you can fix/report it
 *   try {
 *     isPtr(str, true);
 *   } catch (err) {
 *     // The error message contains the details as to why the provided value is not a JSON Pointer
 *   }
 * }
 */
export declare function isPtr(ptr: any, throwWithDetails: any): 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 {object} obj - The object to check
 * @param {boolean} [throwWithDetails=false] - Whether or not to throw an `Error` with the details as to why the value
 * provided is invalid
 *
 * @returns {boolean} the result of the check
 *
 * @throws {error} when the provided value is invalid and the `throwWithDetails` argument is `true`
 *
 * @see {@link http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3}
 *
 * @example
 * // Separating the different ways to invoke isRef for demonstration purposes
 * if (isRef(obj)) {
 *   // Handle a valid JSON Reference
 * } else {
 *   // Get the reason as to why the value is not a JSON Reference so you can fix/report it
 *   try {
 *     isRef(str, true);
 *   } catch (err) {
 *     // The error message contains the details as to why the provided value is not a JSON Reference
 *   }
 * }
 */
export declare function isRef(obj: any, throwWithDetails: any): boolean;
/**
 * Returns an array of path segments for the provided JSON Pointer.
 *
 * @param {string} ptr - The JSON Pointer
 *
 * @returns {string[]} the path segments
 *
 * @throws {Error} if the provided `ptr` argument is not a JSON Pointer
 */
export declare function pathFromPtr(ptr: any): any[];
/**
 * 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 {string[]} path - The array of path segments
 * @param {boolean} [hashPrefix=true] - Whether or not create a hash-prefixed JSON Pointer
 *
 * @returns {string} the corresponding JSON Pointer
 *
 * @throws {Error} if the `path` argument is not an array
 */
export declare function pathToPtr(path: any, hashPrefix: any): string;
/**
 * Finds JSON References defined within the provided array/object and resolves them.
 *
 * @param {array|object} obj - The structure to find JSON References within
 * @param {module:json-refs.JsonRefsOptions} [options] - The JsonRefs options
 *
 * @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
 *
 * @example
 * // Example that only resolves relative and remote references
 * JsonRefs.resolveRefs(swaggerObj, {
 *     filter: ['relative', 'remote']
 *   })
 *   .then(function (res) {
 *      // Do something with the response
 *      //
 *      // res.refs: JSON Reference locations and details
 *      // res.resolved: The document with the appropriate JSON References resolved
 *   }, function (err) {
 *     console.log(err.stack);
 *   });
 */
export declare function resolveRefs(obj: any, options: any): Promise<void>;
/**
 * 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 {string} location - The location to retrieve *(Can be relative or absolute, just make sure you look at the
 * {@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<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
 *
 * @example
 * // Example that loads a JSON document (No options.loaderOptions.processContent required) and resolves all references
 * JsonRefs.resolveRefsAt('./swagger.json')
 *   .then(function (res) {
 *      // Do something with the response
 *      //
 *      // res.refs: JSON Reference locations and details
 *      // res.resolved: The document with the appropriate JSON References resolved
 *      // res.value: The retrieved document
 *   }, function (err) {
 *     console.log(err.stack);
 *   });
 */
export declare function resolveRefsAt(location: any, options: any): Promise<void>;
/**
 * 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)*.
 *
 * @module json-refs
 */
/**
 * A number of functions exported below are used within the exported functions.  Typically, I would use a function
 * declaration _(with documenation)_ above and then just export a reference to the function but due to a bug in JSDoc
 * (https://github.com/jsdoc3/jsdoc/issues/679), this breaks the generated API documentation and TypeScript
 * declarations.  So that's why each `module.exports` below basically just wraps a call to the function declaration.
 */
/**
 * Clears the internal cache of remote documents, reference details, etc.
 */
export declare function clearCache(): void;
//# sourceMappingURL=json-refs.d.ts.map