@snack-kit/lib 0.1.0

package/dist/types/http.d.ts

@@ -0,0 +1,355 @@
+import { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+/**
+ * HTTP 请求配置，扩展自 AxiosRequestConfig
+ */
+interface HttpRequestConfig<D = unknown> extends AxiosRequestConfig<D> {
+    /** Context key，自动从 HttpContext 获取 baseURL */
+    ctx?: string;
+    /** 自定义请求 ID，用于主动取消 */
+    cancelId?: string;
+    /** 回调接收生成的 cancelId */
+    onCancelId?: (id: string) => void;
+    /**
+     * 是否添加时间戳防缓存，默认 false（添加防缓存时间戳）
+     * 设为 true 时不添加时间戳
+     */
+    cache?: boolean;
+}
+/**
+ * HTTP 请求结果，扩展自 AxiosResponse
+ */
+interface HttpResult<T = unknown> extends Partial<AxiosResponse<T>> {
+    /** 有 error 则请求失败，无 error 则成功 */
+    error?: HttpError;
+}
+/**
+ * HTTP 错误信息
+ */
+interface HttpError {
+    /** HTTP 状态码 */
+    status?: number;
+    /** 错误描述 */
+    message: string;
+    /** 服务端返回的原始错误体 */
+    data?: unknown;
+}
+/**
+ * 网关 `/ngw/context` 接口返回的元数据（`$info` 字段）
+ */
+interface ContextInfo {
+    /** 网关版本号，例如 `"4.6.2-r10"` */
+    version: string;
+    /** 网关域名，例如 `"http://172.16.32.155:20000"` */
+    domain: string;
+    /** 客户端标识 */
+    client: string;
+    /** 当前语言 */
+    lang: string;
+}
+/**
+ * 网关 `/web-debug/host/list` 接口返回的服务列表项
+ */
+interface ServerItem {
+    /** 服务唯一标识 */
+    key: string;
+    /** 服务名称 */
+    name: string;
+    /** 服务类型分组，可为空字符串 */
+    type: string;
+    /** 服务地址，用于 `context.load()` 切换路由映射 */
+    origin: string;
+    /** 代理配置（由网关管理，前端只读） */
+    proxyInfo: Record<string, unknown>;
+}
+
+/**
+ * 管理服务地址映射的上下文单例
+ *
+ * 支持两种加载方式：
+ * - **远程加载**：传入网关 URL，自动请求 `GET /ngw/context` 获取映射表
+ * - **本地注入**：直接传入键值对象
+ *
+ * @example 远程加载
+ * ```ts
+ * import { Context } from '@snack-kit/lib/http'
+ *
+ * await Context.load('http://172.16.32.155:20000')
+ * Context.get('ngw')   // 'http://172.16.32.155:20000/ngw'
+ * Context.info         // { version: '4.6.2-r10', domain: '...', ... }
+ * ```
+ *
+ * @example 本地注入
+ * ```ts
+ * await Context.load({
+ *   'user-svc': 'http://user.api.com',
+ *   'order-svc': 'http://order.api.com',
+ * })
+ * ```
+ */
+declare class HttpContext {
+    private _store;
+    private _loaded;
+    private _info;
+    /**
+     * 加载服务地址映射
+     *
+     * 远程加载时，响应中的 `$info` 元数据字段会被单独存储，不计入路由映射表。
+     *
+     * @param source 远程加载传入网关 URL；本地注入传入键值对象
+     * @param timeout 远程加载超时（ms），默认 5000
+     *
+     * @example 远程加载
+     * ```ts
+     * await Context.load('http://172.16.32.155:20000', 3000)
+     * ```
+     *
+     * @example 本地注入
+     * ```ts
+     * await Context.load({ 'user-svc': 'http://user.api.com' })
+     * ```
+     */
+    load(source: string | Record<string, string>, timeout?: number): Promise<void>;
+    /**
+     * 获取指定 ctx key 对应的服务地址
+     * @param key ctx key，例如 `'ngw'`、`'osc'`
+     * @returns 服务地址，未找到时返回空字符串
+     *
+     * @example
+     * ```ts
+     * await Context.load('http://172.16.32.155:20000')
+     * Context.get('osc')  // 'http://172.16.32.155:20000/osc'
+     * Context.get('none') // ''
+     * ```
+     */
+    get(key: string): string;
+    /**
+     * 网关元数据（仅远程加载后可用）
+     *
+     * @example
+     * ```ts
+     * await Context.load('http://172.16.32.155:20000')
+     * Context.info?.version // '4.6.2-r10'
+     * Context.info?.domain  // 'http://172.16.32.155:20000'
+     * ```
+     */
+    get info(): ContextInfo | undefined;
+    /**
+     * Context 是否已加载
+     *
+     * @example
+     * ```ts
+     * Context.loaded // false
+     * await Context.load({ 'user-svc': 'http://user.api.com' })
+     * Context.loaded // true
+     * ```
+     */
+    get loaded(): boolean;
+    /**
+     * 清空所有映射并重置加载状态
+     *
+     * @example
+     * ```ts
+     * Context.clear()
+     * Context.loaded // false
+     * ```
+     */
+    clear(): void;
+}
+/**
+ * HttpContext 全局单例
+ *
+ * @example
+ * ```ts
+ * import { Context } from '@snack-kit/lib/http'
+ *
+ * await Context.load('http://172.16.32.155:20000')
+ * Context.get('osc') // 'http://172.16.32.155:20000/osc'
+ * ```
+ */
+declare const Context: HttpContext;
+/**
+ * 当前页面的 origin（`protocol + host`）
+ *
+ * 在非浏览器环境（如 SSR/Node）返回空字符串。
+ *
+ * @example
+ * ```ts
+ * import { Origin } from '@snack-kit/lib/http'
+ * // 浏览器中：'https://app.example.com'
+ * // Node 环境：''
+ * ```
+ */
+declare const Origin: string;
+/**
+ * 当前页面路径的首段，可直接用作 `ctx` 参数
+ *
+ * 例如 `/osc/employee` → `'osc'`，在非浏览器环境返回空字符串。
+ *
+ * @example
+ * ```ts
+ * import { Ctx, Get } from '@snack-kit/lib/http'
+ *
+ * // 当前路径为 /osc/... 时，Ctx === 'osc'
+ * const result = await Get('/employee', { ctx: Ctx })
+ * ```
+ */
+declare const Ctx: string;
+
+/**
+ * 取消指定 id 的请求并从注册表移除
+ *
+ * @param id 请求唯一标识
+ * @returns 是否找到并取消了请求
+ *
+ * @example
+ * ```ts
+ * import { Get, Cancel } from '@snack-kit/lib/http'
+ *
+ * let cancelId = ''
+ * Get('/api/data', { onCancelId: (id) => { cancelId = id } })
+ *
+ * // 需要时取消
+ * Cancel(cancelId)
+ * ```
+ */
+declare function Cancel(id: string): boolean;
+/**
+ * 取消所有已注册的请求并清空注册表
+ *
+ * @example
+ * ```ts
+ * import { CancelAll } from '@snack-kit/lib/http'
+ *
+ * // 页面卸载时取消所有进行中的请求
+ * window.addEventListener('beforeunload', () => CancelAll())
+ * ```
+ */
+declare function CancelAll(): void;
+
+/**
+ * 核心请求函数，所有快捷方法基于此实现
+ *
+ * 自动处理：
+ * - `ctx` → 从 HttpContext 查询 baseURL 并注入
+ * - `cache: false`（默认）→ URL 附加 `?_=timestamp` 防缓存
+ * - 请求取消 → 自动注册 AbortController，完成后自动清理
+ * - 错误捕获 → 统一返回 `{ error }` 而非 throw
+ *
+ * @param config 请求配置
+ * @returns 请求结果
+ *
+ * @example 基础用法
+ * ```ts
+ * import { Request } from '@snack-kit/lib/http'
+ *
+ * const result = await Request<{ id: number }>({ url: '/api/user', method: 'GET' })
+ * if (result.error) {
+ *   console.error(result.error.message)
+ * } else {
+ *   console.log(result.data)
+ * }
+ * ```
+ *
+ * @example 使用 ctx 自动注入 baseURL
+ * ```ts
+ * import { context, Request } from '@snack-kit/lib/http'
+ *
+ * await context.load({ 'user-svc': 'http://user.api.com' })
+ * const result = await Request({ url: '/profile', method: 'GET', ctx: 'user-svc' })
+ * // 实际请求：GET http://user.api.com/profile
+ * ```
+ */
+declare function Request<T>(config: HttpRequestConfig): Promise<HttpResult<T>>;
+/**
+ * 发起 GET 请求
+ *
+ * @param url 请求地址
+ * @param config 请求配置
+ *
+ * @example
+ * ```ts
+ * import { Get } from '@snack-kit/lib/http'
+ *
+ * const { data, error } = await Get<{ name: string }>('/api/user/1')
+ * if (!error) console.log(data?.name)
+ * ```
+ *
+ * @example 使用 ctx 自动路由
+ * ```ts
+ * const { data } = await Get('/profile', { ctx: 'user-svc' })
+ * ```
+ *
+ * @example 获取 cancelId 以便主动取消
+ * ```ts
+ * let cancelId = ''
+ * Get('/api/list', { onCancelId: (id) => { cancelId = id } })
+ * Cancel(cancelId) // 取消请求
+ * ```
+ */
+declare function Get<T>(url: string, config?: HttpRequestConfig): Promise<HttpResult<T>>;
+/**
+ * 发起 POST 请求
+ *
+ * @param url 请求地址
+ * @param data 请求体数据
+ * @param config 请求配置
+ *
+ * @example
+ * ```ts
+ * import { Post } from '@snack-kit/lib/http'
+ *
+ * const { data, error } = await Post<{ token: string }>('/api/login', {
+ *   username: 'admin',
+ *   password: '123456',
+ * })
+ * if (!error) console.log(data?.token)
+ * ```
+ */
+declare function Post<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResult<T>>;
+/**
+ * 发起 PUT 请求
+ *
+ * @param url 请求地址
+ * @param data 请求体数据
+ * @param config 请求配置
+ *
+ * @example
+ * ```ts
+ * import { Put } from '@snack-kit/lib/http'
+ *
+ * await Put('/api/user/1', { name: 'Alice' })
+ * ```
+ */
+declare function Put<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResult<T>>;
+/**
+ * 发起 PATCH 请求
+ *
+ * @param url 请求地址
+ * @param data 请求体数据
+ * @param config 请求配置
+ *
+ * @example
+ * ```ts
+ * import { Patch } from '@snack-kit/lib/http'
+ *
+ * await Patch('/api/user/1', { avatar: 'https://...' })
+ * ```
+ */
+declare function Patch<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResult<T>>;
+/**
+ * 发起 DELETE 请求
+ *
+ * @param url 请求地址
+ * @param config 请求配置
+ *
+ * @example
+ * ```ts
+ * import { Del } from '@snack-kit/lib/http'
+ *
+ * await Del('/api/user/1')
+ * ```
+ */
+declare function Del<T>(url: string, config?: HttpRequestConfig): Promise<HttpResult<T>>;
+
+export { Cancel, CancelAll, Context, type ContextInfo, Ctx, Del, Get, HttpContext, type HttpError, type HttpRequestConfig, type HttpResult, Origin, Patch, Post, Put, Request, type ServerItem };

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export { Cancel, CancelAll, Context, ContextInfo, Ctx, Del, Get, HttpContext, HttpError, HttpRequestConfig, HttpResult, Origin, Patch, Post, Put, Request, ServerItem } from './http.js';
+export { Debugger, DebuggerOptions } from './debugger.js';
+import 'axios';
+
+var version = "0.1.0";
+
+export { version as VERSION };