create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/api/enums/query.ts

@@ -0,0 +1,82 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import { fnResolveEnumCatalogScope } from './scope'
+import type {
+  IEnumCatalog,
+  IEnumCatalogScope,
+  IEnumCatalogSource,
+  TEnumCatalogScopeInput,
+} from './types'
+
+const arrEnumCatalogQueryRoot: readonly ['enumCatalog'] = ['enumCatalog']
+const nEnumCatalogStaleTimeMs = 5 * 60_000
+const nEnumCatalogGcTimeMs = 30 * 60_000
+
+/** 返回一个语言对应的稳定枚举目录查询 Key。 */
+export function fnEnumCatalogQueryKey(
+  objScopeInput: TEnumCatalogScopeInput
+): readonly ['enumCatalog', IEnumCatalogScope] {
+  return ['enumCatalog', fnResolveEnumCatalogScope(objScopeInput)]
+}
+
+/** 创建完整枚举目录的 QueryClient 查询配置。 */
+export function fnEnumCatalogQueryOptions(
+  objSource: IEnumCatalogSource,
+  objScopeInput: TEnumCatalogScopeInput
+) {
+  const objScope = fnResolveEnumCatalogScope(objScopeInput)
+  return queryOptions({
+    queryKey: fnEnumCatalogQueryKey(objScope),
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnLoadCatalog({
+        objScope,
+        objSignal,
+        strLocale: objScope.strLocale,
+      }),
+    staleTime: nEnumCatalogStaleTimeMs,
+    gcTime: nEnumCatalogGcTimeMs,
+  })
+}
+
+/** 在路由 Loader 或应用启动阶段确保指定语言目录已加载。 */
+export function fnEnsureEnumCatalog(
+  objQueryClient: QueryClient,
+  objSource: IEnumCatalogSource,
+  objScopeInput: TEnumCatalogScopeInput = 'zh-CN'
+) {
+  return objQueryClient.ensureQueryData(
+    fnEnumCatalogQueryOptions(objSource, objScopeInput)
+  )
+}
+
+/** 从 QueryClient 同步读取指定语言已缓存的完整枚举目录。 */
+export function fnGetCachedEnumCatalog(
+  objQueryClient: QueryClient,
+  objScopeInput: TEnumCatalogScopeInput = 'zh-CN'
+): IEnumCatalog | undefined {
+  return objQueryClient.getQueryData<IEnumCatalog>(
+    fnEnumCatalogQueryKey(objScopeInput)
+  )
+}
+
+/** 枚举维护完成后统一失效一个语言或全部语言的目录缓存。 */
+export function fnInvalidateEnumCatalog(
+  objQueryClient: QueryClient,
+  objScopeInput?: TEnumCatalogScopeInput
+) {
+  if (!objScopeInput) {
+    return objQueryClient.invalidateQueries({
+      queryKey: arrEnumCatalogQueryRoot,
+    })
+  }
+
+  if (typeof objScopeInput === 'string') {
+    return objQueryClient.invalidateQueries({
+      queryKey: [arrEnumCatalogQueryRoot[0], { strLocale: objScopeInput }],
+    })
+  }
+
+  return objQueryClient.invalidateQueries({
+    exact: true,
+    queryKey: fnEnumCatalogQueryKey(objScopeInput),
+  })
+}

package/template/src/api/enums/scope.ts

