@lynx-go/ui-kit 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@lynx-go/ui-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Headless core for data-dense console UIs — Query / Command / Subscription over TanStack engines",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/react/index.ts",
+      "default": "./src/react/index.ts"
+    },
+    "./kernel": {
+      "types": "./src/kernel/index.ts",
+      "default": "./src/kernel/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema/index.ts",
+      "default": "./src/schema/index.ts"
+    },
+    "./adapters": {
+      "types": "./src/adapters/index.ts",
+      "default": "./src/adapters/index.ts"
+    },
+    "./react": {
+      "types": "./src/react/index.ts",
+      "default": "./src/react/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "effect": "~4.0.6"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "@tanstack/react-query": ">=5.100",
+    "@tanstack/react-router": ">=1.120",
+    "@tanstack/react-form": ">=1.30"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.104.5",
+    "@tanstack/react-router": "^1.170.46",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^5.0.5",
+    "@tanstack/react-form": "^1.33.5"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  }
 }

package/src/adapters/evaluate.ts

@@ -0,0 +1,20 @@
+import type { CollectionQuery, ResourceScope, Segment } from "../kernel";
+import { evaluateQuery } from "../kernel";
+
+export { decodeClientCursor, encodeClientCursor, evaluateQuery } from "../kernel";
+
+/**
+ * clientCollection —— 客户端求值方言（求值策略，非概念）。
+ *
+ * 整取 fetchAll 后本地求值谓词/排序/窗口，伪造不透明游标（offset 编进 token），
+ * 兑现"游标进 URL、历史即分页栈"。fetchAll 的取数上限由消费方持有
+ * （fleetly 现状：projects=100 / apps=200 / deployments=50 参差，适配器常量）。
+ */
+export function clientCollection<T>(
+  fetchAll: (ctx: ResourceScope, signal?: AbortSignal) => Promise<ReadonlyArray<T>>,
+): (query: CollectionQuery, ctx: ResourceScope, signal?: AbortSignal) => Promise<Segment<T>> {
+  return async (query, ctx, signal) => {
+    const rows = await fetchAll(ctx, signal);
+    return evaluateQuery(query, rows);
+  };
+}

package/src/adapters/http.ts

