@devbie/apits 0.0.0-stage → 1.0.0

package/dist/esm/types.d.mts

@@ -0,0 +1,330 @@
+/// <reference types="node" />
+export * from "json-schema";
+import { JSONSchema4 } from "json-schema";
+import { OpenAPIV3 } from "openapi-types";
+import { ParsedPath } from "path";
+/** Returns the client import snippet placed at the top of each generated file. */
+export type ClientImportTemplate = () => string;
+/** Interface definition */
+export interface Interface {
+    /** Interface name */
+    title: string;
+    /** Request path */
+    path: string;
+    /** Request method, HEAD and OPTIONS are handled like GET, others like POST */
+    method: Method;
+    /** Path parameters */
+    req_params: Array<{
+        /** Name */
+        name: string;
+        /** Description */
+        desc: string;
+        /** Example */
+        example: string;
+        /** Type (YApi-X) */
+        type?: RequestParamType;
+    }>;
+    /** GET only: query string */
+    req_query: Array<{
+        /** Name */
+        name: string;
+        /** Description */
+        desc: string;
+        /** Example */
+        example: string;
+        /** Required */
+        required: Required;
+        /** Type (YApi-X) */
+        type?: RequestQueryType;
+    }>;
+    /** POST only: request content type. No special handling needed for text, file, raw. */
+    req_body_type: RequestBodyType;
+    /** Whether it is json schema when `req_body_type = json` */
+    req_body_is_json_schema: boolean;
+    /** Request content when `req_body_type = form` */
+    req_body_form: Array<{
+        /** Name */
+        name: string;
+        /** Type */
+        type: RequestFormItemType;
+        /** Description */
+        desc: string;
+        /** Example */
+        example: string;
+        /** Required */
+        required: Required;
+        /**
+         * Whether the field accepts multiple files (a binary array in the
+         * OpenAPI schema, e.g. `files: {type: 'array', items: {format: 'binary'}}`).
+         * Only meaningful when `type` is `file`.
+         */
+        isArray?: boolean;
+        /** Allowed literal values when the form field is an enum */
+        enum?: Array<string | number>;
+    }>;
+    /**
+     * Whether the form body is `multipart/form-data` (true) or
+     * `application/x-www-form-urlencoded` (false). Only set when
+     * `req_body_type = form`.
+     */
+    req_body_multipart?: boolean;
+    /**
+     * JSON Schema fragment describing dynamic form fields (the
+     * `additionalProperties` of a multipart request schema). Used for
+     * runtime-named upload fields such as `evidence_0`, `evidence_1`, ...
+     */
+    req_body_additional?: Record<string, any>;
+    /** Request content when `req_body_type = json` */
+    req_body_other: string;
+    /** Response data type */
+    res_body_type: ResponseBodyType;
+    /** Whether it is json schema when `res_body_type = json` */
+    res_body_is_json_schema: boolean;
+    /** Response data */
+    res_body: string;
+    [key: string]: any;
+}
+/** Category information */
+export interface Category {
+    /** Category name */
+    name: string;
+    /** Category description */
+    desc: string;
+}
+/** Request method */
+export declare enum Method {
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    DELETE = "DELETE",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS",
+    PATCH = "PATCH"
+}
+/** Required */
+export declare enum Required {
+    /** Not required */
+    false = "0",
+    /** Required */
+    true = "1"
+}
+/** Request body type */
+export declare enum RequestBodyType {
+    /** Query string */
+    query = "query",
+    /** Form */
+    form = "form",
+    /** JSON */
+    json = "json",
+    /** Plain text */
+    text = "text",
+    /** File */
+    file = "file",
+    /** Raw data */
+    raw = "raw",
+    /** No request data */
+    none = "none"
+}
+/** Request path parameter type */
+export declare enum RequestParamType {
+    /** String */
+    string = "string",
+    /** Number */
+    number = "number"
+}
+/** Request query parameter type */
+export declare enum RequestQueryType {
+    /** String */
+    string = "string",
+    /** Number */
+    number = "number"
+}
+/** Request form item type */
+export declare enum RequestFormItemType {
+    /** Plain text */
+    text = "text",
+    /** File */
+    file = "file"
+}
+/** Response body type */
+export declare enum ResponseBodyType {
+    /** JSON */
+    json = "json",
+    /** Plain text */
+    text = "text",
+    /** XML */
+    xml = "xml",
+    /** Raw data */
+    raw = "raw"
+}
+/** Extended interface definition */
+export interface ExtendedInterface extends Interface {
+    parsedPath: ParsedPath;
+}
+/**
+ * Generator configuration for one OpenAPI source.
+ */
+export interface ApiConfig {
+    /**
+     * The OpenAPI document to generate code from. Required.
+     *
+     * Accepts an http(s) URL or a local file path. Local files may be
+     * JSON (.json / .json5) or YAML (.yaml / .yml).
+     *
+     * @example 'http://localhost:3041/api-json'
+     * @example './openapi.json'
+     * @example './docs/openapi.yaml'
+     */
+    input: string;
+    /**
+     * Output directory for generated files (relative or absolute path).
+     *
+     * Two files are written into it: `<name>.ts` (type declarations and
+     * request functions) and `request.ts` (the axios client, unless
+     * `client` is false or the file already exists).
+     *
+     * @default 'src/api'
+     */
+    output?: string;
+    /**
+     * Base name of the generated types file: code is written to
+     * `<output>/<name>.ts`. Also serves as the source identifier for
+     * `apits gen -n <name>` filtering.
+     *
+     * Defaults to a name derived from `input`: the URL hostname
+     * (`http://localhost:3041/api-json` -> `localhost`) or the local file
+     * name without extension (`./user.openapi.yaml` -> `userOpenapi`).
+     * Duplicated derived names get an index suffix.
+     */
+    name?: string;
+    /**
+     * Runtime `baseURL` baked into every generated request function.
+     *
+     * Prefix with `[code]:` to emit the value as code instead of a string
+     * literal, e.g. to read from an env var at runtime:
+     *
+     * - `baseURL: '[code]:process.env.BASE_URL'` -> `baseURL: process.env.BASE_URL`
+     * - `baseURL: 'http://localhost:3000'`       -> `baseURL: "http://localhost:3000"`
+     *
+     * May also be a function receiving each API path and returning the
+     * baseURL to use for that path (or undefined to omit).
+     */
+    baseURL?: ((path: string) => string | undefined) | string;
+    /**
+     * Returns the import snippet placed at the top of every generated file —
+     * use it to point at a custom request client instead of the scaffolded
+     * `request.ts`.
+     *
+     * Providing this option also flips the default of `client` to `false`,
+     * so no unused `request.ts` is scaffolded; set `client: true` explicitly
+     * to keep both.
+     *
+     * @default () => "import request from './request'"
+     */
+    clientImportTemplate?: ClientImportTemplate;
+    /**
+     * Type used for the `extra` argument of every generated request
+     * function — the object spread into the underlying client call as
+     * per-request overrides (headers, signal, `responseType`, ...).
+     *
+     * Defaults to `AxiosRequestConfig`, in which case each generated file
+     * also imports that type from `axios`. When using a custom client via
+     * `clientImportTemplate`, set this to that client's config type and
+     * make sure `clientImportTemplate` imports it, e.g.:
+     *
+     * ```ts
+     * clientImportTemplate: () => "import {request, type RequestConfig} from '../fetch'",
+     * clientConfigType: 'RequestConfig',
+     * ```
+     *
+     * @default 'AxiosRequestConfig'
+     */
+    clientConfigType?: string;
+    /**
+     * Whether to scaffold the default axios request client into
+     * `<output>/request.ts` (skipped when that file already exists).
+     *
+     * Defaults to `true`, and to `false` when `clientImportTemplate` is
+     * provided without an explicit `client` value.
+     *
+     * @default true
+     */
+    client?: boolean;
+}
+/** Combined configuration. */
+export type SyntheticalConfig = Partial<ApiConfig & {
+    components: OpenAPIV3.Document["components"];
+}>;
+/** Configuration. */
+export type Config = ApiConfig;
+/**
+ * Request configuration.
+ */
+export interface RequestConfig<Path extends string = string, ParamName extends string = string, QueryName extends string = string, RequestDataOptional extends boolean = boolean> {
+    /** Interface path, starting with `/` */
+    path: Path;
+    /** Request method */
+    method: Method;
+    /** Request headers, all headers except Content-Type */
+    requestHeaders: Record<string, string>;
+    /** Request body type */
+    requestBodyType: RequestBodyType;
+    /** Response body type */
+    responseBodyType: ResponseBodyType;
+    /** List of path parameter names */
+    paramNames: ParamName[];
+    /** List of query parameter names */
+    queryNames: QueryName[];
+    /** Whether request data is optional */
+    requestDataOptional: RequestDataOptional;
+    /** JSON Schema for request data (only effective when JSON Schema generation is enabled) */
+    requestDataJsonSchema: JSONSchema4;
+    /** JSON Schema for response data (only effective when JSON Schema generation is enabled) */
+    responseDataJsonSchema: JSONSchema4;
+    /** Request function name */
+    requestFunctionName: string;
+}
+/**
+ * Request parameters.
+ */
+export interface RequestFunctionParams extends RequestConfig {
+    /** Raw data */
+    rawData: Record<string, any>;
+    /** Request data, excluding file data */
+    data: Record<string, any>;
+    /** Whether there is file data */
+    hasFileData: boolean;
+    /** Request file data */
+    fileData: Record<string, any>;
+    /** All request data, including data and fileData */
+    allData: Record<string, any>;
+    /** Get FormData instance for all request data (including files) */
+    getFormData: () => FormData;
+}
+/** Additional parameters of the request function */
+export type RequestFunctionRestArgs<T extends Function> = T extends (payload: any, ...args: infer R) => any ? R : never;
+/** Property definition */
+export interface PropDefinition {
+    /** Property name */
+    name: string;
+    /** Required */
+    required: boolean;
+    /** Type */
+    type: JSONSchema4["type"];
+    /** Comment */
+    comment: string;
+    /** Whether the property is an array (used for multi-file upload fields) */
+    isArray?: boolean;
+    /** Allowed literal values for enum properties */
+    enum?: Array<string | number>;
+}
+/** Property definition list */
+export type PropDefinitions = PropDefinition[];
+/** Request function body generation template function */
+export interface RequestFunctionTemplateProps {
+    baseURL?: string;
+    requestFunctionName: string;
+    requestDataTypeName: string;
+    extendedInterfaceInfo: ExtendedInterface;
+    responseDataTypeName: string;
+}