@@ -0,0 +1,58 @@
+import { EnumCatalogError } from './errors'
+import type {
+  IEnumCatalogScope,
+  IEnumCatalogScopeContext,
+  TEnumCatalogScopeInput,
+  TEnumLocale,
+} from './types'
+
+function fnNormalizeScopeValue(strValue: string | undefined) {
+  const strNormalizedValue = strValue?.trim()
+  return strNormalizedValue || undefined
+}
+
+/** 创建不含凭据、可安全用于 Query Key 的枚举目录作用域。 */
+export function fnCreateEnumCatalogScope(
+  strLocale: TEnumLocale,
+  objContext: IEnumCatalogScopeContext = {}
+): IEnumCatalogScope {
+  if (!strLocale) {
+    throw new EnumCatalogError(
+      'INVALID_SCOPE',
+      '枚举目录作用域必须包含显示语言。'
+    )
+  }
+  if (
+    objContext.nSessionGeneration !== undefined &&
+    (!Number.isInteger(objContext.nSessionGeneration) ||
+      objContext.nSessionGeneration < 0)
+  ) {
+    throw new EnumCatalogError(
+      'INVALID_SCOPE',
+      '枚举目录作用域的会话版本必须是非负整数。'
+    )
+  }
+
+  const strNamespace = fnNormalizeScopeValue(objContext.strNamespace)
+  const strTenantId = fnNormalizeScopeValue(objContext.strTenantId)
+  const strWorkspaceId = fnNormalizeScopeValue(objContext.strWorkspaceId)
+
+  return Object.freeze({
+    ...(objContext.nSessionGeneration !== undefined
+      ? { nSessionGeneration: objContext.nSessionGeneration }
+      : {}),
+    ...(strNamespace ? { strNamespace } : {}),
+    ...(strTenantId ? { strTenantId } : {}),
+    ...(strWorkspaceId ? { strWorkspaceId } : {}),
+    strLocale,
+  })
+}
+
+/** 将兼容的语言或完整作用域输入标准化为稳定作用域。 */
+export function fnResolveEnumCatalogScope(
+  objScope: TEnumCatalogScopeInput
+): IEnumCatalogScope {
+  return typeof objScope === 'string'
+    ? fnCreateEnumCatalogScope(objScope)
+    : fnCreateEnumCatalogScope(objScope.strLocale, objScope)
+}

package/template/src/api/enums/types.ts

