@kine-design/crud 0.0.1-beta.2 → 0.0.1-beta.21

package/composables/request/controlGate.ts

@@ -0,0 +1,143 @@
+/**
+ * @description 控制门 — 防抖/节流/去重
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { ControlPolicy, RequestMethod } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// CacheKey 生成
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 根据请求方法、URL 和参数生成唯一的缓存 key */
+export function buildCacheKey(method: RequestMethod, url: string, body?: unknown): string {
+  const bodyStr = body !== undefined && body !== null ? stableStringify(body) : '';
+  return `${method}:${url}:${bodyStr}`;
+}
+
+/** 稳定 JSON 序列化（key 排序），确保相同对象生成相同字符串 */
+function stableStringify(obj: unknown): string {
+  if (obj === null || obj === undefined) return '';
+  if (typeof obj !== 'object') return String(obj);
+  if (obj instanceof FormData || obj instanceof Blob || obj instanceof File) return '';
+  if (Array.isArray(obj)) return `[${obj.map(stableStringify).join(',')}]`;
+
+  const sorted = Object.keys(obj as Record<string, unknown>).sort();
+  const pairs = sorted.map(k => `${JSON.stringify(k)}:${stableStringify((obj as Record<string, unknown>)[k])}`);
+  return `{${pairs.join(',')}}`;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// ControlGate
+// ────────────────────────────────────────────────────────────────────────────
+
+interface DebounceEntry {
+  timer: ReturnType<typeof setTimeout>;
+  reject: (reason: Error) => void;
+}
+
+export class ControlGate {
+  /** 防抖：取消前一个 timer */
+  private debounceMap = new Map<string, DebounceEntry>();
+  /** 节流：记录上次执行时间 */
+  private throttleMap = new Map<string, number>();
+  /** 去重：共享同一个 Promise */
+  private deduplicateMap = new Map<string, Promise<unknown>>();
+
+  /**
+   * 通过控制门执行请求。
+   * 按配置依次应用防抖、节流、去重策略。
+   */
+  async execute<T>(key: string, fn: () => Promise<T>, policy: ControlPolicy): Promise<T> {
+    // 防抖
+    if (policy.debounce !== undefined && policy.debounce > 0) {
+      return this.withDebounce(key, fn, policy.debounce);
+    }
+
+    // 节流
+    if (policy.throttle !== undefined && policy.throttle > 0) {
+      await this.waitThrottle(key, policy.throttle);
+    }
+
+    // 去重
+    if (policy.deduplicate) {
+      return this.withDeduplicate(key, fn) as Promise<T>;
+    }
+
+    return fn();
+  }
+
+  /** 清理所有挂起的 timer 和状态 */
+  dispose(): void {
+    for (const entry of this.debounceMap.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error('ControlGate 已销毁'));
+    }
+    this.debounceMap.clear();
+    this.throttleMap.clear();
+    this.deduplicateMap.clear();
+  }
+
+  // ── 防抖 ──────────────────────────────────────────────────────────────────
+
+  private withDebounce<T>(key: string, fn: () => Promise<T>, delay: number): Promise<T> {
+    // 取消前一个 pending 请求
+    const prev = this.debounceMap.get(key);
+    if (prev) {
+      clearTimeout(prev.timer);
+      prev.reject(new Error('请求已被防抖取消'));
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(async () => {
+        this.debounceMap.delete(key);
+        try {
+          resolve(await fn());
+        } catch (e) {
+          reject(e);
+        }
+      }, delay);
+
+      this.debounceMap.set(key, { timer, reject });
+    });
+  }
+
+  // ── 节流 ──────────────────────────────────────────────────────────────────
+
+  private waitThrottle(key: string, interval: number): Promise<void> {
+    const lastTime = this.throttleMap.get(key) ?? 0;
+    const now = Date.now();
+    const elapsed = now - lastTime;
+
+    if (elapsed >= interval) {
+      this.throttleMap.set(key, now);
+      return Promise.resolve();
+    }
+
+    const waitTime = interval - elapsed;
+    return new Promise(resolve => {
+      setTimeout(() => {
+        this.throttleMap.set(key, Date.now());
+        resolve();
+      }, waitTime);
+    });
+  }
+
+  // ── 去重 ──────────────────────────────────────────────────────────────────
+
+  private withDeduplicate<T>(key: string, fn: () => Promise<T>): Promise<unknown> {
+    const existing = this.deduplicateMap.get(key);
+    if (existing) return existing;
+
+    const promise = fn().finally(() => {
+      this.deduplicateMap.delete(key);
+    });
+
+    this.deduplicateMap.set(key, promise);
+    return promise;
+  }
+}