package/dist/esm/types.mjs

@@ -0,0 +1,94 @@
+export * from "json-schema";
+
+/** Returns the client import snippet placed at the top of each generated file. */
+
+/** Interface definition */
+
+/** Category information */
+
+/** Request method */
+export var Method = /*#__PURE__*/function (Method) {
+  Method["GET"] = "GET";
+  Method["POST"] = "POST";
+  Method["PUT"] = "PUT";
+  Method["DELETE"] = "DELETE";
+  Method["HEAD"] = "HEAD";
+  Method["OPTIONS"] = "OPTIONS";
+  Method["PATCH"] = "PATCH";
+  return Method;
+}({});
+
+/** Required */
+export var Required = /*#__PURE__*/function (Required) {
+  Required["false"] = "0";
+  Required["true"] = "1";
+  return Required;
+}({});
+
+/** Request body type */
+export var RequestBodyType = /*#__PURE__*/function (RequestBodyType) {
+  RequestBodyType["query"] = "query";
+  RequestBodyType["form"] = "form";
+  RequestBodyType["json"] = "json";
+  RequestBodyType["text"] = "text";
+  RequestBodyType["file"] = "file";
+  RequestBodyType["raw"] = "raw";
+  RequestBodyType["none"] = "none";
+  return RequestBodyType;
+}({});
+
+/** Request path parameter type */
+export var RequestParamType = /*#__PURE__*/function (RequestParamType) {
+  RequestParamType["string"] = "string";
+  RequestParamType["number"] = "number";
+  return RequestParamType;
+}({});
+
+/** Request query parameter type */
+export var RequestQueryType = /*#__PURE__*/function (RequestQueryType) {
+  RequestQueryType["string"] = "string";
+  RequestQueryType["number"] = "number";
+  return RequestQueryType;
+}({});
+
+/** Request form item type */
+export var RequestFormItemType = /*#__PURE__*/function (RequestFormItemType) {
+  RequestFormItemType["text"] = "text";
+  RequestFormItemType["file"] = "file";
+  return RequestFormItemType;
+}({});
+
+/** Response body type */
+export var ResponseBodyType = /*#__PURE__*/function (ResponseBodyType) {
+  ResponseBodyType["json"] = "json";
+  ResponseBodyType["text"] = "text";
+  ResponseBodyType["xml"] = "xml";
+  ResponseBodyType["raw"] = "raw";
+  return ResponseBodyType;
+}({});
+
+/** Extended interface definition */
+
+/**
+ * Generator configuration for one OpenAPI source.
+ */
+
+/** Combined configuration. */
+
+/** Configuration. */
+
+/**
+ * Request configuration.
+ */
+
+/**
+ * Request parameters.
+ */
+
+/** Additional parameters of the request function */
+
+/** Property definition */
+
+/** Property definition list */
+
+/** Request function body generation template function */

package/dist/esm/utils/console.d.mts

@@ -0,0 +1,16 @@
+/** Log a plain message. */
+export declare function log(message?: any, ...args: any[]): void;
+/** Log an error message. */
+export declare function error(message?: any, ...args: any[]): void;
+/** Log an info message. */
+export declare function info(message?: any, ...args: any[]): void;
+/** Log a warning message. */
+export declare function warn(message?: any, ...args: any[]): void;
+/** Log a soft tip message with a prefix icon. */
+export declare function tips(message?: any, ...args: any[]): void;
+/** Log a success message. */
+export declare function success(message?: any, ...args: any[]): void;
+/** Print tabular data as a table. */
+export declare function table(tabularData: any, properties?: ReadonlyArray<string>): void;
+/** Print a separator line (or a blank line). */
+export declare function line(blank?: boolean): void;

package/dist/esm/utils/console.mjs

@@ -0,0 +1,65 @@
+import chalk from "chalk";
+
+/** Log a plain message. */
+export function log(message) {
+  var _console;
+  for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    args[_key - 1] = arguments[_key];
+  }
+  (_console = console).log.apply(_console, [message].concat(args));
+}
+
+/** Log an error message. */
+export function error(message) {
+  var _console2;
+  for (var _len2 = arguments.length, args = new Array(_len2 > 1 ? _len2 - 1 : 0), _key2 = 1; _key2 < _len2; _key2++) {
+    args[_key2 - 1] = arguments[_key2];
+  }
+  (_console2 = console).error.apply(_console2, [chalk.magenta(message)].concat(args));
+}
+
+/** Log an info message. */
+export function info(message) {
+  var _console3;
+  for (var _len3 = arguments.length, args = new Array(_len3 > 1 ? _len3 - 1 : 0), _key3 = 1; _key3 < _len3; _key3++) {
+    args[_key3 - 1] = arguments[_key3];
+  }
+  (_console3 = console).info.apply(_console3, [chalk.yellowBright(message)].concat(args));
+}
+
+/** Log a warning message. */
+export function warn(message) {
+  var _console4;
+  for (var _len4 = arguments.length, args = new Array(_len4 > 1 ? _len4 - 1 : 0), _key4 = 1; _key4 < _len4; _key4++) {
+    args[_key4 - 1] = arguments[_key4];
+  }
+  (_console4 = console).warn.apply(_console4, [chalk.blue(message)].concat(args));
+}
+
+/** Log a soft tip message with a prefix icon. */
+export function tips(message) {
+  var _console5;
+  for (var _len5 = arguments.length, args = new Array(_len5 > 1 ? _len5 - 1 : 0), _key5 = 1; _key5 < _len5; _key5++) {
+    args[_key5 - 1] = arguments[_key5];
+  }
+  (_console5 = console).log.apply(_console5, [chalk.yellow("\uD83D\uDD08 ".concat(message, "\n"))].concat(args));
+}
+
+/** Log a success message. */
+export function success(message) {
+  var _console6;
+  for (var _len6 = arguments.length, args = new Array(_len6 > 1 ? _len6 - 1 : 0), _key6 = 1; _key6 < _len6; _key6++) {
+    args[_key6 - 1] = arguments[_key6];
+  }
+  (_console6 = console).log.apply(_console6, [chalk.cyan("\u2713 ".concat(message))].concat(args));
+}
+
+/** Print tabular data as a table. */
+export function table(tabularData, properties) {
+  console.table(tabularData, properties);
+}
+
+/** Print a separator line (or a blank line). */
+export function line(blank) {
+  console.log("\n".concat(!blank ? "-----------------------" : ""));
+}

