Skip to content

Globals.d.ts beta

Features

  • AXIOS_BASE for Axios's baseURL
  • AXIOS_HEADERS for Axios's headers

See reference/fileManager#getenveource for more information about how this works in the background.

ts
import type { PluginFactoryOptions } from '@kubb/core'
import type { AppMeta as SwaggerAppMeta, OverrideBy, ResolvePathOptions, SkipBy } from '@kubb/swagger'
import type { CreateAxiosDefaults } from 'axios'

/**
 * We override `process.env` so no need to import this
 * @example tsconfig.json
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
*/
export type Environments = {
  AXIOS_BASE?: CreateAxiosDefaults['baseURL']
  AXIOS_HEADERS?: CreateAxiosDefaults['headers']
}

/**
 * We override `process.env` so no need to import this
 * @example tsconfig.json
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
*/
export type Environment = keyof Environments

export type Options = {
  /**
   * Output to save the clients.
   * @default `"clients"``
   */
  output?: string
  /**
   * Group the clients based on the provided name.
   */
  groupBy?: {
    /**
     * Tag will group based on the operation tag inside the Swagger file
     */
    type: 'tag'
    /**
     * Relative path to save the grouped clients.
     *
     * `{{tag}}` will be replaced by the current tagName.
     * @example `${output}/{{tag}}Controller` => `clients/PetController`
     * @default `${output}/{{tag}}Controller`
     */
    output?: string
    /**
     * Name to be used for the `export * as {{exportAs}} from './`
     * @default `"{{tag}}Service"`
     */
    exportAs?: string
  }
  /**
   * Array containing skipBy paramaters to exclude/skip tags/operations/methods/paths.
   */
  skipBy?: Array<SkipBy>
  /**
   * Array containing overrideBy paramaters to override `options` based on tags/operations/methods/paths.
   */
  overrideBy?: Array<OverrideBy<Options>>
  /**
   * Path to the client that will be used to do the API calls.
   * Relative to the root.
   * @default '@kubb/swagger-client/client'
   * @deprecated Use `clientImportPath` instead. It will be skipped if `clientImportPath` is provided.
   */
  client?: string
  /**
   * Path to the client import path that will be used to do the API calls.
   * It will be used as `import client from '${clientImportPath}'`.
   * It allow both relative and absolute path.
   * the path will be applied as is, so relative path should be based on the file being generated.
   * @default '@kubb/swagger-client/client'
   */
  clientImportPath?: string
  /**
   * Experimental
   *
   * ReturnType that needs to be used when calling client().
   *
   * `Data` will return ResponseConfig[data].
   *
   * `Full` will return ResponseConfig.
   * @default `'data'`
   * @private
   */
  dataReturnType?: 'data' | 'full'
  /**
   * Experimental
   *
   * How to pass your pathParams.
   *
   * `object` will return the pathParams as an object.
   *
   * `inline` will return the pathParams as comma separated params.
   * @default `'inline'`
   * @private
   */
  pathParamsType?: 'object' | 'inline'
  transformers?: {
    /**
     * Override the name of the client that is getting generated, this will also override the name of the file.
     */
    name?: (name: string) => string
  }
}

export type FileMeta = {
  pluginName?: string
  tag?: string
}

export type PluginOptions = PluginFactoryOptions<'swagger-client', Options, false, never, ResolvePathOptions>

export type AppMeta = SwaggerAppMeta
import type { PluginFactoryOptions } from '@kubb/core'
import type { AppMeta as SwaggerAppMeta, OverrideBy, ResolvePathOptions, SkipBy } from '@kubb/swagger'
import type { CreateAxiosDefaults } from 'axios'

/**
 * We override `process.env` so no need to import this
 * @example tsconfig.json
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
*/
export type Environments = {
  AXIOS_BASE?: CreateAxiosDefaults['baseURL']
  AXIOS_HEADERS?: CreateAxiosDefaults['headers']
}

