oas 18.2.2 → 18.3.1

package/@types/index.d.ts

@@ -29,19 +29,17 @@ export default class Oas {
      */
     user: RMOAS.User;
     /**
-     * Internal storage array that the library utilizes to keep track of the times the {@see Oas.dereference} has been
-     * called so that if you initiate multiple promises they'll all end up returning the same data set once the initial
-     * dereference call completed.
-     *
-     * @todo These are always `Promise.resolve` and `Promise.reject`. Make these types more specific than `any`.
+     * Internal storage array that the library utilizes to keep track of the times the
+     * {@see Oas.dereference} has been called so that if you initiate multiple promises they'll all
+     * end up returning the same data set once the initial dereference call completed.
      */
     protected promises: {
         resolve: any;
         reject: any;
     }[];
     /**
-     * Internal storage array that the library utilizes to keep track of its `dereferencing` state so it doesn't initiate
-     * multiple dereferencing processes.
+     * Internal storage array that the library utilizes to keep track of its `dereferencing` state so
+     * it doesn't initiate multiple dereferencing processes.
      */
     protected dereferencing: {
         processing: boolean;
@@ -49,16 +47,18 @@ export default class Oas {
     };
     /**
      * @param oas An OpenAPI definition.
-     * @param user The information about a user that we should use when pulling auth tokens from security schemes.
+     * @param user The information about a user that we should use when pulling auth tokens from
+     *    security schemes.
      */
     constructor(oas: RMOAS.OASDocument, user?: RMOAS.User);
     /**
-     * This will initialize a new instance of the `Oas` class. This method is useful if you're using Typescript and are
-     * attempting to supply an untyped JSON object into `Oas` as it will force-type that object to an `OASDocument` for
-     * you.
+     * This will initialize a new instance of the `Oas` class. This method is useful if you're using
+     * Typescript and are attempting to supply an untyped JSON object into `Oas` as it will force-type
+     * that object to an `OASDocument` for you.
      *
      * @param oas An OpenAPI definition.
-     * @param user The information about a user that we should use when pulling auth tokens from security schemes.
+     * @param user The information about a user that we should use when pulling auth tokens from
+     *    security schemes.
      */
     static init(oas: Record<string, unknown> | RMOAS.OASDocument, user?: RMOAS.User): Oas;
     /**
@@ -89,11 +89,12 @@ export default class Oas {
         enum: string[];
     })[];
     /**
-     * With a fully composed server URL, run through our list of known OAS servers and return back which server URL was
-     * selected along with any contained server variables split out.
+     * With a fully composed server URL, run through our list of known OAS servers and return back
+     * which server URL was selected along with any contained server variables split out.
      *
-     * For example, if you have an OAS server URL of `https://{name}.example.com:{port}/{basePath}`, and pass in
-     * `https://buster.example.com:3000/pet` to this function, you'll get back the following:
+     * For example, if you have an OAS server URL of `https://{name}.example.com:{port}/{basePath}`,
+     * and pass in `https://buster.example.com:3000/pet` to this function, you'll get back the
+     * following:
      *
      *    { selected: 0, variables: { name: 'buster', port: 3000, basePath: 'pet' } }
      *
@@ -110,15 +111,15 @@ export default class Oas {
      *
      * There are a couple ways that this will utilize variable data:
      *
-     *  - If data is stored in `this.user` and it matches up with the variable name in the URL user data
-     *    will always take priority. See `getUserVariable` for some more information on how this data is pulled from
-     *    `this.user`.
+     *  - If data is stored in `this.user` and it matches up with the variable name in the URL user
+     *    data will always take priority. See `getUserVariable` for some more information on how this
+     *    data is pulled from `this.user`.
      *  - Supplying a `variables` object. This incoming `variables` object can be two formats:
-     *    `{ variableName: { default: 'value' } }` and `{ variableName: 'value' }`. If the former is present, that will
-     *    take prescendence over the latter.
+     *    `{ variableName: { default: 'value' } }` and `{ variableName: 'value' }`. If the former is
+     *    present, that will take prescendence over the latter.
      *
-     * If no variables supplied match up with the template name, the template name will instead be used as the variable
-     * data.
+     * If no variables supplied match up with the template name, the template name will instead be
+     * used as the variable data.
      *
      * @param url A URL to swap variables into.
      * @param variables An object containing variables to swap into the URL.
@@ -137,31 +138,33 @@ export default class Oas {
     }): Operation;
     findOperationMatches(url: string): PathMatches;
     /**
-     * Discover an operation in an OAS from a fully-formed URL and HTTP method. Will return an object containing a `url`
-     * object and another one for `operation`. This differs from `getOperation()` in that it does not return an instance
-     * of the `Operation` class.
+     * Discover an operation in an OAS from a fully-formed URL and HTTP method. Will return an object
+     * containing a `url` object and another one for `operation`. This differs from `getOperation()`
+     * in that it does not return an instance of the `Operation` class.
      *
      * @param url A full URL to look up.
      * @param method The cooresponding HTTP method to look up.
      */
     findOperation(url: string, method: RMOAS.HttpMethods): PathMatch;
     /**
-     * Discover an operation in an OAS from a fully-formed URL without an HTTP method. Will return an object containing a
-     * `url` object and another one for `operation`.
+     * Discover an operation in an OAS from a fully-formed URL without an HTTP method. Will return an
+     * object containing a `url` object and another one for `operation`.
      *
      * @param url A full URL to look up.
      */
     findOperationWithoutMethod(url: string): PathMatch;
     /**
-     * Retrieve an operation in an OAS from a fully-formed URL and HTTP method. Differs from `findOperation` in that while
-     * this method will return an `Operation` instance, `findOperation()` does not.
+     * Retrieve an operation in an OAS from a fully-formed URL and HTTP method. Differs from
+     * `findOperation` in that while this method will return an `Operation` instance,
+     * `findOperation()` does not.
      *
      * @param url A full URL to look up.
      * @param method The cooresponding HTTP method to look up.
      */
     getOperation(url: string, method: RMOAS.HttpMethods): Operation;
     /**
-     * With an object of user information, retrieve the appropriate API auth keys from the current OAS definition.
+     * With an object of user information, retrieve the appropriate API auth keys from the current
+     * OAS definition.
      *
      * @see {@link https://docs.readme.com/docs/passing-data-to-jwt}
      * @param user User
@@ -171,16 +174,16 @@ export default class Oas {
         [x: string]: unknown;
     };
     /**
-     * Returns the `paths` object that exists in this API definition but with every `method` mapped to an instance of
-     * the `Operation` class.
+     * Returns the `paths` object that exists in this API definition but with every `method` mapped
+     * to an instance of the `Operation` class.
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
      */
     getPaths(): Record<string, Record<RMOAS.HttpMethods, Operation | Webhook>>;
     /**
-     * Returns the `webhooks` object that exists in this API definition but with every `method` mapped to an instance of
-     * the `Operation` class.
+     * Returns the `webhooks` object that exists in this API definition but with every `method`
+     * mapped to an instance of the `Operation` class.
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
@@ -193,8 +196,8 @@ export default class Oas {
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#oasObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#openapi-object}
-     * @param setIfMissing If a tag is not present on an operation that operations path will be added into the list of
-     *    tags returned.
+     * @param setIfMissing If a tag is not present on an operation that operations path will be added
+     *    into the list of tags returned.
      */
     getTags(setIfMissing?: boolean): unknown[];
     /**
@@ -214,8 +217,8 @@ export default class Oas {
      */
     getExtension(extension: string): unknown;
     /**
-     * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas and circular
-     * structures.
+     * Dereference the current OAS definition so it can be parsed free of worries of `$ref` schemas
+     * and circular structures.
      *
      * @param opts
      */

package/@types/lib/dedupe-common-parameters.d.ts

@@ -1,7 +1,7 @@
 import * as RMOAS from '../rmoas.types';
 /**
- * With an array of common parameters filter down them to what isn't already present in a list of non-common
- * parameters.
+ * With an array of common parameters filter down them to what isn't already present in a list of
+ * non-common parameters.
  *
  * @param parameters
  * @param commonParameters

package/@types/lib/find-schema-definition.d.ts

@@ -1,5 +1,6 @@
 /**
- * Lookup a reference pointer within an OpenAPI definition and return the schema that it resolves to.
+ * Lookup a reference pointer within an OpenAPI definition and return the schema that it resolves
+ * to.
  *
  * @deprecated
  * @param $ref Reference to look up a schema for.

package/@types/lib/get-auth.d.ts

@@ -5,12 +5,14 @@ declare type authKey = null | unknown | {
     password: string | number;
 };
 /**
- * Retrieve auth keys for a specific security scheme for a given user for a specific "app" that they have configured.
+ * Retrieve auth keys for a specific security scheme for a given user for a specific "app" that
+ * they have configured.
  *
- * For `scheme` we're typing it to a union of `SecurityScheme` and `any` because we have handling and tests for an
- * unknown or unrecognized `type` and though it's not possible with the `SecurityScheme.type` to be unrecognized it may
- * still be possible to get an unrecognized scheme with this method in the wild as we have API definitions in our
- * database that were ingested before we had good validation in place.
+ * For `scheme` we're typing it to a union of `SecurityScheme` and `any` because we have handling
+ * and tests for an unknown or unrecognized `type` and though it's not possible with the
+ * `SecurityScheme.type` to be unrecognized it may still be possible to get an unrecognized scheme
+ * with this method in the wild as we have API definitions in our database that were ingested
+ * before we had good validation in place.
  *
  * @param user User
  * @param scheme Security scheme to get auth keys for.
@@ -18,7 +20,8 @@ declare type authKey = null | unknown | {
  */
 export declare function getByScheme(user: RMOAS.User, scheme?: RMOAS.KeyedSecuritySchemeObject, selectedApp?: string | number): authKey;
 /**
- * Retrieve auth keys for an API definition from a given user for a specific "app" that they have configured.
+ * Retrieve auth keys for an API definition from a given user for a specific "app" that they have
+ * configured.
  *
  * @param api API definition
  * @param user User

package/@types/lib/get-mediatype-examples.d.ts

@@ -6,9 +6,9 @@ export declare type MediaTypeExample = {
     value: unknown;
 };
 /**
- * Extracts a collection of examples from an OpenAPI Media Type Object. The example will either come from the `example`
- * property, the first item in an `examples` array, or if none of those are present it will generate an example based
- * off its schema.
+ * Extracts a collection of examples from an OpenAPI Media Type Object. The example will either
+ * come from the `example` property, the first item in an `examples` array, or if none of those are
+ * present it will generate an example based off its schema.
  *
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#mediaTypeObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#mediaTypeObject}

package/@types/lib/openapi-to-json-schema.d.ts

@@ -1,6 +1,7 @@
 import * as RMOAS from '../rmoas.types';
 declare type PrevSchemasType = RMOAS.SchemaObject[];
-export declare type toJsonSchemaOptions = {
+export declare type toJSONSchemaOptions = {
+    addEnumsToDescriptions?: boolean;
     currentLocation?: string;
     globalDefaults?: Record<string, unknown>;
     isPolymorphicAllOfChild?: boolean;
@@ -10,29 +11,34 @@ export declare type toJsonSchemaOptions = {
 export declare function getSchemaVersionString(schema: RMOAS.SchemaObject, api: RMOAS.OASDocument): string;
 export declare function isPrimitive(val: unknown): boolean;
 /**
- * Given an OpenAPI-flavored JSON Schema, make an effort to modify it so it's shaped more towards stock JSON Schema.
+ * Given an OpenAPI-flavored JSON Schema, make an effort to modify it so it's shaped more towards
+ * stock JSON Schema.
  *
  * Why do this?
  *
- *  1. OpenAPI 3.0.x supports its own flavor of JSON Schema that isn't fully compatible with most JSON Schema tooling
- *    (like `@readme/oas-form` or `@rjsf/core`).
- *  2. While validating an OpenAPI definition will prevent corrupted or improper schemas from occuring, we have a lot of
- *    legacy schemas in ReadMe that were ingested before we had proper validation in place, and as a result have some
- *    API definitions that will not pass validation right now. In addition to reshaping OAS-JSON Schema into JSON Schema
- *    this library will also fix these improper schemas: things like `type: object` having `items` instead of
- *    `properties`, or `type: array` missing `items`.
- *  3. To ease the burden of polymorphic handling on our form rendering engine we make an attempt to merge `allOf`
- *    schemas here.
- *  4. Additionally due to OpenAPI 3.0.x not supporting JSON Schema, in order to support the `example` keyword that OAS
- *    supports, we need to do some work in here to remap it into `examples`. However, since all we care about in respect
- *    to examples for usage within `@readme/oas-form`, we're only retaining primitives. This *slightly* deviates from
- *    JSON Schema in that JSON Schema allows for any schema to be an example, but since `@readme/oas-form` can only
- *    actually **render** primitives, that's what we're retaining.
- *  5. Though OpenAPI 3.1 does support full JSON Schema, this library should be able to handle it without any problems.
+ *  1. OpenAPI 3.0.x supports its own flavor of JSON Schema that isn't fully compatible with most
+ *    JSON Schema tooling (like `@readme/oas-form` or `@rjsf/core`).
+ *  2. While validating an OpenAPI definition will prevent corrupted or improper schemas from
+ *    occuring, we have a lot of legacy schemas in ReadMe that were ingested before we had proper
+ *    validation in place, and as a result have some API definitions that will not pass validation
+ *    right now. In addition to reshaping OAS-JSON Schema into JSON Schema this library will also
+ *    fix these improper schemas: things like `type: object` having `items` instead of `properties`,
+ *    or `type: array` missing `items`.
+ *  3. To ease the burden of polymorphic handling on our form rendering engine we make an attempt
+ *    to merge `allOf` schemas here.
+ *  4. Additionally due to OpenAPI 3.0.x not supporting JSON Schema, in order to support the
+ *    `example` keyword that OAS supports, we need to do some work in here to remap it into
+ *    `examples`. However, since all we care about in respect to examples for usage within
+ *    `@readme/oas-form`, we're only retaining primitives. This *slightly* deviates from JSON
+ *    Schema in that JSON Schema allows for any schema to be an example, but since
+ *    `@readme/oas-form` can only actually **render** primitives, that's what we're retaining.
+ *  5. Though OpenAPI 3.1 does support full JSON Schema, this library should be able to handle it
+ *    without any problems.
  *
- * And why use this over `@openapi-contrib/openapi-schema-to-json-schema`? Fortunately and unfortunately we've got a lot
- * of API definitions in our database that aren't currently valid so we need to have a lot of bespoke handling for odd
- * quirks, typos, and missing declarations that might be present.
+ * And why use this over `@openapi-contrib/openapi-schema-to-json-schema`? Fortunately and
+ * unfortunately we've got a lot of API definitions in our database that aren't currently valid so
+ * we need to have a lot of bespoke handling for odd quirks, typos, and missing declarations that
+ * might be present.
  *
  * @todo add support for `schema: false` and `not` cases.
  * @see {@link https://json-schema.org/draft/2019-09/json-schema-validation.html}
@@ -40,11 +46,12 @@ export declare function isPrimitive(val: unknown): boolean;
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject}
  * @param data OpenAPI Schema Object to convert to pure JSON Schema.
  * @param opts Options
+ * @param opts.addEnumsToDescriptions Whether or not to extend descriptions with a list of any present enums.
  * @param opts.currentLocation Current location within the schema -- this is a JSON pointer.
  * @param opts.globalDefaults Object containing a global set of defaults that we should apply to schemas that match it.
  * @param opts.isPolymorphicAllOfChild Is this schema the child of a polymorphic `allOf` schema?
  * @param opts.prevSchemas Array of parent schemas to utilize when attempting to path together examples.
  * @param opts.refLogger A function that's called anytime a (circular) `$ref` is found.
  */
-export default function toJSONSchema(data: RMOAS.SchemaObject | boolean, opts?: toJsonSchemaOptions): RMOAS.SchemaObject;
+export default function toJSONSchema(data: RMOAS.SchemaObject | boolean, opts?: toJSONSchemaOptions): RMOAS.SchemaObject;
 export {};

package/@types/operation/get-callback-examples.d.ts

@@ -6,7 +6,8 @@ export declare type CallbackExamples = {
     example: unknown;
 }[];
 /**
- * With an OpenAPI Operation Object return back a collection of examples for any callbacks that may be present.
+ * With an OpenAPI Operation Object return back a collection of examples for any callbacks that may
+ * be present.
  *
  * @param operation Operation to retrieve callback examples from.
  */

package/@types/operation/get-parameters-as-json-schema.d.ts

@@ -8,7 +8,8 @@ export declare type SchemaWrapper = {
     deprecatedProps?: SchemaWrapper;
 };
 /**
- * The order of this object determines how they will be sorted in the compiled JSON Schema representation.
+ * The order of this object determines how they will be sorted in the compiled JSON Schema
+ * representation.
  *
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#parameterObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject}

package/@types/operation.d.ts

@@ -52,28 +52,29 @@ export default class Operation {
     isJson(): boolean;
     isXml(): boolean;
     /**
-     * Returns an array of all security requirements associated wtih this operation. If none are defined at the operation
-     * level, the securities for the entire API definition are returned (with an empty array as a final fallback).
+     * Returns an array of all security requirements associated wtih this operation. If none are
+     * defined at the operation level, the securities for the entire API definition are returned
+     * (with an empty array as a final fallback).
      *
      */
     getSecurity(): RMOAS.SecurityRequirementObject[];
     /**
-     * Retrieve a collection of grouped security schemes. The inner array determines and-grouped security schemes, the
-     * outer array determines or-groups.
+     * Retrieve a collection of grouped security schemes. The inner array determines and-grouped
+     * security schemes, the outer array determines or-groups.
      *
      * @see {@link https://swagger.io/docs/specification/authentication/#multiple}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject}
-     * @param filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent security schemes,
-     *    rather than returning `false`.
+     * @param filterInvalid Optional flag that, when set to `true`, filters out invalid/nonexistent
+     *    security schemes, rather than returning `false`.
      */
     getSecurityWithTypes(filterInvalid?: boolean): (false | (false | {
         security: RMOAS.KeyedSecuritySchemeObject;
         type: SecurityType;
     })[])[];
     /**
-     * Retrieve an object where the keys are unique scheme types, and the values are arrays containing each security
-     * scheme of that type.
+     * Retrieve an object where the keys are unique scheme types, and the values are arrays
+     * containing each security scheme of that type.
      *
      */
     prepareSecurity(): Record<SecurityType, RMOAS.KeyedSecuritySchemeObject[]>;
@@ -120,8 +121,8 @@ export default class Operation {
      */
     hasRequiredParameters(): boolean;
     /**
-     * Convert the operation into an array of JSON Schema schemas for each available type of parameter available on the
-     * operation.
+     * Convert the operation into an array of JSON Schema schemas for each available type of
+     * parameter available on the operation.
      *
      * @param opts
      * @param opts.globalDefaults Contains an object of user defined schema defaults.
@@ -172,9 +173,10 @@ export default class Operation {
     /**
      * Retrieve a specific request body content schema off this operation.
      *
-     * If no media type is supplied this will return either the first available JSON-like request body, or the first
-     * available if there are no JSON-like media types present. When this return comes back it's in the form of an array
-     * with the first key being the selected media type, followed by the media type object in question.
+     * If no media type is supplied this will return either the first available JSON-like request
+     * body, or the first available if there are no JSON-like media types present. When this return
+     * comes back it's in the form of an array with the first key being the selected media type,
+     * followed by the media type object in question.
      *
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject}
      * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject}

package/@types/samples/index.d.ts

@@ -7,8 +7,9 @@
 import type * as RMOAS from '../rmoas.types';
 import memoize from 'memoizee';
 /**
- * Generate a piece of sample data from a JSON Schema object. If `example` declarations are present they will be
- * utilized, but generally this will generate fake data for the information present in the schema.
+ * Generate a piece of sample data from a JSON Schema object. If `example` declarations are present
+ * they will be utilized, but generally this will generate fake data for the information present in
+ * the schema.
  *
  * @param schema JSON Schema to generate a sample for.
  * @param opts Options

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## <small>18.3.1 (2022-04-26)</small>
+
+* chore(deps): bumping out of date deps to get rid of node 18 compat issues (#639) ([13703c8](https://github.com/readmeio/oas/commit/13703c8)), closes [#639](https://github.com/readmeio/oas/issues/639)
+
+
+
 ## <small>18.2.2 (2022-04-11)</small>
 
 * fix: stop rewriting operationIds when we don't need to (#635) ([996cd40](https://github.com/readmeio/oas/commit/996cd40)), closes [#635](https://github.com/readmeio/oas/issues/635)