package/dist/esm/utils/getOutputPath.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Resolve the output file path for a generated file.
+ */
+import { Config } from "../types.mjs";
+export declare const getOutputFilePath: (config: Config, file: string) => string;

package/dist/esm/utils/getOutputPath.mjs

@@ -0,0 +1,12 @@
+/**
+ * Resolve the output file path for a generated file.
+ */
+
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+import path from "path";
+export var getOutputFilePath = function getOutputFilePath(config, file) {
+  var _path$parse = path.parse(config.output || ""),
+    dir = _path$parse.dir,
+    name = _path$parse.name;
+  return path.join(dir, name, file);
+};

package/dist/esm/utils/helpers.d.mts

@@ -0,0 +1,65 @@
+import type { AppendOptions } from "form-data";
+import type { Config, RequestConfig, RequestFunctionParams } from "../types.mjs";
+/**
+ * Normalize user configuration into a config array and apply built-in
+ * defaults.
+ *
+ * Defaults:
+ * - `output` falls back to `src/api`.
+ * - `client` falls back to `true`, except when a custom
+ *   `clientImportTemplate` is provided without an explicit `client` value —
+ *   in that case the scaffolded client is skipped automatically, otherwise
+ *   the generated `request.ts` would be dead code (the generated file
+ *   imports the custom client instead).
+ *
+ * @param config Configuration
+ */
+export declare function defineConfig(config: Config | Config[]): Config[];
+export declare class FileData<T = any> {
+    /**
+     * Original file data.
+     */
+    private originalFileData;
+    /**
+     * Options.
+     */
+    private options;
+    /**
+     * File data helper class, unified file upload for web, mini-program and other platforms.
+     *
+     * @param originalFileData Original file data
+     * @param options If using internal getFormData, options will be used by it
+     */
+    constructor(originalFileData: T, options?: AppendOptions);
+    /**
+     * Get original file data.
+     *
+     * @returns Original file data
+     */
+    getOriginalFileData(): T;
+    /**
+     * Get options.
+     */
+    getOptions(): AppendOptions | undefined;
+}
+/**
+ * Parse request data, separating normal data and file data from request data.
+ *
+ * @param [requestData] Request data to parse
+ * @returns Object containing normal data (data) and file data (fileData), when data and fileData are empty objects, it means no such data exists
+ */
+export declare function parseRequestData(requestData?: any): {
+    data: any;
+    fileData: any;
+};
+/**
+ * Prepare parameters to be passed to the request function.
+ */
+export declare function prepare(requestConfig: RequestConfig, requestData: any): RequestFunctionParams;
+/**
+ * Execute async function queue sequentially
+ * @param fns
+ * @param results
+ * @returns
+ */
+export declare const asyncFnArrayOrderRun: <T = any>(fns: (() => Promise<T>)[], results?: T[]) => Promise<T[]>;