@speclynx/apidom-ns-openapi-2 4.0.2 → 4.0.3

package/src/refractor/index.mjs

@@ -0,0 +1,283 @@
+import { resolveSpecification, dispatchRefractorPlugins } from '@speclynx/apidom-core';
+import { refract as baseRefract } from '@speclynx/apidom-datamodel';
+import { traverse } from '@speclynx/apidom-traverse';
+import { path } from 'ramda';
+import specification from "./specification.mjs";
+import createToolbox from "./toolbox.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+const refract = (value, {
+  element = 'swagger',
+  plugins = [],
+  specificationObj = specification,
+  consume = false
+} = {}) => {
+  const genericElement = baseRefract(value);
+  const resolvedSpec = resolveSpecification(specificationObj);
+  const elementMap = resolvedSpec.elementMap;
+  const specPath = elementMap[element];
+  if (!specPath) {
+    throw new Error(`Unknown element type: "${element}"`);
+  }
+
+  /**
+   * This is where generic ApiDOM becomes semantic (namespace applied).
+   * We don't allow consumers to hook into this translation.
+   * Though we allow consumers to define their own plugins on already transformed ApiDOM.
+   */
+  const RootVisitorClass = path(specPath, resolvedSpec);
+  const rootVisitor = new RootVisitorClass({
+    specObj: resolvedSpec,
+    consume
+  });
+  traverse(genericElement, rootVisitor);
+
+  /**
+   * Running plugins visitors means extra single traversal === performance hit.
+   */
+  return dispatchRefractorPlugins(rootVisitor.element, plugins, {
+    toolboxCreator: createToolbox
+  });
+};
+
+/**
+ * Refracts a value into a SwaggerElement.
+ * @public
+ */
+export const refractSwagger = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'swagger'
+});
+
+/**
+ * Refracts a value into an InfoElement.
+ * @public
+ */
+export const refractInfo = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'info'
+});
+
+/**
+ * Refracts a value into a ContactElement.
+ * @public
+ */
+export const refractContact = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'contact'
+});
+
+/**
+ * Refracts a value into a LicenseElement.
+ * @public
+ */
+export const refractLicense = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'license'
+});
+
+/**
+ * Refracts a value into a PathsElement.
+ * @public
+ */
+export const refractPaths = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'paths'
+});
+
+/**
+ * Refracts a value into a PathItemElement.
+ * @public
+ */
+export const refractPathItem = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'pathItem'
+});
+
+/**
+ * Refracts a value into an OperationElement.
+ * @public
+ */
+export const refractOperation = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'operation'
+});
+
+/**
+ * Refracts a value into an ExternalDocumentationElement.
+ * @public
+ */
+export const refractExternalDocumentation = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'externalDocumentation'
+});
+
+/**
+ * Refracts a value into a ParameterElement.
+ * @public
+ */
+export const refractParameter = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'parameter'
+});
+
+/**
+ * Refracts a value into an ItemsElement.
+ * @public
+ */
+export const refractItems = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'items'
+});
+
+/**
+ * Refracts a value into a ResponsesElement.
+ * @public
+ */
+export const refractResponses = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'responses'
+});
+
+/**
+ * Refracts a value into a ResponseElement.
+ * @public
+ */
+export const refractResponse = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'response'
+});
+
+/**
+ * Refracts a value into a HeadersElement.
+ * @public
+ */
+export const refractHeaders = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'headers'
+});
+
+/**
+ * Refracts a value into an ExampleElement.
+ * @public
+ */
+export const refractExample = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'example'
+});
+
+/**
+ * Refracts a value into a HeaderElement.
+ * @public
+ */
+export const refractHeader = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'header'
+});
+
+/**
+ * Refracts a value into a TagElement.
+ * @public
+ */
+export const refractTag = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'tag'
+});
+
+/**
+ * Refracts a value into a ReferenceElement.
+ * @public
+ */
+export const refractReference = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'reference'
+});
+
+/**
+ * Refracts a value into a SchemaElement.
+ * @public
+ */
+export const refractSchema = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'schema'
+});
+
+/**
+ * Refracts a value into an XmlElement.
+ * @public
+ */
+export const refractXml = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'xml'
+});
+
+/**
+ * Refracts a value into a DefinitionsElement.
+ * @public
+ */
+export const refractDefinitions = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'definitions'
+});
+
+/**
+ * Refracts a value into a ParametersDefinitionsElement.
+ * @public
+ */
+export const refractParametersDefinitions = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'parametersDefinitions'
+});
+
+/**
+ * Refracts a value into a ResponsesDefinitionsElement.
+ * @public
+ */
+export const refractResponsesDefinitions = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'responsesDefinitions'
+});
+
+/**
+ * Refracts a value into a SecurityDefinitionsElement.
+ * @public
+ */
+export const refractSecurityDefinitions = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'securityDefinitions'
+});
+
+/**
+ * Refracts a value into a SecuritySchemeElement.
+ * @public
+ */
+export const refractSecurityScheme = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'securityScheme'
+});
+
+/**
+ * Refracts a value into a ScopesElement.
+ * @public
+ */
+export const refractScopes = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'scopes'
+});
+
+/**
+ * Refracts a value into a SecurityRequirementElement.
+ * @public
+ */
+export const refractSecurityRequirement = (value, options = {}) => refract(value, {
+  ...options,
+  element: 'securityRequirement'
+});
+export default refract;

