@kubb/swagger-ts 2.0.0-beta.6 → 2.0.0-beta.8

package/src/infer/model.ts

@@ -0,0 +1,38 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+import type { OasTypes } from '@kubb/swagger'
+import type {
+  FromSchema,
+  JSONSchema,
+} from 'json-schema-to-ts'
+
+namespace Checks {
+  export type ModelWithSchemas = {
+    components: {
+      schemas: Record<string, JSONSchema>
+    }
+  }
+  export type ModelWithSchemasNamed<TName extends string | number | symbol> = {
+    components: {
+      schemas: {
+        [TModelName in TName]: JSONSchema
+      }
+    }
+  }
+  export type ModelWithDefinitions = {
+    definitions: Record<string, JSONSchema>
+  }
+  export type ModelWithDefinitionsNamed<TName extends string | number | symbol = never> = {
+    definitions: {
+      [TModelName in TName]: JSONSchema
+    }
+  }
+}
+
+export type Model<
+  TOAS extends OasTypes.OASDocument,
+  TName extends TOAS extends Checks.ModelWithSchemas ? keyof TOAS['components']['schemas']
+    : TOAS extends Checks.ModelWithDefinitions ? keyof TOAS['definitions']
+    : never,
+> = TOAS extends Checks.ModelWithSchemasNamed<TName> ? FromSchema<TOAS['components']['schemas'][TName]>
+  : TOAS extends Checks.ModelWithDefinitionsNamed<TName> ? FromSchema<TOAS['definitions'][TName]>
+  : never

package/src/infer/parse.ts

@@ -0,0 +1,58 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+import type { Booleans, Call, Objects, Strings, Tuples } from 'hotscript'
+import type { Object } from 'ts-toolbelt'
+
+namespace Checks {
+  export type AllOFf = { allOf: any[] }
+  export type Object = {
+    type: 'object'
+    properties: any
+  }
+  export type Properties = { properties: any }
+  export type PropertiesRequired = {
+    properties: Record<string, any>
+    required: string[]
+  }
+}
+
+type FixAdditionalPropertiesForAllOf<T> = T extends Checks.AllOFf ? Omit<T, 'allOf'> & {
+    allOf: Call<Tuples.Map<Objects.Omit<'additionalProperties'>>, T['allOf']>
+  }
+  : T
+
+type FixMissingAdditionalProperties<T> = T extends Checks.Object ? Omit<T, 'additionalProperties'> & { additionalProperties: false }
+  : T
+type FixMissingTypeObject<T> = T extends Checks.Properties ? T & { type: 'object' } : T
+
+type FixExtraRequiredFields<T> = T extends Checks.PropertiesRequired ? Omit<T, 'required'> & {
+    required: Call<Tuples.Filter<Booleans.Extends<keyof T['properties']>>, T['required']>
+  }
+  : T
+
+// Later suggest using json-machete
+type FixJSONSchema<T> = FixAdditionalPropertiesForAllOf<
+  FixMissingAdditionalProperties<FixMissingTypeObject<FixExtraRequiredFields<T>>>
+>
+
+type Mutable<Type> = FixJSONSchema<
+  {
+    -readonly [Key in keyof Type]: Mutable<Type[Key]>
+  }
+>
+
+type RefToPath<T extends string> = T extends `#/${infer Ref}` ? Call<Strings.Split<'/'>, Ref>
+  : never
+
+type ResolveRef<TObj, TRef extends string> = {
+  $id: TRef
+} & Object.Path<TObj, RefToPath<TRef>>
+
+type ResolveRefInObj<T, TBase> = T extends { $ref: infer Ref } ? Ref extends string ? ResolveRef<TBase, Ref>
+  : T
+  : T
+
+type ResolveRefsInObj<T, TBase = T> = {
+  [K in keyof T]: ResolveRefsInObj<ResolveRefInObj<T[K], TBase>, TBase>
+}
+
+export type Parse<TOAS> = Mutable<ResolveRefsInObj<TOAS>>

package/src/infer/requestParams.ts