package/composables/request/createRequest.ts

@@ -0,0 +1,173 @@
+/**
+ * @description 请求客户端工厂
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { RequestMethod, RequestOptions } from './types';
+import { ControlGate } from './controlGate';
+import { FetchTransport } from './transport/fetchTransport';
+import { RequestBuilder, type RequestBuilderContext } from './requestBuilder';
+
+// ────────────────────────────────────────────────────────────────────────────
+// RequestClient
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface RequestClient {
+  /** 请求基础 URL */
+  readonly baseURL: string;
+  /** 简便方法，直接返回 Promise<T> */
+  send<T>(method: RequestMethod, url: string, body?: unknown): Promise<T>;
+  /** GET 请求 */
+  get<T>(url: string, params?: Record<string, unknown>): Promise<T>;
+  /** POST 请求 */
+  post<T>(url: string, body?: unknown): Promise<T>;
+  /** PUT 请求 */
+  put<T>(url: string, body?: unknown): Promise<T>;
+  /** PATCH 请求 */
+  patch<T>(url: string, body?: unknown): Promise<T>;
+  /** DELETE 请求 */
+  delete<T>(url: string, body?: unknown): Promise<T>;
+  /** 返回 RequestBuilder，支持链式配置 */
+  request(method: RequestMethod, url: string, body?: unknown): RequestBuilder;
+  /** 注册 AbortController，供外部管理请求取消 */
+  registerAbortController(controller: AbortController): void;
+  /** 取消所有 pending 请求 */
+  abortAll(): void;
+  /** 销毁客户端，清理所有资源 */
+  dispose(): void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createRequest
+// ────────────────────────────────────────────────────────────────────────────
+
+export function createRequest(options: RequestOptions = {}): RequestClient {
+  const transport = options.transport ?? new FetchTransport();
+  const controlGate = new ControlGate();
+  const abortControllers = new Set<AbortController>();
+
+  const context: RequestBuilderContext = {
+    transport,
+    controlGate,
+    baseURL: options.baseURL ?? '',
+    defaultHeaders: options.headers ?? {},
+    getToken: options.getToken,
+    onUnauthorized: options.onUnauthorized,
+    responseInterceptor: options.responseInterceptor,
+    feedback: options.feedback,
+    registerAbort: (controller: AbortController) => {
+      abortControllers.add(controller);
+      // 完成后自动移除
+      const originalAbort = controller.abort.bind(controller);
+      controller.abort = (reason?: unknown) => {
+        abortControllers.delete(controller);
+        return originalAbort(reason);
+      };
+    },
+  };
+
+  function createBuilder(method: RequestMethod, url: string, body?: unknown): RequestBuilder {
+    const builder = new RequestBuilder(context, method, url, body);
+
+    // 应用默认配置
+    const dc = options.defaultConfig;
+    if (dc?.cache) builder.cache(dc.cache);
+    if (dc?.retry) builder.retry(dc.retry);
+    if (dc?.timeout) builder.timeout(dc.timeout);
+    if (dc?.totalTimeout) builder.totalTimeout(dc.totalTimeout);
+    if (dc?.lifecycle) builder.lifecycle(dc.lifecycle);
+    if (dc?.control?.debounce) builder.debounce(dc.control.debounce);
+    if (dc?.control?.throttle) builder.throttle(dc.control.throttle);
+    if (dc?.control?.deduplicate) builder.deduplicate(dc.control.deduplicate);
+
+    return builder;
+  }
+
+  const client: RequestClient = {
+    baseURL: context.baseURL,
+
+    send: <T>(method: RequestMethod, url: string, body?: unknown) =>
+      createBuilder(method, url, body).execute<T>(),
+
+    get: <T>(url: string, params?: Record<string, unknown>) =>
+      createBuilder('GET', url, params).execute<T>(),
+
+    post: <T>(url: string, body?: unknown) =>
+      createBuilder('POST', url, body).execute<T>(),
+
+    put: <T>(url: string, body?: unknown) =>
+      createBuilder('PUT', url, body).execute<T>(),
+
+    patch: <T>(url: string, body?: unknown) =>
+      createBuilder('PATCH', url, body).execute<T>(),
+
+    delete: <T>(url: string, body?: unknown) =>
+      createBuilder('DELETE', url, body).execute<T>(),
+
+    request: (method: RequestMethod, url: string, body?: unknown) =>
+      createBuilder(method, url, body),
+
+    registerAbortController: (controller: AbortController) => {
+      abortControllers.add(controller);
+    },
+
+    abortAll: () => {
+      for (const controller of abortControllers) {
+        controller.abort('客户端取消所有请求');
+      }
+      abortControllers.clear();
+    },
+
+    dispose: () => {
+      client.abortAll();
+      controlGate.dispose();
+    },
+  };
+
+  return client;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 预设工厂
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 默认配置：适用于大多数场景 */
+export function createDefaultRequest(options: RequestOptions = {}): RequestClient {
+  return createRequest({
+    ...options,
+    defaultConfig: {
+      retry: { type: 'exponential', maxAttempts: 3, initialDelay: 300, multiplier: 2, maxDelay: 5000 },
+      timeout: 30000,
+      ...options.defaultConfig,
+    },
+  });
+}
+
+/** 严格配置：无重试、短超时 */
+export function createStrictRequest(options: RequestOptions = {}): RequestClient {
+  return createRequest({
+    ...options,
+    defaultConfig: {
+      retry: { type: 'none' },
+      timeout: 10000,
+      ...options.defaultConfig,
+    },
+  });
+}
+
+/** 宽松配置：多重试、长超时 */
+export function createPermissiveRequest(options: RequestOptions = {}): RequestClient {
+  return createRequest({
+    ...options,
+    defaultConfig: {
+      retry: { type: 'exponential', maxAttempts: 5, initialDelay: 500, multiplier: 2, maxDelay: 30000 },
+      timeout: 60000,
+      totalTimeout: 120000,
+      ...options.defaultConfig,
+    },
+  });
+}

package/composables/request/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @description 请求模块统一导出
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+// ── 类型导出 ──────────────────────────────────────────────────────────────
+
+export type {
+  RequestMethod,
+  ControlPolicy,
+  CachePolicy,
+  RetryPolicy,
+  Lifecycle,
+  RequestConfig,
+  WrappedResponse,
+  NetworkError,
+  UserFeedbackHandler,
+  Transport,
+  TransportRequest,
+  TransportResponse,
+  RequestOptions,
+  OrchestratorNode,
+  FailureStrategy,
+  UploadOptions,
+  UploaderOptions,
+} from './types';
+
+export { BusinessError, NetworkRequestError } from './types';
+
+// ── 控制门 ────────────────────────────────────────────────────────────────
+
+export { ControlGate, buildCacheKey } from './controlGate';
+
+// ── 传输层 ────────────────────────────────────────────────────────────────
+
+export { FetchTransport } from './transport/fetchTransport';
+export { XhrTransport } from './transport/xhrTransport';
+
+// ── 请求构建器 ──────────────────────────────────────────────────────────────
+
+export { RequestBuilder } from './requestBuilder';
+export type { RequestBuilderContext } from './requestBuilder';
+
+// ── 请求客户端 ──────────────────────────────────────────────────────────────
+
+export {
+  createRequest,
+  createDefaultRequest,
+  createStrictRequest,
+  createPermissiveRequest,
+} from './createRequest';
+export type { RequestClient } from './createRequest';
+
+// ── 编排器 ────────────────────────────────────────────────────────────────
+
+export { orchestrate, createNode, after } from './orchestrator';
+export type { OrchestratorResult } from './orchestrator';
+
+// ── Vue Composables ────────────────────────────────────────────────────────
+
+export { useRequest, usePolling, useBatchLoader } from './composables';
+export type { UsePollingReturn, BatchLoaderOptions, UseBatchLoaderReturn } from './composables';
+
+// ── 上传 ──────────────────────────────────────────────────────────────────
+
+export { createUploader } from './upload';
+export type { UploadHandle, Uploader } from './upload';

package/composables/request/orchestrator.ts

@@ -0,0 +1,145 @@
+/**
+ * @description DAG 编排器 — 拓扑排序 + 分层并发执行
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { FailureStrategy, OrchestratorNode } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 编排结果
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface OrchestratorResult {
+  /** 所有成功节点的结果 */
+  results: Map<string, unknown>;
+  /** 失败节点的错误（仅 continueOnError 模式下存在） */
+  errors: Map<string, Error>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 拓扑排序
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 拓扑排序，返回按层分组的节点 ID */
+function topologicalSort(nodes: OrchestratorNode[]): string[][] {
+  const nodeMap = new Map(nodes.map(n => [n.id, n]));
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+
+  // 初始化
+  for (const node of nodes) {
+    inDegree.set(node.id, 0);
+    adjacency.set(node.id, []);
+  }
+
+  // 构建入度表和邻接表
+  for (const node of nodes) {
+    for (const dep of node.dependencies) {
+      if (!nodeMap.has(dep)) {
+        throw new Error(`[orchestrator] 节点 "${node.id}" 依赖的 "${dep}" 不存在`);
+      }
+      adjacency.get(dep)!.push(node.id);
+      inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+    }
+  }
+
+  // BFS 分层
+  const layers: string[][] = [];
+  let queue = nodes.filter(n => inDegree.get(n.id) === 0).map(n => n.id);
+
+  while (queue.length > 0) {
+    layers.push([...queue]);
+    const nextQueue: string[] = [];
+
+    for (const id of queue) {
+      for (const neighbor of adjacency.get(id)!) {
+        const degree = inDegree.get(neighbor)! - 1;
+        inDegree.set(neighbor, degree);
+        if (degree === 0) {
+          nextQueue.push(neighbor);
+        }
+      }
+    }
+
+    queue = nextQueue;
+  }
+
+  // 检测循环依赖
+  const totalSorted = layers.reduce((sum, layer) => sum + layer.length, 0);
+  if (totalSorted !== nodes.length) {
+    throw new Error('[orchestrator] 检测到循环依赖');
+  }
+
+  return layers;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// orchestrate
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 执行 DAG 编排。
+ * 拓扑排序 → 分层 → 同层 Promise.all 并发 → 收集结果。
+ */
+export async function orchestrate(
+  nodes: OrchestratorNode[],
+  failureStrategy: FailureStrategy = 'failFast',
+): Promise<OrchestratorResult> {
+  if (nodes.length === 0) {
+    return { results: new Map(), errors: new Map() };
+  }
+
+  const nodeMap = new Map(nodes.map(n => [n.id, n]));
+  const layers = topologicalSort(nodes);
+  const results = new Map<string, unknown>();
+  const errors = new Map<string, Error>();
+
+  for (const layer of layers) {
+    const tasks = layer.map(async (id) => {
+      const node = nodeMap.get(id)!;
+      try {
+        const result = await node.execute();
+        results.set(id, result);
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        errors.set(id, error);
+
+        if (failureStrategy === 'failFast') {
+          throw error;
+        }
+      }
+    });
+
+    if (failureStrategy === 'failFast') {
+      await Promise.all(tasks);
+    } else {
+      await Promise.allSettled(tasks);
+    }
+  }
+
+  return { results, errors };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 辅助：节点构建
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 创建编排节点 */
+export function createNode<T>(
+  id: string,
+  execute: () => Promise<T>,
+  dependencies: string[] = [],
+): OrchestratorNode<T> {
+  return { id, execute, dependencies };
+}
+
+/** 声明依赖关系 — 返回带有 dependencies 的节点配置 */
+export function after(...deps: string[]) {
+  return <T>(id: string, execute: () => Promise<T>): OrchestratorNode<T> => {
+    return { id, execute, dependencies: deps };
+  };
+}