refactor!: replace enums with types

.changeset/funny-mayflies-knock.md

@@ -0,0 +1,6 @@
+---
+"@redocly/openapi-core": major
+---
+
+Replaced the `SpecVersion`, `SpecMajorVersion`, `OPENAPI3_METHOD`, and `OPENAPI3_COMPONENT` enums with types for improved flexibility and type safety.
+Removed the unused `OasVersion` enum.

packages/cli/src/__tests__/commands/join.test.ts

@@ -4,7 +4,6 @@ import {
   detectSpec,
   getTotals,
   loadConfig,
-  type SpecVersion,
   type Document,
 } from '@redocly/openapi-core';
 import { handleJoin } from '../../commands/join.js';
@@ -83,7 +82,7 @@ describe('handleJoin', () => {
   });
 
   it('should proceed if glob expands to 2 or more APIs', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_1' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_1');
     vi.mocked(getFallbackApisOrExit).mockResolvedValueOnce([
       { path: 'first.yaml' },
       { path: 'second.yaml' },
@@ -132,7 +131,7 @@ describe('handleJoin', () => {
   });
 
   it('should call exitWithError because Only OpenAPI 3.0 and OpenAPI 3.1 are supported', async () => {
-    vi.mocked(detectSpec).mockReturnValueOnce('oas2_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValueOnce('oas2');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -147,8 +146,8 @@ describe('handleJoin', () => {
 
   it('should call exitWithError if mixing OpenAPI 3.0 and 3.1', async () => {
     vi.mocked(detectSpec)
-      .mockImplementationOnce(() => 'oas3_0' as SpecVersion)
-      .mockImplementationOnce(() => 'oas3_1' as SpecVersion);
+      .mockImplementationOnce(() => 'oas3_0')
+      .mockImplementationOnce(() => 'oas3_1');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -163,7 +162,7 @@ describe('handleJoin', () => {
   });
 
   it('should call writeToFileByExtension function', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_0');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -180,7 +179,7 @@ describe('handleJoin', () => {
   });
 
   it('should call writeToFileByExtension function for OpenAPI 3.1', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_1' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_1');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -197,7 +196,7 @@ describe('handleJoin', () => {
   });
 
   it('should call writeToFileByExtension function with custom output file', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_0');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -215,7 +214,7 @@ describe('handleJoin', () => {
   });
 
   it('should call writeToFileByExtension function with json file extension', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_0');
     await handleJoin({
       argv: {
         apis: ['first.json', 'second.yaml'],
@@ -232,7 +231,7 @@ describe('handleJoin', () => {
   });
 
   it('should call skipDecorators and skipPreprocessors', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_0');
     await handleJoin({
       argv: {
         apis: ['first.yaml', 'second.yaml'],
@@ -247,7 +246,7 @@ describe('handleJoin', () => {
   });
 
   it('should handle join with prefix-components-with-info-prop and null values', async () => {
-    vi.mocked(detectSpec).mockReturnValue('oas3_0' as SpecVersion);
+    vi.mocked(detectSpec).mockReturnValue('oas3_0');
 
     await handleJoin({
       argv: {

packages/cli/src/__tests__/wrapper.test.ts

@@ -3,7 +3,7 @@ import { loadConfigAndHandleErrors } from '../utils/miscellaneous.js';
 import { sendTelemetry } from '../utils/telemetry.js';
 import { commandWrapper } from '../wrapper.js';
 import { handleLint } from '../commands/lint.js';
-import { type Config, detectSpec, type SpecVersion } from '@redocly/openapi-core';
+import { type Config, detectSpec } from '@redocly/openapi-core';
 
 const originalFetch = global.fetch;
 
@@ -31,7 +31,7 @@ describe('commandWrapper', () => {
       return { resolvedConfig: { telemetry: 'on' } } as Config;
     });
     vi.mocked(detectSpec).mockImplementationOnce(() => {
-      return 'oas3_1' as SpecVersion;
+      return 'oas3_1';
     });
     vi.mocked(handleLint).mockImplementation(async ({ collectSpecData }) => {
       collectSpecData?.({ openapi: '3.1.0' });

packages/cli/src/commands/join.ts

@@ -2,7 +2,6 @@
 import { red, blue, yellow, green } from 'colorette';
 import { performance } from 'node:perf_hooks';
 import {
-  SpecVersion,
   BaseResolver,
   formatProblems,
   getTotals,
@@ -23,7 +22,7 @@
   writeToFileByExtension,
 } from '../utils/miscellaneous.js';
 import { exitWithError } from '../utils/error.js';
-import { COMPONENTS, OPENAPI3_METHOD } from './split/types.js';
+import { COMPONENTS, type Oas3Method, OPENAPI3_METHOD_NAMES } from './split/types.js';
 import { crawl, startsWithComponents } from './split/index.js';
 
 import type {
@@ -37,6 +36,7 @@
   Oas3PathItem,
   Oas3Server,
   Oas3Tag,
+  SpecVersion,
 } from '@redocly/openapi-core';
 import type { CommandArgs } from '../wrapper.js';
 import type { VerifyConfigOptions } from '../types.js';
@@ -50,7 +50,7 @@
   apiFilename: string;
   apiTitle?: string;
   tags: Oas3Tag[];
   potentialConflicts: any;
   tagsPrefix: string;
   componentsPrefix: string | undefined;
 };
@@ -153,7 +153,7 @@
     try {
       const version = detectSpec(document.parsed);
       collectSpecData?.(document.parsed);
-      if (version !== SpecVersion.OAS3_0 && version !== SpecVersion.OAS3_1) {
+      if (version !== 'oas3_0' && version !== 'oas3_1') {
         return exitWithError(
           `Only OpenAPI 3.0 and OpenAPI 3.1 are supported: ${blue(document.source.absoluteRef)}.`
         );
@@ -170,7 +170,7 @@
     }
   }
 
   const joinedDef: any = {};
   const potentialConflicts = {
     tags: {},
     paths: {},
@@ -293,7 +293,7 @@
   }
 
   function getIndexGroup(name: string): number {
     return joinedDef[xTagGroups].findIndex((item: any) => item.name === name);
   }
 
   function createXTagGroups(name: string) {
@@ -301,7 +301,7 @@
       joinedDef[xTagGroups] = [];
     }
 
     if (!joinedDef[xTagGroups].some((g: any) => g.name === name)) {
       joinedDef[xTagGroups].push({ name, tags: [] });
     }
 
@@ -327,7 +327,7 @@
         joinedDef['servers'] = [];
       }
       for (const server of servers) {
         if (!joinedDef.servers.some((s: any) => s.url === server.url)) {
           joinedDef.servers.push(server);
         }
       }
@@ -360,7 +360,7 @@
     }: JoinDocumentContext
   ) {
     const { paths } = openapi;
-    const operationsSet = new Set(keysOf<typeof OPENAPI3_METHOD>(OPENAPI3_METHOD));
+    const operationsSet = new Set(OPENAPI3_METHOD_NAMES);
     if (paths) {
       if (!joinedDef.hasOwnProperty('paths')) {
         joinedDef['paths'] = {};
@@ -377,8 +377,8 @@
         const pathItem = paths[path] as Oas3PathItem;
 
         for (const field of keysOf(pathItem)) {
-          if (operationsSet.has(field as OPENAPI3_METHOD)) {
-            collectPathOperation(pathItem, path, field as OPENAPI3_METHOD);
+          if (operationsSet.has(field as Oas3Method)) {
+            collectPathOperation(pathItem, path, field as Oas3Method);
           }
           if (field === 'servers') {
             collectPathServers(pathItem, path);
@@ -474,7 +474,7 @@
     function collectPathOperation(
       pathItem: Oas3PathItem,
       path: string | number,
-      operation: OPENAPI3_METHOD
+      operation: Oas3Method
     ) {
       const pathOperation = pathItem[operation];
 
@@ -587,7 +587,7 @@
       componentsPrefix,
     }: JoinDocumentContext
   ) {
-    const webhooks = oasVersion === SpecVersion.OAS3_1 ? 'webhooks' : 'x-webhooks';
+    const webhooks = oasVersion === 'oas3_1' ? 'webhooks' : 'x-webhooks';
     const openapiWebhooks = openapi[webhooks];
     if (openapiWebhooks) {
       if (!joinedDef.hasOwnProperty(webhooks)) {
@@ -627,7 +627,7 @@
   }
 
   function addInfoSectionAndSpecVersion(
     documents: any,
     prefixComponentsWithInfoProp: string | undefined
   ) {
     const firstApi = documents[0];

packages/cli/src/commands/split/index.ts

@@ -22,12 +22,7 @@ import {
   getAndValidateFileExtension,
 } from '../../utils/miscellaneous.js';
 import { exitWithError } from '../../utils/error.js';
-import {
-  OPENAPI3_COMPONENT,
-  COMPONENTS,
-  OPENAPI3_METHOD_NAMES,
-  OPENAPI3_COMPONENT_NAMES,
-} from './types.js';
+import { COMPONENTS, OPENAPI3_METHOD_NAMES, OPENAPI3_COMPONENT_NAMES } from './types.js';
 
 import type {
   Oas3Definition,
@@ -42,7 +37,7 @@ import type {
   OasRef,
   Referenced,
 } from '@redocly/openapi-core';
-import type { ComponentsFiles, Definition, RefObject } from './types.js';
+import type { ComponentsFiles, Definition, Oas3Component, RefObject } from './types.js';
 import type { CommandArgs } from '../../wrapper.js';
 import type { VerifyConfigOptions } from '../../types.js';
 
@@ -204,7 +199,7 @@ function implicitlyReferenceDiscriminator(
   schemaFiles: any
 ) {
   if (!obj.discriminator) return;
-  const defPtr = `#/${COMPONENTS}/${OPENAPI3_COMPONENT.Schemas}/${defName}`;
+  const defPtr = `#/${COMPONENTS}/${'schemas' as Oas3Component}/${defName}`;
   const implicitMapping: Record<string, string> = {};
   for (const [name, { inherits, filename: parentFilename }] of Object.entries(schemaFiles) as any) {
     if (inherits.indexOf(defPtr) > -1) {
@@ -233,7 +228,7 @@ function implicitlyReferenceDiscriminator(
 }
 
 function isNotSecurityComponentType(componentType: string) {
-  return componentType !== OPENAPI3_COMPONENT.SecuritySchemes;
+  return componentType !== 'securitySchemes';
 }
 
 function findComponentTypes(components: any) {
@@ -280,7 +275,7 @@ function gatherComponentsFiles(
   filename: string
 ) {
   let inherits: string[] = [];
-  if (componentType === OPENAPI3_COMPONENT.Schemas) {
+  if (componentType === 'schemas') {
     inherits = (
       (components?.[componentType]?.[componentName] as Oas3Schema | Oas3_1Schema)?.allOf || []
     )

packages/cli/src/commands/split/types.ts

@@ -12,48 +12,28 @@ export const COMPONENTS = 'components';
 export const PATHS = 'paths';
 export const WEBHOOKS = 'webhooks';
 export const xWEBHOOKS = 'x-webhooks';
-export enum OPENAPI3_METHOD {
-  get = 'get',
-  put = 'put',
-  post = 'post',
-  delete = 'delete',
-  options = 'options',
-  head = 'head',
-  patch = 'patch',
-  trace = 'trace',
-}
-
-export const OPENAPI3_METHOD_NAMES: OPENAPI3_METHOD[] = [
-  OPENAPI3_METHOD.get,
-  OPENAPI3_METHOD.put,
-  OPENAPI3_METHOD.post,
-  OPENAPI3_METHOD.delete,
-  OPENAPI3_METHOD.options,
-  OPENAPI3_METHOD.head,
-  OPENAPI3_METHOD.patch,
-  OPENAPI3_METHOD.trace,
-];
 
-export enum OPENAPI3_COMPONENT {
-  Schemas = 'schemas',
-  Responses = 'responses',
-  Parameters = 'parameters',
-  Examples = 'examples',
-  Headers = 'headers',
-  RequestBodies = 'requestBodies',
-  Links = 'links',
-  Callbacks = 'callbacks',
-  SecuritySchemes = 'securitySchemes',
-}
+export type Oas3Method = typeof OPENAPI3_METHOD_NAMES[number];
+export const OPENAPI3_METHOD_NAMES = [
+  'get',
+  'put',
+  'post',
+  'delete',
+  'options',
+  'head',
+  'patch',
+  'trace',
+] as const;
 
-export const OPENAPI3_COMPONENT_NAMES: OPENAPI3_COMPONENT[] = [
-  OPENAPI3_COMPONENT.RequestBodies,
-  OPENAPI3_COMPONENT.Schemas,
-  OPENAPI3_COMPONENT.Responses,
-  OPENAPI3_COMPONENT.Parameters,
-  OPENAPI3_COMPONENT.Examples,
-  OPENAPI3_COMPONENT.Headers,
-  OPENAPI3_COMPONENT.Links,
-  OPENAPI3_COMPONENT.Callbacks,
-  OPENAPI3_COMPONENT.SecuritySchemes,
-];
+export type Oas3Component = typeof OPENAPI3_COMPONENT_NAMES[number];
+export const OPENAPI3_COMPONENT_NAMES = [
+  'schemas',
+  'responses',
+  'parameters',
+  'examples',
+  'headers',
+  'requestBodies',
+  'links',
+  'callbacks',
+  'securitySchemes',
+] as const;