@@ -0,0 +1,170 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type { OasTypes } from '@kubb/swagger'
+import type { SplitByDelimiter, TupleToUnion } from '@kubb/types'
+import type { Pipe, Strings, Tuples } from 'hotscript'
+import type {
+  FromSchema,
+  JSONSchema,
+} from 'json-schema-to-ts'
+import type { MethodMap, ParamMap, PathMap } from './mappers.ts'
+import type { SecurityParamsBySecurityRef } from './security.ts'
+
+namespace Checks {
+  export type RequestBodyJson = {
+    requestBody: { content: { 'application/json': { schema: JSONSchema } } }
+  }
+  export type RequestBodyFormData = {
+    requestBody: {
+      content: { 'multipart/form-data': { schema: JSONSchema } }
+    }
+  }
+  export type RequestBodyFormEncoded = {
+    requestBody: {
+      content: {
+        'application/x-www-form-urlencoded': { schema: JSONSchema }
+      }
+    }
+  }
+  export type Parameters = {
+    parameters: { name: string; in: string }[]
+  }
+  export type PathBrackets = `${string}{${string}}${string}`
+  export type PathPattern = `${string}:${string}${string}`
+  export type Required = { required: true }
+}
+
+type ExtractPathParamsWithPattern<TPath extends string> = Pipe<
+  TPath,
+  [
+    Strings.Split<'/'>,
+    Tuples.Filter<Strings.StartsWith<':'>>,
+    Tuples.Map<Strings.Trim<':'>>,
+    Tuples.ToUnion,
+  ]
+>
+
+type IsPathParameter<T extends string> = T extends `{${infer U}}` ? U : never
+
+type ExtractPathParameters<T extends any[]> = {
+  [K in keyof T]: IsPathParameter<T[K]>
+}
+
+type ExtractSegments<TPath extends string> = SplitByDelimiter<TPath, '/'>
+
+type ExtractSubSegments<T extends any[]> = {
+  [K in keyof T]: SplitByDelimiter<T[K], ';'>
+}
+
+type ExtractPathParamsWithBrackets<TPath extends string> = TupleToUnion<
+  ExtractPathParameters<ExtractSubSegments<ExtractSegments<TPath>>[number]>
+>
+
+export type RequestParams<
+  TOAS extends OasTypes.OASDocument,
+  TPath extends keyof PathMap<TOAS>,
+  TMethod extends keyof MethodMap<TOAS, TPath>,
+> =
+  & (MethodMap<TOAS, TPath>[TMethod] extends Checks.RequestBodyJson ? MethodMap<TOAS, TPath>[TMethod]['requestBody'] extends Checks.Required ? {
+        /**
+         * The request body in JSON is required for this request.
+         *
+         * The value of `json` will be stringified and sent as the request body with `Content-Type: application/json`.
+         */
+        json: FromSchema<
+          MethodMap<TOAS, TPath>[TMethod]['requestBody']['content']['application/json']['schema']
+        >
+      }
+    : {
+      /**
+       * The request body in JSON is optional for this request.
+       *
+       * The value of `json` will be stringified and sent as the request body with `Content-Type: application/json`.
+       */
+      json?: FromSchema<
+        MethodMap<TOAS, TPath>[TMethod]['requestBody']['content']['application/json']['schema']
+      >
+    }
+    : MethodMap<TOAS, TPath>[TMethod] extends Checks.RequestBodyFormData ? MethodMap<TOAS, TPath>[TMethod]['requestBody'] extends Checks.Required ? {
+          /**
+           * The request body in multipart/form-data is required for this request.
+           *
+           * The value of `formData` will be sent as the request body with `Content-Type: multipart/form-data`.
+           */
+          formData: FromSchema<
+            MethodMap<
+              TOAS,
+              TPath
+            >[TMethod]['requestBody']['content']['multipart/form-data']['schema']
+          >
+        }
+      : {
+        /**
+         * The request body in multipart/form-data is optional for this request.
+         *
+         * The value of `formData` will be sent as the request body with `Content-Type: multipart/form-data`.
+         */
+        formData?: FromSchema<
+          MethodMap<
+            TOAS,
+            TPath
+          >[TMethod]['requestBody']['content']['multipart/form-data']['schema']
+        >
+      }
+    : MethodMap<TOAS, TPath>[TMethod] extends Checks.RequestBodyFormEncoded ? MethodMap<TOAS, TPath>[TMethod]['requestBody'] extends Checks.Required ? {
+          /**
+           * The request body in application/x-www-form-urlencoded is required for this request.
+           *
+           * The value of `formUrlEncoded` will be sent as the request body with `Content-Type: application/x-www-form-urlencoded`.
+           */
+          formUrlEncoded: FromSchema<
+            MethodMap<
+              TOAS,
+              TPath
+            >[TMethod]['requestBody']['content']['application/x-www-form-urlencoded']['schema']
+          >
+        }
+      : {
+        /**
+         * The request body in application/x-www-form-urlencoded is optional for this request.
+         *
+         * The value of `formUrlEncoded` will be sent as the request body with `Content-Type: application/x-www-form-urlencoded`.
+         */
+        formUrlEncoded?: FromSchema<
+          MethodMap<
+            TOAS,
+            TPath
+          >[TMethod]['requestBody']['content']['application/x-www-form-urlencoded']['schema']
+        >
+      }
+    : {})
+  & (MethodMap<TOAS, TPath>[TMethod] extends Checks.Parameters ? ParamMap<MethodMap<TOAS, TPath>[TMethod]['parameters']>
+    : {})
+  & // If there is any parameters defined in path but not in the parameters array, we should add them to the params
+  (TPath extends Checks.PathBrackets ? {
+      /**
+       * Parameters defined in the path are required for this request.
+       *
+       * The value of `params` will be used to replace the path parameters.
+       *
+       * For example if path is `/todos/{id}` and `params` is `{ id: '1' }`, the path will be `/todos/1`
+       */
+      params: Record<ExtractPathParamsWithBrackets<TPath>, string | number | bigint | boolean>
+    }
+    : {})
+  & (TPath extends Checks.PathPattern ? {
+      /**
+       * Parameters defined in the path are required for this request.
+       *
+       * The value of `params` will be used to replace the path parameters.
+       *
+       * For example if path is `/todos/:id` and `params` is `{ id: '1' }`, the path will be `/todos/1`.
+       */
+      params: Record<ExtractPathParamsWithPattern<TPath>, string | number | bigint | boolean>
+    }
+    : {})
+  & // Respect security definitions in path object
+  SecurityParamsBySecurityRef<TOAS, MethodMap<TOAS, TPath>[TMethod]>
+  & // Respect global security definitions
+  SecurityParamsBySecurityRef<TOAS, TOAS>

