From 211426c876c23974dcbc52d2f215d19917c801e2 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Thu, 21 Nov 2024 08:50:27 +0100 Subject: [PATCH] chore(reference): use API Extractor for TypeScript rollup Refs #4382 --- .../config/api-extractor/api-extractor.json | 4 +++ .../config/rollup/types.dist.js | 11 ------- packages/apidom-reference/package.json | 10 +++---- packages/apidom-reference/src/File.ts | 4 +++ packages/apidom-reference/src/Reference.ts | 6 ++++ packages/apidom-reference/src/ReferenceSet.ts | 6 ++++ .../src/bundle/strategies/BundleStrategy.ts | 6 ++++ .../strategies/DereferenceStrategy.ts | 6 ++++ .../apidom-reference/src/dereference/util.ts | 3 ++ .../src/errors/BundleError.ts | 3 ++ .../src/errors/DereferenceError.ts | 3 ++ .../src/errors/EvaluationElementIdError.ts | 3 ++ .../EvaluationJsonSchema$anchorError.ts | 3 ++ .../errors/EvaluationJsonSchemaUriError.ts | 3 ++ .../errors/InvalidJsonSchema$anchorError.ts | 3 ++ .../src/errors/JsonSchema$anchorError.ts | 3 ++ .../src/errors/JsonSchemaUriError.ts | 3 ++ .../src/errors/MaximumBundleDepthError.ts | 3 ++ .../errors/MaximumDereferenceDepthError.ts | 3 ++ .../src/errors/MaximumResolveDepthError.ts | 3 ++ .../apidom-reference/src/errors/ParseError.ts | 3 ++ .../src/errors/ParserError.ts | 3 ++ .../src/errors/PluginError.ts | 3 ++ .../src/errors/ResolveError.ts | 3 ++ .../src/errors/ResolverError.ts | 3 ++ .../errors/UnmatchedBundleStrategyError.ts | 3 ++ .../UnmatchedDereferenceStrategyError.ts | 3 ++ .../errors/UnmatchedResolveStrategyError.ts | 3 ++ .../src/errors/UnmatchedResolverError.ts | 3 ++ packages/apidom-reference/src/index.ts | 29 ++++++++++++++++++ .../apidom-reference/src/options/index.ts | 26 +++++++++++++--- packages/apidom-reference/src/options/util.ts | 3 ++ .../src/parse/parsers/Parser.ts | 6 ++++ .../src/resolve/resolvers/HTTPResolver.ts | 6 ++++ .../src/resolve/resolvers/Resolver.ts | 6 ++++ .../src/resolve/strategies/ResolveStrategy.ts | 6 ++++ packages/apidom-reference/src/util/url.ts | 30 +++++++++++++++---- 37 files changed, 203 insertions(+), 25 deletions(-) create mode 100644 packages/apidom-reference/config/api-extractor/api-extractor.json delete mode 100644 packages/apidom-reference/config/rollup/types.dist.js diff --git a/packages/apidom-reference/config/api-extractor/api-extractor.json b/packages/apidom-reference/config/api-extractor/api-extractor.json new file mode 100644 index 0000000000..7de0d99447 --- /dev/null +++ b/packages/apidom-reference/config/api-extractor/api-extractor.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "extends": "../../../../api-extractor.json" +} diff --git a/packages/apidom-reference/config/rollup/types.dist.js b/packages/apidom-reference/config/rollup/types.dist.js deleted file mode 100644 index 308fe65359..0000000000 --- a/packages/apidom-reference/config/rollup/types.dist.js +++ /dev/null @@ -1,11 +0,0 @@ -import dts from 'rollup-plugin-dts'; - -const config = [ - { - input: './types/index.d.ts', - output: [{ file: 'types/dist.d.ts', format: 'es' }], - plugins: [dts()], - }, -]; - -export default config; diff --git a/packages/apidom-reference/package.json b/packages/apidom-reference/package.json index 47686c4cf7..2edb29d961 100644 --- a/packages/apidom-reference/package.json +++ b/packages/apidom-reference/package.json @@ -19,22 +19,22 @@ "./src/resolve/resolvers/file/index-node.mjs": "./src/resolve/resolvers/file/index-browser.mjs" }, "main": "./src/configuration/saturated.cjs", - "types": "./types/dist.d.ts", + "types": "./types/apidom-reference.d.ts", "exports": { ".": { "import": "./src/configuration/saturated.mjs", "require": "./src/configuration/saturated.cjs", - "types": "./types/dist.d.ts" + "types": "./types/apidom-reference.d.ts" }, "./configuration/saturated": { "import": "./src/configuration/saturated.mjs", "require": "./src/configuration/saturated.cjs", - "types": "./types/dist.d.ts" + "types": "./types/apidom-reference.d.ts" }, "./configuration/empty": { "import": "./src/configuration/empty.mjs", "require": "./src/configuration/empty.cjs", - "types": "./types/dist.d.ts" + "types": "./types/apidom-reference.d.ts" }, "./resolve/resolvers/file": { "browser": { @@ -246,7 +246,7 @@ "perf": "cross-env BABEL_ENV=es babel ./test/perf/index.ts --out-file ./test/perf/index.mjs --root-mode 'upward' && cross-env NODE_ENV=test node ./test/perf/index.mjs", "perf:openapi-3-1-dereference": "cross-env BABEL_ENV=es babel ./test/perf/openapi-3-1-dereference.ts --out-file ./test/perf/openapi-3-1-dereference.mjs --root-mode 'upward' && cross-env NODE_ENV=test node ./test/perf/openapi-3-1-dereference.mjs", "typescript:check-types": "tsc --noEmit && tsc -p ./test/tsconfig.json --noEmit", - "typescript:declaration": "tsc -p tsconfig.declaration.json && rollup -c config/rollup/types.dist.js", + "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json", "prepack": "copyfiles -u 3 ../../LICENSES/* LICENSES && copyfiles -u 2 ../../NOTICE .", "postpack": "rimraf NOTICE LICENSES" }, diff --git a/packages/apidom-reference/src/File.ts b/packages/apidom-reference/src/File.ts index 800efa07bd..2aba33e3f6 100644 --- a/packages/apidom-reference/src/File.ts +++ b/packages/apidom-reference/src/File.ts @@ -6,6 +6,7 @@ import * as url from './util/url.ts'; /** * This class represents a File object with url and data. + * @public */ export interface FileOptions { @@ -15,6 +16,9 @@ export interface FileOptions { readonly parseResult?: ParseResultElement; } +/** + * @public + */ class File { public uri: string; diff --git a/packages/apidom-reference/src/Reference.ts b/packages/apidom-reference/src/Reference.ts index baa80b8754..03d7cb0962 100644 --- a/packages/apidom-reference/src/Reference.ts +++ b/packages/apidom-reference/src/Reference.ts @@ -2,6 +2,9 @@ import { Element } from '@swagger-api/apidom-core'; import ReferenceSet from './ReferenceSet.ts'; +/** + * @public + */ export interface ReferenceOptions { readonly uri: string; readonly depth?: number; @@ -9,6 +12,9 @@ export interface ReferenceOptions { readonly value: T; } +/** + * @public + */ class Reference { public readonly uri: string; diff --git a/packages/apidom-reference/src/ReferenceSet.ts b/packages/apidom-reference/src/ReferenceSet.ts index f2fad2092f..f6833626ef 100644 --- a/packages/apidom-reference/src/ReferenceSet.ts +++ b/packages/apidom-reference/src/ReferenceSet.ts @@ -2,11 +2,17 @@ import { isNotUndefined, isString } from 'ramda-adjunct'; import type Reference from './Reference.ts'; +/** + * @public + */ export interface ReferenceSetOptions { readonly refs?: Reference[]; readonly circular?: boolean; } +/** + * @public + */ class ReferenceSet { public rootRef?: Reference; diff --git a/packages/apidom-reference/src/bundle/strategies/BundleStrategy.ts b/packages/apidom-reference/src/bundle/strategies/BundleStrategy.ts index 4849e898fd..b76cf87a7a 100644 --- a/packages/apidom-reference/src/bundle/strategies/BundleStrategy.ts +++ b/packages/apidom-reference/src/bundle/strategies/BundleStrategy.ts @@ -3,10 +3,16 @@ import { ParseResultElement } from '@swagger-api/apidom-core'; import File from '../../File.ts'; import type { ReferenceOptions } from '../../options/index.ts'; +/** + * @public + */ export interface BundleStrategyOptions { readonly name: string; } +/** + * @public + */ abstract class BundleStrategy { public readonly name: string; diff --git a/packages/apidom-reference/src/dereference/strategies/DereferenceStrategy.ts b/packages/apidom-reference/src/dereference/strategies/DereferenceStrategy.ts index a4c3c10add..313ca494cc 100644 --- a/packages/apidom-reference/src/dereference/strategies/DereferenceStrategy.ts +++ b/packages/apidom-reference/src/dereference/strategies/DereferenceStrategy.ts @@ -3,10 +3,16 @@ import { Element } from 'minim'; import File from '../../File.ts'; import type { ReferenceOptions } from '../../options/index.ts'; +/** + * @public + */ export interface DereferenceStrategyOptions { readonly name: string; } +/** + * @public + */ abstract class DereferenceStrategy { public readonly name: string; diff --git a/packages/apidom-reference/src/dereference/util.ts b/packages/apidom-reference/src/dereference/util.ts index 8fb5c3871e..df15ff210b 100644 --- a/packages/apidom-reference/src/dereference/util.ts +++ b/packages/apidom-reference/src/dereference/util.ts @@ -1,5 +1,8 @@ import { Element, isElement } from '@swagger-api/apidom-core'; +/** + * @public + */ // eslint-disable-next-line import/prefer-default-export export class AncestorLineage extends Array> { includesCycle(element: T) { diff --git a/packages/apidom-reference/src/errors/BundleError.ts b/packages/apidom-reference/src/errors/BundleError.ts index 8bfdff9ff4..4892418835 100644 --- a/packages/apidom-reference/src/errors/BundleError.ts +++ b/packages/apidom-reference/src/errors/BundleError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class BundleError extends ApiDOMError {} export default BundleError; diff --git a/packages/apidom-reference/src/errors/DereferenceError.ts b/packages/apidom-reference/src/errors/DereferenceError.ts index dacfd60f30..c95a9553f9 100644 --- a/packages/apidom-reference/src/errors/DereferenceError.ts +++ b/packages/apidom-reference/src/errors/DereferenceError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class DereferenceError extends ApiDOMError {} export default DereferenceError; diff --git a/packages/apidom-reference/src/errors/EvaluationElementIdError.ts b/packages/apidom-reference/src/errors/EvaluationElementIdError.ts index be994e7346..7e63c7e3d7 100644 --- a/packages/apidom-reference/src/errors/EvaluationElementIdError.ts +++ b/packages/apidom-reference/src/errors/EvaluationElementIdError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class EvaluationElementIdError extends ApiDOMError {} export default EvaluationElementIdError; diff --git a/packages/apidom-reference/src/errors/EvaluationJsonSchema$anchorError.ts b/packages/apidom-reference/src/errors/EvaluationJsonSchema$anchorError.ts index 734523ca53..3595bed6a5 100644 --- a/packages/apidom-reference/src/errors/EvaluationJsonSchema$anchorError.ts +++ b/packages/apidom-reference/src/errors/EvaluationJsonSchema$anchorError.ts @@ -1,5 +1,8 @@ import JsonSchema$anchorError from './JsonSchema$anchorError.ts'; +/** + * @public + */ class EvaluationJsonSchema$anchorError extends JsonSchema$anchorError {} export default EvaluationJsonSchema$anchorError; diff --git a/packages/apidom-reference/src/errors/EvaluationJsonSchemaUriError.ts b/packages/apidom-reference/src/errors/EvaluationJsonSchemaUriError.ts index dc33b88c01..c9e145cd5e 100644 --- a/packages/apidom-reference/src/errors/EvaluationJsonSchemaUriError.ts +++ b/packages/apidom-reference/src/errors/EvaluationJsonSchemaUriError.ts @@ -1,5 +1,8 @@ import JsonSchemaUriError from './JsonSchemaUriError.ts'; +/** + * @public + */ class EvaluationJsonSchemaUriError extends JsonSchemaUriError {} export default EvaluationJsonSchemaUriError; diff --git a/packages/apidom-reference/src/errors/InvalidJsonSchema$anchorError.ts b/packages/apidom-reference/src/errors/InvalidJsonSchema$anchorError.ts index f8562ef080..0487b170f7 100644 --- a/packages/apidom-reference/src/errors/InvalidJsonSchema$anchorError.ts +++ b/packages/apidom-reference/src/errors/InvalidJsonSchema$anchorError.ts @@ -1,5 +1,8 @@ import JsonSchema$anchorError from './JsonSchema$anchorError.ts'; +/** + * @public + */ class InvalidJsonSchema$anchorError extends JsonSchema$anchorError { constructor(anchor: string) { super(`Invalid JSON Schema $anchor "${anchor}".`); diff --git a/packages/apidom-reference/src/errors/JsonSchema$anchorError.ts b/packages/apidom-reference/src/errors/JsonSchema$anchorError.ts index ed89b8c96b..e43574da95 100644 --- a/packages/apidom-reference/src/errors/JsonSchema$anchorError.ts +++ b/packages/apidom-reference/src/errors/JsonSchema$anchorError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class JsonSchema$anchorError extends ApiDOMError {} export default JsonSchema$anchorError; diff --git a/packages/apidom-reference/src/errors/JsonSchemaUriError.ts b/packages/apidom-reference/src/errors/JsonSchemaUriError.ts index 2bc032a6c4..782258079f 100644 --- a/packages/apidom-reference/src/errors/JsonSchemaUriError.ts +++ b/packages/apidom-reference/src/errors/JsonSchemaUriError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class JsonSchemaUriError extends ApiDOMError {} export default JsonSchemaUriError; diff --git a/packages/apidom-reference/src/errors/MaximumBundleDepthError.ts b/packages/apidom-reference/src/errors/MaximumBundleDepthError.ts index 5ae744e08f..0ef5abc325 100644 --- a/packages/apidom-reference/src/errors/MaximumBundleDepthError.ts +++ b/packages/apidom-reference/src/errors/MaximumBundleDepthError.ts @@ -1,5 +1,8 @@ import BundleError from './BundleError.ts'; +/** + * @public + */ class MaximumBundleDepthError extends BundleError {} export default MaximumBundleDepthError; diff --git a/packages/apidom-reference/src/errors/MaximumDereferenceDepthError.ts b/packages/apidom-reference/src/errors/MaximumDereferenceDepthError.ts index cebda81c14..b7413ab6f9 100644 --- a/packages/apidom-reference/src/errors/MaximumDereferenceDepthError.ts +++ b/packages/apidom-reference/src/errors/MaximumDereferenceDepthError.ts @@ -1,5 +1,8 @@ import DereferenceError from './DereferenceError.ts'; +/** + * @public + */ class MaximumDereferenceDepthError extends DereferenceError {} export default MaximumDereferenceDepthError; diff --git a/packages/apidom-reference/src/errors/MaximumResolveDepthError.ts b/packages/apidom-reference/src/errors/MaximumResolveDepthError.ts index 91197522d5..e99fee8004 100644 --- a/packages/apidom-reference/src/errors/MaximumResolveDepthError.ts +++ b/packages/apidom-reference/src/errors/MaximumResolveDepthError.ts @@ -1,5 +1,8 @@ import ResolveError from './ResolveError.ts'; +/** + * @public + */ class MaximumResolveDepthError extends ResolveError {} export default MaximumResolveDepthError; diff --git a/packages/apidom-reference/src/errors/ParseError.ts b/packages/apidom-reference/src/errors/ParseError.ts index 7db180a8c4..78e799fd51 100644 --- a/packages/apidom-reference/src/errors/ParseError.ts +++ b/packages/apidom-reference/src/errors/ParseError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class ParseError extends ApiDOMError {} export default ParseError; diff --git a/packages/apidom-reference/src/errors/ParserError.ts b/packages/apidom-reference/src/errors/ParserError.ts index 6891dad4b8..623e51b654 100644 --- a/packages/apidom-reference/src/errors/ParserError.ts +++ b/packages/apidom-reference/src/errors/ParserError.ts @@ -1,5 +1,8 @@ import ParseError from './ParseError.ts'; +/** + * @public + */ class ParserError extends ParseError {} export default ParserError; diff --git a/packages/apidom-reference/src/errors/PluginError.ts b/packages/apidom-reference/src/errors/PluginError.ts index b8452a69bd..85d1bae7ae 100644 --- a/packages/apidom-reference/src/errors/PluginError.ts +++ b/packages/apidom-reference/src/errors/PluginError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class PluginError extends ApiDOMError { public plugin: any; diff --git a/packages/apidom-reference/src/errors/ResolveError.ts b/packages/apidom-reference/src/errors/ResolveError.ts index f89d0f91d6..0302a9f3dc 100644 --- a/packages/apidom-reference/src/errors/ResolveError.ts +++ b/packages/apidom-reference/src/errors/ResolveError.ts @@ -1,5 +1,8 @@ import { ApiDOMError } from '@swagger-api/apidom-error'; +/** + * @public + */ class ResolveError extends ApiDOMError {} export default ResolveError; diff --git a/packages/apidom-reference/src/errors/ResolverError.ts b/packages/apidom-reference/src/errors/ResolverError.ts index 8bd842c23c..3c4f19f089 100644 --- a/packages/apidom-reference/src/errors/ResolverError.ts +++ b/packages/apidom-reference/src/errors/ResolverError.ts @@ -1,5 +1,8 @@ import ResolveError from './ResolveError.ts'; +/** + * @public + */ class ResolverError extends ResolveError {} export default ResolverError; diff --git a/packages/apidom-reference/src/errors/UnmatchedBundleStrategyError.ts b/packages/apidom-reference/src/errors/UnmatchedBundleStrategyError.ts index ba591d87dc..98ecd1b6b9 100644 --- a/packages/apidom-reference/src/errors/UnmatchedBundleStrategyError.ts +++ b/packages/apidom-reference/src/errors/UnmatchedBundleStrategyError.ts @@ -1,5 +1,8 @@ import BundleError from './BundleError.ts'; +/** + * @public + */ class UnmatchedBundleStrategyError extends BundleError {} export default UnmatchedBundleStrategyError; diff --git a/packages/apidom-reference/src/errors/UnmatchedDereferenceStrategyError.ts b/packages/apidom-reference/src/errors/UnmatchedDereferenceStrategyError.ts index 006e26c43b..756fdfe2c9 100644 --- a/packages/apidom-reference/src/errors/UnmatchedDereferenceStrategyError.ts +++ b/packages/apidom-reference/src/errors/UnmatchedDereferenceStrategyError.ts @@ -1,5 +1,8 @@ import DereferenceError from './DereferenceError.ts'; +/** + * @public + */ class UnmatchedDereferenceStrategyError extends DereferenceError {} export default UnmatchedDereferenceStrategyError; diff --git a/packages/apidom-reference/src/errors/UnmatchedResolveStrategyError.ts b/packages/apidom-reference/src/errors/UnmatchedResolveStrategyError.ts index 0df59727ff..aefc01c421 100644 --- a/packages/apidom-reference/src/errors/UnmatchedResolveStrategyError.ts +++ b/packages/apidom-reference/src/errors/UnmatchedResolveStrategyError.ts @@ -1,5 +1,8 @@ import ResolveError from './ResolveError.ts'; +/** + * @public + */ class UnmatchedResolveStrategyError extends ResolveError {} export default UnmatchedResolveStrategyError; diff --git a/packages/apidom-reference/src/errors/UnmatchedResolverError.ts b/packages/apidom-reference/src/errors/UnmatchedResolverError.ts index 6f7728cd82..2d52b33a95 100644 --- a/packages/apidom-reference/src/errors/UnmatchedResolverError.ts +++ b/packages/apidom-reference/src/errors/UnmatchedResolverError.ts @@ -1,5 +1,8 @@ import ResolverError from './ResolverError.ts'; +/** + * @public + */ class UnmatchedResolverError extends ResolverError {} export default UnmatchedResolverError; diff --git a/packages/apidom-reference/src/index.ts b/packages/apidom-reference/src/index.ts index 1b6b06edde..8bdd77597a 100644 --- a/packages/apidom-reference/src/index.ts +++ b/packages/apidom-reference/src/index.ts @@ -18,6 +18,7 @@ export type { ParserOptions } from './parse/parsers/Parser.ts'; export { default as Resolver } from './resolve/resolvers/Resolver.ts'; export { default as HTTPResolver } from './resolve/resolvers/HTTPResolver.ts'; +export type { HTTPResolverOptions } from './resolve/resolvers/HTTPResolver.ts'; export { default as ResolveStrategy } from './resolve/strategies/ResolveStrategy.ts'; export type { ResolverOptions } from './resolve/resolvers/Resolver.ts'; export type { ResolveStrategyOptions } from './resolve/strategies/ResolveStrategy.ts'; @@ -31,6 +32,13 @@ export type { BundleStrategyOptions } from './bundle/strategies/BundleStrategy.t export { default as options } from './options/index.ts'; export { merge as mergeOptions } from './options/util.ts'; +export type { + ReferenceOptions as ApiDOMReferenceOptions, + ReferenceBundleOptions as ApiDOMReferenceBundleOptions, + ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions, + ReferenceParseOptions as ApiDOMReferenceParseOptions, + ReferenceResolveOptions as ApiDOMReferenceResolveOptions, +} from './options/index.ts'; export { File }; export { default as Reference } from './Reference.ts'; @@ -60,6 +68,9 @@ export { default as UnmatchedDereferenceStrategyError } from './errors/Unmatched export { default as UnmatchedResolveStrategyError } from './errors/UnmatchedResolveStrategyError.ts'; export { default as UnmatchedResolverError } from './errors/UnmatchedResolverError.ts'; +/** + * @public + */ export const readFile = async (uri: string, options = {}): Promise => { const mergedOptions = mergeOptions(defaultOptions, options); const file = new File({ uri: url.sanitize(uri) }); @@ -67,16 +78,25 @@ export const readFile = async (uri: string, options = {}): Promise => { return readFileFn(file, mergedOptions); }; +/** + * @public + */ export const parse = async (uri: string, options = {}): Promise => { const mergedOptions = mergeOptions(defaultOptions, options); return parseFn(uri, mergedOptions); }; +/** + * @public + */ export const resolve = async (uri: string, options = {}): Promise => { const mergedOptions = mergeOptions(defaultOptions, options); return resolveFn(uri, mergedOptions); }; +/** + * @public + */ export const resolveApiDOM = async ( element: T, options = {}, @@ -85,11 +105,17 @@ export const resolveApiDOM = async ( return resolveApiDOMFn(element, mergedOptions); }; +/** + * @public + */ export const dereference = async (uri: string, options = {}): Promise => { const mergedOptions = mergeOptions(defaultOptions, options); return dereferenceFn(uri, mergedOptions); }; +/** + * @public + */ export const dereferenceApiDOM = async ( element: T, options = {}, @@ -98,6 +124,9 @@ export const dereferenceApiDOM = async ( return dereferenceApiDOMFn(element, mergedOptions); }; +/** + * @public + */ export const bundle = async (uri: string, options = {}): Promise => { const mergedOptions = mergeOptions(defaultOptions, options); return bundleFn(uri, mergedOptions); diff --git a/packages/apidom-reference/src/options/index.ts b/packages/apidom-reference/src/options/index.ts index b3790ebfd0..4a1e7cbd98 100644 --- a/packages/apidom-reference/src/options/index.ts +++ b/packages/apidom-reference/src/options/index.ts @@ -8,13 +8,19 @@ import type DereferenceStrategy from '../dereference/strategies/DereferenceStrat import type ReferenceSet from '../ReferenceSet.ts'; import type BundleStrategy from '../bundle/strategies/BundleStrategy.ts'; -interface ReferenceParseOptions { +/** + * @public + */ +export interface ReferenceParseOptions { mediaType: string; parsers: Array; parserOpts: Record; } -interface ReferenceResolveOptions { +/** + * @public + */ +export interface ReferenceResolveOptions { baseURI: string; resolvers: Array; resolverOpts: Record; @@ -25,7 +31,10 @@ interface ReferenceResolveOptions { maxDepth: number; } -interface ReferenceDereferenceOptions { +/** + * @public + */ +export interface ReferenceDereferenceOptions { strategies: Array; strategyOpts: Record; refSet: null | ReferenceSet; @@ -35,12 +44,18 @@ interface ReferenceDereferenceOptions { immutable: boolean; } -interface ReferenceBundleOptions { +/** + * @public + */ +export interface ReferenceBundleOptions { strategies: Array; refSet: null | ReferenceSet; maxDepth: number; } +/** + * @public + */ export interface ReferenceOptions { readonly parse: ReferenceParseOptions; readonly resolve: ReferenceResolveOptions; @@ -48,6 +63,9 @@ export interface ReferenceOptions { readonly bundle: ReferenceBundleOptions; } +/** + * @public + */ const defaultOptions: ReferenceOptions = { parse: { /** diff --git a/packages/apidom-reference/src/options/util.ts b/packages/apidom-reference/src/options/util.ts index 0720617fd8..5adf4ce19a 100644 --- a/packages/apidom-reference/src/options/util.ts +++ b/packages/apidom-reference/src/options/util.ts @@ -11,6 +11,9 @@ import type { ReferenceOptions } from './index.ts'; const baseURILens = lens(path(['resolve', 'baseURI']), assocPath(['resolve', 'baseURI'])); const baseURIDefault = (baseURI: string) => (isEmptyString(baseURI) ? cwd() : baseURI); +/** + * @public + */ // eslint-disable-next-line import/prefer-default-export export const merge = (lObj: ReferenceOptions, rObj: Record): ReferenceOptions => { const withoutDefaults = mergeDeepRight(lObj, rObj); diff --git a/packages/apidom-reference/src/parse/parsers/Parser.ts b/packages/apidom-reference/src/parse/parsers/Parser.ts index d6b2101791..5232a77dc8 100644 --- a/packages/apidom-reference/src/parse/parsers/Parser.ts +++ b/packages/apidom-reference/src/parse/parsers/Parser.ts @@ -2,6 +2,9 @@ import { ParseResultElement } from '@swagger-api/apidom-core'; import File from '../../File.ts'; +/** + * @public + */ export interface ParserOptions { readonly name: string; readonly allowEmpty?: boolean; @@ -10,6 +13,9 @@ export interface ParserOptions { readonly mediaTypes?: string[]; } +/** + * @public + */ abstract class Parser { public readonly name: string; diff --git a/packages/apidom-reference/src/resolve/resolvers/HTTPResolver.ts b/packages/apidom-reference/src/resolve/resolvers/HTTPResolver.ts index f06c8b2000..eb568c2502 100644 --- a/packages/apidom-reference/src/resolve/resolvers/HTTPResolver.ts +++ b/packages/apidom-reference/src/resolve/resolvers/HTTPResolver.ts @@ -2,12 +2,18 @@ import Resolver, { ResolverOptions } from './Resolver.ts'; import * as url from '../../util/url.ts'; import File from '../../File.ts'; +/** + * @public + */ export interface HTTPResolverOptions extends ResolverOptions { readonly timeout?: number; readonly redirects?: number; readonly withCredentials?: boolean; } +/** + * @public + */ abstract class HTTPResolver extends Resolver { protected readonly timeout: number; diff --git a/packages/apidom-reference/src/resolve/resolvers/Resolver.ts b/packages/apidom-reference/src/resolve/resolvers/Resolver.ts index a8f4511e58..d95f90f6b9 100644 --- a/packages/apidom-reference/src/resolve/resolvers/Resolver.ts +++ b/packages/apidom-reference/src/resolve/resolvers/Resolver.ts @@ -1,9 +1,15 @@ import File from '../../File.ts'; +/** + * @public + */ export interface ResolverOptions { readonly name: string; } +/** + * @public + */ abstract class Resolver { public readonly name: string; diff --git a/packages/apidom-reference/src/resolve/strategies/ResolveStrategy.ts b/packages/apidom-reference/src/resolve/strategies/ResolveStrategy.ts index 30b6697fa6..9423b94cba 100644 --- a/packages/apidom-reference/src/resolve/strategies/ResolveStrategy.ts +++ b/packages/apidom-reference/src/resolve/strategies/ResolveStrategy.ts @@ -2,10 +2,16 @@ import File from '../../File.ts'; import ReferenceSet from '../../ReferenceSet.ts'; import type { ReferenceOptions } from '../../options/index.ts'; +/** + * @public + */ export interface ResolveStrategyOptions { readonly name: string; } +/** + * @public + */ abstract class ResolveStrategy { public readonly name: string; diff --git a/packages/apidom-reference/src/util/url.ts b/packages/apidom-reference/src/util/url.ts index e67a69a124..4e682b008e 100644 --- a/packages/apidom-reference/src/util/url.ts +++ b/packages/apidom-reference/src/util/url.ts @@ -8,12 +8,16 @@ import { isUndefined, replaceAll, isNotUndefined, trimCharsEnd } from 'ramda-adj * SPDX-License-Identifier: MIT */ -type WindowsPredicate = () => boolean; +/** + * @public + */ +export type WindowsPredicate = () => boolean; const isWindows: WindowsPredicate = () => pathSatisfies(test(/^win/), ['platform'], process); /** * Returns the protocol of the given URL, or `undefined` if it has no protocol. + * @public */ export const getProtocol = (url: string): string | undefined => { try { @@ -26,12 +30,14 @@ export const getProtocol = (url: string): string | undefined => { /** * Returns true if given URL has protocol. + * @public */ export const hasProtocol = pipe(getProtocol, isNotUndefined); /** * Returns the lower-cased file extension of the given URL, * or an empty string if it has no extension. + * @public */ export const getExtension = (url: string): string => { const lastDotPosition = url.lastIndexOf('.'); @@ -44,6 +50,7 @@ export const getExtension = (url: string): string => { /** * Determines whether the given path is a filesystem path. * This includes "file://" URLs. + * @public */ export const isFileSystemPath = (uri: string): boolean => { // @ts-ignore @@ -61,6 +68,7 @@ export const isFileSystemPath = (uri: string): boolean => { /** * Determines whether the given URI is an HTTP(S) URL. + * @public */ export const isHttpUrl = (url: string): boolean => { const protocol = getProtocol(url); @@ -69,7 +77,7 @@ export const isHttpUrl = (url: string): boolean => { /** * Determines whether the given URI - * @param uri + * @public */ export const isURI = (uri: string): boolean => { try { @@ -79,13 +87,17 @@ export const isURI = (uri: string): boolean => { } }; -interface ToFileSystemPathOptions { +/** + * @public + */ +export interface ToFileSystemPathOptions { keepFileProtocol?: boolean; isWindows?: WindowsPredicate; } /** * Converts a URL to a local filesystem path. + * @public */ export const toFileSystemPath = (uri: string, options?: ToFileSystemPathOptions): string => { // RegExp patterns to URL-decode special characters for local filesystem paths @@ -151,10 +163,12 @@ export const toFileSystemPath = (uri: string, options?: ToFileSystemPathOptions) * * @example * The following filesystem paths would be converted to the following URLs: - * + *``` * <"!@#$%^&*+=?'>.json ==> %3C%22!@%23$%25%5E&*+=%3F\'%3E.json * C:\\My Documents\\File (1).json ==> C:/My%20Documents/File%20(1).json * file://Project #42/file.json ==> file://Project%20%2342/file.json + * ``` + * @public */ export const fromFileSystemPath = (uri: string): string => { const urlEncodePatterns = [/\?/g, '%3F', /#/g, '%23']; @@ -183,6 +197,7 @@ export const fromFileSystemPath = (uri: string): string => { /** * Returns the hash (URL fragment), of the given path. * If there is no hash, then the root hash ("#") is returned. + * @public */ export const getHash = (uri: string): string => { const hashIndex = uri.indexOf('#'); @@ -194,6 +209,7 @@ export const getHash = (uri: string): string => { /** * Removes the hash (URL fragment), if any, from the given path. + * @public */ export const stripHash = (uri: string): string => { const hashIndex = uri.indexOf('#'); @@ -206,6 +222,7 @@ export const stripHash = (uri: string): string => { /** * Returns the current working directory (in Node) or the current page URL (in browsers). + * @public */ export const cwd = (): string => { // @ts-ignore @@ -224,7 +241,8 @@ export const cwd = (): string => { }; /** - * Resolves a target URI relative to a base URI in a manner similar to that of a Web browser resolving an anchor tag HREF. + * Resolves a target URI relative to a base URI in a manner similar to that of a Web browser resolving an anchor tag HREF. + * @public */ export const resolve = (from: string, to: string): string => { const resolvedUrl = new URL(to, new URL(from, 'resolve://')); @@ -243,6 +261,7 @@ export const resolve = (from: string, to: string): string => { * The functional will compensate with the usecase when * already sanitized URI is passed to it, * by first unsatizing it and then performing sanitization again. + * @public */ export const sanitize = (uri: string) => { @@ -262,6 +281,7 @@ export const sanitize = (uri: string) => { * Unsanitizes/Decodes URI to it's url encoded form. * This function already assumes that hash part of the URI * has been removed prior to transforming it to it's sanitized form. + * @public */ export const unsanitize = (uri: string): string => {