package/src/refractor/index.ts

@@ -0,0 +1,330 @@
+import { resolveSpecification, dispatchRefractorPlugins } from '@speclynx/apidom-core';
+import { Element, refract as baseRefract } from '@speclynx/apidom-datamodel';
+import { traverse } from '@speclynx/apidom-traverse';
+import { path } from 'ramda';
+
+import type VisitorClass from './visitors/Visitor.ts';
+import specification from './specification.ts';
+import createToolbox, { type Toolbox } from './toolbox.ts';
+import type SwaggerElement from '../elements/Swagger.ts';
+import type InfoElement from '../elements/Info.ts';
+import type ContactElement from '../elements/Contact.ts';
+import type LicenseElement from '../elements/License.ts';
+import type PathsElement from '../elements/Paths.ts';
+import type PathItemElement from '../elements/PathItem.ts';
+import type OperationElement from '../elements/Operation.ts';
+import type ExternalDocumentationElement from '../elements/ExternalDocumentation.ts';
+import type ParameterElement from '../elements/Parameter.ts';
+import type ItemsElement from '../elements/Items.ts';
+import type ResponsesElement from '../elements/Responses.ts';
+import type ResponseElement from '../elements/Response.ts';
+import type HeadersElement from '../elements/Headers.ts';
+import type ExampleElement from '../elements/Example.ts';
+import type HeaderElement from '../elements/Header.ts';
+import type TagElement from '../elements/Tag.ts';
+import type ReferenceElement from '../elements/Reference.ts';
+import type SchemaElement from '../elements/Schema.ts';
+import type XmlElement from '../elements/Xml.ts';
+import type DefinitionsElement from '../elements/Definitions.ts';
+import type ParametersDefinitionsElement from '../elements/ParametersDefinitions.ts';
+import type ResponsesDefinitionsElement from '../elements/ResponsesDefinitions.ts';
+import type SecurityDefinitionsElement from '../elements/SecurityDefinitions.ts';
+import type SecuritySchemeElement from '../elements/SecurityScheme.ts';
+import type ScopesElement from '../elements/Scopes.ts';
+import type SecurityRequirementElement from '../elements/SecurityRequirement.ts';
+
+/**
+ * @public
+ */
+export type RefractorPlugin = (toolbox: Toolbox) => {
+  visitor?: object;
+  pre?: () => void;
+  post?: () => void;
+};
+
+/**
+ * @public
+ */
+export interface RefractorOptions {
+  readonly element?: string;
+  readonly plugins?: RefractorPlugin[];
+  readonly specificationObj?: typeof specification;
+  readonly consume?: boolean;
+}
+
+/**
+ * @public
+ */
+const refract = <T extends Element>(
+  value: unknown,
+  {
+    element = 'swagger',
+    plugins = [],
+    specificationObj = specification,
+    consume = false,
+  }: RefractorOptions = {},
+): T => {
+  const genericElement = baseRefract(value);
+  const resolvedSpec = resolveSpecification(specificationObj);
+  const elementMap = resolvedSpec.elementMap as Record<string, string[]>;
+  const specPath = elementMap[element];
+
+  if (!specPath) {
+    throw new Error(`Unknown element type: "${element}"`);
+  }
+
+  /**
+   * This is where generic ApiDOM becomes semantic (namespace applied).
+   * We don't allow consumers to hook into this translation.
+   * Though we allow consumers to define their own plugins on already transformed ApiDOM.
+   */
+  const RootVisitorClass = path(specPath, resolvedSpec) as new (
+    options: Record<string, unknown>,
+  ) => InstanceType<typeof VisitorClass>;
+  const rootVisitor = new RootVisitorClass({ specObj: resolvedSpec, consume });
+
+  traverse(genericElement, rootVisitor);
+
+  /**
+   * Running plugins visitors means extra single traversal === performance hit.
+   */
+  return dispatchRefractorPlugins(rootVisitor.element, plugins, {
+    toolboxCreator: createToolbox,
+  }) as T;
+};
+
+/**
+ * Refracts a value into a SwaggerElement.
+ * @public
+ */
+export const refractSwagger = <T extends Element = SwaggerElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'swagger' });
+
+/**
+ * Refracts a value into an InfoElement.
+ * @public
+ */
+export const refractInfo = <T extends Element = InfoElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'info' });
+
+/**
+ * Refracts a value into a ContactElement.
+ * @public
+ */
+export const refractContact = <T extends Element = ContactElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'contact' });
+
+/**
+ * Refracts a value into a LicenseElement.
+ * @public
+ */
+export const refractLicense = <T extends Element = LicenseElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'license' });
+
+/**
+ * Refracts a value into a PathsElement.
+ * @public
+ */
+export const refractPaths = <T extends Element = PathsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'paths' });
+
+/**
+ * Refracts a value into a PathItemElement.
+ * @public
+ */
+export const refractPathItem = <T extends Element = PathItemElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'pathItem' });
+
+/**
+ * Refracts a value into an OperationElement.
+ * @public
+ */
+export const refractOperation = <T extends Element = OperationElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'operation' });
+
+/**
+ * Refracts a value into an ExternalDocumentationElement.
+ * @public
+ */
+export const refractExternalDocumentation = <T extends Element = ExternalDocumentationElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'externalDocumentation' });
+
+/**
+ * Refracts a value into a ParameterElement.
+ * @public
+ */
+export const refractParameter = <T extends Element = ParameterElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'parameter' });
+
+/**
+ * Refracts a value into an ItemsElement.
+ * @public
+ */
+export const refractItems = <T extends Element = ItemsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'items' });
+
+/**
+ * Refracts a value into a ResponsesElement.
+ * @public
+ */
+export const refractResponses = <T extends Element = ResponsesElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'responses' });
+
+/**
+ * Refracts a value into a ResponseElement.
+ * @public
+ */
+export const refractResponse = <T extends Element = ResponseElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'response' });
+
+/**
+ * Refracts a value into a HeadersElement.
+ * @public
+ */
+export const refractHeaders = <T extends Element = HeadersElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'headers' });
+
+/**
+ * Refracts a value into an ExampleElement.
+ * @public
+ */
+export const refractExample = <T extends Element = ExampleElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'example' });
+
+/**
+ * Refracts a value into a HeaderElement.
+ * @public
+ */
+export const refractHeader = <T extends Element = HeaderElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'header' });
+
+/**
+ * Refracts a value into a TagElement.
+ * @public
+ */
+export const refractTag = <T extends Element = TagElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'tag' });
+
+/**
+ * Refracts a value into a ReferenceElement.
+ * @public
+ */
+export const refractReference = <T extends Element = ReferenceElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'reference' });
+
+/**
+ * Refracts a value into a SchemaElement.
+ * @public
+ */
+export const refractSchema = <T extends Element = SchemaElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'schema' });
+
+/**
+ * Refracts a value into an XmlElement.
+ * @public
+ */
+export const refractXml = <T extends Element = XmlElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'xml' });
+
+/**
+ * Refracts a value into a DefinitionsElement.
+ * @public
+ */
+export const refractDefinitions = <T extends Element = DefinitionsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'definitions' });
+
+/**
+ * Refracts a value into a ParametersDefinitionsElement.
+ * @public
+ */
+export const refractParametersDefinitions = <T extends Element = ParametersDefinitionsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'parametersDefinitions' });
+
+/**
+ * Refracts a value into a ResponsesDefinitionsElement.
+ * @public
+ */
+export const refractResponsesDefinitions = <T extends Element = ResponsesDefinitionsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'responsesDefinitions' });
+
+/**
+ * Refracts a value into a SecurityDefinitionsElement.
+ * @public
+ */
+export const refractSecurityDefinitions = <T extends Element = SecurityDefinitionsElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'securityDefinitions' });
+
+/**
+ * Refracts a value into a SecuritySchemeElement.
+ * @public
+ */
+export const refractSecurityScheme = <T extends Element = SecuritySchemeElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'securityScheme' });
+
+/**
+ * Refracts a value into a ScopesElement.
+ * @public
+ */
+export const refractScopes = <T extends Element = ScopesElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'scopes' });
+
+/**
+ * Refracts a value into a SecurityRequirementElement.
+ * @public
+ */
+export const refractSecurityRequirement = <T extends Element = SecurityRequirementElement>(
+  value: unknown,
+  options: Omit<RefractorOptions, 'element'> = {},
+): T => refract(value, { ...options, element: 'securityRequirement' });
+
+export default refract;