@devbie/apits 0.0.0-stage → 1.0.0

package/dist/cjs/types.d.ts

@@ -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/cjs/types.js

@@ -0,0 +1,90 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+__export(types_exports, {
+  Method: () => Method,
+  RequestBodyType: () => RequestBodyType,
+  RequestFormItemType: () => RequestFormItemType,
+  RequestParamType: () => RequestParamType,
+  RequestQueryType: () => RequestQueryType,
+  Required: () => Required,
+  ResponseBodyType: () => ResponseBodyType
+});
+module.exports = __toCommonJS(types_exports);
+__reExport(types_exports, require("json-schema"), module.exports);
+var Method = /* @__PURE__ */ ((Method2) => {
+  Method2["GET"] = "GET";
+  Method2["POST"] = "POST";
+  Method2["PUT"] = "PUT";
+  Method2["DELETE"] = "DELETE";
+  Method2["HEAD"] = "HEAD";
+  Method2["OPTIONS"] = "OPTIONS";
+  Method2["PATCH"] = "PATCH";
+  return Method2;
+})(Method || {});
+var Required = /* @__PURE__ */ ((Required2) => {
+  Required2["false"] = "0";
+  Required2["true"] = "1";
+  return Required2;
+})(Required || {});
+var RequestBodyType = /* @__PURE__ */ ((RequestBodyType2) => {
+  RequestBodyType2["query"] = "query";
+  RequestBodyType2["form"] = "form";
+  RequestBodyType2["json"] = "json";
+  RequestBodyType2["text"] = "text";
+  RequestBodyType2["file"] = "file";
+  RequestBodyType2["raw"] = "raw";
+  RequestBodyType2["none"] = "none";
+  return RequestBodyType2;
+})(RequestBodyType || {});
+var RequestParamType = /* @__PURE__ */ ((RequestParamType2) => {
+  RequestParamType2["string"] = "string";
+  RequestParamType2["number"] = "number";
+  return RequestParamType2;
+})(RequestParamType || {});
+var RequestQueryType = /* @__PURE__ */ ((RequestQueryType2) => {
+  RequestQueryType2["string"] = "string";
+  RequestQueryType2["number"] = "number";
+  return RequestQueryType2;
+})(RequestQueryType || {});
+var RequestFormItemType = /* @__PURE__ */ ((RequestFormItemType2) => {
+  RequestFormItemType2["text"] = "text";
+  RequestFormItemType2["file"] = "file";
+  return RequestFormItemType2;
+})(RequestFormItemType || {});
+var ResponseBodyType = /* @__PURE__ */ ((ResponseBodyType2) => {
+  ResponseBodyType2["json"] = "json";
+  ResponseBodyType2["text"] = "text";
+  ResponseBodyType2["xml"] = "xml";
+  ResponseBodyType2["raw"] = "raw";
+  return ResponseBodyType2;
+})(ResponseBodyType || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Method,
+  RequestBodyType,
+  RequestFormItemType,
+  RequestParamType,
+  RequestQueryType,
+  Required,
+  ResponseBodyType,
+  ...require("json-schema")
+});

package/dist/cjs/utils/console.d.ts

@@ -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/cjs/utils/console.js

@@ -0,0 +1,79 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/console.ts
+var console_exports = {};
+__export(console_exports, {
+  error: () => error,
+  info: () => info,
+  line: () => line,
+  log: () => log,
+  success: () => success,
+  table: () => table,
+  tips: () => tips,
+  warn: () => warn
+});
+module.exports = __toCommonJS(console_exports);
+var import_chalk = __toESM(require("chalk"));
+function log(message, ...args) {
+  console.log(message, ...args);
+}
+function error(message, ...args) {
+  console.error(import_chalk.default.magenta(message), ...args);
+}
+function info(message, ...args) {
+  console.info(import_chalk.default.yellowBright(message), ...args);
+}
+function warn(message, ...args) {
+  console.warn(import_chalk.default.blue(message), ...args);
+}
+function tips(message, ...args) {
+  console.log(import_chalk.default.yellow(`🔈 ${message}
+`), ...args);
+}
+function success(message, ...args) {
+  console.log(import_chalk.default.cyan(`✓ ${message}`), ...args);
+}
+function table(tabularData, properties) {
+  console.table(tabularData, properties);
+}
+function line(blank) {
+  console.log(`
+${!blank ? "-----------------------" : ""}`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  error,
+  info,
+  line,
+  log,
+  success,
+  table,
+  tips,
+  warn
+});

package/dist/cjs/utils/getOutputPath.d.ts

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

package/dist/cjs/utils/getOutputPath.js

@@ -0,0 +1,43 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/getOutputPath.ts
+var getOutputPath_exports = {};
+__export(getOutputPath_exports, {
+  getOutputFilePath: () => getOutputFilePath
+});
+module.exports = __toCommonJS(getOutputPath_exports);
+var import_path = __toESM(require("path"));
+var getOutputFilePath = (config, file) => {
+  const { dir, name } = import_path.default.parse(config.output || "");
+  return import_path.default.join(dir, name, file);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getOutputFilePath
+});

package/dist/cjs/utils/helpers.d.ts

@@ -0,0 +1,65 @@
+import type { AppendOptions } from "form-data";
+import type { Config, RequestConfig, RequestFunctionParams } from "../types.js";
+/**
+ * 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[]>;