oas/dist/reducer/index.d.ts

Comprehensive tooling for working with OpenAPI definitions

import { OASDocument } from '../types.js';
import 'json-schema';
import 'openapi-types';

declare class OpenAPIReducer {
    private definition;
    /**
     * A collection of `$ref` pointers that are used within our reduced API definition. This is used
     * to ensure that all referenced schemas are retained in our resulting API definition. Not
     * retaining them would result in an invalid OpenAPI definition.
     */
    private $refs;
    /**
     * A collection of OpenAPI tags that are used within our reduced API definition.
     */
    private usedTags;
    /**
     * A collection of OpenAPI paths and operations that are cross-referenced from any other paths
     * and operations that we are reducing. This collection is used in order to ensure that those
     * schemas are retained with our resulting API definition. Not retaining them would result in an
     * invalid OpenAPI definition.
     */
    private retainPathMethods;
    /**
     * A collection of OpenAPI webhook names and methods that are cross-referenced from any other
     * schemas. This collection, like `retainPathMethods`, is used in order to ensure that those
     * schemas are retained with our resulting API definition. Not retaining them would result in an
     * invalid OpenAPI definition.
     */
    private retainWebhookMethods;
    /**
     * An array of OpenAPI tags to reduce down to.
     */
    private tagsToReduceBy;
    /**
     * A collection of OpenAPI paths and operations to reduce down to.
     */
    private pathsToReduceBy;
    /**
     * A collection of OpenAPI webhooks to reduce down to.
     */
    private webhooksToReduceBy;
    private hasTagsToReduceBy;
    private hasPathsToReduceBy;
    private hasWebhooksToReduceBy;
    private constructor();
    /**
     * Initialize a new instance of the `OpenAPIReducer`. The reducer allows you to reduce an OpenAPI
     * definition down to only the information necessary to fulfill a specific set of tags, paths,
     * operations, and webhooks.
     *
     * OpenAPI reduction can be helpful not only to isolate and troubleshoot issues with large API
     * definitions, but also to compress a large API definition down to a manageable size containing
     * a specific set of items.
     *
     * All OpenAPI definitions reduced will still be fully functional and valid OpenAPI definitions.
     *
     * @param definition An OpenAPI definition to reduce.
     */
    static init(definition: OASDocument): OpenAPIReducer;
    /**
     * Mark an OpenAPI tag to be included in our reduced API definition. Tag casing does not matter.
     *
     * @param tag The tag to mark for reduction.
     */
    byTag(tag: string): OpenAPIReducer;
    /**
     * Mark an entire OpenAPI path, and all methods that it contains, to be included in your reduced
     * API definition. Path casing does not matter.
     *
     * @param path The path to mark for reduction.
     */
    byPath(path: string): OpenAPIReducer;
    /**
     * Mark a single OpenAPI operation to be included in your reduced API definition. If the path
     * that this operation is a part of utilizes common parameters, those will be automatically
     * included. Path and method casing does not matter.
     *
     * Note that if you previously called `.byPath()` to reduce an entire path down, calling
     * `.byOperation()` will override that to just reduce this specific method (or this plus
     * subsequent calls to `.byOperation()`).
     *
     * @param path The path that the operation is a part of.
     * @param method The HTTP method of the operation to mark for reduction.
     *
     */
    byOperation(path: string, method: string): OpenAPIReducer;
    /**
     * Mark an OpenAPI webhook (and all of its operations) to be included in your reduced API
     * definition. Casing does not matter.
     *
     * @param webhookName The webhook name to mark for reduction.
     */
    byWebhook(webhookName: string): OpenAPIReducer;
    /**
     * Mark a single OpenAPI webhook operation to be included in your reduced API definition.
     * Casing does not matter.
     *
     * @param webhookName The webhook name that the operation belongs to.
     * @param method The HTTP method of the webhook operation to mark for reduction.
     */
    byWebhook(webhookName: string, method: string): OpenAPIReducer;
    /**
     * Reduce the current OpenAPI definition down to the configured filters.
     *
     */
    reduce(): OASDocument;
    /**
     * Recursively process a `$ref` pointer and accumulate any other `$ref` pointers that it or its
     * children use. This handles circular references by skipping `$ref` pointers we have already seen.
     * Additionally when a `$ref` points to `#/paths` we record the used path + method so we can
     * retain cross-operation references within the reduced definition.
     *
     * @param schema JSON Schema object to look for and accumulate any `$ref` pointers that it may have.
     * @param $refs Known set of `$ref` pointers.
     * @param $ref `$ref` pointer to fetch a schema from out of the supplied schema.
     */
    private accumulateUsedRefs;
    /**
     * Query a JSON Schema object for any `$ref` pointers using JSONPath and return any pointers that
     * exist.
     *
     * @see {@link https://datatracker.ietf.org/doc/html/rfc9535}
     * @param schema JSON Schema object to look for any `$ref` pointers within it.
     */
    private queryForRefPointers;
    /**
     * Normalize a value from a `jsonpath-plus` `$ref` query to a `$ref` pointer because JSONPath
     * queries may return the property value or the parent.
     *
     */
    private toRefString;
    /**
     * If the given `$ref` points into a path (e.g. `#/paths/~1anything/post/...`), return the path
     * and method so the reducer can ultimately retain cross-operation references.
     *
     */
    private parsePathRef;
    /**
     * If the given `$ref` points into webhooks (e.g. `#/webhooks/newBooking/post/...`), return the
     * webhook name and method so the reducer can retain cross-referenced webhook operations.
     *
     */
    private parseWebhookRef;
    /**
     * Walk through the `paths` in our OpenAPI definition and reduce down any that we know we do not
     * want to keep and accumulate any `$ref` pointers that we find that may be cross-referenced in
     * paths, webhooks, operations, and schemas that we _do_ want to keep.
     *
     */
    private walkPaths;
    /**
     * Walk through the `webhooks` in our OpenAPI definition and reduce down any that we know we do
     * not want to keep and accumulate any `$ref` pointers that we find that may be cross-referenced
     * in paths, operations, and schemas that we _do_ want to keep.
     *
     */
    private walkWebhooks;
    /**
     * Prune back our `paths` object in the OpenAPI definition to only include paths that we want to
     * preserve.
     *
     */
    private reducePaths;
    /**
     * Prune back our `webhooks` object in the OpenAPI definition to only include webhooks that we
     * want to preserve.
     *
     */
    private reduceWebhooks;
}

export { OpenAPIReducer };