refact(opapi): Use classes inside opapi

opapi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpinternal/opapi",
-  "version": "0.18.0",
+  "version": "1.0.0",
   "description": "Opapi is a highly opinionated library to generate server, client and documentation from OpenAPI specification using typescript.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

opapi/readme.md

@@ -10,7 +10,7 @@ Install the package and start creating your OpenAPI specification. See the examp
 import { OpenApi, schema } from '@bpinternal/opapi'
 import { z } from 'zod'
 
-const api = OpenApi({
+const api = new OpenApi({
   metadata: {
     title: 'Example API', // This is the title of the API
     description: 'Description of this api', // This is the description of the API
@@ -21,7 +21,7 @@ const api = OpenApi({
   // This is metadata to be used in the documentation
   section: {
     User: {
-      tilte: 'User',
+      title: 'User',
       description: 'User related endpoints',
     },
   },

opapi/src/export-options.test.ts

@@ -1,10 +1,10 @@
 import { describe, it, expect } from 'vitest'
-import { createState } from './state'
 import { z } from 'zod'
 import { applyExportOptions } from './export-options'
 import { addOperation } from './operation'
+import { CreateStateProps, createState } from './state'
 
-type AnyProps = Parameters<typeof createState>[0]
+type AnyProps = CreateStateProps<string, string, string>
 
 function getApiState() {
   const metadata = {

opapi/src/opapi.ts

@@ -7,22 +7,11 @@ import {
   generateServer,
   generateTypesBySection,
 } from './generator'
-import { addOperation } from './operation'
-import {
-  ApiError,
-  ComponentType,
-  createState,
-  getRef,
-  Metadata,
-  Operation,
-  Options,
-  Parameter,
-  State,
-  Security,
-} from './state'
+import { ComponentType, Operation, Options, State, CreateStateProps, cloneState, getRef, createState } from './state'
 import { exportStateAsTypescript, ExportStateAsTypescriptOptions } from './generators/ts-state'
 import { generateHandler } from './handler-generator'
 import { applyExportOptions, ExportStateOptions } from './export-options'
+import { addOperation } from './operation'
 export { Operation, Parameter } from './state'
 
 type AnatineSchemaObject = NonNullable<Parameters<typeof extendApi>[1]>
@@ -36,121 +25,91 @@ export const schema = <T extends OpenApiZodAny>(
   return extendApi(copy, schemaObject)
 }
 
-export type OpenApi<
-  SchemaName extends string = string,
-  DefaultParameterName extends string = string,
-  SectionName extends string = string,
-> = ReturnType<typeof createOpapiFromState<SchemaName, DefaultParameterName, SectionName>>
-
-// TODO: ensure type inference comes from field 'sections' not 'schemas'
-export type OpenApiProps<SchemaName extends string, DefaultParameterName extends string, SectionName extends string> = {
-  metadata: Metadata
-  // adds default parameters to all operations
-  defaultParameters?: Record<DefaultParameterName, Parameter<'zod-schema'>>
-  // adds the openapi schemas
-  schemas?: Record<SchemaName, { schema: OpenApiZodAny; section: SectionName }>
-  // adds the openapi tags
-  sections?: Record<SectionName, { title: string; description: string }>
-  // add the openapi errors
-  errors?: readonly ApiError[]
-  // add security schemes
-  security?: Security[]
-}
+export class OpenApi<SchemaName extends string, DefaultParameterName extends string, SectionName extends string> {
+  private _state: State<SchemaName, DefaultParameterName, SectionName>
 
-export type CodePostProcessor = (code: string) => Promise<string> | string
+  constructor(props: CreateStateProps<SchemaName, DefaultParameterName, SectionName>, options: Partial<Options> = {}) {
+    this._state = createState(props, options)
+  }
 
-export type OpenApiPostProcessors = {
-  apiCode: CodePostProcessor
-}
+  static fromState<SchemaName extends string, DefaultParameterName extends string, SectionName extends string>(
+    state: State<SchemaName, DefaultParameterName, SectionName>,
+  ) {
+    const openapi = new OpenApi({ metadata: state.metadata })
+    openapi._state = state
+    return openapi
+  }
 
-export type GenerateClientProps = (
-  | {
-      generator: 'openapi-generator'
-      endpoint: string
-      postProcessors?: OpenApiPostProcessors
-    }
-  | {
-      generator: 'opapi'
-    }
-) &
-  ExportStateOptions
+  getState() {
+    return cloneState(this._state)
+  }
 
-function exportClient(state: State<string, string, string>) {
-  function _exportClient(dir: string, props: GenerateClientProps): Promise<void>
-  function _exportClient(
-    dir: string,
-    openapiGeneratorEndpoint: string,
-    props?: OpenApiPostProcessors & ExportStateOptions,
-  ): Promise<void>
-  function _exportClient(
-    dir = '.',
-    propsOrEndpoint: GenerateClientProps | string,
-    postProcessorsAndStateOpts?: OpenApiPostProcessors & ExportStateOptions,
-  ) {
-    let options: GenerateClientProps
-    if (typeof propsOrEndpoint === 'string') {
-      options = {
-        generator: 'openapi-generator',
-        endpoint: propsOrEndpoint,
-        postProcessors: postProcessorsAndStateOpts,
-      }
-    } else {
-      options = propsOrEndpoint
-    }
+  getModelRef(name: SchemaName): OpenApiZodAny {
+    return getRef(this._state, ComponentType.SCHEMAS, name)
+  }
 
-    state = applyExportOptions(state, postProcessorsAndStateOpts)
+  addOperation<Path extends string>(operation: Operation<DefaultParameterName, SectionName, Path, 'zod-schema'>) {
+    addOperation(this._state, operation)
+  }
 
+  exportClient(dir: string, options: GenerateClientOptions & ExportStateOptions) {
     if (options.generator === 'openapi-generator') {
-      return generateClientWithOpenapiGenerator(state, dir, options.endpoint, options.postProcessors)
+      return generateClientWithOpenapiGenerator(
+        applyExportOptions(this._state, options),
+        dir,
+        options.endpoint,
+        options.postProcessors,
+      )
     }
     if (options.generator === 'opapi') {
-      return generateClientWithOpapi(state, dir)
+      return generateClientWithOpapi(applyExportOptions(this._state, options), dir)
     }
     throw new Error('Unknown generator')
   }
-  return _exportClient
-}
 
-const createOpapiFromState = <
-  SchemaName extends string,
-  DefaultParameterName extends string,
-  SectionName extends string,
->(
-  state: State<SchemaName, DefaultParameterName, SectionName>,
-) => {
-  return {
-    getModelRef: (name: SchemaName): OpenApiZodAny => getRef(state, ComponentType.SCHEMAS, name),
-    getState: () => state,
-    addOperation: <Path extends string>(
-      operationProps: Operation<DefaultParameterName, SectionName, Path, 'zod-schema'>,
-    ) => addOperation(state, operationProps),
-    exportClient: exportClient(state),
-    exportTypesBySection: (dir = '.', opts?: ExportStateOptions) =>
-      generateTypesBySection(applyExportOptions(state, opts), dir),
-    exportServer: (dir = '.', useExpressTypes: boolean, opts?: ExportStateOptions) =>
-      generateServer(applyExportOptions(state, opts), dir, useExpressTypes),
-    exportOpenapi: (dir = '.', opts?: ExportStateOptions) => generateOpenapi(applyExportOptions(state, opts), dir),
-    exportState: (dir = '.', opts?: ExportStateAsTypescriptOptions & ExportStateOptions) =>
-      exportStateAsTypescript(applyExportOptions(state, opts), dir, opts),
-    exportErrors: (dir = '.') => generateErrorsFile(state.errors ?? [], dir),
-    exportHandler: (dir = '.', opts?: ExportStateOptions) => generateHandler(applyExportOptions(state, opts), dir),
+  exportTypesBySection(dir = '.', options?: ExportStateOptions) {
+    return generateTypesBySection(applyExportOptions(this._state, options), dir)
+  }
+
+  exportServer(dir = '.', useExpressTypes: boolean, options?: ExportStateOptions) {
+    return generateServer(applyExportOptions(this._state, options), dir, useExpressTypes)
+  }
+
+  exportOpenapi(dir = '.', options?: ExportStateOptions) {
+    return generateOpenapi(applyExportOptions(this._state, options), dir)
+  }
+
+  exportState(dir = '.', options?: ExportStateAsTypescriptOptions & ExportStateOptions) {
+    return exportStateAsTypescript(applyExportOptions(this._state, options), dir, options)
+  }
+
+  exportErrors(dir = '.') {
+    return generateErrorsFile(this._state.errors ?? [], dir)
   }
-}
 
-export function OpenApi<SchemaName extends string, DefaultParameterName extends string, SectionName extends string>(
-  props: OpenApiProps<SchemaName, DefaultParameterName, SectionName>,
-  opts: Partial<Options> = {},
-) {
-  const state = createState(props, opts)
-  return createOpapiFromState(state)
+  exportHandler(dir = '.', options?: ExportStateOptions) {
+    return generateHandler(applyExportOptions(this._state, options), dir)
+  }
 }
 
-export namespace OpenApi {
-  export const fromState = <SchemaName extends string, DefaultParameterName extends string, SectionName extends string>(
-    state: State<SchemaName, DefaultParameterName, SectionName>,
-  ) => createOpapiFromState(state as State<SchemaName, DefaultParameterName, SectionName>)
+export type CodePostProcessor = (code: string) => Promise<string> | string
+
+export type OpenApiPostProcessors = {
+  apiCode: CodePostProcessor
 }
 
+export type GenerateClientOptions = (
+  | {
+      generator: 'openapi-generator'
+      endpoint: string
+      postProcessors?: OpenApiPostProcessors
+    }
+  | {
+      generator: 'opapi'
+    }
+) &
+  ExportStateOptions
+
 export type SchemaOf<O extends OpenApi<any, any, any>> =
   O extends OpenApi<infer Skema, infer _Param, infer _Sexion> ? Skema : never
 

opapi/src/section-types-generator/helpers.ts

@@ -3,6 +3,7 @@ import type { SchemaObject } from 'openapi3-ts'
 import { pascal, title } from 'radash'
 import { createOpenapi } from '../openapi'
 import { Block, DefaultState } from './types'
+import { cloneState } from 'src/state'
 
 export const pascalize = (str: string) => pascal(title(str))
 
@@ -72,7 +73,7 @@ export function remove$RefPropertiesFromSchema(
 export async function getDereferencedSchema(state: DefaultState) {
   // this doesn't do a deep clone, which helps us in the dereference step
   // in other words, openapi still has references to the original objects in state
-  const clonedState = JSON.parse(JSON.stringify(state))
+  const clonedState = cloneState(state)
   const openapi = createOpenapi(clonedState).getSpec()
   // this dereferences those objects in place
   await OpenAPIParser.dereference(openapi as any)

opapi/src/state.ts

@@ -228,7 +228,11 @@ type BaseOperationProps<
   deprecated?: boolean
 }
 
-type CreateStateProps<SchemaName extends string, DefaultParameterName extends string, SectionName extends string> = {
+export type CreateStateProps<
+  SchemaName extends string,
+  DefaultParameterName extends string,
+  SectionName extends string,
+> = {
   metadata: Metadata
   defaultParameters?: Record<DefaultParameterName, Parameter<'zod-schema'>>
   schemas?: Record<SchemaName, { schema: OpenApiZodAny; section: SectionName }>
@@ -327,6 +331,10 @@ export function createState<SchemaName extends string, DefaultParameterName exte
   }
 }
 
+export function cloneState(state: State<string, string, string>) {
+  return Object.assign(Object.create(Object.getPrototypeOf(state)), state)
+}
+
 export function getRef(state: State<string, string, string>, type: ComponentType, name: string): OpenApiZodAny {
   if (!state.refs[type][name]) {
     throw new VError(`${type} ${name} does not exist`)

opapi/test/api.ts

@@ -36,7 +36,7 @@ const nestedSchema = z.object({
 })
 
 export const getMockApi = () => {
-  const api = OpenApi({
+  const api = new OpenApi({
     errors: [
       {
         description: 'Foo not found',

opapi/test/client.test.ts

@@ -10,7 +10,10 @@ describe('client generator', () => {
 
     const api = getMockApi()
 
-    await api.exportClient(genClientFolder, 'https://api.openapi-generator.tech')
+    await api.exportClient(genClientFolder, {
+      generator: 'openapi-generator',
+      endpoint: 'https://api.openapi-generator.tech',
+    })
 
     const files = getFiles(genClientFolder)
 

opapi/test/state.test.ts

@@ -40,7 +40,7 @@ const expectedErrorMessage = 'allOf, anyOf and oneOf are not supported'
 describe('openapi generator with unions not allowed', () => {
   it('should not allow unions when creating api', async () => {
     expect(() => {
-      OpenApi({
+      new OpenApi({
         metadata,
         sections,
         schemas: {
@@ -54,7 +54,7 @@ describe('openapi generator with unions not allowed', () => {
   })
 
   it('should not allow unions in response when adding an operation', async () => {
-    const api = OpenApi({ metadata, sections })
+    const api = new OpenApi({ metadata, sections })
     expect(() => {
       api.addOperation({
         name: 'getTree',
@@ -77,7 +77,7 @@ describe('openapi generator with unions not allowed', () => {
   })
 
   it('should not allow unions in request body when adding an operation', async () => {
-    const api = OpenApi({ metadata, sections })
+    const api = new OpenApi({ metadata, sections })
     expect(() => {
       api.addOperation({
         name: 'createTree',
@@ -100,7 +100,7 @@ describe('openapi generator with unions not allowed', () => {
 describe('openapi generator with unions allowed', () => {
   const opts = { allowUnions: true } as const
   it('should allow unions when creating api', async () => {
-    OpenApi(
+    new OpenApi(
       {
         metadata,
         sections,
@@ -116,7 +116,7 @@ describe('openapi generator with unions allowed', () => {
   })
 
   it('should allow unions in response when adding an operation', async () => {
-    const api = OpenApi({ metadata, sections }, opts)
+    const api = new OpenApi({ metadata, sections }, opts)
     api.addOperation({
       name: 'getTree',
       description: 'Get a tree',
@@ -137,7 +137,7 @@ describe('openapi generator with unions allowed', () => {
   })
 
   it('should allow unions in request body when adding an operation', async () => {
-    const api = OpenApi({ metadata, sections }, opts)
+    const api = new OpenApi({ metadata, sections }, opts)
     api.addOperation({
       name: 'createTree',
       description: 'Create a tree',
@@ -157,7 +157,7 @@ describe('openapi generator with unions allowed', () => {
 
 describe('openapi state generator', () => {
   it('should export state', async () => {
-    const api = OpenApi(
+    const api = new OpenApi(
       {
         metadata,
         sections,
@@ -184,7 +184,7 @@ describe('openapi state generator', () => {
   })
 
   it('should export state without defaultParameters when ignoreDefaultParameters is set', async () => {
-    const api = OpenApi(
+    const api = new OpenApi(
       {
         security: ['BearerAuth'],
         metadata,
@@ -248,7 +248,7 @@ describe('openapi state generator', () => {
   })
 
   it('should export state defaultParameters', async () => {
-    const api = OpenApi(
+    const api = new OpenApi(
       {
         security: ['BearerAuth'],
         metadata,