package/src/infer/response.ts

@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+import type { OasTypes } from '@kubb/swagger'
+import type {
+  FromSchema,
+} from 'json-schema-to-ts'
+import type { MethodMap, PathMap, StatusMap } from './mappers.ts'
+
+namespace Checks {
+  export type Content = { content: any }
+}
+
+type ResponseSchemas<
+  TOAS extends OasTypes.OASDocument,
+  TPath extends keyof PathMap<TOAS>,
+  TMethod extends keyof MethodMap<TOAS, TPath>,
+  TStatus extends keyof StatusMap<TOAS, TPath, TMethod>,
+> = StatusMap<TOAS, TPath, TMethod>[TStatus]['content']
+
+type JSONResponseSchema<
+  TOAS extends OasTypes.OASDocument,
+  TPath extends keyof PathMap<TOAS>,
+  TMethod extends keyof MethodMap<TOAS, TPath>,
+  TStatus extends keyof StatusMap<TOAS, TPath, TMethod>,
+> = StatusMap<TOAS, TPath, TMethod>[TStatus] extends Checks.Content ? ResponseSchemas<TOAS, TPath, TMethod, TStatus>[
+    keyof ResponseSchemas<
+      TOAS,
+      TPath,
+      TMethod,
+      TStatus
+    >
+  ]['schema']
+  : StatusMap<TOAS, TPath, TMethod>[TStatus]['schema']
+
+export type Response<
+  TOAS extends OasTypes.OASDocument,
+  TPath extends keyof PathMap<TOAS>,
+  TMethod extends keyof MethodMap<TOAS, TPath>,
+  TStatusCode extends keyof StatusMap<TOAS, TPath, TMethod> = 200,
+> = FromSchema<JSONResponseSchema<TOAS, TPath, TMethod, TStatusCode>>

package/src/infer/security.ts

