types.ts

import {JSONSchema4} from 'json-schema'
import {LiteralUnion, Omit} from 'vtils'
import {ParsedPath} from 'path'

export interface ChangeCase {
  /**
   * @example
   * changeCase.camelCase('test string') // => 'testString'
   */
  camelCase: (value: string) => string,
  /**
   * @example
   * changeCase.constantCase('test string') // => 'TEST_STRING'
   */
  constantCase: (value: string) => string,
  /**
   * @example
   * changeCase.dotCase('test string') // => 'test.string'
   */
  dotCase: (value: string) => string,
  /**
   * @example
   * changeCase.headerCase('test string') // => 'Test-String'
   */
  headerCase: (value: string) => string,
  /**
   * @example
   * changeCase.lowerCase('TEST STRING') // => 'test string'
   */
  lowerCase: (value: string) => string,
  /**
   * @example
   * changeCase.lowerCaseFirst('TEST') // => 'tEST'
   */
  lowerCaseFirst: (value: string) => string,
  /**
   * @example
   * changeCase.paramCase('test string') // => 'test-string'
   */
  paramCase: (value: string) => string,
  /**
   * @example
   * changeCase.pascalCase('test string') // => 'TestString'
   */
  pascalCase: (value: string) => string,
  /**
   * @example
   * changeCase.pathCase('test string') // => 'test/string'
   */
  pathCase: (value: string) => string,
  /**
   * @example
   * changeCase.sentenceCase('testString') // => 'Test string'
   */
  sentenceCase: (value: string) => string,
  /**
   * @example
   * changeCase.snakeCase('test string') // => 'test_string'
   */
  snakeCase: (value: string) => string,
  /**
   * @example
   * changeCase.swapCase('Test String') // => 'tEST sTRING'
   */
  swapCase: (value: string) => string,
  /**
   * @example
   * changeCase.titleCase('a simple test') // => 'A Simple Test'
   */
  titleCase: (value: string) => string,
  /**
   * @example
   * changeCase.upperCase('test string') // => 'TEST STRING'
   */
  upperCase: (value: string) => string,
  /**
   * @example
   * changeCase.upperCaseFirst('test') // => 'Test'
   */
  upperCaseFirst: (value: string) => string,
}

/** 请求方式 */
export enum Method {
  GET = 'GET',
  POST = 'POST',
  PUT = 'PUT',
  DELETE = 'DELETE',
  HEAD = 'HEAD',
  OPTIONS = 'OPTIONS',
  PATCH = 'PATCH',
}

/** 是否必需 */
export enum Required {
  /** 不必需 */
  false = '0',
  /** 必需 */
  true = '1',
}

/** 请求数据类型 */
export enum RequestBodyType {
  /** 查询字符串 */
  query = 'query',
  /** 表单 */
  form = 'form',
  /** JSON */
  json = 'json',
  /** 纯文本 */
  text = 'text',
  /** 文件 */
  file = 'file',
  /** 原始数据 */
  raw = 'raw',
  /** 无请求数据 */
  none = 'none',
}

/** 请求表单条目类型 */
export enum RequestFormItemType {
  /** 纯文本 */
  text = 'text',
  /** 文件 */
  file = 'file',
}

/** 返回数据类型 */
export enum ResponseBodyType {
  /** JSON */
  json = 'json',
  /** 纯文本 */
  text = 'text',
  /** XML */
  xml = 'xml',
  /** 原始数据 */
  raw = 'raw',

  // yapi 实际上返回的是 json，有另外的字段指示其是否是 json schema
  /** JSON Schema */
  // jsonSchema = 'json-schema',
}

/** 接口定义 */
export interface Interface {
  /** 接口 ID */
  _id: number,
  /** 所属分类信息（由 YTT 自行实现） */
  _category: Omit<Category, 'list'>,
  /** 接口名称 */
  title: string,
  /** 状态 */
  status: LiteralUnion<'done' | 'undone', string>,
  /** 接口备注 */
  markdown: string,
  /** 请求路径 */
  path: string,
  /** 请求方式，HEAD、OPTIONS 处理与 GET 相似，其余处理与 POST 相似 */
  method: Method,
  /** 所属项目 id */
  project_id: number,
  /** 所属分类 id */
  catid: number,
  /** 标签列表 */
  tag: string[],
  /** 路径参数 */
  req_params: Array<{
    /** 名称 */
    name: string,
    /** 备注 */
    desc: string,
    /** 示例 */
    example: string,
  }>,
  /** 仅 GET：请求串 */
  req_query: Array<{
    /** 名称 */
    name: string,
    /** 备注 */
    desc: string,
    /** 示例 */
    example: string,
    /** 是否必需 */
    required: Required,
  }>,
  /** 仅 POST：请求内容类型。为 text, file, raw 时不必特殊处理。 */
  req_body_type: RequestBodyType,
  /** `req_body_type = json` 时是否为 json schema */
  req_body_is_json_schema: boolean,
  /** `req_body_type = form` 时的请求内容 */
  req_body_form: Array<{
    /** 名称 */
    name: string,
    /** 类型 */
    type: RequestFormItemType,
    /** 备注 */
    desc: string,
    /** 示例 */
    example: string,
    /** 是否必需 */
    required: Required,
  }>,
  /** `req_body_type = json` 时的请求内容 */
  req_body_other: string,
  /** 返回数据类型 */
  res_body_type: ResponseBodyType,
  /** `res_body_type = json` 时是否为 json schema */
  res_body_is_json_schema: boolean,
  /** 返回数据 */
  res_body: string,
  /** 创建时间（unix时间戳） */
  add_time: number,
  /** 更新时间（unix时间戳） */
  up_time: number,
  [key: string]: any,
}