@@ -0,0 +1,217 @@
+import { Data, Effect } from "effect";
+import { type ApiError, isApiError } from "../kernel";
+
+/**
+ * 缝 1 —— http 管线（Effect 住在缝里，Promise 站在边界上）。
+ *
+ * - 网络断层 = typed failure（HttpFailure/NetworkFailure → ApiError），defect 只留程序错误；
+ * - runApi 是唯一 Effect→Promise 边界：mapError 归一为 ApiError，defect 包裹上报，interrupt 放行；
+ * - 401 闭环：管线内先走 onUnauthorized（单飞由实现方保证），仍失败才以 ApiError.auth 出界。
+ */
+
+export class HttpFailure extends Data.TaggedError("HttpFailure")<{
+  readonly status: number;
+  readonly body?: unknown;
+}> {}
+
+export class NetworkFailure extends Data.TaggedError("NetworkFailure")<{
+  readonly cause?: unknown;
+}> {}
+
+type AdapterFailure = HttpFailure | NetworkFailure;
+
+function extractMessage(body: unknown): string | undefined {
+  if (typeof body === "object" && body !== null) {
+    const record = body as Record<string, unknown>;
+    if (typeof record.message === "string") return record.message;
+    if (typeof record.error === "object" && record.error !== null) {
+      const inner = (record.error as Record<string, unknown>).message;
+      if (typeof inner === "string") return inner;
+    }
+  }
+  return undefined;
+}
+
+function toApiError(failure: AdapterFailure): ApiError {
+  switch (failure._tag) {
+    case "NetworkFailure":
+      return { kind: "network", ...(failure.cause !== undefined ? { cause: failure.cause } : {}) };
+    case "HttpFailure": {
+      const { status, body } = failure;
+      if (status === 401) return { kind: "auth" };
+      if (status === 403) return { kind: "forbidden" };
+      if (status === 404) return { kind: "not-found" };
+      return {
+        kind: "server",
+        status,
+        ...(extractMessage(body) ? { message: extractMessage(body) } : {}),
+      };
+    }
+  }
+}
+
+/** 唯一边界：所有 Effect→Promise 只经它。 */
+export function runApi<A>(eff: Effect.Effect<A, AdapterFailure>): Promise<A> {
+  return Effect.runPromise(Effect.mapError(eff, toApiError)).catch(
+    (err: unknown) =>
+      new Promise<A>((_resolve, reject) => {
+        if (isApiError(err)) {
+          reject(err);
+          return;
+        }
+        // defect（程序错误）——归一为可观测的包装，不混入 ApiError 封闭集
+        reject(new Error("fleet-ui: unexpected defect in adapter pipeline", { cause: err }));
+      }),
+  );
+}
+
+export interface HttpOptions {
+  baseUrl?: string;
+  /** 401 handler 注册点（工厂参数，非全局 provider）。签名符合"清凭证+清缓存+跳登录"。 */
+  onUnauthorized?: () => void | Promise<void>;
+}
+
+export type QueryParams = Record<string, string | number | boolean | ReadonlyArray<string>>;
+
+export interface HttpRequest {
+  params?: QueryParams;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  /** 运行时解码（Effect Schema transform 接入点；缺省直通 as T） */
+  decode?: (raw: unknown) => unknown;
+}
+
+function buildUrl(baseUrl: string | undefined, path: string, params?: QueryParams): string {
+  const url = baseUrl ? `${baseUrl}${path}` : path;
+  if (!params) return url;
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) search.append(key, item); // repeated key=a&key=b（gateway 方言）
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const qs = search.toString();
+  return qs ? `${url}?${qs}` : url;
+}
+
+export function createHttp(options: HttpOptions = {}) {
+  function requestJson(
+    path: string,
+    init: RequestInit & { params?: QueryParams },
+  ): Effect.Effect<unknown, AdapterFailure> {
+    const url = buildUrl(options.baseUrl, path, init.params);
+    return Effect.tryPromise({
+      // 注意 arity 陷阱：单参数 signal（v4 按函数 length 探测）
+      try: (signal) => fetch(url, { ...init, signal: init.signal ?? signal }),
+      catch: (cause) => new NetworkFailure({ cause }),
+    }).pipe(
+      Effect.flatMap((response) =>
+        Effect.suspend((): Effect.Effect<unknown, AdapterFailure> => {
+          if (!response.ok) {
+            return readBody(response).pipe(
+              Effect.flatMap((body) => {
+                const failure: AdapterFailure = new HttpFailure({
+                  status: response.status,
+                  ...(body !== undefined ? { body } : {}),
+                });
+                if (response.status === 401 && options.onUnauthorized) {
+                  // 401 闭环：管线内先行 handler，仍失败才以 failure 出界
+                  return Effect.tryPromise({
+                    try: async () => {
+                      await options.onUnauthorized?.();
+                    },
+                    catch: () => failure,
+                  }).pipe(Effect.flatMap(() => Effect.fail(failure)));
+                }
+                return Effect.fail(failure);
+              }),
+            );
+          }
+          return Effect.tryPromise({
+            try: () => response.json(),
+            catch: () =>
+              new HttpFailure({
+                status: response.status,
+                body: { message: `fleet-ui: response is not JSON (${path})` },
+              }) as AdapterFailure,
+          });
+        }),
+      ),
+    );
+  }
+
+  function readBody(response: Response): Effect.Effect<unknown, AdapterFailure> {
+    return Effect.tryPromise({
+      try: () => response.json(),
+      catch: () => undefined,
+    }).pipe(Effect.orElseSucceed(() => undefined));
+  }
+
+  async function request<T>(
+    method: string,
+    path: string,
+    req: HttpRequest & { body?: unknown },
+  ): Promise<T> {
+    const headers: Record<string, string> = { ...req.headers };
+    let body: BodyInit | undefined;
+    if (req.body !== undefined) {
+      headers["Content-Type"] ??= "application/json";
+      body = JSON.stringify(req.body);
+    }
+    const raw = await runApi(
+      requestJson(path, {
+        method,
+        headers,
+        ...(body !== undefined ? { body } : {}),
+        ...(req.params ? { params: req.params } : {}),
+        ...(req.signal ? { signal: req.signal } : {}),
+      }),
+    );
+    return (req.decode ? req.decode(raw) : raw) as T;
+  }
+
+  return {
+    get: <T>(path: string, req: HttpRequest = {}) => request<T>("GET", path, req),
+    post: <T>(path: string, body: unknown, req: HttpRequest = {}) =>
+      request<T>("POST", path, { ...req, body }),
+    put: <T>(path: string, body: unknown, req: HttpRequest = {}) =>
+      request<T>("PUT", path, { ...req, body }),
+    del: <T>(path: string, req: HttpRequest = {}) => request<T>("DELETE", path, req),
+    /** raw body 命令（tar 裸上传 / FormData 分片）+ raw response 逃生口（Blob 下载不过 decode）。 */
+    async sendRaw<T>(
+      path: string,
+      body: BodyInit,
+      contentType?: string,
+      req: HttpRequest = {},
+    ): Promise<T> {
+      const headers = { ...req.headers, ...(contentType ? { "Content-Type": contentType } : {}) };
+      const raw = await runApi(
+        requestJson(path, {
+          method: "POST",
+          headers,
+          body,
+          ...(req.signal ? { signal: req.signal } : {}),
+        }),
+      );
+      return (req.decode ? req.decode(raw) : raw) as T;
+    },
+    /** 非 JSON 响应面（Blob 下载/文件预览）——完全绕过 decode。 */
+    async getBlob(path: string, req: HttpRequest = {}): Promise<Blob> {
+      const url = buildUrl(options.baseUrl, path, req.params);
+      const response = await fetch(url, {
+        headers: req.headers,
+        ...(req.signal ? { signal: req.signal } : {}),
+      });
+      if (!response.ok) {
+        const failure = toApiError(new HttpFailure({ status: response.status }));
+        throw failure;
+      }
+      return response.blob();
+    },
+  };
+}
+
+export type Http = ReturnType<typeof createHttp>;

