@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/utils/props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.js","names":[],"sources":["../../src/utils/props.ts"],"sourcesContent":["/**\n * 部件 props 的类型与合并规则（COMPONENTS.md §2）。\n *\n * 组件给部件的属性分两层：可被使用方覆盖的默认属性（defaults），以及组件状态决定、\n * 不允许覆盖的受管属性（managed，如 role、aria-expanded）。合并规则：\n *   - sx：默认在前、使用方其次、受管最后，后者覆盖前者\n *   - class、style：依次排列成数组，交给 Vue 统一处理（它们也可能是数组或对象）\n *   - 事件 onXxx：使用方先执行，调用了 event.preventDefault() 就跳过组件自己的处理\n *   - ref：各方都拿到元素\n *   - 其他属性：受管 > 使用方 > 默认\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { IntrinsicProps, JSX } from '@zerodep-dev/vue-tsx-pro-tsx/jsx-runtime';\n// 登记主题 tokens（样式里的 '_md' 靠它）：每个组件都经过这里合并属性，渲染之前一定登记过\nimport '../config/theme/tokens';\nimport type { StyleAttrs, SxStyles } from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { Ref, VNodeChild } from 'vue';\n\n/**\n * 原生元素部件的 props：该元素的属性加上 sx；去掉组件管理的属性与 children（内容走组件自己的 prop）。\n * 形如 `propsInput?: PartProps<'input', 'value' | 'aria-invalid'>`。\n */\nexport type PartProps<\n  Tag extends keyof JSX.IntrinsicElements,\n  Managed extends string = never,\n> = Omit<IntrinsicProps<Tag>, Managed | 'children'> & { sx?: SxStyles };\n\n/**\n * 展开收起类组件（Collapsible、Popover）交给触发器的属性：展开到任意可聚焦元素上，\n * 形如 `trigger={(props) => <Button {...props}>更多</Button>}`。弹层另外加上 id、ref、aria-haspopup。\n */\nexport interface TriggerProps {\n  /** 切换展开与收起 */\n  onClick: (event: MouseEvent) => void;\n  /** 当前是否展开，读屏据此播报“已展开 / 已折叠” */\n  'aria-expanded': boolean;\n  /** 被控制的内容区的 id */\n  'aria-controls': string;\n  /** 不可用：组件设了 disabled 时为 true，展开到按钮上就是原生的 disabled */\n  disabled?: boolean;\n}\n\n/**\n * data-* 属性写进对象字面量（部件属性、mergeAttrs 的各层）：元素的属性类型不收 data-* 键，\n * 用它包一层再展开。JSX 上直接写 data-* 不需要它。\n *\n *   mergeAttrs<'td'>(defaults, user, { role: 'gridcell', ...dataAttrs({ 'data-in-range': inRange || undefined }) })\n */\nexport const dataAttrs = (attrs: Record<`data-${string}`, string | number | boolean | undefined>) =>\n  attrs;\n\ntype Props = Record<string, unknown>;\ntype Handler = (...args: unknown[]) => unknown;\ntype RefSetter = ((element: unknown) => void) | Ref<unknown>;\n\n/**\n * 一层属性：Target 是标签名（'svg'）时为该元素的属性加 sx，是 props 类型（IconProps）时就是它。\n * 标签名的联合（'h1' | 'h2'，一个工厂生成的几个组件共用实现时）取这些标签共有的属性，所以这里不按联合分配\n */\ntype PropsLayer<Target> = Partial<\n  [Target] extends [keyof JSX.IntrinsicElements] ? PartProps<Target> : Target\n>;\n\n/**\n * 合并部件的三层属性：组件默认、使用方传入、组件受管，规则见文件开头。\n * 用类型参数写明属性落到哪里，三层的对象字面量才有补全、悬停说明与类型检查：\n *   mergeProps<IconProps>({ sx: … }, propsIcon)；原生元素用 mergeAttrs<'svg'>(默认, rest, 受管)\n *\n * 渲染里每个部件每次都要合并，按最常见的情况走捷径：只有默认层时原样返回；\n * 只有两层以上都给了同名事件时才包一层回调。\n */\nexport function mergeProps<Target = Props>(\n  defaults: PropsLayer<Target>,\n  user?: PropsLayer<Target>,\n  managed?: PropsLayer<Target>,\n): PropsLayer<Target> {\n  const base = defaults as Props;\n  const own = hasKeys(user) ? (user as Props) : undefined;\n  const fixed = hasKeys(managed) ? (managed as Props) : undefined;\n  if (!own && !fixed) return defaults;\n  const merged: Props = { ...base, ...own, ...fixed };\n\n  for (const key of LISTED_KEYS) {\n    const values = present3(base[key], own?.[key], fixed?.[key]);\n    if (values) merged[key] = values;\n  }\n\n  const refs = present3(base.ref, own?.ref, fixed?.ref) as RefSetter[] | undefined;\n  if (refs && refs.length > 1) {\n    merged.ref = (element: unknown) => refs.forEach((ref) => setRef(ref, element));\n  }\n\n  // 同名事件：使用方的与组件的（默认层、受管层）合并；只有组件两层都有时也要合并\n  if (own) {\n    for (const key in own) {\n      if (!isHandlerKey(key)) continue;\n      if (base[key] == null && fixed?.[key] == null) {\n        // 受管层写了 onXxx: undefined（这时没有自己的处理）也不盖掉使用方的事件\n        merged[key] = own[key];\n        continue;\n      }\n      // 使用方传了 undefined（onClick={cond ? fn : undefined}）时也保留组件自己的\n      merged[key] =\n        mergeHandlers(own[key] as Handler | undefined, [base[key], fixed?.[key]]) ??\n        fixed?.[key] ??\n        base[key];\n    }\n  }\n  if (fixed) {\n    for (const key in fixed) {\n      if (!isHandlerKey(key) || base[key] == null || (own && key in own)) continue;\n      const handler = mergeHandlers(undefined, [base[key], fixed[key]]);\n      if (handler) merged[key] = handler;\n    }\n  }\n  return merged as PropsLayer<Target>;\n}\n\n/**\n * 子组件部件的合并：mergeProps 的规则，但默认层要写齐子组件的必填 props（如 Icon 的 icon），\n * 返回完整的 props 类型，展开到子组件上不必再断言：\n *   <Icon {...mergePartProps<IconProps>({ icon: X, sx: styles.icon }, propsIcon)} />\n */\nexport function mergePartProps<P extends object>(\n  defaults: P,\n  user?: Partial<P>,\n  managed?: Partial<P>,\n): P {\n  // P 是组件 props 类型，不是标签名：按对象合并，结果的类型就是 P\n  return mergeProps(\n    defaults as Props,\n    user as Props | undefined,\n    managed as Props | undefined,\n  ) as P;\n}\n\n/**\n * 原生元素部件的合并：mergeProps 的规则，再把 sx 换成 class 与 style（elementProps），结果直接展开到元素上：\n *   <svg {...mergeAttrs<'svg'>({ sx: styles.icon }, rest, { 'aria-hidden': true })} />\n */\nexport function mergeAttrs<Tag extends keyof JSX.IntrinsicElements>(\n  defaults: PropsLayer<Tag>,\n  user?: PropsLayer<Tag>,\n  managed?: PropsLayer<Tag>,\n): Omit<PropsLayer<Tag>, 'sx' | 'children'> {\n  return elementProps(mergeProps<Tag>(defaults, user, managed));\n}\n\n/**\n * 原生元素部件：把 sx 换成样式引擎生成的 class 与 style，再与已有的 class、style 合并。\n * 去掉 children：它是内容不是元素属性（组件的 ...rest 里带着它，转交给子组件时要用）。\n */\nexport function elementProps<P extends object>(props: P): Omit<P, 'sx' | 'children'> {\n  // 解构出的 rest 是新对象：之后直接往上写，不再复制一次（每个元素每次渲染都要走这里）\n  const { sx, children: _children, ...rest } = props as P & Props;\n  if (sx == null) return rest as Omit<P, 'sx' | 'children'>;\n  const compiled = compileSx(sx as SxStyles);\n  const element = rest as Props;\n  // 响应式绑定的 ref（元素挂上后改变量）与使用方的 ref 都要拿到元素\n  if (compiled.ref && element.ref != null) {\n    const own = element.ref as RefSetter;\n    const bound = compiled.ref;\n    element.ref = (target: unknown) => {\n      setRef(own, target);\n      bound(target);\n    };\n  } else if (compiled.ref) element.ref = compiled.ref;\n  if (rest.class == null && rest.style == null) {\n    if (compiled.class != null) element.class = compiled.class;\n    if (compiled.style != null) element.style = compiled.style;\n    return rest as Omit<P, 'sx' | 'children'>;\n  }\n  element.class = present3(rest.class, compiled.class) ?? [];\n  element.style = present3(compiled.style, rest.style) ?? [];\n  return rest as Omit<P, 'sx' | 'children'>;\n}\n\n/**\n * 编译好的样式是不变的常量：单个样式（不是数组）按对象缓存 css.attrs 的结果，\n * 根元素、图标这类每次渲染都是同一个样式的部件不必重复合并\n */\nconst compiledCache = new WeakMap<object, ReturnType<typeof css.attrs>>();\nfunction compileSx(sx: SxStyles) {\n  if (Array.isArray(sx) || typeof sx !== 'object' || sx === null) return css.attrs(sx);\n  let compiled = compiledCache.get(sx);\n  if (!compiled) compiledCache.set(sx, (compiled = css.attrs(sx)));\n  return compiled;\n}\n\n/** onClick、onUpdate:_value：on 后面跟大写字母 */\nfunction isHandlerKey(key: string) {\n  const third = key.charCodeAt(2);\n  return key.charCodeAt(0) === 111 && key.charCodeAt(1) === 110 && third >= 65 && third <= 90;\n}\n\nfunction hasKeys(layer: object | undefined): boolean {\n  if (!layer) return false;\n  for (const _ in layer) return true;\n  return false;\n}\n\n/**\n * 使用方的回调先执行，它调用了 event.preventDefault() 就跳过组件自己的回调。\n * 只有一方提供回调时返回 undefined，保留展开合并的结果即可。\n */\nfunction mergeHandlers(user: Handler | undefined, internal: unknown[]): Handler | undefined {\n  const own = present(internal) as Handler[];\n  if (own.length + (user ? 1 : 0) < 2) return undefined;\n  return (...args) => {\n    user?.(...args);\n    const event = args[0];\n    if (event instanceof Event && event.defaultPrevented) return;\n    own.forEach((handler) => handler(...args));\n  };\n}\n\nfunction setRef(ref: RefSetter, element: unknown) {\n  if (typeof ref === 'function') ref(element);\n  else ref.value = element;\n}\n\nconst present = <T>(values: readonly (T | null | undefined)[]) =>\n  values.filter((value): value is T => value != null);\n\n/** 按层排列、要合并成数组的属性 */\nconst LISTED_KEYS = ['sx', 'class', 'style'] as const;\n\n/** 最多三个值里不为空的那些，按原顺序成数组；都为空时返回 undefined。渲染路径上用，不建中间数组 */\nfunction present3(a: unknown, b: unknown, c?: unknown): unknown[] | undefined {\n  if (a == null) {\n    if (b == null) return c == null ? undefined : [c];\n    return c == null ? [b] : [b, c];\n  }\n  if (b == null) return c == null ? [a] : [a, c];\n  return c == null ? [a, b] : [a, b, c];\n}\n\n/**\n * 默认的 aria-labelledby（Field 的标签、弹层的触发器）：使用方写的 aria-labelledby 优先；使用方写了 aria-label 时\n * 不加默认的（aria-labelledby 会盖过 aria-label，使用方写的名称就白写了）\n */\nexport function defaultLabelledBy(\n  attrs: { 'aria-label'?: string; 'aria-labelledby'?: string },\n  fallback: string | undefined,\n): string | undefined {\n  return attrs['aria-labelledby'] ?? (attrs['aria-label'] == null ? fallback : undefined);\n}\n\n/**\n * 内容（插槽、标题、说明、错误这类 VNodeChild）有没有东西：null、undefined、空字符串与布尔都算没有。\n * 使用方常写 `error={cond && '…'}`、`aside={wide && <Panel />}`，条件不成立时是 false，不该渲染出空的外层\n */\nexport function hasContent(node: VNodeChild): boolean {\n  return node != null && typeof node !== 'boolean' && node !== '';\n}\n\n/**\n * 把 css.attrs 的结果写到命令式创建的元素上（波纹、量取主题的探针）：class 与行内样式，\n * 自定义属性（动态样式的变量）名字原样、用 setProperty\n */\nexport function applyStyleAttrs(element: HTMLElement, { class: className, style }: StyleAttrs) {\n  element.className = className ?? '';\n  for (const [name, value] of Object.entries(style ?? {})) {\n    const property = name.startsWith('--')\n      ? name\n      : name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);\n    element.style.setProperty(property, String(value));\n  }\n}\n"],"mappings":"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"}

package/dist/utils/request/http.d.ts

@@ -0,0 +1,101 @@
+import { type WireReviveOptions, type WireScalar } from './wire';
+/** 请求方法 */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+/**
+ * query 里的一个值：null、undefined 不写进地址，数组写成重复的键（a=1&a=2，数组里的 null 是空字符串）；
+ * bigint、Decimal、日期等按线上的文字写（wireText：Decimal 不用科学计数法，日期是 ISO）
+ */
+export type QueryValue = WireScalar | readonly WireScalar[];
+/** 一次请求 */
+export interface HttpRequest {
+    /** 请求方法，默认 GET */
+    method?: HttpMethod;
+    /** 地址：相对地址拼在 baseURL 后面，完整地址（https://…）原样使用 */
+    url: string;
+    /** 查询参数 */
+    query?: Readonly<Record<string, QueryValue>>;
+    /** 请求体：普通对象与数组按 JSON 发送；FormData、Blob、URLSearchParams、字符串原样发送 */
+    body?: unknown;
+    /** 请求头，盖过客户端的默认请求头 */
+    headers?: Readonly<Record<string, string>>;
+    /** 取消：abort 后请求中止，Promise 以 AbortError 拒绝 */
+    signal?: AbortSignal;
+    /** 超时（毫秒），盖过客户端的设置；0 表示不限 */
+    timeout?: number;
+    /** 怎样读响应体，默认按 content-type：JSON 解析，text/* 读成文字，其余读成 Blob */
+    responseType?: 'json' | 'text' | 'blob';
+}
+/** 组件依赖的请求接口：发出请求，返回解析（拆包）后的数据；失败时拒绝 */
+export interface HttpClient {
+    /** 发出一次请求，返回解析（拆包）后的数据；失败时以 HttpError 拒绝，取消时以 AbortError 拒绝 */
+    request<T = unknown>(request: HttpRequest): Promise<T>;
+}
+/** 请求失败时的上下文：发生在哪个请求、拿到的响应 */
+export interface HttpErrorContext {
+    /** 出错的请求 */
+    request: HttpRequest;
+    /** 响应；网络错误、超时时没有 */
+    response?: Response;
+    /** 响应体（错误详情），读得到时带上 */
+    data?: unknown;
+    /** 底层的错误（网络错误、超时） */
+    cause?: unknown;
+}
+/** 请求失败：状态码不是 2xx、网络错误、超时，或 onResponse 判定的业务错误 */
+export declare class HttpError extends Error {
+    /** 错误名，同类名：日志与 instanceof 之外的判断用 */
+    readonly name = "HttpError";
+    /** 出错的请求 */
+    readonly request: HttpRequest;
+    /** 响应；网络错误、超时时没有 */
+    readonly response?: Response;
+    /** HTTP 状态码；网络错误、超时为 0 */
+    readonly status: number;
+    /** 响应体（错误详情） */
+    readonly data?: unknown;
+    constructor(message: string, { request, response, data, cause }: HttpErrorContext);
+}
+/** 是不是主动取消（abort）造成的拒绝：界面上不当作错误 */
+export declare const isAbortError: (error: unknown) => boolean;
+/** createHttpClient 的选项 */
+export interface HttpClientOptions {
+    /** 相对地址的前缀，如 '/api' */
+    baseURL?: string;
+    /** 每个请求都带的请求头 */
+    headers?: Readonly<Record<string, string>>;
+    /** 超时（毫秒），默认 30000；0 表示不限 */
+    timeout?: number;
+    /** 发出之前改请求（加令牌、追踪编号）；可以返回一个新的 Request */
+    onRequest?: (request: Request) => Request | void | Promise<Request | void>;
+    /** 2xx 响应解析后的数据交给它：拆掉后端的包装、判定业务错误（抛 HttpError），返回值就是请求的结果 */
+    onResponse?: (data: unknown, context: {
+        request: HttpRequest;
+        response: Response;
+    }) => unknown;
+    /**
+     * 线上的 typed JSON 怎样还原（见 wire.ts）：给 `{ decimal: Decimal }` 时 decimal 还原成 Decimal，`dates: 'objects'`
+     * 时日期还原成 CalendarDate 等；默认 `{}`（bigint 还原成 bigint，decimal 与日期留作文字）。false 时请求体按普通 JSON 发、响应不还原
+     */
+    wire?: WireReviveOptions | false;
+    /** 换掉 fetch（测试、SSR、注入公共处理） */
+    fetch?: typeof fetch;
+}
+/** createHttpClient 的结果：request 之外，再给常用方法的简写 */
+export interface FetchClient extends HttpClient {
+    /** GET：参数写在 options.query 里 */
+    get<T = unknown>(url: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<T>;
+    /** DELETE */
+    delete<T = unknown>(url: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<T>;
+    /** POST：普通对象的 body 按 JSON 发送 */
+    post<T = unknown>(url: string, body?: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<T>;
+    /** PUT：普通对象的 body 按 JSON 发送 */
+    put<T = unknown>(url: string, body?: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<T>;
+    /** PATCH：普通对象的 body 按 JSON 发送 */
+    patch<T = unknown>(url: string, body?: unknown, options?: Omit<HttpRequest, 'url' | 'method' | 'body'>): Promise<T>;
+}
+/** 原生 fetch 的薄封装（见文件开头） */
+export declare function createHttpClient(options?: HttpClientOptions): FetchClient;
+/**
+ * 当前配置的请求客户端（在 setup 里调用）：createUi / Provider 的 http；都没给时是一个默认的 createHttpClient()
+ */
+export declare function useHttp(): HttpClient;

package/dist/utils/request/http.js

@@ -0,0 +1,154 @@
+import { useConfig } from "../../config/context.js";
+import { fromWire, toWire, wireText } from "./wire.js";
+//#region src/utils/request/http.ts
+/**
+* 请求层：组件（远程选项、上传、列表查询）只依赖 HttpClient 接口，应用经 createUi / Provider 的 http 给出实现。
+* 默认实现 createHttpClient 是原生 fetch 的薄封装（参考 ky、ofetch）：baseURL、query、JSON 请求体、超时与取消、
+* 状态码错误（HttpError）、请求与响应钩子。用 axios、ky 时只要写一个 request：
+*
+*   createUi({ http: { request: (r) => axios.request({ ...r, params: r.query, data: r.body }).then((res) => res.data) } })
+*
+* 值按线上的 typed JSON 传（见 wire.ts）：请求体里的 bigint、Decimal、CalendarDate 写成文字并附上 `$types`，
+* 地址栏参数写成同样的文字，带 `$types` 的响应先还原再交给 onResponse；`wire: false` 时按普通 JSON。
+*
+* 后端把数据包在 { code, data, message } 里时，在 onResponse 里拆开，业务错误抛 HttpError：
+*
+*   const http = createHttpClient({
+*     baseURL: '/api',
+*     onRequest: (request) => request.headers.set('Authorization', `Bearer ${token()}`),
+*     onResponse: (body: Envelope, context) => {
+*       if (body.code !== 0) throw new HttpError(body.message, { ...context, data: body });
+*       return body.data;
+*     },
+*   });
+*/
+/** 请求失败：状态码不是 2xx、网络错误、超时，或 onResponse 判定的业务错误 */
+var HttpError = class extends Error {
+	/** 错误名，同类名：日志与 instanceof 之外的判断用 */
+	name = "HttpError";
+	/** 出错的请求 */
+	request;
+	/** 响应；网络错误、超时时没有 */
+	response;
+	/** HTTP 状态码；网络错误、超时为 0 */
+	status;
+	/** 响应体（错误详情） */
+	data;
+	constructor(message, { request, response, data, cause }) {
+		super(message, { cause });
+		this.request = request;
+		this.response = response;
+		this.status = response?.status ?? 0;
+		this.data = data;
+	}
+};
+/** 是不是主动取消（abort）造成的拒绝：界面上不当作错误 */
+var isAbortError = (error) => error instanceof DOMException && error.name === "AbortError";
+/** 原生 fetch 的薄封装（见文件开头） */
+function createHttpClient(options = {}) {
+	const { baseURL = "", timeout: defaultTimeout = 3e4, onRequest, onResponse, wire = {} } = options;
+	async function request(spec) {
+		const { method = "GET", body, signal, timeout = defaultTimeout } = spec;
+		const headers = new Headers({
+			...options.headers,
+			...spec.headers
+		});
+		const json = isJsonBody(body);
+		if (json && !headers.has("content-type")) headers.set("content-type", "application/json");
+		const signals = [signal, timeout > 0 ? AbortSignal.timeout(timeout) : void 0].filter((item) => item != null);
+		let prepared = new Request(buildUrl(baseURL, spec.url, spec.query), {
+			method,
+			headers,
+			body: json ? JSON.stringify(wire === false ? body : toWire(body)) : body,
+			signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0]
+		});
+		prepared = await onRequest?.(prepared) ?? prepared;
+		let response;
+		try {
+			response = await (options.fetch ?? fetch)(prepared);
+		} catch (cause) {
+			if (signal?.aborted) throw cause;
+			throw new HttpError(cause instanceof DOMException && cause.name === "TimeoutError" ? `请求超时（${timeout / 1e3} 秒）：${method} ${spec.url}` : `网络错误：${method} ${spec.url}`, {
+				request: spec,
+				cause
+			});
+		}
+		const raw = await readBody(response, spec.responseType);
+		const data = wire === false ? raw : fromWire(raw, wire);
+		if (!response.ok) throw new HttpError(`请求失败（${`${response.status}${response.statusText ? ` ${response.statusText}` : ""}`}）：${method} ${spec.url}`, {
+			request: spec,
+			response,
+			data
+		});
+		return onResponse ? onResponse(data, {
+			request: spec,
+			response
+		}) : data;
+	}
+	const withBody = (method) => (url, body, rest) => request({
+		...rest,
+		method,
+		url,
+		body
+	});
+	return {
+		request,
+		get: (url, rest) => request({
+			...rest,
+			method: "GET",
+			url
+		}),
+		delete: (url, rest) => request({
+			...rest,
+			method: "DELETE",
+			url
+		}),
+		post: withBody("POST"),
+		put: withBody("PUT"),
+		patch: withBody("PATCH")
+	};
+}
+var fallback;
+/**
+* 当前配置的请求客户端（在 setup 里调用）：createUi / Provider 的 http；都没给时是一个默认的 createHttpClient()
+*/
+function useHttp() {
+	return useConfig().http ?? (fallback ??= createHttpClient());
+}
+/** 地址 + query：相对地址拼在 baseURL 后面（斜杠不重复），null、undefined 的参数跳过 */
+function buildUrl(baseURL, url, query) {
+	let full = /^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//") || !baseURL ? url : `${baseURL.replace(/\/+$/, "")}/${url.replace(/^\/+/, "")}`;
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query ?? {})) {
+		if (value == null) continue;
+		const items = Array.isArray(value) ? value : [value];
+		for (const item of items) params.append(key, wireText(item));
+	}
+	const search = params.toString();
+	if (search) full += `${full.includes("?") ? "&" : "?"}${search}`;
+	return full;
+}
+/** 普通对象与数组按 JSON 发送 */
+function isJsonBody(body) {
+	if (body == null || typeof body !== "object") return false;
+	const prototype = Object.getPrototypeOf(body);
+	return Array.isArray(body) || prototype === Object.prototype || prototype === null;
+}
+async function readBody(response, type) {
+	if (response.status === 204 || response.status === 205 || response.headers.get("content-length") === "0") return;
+	const contentType = response.headers.get("content-type") ?? "";
+	const kind = type ?? (/[/+]json\b/.test(contentType) ? "json" : contentType.startsWith("text/") ? "text" : "blob");
+	if (kind === "blob") return response.blob();
+	const text = await response.text();
+	if (kind === "text") return text;
+	if (text === "") return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+//#endregion
+export { HttpError, createHttpClient, isAbortError, useHttp };
+
+//# sourceMappingURL=http.js.map

package/dist/utils/request/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../../../src/utils/request/http.ts"],"sourcesContent":["/**\n * 请求层：组件（远程选项、上传、列表查询）只依赖 HttpClient 接口，应用经 createUi / Provider 的 http 给出实现。\n * 默认实现 createHttpClient 是原生 fetch 的薄封装（参考 ky、ofetch）：baseURL、query、JSON 请求体、超时与取消、\n * 状态码错误（HttpError）、请求与响应钩子。用 axios、ky 时只要写一个 request：\n *\n *   createUi({ http: { request: (r) => axios.request({ ...r, params: r.query, data: r.body }).then((res) => res.data) } })\n *\n * 值按线上的 typed JSON 传（见 wire.ts）：请求体里的 bigint、Decimal、CalendarDate 写成文字并附上 `$types`，\n * 地址栏参数写成同样的文字，带 `$types` 的响应先还原再交给 onResponse；`wire: false` 时按普通 JSON。\n *\n * 后端把数据包在 { code, data, message } 里时，在 onResponse 里拆开，业务错误抛 HttpError：\n *\n *   const http = createHttpClient({\n *     baseURL: '/api',\n *     onRequest: (request) => request.headers.set('Authorization', `Bearer ${token()}`),\n *     onResponse: (body: Envelope, context) => {\n *       if (body.code !== 0) throw new HttpError(body.message, { ...context, data: body });\n *       return body.data;\n *     },\n *   });\n */\nimport { useConfig } from '../../config/context';\nimport { fromWire, toWire, wireText, type WireReviveOptions, type WireScalar } from './wire';\n\n/** 请求方法 */\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';\n\n/**\n * query 里的一个值：null、undefined 不写进地址，数组写成重复的键（a=1&a=2，数组里的 null 是空字符串）；\n * bigint、Decimal、日期等按线上的文字写（wireText：Decimal 不用科学计数法，日期是 ISO）\n */\nexport type QueryValue = WireScalar | readonly WireScalar[];\n\n/** 一次请求 */\nexport interface HttpRequest {\n  /** 请求方法，默认 GET */\n  method?: HttpMethod;\n  /** 地址：相对地址拼在 baseURL 后面，完整地址（https://…）原样使用 */\n  url: string;\n  /** 查询参数 */\n  query?: Readonly<Record<string, QueryValue>>;\n  /** 请求体：普通对象与数组按 JSON 发送；FormData、Blob、URLSearchParams、字符串原样发送 */\n  body?: unknown;\n  /** 请求头，盖过客户端的默认请求头 */\n  headers?: Readonly<Record<string, string>>;\n  /** 取消：abort 后请求中止，Promise 以 AbortError 拒绝 */\n  signal?: AbortSignal;\n  /** 超时（毫秒），盖过客户端的设置；0 表示不限 */\n  timeout?: number;\n  /** 怎样读响应体，默认按 content-type：JSON 解析，text/* 读成文字，其余读成 Blob */\n  responseType?: 'json' | 'text' | 'blob';\n}\n\n/** 组件依赖的请求接口：发出请求，返回解析（拆包）后的数据；失败时拒绝 */\nexport interface HttpClient {\n  /** 发出一次请求，返回解析（拆包）后的数据；失败时以 HttpError 拒绝，取消时以 AbortError 拒绝 */\n  request<T = unknown>(request: HttpRequest): Promise<T>;\n}\n\n/** 请求失败时的上下文：发生在哪个请求、拿到的响应 */\nexport interface HttpErrorContext {\n  /** 出错的请求 */\n  request: HttpRequest;\n  /** 响应；网络错误、超时时没有 */\n  response?: Response;\n  /** 响应体（错误详情），读得到时带上 */\n  data?: unknown;\n  /** 底层的错误（网络错误、超时） */\n  cause?: unknown;\n}\n\n/** 请求失败：状态码不是 2xx、网络错误、超时，或 onResponse 判定的业务错误 */\nexport class HttpError extends Error {\n  /** 错误名，同类名：日志与 instanceof 之外的判断用 */\n  override readonly name = 'HttpError';\n  /** 出错的请求 */\n  readonly request: HttpRequest;\n  /** 响应；网络错误、超时时没有 */\n  readonly response?: Response;\n  /** HTTP 状态码；网络错误、超时为 0 */\n  readonly status: number;\n  /** 响应体（错误详情） */\n  readonly data?: unknown;\n\n  constructor(message: string, { request, response, data, cause }: HttpErrorContext) {\n    super(message, { cause });\n    this.request = request;\n    this.response = response;\n    this.status = response?.status ?? 0;\n    this.data = data;\n  }\n}\n\n/** 是不是主动取消（abort）造成的拒绝：界面上不当作错误 */\nexport const isAbortError = (error: unknown) =>\n  error instanceof DOMException && error.name === 'AbortError';\n\n/** createHttpClient 的选项 */\nexport interface HttpClientOptions {\n  /** 相对地址的前缀，如 '/api' */\n  baseURL?: string;\n  /** 每个请求都带的请求头 */\n  headers?: Readonly<Record<string, string>>;\n  /** 超时（毫秒），默认 30000；0 表示不限 */\n  timeout?: number;\n  /** 发出之前改请求（加令牌、追踪编号）；可以返回一个新的 Request */\n  onRequest?: (request: Request) => Request | void | Promise<Request | void>;\n  /** 2xx 响应解析后的数据交给它：拆掉后端的包装、判定业务错误（抛 HttpError），返回值就是请求的结果 */\n  onResponse?: (data: unknown, context: { request: HttpRequest; response: Response }) => unknown;\n  /**\n   * 线上的 typed JSON 怎样还原（见 wire.ts）：给 `{ decimal: Decimal }` 时 decimal 还原成 Decimal，`dates: 'objects'`\n   * 时日期还原成 CalendarDate 等；默认 `{}`（bigint 还原成 bigint，decimal 与日期留作文字）。false 时请求体按普通 JSON 发、响应不还原\n   */\n  wire?: WireReviveOptions | false;\n  /** 换掉 fetch（测试、SSR、注入公共处理） */\n  fetch?: typeof fetch;\n}\n\n/** createHttpClient 的结果：request 之外，再给常用方法的简写 */\nexport interface FetchClient extends HttpClient {\n  /** GET：参数写在 options.query 里 */\n  get<T = unknown>(url: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<T>;\n  /** DELETE */\n  delete<T = unknown>(url: string, options?: Omit<HttpRequest, 'url' | 'method'>): Promise<T>;\n  /** POST：普通对象的 body 按 JSON 发送 */\n  post<T = unknown>(\n    url: string,\n    body?: unknown,\n    options?: Omit<HttpRequest, 'url' | 'method' | 'body'>,\n  ): Promise<T>;\n  /** PUT：普通对象的 body 按 JSON 发送 */\n  put<T = unknown>(\n    url: string,\n    body?: unknown,\n    options?: Omit<HttpRequest, 'url' | 'method' | 'body'>,\n  ): Promise<T>;\n  /** PATCH：普通对象的 body 按 JSON 发送 */\n  patch<T = unknown>(\n    url: string,\n    body?: unknown,\n    options?: Omit<HttpRequest, 'url' | 'method' | 'body'>,\n  ): Promise<T>;\n}\n\n/** 原生 fetch 的薄封装（见文件开头） */\nexport function createHttpClient(options: HttpClientOptions = {}): FetchClient {\n  const {\n    baseURL = '',\n    timeout: defaultTimeout = 30_000,\n    onRequest,\n    onResponse,\n    wire = {},\n  } = options;\n\n  async function request<T>(spec: HttpRequest): Promise<T> {\n    const { method = 'GET', body, signal, timeout = defaultTimeout } = spec;\n    const headers = new Headers({ ...options.headers, ...spec.headers });\n    const json = isJsonBody(body);\n    if (json && !headers.has('content-type')) headers.set('content-type', 'application/json');\n    const signals = [signal, timeout > 0 ? AbortSignal.timeout(timeout) : undefined].filter(\n      (item): item is AbortSignal => item != null,\n    );\n    let prepared = new Request(buildUrl(baseURL, spec.url, spec.query), {\n      method,\n      headers,\n      body: json\n        ? JSON.stringify(wire === false ? body : toWire(body))\n        : (body as BodyInit | undefined),\n      signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],\n    });\n    prepared = (await onRequest?.(prepared)) ?? prepared;\n\n    let response: Response;\n    try {\n      response = await (options.fetch ?? fetch)(prepared);\n    } catch (cause) {\n      // 调用方取消的：原样交出（AbortError），界面据此不当作错误\n      if (signal?.aborted) throw cause;\n      const timedOut = cause instanceof DOMException && cause.name === 'TimeoutError';\n      const message = timedOut\n        ? `请求超时（${timeout / 1000} 秒）：${method} ${spec.url}`\n        : `网络错误：${method} ${spec.url}`;\n      throw new HttpError(message, { request: spec, cause });\n    }\n    const raw = await readBody(response, spec.responseType);\n    const data = wire === false ? raw : fromWire(raw, wire);\n    if (!response.ok) {\n      const status = `${response.status}${response.statusText ? ` ${response.statusText}` : ''}`;\n      throw new HttpError(`请求失败（${status}）：${method} ${spec.url}`, {\n        request: spec,\n        response,\n        data,\n      });\n    }\n    return (onResponse ? onResponse(data, { request: spec, response }) : data) as T;\n  }\n\n  const withBody =\n    (method: HttpMethod) =>\n    <T>(url: string, body?: unknown, rest?: Omit<HttpRequest, 'url' | 'method' | 'body'>) =>\n      request<T>({ ...rest, method, url, body });\n  return {\n    request,\n    get: (url, rest) => request({ ...rest, method: 'GET', url }),\n    delete: (url, rest) => request({ ...rest, method: 'DELETE', url }),\n    post: withBody('POST'),\n    put: withBody('PUT'),\n    patch: withBody('PATCH'),\n  };\n}\n\nlet fallback: FetchClient | undefined;\n\n/**\n * 当前配置的请求客户端（在 setup 里调用）：createUi / Provider 的 http；都没给时是一个默认的 createHttpClient()\n */\nexport function useHttp(): HttpClient {\n  return useConfig().http ?? (fallback ??= createHttpClient());\n}\n\n/** 地址 + query：相对地址拼在 baseURL 后面（斜杠不重复），null、undefined 的参数跳过 */\nfunction buildUrl(baseURL: string, url: string, query: HttpRequest['query']): string {\n  const absolute = /^[a-z][a-z\\d+.-]*:/i.test(url) || url.startsWith('//');\n  let full =\n    absolute || !baseURL ? url : `${baseURL.replace(/\\/+$/, '')}/${url.replace(/^\\/+/, '')}`;\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(query ?? {})) {\n    if (value == null) continue;\n    const items: readonly WireScalar[] = Array.isArray(value) ? value : [value as WireScalar];\n    for (const item of items) params.append(key, wireText(item));\n  }\n  const search = params.toString();\n  if (search) full += `${full.includes('?') ? '&' : '?'}${search}`;\n  return full;\n}\n\n/** 普通对象与数组按 JSON 发送 */\nfunction isJsonBody(body: unknown): boolean {\n  if (body == null || typeof body !== 'object') return false;\n  const prototype = Object.getPrototypeOf(body) as unknown;\n  return Array.isArray(body) || prototype === Object.prototype || prototype === null;\n}\n\nasync function readBody(response: Response, type: HttpRequest['responseType']): Promise<unknown> {\n  if (\n    response.status === 204 ||\n    response.status === 205 ||\n    response.headers.get('content-length') === '0'\n  ) {\n    return undefined;\n  }\n  const contentType = response.headers.get('content-type') ?? '';\n  const kind =\n    type ??\n    (/[/+]json\\b/.test(contentType) ? 'json' : contentType.startsWith('text/') ? 'text' : 'blob');\n  if (kind === 'blob') return response.blob();\n  const text = await response.text();\n  if (kind === 'text') return text;\n  if (text === '') return undefined;\n  try {\n    return JSON.parse(text);\n  } catch {\n    // 声明是 JSON 却解析不了（网关的 HTML 错误页）：交出原文，状态码错误里还能看到\n    return text;\n  }\n}\n"],"mappings":"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"}

package/dist/utils/request/use-request.d.ts

@@ -0,0 +1,37 @@
+/** useRequest 的选项 */
+export interface RequestOptions<P, T> {
+    /** 请求参数：读到的响应式值变了、且内容确实不同时重新请求；不写时只在开始与 refresh 时请求 */
+    params?: () => P;
+    /** 参数变了以后等多久再请求（毫秒），默认 0；refresh 不等 */
+    debounce?: number;
+    /** 一开始就请求，默认 true；false 时等调用 refresh（或参数变化） */
+    immediate?: boolean;
+    /** 重新请求时保留上一次的数据，默认 true；false 时请求一开始就清空 */
+    keepPrevious?: boolean;
+    /**
+     * 自动请求的开关（弹层打开时才请求这类）：为 false 时 immediate 与参数变化都不请求，refresh 照常。
+     * 变回 true 时不自动补一次，需要时调用 refresh
+     */
+    enabled?: () => boolean;
+    /** 成功后调用 */
+    onSuccess?: (data: T, params: P) => void;
+    /** 失败后调用（取消的不算） */
+    onError?: (error: unknown, params: P) => void;
+}
+/** useRequest 的返回值 */
+export interface RequestState<T> {
+    /** 最后一次成功的结果 */
+    readonly data: T | undefined;
+    /** 最后一次失败的原因；成功后清空 */
+    readonly error: unknown;
+    /** 正在请求（防抖等待时还不算） */
+    readonly loading: boolean;
+    /** 按当前参数立即请求，取消进行中的；返回结果，失败或被后来的请求顶掉时为 undefined */
+    refresh(): Promise<T | undefined>;
+    /** 取消进行中的请求与等着的防抖 */
+    cancel(): void;
+    /** 直接改数据（乐观更新、本地删掉一行），不发请求 */
+    mutate(data: T | undefined): void;
+}
+/** 请求的状态（在 setup 里调用；见文件开头） */
+export declare function useRequest<T, P = undefined>(fetcher: (params: P, signal: AbortSignal) => Promise<T>, options?: RequestOptions<P, T>): RequestState<T>;

package/dist/utils/request/use-request.js

@@ -0,0 +1,90 @@
+import { sameValue } from "../data/equality.js";
+import { isAbortError } from "./http.js";
+import { onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/request/use-request.ts
+/**
+* 一个请求的状态（参考 TanStack Query、alova 的 useWatcher）：只采用最后一次的结果，发新请求时取消上一次，
+* 参数变化防抖，重新请求时保留旧数据（表格不闪成空的）。
+*
+*   const http = useHttp();
+*   const users = useRequest(
+*     ({ keyword, page }, signal) => http.request<Page<User>>({ url: '/users', query: { keyword, page }, signal }),
+*     { params: () => ({ keyword, page }), debounce: 300 },
+*   );
+*   users.data?.rows; users.loading; users.error; users.refresh();
+*
+* 只在浏览器里自动请求：服务端渲染时 data 留空，等页面在浏览器里接管后再请求。
+*/
+/** 请求的状态（在 setup 里调用；见文件开头） */
+function useRequest(fetcher, options = {}) {
+	const { params, debounce = 0, immediate = true, keepPrevious = true } = options;
+	const data = shallowRef();
+	const error = shallowRef();
+	const loading = shallowRef(false);
+	let controller;
+	let timer;
+	let latest = 0;
+	const readParams = () => params?.();
+	let last = params ? readParams() : void 0;
+	function cancel() {
+		clearTimeout(timer);
+		latest++;
+		controller?.abort();
+		controller = void 0;
+		loading.value = false;
+	}
+	async function run(current) {
+		cancel();
+		last = current;
+		const id = latest;
+		const own = controller = new AbortController();
+		loading.value = true;
+		if (!keepPrevious) data.value = void 0;
+		try {
+			const result = await fetcher(current, own.signal);
+			if (id !== latest) return void 0;
+			data.value = result;
+			error.value = void 0;
+			options.onSuccess?.(result, current);
+			return result;
+		} catch (reason) {
+			if (id !== latest || isAbortError(reason)) return void 0;
+			error.value = reason;
+			options.onError?.(reason, current);
+			return;
+		} finally {
+			if (id === latest) {
+				loading.value = false;
+				controller = void 0;
+			}
+		}
+	}
+	if (params) watch(readParams, (next) => {
+		if (options.enabled?.() === false) return;
+		if (sameValue(next, last)) return;
+		last = next;
+		clearTimeout(timer);
+		if (debounce > 0) timer = setTimeout(() => void run(next), debounce);
+		else run(next);
+	});
+	if (immediate && options.enabled?.() !== false && typeof window !== "undefined") run(readParams());
+	onScopeDispose(cancel);
+	return {
+		get data() {
+			return data.value;
+		},
+		get error() {
+			return error.value;
+		},
+		get loading() {
+			return loading.value;
+		},
+		refresh: () => run(readParams()),
+		cancel,
+		mutate: (value) => data.value = value
+	};
+}
+//#endregion
+export { useRequest };
+
+//# sourceMappingURL=use-request.js.map

package/dist/utils/request/use-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-request.js","names":[],"sources":["../../../src/utils/request/use-request.ts"],"sourcesContent":["/**\n * 一个请求的状态（参考 TanStack Query、alova 的 useWatcher）：只采用最后一次的结果，发新请求时取消上一次，\n * 参数变化防抖，重新请求时保留旧数据（表格不闪成空的）。\n *\n *   const http = useHttp();\n *   const users = useRequest(\n *     ({ keyword, page }, signal) => http.request<Page<User>>({ url: '/users', query: { keyword, page }, signal }),\n *     { params: () => ({ keyword, page }), debounce: 300 },\n *   );\n *   users.data?.rows; users.loading; users.error; users.refresh();\n *\n * 只在浏览器里自动请求：服务端渲染时 data 留空，等页面在浏览器里接管后再请求。\n */\nimport { onScopeDispose, shallowRef, watch } from 'vue';\nimport { sameValue } from '../data/equality';\nimport { isAbortError } from './http';\n\n/** useRequest 的选项 */\nexport interface RequestOptions<P, T> {\n  /** 请求参数：读到的响应式值变了、且内容确实不同时重新请求；不写时只在开始与 refresh 时请求 */\n  params?: () => P;\n  /** 参数变了以后等多久再请求（毫秒），默认 0；refresh 不等 */\n  debounce?: number;\n  /** 一开始就请求，默认 true；false 时等调用 refresh（或参数变化） */\n  immediate?: boolean;\n  /** 重新请求时保留上一次的数据，默认 true；false 时请求一开始就清空 */\n  keepPrevious?: boolean;\n  /**\n   * 自动请求的开关（弹层打开时才请求这类）：为 false 时 immediate 与参数变化都不请求，refresh 照常。\n   * 变回 true 时不自动补一次，需要时调用 refresh\n   */\n  enabled?: () => boolean;\n  /** 成功后调用 */\n  onSuccess?: (data: T, params: P) => void;\n  /** 失败后调用（取消的不算） */\n  onError?: (error: unknown, params: P) => void;\n}\n\n/** useRequest 的返回值 */\nexport interface RequestState<T> {\n  /** 最后一次成功的结果 */\n  readonly data: T | undefined;\n  /** 最后一次失败的原因；成功后清空 */\n  readonly error: unknown;\n  /** 正在请求（防抖等待时还不算） */\n  readonly loading: boolean;\n  /** 按当前参数立即请求，取消进行中的；返回结果，失败或被后来的请求顶掉时为 undefined */\n  refresh(): Promise<T | undefined>;\n  /** 取消进行中的请求与等着的防抖 */\n  cancel(): void;\n  /** 直接改数据（乐观更新、本地删掉一行），不发请求 */\n  mutate(data: T | undefined): void;\n}\n\n/** 请求的状态（在 setup 里调用；见文件开头） */\nexport function useRequest<T, P = undefined>(\n  fetcher: (params: P, signal: AbortSignal) => Promise<T>,\n  options: RequestOptions<P, T> = {},\n): RequestState<T> {\n  const { params, debounce = 0, immediate = true, keepPrevious = true } = options;\n  const data = shallowRef<T>();\n  const error = shallowRef<unknown>();\n  const loading = shallowRef(false);\n  let controller: AbortController | undefined;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  // 每次请求一个编号：结果回来时不是最后一次的就丢掉（fetcher 没理会 signal 时也不会覆盖）\n  let latest = 0;\n  const readParams = () => params?.() as P;\n  // 上一次请求（或开始时）的参数：参数变了但与它相同时不再请求（refresh 之后侦听器又看到同一组参数）\n  let last = params ? readParams() : undefined;\n\n  function cancel() {\n    clearTimeout(timer);\n    latest++;\n    controller?.abort();\n    controller = undefined;\n    loading.value = false;\n  }\n\n  async function run(current: P): Promise<T | undefined> {\n    cancel();\n    last = current;\n    const id = latest;\n    const own = (controller = new AbortController());\n    loading.value = true;\n    if (!keepPrevious) data.value = undefined;\n    try {\n      const result = await fetcher(current, own.signal);\n      if (id !== latest) return undefined;\n      data.value = result;\n      error.value = undefined;\n      options.onSuccess?.(result, current);\n      return result;\n    } catch (reason) {\n      if (id !== latest || isAbortError(reason)) return undefined;\n      error.value = reason;\n      options.onError?.(reason, current);\n      return undefined;\n    } finally {\n      if (id === latest) {\n        loading.value = false;\n        controller = undefined;\n      }\n    }\n  }\n\n  if (params) {\n    watch(readParams, (next) => {\n      if (options.enabled?.() === false) return;\n      if (sameValue(next, last)) return;\n      last = next;\n      clearTimeout(timer);\n      if (debounce > 0) timer = setTimeout(() => void run(next), debounce);\n      else void run(next);\n    });\n  }\n  if (immediate && options.enabled?.() !== false && typeof window !== 'undefined') {\n    void run(readParams());\n  }\n  onScopeDispose(cancel);\n\n  return {\n    get data() {\n      return data.value;\n    },\n    get error() {\n      return error.value;\n    },\n    get loading() {\n      return loading.value;\n    },\n    refresh: () => run(readParams()),\n    cancel,\n    mutate: (value) => (data.value = value),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAuDA,SAAgB,WACd,SACA,UAAgC,CAAC,GAChB;CACjB,MAAM,EAAE,QAAQ,WAAW,GAAG,YAAY,MAAM,eAAe,SAAS;CACxE,MAAM,OAAO,WAAc;CAC3B,MAAM,QAAQ,WAAoB;CAClC,MAAM,UAAU,WAAW,KAAK;CAChC,IAAI;CACJ,IAAI;CAEJ,IAAI,SAAS;CACb,MAAM,mBAAmB,SAAS;CAElC,IAAI,OAAO,SAAS,WAAW,IAAI,KAAA;CAEnC,SAAS,SAAS;EAChB,aAAa,KAAK;EAClB;EACA,YAAY,MAAM;EAClB,aAAa,KAAA;EACb,QAAQ,QAAQ;CAClB;CAEA,eAAe,IAAI,SAAoC;EACrD,OAAO;EACP,OAAO;EACP,MAAM,KAAK;EACX,MAAM,MAAO,aAAa,IAAI,gBAAgB;EAC9C,QAAQ,QAAQ;EAChB,IAAI,CAAC,cAAc,KAAK,QAAQ,KAAA;EAChC,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,SAAS,IAAI,MAAM;GAChD,IAAI,OAAO,QAAQ,OAAO,KAAA;GAC1B,KAAK,QAAQ;GACb,MAAM,QAAQ,KAAA;GACd,QAAQ,YAAY,QAAQ,OAAO;GACnC,OAAO;EACT,SAAS,QAAQ;GACf,IAAI,OAAO,UAAU,aAAa,MAAM,GAAG,OAAO,KAAA;GAClD,MAAM,QAAQ;GACd,QAAQ,UAAU,QAAQ,OAAO;GACjC;EACF,UAAU;GACR,IAAI,OAAO,QAAQ;IACjB,QAAQ,QAAQ;IAChB,aAAa,KAAA;GACf;EACF;CACF;CAEA,IAAI,QACF,MAAM,aAAa,SAAS;EAC1B,IAAI,QAAQ,UAAU,MAAM,OAAO;EACnC,IAAI,UAAU,MAAM,IAAI,GAAG;EAC3B,OAAO;EACP,aAAa,KAAK;EAClB,IAAI,WAAW,GAAG,QAAQ,iBAAiB,KAAK,IAAI,IAAI,GAAG,QAAQ;OAC9D,IAAS,IAAI;CACpB,CAAC;CAEH,IAAI,aAAa,QAAQ,UAAU,MAAM,SAAS,OAAO,WAAW,aAClE,IAAS,WAAW,CAAC;CAEvB,eAAe,MAAM;CAErB,OAAO;EACL,IAAI,OAAO;GACT,OAAO,KAAK;EACd;EACA,IAAI,QAAQ;GACV,OAAO,MAAM;EACf;EACA,IAAI,UAAU;GACZ,OAAO,QAAQ;EACjB;EACA,eAAe,IAAI,WAAW,CAAC;EAC/B;EACA,SAAS,UAAW,KAAK,QAAQ;CACnC;AACF"}

package/dist/utils/request/wire.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 线上的 typed JSON（与 query 库的 @zerodep-dev/wire、Java 的 org.dpdns.zerodep.wire 同一套写法）：bigint、Decimal、
+ * 日期、时间、字节等 JSON 不能原样承载的值写成文字，根对象上的 `$types` 记下它们的位置（路径 → 种类），对方据此还原。
+ * createHttpClient 默认就用它：请求体经 toWire 发出，带 `$types` 的响应经 fromWire 还原，地址栏参数经 wireText 写成文字。
+ *
+ *   toWire({ id: 9007199254740993n, amount: new Decimal('12.50'), on: new CalendarDate(2024, 1, 31) })
+ *   // { id: '9007199254740993', amount: '12.5', on: '2024-01-31', $types: { id: 'bigint', amount: 'decimal', on: 'date' } }
+ *
+ * 种类与文字：bigint 是十进制整数，decimal 不用科学计数法，double 只有 NaN / ±Infinity 写成文字，date 'YYYY-MM-DD'、
+ * time 'HH:mm:ss'、timestamp 'YYYY-MM-DDTHH:mm:ss[.fff]'、timestamptz 换算成 UTC 带 Z，bytes 是标准 base64。
+ * 路径从根开始用点连接属性名，数组不占一段（`rows.amount` 是每一行的 amount），属性名里的 ~ 与 . 写成 ~0、~1。
+ *
+ * 还原的默认值跟组件的约定走：bigint 还原成 bigint；decimal 在给了 Decimal 构造函数时还原成 Decimal，否则留作十进制文字
+ * （DataTable 的数字列、NumberField 都认）；日期与时间留作 ISO 文字（组件对外的值就是它），dates: 'objects' 时还原成
+ * CalendarDate、Time、CalendarDateTime、ZonedDateTime。这里不在运行时导入 decimal.js（同 numeric.ts）。
+ */
+import { CalendarDate, CalendarDateTime, Time, ZonedDateTime } from '@internationalized/date';
+import type Decimal from 'decimal.js';
+/** 线上要还原的值的种类 */
+export type WireType = 'bigint' | 'decimal' | 'double' | 'date' | 'time' | 'timestamp' | 'timestamptz' | 'bytes';
+/** 根对象上的类型表：路径 → 种类 */
+export type WireTypes = Record<string, WireType>;
+/** 能写成线上文字的单个值（地址栏参数、表头筛选） */
+export type WireScalar = string | number | boolean | bigint | Decimal | CalendarDate | CalendarDateTime | ZonedDateTime | Time | Date | null | undefined;
+/** fromWire 怎样还原 */
+export interface WireReviveOptions {
+    /** 还原 decimal 用的构造函数（decimal.js 的 Decimal 或它 clone 出来的）；不给时 decimal 留作十进制文字 */
+    decimal?: new (text: string) => Decimal;
+    /** 日期与时间：'iso' 留作 ISO 文字（默认），'objects' 还原成 CalendarDate、Time、CalendarDateTime、ZonedDateTime */
+    dates?: 'iso' | 'objects';
+    /** 'objects' 时 timestamptz 还原到哪个时区，默认浏览器的时区 */
+    timeZone?: string;
+}
+/**
+ * 一个值写成线上的文字：地址栏参数、表头筛选都用它。Decimal 不用科学计数法，日期与时间是 ISO 写法，
+ * 带时区的时刻换算成 UTC；null、undefined 是空字符串
+ */
+export declare function wireText(value: WireScalar): string;
+/**
+ * 把值写成线上的 JSON：要还原的值写成文字，根对象上加 `$types`；没有这样的值时就是普通 JSON。
+ * 对象取自身可枚举的属性（undefined 与函数跳过），有 toJSON 的先调用它；同一路径上既有文字又有 Decimal 这类值时报错
+ */
+export declare function toWire(value: unknown): unknown;
+/**
+ * 读线上的 JSON：按根上的 `$types` 还原（见文件开头的默认值），去掉 `$types`，`{ $value, $types }` 拆成里面的值；
+ * 没有 `$types` 时原样返回。就地改写传入的对象（通常刚由 JSON.parse 得到）
+ */
+export declare function fromWire<T = unknown>(json: unknown, options?: WireReviveOptions): T;