/** 扩展接口定义 */
export interface ExtendedInterface extends Interface {
  parsedPath: ParsedPath,
}

/** 接口列表 */
export type InterfaceList = Interface[]

/** 分类信息 */
export interface Category {
  /** 分类名称 */
  name: string,
  /** 分类备注 */
  desc: string,
  /** 分类接口列表 */
  list: InterfaceList,
  /** 创建时间（unix时间戳） */
  add_time: number,
  /** 更新时间（unix时间戳） */
  up_time: number,
}

/** 分类列表，对应数据导出的 json 内容 */
export type CategoryList = Category[]

/** 支持生成 React Hooks 代码的相关配置 */
export interface ReactHooksConfig {
  /**
   * 是否开启该项功能。
   */
  enable: boolean,

  /**
   * 从何处引入 useState、useEffect 等 Hooks。
   *
   * @default 'react'
   */
  pragma?: string,

  /**
   * 获取自动触发 API 的 Hook 的名称。
   *
   * @default `useAutoApi${changeCase.pascalCase(requestFunctionName)}`
   * @param interfaceInfo 接口信息
   * @param changeCase 常用的大小写转换函数集合对象
   * @returns Hook 的名称
   */
  getAutoApiHookName?(interfaceInfo: ExtendedInterface, changeCase: ChangeCase): string,

  /**
   * 获取手动触发 API 的 Hook 的名称。
   *
   * @default `useManualApi${changeCase.pascalCase(requestFunctionName)}`
   * @param interfaceInfo 接口信息
   * @param changeCase 常用的大小写转换函数集合对象
   * @returns Hook 的名称
   */
  getManualApiHookName?(interfaceInfo: ExtendedInterface, changeCase: ChangeCase): string,
}

/**
 * 共享的配置。
 */
export interface SharedConfig {
  /**
   * 是否只生成接口请求内容和返回内容的 TypeSript 类型，是则请求文件和请求函数都不会生成。
   *
   * @default false
   */
  typesOnly?: boolean,

  /**
   * 测试环境名称。
   *
   * **用于获取测试环境域名。**
   *
   * 获取方式：打开项目 --> `设置` --> `环境配置` --> 点开或新增测试环境 --> 复制测试环境名称。
   *
   * @example 'dev'
   */
  devEnvName?: string,

  /**
   * 生产环境名称。
   *
   * **用于获取生产环境域名。**
   *
   * 获取方式：打开项目 --> `设置` --> `环境配置` --> 点开或新增生产环境 --> 复制生产环境名称。
   *
   * @example 'prod'
   */
  prodEnvName?: string,

  /**
   * 输出文件路径。
   *
   * 可以是 `相对路径` 或 `绝对路径`。
   *
   * @example 'src/api/index.ts'
   */
  outputFilePath?: string,

  /**
   * 请求函数文件路径。
   *
   * @default 与 `outputFilePath` 同级目录下的 `request.ts` 文件
   * @example 'src/api/request.ts'
   */
  requestFunctionFilePath?: string,

  /**
   * 如果接口响应的结果是 `JSON` 对象，
   * 且我们想要的数据在该对象下，
   * 那我们就可将 `dataKey` 设为我们想要的数据对应的键。
   *
   * 比如该对象为 `{ code: 0, msg: '成功', data: 100 }`，
   * 我们想要的数据为 `100`，
   * 则我们可将 `dataKey` 设为 `data`。
   *
   * @example 'data'
   */
  dataKey?: string,

  /**
   * 支持生成 React Hooks 代码的相关配置。
   */
  reactHooks?: ReactHooksConfig,

