@fine-kit/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,610 @@
+/**
+ * Action 类型定义
+ *
+ * FlowAction — SPA 内部导航
+ * ExternalUrlAction — 打开外部链接
+ * CompoundAction — 组合多个 Action
+ */
+/** Action Kind 常量 */
+declare const ACTION_KINDS: {
+    FLOW: "flow";
+    EXTERNAL_URL: "externalUrl";
+    COMPOUND: "compound";
+};
+/** FlowAction — SPA 导航 */
+interface FlowAction {
+    kind: typeof ACTION_KINDS.FLOW;
+    url: string;
+    /** 展示方式: 默认 push，modal 弹窗 */
+    presentationContext?: "default" | "modal";
+}
+/** ExternalUrlAction — 外部链接 */
+interface ExternalUrlAction {
+    kind: typeof ACTION_KINDS.EXTERNAL_URL;
+    url: string;
+}
+/** CompoundAction — 组合 Action */
+interface CompoundAction {
+    kind: typeof ACTION_KINDS.COMPOUND;
+    actions: Action[];
+}
+/** 所有 Action 的联合类型 */
+type Action = FlowAction | ExternalUrlAction | CompoundAction;
+declare function isFlowAction(action: Action): action is FlowAction;
+declare function isExternalUrlAction(action: Action): action is ExternalUrlAction;
+declare function isCompoundAction(action: Action): action is CompoundAction;
+declare function makeFlowAction(url: string, presentationContext?: FlowAction["presentationContext"]): FlowAction;
+declare function makeExternalUrlAction(url: string): ExternalUrlAction;
+
+/**
+ * ActionDispatcher — Action 分发器
+ *
+ * 注册不同 kind 的 handler，按类型分发。
+ * CompoundAction 自动展开递归执行。
+ */
+
+/** Action 处理器函数类型 */
+type ActionHandler<A extends Action = Action> = (action: A) => Promise<void> | void;
+declare class ActionDispatcher {
+    private handlers;
+    private wiredActions;
+    /** 注册指定 kind 的 handler（防止重复注册） */
+    onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
+    /** 执行一个 Action（CompoundAction 递归展开） */
+    perform(action: Action): Promise<void>;
+}
+
+/**
+ * Container — 通用的依赖注入容器
+ */
+type Factory<T> = () => T;
+declare class Container {
+    private registrations;
+    /** 注册依赖（默认单例） */
+    register<T>(key: string, factory: Factory<T>, singleton?: boolean): this;
+    /** 解析依赖 */
+    resolve<T>(key: string): T;
+    /** 检查是否已注册 */
+    has(key: string): boolean;
+    /** 销毁容器，清除所有缓存 */
+    dispose(): void;
+}
+
+/**
+ * Intent 类型定义
+ */
+
+/** Intent — 描述一个用户意图 */
+interface Intent<T = unknown> {
+    /** Intent 标识符（用于匹配 Controller） */
+    id: string;
+    /** 意图参数 */
+    params?: Record<string, string>;
+    /** 预期返回的数据（仅用于类型推断） */
+    _returnType?: T;
+}
+/** Intent Controller — 处理特定 intentId 的业务逻辑 */
+interface IntentController<T = unknown> {
+    /** Controller 对应的 Intent ID */
+    intentId: string;
+    /** 执行意图，返回页面数据 */
+    perform(intent: Intent<T>, container: Container): Promise<T> | T;
+}
+
+/**
+ * IntentDispatcher — Intent 分发器
+ *
+ * 注册 IntentController，按 intentId 分发。
+ */
+
+declare class IntentDispatcher {
+    private controllers;
+    /** 注册一个 IntentController */
+    register(controller: IntentController): void;
+    /** 分发 Intent 到对应 Controller */
+    dispatch<T>(intent: Intent<T>, container: Container): Promise<T>;
+    /** 检查是否已注册某个 Intent */
+    has(intentId: string): boolean;
+}
+
+/** 日志级别 */
+type Level = "debug" | "info" | "warn" | "error";
+/**
+ * Logger 接口
+ *
+ * 所有方法返回空字符串，允许在模板中内联使用而不渲染文本。
+ */
+interface Logger {
+    debug(...args: unknown[]): string;
+    info(...args: unknown[]): string;
+    warn(...args: unknown[]): string;
+    error(...args: unknown[]): string;
+}
+interface LoggerFactory {
+    loggerFor(category: string): Logger;
+}
+
+/**
+ * 依赖工厂 — 创建所有基础依赖
+ */
+
+/** 网络请求层 */
+interface Net {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/** 多语言状态 */
+interface Locale {
+    language: string;
+    storefront: string;
+    setActiveLocale(language: string, storefront: string): void;
+}
+/** 存储接口 */
+interface Storage {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+/** Feature Flags */
+interface FeatureFlags {
+    isEnabled(key: string): boolean;
+    getString(key: string): string | undefined;
+    getNumber(key: string): number | undefined;
+}
+/** Metrics 记录器 */
+interface MetricsRecorder {
+    recordPageView(page: string, fields?: Record<string, unknown>): void;
+    recordEvent(name: string, fields?: Record<string, unknown>): void;
+}
+declare const DEP_KEYS: {
+    readonly LOGGER: "logger";
+    readonly LOGGER_FACTORY: "loggerFactory";
+    readonly NET: "net";
+    readonly LOCALE: "locale";
+    readonly STORAGE: "storage";
+    readonly FEATURE_FLAGS: "featureFlags";
+    readonly METRICS: "metrics";
+    readonly FETCH: "fetch";
+};
+interface MakeDependenciesOptions {
+    fetch?: typeof globalThis.fetch;
+    language?: string;
+    storefront?: string;
+    featureFlags?: Record<string, boolean | string | number>;
+}
+declare function makeDependencies(container: Container, options?: MakeDependenciesOptions): void;
+
+/**
+ * URL 路由器 — URL pattern → Intent + FlowAction
+ */
+
+/** 路由匹配结果 */
+interface RouteMatch {
+    intent: Intent;
+    action: FlowAction;
+}
+declare class Router {
+    private routes;
+    /** 添加路由规则 */
+    add(pattern: string, intentId: string): this;
+    /** 解析 URL → RouteMatch */
+    resolve(urlOrPath: string): RouteMatch | null;
+    /** 获取所有已注册的路由 */
+    getRoutes(): string[];
+    private extractPath;
+    private extractQueryParams;
+}
+
+/**
+ * BaseLogger — 抽象日志基类
+ */
+
+declare abstract class BaseLogger implements Logger {
+    protected category: string;
+    constructor(category: string);
+    abstract debug(...args: unknown[]): string;
+    abstract info(...args: unknown[]): string;
+    abstract warn(...args: unknown[]): string;
+    abstract error(...args: unknown[]): string;
+}
+
+/**
+ * Composite Logger — 组合日志，广播到多个后端
+ */
+
+declare class CompositeLoggerFactory implements LoggerFactory {
+    private readonly factories;
+    constructor(factories: LoggerFactory[]);
+    loggerFor(name: string): Logger;
+}
+declare class CompositeLogger implements Logger {
+    private readonly loggers;
+    constructor(loggers: Logger[]);
+    debug(...args: unknown[]): string;
+    info(...args: unknown[]): string;
+    warn(...args: unknown[]): string;
+    error(...args: unknown[]): string;
+    private callAll;
+}
+
+/**
+ * ConsoleLogger — 基于 console 的日志实现
+ */
+
+declare class ConsoleLogger extends BaseLogger {
+    debug(...args: unknown[]): string;
+    info(...args: unknown[]): string;
+    warn(...args: unknown[]): string;
+    error(...args: unknown[]): string;
+}
+declare class ConsoleLoggerFactory implements LoggerFactory {
+    loggerFor(category: string): Logger;
+}
+
+/**
+ * localStorage 日志级别过滤
+ *
+ * 通过 localStorage.onyxLog 控制日志级别:
+ *   '*=info'              — 全局 info 及以上
+ *   '*=info,Foo=off'      — 全局 info，Foo 静默
+ *   'Bar=error,Baz=warn'  — Bar 只输出 error，Baz 输出 warn+
+ */
+
+declare function shouldLog(name: string, level: Level): boolean;
+declare function resetFilterCache(): void;
+
+/**
+ * BasePage — 所有页面共享的基础属性
+ *
+ * 具体页面类型由应用层定义并扩展此接口。
+ */
+interface BasePage {
+    id: string;
+    pageType: string;
+    title: string;
+    description?: string;
+    url?: string;
+}
+
+/**
+ * PrefetchedIntents — SSR 数据缓存
+ *
+ * 服务端渲染时将 Intent→Data 映射序列化嵌入 HTML，
+ * 客户端 hydrate 时提取缓存。Framework.dispatch() 优先查缓存，
+ * 命中则直接返回，未命中则走 Controller 调度。
+ */
+
+/** 预获取的 Intent-Data 对 */
+interface PrefetchedIntent {
+    intent: Intent;
+    data: unknown;
+}
+declare class PrefetchedIntents {
+    private intents;
+    private constructor();
+    /** 从 PrefetchedIntent 数组创建缓存实例 */
+    static fromArray(items: PrefetchedIntent[]): PrefetchedIntents;
+    /** 创建空缓存实例 */
+    static empty(): PrefetchedIntents;
+    /**
+     * 获取缓存的 Intent 结果（一次性使用）。
+     * 命中后从缓存中删除。
+     */
+    get<T>(intent: Intent<T>): T | undefined;
+    /** 检查缓存中是否有某个 Intent 的数据 */
+    has(intent: Intent): boolean;
+    /** 缓存中的条目数 */
+    get size(): number;
+}
+
+/**
+ * Framework — 框架核心类
+ *
+ * 对应原版 Jet 类，统一管理: DI 容器、Intent 分发、Action 分发、路由、Metrics。
+ * 纯 TypeScript，不依赖任何 UI 框架。
+ */
+
+/** Framework 初始化配置 */
+interface FrameworkConfig extends MakeDependenciesOptions {
+    setupRoutes?: (router: Router) => void;
+    prefetchedIntents?: PrefetchedIntents;
+}
+declare class Framework {
+    readonly container: Container;
+    readonly intentDispatcher: IntentDispatcher;
+    readonly actionDispatcher: ActionDispatcher;
+    readonly router: Router;
+    readonly prefetchedIntents: PrefetchedIntents;
+    private constructor();
+    /** 创建并初始化 Framework 实例 */
+    static create(config?: FrameworkConfig): Framework;
+    /** 分发 Intent — 获取页面数据 */
+    dispatch<T>(intent: Intent<T>): Promise<T>;
+    /** 执行 Action — 处理用户交互 */
+    perform(action: Action): Promise<void>;
+    /** 路由 URL — 将 URL 解析为 Intent + Action */
+    routeUrl(url: string): RouteMatch | null;
+    /** 记录页面访问事件 */
+    didEnterPage(page: BasePage): void;
+    /** 注册 Action 处理器 */
+    onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
+    /** 注册 Intent Controller */
+    registerIntent(controller: IntentController): void;
+    /** 销毁 Framework 实例 */
+    dispose(): void;
+}
+
+/**
+ * BaseShelf / BaseItem — 所有 Shelf 和 Item 共享的基础属性
+ *
+ * 具体 Shelf/Item 类型由应用层定义并扩展此接口。
+ */
+
+interface BaseShelf {
+    id: string;
+    shelfType: string;
+    title?: string;
+    subtitle?: string;
+    seeAllAction?: Action;
+    isHorizontal?: boolean;
+}
+interface BaseItem {
+    id: string;
+    itemType: string;
+    clickAction?: Action;
+}
+
+/**
+ * stableStringify — 确定性 JSON 序列化（keys 按字母排序）
+ *
+ * 用作缓存 key：相同内容的对象始终产生相同字符串。
+ */
+declare function stableStringify(obj: unknown): string;
+
+/**
+ * HttpClient — 通用 HTTP 客户端基类
+ *
+ * 为 API Client 提供标准化的 HTTP 请求能力。
+ * 子类继承后只需关注业务端点定义，不需要重复实现 fetch / JSON 解析 / 错误处理。
+ */
+/** HTTP 请求错误 */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body?: string | undefined;
+    constructor(status: number, statusText: string, body?: string | undefined);
+}
+/** HttpClient 构造配置 */
+interface HttpClientConfig {
+    /** API base URL（如 "/api" 或 "https://example.com/api"） */
+    baseUrl: string;
+    /** 默认请求头 */
+    defaultHeaders?: Record<string, string>;
+    /** 自定义 fetch 实现（便于测试或 SSR） */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * 通用 HTTP 客户端基类
+ *
+ * 使用方式: 创建子类继承 HttpClient，定义业务方法调用 this.get() / this.post() 等。
+ *
+ * @example
+ * ```ts
+ * class MyApiClient extends HttpClient {
+ *   async getUser(id: string) {
+ *     return this.get<User>(`/users/${id}`);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class HttpClient {
+    protected readonly baseUrl: string;
+    protected readonly defaultHeaders: Record<string, string>;
+    protected readonly fetchFn: typeof globalThis.fetch;
+    constructor(config: HttpClientConfig);
+    /** GET 请求，返回解析后的 JSON */
+    protected get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    /** POST 请求，自动序列化 body 为 JSON */
+    protected post<T>(path: string, body?: unknown, params?: Record<string, string>): Promise<T>;
+    /** PUT 请求 */
+    protected put<T>(path: string, body?: unknown, params?: Record<string, string>): Promise<T>;
+    /** DELETE 请求 */
+    protected del<T>(path: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * 底层请求方法 — 子类可覆写以自定义行为
+     *
+     * 自动处理:
+     * - URL 拼接 (baseUrl + path + params)
+     * - 默认 headers 合并
+     * - JSON body 序列化
+     * - 响应 JSON 解析
+     * - 非 2xx 状态码抛出 HttpError
+     */
+    protected request<T>(method: string, path: string, options?: {
+        params?: Record<string, string>;
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /** 构建完整 URL — 子类可覆写以自定义 URL 拼接逻辑 */
+    protected buildUrl(path: string, params?: Record<string, string>): string;
+}
+
+/**
+ * BaseController — 抽象 Intent Controller 基类
+ *
+ * 提供标准化的 try/catch → fallback 模式。
+ * 子类只需实现 execute() 和可选的 fallback()。
+ */
+
+/**
+ * 抽象 Controller 基类
+ *
+ * 统一处理:
+ * - 类型安全的参数提取 (TParams)
+ * - 返回类型约束 (TResult)
+ * - try/catch 错误处理 + 可选 fallback
+ *
+ * @example
+ * ```ts
+ * class ProductController extends BaseController<{ productId: string }, ProductPage> {
+ *   readonly intentId = "product-page";
+ *
+ *   async execute(params: { productId: string }, container: Container) {
+ *     const api = container.resolve<ApiClient>("api");
+ *     return api.getProduct(params.productId);
+ *   }
+ *
+ *   fallback(params: { productId: string }, error: Error) {
+ *     return getMockProduct(params.productId);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseController<TParams extends Record<string, string | undefined> = Record<string, string>, TResult = unknown> implements IntentController<TResult> {
+    /** Controller 对应的 Intent ID */
+    abstract readonly intentId: string;
+    /**
+     * 执行业务逻辑 — 子类必须实现
+     *
+     * @param params - Intent 参数（已类型化）
+     * @param container - DI 容器
+     * @returns 页面数据
+     */
+    abstract execute(params: TParams, container: Container): Promise<TResult> | TResult;
+    /**
+     * 错误回退 — 子类可选覆写
+     *
+     * 当 execute() 抛出异常时调用。
+     * 默认行为: 重新抛出原始错误。
+     *
+     * @param params - Intent 参数
+     * @param error - execute() 抛出的错误
+     * @returns 回退数据
+     */
+    fallback(params: TParams, error: Error): Promise<TResult> | TResult;
+    /**
+     * IntentController.perform() 实现
+     *
+     * 自动 try/catch → fallback 模式。
+     */
+    perform(intent: Intent<TResult>, container: Container): Promise<TResult>;
+}
+
+/**
+ * Mapper 类型工具 — 标准化数据转换管线
+ *
+ * 提供类型约定和组合函数，让 API 响应 → 页面模型 的转换有统一的签名模式。
+ */
+/** 同步映射函数 */
+type Mapper<TInput, TOutput> = (input: TInput) => TOutput;
+/** 异步映射函数 */
+type AsyncMapper<TInput, TOutput> = (input: TInput) => TOutput | Promise<TOutput>;
+/**
+ * 组合两个同步 Mapper: A → B → C
+ */
+declare function pipe<A, B, C>(m1: Mapper<A, B>, m2: Mapper<B, C>): Mapper<A, C>;
+/**
+ * 组合三个同步 Mapper: A → B → C → D
+ */
+declare function pipe<A, B, C, D>(m1: Mapper<A, B>, m2: Mapper<B, C>, m3: Mapper<C, D>): Mapper<A, D>;
+/**
+ * 组合四个同步 Mapper: A → B → C → D → E
+ */
+declare function pipe<A, B, C, D, E>(m1: Mapper<A, B>, m2: Mapper<B, C>, m3: Mapper<C, D>, m4: Mapper<D, E>): Mapper<A, E>;
+/**
+ * 组合任意数量的同步 Mapper
+ */
+declare function pipe(...mappers: Mapper<unknown, unknown>[]): Mapper<unknown, unknown>;
+/**
+ * 组合两个可能异步的 Mapper: A → B → C
+ */
+declare function pipeAsync<A, B, C>(m1: AsyncMapper<A, B>, m2: AsyncMapper<B, C>): AsyncMapper<A, C>;
+/**
+ * 组合三个可能异步的 Mapper
+ */
+declare function pipeAsync<A, B, C, D>(m1: AsyncMapper<A, B>, m2: AsyncMapper<B, C>, m3: AsyncMapper<C, D>): AsyncMapper<A, D>;
+/**
+ * 将一个 Mapper 应用到数组的每个元素
+ */
+declare function mapEach<TInput, TOutput>(mapper: Mapper<TInput, TOutput>): Mapper<TInput[], TOutput[]>;
+
+/**
+ * defineRoutes — 声明式路由 + Controller 注册
+ *
+ * 将命令式的路由注册 (20+ 行 framework.router.add / framework.registerIntent)
+ * 简化为声明式配置数组。
+ */
+
+/** 单条路由定义 */
+interface RouteDefinition {
+    /** URL pattern (如 "/product/:productId") */
+    path: string;
+    /** Intent ID (如 "product-page") */
+    intentId: string;
+    /**
+     * Controller 实例（可选）。
+     * 同一个 intentId 的多条路由只需在第一条提供 controller。
+     */
+    controller?: IntentController;
+}
+/**
+ * 声明式注册路由和 Controller
+ *
+ * - 自动去重: 同一 intentId 的 controller 只注册一次
+ * - 路由和 controller 在同一个配置数组中，方便检查一致性
+ *
+ * @example
+ * ```ts
+ * defineRoutes(framework, [
+ *   { path: "/",                intentId: "home",     controller: new HomeController() },
+ *   { path: "/product/:id",    intentId: "product",  controller: new ProductController() },
+ *   { path: "/search",         intentId: "search",   controller: new SearchController() },
+ *   { path: "/charts/:type",   intentId: "charts",   controller: new ChartsController() },
+ *   { path: "/charts",         intentId: "charts" },  // 同 intentId，不需要重复 controller
+ * ]);
+ * ```
+ */
+declare function defineRoutes(framework: Framework, definitions: RouteDefinition[]): void;
+
+/**
+ * LruMap — 固定容量的 LRU 缓存
+ */
+declare class LruMap<K, V> {
+    private map;
+    private readonly capacity;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    get size(): number;
+    clear(): void;
+}
+
+/**
+ * Optional 类型工具
+ */
+type None = null | undefined;
+type Optional<T> = T | None;
+declare function isSome<T>(value: Optional<T>): value is T;
+declare function isNone<T>(value: Optional<T>): value is None;
+
+/**
+ * URL 工具函数
+ */
+/** 移除 URL scheme (https://, http://) */
+declare function removeScheme(url: string): string;
+/** 移除 URL host 部分，保留路径 */
+declare function removeHost(url: string): string;
+/** 移除 query 参数 */
+declare function removeQueryParams(url: string): string;
+/** 获取 URL 的基础路径（无 query、hash） */
+declare function getBaseUrl(url: string): string;
+/** 构建 URL（路径 + query 参数） */
+declare function buildUrl(path: string, params?: Record<string, string | undefined>): string;
+
+/**
+ * UUID v4 生成器
+ */
+declare function generateUuid(): string;
+
+export { ACTION_KINDS, type Action, ActionDispatcher, type ActionHandler, type AsyncMapper, BaseController, type BaseItem, BaseLogger, type BasePage, type BaseShelf, CompositeLogger, CompositeLoggerFactory, type CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, type ExternalUrlAction, type FeatureFlags, type FlowAction, Framework, type FrameworkConfig, HttpClient, type HttpClientConfig, HttpError, type Intent, type IntentController, IntentDispatcher, type Locale, type Logger, type LoggerFactory, type Logger as LoggerInterface, LruMap, type Mapper, type MetricsRecorder, type Net, type None, type Optional, type PrefetchedIntent, PrefetchedIntents, type RouteDefinition, type RouteMatch, Router, type Storage, buildUrl, defineRoutes, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify };