fzkit 0.1.0

package/dist/create-http-client-BoM9-_Ty.d.mts

@@ -0,0 +1,265 @@
+import { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+//#region src/http-client/types/token.d.ts
+/**
+ * token 详细信息，用于主动刷新判断。
+ */
+interface AccessTokenDetail {
+  token: string;
+  expiresAt: Date | string | number;
+}
+/**
+ * getAccessToken 的返回值类型，兼容旧版纯字符串返回。
+ */
+type AccessTokenResult = string | AccessTokenDetail | null;
+//#endregion
+//#region src/http-client/token-refresh-manager.d.ts
+/** @internal 冷却期内跳过刷新时的哨兵值，不对业务侧开放。 */
+declare const REFRESH_SKIPPED: unique symbol;
+declare class TokenRefreshManager {
+  private refreshingPromise;
+  private lastRefreshTime;
+  private readonly cooldownMs;
+  constructor(cooldownMs?: number);
+  /** @internal 供 createHttpClient 内部调用。 */
+  runRefresh(task: () => Promise<AccessTokenResult>): Promise<AccessTokenResult | typeof REFRESH_SKIPPED>;
+}
+//#endregion
+//#region src/http-client/types/common.d.ts
+/**
+ * onBusinessResponse 的返回值类型。
+ * - void：继续正常流程（表示成功）
+ * - Error：抛出错误（表示业务失败）
+ * - AxiosResponse：用完整响应形态（status/data/headers/config/statusText）替换原响应，不会二次触发 onBusinessResponse
+ */
+type BusinessResponseResult = void | Error | AxiosResponse;
+/**
+ * 错误上下文，传递给 onError 钩子。
+ */
+interface ErrorContext {
+  /**
+   * 错误来源类型。
+   */
+  type: 'request' | 'refresh';
+}
+/**
+ * 自定义错误消息。
+ */
+interface ErrorMessages {
+  refreshTokenExpired?: string;
+  loginExpired?: string;
+}
+//#endregion
+//#region src/http-client/types/http-client-options.d.ts
+/**
+ * 请求合并配置。
+ */
+interface DedupePolicy {
+  /** 是否启用请求合并。默认 false。仅合并 GET 请求。 */
+  enabled?: boolean;
+  /**
+   * 自定义合并 key 生成器。
+   * 默认：`method:baseURL:url:stableParams:headersProviderSnapshot`
+   *
+   * 默认实现仅纳入 `headersProvider()` 返回值快照（`config.__dedupeProviderHeaders`），
+   * 不纳入调用方 `config.headers` 或工厂注入的 token。
+   * params 稳定序列化支持 plain object / array / URLSearchParams / Date / Map / Set；
+   * 循环引用会抛错，避免误合并。
+   */
+  generateKey?: (config: AxiosRequestConfig) => string;
+}
+/**
+ * 请求级合并配置。
+ * 仅允许覆盖 enabled；generateKey 只能在客户端级配置。
+ */
+interface RequestDedupePolicy {
+  /** 是否启用请求合并。覆盖客户端级 enabled。 */
+  enabled?: boolean;
+}
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    /**
+     * 请求级合并策略。
+     * 仅可覆盖 enabled，不能修改 generateKey。
+     * 仅 createHttpClient 创建的实例生效。
+     */
+    dedupePolicy?: RequestDedupePolicy;
+  }
+}
+/**
+ * 重试策略配置。
+ */
+interface RetryPolicy {
+  /** 最大重试次数（不含首次请求）。默认 0（不重试）。 */
+  maxRetries?: number;
+  /**
+   * 判断是否需要重试。
+   * 默认：网络错误（无 response）或 5xx 状态码时重试；用户取消不重试。
+   */
+  shouldRetry?: (error: unknown, retryCount: number) => boolean;
+  /**
+   * 计算重试延迟（毫秒）。
+   * 默认：指数退避，公式 `1000 * 2^retryCount`，上限 30 秒。
+   * 返回非有限数（NaN/Infinity）或负数时，按 0ms 处理。
+   * shouldRetry / retryDelay 抛错会停止重试，并进入 onError({ type: "request" })。
+   */
+  retryDelay?: (retryCount: number) => number;
+}
+/**
+ * 创建 HTTP 客户端时可传入的配置。
+ *
+ * @typeParam T - getAccessToken / refreshAccessToken 的统一返回类型，
+ *   默认为 `AccessTokenResult`。当 T 为 `AccessTokenDetail` 时启用主动刷新。
+ */
+interface HttpClientOptions<T extends AccessTokenResult = AccessTokenResult> {
+  /**
+   * 透传给 axios.create 的初始化配置。
+   */
+  axiosConfig: AxiosRequestConfig;
+  /**
+   * 获取当前 access token。
+   *
+   * 返回 `string` 时仅注入 token，不做主动刷新判断。
+   * 返回 `AccessTokenDetail` 时，会在 token 即将过期前主动触发刷新。
+   */
+  getAccessToken: () => T | Promise<T>;
+  /**
+   * access token 注入到请求头时使用的字段名。
+   * 默认 `Authorization`。
+   */
+  accessTokenHeaderName?: string;
+  /**
+   * access token 的前缀。
+   * 默认 `Bearer`。
+   */
+  accessTokenPrefix?: string;
+  /**
+   * 刷新失败判定的业务 code 列表。
+   *
+   * 仅用于 `defaultIsRefreshFailure`：当 refresh 请求响应体存在 `data.code`
+   * 且命中该列表时，视为刷新鉴权失败。
+   *
+   * 不会影响普通业务请求的鉴权识别；更通用的入口是 `isRefreshFailure`。
+   * 默认假设响应体形状为 `{ code?: number }`。
+   */
+  refreshFailureCodes?: number[];
+  /**
+   * 通用重试策略。
+   * 默认不重试（maxRetries: 0）。
+   */
+  retryPolicy?: RetryPolicy;
+  /**
+   * 请求合并策略。
+   * 默认关闭（enabled: false）。
+   */
+  dedupePolicy?: DedupePolicy;
+  /**
+   * 运行时动态 headers 提供者。
+   *
+   * 每次请求时调用，返回的 headers 会合并到请求中。
+   * 支持同步或异步返回。
+   *
+   * 典型场景：
+   * - 请求追踪：`{ 'x-trace-id': crypto.randomUUID() }`
+   * - 业务标识：从 store 读取 `{ 'x-tenant-id': tenantId }`
+   *
+   * 注意：
+   * - 首次请求时，返回的 headers 会覆盖默认注入的 headers（如 Authorization）
+   * - 鉴权刷新后的重试请求中，新 token 优先，不会被 headersProvider 的旧 Authorization 覆盖
+   */
+  headersProvider?: () => Record<string, string> | Promise<Record<string, string>>;
+  /**
+   * 触发刷新流程的 HTTP 状态码。
+   * 默认 `401`。
+   */
+  unauthorizedStatusCode?: number;
+  /**
+   * 自定义错误消息，覆盖内部默认值。
+   */
+  errorMessages?: ErrorMessages;
+  /**
+   * 判断刷新 token 请求本身是否已经失败到需要退出登录。
+   *
+   * 默认行为：
+   * - 非 AxiosError（编程错误 / 业务自定义 Error）不视为刷新鉴权失败
+   * - AxiosError 无 response（网络错误）或状态码 >= 500 时不视为刷新失败
+   * - 状态码 === unauthorizedStatusCode 时视为刷新失败
+   * - 响应 data.code 在 refreshFailureCodes 列表中时视为刷新鉴权失败
+   *
+   * 若业务需要“refresh 抛 Error 即登出”，请自定义该函数。
+   */
+  isRefreshFailure?: (error: unknown) => boolean;
+  /**
+   * 自定义刷新逻辑，返回类型必须与 getAccessToken 一致。
+   *
+   * 库不缓存 token。若返回 AccessTokenDetail，业务必须把新 token / expiresAt
+   * 写回 getAccessToken 使用的数据源，后续请求才会读到新过期时间。
+   */
+  refreshAccessToken?: () => T | Promise<T>;
+  /**
+   * 不触发 refresh token 流程的请求路径列表。
+   *
+   * 仅 exact / prefix 匹配，不是任意子串 includes，也不做中间段滑动匹配。
+   * 例如配置 `/auth` 会匹配 `/auth`、`/auth/login`，
+   * 但不会匹配 `/user/auth-history`、`/authorization`、`/api/auth/login`。
+   */
+  skipRefreshUrls?: string[];
+  /**
+   * 提前刷新的毫秒数，默认 0（不提前刷新）。
+   * 设置为大于 0 的值时，会在 token 即将过期前主动触发刷新。
+   */
+  refreshBufferMs?: number;
+  /**
+   * 刷新 token 后的冷却期（毫秒）。
+   * 在冷却期内收到的 401 请求会跳过刷新，直接使用新 token 重试。
+   * 用于处理刷新完成后，旧请求陆续返回 401 的并发场景。
+   * 默认 15000（15 秒）。
+   */
+  refreshCooldownMs?: number;
+  /**
+   * 外部传入的 TokenRefreshManager 实例。
+   * 用于多个客户端共享同一鉴权域的 refresh / 冷却状态。
+   * 不传则自动创建独立实例。
+   *
+   * 共享 manager 时：
+   * - 一次合并 refresh 事务的鉴权失败只会触发一次 onAuthFailure
+   * - 使用发起该次 refresh 的 client 回调
+   * - 建议共享 client 使用同一 token 数据源与等价 logout 行为
+   * - 外部 manager 的 cooldown 由构造参数决定；client 的 refreshCooldownMs 不会回写已有 manager
+   */
+  refreshManager?: TokenRefreshManager;
+  /**
+   * 通过业务响应判断是否需要刷新 token。
+   */
+  shouldRefreshByResponse?: (response: AxiosResponse<unknown>) => boolean;
+  /**
+   * 登录失效后的统一收尾回调。
+   */
+  onAuthFailure?: (error?: unknown) => void | Promise<void>;
+  /**
+   * 业务响应拦截器。
+   * - 返回 void：继续正常流程（表示成功）
+   * - 返回 Error：抛出错误（表示业务失败）
+   * - throw Error / 非 Error：与返回 Error 一样，统一进入 onError({ type: "request" })
+   * - 返回完整 AxiosResponse 形态：用新响应替换原响应，不会二次触发 onBusinessResponse
+   * - 可以是 async
+   */
+  onBusinessResponse?: (response: AxiosResponse<unknown>) => BusinessResponseResult | Promise<BusinessResponseResult>;
+  /**
+   * 全局错误钩子。
+   * - 返回 Error：用新错误替换原错误
+   * - 返回 void：继续抛出原错误
+   * - 可以是 async
+   *
+   * error 类型为 AxiosError | Error：
+   * - 请求失败时为 AxiosError，可通过 axios.isAxiosError(error) 收敛访问 response/config
+   * - 刷新失败时可能为 AxiosError 或业务侧抛出的任意 Error
+   * - 登录过期等内部构造的错误为普通 Error
+   */
+  onError?: (error: AxiosError | Error, context: ErrorContext) => AxiosError | Error | void | Promise<AxiosError | Error | void>;
+}
+//#endregion
+//#region src/http-client/create-http-client.d.ts
+declare const createHttpClient: <T extends AccessTokenResult = AccessTokenResult>(options: HttpClientOptions<T>) => AxiosInstance;
+//#endregion
+export { RetryPolicy as a, ErrorMessages as c, AccessTokenResult as d, RequestDedupePolicy as i, TokenRefreshManager as l, DedupePolicy as n, BusinessResponseResult as o, HttpClientOptions as r, ErrorContext as s, createHttpClient as t, AccessTokenDetail as u };
+//# sourceMappingURL=create-http-client-BoM9-_Ty.d.mts.map

