@moluoxixi/ajax-package 0.0.58

package/README.md

@@ -0,0 +1,46 @@
+# @moluoxixi/ajax-package
+
+基于 `axios` 的可复用 HTTP 客户端包。
+
+## 使用
+
+```ts
+import { getHttpService } from '@moluoxixi/ajax-package'
+
+const session = {
+  token: 'token-from-app',
+}
+
+const http = getHttpService({
+  baseURL: 'https://api.example.com',
+  token: {
+    getToken: () => session.token,
+    headerName: 'Authorization',
+    formatToken: token => `Bearer ${token}`,
+  },
+})
+
+const users = await http.get('/users')
+```
+
+## 响应契约
+
+默认返回 `response.data`，不会假设业务响应结构。需要解析业务包裹层时显式声明契约：
+
+```ts
+const http = getHttpService({
+  responseContract: {
+    codePath: 'code',
+    messagePath: 'message',
+    dataPath: 'data.items',
+    isSuccess: code => code === 0,
+  },
+})
+```
+
+## 业务剥离范围
+
+- 不导出 Vue 插件，不写入 `window.$http`。
+- 不依赖 Element Plus、弹窗组件或通知组件。
+- 不内置登录页跳转、localStorage token 读取、系统异常弹窗和特定业务错误码。
+- HTTP 错误、axios 错误和响应契约错误都会继续抛出，调用方自行决定 UI 副作用。

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { AxiosInstance, AxiosRequestConfig, InternalAxiosRequestConfig, AxiosResponse, AxiosError } from 'axios';
+
+interface TokenConfig {
+    /**
+     * 每次请求前按需读取 token；未返回 token 时不会写入任何认证头。
+     */
+    getToken: () => Promise<string | null | undefined> | string | null | undefined;
+    /**
+     * 认证头名称默认使用通用的 Authorization，不保留旧包的业务 Token 头约定。
+     */
+    headerName?: string;
+    /**
+     * 调用方负责决定 Bearer、Token 或其他格式，工具包不猜测业务协议。
+     */
+    formatToken?: (token: string) => string;
+}
+interface BaseHttpClientConfig extends AxiosRequestConfig {
+    token?: TokenConfig;
+    onRequest?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>;
+    onResponse?: (response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>;
+    onResponseError?: (error: AxiosError) => void | Promise<void>;
+    onTimeout?: (error: AxiosError) => void | Promise<void>;
+    onUnauthorized?: (error: AxiosError) => void | Promise<void>;
+}
+interface HttpResponseContract {
+    /**
+     * 业务状态码路径；未配置时不做业务成功/失败判断。
+     */
+    codePath?: string;
+    /**
+     * 错误消息路径；只有业务失败时才会读取。
+     */
+    messagePath?: string;
+    /**
+     * 数据路径；配置后路径缺失会直接抛错，避免返回伪成功的 undefined。
+     */
+    dataPath?: string;
+    /**
+     * 判断业务响应是否成功；不提供时只做数据路径提取，不判断 code。
+     */
+    isSuccess?: (code: unknown, body: unknown, response: AxiosResponse) => boolean;
+}
+interface BaseApiConfig extends BaseHttpClientConfig {
+    responseContract?: HttpResponseContract;
+}
+type HttpRequestConfig = AxiosRequestConfig;
+type HttpClientInstance = AxiosInstance;
+
+type AwaitedPromiseTuple<Requests extends readonly Promise<unknown>[]> = {
+    readonly [Index in keyof Requests]: Awaited<Requests[Index]>;
+};
+declare class BaseHttpClient {
+    readonly instance: HttpClientInstance;
+    private readonly token;
+    private readonly onRequest;
+    private readonly onResponse;
+    private readonly onResponseError;
+    private readonly onTimeout;
+    private readonly onUnauthorized;
+    constructor(config?: BaseHttpClientConfig);
+    protected processRequestConfig(config: InternalAxiosRequestConfig): Promise<InternalAxiosRequestConfig>;
+    protected processResponseConfig<R>(response: AxiosResponse<R>): Promise<R>;
+    protected processResponseError(error: AxiosError): Promise<void>;
+    private setupInterceptors;
+    /**
+     * 所有快捷方法最终都走 request，便于子类在单点扩展请求语义。
+     */
+    request<R = unknown>(config: AxiosRequestConfig): Promise<R>;
+    get<R = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<R>;
+    post<R = unknown, D = unknown>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
+    put<R = unknown, D = unknown>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
+    delete<R = unknown>(url: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<R>;
+    all<const Requests extends readonly Promise<unknown>[]>(requests: Requests): Promise<AwaitedPromiseTuple<Requests>>;
+    all<R = unknown>(requests: readonly AxiosRequestConfig[]): Promise<R[]>;
+    all<R = unknown>(requests: readonly (AxiosRequestConfig | Promise<R>)[]): Promise<R[]>;
+    uploadFile<R = unknown>(url: string, file: Blob, config?: AxiosRequestConfig<FormData>): Promise<R>;
+    downloadFile(blob: Blob, filename: string): void;
+}
+
+declare class BaseApi extends BaseHttpClient {
+    private readonly responseContract;
+    constructor(config?: BaseApiConfig);
+    protected processResponseConfig<R = unknown>(response: AxiosResponse<R>): Promise<R>;
+}
+
+interface HttpResponseErrorOptions {
+    body: unknown;
+    code: unknown;
+    response: AxiosResponse;
+}
+declare class HttpResponseError extends Error {
+    readonly body: unknown;
+    readonly code: unknown;
+    readonly response: AxiosResponse;
+    constructor(message: string, options: HttpResponseErrorOptions);
+}
+
+declare function createHttpService(config?: BaseApiConfig): BaseApi;
+declare function getHttpService(config?: BaseApiConfig): BaseApi;
+
+/**
+ * 严格解析点号路径；调用方声明了路径，就必须让响应满足该契约。
+ */
+declare function getValueByPath(source: unknown, path: string | undefined): unknown;
+
+export { BaseApi, type BaseApiConfig, BaseApi as BaseApiDefault, BaseHttpClient, type BaseHttpClientConfig, BaseHttpClient as BaseHttpClientDefault, type HttpClientInstance, type HttpRequestConfig, type HttpResponseContract, HttpResponseError, type TokenConfig, createHttpService, getHttpService as default, getHttpService, getValueByPath };

package/dist/index.js

@@ -0,0 +1,201 @@
+// src/BaseHttpClient.ts
+import axios, { AxiosHeaders } from "axios";
+function isTimeoutError(error) {
+  return error.code === "ECONNABORTED" || error.code === "ETIMEDOUT";
+}
+function setRequestHeader(config, name, value) {
+  const headers = AxiosHeaders.from(config.headers);
+  headers.set(name, value);
+  config.headers = headers;
+}
+var BaseHttpClient = class {
+  instance;
+  token;
+  onRequest;
+  onResponse;
+  onResponseError;
+  onTimeout;
+  onUnauthorized;
+  constructor(config = {}) {
+    const {
+      token,
+      onRequest,
+      onResponse,
+      onResponseError,
+      onTimeout,
+      onUnauthorized,
+      ...axiosConfig
+    } = config;
+    this.token = token;
+    this.onRequest = onRequest;
+    this.onResponse = onResponse;
+    this.onResponseError = onResponseError;
+    this.onTimeout = onTimeout;
+    this.onUnauthorized = onUnauthorized;
+    this.instance = axios.create(axiosConfig);
+    this.setupInterceptors();
+  }
+  async processRequestConfig(config) {
+    if (!this.token) {
+      return config;
+    }
+    const token = await this.token.getToken();
+    if (token == null || token === "") {
+      return config;
+    }
+    const headerName = this.token.headerName ?? "Authorization";
+    const headerValue = this.token.formatToken?.(token) ?? token;
+    setRequestHeader(config, headerName, headerValue);
+    return config;
+  }
+  async processResponseConfig(response) {
+    const processedResponse = this.onResponse ? await this.onResponse(response) : response;
+    return processedResponse.data;
+  }
+  async processResponseError(error) {
+    if (error.response?.status === 401) {
+      await this.onUnauthorized?.(error);
+    }
+    if (isTimeoutError(error)) {
+      await this.onTimeout?.(error);
+    }
+    await this.onResponseError?.(error);
+  }
+  setupInterceptors() {
+    this.instance.interceptors.request.use(
+      async (config) => {
+        const processedConfig = await this.processRequestConfig(config);
+        return this.onRequest ? await this.onRequest(processedConfig) : processedConfig;
+      },
+      (error) => Promise.reject(error)
+    );
+    this.instance.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        await this.processResponseError(error);
+        return Promise.reject(error);
+      }
+    );
+  }
+  /**
+   * 所有快捷方法最终都走 request，便于子类在单点扩展请求语义。
+   */
+  async request(config) {
+    const response = await this.instance.request(config);
+    return await this.processResponseConfig(response);
+  }
+  async get(url, params, config) {
+    return await this.request({ ...config, method: "get", params, url });
+  }
+  async post(url, data, config) {
+    return await this.request({ ...config, data, method: "post", url });
+  }
+  async put(url, data, config) {
+    return await this.request({ ...config, data, method: "put", url });
+  }
+  async delete(url, params, config) {
+    return await this.request({ ...config, method: "delete", params, url });
+  }
+  async all(requests) {
+    const tasks = requests.map((request) => {
+      return request instanceof Promise ? request : this.request(request);
+    });
+    return await Promise.all(tasks);
+  }
+  async uploadFile(url, file, config) {
+    const formData = new FormData();
+    formData.append("file", file);
+    return await this.post(url, formData, config);
+  }
+  downloadFile(blob, filename) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      throw new TypeError("[ajax-package] downloadFile requires a browser runtime");
+    }
+    const url = window.URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    try {
+      link.click();
+    } finally {
+      link.remove();
+      window.URL.revokeObjectURL(url);
+    }
+  }
+};
+var BaseHttpClient_default = BaseHttpClient;
+
+// src/errors.ts
+var HttpResponseError = class extends Error {
+  body;
+  code;
+  response;
+  constructor(message, options) {
+    super(message);
+    this.name = "HttpResponseError";
+    this.body = options.body;
+    this.code = options.code;
+    this.response = options.response;
+  }
+};
+
+// src/path.ts
+import { readValueByPath } from "@moluoxixi/core";
+function getValueByPath(source, path) {
+  return readValueByPath(source, path, {
+    createMissingPathError: (missingPath) => new Error(`[ajax-package] response path not found: ${missingPath}`),
+    strict: true
+  });
+}
+
+// src/BaseApi.ts
+function resolveResponseMessage(contract, body, code) {
+  if (contract.messagePath) {
+    const message = getValueByPath(body, contract.messagePath);
+    return typeof message === "string" ? message : String(message);
+  }
+  return `HTTP response contract rejected code: ${String(code)}`;
+}
+var BaseApi = class extends BaseHttpClient_default {
+  responseContract;
+  constructor(config = {}) {
+    const { responseContract, ...baseConfig } = config;
+    super(baseConfig);
+    this.responseContract = responseContract;
+  }
+  async processResponseConfig(response) {
+    const body = await super.processResponseConfig(response);
+    if (!this.responseContract) {
+      return body;
+    }
+    const code = this.responseContract.codePath ? getValueByPath(body, this.responseContract.codePath) : void 0;
+    if (this.responseContract.isSuccess && !this.responseContract.isSuccess(code, body, response)) {
+      throw new HttpResponseError(
+        resolveResponseMessage(this.responseContract, body, code),
+        { body, code, response }
+      );
+    }
+    return getValueByPath(body, this.responseContract.dataPath);
+  }
+};
+var BaseApi_default = BaseApi;
+
+// src/factory.ts
+function createHttpService(config = {}) {
+  return new BaseApi_default(config);
+}
+function getHttpService(config = {}) {
+  return createHttpService(config);
+}
+export {
+  BaseApi,
+  BaseApi_default as BaseApiDefault,
+  BaseHttpClient,
+  BaseHttpClient_default as BaseHttpClientDefault,
+  HttpResponseError,
+  createHttpService,
+  getHttpService as default,
+  getHttpService,
+  getValueByPath
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@moluoxixi/ajax-package",
+  "type": "module",
+  "version": "0.0.58",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moluoxixi/utils.git",
+    "directory": "packages/AjaxPackage"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist/**/*.d.ts",
+    "dist/**/*.js"
+  ],
+  "dependencies": {
+    "axios": "^1.16.1",
+    "@moluoxixi/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}