  /**
   * 预处理接口信息，返回新的接口信息。
   *
   * 譬如你想对接口的 `path` 进行某些处理，就可使用该方法。
   *
   * @example
   *
   * ```js
   * interfaceInfo => {
   *   interfaceInfo.path = interfaceInfo.path.replace('v1', 'v2')
   *   return interfaceInfo
   * }
   * ```
   */
  preproccessInterface?(interfaceInfo: Interface, changeCase: ChangeCase): Interface,

  /**
   * 获取请求函数的名称。
   *
   * @default changeCase.camelCase(interfaceInfo.parsedPath.name)
   * @param interfaceInfo 接口信息
   * @param changeCase 常用的大小写转换函数集合对象
   * @returns 请求函数的名称
   */
  getRequestFunctionName?(interfaceInfo: ExtendedInterface, changeCase: ChangeCase): string,

  /**
   * 获取请求数据类型的名称。
   *
   * @default changeCase.pascalCase(`${requestFunctionName}Request`)
   * @param interfaceInfo 接口信息
   * @param changeCase 常用的大小写转换函数集合对象
   * @returns 请求数据类型的名称
   */
  getRequestDataTypeName?(interfaceInfo: ExtendedInterface, changeCase: ChangeCase): string,

  /**
   * 获取响应数据类型的名称。
   *
   * @default changeCase.pascalCase(`${requestFunctionName}Response`)
   * @param interfaceInfo 接口信息
   * @param changeCase 常用的大小写转换函数集合对象
   * @returns 响应数据类型的名称
   */
  getResponseDataTypeName?(interfaceInfo: ExtendedInterface, changeCase: ChangeCase): string,
}

/**
 * 分类的配置。
 */
export interface CategoryConfig extends SharedConfig {
  /**
   * 分类 ID，可以设置多个。设为 `0` 时表示全部分类。
   *
   * 获取方式：打开项目 --> 点开分类 --> 复制浏览器地址栏 `/api/cat_` 后面的数字。
   *
   * @example 20
   */
  id: number | number[],
}

/**
 * 项目的配置。
 */
export interface ProjectConfig extends SharedConfig {
  /**
   * 项目的唯一标识。
   *
   * 获取方式：打开项目 --> `设置` --> `token配置` --> 复制 token。
   *
   * @example 'e02a47122259d0c1973a9ff81cabb30685d64abc72f39edaa1ac6b6a792a647d'
   */
  token: string,

  /**
   * 分类列表。
   */
  categories: CategoryConfig[],
}

/**
 * 服务器的配置。
 */
export interface ServerConfig extends SharedConfig {
  /**
   * YApi 服务地址。
   *
   * @example 'http://yapi.foo.bar'
   */
  serverUrl: string,

  /**
   * 项目列表。
   */
  projects: ProjectConfig[],
}

/** 混合的配置。 */
export type SyntheticalConfig = Partial<(
  ServerConfig
  & ServerConfig['projects'][0]
  & ServerConfig['projects'][0]['categories'][0]
  & {
    mockUrl: string,
    devUrl: string,
    prodUrl: string,
  }
)>

/** 配置。 */
export type Config = ServerConfig | ServerConfig[]

/**
 * 请求配置。
 */
export interface RequestConfig<
  MockUrl extends string = any,
  DevUrl extends string = any,
  ProdUrl extends string = any,
  Path extends string = any,
  DataKey extends string | undefined = any,
  ParamName extends string = any,
> {
  /** 接口 Mock 地址，结尾无 `/` */
  mockUrl: MockUrl,
  /** 接口测试环境地质，结尾无 `/` */
  devUrl: DevUrl,
  /** 接口生产环境地址，结尾无 `/` */
  prodUrl: ProdUrl,
  /** 接口路径，以 `/` 开头 */
  path: Path,
  /** 请求方法 */
  method: Method,
  /** 请求数据类型 */
  requestBodyType: RequestBodyType,
  /** 返回数据类型 */
  responseBodyType: ResponseBodyType,
  /** 数据所在键 */
  dataKey: DataKey,
  /** 路径参数的名称列表 */
  paramNames: ParamName[],
}

/**
 * 请求参数。
 */
export interface RequestFunctionParams extends RequestConfig {
  /** 请求数据，不含文件数据 */
  data: any,
  /** 是否有文件数据 */
  hasFileData: boolean,
  /** 请求文件数据 */
  fileData: Record<string, any>,
}

/** 请求函数的额外参数 */
export type RequestFunctionRestArgs<T extends Function> = T extends (payload: any, ...args: infer R) => any ? R : never

/** 属性定义 */
export interface PropDefinition {
  /** 属性名称 */
  name: string,
  /** 是否必需 */
  required: boolean,
  /** 类型 */
  type: JSONSchema4['type'],
  /** 注释 */
  comment: string,
}

/** 属性定义列表 */
export type PropDefinitions = PropDefinition[]