package/dist/create-http-client-BoM9-_Ty.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-http-client-BoM9-_Ty.d.mts","names":[],"sources":["../src/http-client/types/token.ts","../src/http-client/token-refresh-manager.ts","../src/http-client/types/common.ts","../src/http-client/types/http-client-options.ts","../src/http-client/create-http-client.ts"],"mappings":";;;;;UAGiB;EACf;EACA,WAAW;;;;;KAMD,6BAA6B;;;;cCR5B;cAEA;UACH;UACA;mBACS;cAEL;;EAKN,WACJ,YAAY,QAAQ,qBACnB,QAAQ,2BAA2B;;;;;;;;;;KCe5B,gCAAgC,QAAQ;;;;UAKnC;;;;EAIf;;;;;UAMe;EACf;EACA;;;;;;;UCzCe;;EAEf;;;;;;;;;;EAWA,eAAe,QAAQ;;;;;;UAOR;;EAEf;;;YAMU;;;;;;IAMR,eAAe;;;;;;UAOF;;EAEf;;;;;EAMA,eAAe,gBAAgB;;;;;;;EAQ/B,cAAc;;;;;;;;UASC,kBAAkB,UAAU,oBAAoB;;;;EAI/D,aAAa;;;;;;;EAUb,sBAAsB,IAAI,QAAQ;;;;;EAMlC;;;;;EAMA;;;;;;;;;;EAaA;;;;;EAMA,cAAc;;;;;EAMd,eAAe;;;;;;;;;;;;;;;EAgBf,wBAAwB,yBAAyB,QAAQ;;;;;EAMzD;;;;EAKA,gBAAgB;;;;;;;;;;;;EAahB,oBAAoB;;;;;;;EAUpB,2BAA2B,IAAI,QAAQ;;;;;;;;EASvC;;;;;EAMA;;;;;;;EAQA;;;;;;;;;;;;EAaA,iBAAiB;;;;EAKjB,2BAA2B,UAAU;;;;EAOrC,iBAAiB,2BAA2B;;;;;;;;;EAU5C,sBACE,UAAU,2BACP,yBAAyB,QAAQ;;;;;;;;;;;;EAatC,WACE,OAAO,aAAa,OACpB,SAAS,iBACN,aAAa,eAAe,QAAQ,aAAa;;;;cC7O3C,mBAAoB,UAAU,oBAAoB,mBAC7D,SAAS,kBAAkB,OAC1B"}