@@ -0,0 +1,158 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type { Call, Objects, Tuples } from 'hotscript'
+
+namespace Checks {
+  export type Security = { security: { [key: string]: any }[] }
+
+  export namespace AuthParams {
+    export type Basic =
+      | {
+        type: 'http'
+        scheme: 'basic'
+      }
+      | { type: 'basic' }
+    export type Bearer =
+      | {
+        type: 'http'
+        scheme: 'bearer'
+      }
+      | { type: 'bearer' }
+
+    export type OAuth2 = {
+      type: 'oauth2'
+    }
+    export type ApiKey = {
+      type: 'apiKey'
+      in: 'header'
+    }
+  }
+
+  export namespace AuthName {
+    export type Basic = `basic${string}`
+    export type Bearer = `bearer${string}`
+    export type OAuth2 = `oauth${string}`
+  }
+}
+
+type SecuritySchemeName<T extends Checks.Security> = Call<
+  Tuples.Map<Objects.Keys>,
+  T['security']
+>[number]
+
+namespace AuthParams {
+  export type Basic<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.Basic ? {
+      headers: {
+        /**
+         * `Authorization` header is required for basic authentication
+         * @see https://en.wikipedia.org/wiki/Basic_access_authentication
+         *
+         * It contains the word `Basic` followed by a space and a base64-encoded string `username:password`
+         *
+         * @example
+         * ```
+         * Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+         * ```
+         */
+        Authorization: `Basic ${string}`
+      }
+    }
+    : {}
+
+  export type Bearer<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.Bearer ? {
+      /**
+       * `Authorization` header is required for bearer authentication
+       * @see https://swagger.io/docs/specification/authentication/bearer-authentication/
+       */
+      headers: {
+        /**
+         * It contains the word `Bearer` followed by a space and the token
+         *
+         * @example
+         * ```
+         * Authorization: Bearer {token}
+         * ```
+         */
+        Authorization: `Bearer ${string}`
+      }
+    }
+    : {}
+
+  export type ApiKey<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.ApiKey & { name: infer TApiKeyHeaderName } ? {
+      headers: {
+        /**
+         * Header required for API key authentication
+         */
+        [THeaderName in TApiKeyHeaderName extends string ? TApiKeyHeaderName : never]: string
+      }
+    }
+    : TSecurityScheme extends {
+      type: 'apiKey'
+      in: 'query'
+      name: infer TApiKeyQueryName
+    } ? {
+        query: {
+          /**
+           * Query parameter required for API key authentication
+           */
+          [TQueryName in TApiKeyQueryName extends string ? TApiKeyQueryName : never]: string
+        }
+      }
+    : {}
+
+  export type OAuth2<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.OAuth2 ? {
+      /**
+       * `Authorization` header is required for OAuth2.
+       */
+      headers: {
+        /**
+         * The access token string as issued by the authorization server.
+         * @example `Authorization: Bearer <access_token>`
+         */
+        Authorization: `Bearer ${string}`
+      }
+    }
+    : {}
+}
+
+type OASSecurityParams<TSecurityScheme> =
+  & AuthParams.Basic<TSecurityScheme>
+  & AuthParams.Bearer<TSecurityScheme>
+  & AuthParams.ApiKey<TSecurityScheme>
+  & AuthParams.OAuth2<TSecurityScheme>
+
+export type SecurityParamsBySecurityRef<TOAS, TSecurityObj> = TSecurityObj extends Checks.Security ? TOAS extends
+    | {
+      components: {
+        securitySchemes: {
+          [
+            TSecuritySchemeNameKey in SecuritySchemeName<TSecurityObj> extends string ? SecuritySchemeName<TSecurityObj>
+              : never
+          ]: infer TSecurityScheme
+        }
+      }
+    }
+    | {
+      securityDefinitions: {
+        [
+          TSecuritySchemeNameKey in SecuritySchemeName<TSecurityObj> extends string ? SecuritySchemeName<TSecurityObj>
+            : never
+        ]: infer TSecurityScheme
+      }
+    } ? OASSecurityParams<TSecurityScheme>
+    // OAS may have a bad reference to a security scheme
+    // So we can assume it
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.Basic ? AuthParams.Basic<{
+      type: 'http'
+      scheme: 'basic'
+    }>
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.Bearer ? AuthParams.Bearer<{
+      type: 'http'
+      scheme: 'bearer'
+    }>
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.OAuth2 ? AuthParams.OAuth2<{
+      type: 'oauth2'
+    }>
+  : {}
+  : {}

package/src/plugin.ts