/**
 * We override `process.env` so no need to import this
 * @example tsconfig.json
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
*/
export type Environment = keyof Environments

export type Options = {
  /**
   * Output to save the clients.
   * @default `"clients"``
   */
  output?: string
  /**
   * Group the clients based on the provided name.
   */
  groupBy?: {
    /**
     * Tag will group based on the operation tag inside the Swagger file
     */
    type: 'tag'
    /**
     * Relative path to save the grouped clients.
     *
     * `{{tag}}` will be replaced by the current tagName.
     * @example `${output}/{{tag}}Controller` => `clients/PetController`
     * @default `${output}/{{tag}}Controller`
     */
    output?: string
    /**
     * Name to be used for the `export * as {{exportAs}} from './`
     * @default `"{{tag}}Service"`
     */
    exportAs?: string
  }
  /**
   * Array containing skipBy paramaters to exclude/skip tags/operations/methods/paths.
   */
  skipBy?: Array<SkipBy>
  /**
   * Array containing overrideBy paramaters to override `options` based on tags/operations/methods/paths.
   */
  overrideBy?: Array<OverrideBy<Options>>
  /**
   * Path to the client that will be used to do the API calls.
   * Relative to the root.
   * @default '@kubb/swagger-client/client'
   * @deprecated Use `clientImportPath` instead. It will be skipped if `clientImportPath` is provided.
   */
  client?: string
  /**
   * Path to the client import path that will be used to do the API calls.
   * It will be used as `import client from '${clientImportPath}'`.
   * It allow both relative and absolute path.
   * the path will be applied as is, so relative path should be based on the file being generated.
   * @default '@kubb/swagger-client/client'
   */
  clientImportPath?: string
  /**
   * Experimental
   *
   * ReturnType that needs to be used when calling client().
   *
   * `Data` will return ResponseConfig[data].
   *
   * `Full` will return ResponseConfig.
   * @default `'data'`
   * @private
   */
  dataReturnType?: 'data' | 'full'
  /**
   * Experimental
   *
   * How to pass your pathParams.
   *
   * `object` will return the pathParams as an object.
   *
   * `inline` will return the pathParams as comma separated params.
   * @default `'inline'`
   * @private
   */
  pathParamsType?: 'object' | 'inline'
  transformers?: {
    /**
     * Override the name of the client that is getting generated, this will also override the name of the file.
     */
    name?: (name: string) => string
  }
}

export type FileMeta = {
  pluginName?: string
  tag?: string
}

export type PluginOptions = PluginFactoryOptions<'swagger-client', Options, false, never, ResolvePathOptions>

export type AppMeta = SwaggerAppMeta
ts
/// <reference no-default-lib="true" />
/// <reference lib="esnext" />

type Environments = import('./src/types.ts').Environments

declare module 'global' {
  namespace NodeJS {
    export interface ProcessEnv extends Partial<Record<keyof Environments, string>> {}
  }
}
/**
 * `tsconfig.json`
 * @example
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
 * @example implementation
{
___ env?: NodeJS.ProcessEnv
}
*/
declare namespace NodeJS {
  export interface ProcessEnv extends Partial<Record<keyof Environments, string>> {}
}
/// <reference no-default-lib="true" />
/// <reference lib="esnext" />

type Environments = import('./src/types.ts').Environments

declare module 'global' {
  namespace NodeJS {
    export interface ProcessEnv extends Partial<Record<keyof Environments, string>> {}
  }
}
/**
 * `tsconfig.json`
 * @example
"compilerOptions": {
___ "types": ["@kubb/swagger-client/globals"]
}
 * @example implementation
{
___ env?: NodeJS.ProcessEnv
}
*/
declare namespace NodeJS {
  export interface ProcessEnv extends Partial<Record<keyof Environments, string>> {}
}

TypeScript

To get TypeScript support for NodeJS.ProcessEnv(with already the process.env type being set), add @kubb/swagger-client/globals to your tsconfig.json:

typescript
{
  "compilerOptions": {
    "types": [
      "@kubb/swagger-client/globals" 
    ]
  }
}
{
  "compilerOptions": {
    "types": [
      "@kubb/swagger-client/globals" 
    ]
  }
}

Usage

ts
/* eslint-disable @typescript-eslint/no-namespace */

type BasePath<T extends string = string> = `${T}/`

export type CacheItem = KubbFile.ResolvedFile & {
  cancel?: () => void
}

export namespace KubbFile {
  export type Import = {
    name: string | Array<string>
    path: string
    isTypeOnly?: boolean
  }

  export type Export = {
    name?: string | Array<string>
    path: string
    isTypeOnly?: boolean
    asAlias?: boolean
  }

  export type UUID = string
  export type Source = string

  export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`

  export type Mode = 'file' | 'directory'

  export type BaseName = `${string}${Extname}`

  export type Path = string

  export type AdvancedPath<T extends BaseName = BaseName> = `${BasePath}${T}`

  export type OptionalPath = Path | undefined | null

  export type File<
    TMeta extends {
      pluginName?: string
    } = {
      pluginName?: string
    },
    TBaseName extends BaseName = BaseName,
  > = {
    /**
     * Name to be used to dynamicly create the baseName(based on input.path)
     * Based on UNIX basename
     * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
     */
    baseName: TBaseName
    /**
     * Path will be full qualified path to a specified file
     */
    path: AdvancedPath<TBaseName> | Path
    source: Source
    imports?: Import[]
    exports?: Export[]
    /**
     * This will call fileManager.add instead of fileManager.addOrAppend, adding the source when the files already exists
     * @default `false`
     */
    override?: boolean
    meta?: TMeta
    /**
     * This will override `process.env[key]` inside the `source`, see `getFileSource`.
     */
    env?: NodeJS.ProcessEnv
  }

  export type ResolvedFile = KubbFile.File & {
    /**
     * crypto.randomUUID()
     */
    id: UUID
  }
}
/* eslint-disable @typescript-eslint/no-namespace */

type BasePath<T extends string = string> = `${T}/`

export type CacheItem = KubbFile.ResolvedFile & {
  cancel?: () => void
}

export namespace KubbFile {
  export type Import = {
    name: string | Array<string>
    path: string
    isTypeOnly?: boolean
  }

  export type Export = {
    name?: string | Array<string>
    path: string
    isTypeOnly?: boolean
    asAlias?: boolean
  }

  export type UUID = string
  export type Source = string

  export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`

  export type Mode = 'file' | 'directory'

  export type BaseName = `${string}${Extname}`

  export type Path = string

  export type AdvancedPath<T extends BaseName = BaseName> = `${BasePath}${T}`

  export type OptionalPath = Path | undefined | null

  export type File<
    TMeta extends {
      pluginName?: string
    } = {
      pluginName?: string
    },
    TBaseName extends BaseName = BaseName,
  > = {
    /**
     * Name to be used to dynamicly create the baseName(based on input.path)
     * Based on UNIX basename
     * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
     */
    baseName: TBaseName
    /**
     * Path will be full qualified path to a specified file
     */
    path: AdvancedPath<TBaseName> | Path
    source: Source
    imports?: Import[]
    exports?: Export[]
    /**
     * This will call fileManager.add instead of fileManager.addOrAppend, adding the source when the files already exists
     * @default `false`
     */
    override?: boolean
    meta?: TMeta
    /**
     * This will override `process.env[key]` inside the `source`, see `getFileSource`.
     */
    env?: NodeJS.ProcessEnv
  }

  export type ResolvedFile = KubbFile.File & {
    /**
     * crypto.randomUUID()
     */
    id: UUID
  }
}

Notes

This feature could be useful for:

  • Types support for 'axios' options
  • Prototyping

Released under the MIT License.