@@ -0,0 +1,251 @@
+import type { ReactNode } from 'react'
+import type { TAppLocale } from '@/locale/types'
+
+/** 枚举目录支持的显示语言。 */
+export type TEnumLocale = TAppLocale
+
+/** 业务字段可用于查找枚举显示值的基础类型。 */
+export type TEnumValue = boolean | number | string
+
+/** 枚举目录错误的稳定分类。 */
+export type TEnumCatalogErrorCode =
+  | 'DUPLICATE_LABEL'
+  | 'DUPLICATE_VALUE'
+  | 'INVALID_OPTION'
+  | 'INVALID_RESPONSE'
+  | 'INVALID_SCOPE'
+  | 'LOCALE_MISMATCH'
+
+/** 除语言外用于隔离枚举缓存的业务作用域。 */
+export interface IEnumCatalogScopeContext {
+  /** 登录、退出或授权上下文变化时递增的会话版本。 */
+  readonly nSessionGeneration?: number
+  /** 产品模块或后端枚举命名空间。 */
+  readonly strNamespace?: string
+  /** 当前租户标识。 */
+  readonly strTenantId?: string
+  /** 当前组织、项目或工作空间标识。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 一个枚举目录请求与缓存的完整身份。 */
+export interface IEnumCatalogScope extends IEnumCatalogScopeContext {
+  /** 当前目录使用的显示语言。 */
+  readonly strLocale: TEnumLocale
+}
+
+/** 查询 API 接受完整作用域，也兼容仅传语言的简单调用。 */
+export type TEnumCatalogScopeInput = IEnumCatalogScope | TEnumLocale
+
+/** 后端枚举扩展信息允许携带的 JSON 值。 */
+export type TEnumMetadataValue =
+  | boolean
+  | number
+  | string
+  | null
+  | readonly TEnumMetadataValue[]
+  | { readonly [strKey: string]: TEnumMetadataValue }
+
+/** 后端枚举目录中的原始选项；字段保持 Swagger 数据契约命名。 */
+export interface IEnumOptionPayload {
+  /** 可选颜色标识，可由具体展示组件解释为设计系统色调。 */
+  color?: string
+  /** 可选补充说明，用于提示或无障碍描述。 */
+  description?: string
+  /** 是否保留展示但禁止产生新的选择。 */
+  disabled?: boolean
+  /** 面向当前语言的显示文本。 */
+  label?: string
+  /** 不参与全局基础逻辑的后端扩展信息。 */
+  metadata?: Readonly<Record<string, TEnumMetadataValue>>
+  /** 升序排列权重。 */
+  sortOrder?: number
+  /** 跨语言稳定、用于提交和比较的枚举值。 */
+  value?: TEnumValue
+}
+
+/** 后端统一枚举接口的原始目录；字段保持 Swagger 数据契约命名。 */
+export interface IEnumCatalogPayload {
+  /** 以稳定枚举 Key 为索引的选项集合。 */
+  enums?: Readonly<Record<string, readonly IEnumOptionPayload[] | undefined>>
+  /** 本次目录响应的显示语言。 */
+  locale?: string
+  /** 后端目录版本，用于诊断与刷新确认。 */
+  version?: string
+}
+
+/** 经过运行时校验、可安全交给 Feature 使用的枚举选项。 */
+export interface IEnumOption {
+  /** 可选颜色标识；组件应显式映射到自身视觉语义。 */
+  readonly color?: string
+  /** 可选补充说明。 */
+  readonly description?: string
+  /** 是否保留展示但禁止产生新的选择。 */
+  readonly disabled: boolean
+  /** 面向当前语言的显示文本。 */
+  readonly label: string
+  /** 只读的后端扩展信息。 */
+  readonly metadata?: Readonly<Record<string, TEnumMetadataValue>>
+  /** 升序排列权重。 */
+  readonly sortOrder: number
+  /** 跨语言稳定的枚举值。 */
+  readonly value: TEnumValue
+}
+
+/** 单个语言下已标准化的完整枚举目录。 */
+export interface IEnumCatalog {
+  /** 以稳定枚举 Key 为索引的只读选项集合。 */
+  readonly enums: ReadonlyMap<string, readonly IEnumOption[]>
+  /** 已加载目录的显示语言。 */
+  readonly locale: TEnumLocale
+  /** 后端返回的目录版本。 */
+  readonly version: string
+}
+
+/** 完整枚举目录展开后的单个条目。 */
+export interface IEnumCatalogEntry {
+  /** 当前枚举下已按 `sortOrder` 排序的只读选项。 */
+  readonly arrOptions: readonly IEnumOption[]
+  /** 后端定义的稳定枚举 Key。 */
+  readonly strKey: string
+}
+
+/** 后端枚举请求所需的运行时上下文。 */
+export interface IEnumCatalogRequestContext {
+  /** 本次请求与缓存使用的完整业务作用域。 */
+  readonly objScope: IEnumCatalogScope
+  /** QueryClient 取消或替换请求时触发的取消信号。 */
+  readonly objSignal: AbortSignal
+  /** 请求使用的显示语言。 */
+  readonly strLocale: TEnumLocale
+}
+
+/** 由生成客户端实现的后端枚举请求函数。 */
+export type TEnumCatalogRequest = (
+  objContext: IEnumCatalogRequestContext
+) => Promise<IEnumCatalogPayload | undefined>
+
+/** 全局枚举系统依赖的后端数据源契约。 */
+export interface IEnumCatalogSource {
+  /** 加载并返回一个语言下的完整、已校验目录。 */
+  fnLoadCatalog: (
+    objContext: IEnumCatalogRequestContext
+  ) => Promise<IEnumCatalog>
+}
+
+/** 全局枚举 Provider 的公共参数。 */
+export interface IEnumCatalogProviderProps {
+  /** 是否允许发起目录请求，默认启用。 */
+  bIsEnabled?: boolean
+  /** 使用统一枚举能力的应用子树。 */
+  children: ReactNode
+  /** 租户、工作空间等非语言缓存作用域。 */
+  objScope?: IEnumCatalogScopeContext
+  /** 由 Swagger 生成客户端适配的后端数据源；未配置时不会发起请求。 */
+  objSource?: IEnumCatalogSource
+  /** 当前目录语言，默认 `zh-CN`。 */
+  strLocale?: TEnumLocale
+}
+
+/** 完整目录查询暴露给预加载与诊断界面的状态。 */
+export interface IUseEnumCatalogResult {
+  /** 完整目录按 Key 排序后展开的只读条目。 */
+  arrEntries: readonly IEnumCatalogEntry[]
+  /** 完整目录中按字典序排列的枚举 Key。 */
+  arrKeys: readonly string[]
+  /** 是否已经配置后端枚举数据源。 */
+  bIsConfigured: boolean
+  /** 当前是否允许发起目录请求。 */
+  bIsEnabled: boolean
+  /** 请求是否失败。 */
+  bIsError: boolean
+  /** 包含首次请求和后台刷新的所有请求状态。 */
+  bIsFetching: boolean
+  /** 首次目录请求是否仍在进行。 */
+  bIsLoading: boolean
+  /** 已有数据时是否正在后台刷新。 */
+  bIsRefetching: boolean
+  /** 最近一次成功更新的时间戳，尚未成功时为 `0`。 */
+  nUpdatedAt: number
+  /** 请求失败时的标准 Error。 */
+  objError: Error | null
+  /** 已加载目录；尚未成功时为空。 */
+  objCatalog: IEnumCatalog | undefined
+  /** 当前请求与缓存使用的完整业务作用域。 */
+  objScope: IEnumCatalogScope
+  /** 当前请求语言。 */
+  strLocale: TEnumLocale
+  /** 后端目录版本；尚未加载时为空。 */
+  strVersion: string | null
+  /** 根据枚举 Key 和值读取显示文本，未知值回退为原始字符串。 */
+  fnGetLabel: (
+    strEnumKey: string,
+    objValue: TEnumValue | null | undefined
+  ) => string
+  /** 批量读取显示文本，保持输入顺序和重复项。 */
+  fnGetLabels: (
+    strEnumKey: string,
+    arrValues: readonly TEnumValue[]
+  ) => readonly string[]
+  /** 根据枚举 Key 读取已排序的完整选项。 */
+  fnGetOptions: (strEnumKey: string) => readonly IEnumOption[]
+  /** 批量读取已存在的选项，保持输入顺序并忽略未知值。 */
+  fnGetOptionsByValues: (
+    strEnumKey: string,
+    arrValues: readonly TEnumValue[]
+  ) => readonly IEnumOption[]
+  /** 根据枚举 Key 和显示文本反查稳定值。 */
+  fnGetValue: (strEnumKey: string, strLabel: string) => TEnumValue | undefined
+  /** 根据枚举 Key 读取所有稳定值。 */
+  fnGetValues: (strEnumKey: string) => readonly TEnumValue[]
+  /** 判断完整目录中是否存在指定枚举 Key。 */
+  fnHasKey: (strEnumKey: string) => boolean
+  /** 重新请求当前语言目录。 */
+  fnRefetch: () => Promise<void>
+}
+
+/** Feature 按枚举 Key 消费时获得的标准结果。 */
+export interface IUseEnumResult {
+  /** 已按 `sortOrder` 排序的只读选项。 */
+  arrOptions: readonly IEnumOption[]
+  /** 是否已经配置后端枚举数据源。 */
+  bIsConfigured: boolean
+  /** 当前是否允许发起目录请求。 */
+  bIsEnabled: boolean
+  /** 目录请求是否失败。 */
+  bIsError: boolean
+  /** 包含首次请求和后台刷新的所有请求状态。 */
+  bIsFetching: boolean
+  /** 目录已加载但没有找到当前枚举 Key。 */
+  bIsMissing: boolean
+  /** 首次目录请求是否仍在进行。 */
+  bIsLoading: boolean
+  /** 已有数据时是否正在后台刷新。 */
+  bIsRefetching: boolean
+  /** 最近一次成功更新的时间戳，尚未成功时为 `0`。 */
+  nUpdatedAt: number
+  /** 请求失败时的标准 Error。 */
+  objError: Error | null
+  /** 当前请求与缓存使用的完整业务作用域。 */
+  objScope: IEnumCatalogScope
+  /** 返回值对应的目录语言。 */
+  strLocale: TEnumLocale
+  /** 后端目录版本；尚未加载时为空。 */
+  strVersion: string | null
+  /** 判断值是否存在于当前枚举。 */
+  fnHasValue: (objValue: TEnumValue | null | undefined) => boolean
+  /** 根据值读取完整选项，不存在时返回 `null`。 */
+  fnGetOption: (objValue: TEnumValue | null | undefined) => IEnumOption | null
+  /** 根据值读取显示文本，未知值回退为原始字符串。 */
+  fnGetLabel: (objValue: TEnumValue | null | undefined) => string
+  /** 批量读取显示文本，保持输入顺序和重复项。 */
+  fnGetLabels: (arrValues: readonly TEnumValue[]) => readonly string[]
+  /** 批量读取已存在的选项，保持输入顺序并忽略未知值。 */
+  fnGetOptionsByValues: (
+    arrValues: readonly TEnumValue[]
+  ) => readonly IEnumOption[]
+  /** 根据显示文本反查稳定值。 */
+  fnGetValue: (strLabel: string) => TEnumValue | undefined
+  /** 重新请求当前语言的完整枚举目录。 */
+  fnRefetch: () => Promise<void>
+}

package/template/src/api/hooks/error.ts

@@ -0,0 +1,198 @@
+import { fnCaptureError } from '@/observability'
+import axios, { AxiosError, type AxiosResponse } from 'axios'
+import { ApiError } from '@/api/ApiError'
+import type { TApiErrorKind } from '@/api/types'
+import { fnResolveResponseRequestId } from './requestId'
+import type { IApiHookOptions } from './types'
+
+type TErrorPayload = Record<string, unknown>
+const nMaxDisplayMessageLength = 500
+
+async function fnResolveBlobPayload(objPayload: unknown) {
+  if (!(objPayload instanceof Blob)) return objPayload
+
+  try {
+    return JSON.parse(await objPayload.text()) as unknown
+  } catch {
+    return objPayload
+  }
+}
+
+function fnReadPayloadString(objPayload: TErrorPayload, strKey: string) {
+  const objValue = objPayload[strKey]
+  return typeof objValue === 'string' || typeof objValue === 'number'
+    ? String(objValue)
+    : null
+}
+
+function fnIsErrorPayload(objPayload: unknown): objPayload is TErrorPayload {
+  return (
+    typeof objPayload === 'object' &&
+    objPayload !== null &&
+    !Array.isArray(objPayload) &&
+    !(objPayload instanceof Blob)
+  )
+}
+
+function fnNormalizeDisplayMessage(strMessage: string, strFallback: string) {
+  const strNormalized = Array.from(strMessage)
+    .map((strCharacter) => {
+      const nCodePoint = strCharacter.codePointAt(0) ?? 0
+      return nCodePoint <= 31 || nCodePoint === 127 ? ' ' : strCharacter
+    })
+    .join('')
+    .trim()
+  if (!strNormalized || /^\s*<(?:!doctype|html)/i.test(strNormalized)) {
+    return strFallback
+  }
+  return strNormalized.slice(0, nMaxDisplayMessageLength)
+}
+
+function fnNormalizeErrorCode(strCode: string | null, strFallback: string) {
+  const strNormalized = strCode?.trim() ?? ''
+  return /^[a-z0-9._:-]{1,128}$/i.test(strNormalized)
+    ? strNormalized
+    : strFallback
+}
+
+function fnGetErrorKind(objError: AxiosError): TApiErrorKind {
+  if (objError.response) return 'http'
+  if (['ECONNABORTED', 'ETIMEDOUT'].includes(objError.code ?? '')) {
+    return 'timeout'
+  }
+  if (objError.code === 'ERR_NETWORK') return 'network'
+  if (objError.config) return 'client'
+  return 'unknown'
+}
+
+function fnIsRetriableApiError(strKind: TApiErrorKind, nStatus?: number) {
+  if (strKind === 'network' || strKind === 'timeout') return true
+  return nStatus === 408 || nStatus === 429 || (nStatus ?? 0) >= 500
+}
+
+function fnGetFallbackMessage(objError: AxiosError, strKind: TApiErrorKind) {
+  if (strKind === 'network') return '网络连接异常，请稍后重试'
+  if (strKind === 'timeout') return '请求超时，请稍后重试'
+  if (objError.code === 'ERR_UNAUTHORIZED') return '登录状态已失效，请重新登录'
+  return fnNormalizeDisplayMessage(objError.message, '请求失败，请稍后重试')
+}
+
+function fnGetErrorMessage(
+  objResponse: AxiosResponse | undefined,
+  objPayload: unknown,
+  strFallback: string
+) {
+  if (!objResponse) return strFallback
+  if (typeof objPayload === 'string') {
+    return fnNormalizeDisplayMessage(
+      objPayload,
+      objResponse.statusText || `HTTP ${objResponse.status}`
+    )
+  }
+  if (!fnIsErrorPayload(objPayload)) {
+    return objResponse.statusText || `HTTP ${objResponse.status}`
+  }
+
+  const strCode =
+    fnReadPayloadString(objPayload, 'rspCode') ??
+    fnReadPayloadString(objPayload, 'code') ??
+    String(objResponse.status)
+  const strMessage =
+    fnReadPayloadString(objPayload, 'msg') ??
+    fnReadPayloadString(objPayload, 'message') ??
+    fnReadPayloadString(objPayload, 'detail') ??
+    fnReadPayloadString(objPayload, 'title')
+  const strError = fnReadPayloadString(objPayload, 'error')
+
+  return fnNormalizeDisplayMessage(
+    strMessage ?? `${strCode}${strError ? ` ${strError}` : ''}`,
+    objResponse.statusText || `HTTP ${objResponse.status}`
+  )
+}
+
+function fnGetPayloadDetails(objPayload: unknown) {
+  if (!fnIsErrorPayload(objPayload)) return undefined
+  return objPayload.details ?? objPayload.errors
+}
+
+function fnGetPayloadRequestId(objPayload: unknown) {
+  if (!fnIsErrorPayload(objPayload)) return undefined
+  return (
+    fnReadPayloadString(objPayload, 'requestId') ??
+    fnReadPayloadString(objPayload, 'traceId')
+  )
+}
+
+function fnGetErrorCode(
+  objError: AxiosError,
+  objPayload: unknown,
+  nStatus?: number
+) {
+  const strPayloadCode = fnIsErrorPayload(objPayload)
+    ? (fnReadPayloadString(objPayload, 'rspCode') ??
+      fnReadPayloadString(objPayload, 'code') ??
+      fnReadPayloadString(objPayload, 'type'))
+    : null
+  return fnNormalizeErrorCode(
+    strPayloadCode,
+    nStatus ? `HTTP_${nStatus}` : (objError.code ?? 'UNKNOWN_ERROR')
+  )
+}
+
+export function fnCreateErrorHook(objOptions: IApiHookOptions = {}) {
+  return async (objReason: unknown) => {
+    if (axios.isCancel(objReason)) return Promise.reject(objReason)
+
+    const objError = axios.isAxiosError(objReason)
+      ? objReason
+      : new AxiosError(
+          objReason instanceof Error ? objReason.message : String(objReason)
+        )
+    const objResponse = objError.response
+    const objPayload = await fnResolveBlobPayload(objResponse?.data)
+    const nStatus = objResponse?.status
+    const strKind = fnGetErrorKind(objError)
+    const strFallbackMessage = fnGetFallbackMessage(objError, strKind)
+    const objApiError = new ApiError({
+      bRetriable: fnIsRetriableApiError(strKind, nStatus),
+      nStatus,
+      objDetails: fnGetPayloadDetails(objPayload),
+      strCode: fnGetErrorCode(objError, objPayload, nStatus),
+      strKind,
+      strMessage: fnGetErrorMessage(
+        objResponse,
+        objPayload,
+        strFallbackMessage
+      ),
+      strRequestId: fnResolveResponseRequestId(
+        objResponse,
+        fnGetPayloadRequestId(objPayload),
+        objError.config?.strRequestId
+      ),
+    })
+
+    objError.config?.fnProgress?.(false)
+
+    fnCaptureError(objApiError, {
+      strName: 'api.request_failed',
+      strSource: 'api',
+      objAttributes: {
+        bRetriable: objApiError.bRetriable,
+        nStatus: objApiError.nStatus ?? null,
+        strCode: objApiError.strCode,
+        strKind: objApiError.strKind,
+        strRequestId: objApiError.strRequestId ?? null,
+      },
+    })
+
+    if (nStatus === 401 || objError.code === 'ERR_UNAUTHORIZED') {
+      await objOptions.fnOnUnauthorized?.()
+    }
+
+    if (objError.config?.bShowError !== false) {
+      await objOptions.fnOnError?.(objApiError)
+    }
+
+    return Promise.reject(objApiError)
+  }
+}

package/template/src/api/hooks/index.ts

@@ -0,0 +1,4 @@
+export { fnCreateErrorHook } from './error'
+export { fnCreateRequestHook } from './request'
+export { fnCreateResponseHook } from './response'
+export type { IApiHookOptions, TMaybePromise } from './types'

package/template/src/api/hooks/request.ts

@@ -0,0 +1,99 @@
+import { AxiosError, isCancel, type InternalAxiosRequestConfig } from 'axios'
+import { fnIsSuccessfulHttpStatus } from '@/api/clients/httpStatus'
+import { fnNormalizeIdempotencyKey } from '@/api/idempotency/key'
+import { fnEnsureRequestId } from './requestId'
+import type { IApiHookOptions } from './types'
+
+const arrDefaultAnonymousPaths = ['/login', '/refresh-token']
+
+function fnIsAnonymousRequest(
+  strUrl: string,
+  arrAnonymousPaths: readonly string[]
+) {
+  let strPathname: string
+
+  try {
+    strPathname = new URL(strUrl, 'http://localhost').pathname
+  } catch {
+    return false
+  }
+
+  return arrAnonymousPaths.some((strPath) => {
+    const strNormalizedPath = strPath.startsWith('/') ? strPath : `/${strPath}`
+    return (
+      strPathname === strNormalizedPath ||
+      strPathname.endsWith(strNormalizedPath)
+    )
+  })
+}
+
+function fnCreateUnauthorizedRequestError(
+  objConfig: InternalAxiosRequestConfig
+) {
+  return new AxiosError(
+    'Authentication is required before sending this request.',
+    'ERR_UNAUTHORIZED',
+    objConfig
+  )
+}
+
+export function fnCreateRequestHook(objOptions: IApiHookOptions = {}) {
+  let objRefreshPromise: Promise<string | null> | null = null
+
+  return async (objConfig: InternalAxiosRequestConfig) => {
+    objConfig.validateStatus = fnIsSuccessfulHttpStatus
+    fnEnsureRequestId(objConfig, objOptions.fnCreateRequestId)
+    if (objConfig.strIdempotencyKey) {
+      objConfig.headers.set(
+        'Idempotency-Key',
+        fnNormalizeIdempotencyKey(objConfig.strIdempotencyKey)
+      )
+    }
+    objConfig.fnProgress?.(true)
+
+    if (objConfig.fnBeforeRequest) {
+      objConfig.fnBeforeRequest(objConfig)
+      return objConfig
+    }
+
+    const strUrl = objConfig.url ?? ''
+    const arrAnonymousPaths =
+      objOptions.arrAnonymousPaths ?? arrDefaultAnonymousPaths
+
+    if (fnIsAnonymousRequest(strUrl, arrAnonymousPaths)) {
+      return objConfig
+    }
+
+    let strAccessToken = (await objOptions.fnGetAccessToken?.()) ?? null
+    const bIsExpired = (await objOptions.fnIsAccessTokenExpired?.()) ?? false
+
+    if (bIsExpired) {
+      if (!objOptions.fnRefreshAccessToken) {
+        await objOptions.fnOnUnauthorized?.()
+        throw fnCreateUnauthorizedRequestError(objConfig)
+      }
+
+      objRefreshPromise ??= objOptions.fnRefreshAccessToken().finally(() => {
+        objRefreshPromise = null
+      })
+
+      try {
+        strAccessToken = await objRefreshPromise
+      } catch (objError) {
+        if (!isCancel(objError)) await objOptions.fnOnUnauthorized?.()
+        throw objError
+      }
+
+      if (!strAccessToken) {
+        await objOptions.fnOnUnauthorized?.()
+        throw fnCreateUnauthorizedRequestError(objConfig)
+      }
+    }
+
+    if (strAccessToken) {
+      objConfig.headers.set('Authorization', `Bearer ${strAccessToken}`)
+    }
+
+    return objConfig
+  }
+}