@@ -16,7 +16,7 @@ export const pluginKey: PluginOptions['key'] = [pluginName] satisfies PluginOpti
 
 export const definePlugin = createPlugin<PluginOptions>((options) => {
   const {
-    output = 'types',
+    output = { path: 'types' },
     group,
     exclude = [],
     include,
@@ -25,9 +25,9 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
     dateType = 'string',
     optionalType = 'questionToken',
     transformers = {},
-    exportAs,
+    oasType = false,
   } = options
-  const template = group?.output ? group.output : `${output}/{{tag}}Controller`
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
 
   return {
     name: pluginName,
@@ -36,20 +36,21 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
       dateType,
       enumType,
       optionalType,
+      oasType,
       // keep the used enumnames between TypeBuilder and OperationGenerator per plugin(pluginKey)
       usedEnumNames: {},
     },
     pre: [swaggerPluginName],
     resolvePath(baseName, directory, options) {
       const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = FileManager.getMode(path.resolve(root, output))
+      const mode = FileManager.getMode(path.resolve(root, output.path))
 
       if (mode === 'file') {
         /**
          * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
          * Other plugins then need to call addOrAppend instead of just add from the fileManager class
          */
-        return path.resolve(root, output)
+        return path.resolve(root, output.path)
       }
 
       if (options?.tag && group?.type === 'tag') {
@@ -58,7 +59,7 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
         return path.resolve(root, renderTemplate(template, { tag }), baseName)
       }
 
-      return path.resolve(root, output, baseName)
+      return path.resolve(root, output.path, baseName)
     },
     resolveName(name, type) {
       const resolvedName = pascalCase(name)
@@ -83,7 +84,7 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
 
       const schemas = await swaggerPlugin.api.getSchemas()
       const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = FileManager.getMode(path.resolve(root, output))
+      const mode = FileManager.getMode(path.resolve(root, output.path))
       const builder = new TypeBuilder(this.plugin.options, { oas, pluginManager: this.pluginManager })
 
       builder.add(
@@ -126,7 +127,7 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
 
         await this.addFile({
           path: resolvedPath,
-          baseName: output as KubbFile.BaseName,
+          baseName: output.path as KubbFile.BaseName,
           source,
           imports: [],
           meta: {
@@ -161,25 +162,9 @@ export const definePlugin = createPlugin<PluginOptions>((options) => {
 
       await this.fileManager.addIndexes({
         root,
-        extName: '.ts',
+        output,
         meta: { pluginKey: this.plugin.key },
         options: {
-          map: (file) => {
-            return {
-              ...file,
-              exports: file.exports?.map((item) => {
-                if (exportAs) {
-                  return {
-                    ...item,
-                    name: exportAs,
-                    asAlias: !!exportAs,
-                  }
-                }
-                return item
-              }),
-            }
-          },
-          output,
           isTypeOnly: true,
         },
       })

package/src/types.ts

@@ -1,13 +1,23 @@
-import type { KubbPlugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type { KubbFile, KubbPlugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
 import type { AppMeta as SwaggerAppMeta, Exclude, Include, Override, ResolvePathOptions } from '@kubb/swagger'
 
 export type Options = {
-  /**
-   * Relative path to save the TypeScript types.
-   * When output is a file it will save all models inside that file else it will create a file per schema item.
-   * @default 'types'
-   */
-  output?: string
+  output?: {
+    /**
+     * Relative path to save the TypeScript types.
+     * When output is a file it will save all models inside that file else it will create a file per schema item.
+     * @default 'types'
+     */
+    path: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './'`
+     */
+    exportAs?: string
+    /**
+     * Add an extension to the generated imports and exports, default it will not use an extension
+     */
+    extName?: KubbFile.Extname
+  }
   /**
    * Group the TypeScript types based on the provided name.
    */
@@ -25,10 +35,6 @@ export type Options = {
      */
     output?: string
   }
-  /**
-   * Name to be used for the `export * as {{exportAs}} from './`
-   */
-  exportAs?: string
   /**
    * Array containing exclude paramaters to exclude/skip tags/operations/methods/paths.
    */
@@ -65,6 +71,12 @@ export type Options = {
      */
     name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
   }
+  /**
+   * Export Oas object as Oas type with import type { Infer } from `@kubb/swagger-ts/infer`
+   * TODO add docs
+   * @beta
+   */
+  oasType?: boolean
 }
 
 type ResolvedOptions = {
@@ -72,6 +84,7 @@ type ResolvedOptions = {
   dateType: NonNullable<Options['dateType']>
   optionalType: NonNullable<Options['optionalType']>
   transformers: NonNullable<Options['transformers']>
+  oasType: NonNullable<Options['oasType']>
   usedEnumNames: Record<string, number>
 }
 
@@ -90,3 +103,5 @@ declare module '@kubb/core' {
     ['@kubb/swagger-ts']: PluginOptions
   }
 }
+// external packages
+export * as Infer from './infer/index.ts'