package/src/adapters/index.ts

@@ -0,0 +1,45 @@
+export {
+  clientCollection,
+  decodeClientCursor,
+  encodeClientCursor,
+  evaluateQuery,
+} from "./evaluate";
+export {
+  createHttp,
+  type Http,
+  HttpFailure,
+  type HttpOptions,
+  type HttpRequest,
+  NetworkFailure,
+  type QueryParams,
+  runApi,
+} from "./http";
+export {
+  type MockCollection,
+  type MockCollectionOptions,
+  type MockDialect,
+  type MockHandle,
+  mockCollection,
+  mockFetchAll,
+} from "./mock";
+export {
+  type MockTransport,
+  type MockTransportHandle,
+  type MockTransportOptions,
+  mockSeqTransport,
+  mockTransport,
+} from "./mock-transport";
+export {
+  createSubscriptionEngine,
+  type SubscriptionEngine,
+  type SubscriptionEngineOptions,
+  type SubscriptionHandle,
+  type SubscriptionState,
+} from "./subscription";
+export {
+  type NdjsonTransportOptions,
+  ndjsonTransport,
+  type SseMessage,
+  type SseTransportOptions,
+  sseTransport,
+} from "./transport";

package/src/adapters/mock-transport.ts

@@ -0,0 +1,179 @@
+import type { ApiError, Cursor, FrameSource, Transport } from "../kernel";
+
+/**
+ * mockTransport —— Transport 契约的内存实现（测试工具 + demo 数据源）。
+ *
+ * 命令式控制（emit/interrupt/close/failNext）作用于**当前连接**（最近一次 open）；
+ * 控制落在已被引擎 abort 的死连接上时静默丢弃——现实语义：重连间隙发出的帧就是丢了。
+ *
+ * 自动模式（demo events 流）：每次 open 按 intervalMs 递增 seq 生成帧；
+ * 引擎带游标重开时从 seqOfCursor(cursor)+1 续发（backlog→follow 的续订方言）。
+ */
+
+export interface MockTransportHandle<F> {
+  /** 向当前连接递送一帧 */
+  emit(frame: F): void;
+  /** 当前连接以未知错误中断（引擎按 backoffMs 重连） */
+  interrupt(): void;
+  /** 当前连接正常收流，上报 closeReason（终态分诊入口） */
+  close(reason: FrameSource<F>["closeReason"]): void;
+  gap(): void;
+  end(): void;
+  /** 下一次 open 立即抛出该 ApiError（auth 闭环/不可重试失败测试） */
+  failNext(error: ApiError): void;
+  /** open 调用记录（含游标快照，供断言重连/续订行为） */
+  readonly opens: ReadonlyArray<{ cursor: Cursor | null }>;
+}
+
+export interface MockTransportOptions<F> {
+  /** 帧游标投影（供引擎恢复点；缺省不产生游标） */
+  cursorOf?: (frame: F) => Cursor | undefined;
+  /** 自动生成：按 seq 递增（手动 emit 与自动生成可并存） */
+  auto?: {
+    intervalMs: number;
+    frame: (seq: number) => F;
+    /** 起始 seq（无游标开流时） */
+    startSeq?: number;
+    /** 由游标解析续发起点；缺省 parseInt */
+    seqOfCursor?: (cursor: Cursor) => number;
+  };
+}
+
+type MockStep<F> =
+  | { kind: "frame"; frame: F }
+  | { kind: "close"; reason: FrameSource<F>["closeReason"] }
+  | { kind: "fail"; error: unknown };
+
+export type MockTransport<F> = Transport<F> & MockTransportHandle<F>;
+
+class MockAbortError extends Error {
+  constructor() {
+    super("mock: aborted");
+    this.name = "AbortError";
+  }
+}
+
+export function mockTransport<F>(options: MockTransportOptions<F> = {}): MockTransport<F> {
+  const opens: { cursor: Cursor | null }[] = [];
+  const failQueue: ApiError[] = [];
+
+  interface Conn {
+    alive: boolean;
+    reason: FrameSource<F>["closeReason"];
+    steps: MockStep<F>[];
+    waiters: Array<() => void>;
+    timer: ReturnType<typeof setInterval> | null;
+    detach(): void;
+  }
+  let active: Conn | null = null;
+
+  /** 直接投递到指定连接（绕过 alive 检查——abort 也要能唤醒等待者） */
+  function post(conn: Conn, step: MockStep<F>): void {
+    conn.steps.push(step);
+    conn.waiters.shift()?.();
+  }
+
+  /** 面向句柄控制：只投给活着的当前连接 */
+  function send(step: MockStep<F>): void {
+    if (active?.alive) post(active, step);
+  }
+
+  const handle: MockTransportHandle<F> = {
+    emit: (frame) => send({ kind: "frame", frame }),
+    interrupt: () => send({ kind: "fail", error: new TypeError("mock: connection reset") }),
+    close: (reason) => send({ kind: "close", reason }),
+    gap: () => handle.close("gapped"),
+    end: () => handle.close("ended"),
+    failNext: (error) => {
+      failQueue.push(error);
+    },
+    get opens() {
+      return opens;
+    },
+  };
+
+  return {
+    ...handle,
+    open(cursor: Cursor | null, signal: AbortSignal): FrameSource<F> {
+      opens.push({ cursor });
+      const failure = failQueue.shift();
+      if (failure) throw failure;
+
+      const auto = options.auto;
+      const conn: Conn = {
+        alive: true,
+        reason: "transport",
+        steps: [],
+        waiters: [],
+        timer: null,
+        detach() {
+          conn.alive = false;
+          if (conn.timer) clearInterval(conn.timer);
+          signal.removeEventListener("abort", abort);
+          // 唤醒所有等待者：它们会看到 steps 空 + 已死 → done（防提前 return 挂起）
+          for (const wake of conn.waiters.splice(0)) wake();
+        },
+      };
+      active = conn;
+
+      const abort = () => {
+        if (!conn.alive) return;
+        conn.detach();
+        post(conn, { kind: "fail", error: new MockAbortError() });
+      };
+      signal.addEventListener("abort", abort, { once: true });
+
+      if (auto) {
+        const seqOfCursor = auto.seqOfCursor ?? ((c: Cursor) => Number.parseInt(c, 10));
+        let seq = cursor === null ? (auto.startSeq ?? 0) : seqOfCursor(cursor) + 1;
+        conn.timer = setInterval(() => {
+          if (!conn.alive) return;
+          send({ kind: "frame", frame: auto.frame(seq) });
+          seq += 1;
+        }, auto.intervalMs);
+      }
+
+      const iterator: AsyncIterator<F> = {
+        async next(): Promise<IteratorResult<F>> {
+          while (conn.steps.length === 0 && conn.alive) {
+            await new Promise<void>((resolve) => {
+              conn.waiters.push(resolve);
+            });
+          }
+          const step = conn.steps.shift();
+          if (step === undefined) return { done: true, value: undefined };
+          if (step.kind === "frame") return { done: false, value: step.frame };
+          conn.detach();
+          if (step.kind === "close") {
+            conn.reason = step.reason;
+            return { done: true, value: undefined };
+          }
+          throw step.error;
+        },
+        async return(): Promise<IteratorResult<F>> {
+          conn.detach();
+          return { done: true, value: undefined };
+        },
+      };
+
+      return {
+        [Symbol.asyncIterator]: () => iterator,
+        get closeReason() {
+          return conn.reason;
+        },
+      };
+    },
+  };
+}
+
+/** 数字帧的便捷构造（测试：seq 即帧即游标）。 */
+export function mockSeqTransport(
+  options: { intervalMs?: number; startSeq?: number } = {},
+): MockTransport<number> {
+  return mockTransport<number>({
+    cursorOf: (frame) => String(frame),
+    auto: options.intervalMs
+      ? { intervalMs: options.intervalMs, frame: (seq) => seq, startSeq: options.startSeq ?? 0 }
+      : undefined,
+  });
+}