@lark.js/mvc 0.0.1 → 0.0.2

package/lark.d.ts

@@ -0,0 +1,1176 @@
+/**
+ * @lark/mvc 命名空间
+ *
+ * Lark 是一个轻量级的 MVC 前端框架，提供视图管理、路由、状态管理、
+ * 接口服务等核心能力，适用于单页应用（SPA）开发。
+ *
+ * 核心模块：
+ * - View：视图基类，支持 extend/merge 继承与事件方法模式
+ * - Router：基于 Hash 的两阶段路由确认机制
+ * - State：跨视图的全局可观察状态管理
+ * - Service：API 请求管理，支持缓存、去重与队列
+ * - Frame：视图帧树，管理视图的挂载/卸载生命周期
+ * - Updater：视图数据绑定与 VDOM Diff 渲染引擎
+ */
+declare namespace LarkMvc {
+  /**
+   * 框架配置接口，用于 Lark.boot() 时传入应用的全局配置。
+   * 所有配置项均可在运行时通过 Lark.config('key') 动态访问
+   */
+  export interface Config {
+    /**
+     * 根视图所在的 DOM 节点 ID，框架将在此节点内渲染根视图。
+     * 该字段为必填项，若未指定则默认为 "lark-root"
+     */
+    rootId: string;
+    /**
+     * 默认加载的视图路径。当 URL 中无法匹配到任何路由时，将加载该视图作为根视图
+     */
+    defaultView?: string;
+    /**
+     * 默认路径。当 URL 哈希为空时使用的路径，默认为 "/"
+     */
+    defaultPath?: string;
+    /**
+     * 路径与视图的映射关系。
+     * - 简单映射：`{ "/home": "app/views/home" }`
+     * - 带配置映射：`{ "/detail": { view: "app/views/detail", title: "详情" } }`
+     * 路径重写逻辑请使用 rewrite 配置项
+     */
+    routes?: Record<string, string | { view: string; [key: string]: unknown }>;
+    /**
+     * 在 routes 中找不到匹配时使用的视图路径，例如用于显示 404 页面
+     */
+    unmatchedView?: string;
+    /**
+     * 项目启动时加载的扩展模块路径数组。
+     * 这些扩展会在应用初始化之前加载完成
+     */
+    exts?: string[];
+    /**
+     * 全局错误处理函数。框架以 try-catch 方式执行部分核心流程，
+     * 当出错时允许开发者通过该配置项进行捕获。
+     * 注意：不应在该方法内再次抛出任何错误
+     */
+    error?: (error: Error) => void;
+    /**
+     * 其它动态配置项，允许通过 config.key 方式访问自定义配置
+     */
+    [key: string]: unknown;
+  }
+  /**
+   * URL 解析结果中的路径与参数部分。
+   * 由 Router.parse() 返回，包含路径字符串和解析后的键值参数对
+   */
+  export interface RouterParseParts {
+    /**
+     * 解析出的参数键值对
+     */
+    readonly params: Readonly<Record<string, string>>;
+    /**
+     * 路径字符串，不包含查询参数
+     */
+    readonly path: string;
+  }
+  /**
+   * URL 解析结果接口，包含对当前 URL 的完整解析信息。
+   * 由 Router.parse() 返回，涵盖 query（?后）和 hash（#后）两部分
+   */
+  export interface RouterParse {
+    /**
+     * 原始的完整 href 字符串
+     */
+    readonly href: string;
+    /**
+     * 原始查询字符串（问号之后、井号之前的部分）
+     */
+    readonly srcQuery: string;
+    /**
+     * 原始哈希字符串（井号之后的部分）
+     */
+    readonly srcHash: string;
+    /**
+     * srcQuery 解析出的路径与参数对象
+     */
+    readonly query: RouterParseParts;
+    /**
+     * srcHash 解析出的路径与参数对象
+     */
+    readonly hash: RouterParseParts;
+    /**
+     * query.params 与 hash.params 合并后的参数对象，
+     * 当键名冲突时，hash 中的值优先
+     */
+    readonly params: Readonly<Record<string, string>>;
+    /**
+     * 根据 hash 中的 path 和 query 中的 path，结合路由规则计算得出的当前路径。
+     * 在框架启动前可能为 undefined
+     */
+    readonly path?: string;
+    /**
+     * 当前 URL 对应的要渲染的根视图路径。
+     * 在框架启动前可能为 undefined
+     */
+    readonly view?: string;
+    /**
+     * 从 params 中获取指定键的参数值。
+     * 当键不存在时返回默认值或空字符串
+     * @param key 参数键名
+     * @param defaultValue 当值不存在时返回的默认值，默认为空字符串
+     */
+    get(key: string, defaultValue?: string): string;
+  }
+  /**
+   * 参数差异项，表示某个 URL 参数从旧值变更为新值。
+   * 用于 Router.diff() 返回的差异比较结果中
+   */
+  export interface RouterDiffItem {
+    /**
+     * 变更前的旧值
+     */
+    readonly from: string;
+    /**
+     * 变更后的新值
+     */
+    readonly to: string;
+  }
+  /**
+   * URL 差异对象接口，描述两次路由状态之间的变化。
+   * 由 Router.diff() 返回，包含路径、视图及参数的详细差异信息
+   */
+  export interface RouterDiff {
+    /**
+     * 是否为应用首次初始化时强制触发的差异比较
+     */
+    readonly force: boolean;
+    /**
+     * 当路径有变化时，包含路径的差异信息
+     */
+    readonly path?: RouterDiffItem;
+    /**
+     * 当渲染的根视图有变化时，包含视图的差异信息
+     */
+    readonly view?: RouterDiffItem;
+    /**
+     * 所有发生变化的参数及其差异信息
+     */
+    readonly params: Readonly<Record<string, RouterDiffItem>>;
+    /**
+     * 是否有任何内容发生了变化
+     */
+    readonly changed: boolean;
+  }
+  /**
+   * 视图更新器接口，管理视图数据绑定与变更检测。
+   * 每个 View 实例持有一个 Updater，通过 set/digest 驱动界面更新。
+   * 内部执行模板渲染 → VDOM Diff → DOM 操作的完整流水线
+   */
+  export interface Updater {
+    /**
+     * 获取已设置的数据。当 key 未传递时返回整个数据对象；
+     * 当 key 传递时返回该键对应的值
+     * @param key 数据键名，省略则返回完整数据对象
+     */
+    get<T = unknown>(key?: string): T;
+    /**
+     * 设置数据并追踪变更的键。设置后需调用 digest() 才会将变更应用到界面。
+     * 返回 this 以支持链式调用
+     * @param data 数据对象，例如 `{ a: 20, b: 30 }`
+     * @param excludes 需要排除变更追踪的键集合
+     */
+    set(data: Record<string, unknown>, excludes?: Set<string>): this;
+    /**
+     * 检测数据变化并触发 VDOM 重新渲染。
+     * 放入数据后需显式调用该方法，界面才会更新。
+     * 内部执行模板渲染 → VDOM Diff → DOM 操作的完整流水线
+     * @param data 可选的数据对象，若提供则先调用 set() 设置数据
+     * @param excludes 需要排除变更追踪的键集合
+     * @param callback 渲染完成后的回调函数
+     */
+    digest(
+      data?: Record<string, unknown>,
+      excludes?: Set<string>,
+      callback?: () => void,
+    ): void;
+    /**
+     * 获取当前数据状态的快照，配合 altered() 方法可检测数据是否有变化
+     */
+    snapshot(): this;
+    /**
+     * 检测自上次 snapshot() 以来数据是否有变动。
+     * 若从未调用 snapshot()，则返回 undefined
+     */
+    altered(): boolean | undefined;
+    /**
+     * 翻译模板中 @ 符号对应的原始引用数据。
+     * 将以特殊分隔符开头的字符串替换为 refData 中的实际值
+     * @param data 待翻译的数据值
+     */
+    translate(data: unknown): unknown;
+    /**
+     * 在数据上下文中解析表达式字符串
+     * @param expr 表达式字符串
+     */
+    parse(expr: string): unknown;
+  }
+  /**
+   * 数据载体接口，包装 API 请求的响应数据，提供便捷的读写方法。
+   * Bag 实例由 Service 内部创建，开发者通过 all/one/save 回调获取
+   */
+  export interface Bag {
+    /**
+     * 从 Bag 中获取指定键的数据
+     * @param key 数据键名
+     */
+    get<T = unknown>(key: string): T;
+    /**
+     * 向 Bag 中设置数据，支持三种调用方式：
+     * - 传入键值对：`bag.set("name", "value")`
+     * - 传入数据对象：`bag.set({ name: "value" })`
+     * - 传入接口元信息对象（框架内部使用）
+     * 返回 this 以支持链式调用
+     * @param keyOrData 键名字符串、数据对象或接口元信息
+     * @param value 当第一个参数为键名时对应的值
+     */
+    set(
+      keyOrData: string | Record<string, unknown> | ServiceInterfaceMeta,
+      value?: unknown,
+    ): this;
+  }
+  /**
+   * State 数据变化事件接口，携带变更键的集合信息
+   */
+  export interface StateChangedEvent extends TriggerEventDescriptor {
+    /**
+     * 包含哪些数据键发生变化的集合对象，值为 1 表示该键发生了变化
+     */
+    readonly keys: Readonly<Record<string, 1>>;
+  }
+  /**
+   * 事件对象接口，提供 on/off/fire 方法实现发布-订阅模式
+   */
+  export interface Event<T = unknown> {
+    /**
+     * 绑定事件监听器。当事件触发时，处理器将被调用
+     * @param name 事件名称
+     * @param fn 事件处理函数
+     */
+    on(name: string, fn: (this: T, e?: TriggerEventDescriptor) => void): this;
+    /**
+     * 解除事件监听。若未传递处理函数，则移除该事件的所有监听器
+     * @param name 事件名称
+     * @param fn 可选的事件处理函数，省略则移除所有监听
+     */
+    off(name: string, fn?: (...args: unknown[]) => unknown): this;
+    /**
+     * 派发事件，执行所有已绑定的监听器。
+     * 事件数据中将自动添加 type 属性。支持在派发时移除所有监听器，
+     * 以及按倒序执行监听列表
+     * @param name 事件名称
+     * @param data 事件数据对象
+     * @param remove 是否在派发后移除所有监听器
+     * @param lastToFirst 是否倒序派发监听列表
+     */
+    fire(
+      name: string,
+      data?: Record<string, unknown>,
+      remove?: boolean,
+      lastToFirst?: boolean,
+    ): this;
+  }
+  /**
+   * 全局状态接口，提供跨视图的数据共享与变更通知能力。
+   * State 是一个单例对象，通过 get/set/digest 管理应用级状态数据。
+   * 支持 clean() 方法创建视图销毁时自动清理的 mixin
+   */
+  export interface State extends Event<State> {
+    /**
+     * 从全局状态中获取数据。当 key 未传递时返回整个状态对象
+     * @param key 数据键名，省略则返回完整状态对象
+     */
+    get<T = unknown>(key?: string): T;
+    /**
+     * 设置全局状态数据。设置后需调用 digest() 才会派发 changed 事件通知视图更新
+     * @param data 数据对象，例如 `{ a: 20, b: 30 }`
+     * @param excludes 需要排除变更追踪的键集合
+     */
+    set(data: Record<string, unknown>, excludes?: Set<string>): this;
+    /**
+     * 清理 State 中指定键的数据。只能在 view 的 mixins 中使用，
+     * 例如 `mixins: [Lark.State.clean("a,b")]`。
+     * 当视图销毁时，通过该方法注册的键将自动被清理，
+     * 同时减少对应键的引用计数，引用计数归零时自动删除该数据
+     * @param keys 逗号分隔的键名字符串
+     * @returns 包含 make 方法的对象，供 mixins 机制调用
+     */
+    clean(keys: string): { make: (...args: unknown[]) => unknown };
+    /**
+     * 检测数据变化并派发 changed 事件。
+     * 通过 set() 放入数据后需显式调用该方法，事件才会派发
+     * @param data 可选的数据对象，若提供则先调用 set() 设置数据
+     * @param excludes 需要排除变更追踪的键集合
+     */
+    digest(data?: Record<string, unknown>, excludes?: Set<string>): void;
+    /**
+     * State 中的数据发生变化时触发
+     */
+    onchanged: (this: this, e?: StateChangedEvent) => void;
+  }
+  /**
+   * 接口元信息配置，用于向 Service 注册一个 API 端点。
+   * 每个 meta 条目描述了接口的 URL、缓存策略、前后置钩子等
+   */
+  export interface ServiceInterfaceMeta {
+    /**
+     * 缓存有效时间，以毫秒为单位。0 表示不缓存，
+     * 大于 0 表示缓存 TTL（在该时间范围内复用缓存数据）
+     */
+    cache?: number;
+    /**
+     * 请求的 URL 地址（必填项）
+     */
+    url: string;
+    /**
+     * 接口元信息的唯一名称，需确保在同一个 Service 类中唯一
+     */
+    name: string;
+    /**
+     * 逗号分隔的接口名称字符串，用于清除其它接口的缓存。
+     * 例如该接口是一个新增数据的接口，调用成功后应清除
+     * 所有获取相关数据的缓存接口，否则将获取不到新数据
+     */
+    cleans?: string;
+    /**
+     * 请求发送前的钩子函数，可在该方法内对请求数据进行加工处理。
+     * this 指向当前 Bag 实例
+     * @param bag 当前请求的数据载体
+     */
+    before?: (this: Bag, bag: Bag) => void;
+    /**
+     * 请求成功后的钩子函数，在数据送达视图前调用，
+     * 可在该方法内对响应数据进行加工处理。
+     * this 指向当前 Bag 实例
+     * @param bag 当前请求的数据载体
+     */
+    after?: (this: Bag, bag: Bag) => void;
+    [key: string]: unknown;
+  }
+  /**
+   * 基础触发事件描述接口，所有事件对象的公共基础类型。
+   * 包含 type 属性标识事件类型名称
+   */
+  export interface TriggerEventDescriptor {
+    /**
+     * 事件类型名称
+     */
+    readonly type: string;
+  }
+  /**
+   * 路由变化前的事件接口（change 阶段），
+   * 提供两阶段确认机制：先触发 change（可拒绝），再触发 changed（已生效）。
+   * 开发者可通过此事件对象阻止、拒绝或接受路由变更
+   */
+  export interface RouterChangeEvent extends TriggerEventDescriptor {
+    /**
+     * 拒绝 URL 改变，恢复到之前的地址
+     */
+    reject: () => void;
+    /**
+     * 接受 URL 改变，继续导航
+     */
+    resolve: () => void;
+    /**
+     * 阻止 URL 改变，暂停后续路由处理
+     */
+    prevent: () => void;
+  }
+  /**
+   * 路由变化后的事件接口（changed 阶段），
+   * 携带路由差异信息。当路由变更确认后触发，此时 URL 已更新
+   */
+  export interface RouterChangedEvent
+    extends RouterDiff, TriggerEventDescriptor {}
+  /**
+   * 视图监听 URL 变化的配置接口。
+   * 用于 observeLocation() 方法的对象参数形式
+   */
+  export interface ViewObserveLocation {
+    /**
+     * 是否监听路径变化
+     */
+    path?: boolean;
+    /**
+     * 监听的参数键名，支持逗号分隔字符串或字符串数组
+     */
+    params?: string | string[];
+  }
+  /**
+   * 路由对象接口，提供 URL 解析、导航、差异比较及事件监听能力。
+   * 支持两阶段路由确认机制：change（可拒绝）→ changed（已生效）。
+   * 基于 Hash 实现，使用 #! 作为默认哈希前缀
+   */
+  export interface Router extends Event<Router> {
+    /**
+     * 解析 href 的 query 和 hash 部分，返回结构化的路由信息。
+     * 默认解析当前页面 location.href
+     * @param url 待解析的 URL，若未指定则使用 location.href
+     */
+    parse(url?: string): RouterParse;
+    /**
+     * 计算当前 URL 与上一个 URL 之间的差异对象。
+     * 如果尚未发生任何路由变化，返回 undefined
+     */
+    diff(): RouterDiff | undefined;
+    /**
+     * 导航到新的地址，支持路径字符串或参数对象两种调用方式：
+     * - `Router.to("/list", { page: 2 })` — 指定路径和参数
+     * - `Router.to({ page: 2 })` — 仅更新参数，保持当前路径
+     * @param pathOrParams 路径字符串或参数对象
+     * @param params 查询参数对象（仅当第一个参数为路径字符串时使用）
+     * @param replace 是否替换当前的历史记录（而非新增）
+     * @param silent 是否静默更新，不触发 change 事件
+     */
+    to(
+      pathOrParams: string | Record<string, unknown>,
+      params?: Record<string, unknown>,
+      replace?: boolean,
+      silent?: boolean,
+    ): void;
+    /**
+     * URL 即将改变时触发（change 阶段），可通过事件对象拒绝或阻止导航
+     */
+    onchange: (this: this, e?: RouterChangeEvent) => void;
+    /**
+     * URL 改变后触发（changed 阶段），携带路由差异信息
+     */
+    onchanged: (this: this, e?: RouterChangedEvent) => void;
+  }
+  /**
+   * 接口服务事件接口，在请求开始或结束时触发。
+   * 包含 begin/done/fail/end 四种事件
+   */
+  export interface ServiceEvent extends TriggerEventDescriptor {
+    /**
+     * 数据载体对象，包含本次请求的数据
+     */
+    readonly bag: Bag;
+    /**
+     * 错误对象，如果请求过程中发生错误则携带该信息，否则为 null
+     */
+    readonly error: object | string | null;
+  }
+  /**
+   * 继承属性描述接口，定义 extend() 方法中可传入的属性值类型约束。
+   * 支持基本类型、正则、符号、对象及函数
+   */
+  export type ExtendPropertyDescriptor<T> = Record<
+    string,
+    | string
+    | number
+    | undefined
+    | boolean
+    | RegExp
+    | symbol
+    | Record<string, unknown>
+    | null
+    | ((this: T, ...args: unknown[]) => unknown)
+  >;
+  /**
+   * 继承方法中的 this 指向类型，将 ExtendPropertyDescriptor 与 ThisType 结合
+   */
+  type TExtendPropertyDescriptor<T> = ExtendPropertyDescriptor<T> & ThisType<T>;
+  /**
+   * 继承静态属性描述接口，用于 extend() 方法的 statics 参数
+   */
+  export type ExtendStaticPropertyDescriptor = Record<string, unknown>;
+  /**
+   * 视图监听 URL 参数的配置接口（与 ViewObserveLocation 相同）
+   */
+  export interface ViewObserveUrl {
+    /**
+     * 监听的参数键名，支持逗号分隔字符串或字符串数组
+     */
+    params?: string | string[];
+    /**
+     * 是否监听路径变化
+     */
+    path?: boolean;
+  }
+  /**
+   * 视图事件接口，携带触发事件的节点 ID。
+   * 在通过 v-event 属性绑定的 DOM 事件中携带
+   */
+  export interface ViewEvent extends TriggerEventDescriptor {
+    /**
+     * 触发事件的 DOM 节点 ID
+     */
+    readonly id: string;
+  }
+  /**
+   * Frame 静态事件接口，携带关联的 Frame 实例。
+   * 在 Frame 的 add/remove 静态事件中携带
+   */
+  export interface FrameStaticEvent extends TriggerEventDescriptor {
+    /**
+     * 关联的 Frame 实例对象
+     */
+    readonly vframe: FramePrototype;
+  }
+  /**
+   * 缓存类原型接口，提供基于 LFU（最不经常使用）策略的缓存管理能力。
+   * 缓存键在内部使用特殊分隔符前缀进行命名空间隔离
+   */
+  export interface CachePrototype {
+    /**
+     * 设置缓存资源。若 key 已存在则更新对应资源值并增加访问频率。
+     * 当缓存条目数超过容量（maxSize + bufferSize）时，将触发 LFU 淘汰策略
+     * @param key 缓存资源的唯一标识键
+     * @param resource 要缓存的资源
+     */
+    set<T>(key: string, resource: T): void;
+    /**
+     * 获取缓存的资源。访问时会增加该条目的频率计数和时间戳，
+     * 以影响 LFU 排序。若不存在则返回 undefined
+     * @param key 缓存资源时使用的键
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * 从缓存中删除指定键的资源。删除时会触发 onRemove 回调
+     * @param key 要删除的缓存资源键
+     */
+    del(key: string): void;
+    /**
+     * 判断缓存中是否包含给定键的资源
+     * @param key 缓存资源键
+     */
+    has(key: string): boolean;
+    /**
+     * 遍历缓存中的所有资源值
+     * @param callback 遍历回调函数，参数为缓存值（可能为 undefined）
+     */
+    forEach<T = unknown>(callback: (value: T | undefined) => void): void;
+    /**
+     * 当前缓存中的条目数量
+     */
+    readonly size: number;
+    /**
+     * 清空缓存中的所有条目，每个被清除的条目都会触发 onRemove 回调
+     */
+    clear(): void;
+  }
+  /**
+   * 缓存类构造接口，创建基于 LFU 策略的缓存实例
+   */
+  export interface Cache {
+    /**
+     * 创建缓存实例
+     * @param options 缓存配置对象，包含 maxSize、bufferSize、onRemove 等选项
+     */
+    new (options?: {
+      maxSize?: number;
+      bufferSize?: number;
+      onRemove?: (key: string) => void;
+      sortComparator?: (a: unknown, b: unknown) => number;
+    }): CachePrototype;
+    readonly prototype: CachePrototype;
+  }
+  /**
+   * 拥有 on/off/fire 事件的基类原型接口。
+   * Base 类继承自 EventEmitter，可直接实例化使用
+   */
+  export type BasePrototype = Event<BasePrototype>;
+  /**
+   * 拥有 on/off/fire 事件的基类接口。
+   * Base 类继承自 EventEmitter，可直接实例化使用
+   */
+  export interface Base {
+    /**
+     * 创建 Base 实例
+     */
+    new (): BasePrototype;
+    /**
+     * 原型
+     */
+    readonly prototype: BasePrototype;
+  }
+  /**
+   * Frame 类原型接口。
+   * Frame（视图帧）是视图的容器，管理视图的挂载、卸载及父子层级关系。
+   * 每个 Frame 对应一个 DOM 节点，通过 lark-view 属性关联视图
+   */
+  export interface FramePrototype extends Event<FramePrototype> {
+    /**
+     * Frame 所在的 DOM 节点 ID
+     */
+    readonly id: string;
+    /**
+     * 当前 Frame 渲染的视图模块路径，例如 "app/views/default"
+     */
+    readonly viewPath?: string;
+    /**
+     * 父 Frame 的 ID，若为顶层 Frame 则为 undefined
+     */
+    readonly parentId: string | undefined;
+    /**
+     * 挂载视图到当前 Frame。框架将加载视图类、创建实例并完成渲染
+     * @param viewPath 视图模块路径，例如 "app/views/default"
+     * @param viewInitParams 初始化视图时传递的参数，可在视图的 init 方法中接收
+     */
+    mountView(viewPath: string, viewInitParams?: Record<string, unknown>): void;
+    /**
+     * 卸载当前 Frame 中的视图，触发视图的 destroy 事件并清理资源
+     */
+    unmountView(): void;
+    /**
+     * 在指定 DOM 节点上挂载子 Frame 并渲染视图
+     * @param id 要渲染的 DOM 节点 ID
+     * @param viewPath 视图路径
+     * @param viewInitParams 初始化视图时传递的参数
+     */
+    mountFrame(
+      id: string,
+      viewPath: string,
+      viewInitParams?: Record<string, unknown>,
+    ): this;
+    /**
+     * 卸载指定 DOM 节点上的子 Frame
+     * @param id DOM 节点 ID，默认卸载当前 Frame
+     */
+    unmountFrame(id?: string): void;
+    /**
+     * 渲染指定节点下的所有子视图（扫描 lark-view 属性并挂载）
+     * @param id DOM 节点 ID，默认为当前 Frame
+     * @param inner 是否为内部调用（框架内部使用）
+     */
+    mountZone(id?: string, inner?: boolean): void;
+    /**
+     * 卸载指定节点下的所有子视图
+     * @param id DOM 节点 ID，默认为当前 Frame
+     */
+    unmountZone(id?: string): void;
+    /**
+     * 获取祖先 Frame。默认获取父 Frame（level=1）
+     * @param level 向上查找的层级，默认为 1
+     */
+    parent(level?: number): this | undefined;
+    /**
+     * 获取当前 Frame 的所有子 Frame 的 ID 数组。
+     * 注意：数组中 ID 的位置并不固定
+     */
+    children(): string[];
+    /**
+     * 调用当前 Frame 中视图的指定方法。
+     * 若视图尚未渲染完成，调用将被延迟到渲染后执行
+     * @param name 方法名
+     * @param args 传递给方法的参数数组
+     */
+    invoke<TReturnType>(name: string, args?: unknown[]): TReturnType;
+    /**
+     * 子孙视图全部创建完成时触发
+     */
+    oncreated: (this: this, e?: TriggerEventDescriptor) => void;
+    /**
+     * 子孙视图发生变更时触发
+     */
+    onalter: (this: this, e?: TriggerEventDescriptor) => void;
+  }
+  /**
+   * Frame 类接口（静态侧）。
+   * 开发者不需要继承或实例化该类，框架内部自动管理 Frame 的生命周期
+   */
+  export interface Frame extends Event<Frame> {
+    /**
+     * 获取当前页面上所有的 Frame 实例映射表
+     */
+    getAll(): Map<string, FramePrototype>;
+    /**
+     * 根据 ID 获取 Frame 实例，若不存在返回 undefined
+     * @param id Frame 的 DOM 节点 ID
+     */
+    get(id: string): FramePrototype | undefined;
+    /**
+     * 当 Frame 创建并注册时触发
+     */
+    onadd: (this: this, e?: FrameStaticEvent) => void;
+    /**
+     * 当 Frame 销毁并注销时触发
+     */
+    onremove: (this: this, e?: FrameStaticEvent) => void;
+    /**
+     * 原型
+     */
+    readonly prototype: FramePrototype;
+  }
+  /**
+   * 视图类原型接口，定义视图实例可用的属性和方法。
+   * 视图通过 View.extend() 创建子类，由 Frame 负责实例化和生命周期管理。
+   * 支持事件方法模式（如 `'name<click>'`）、资源托管和异步回调安全
+   */
+  export interface ViewPrototype extends Event<ViewPrototype> {
+    /**
+     * 当前视图所在的 DOM 节点 ID
+     */
+    readonly id: string;
+    /**
+     * 视图模板，支持函数模板或字符串模板。
+     * 函数模板签名：(data, viewId, refData, encodeHTML, ...) => string
+     */
+    readonly template?: ((...args: unknown[]) => string) | string;
+    /**
+     * 持有当前视图的 Frame 实例。
+     * 在视图初始化完成前可能为数字占位符（0）
+     */
+    readonly owner: FramePrototype | number;
+    /**
+     * 更新器实例，管理视图的数据绑定与 VDOM 渲染
+     */
+    readonly updater: Updater;
+    /**
+     * 混入的视图原型链上的其它对象数组，用于扩展视图功能。
+     * 框架会将 mixins 中的属性和方法合并到视图原型上，
+     * 事件方法模式的冲突会自动合并为串行调用
+     */
+    mixins?: ExtendStaticPropertyDescriptor[];
+    /**
+     * 初始化视图时调用。框架在挂载视图后自动调用此方法，
+     * 开发者可在此处执行初始化逻辑。
+     * 实际调用时框架会传入两个参数：initParams（初始化参数对象）和
+     * options（包含 node: Element 和 deep: boolean）
+     */
+    init(): void;
+    /**
+     * 渲染界面。框架在 init() 之后自动调用此方法，
+     * 开发者在此方法内完成界面渲染流程（通常调用 updater.digest()）
+     */
+    render(): void;
+    /**
+     * 增量更新视图的 DOM。框架内部使用 VDOM Diff 机制，
+     * 仅更新发生变化的部分，并自动处理子视图的挂载与卸载。
+     * 返回 true 表示有 DOM 变更，undefined 表示无变更
+     * @param options 增量更新配置（框架内部使用）
+     */
+    assign(options?: unknown): boolean | undefined;
+    /**
+     * 监听地址栏的变化。支持两种调用方式：
+     * - `observeLocation("page,size", true)` — 传入参数键名和是否监听路径
+     * - `observeLocation({ params: ["page", "size"], path: true })` — 传入配置对象
+     * 当监听的参数或路径变化时，视图将自动重新渲染
+     * @param parameters 监听的参数键名，支持逗号分隔字符串或字符串数组；
+     *                   或传入配置对象
+     * @param observePath 是否监听路径变化
+     */
+    observeLocation(
+      parameters: string | string[] | Record<string, unknown>,
+      observePath?: boolean,
+    ): void;
+    /**
+     * 监听 Lark.State 中指定键的数据变化。
+     * 当被监听的键通过 State.digest() 更新时，视图将自动重新渲染
+     * @param keys 逗号分隔的键名字符串，或字符串数组
+     */
+    observeState(keys: string | string[]): void;
+    /**
+     * 通知当前视图某个区域即将开始 HTML 更新。
+     * 内部会卸载该区域内的子 Frame，防止 VDOM Diff 时操作已卸载的节点
+     * @param id 需要更新的区域节点 ID，默认为当前视图
+     */
+    beginUpdate(id?: string): void;
+    /**
+     * 通知当前视图某个区域的 HTML 更新已完成。
+     * 内部会挂载该区域内的子 Frame，并执行延迟调用队列（invokes）
+     * @param id 更新完成的区域节点 ID，默认为当前视图
+     * @param inner 是否为内部调用
+     */
+    endUpdate(id?: string, inner?: boolean): void;
+    /**
+     * 包装异步回调函数，确保回调在视图未被销毁时才执行。
+     * 在单页应用中，异步回调（如 setTimeout、AJAX）执行时视图可能已销毁，
+     * 直接操作 DOM 会导致错误。使用 wrapAsync 包装后，Lark 会自动检查
+     * 视图状态，仅在视图存活时执行回调
+     * @param callback 待包装的回调函数
+     * @param context 回调执行时的 this 指向，默认为视图自身
+     */
+    wrapAsync<Fn extends (...args: unknown[]) => unknown>(
+      callback: Fn,
+      context?: unknown,
+    ): (...args: Parameters<Fn>) => ReturnType<Fn> | undefined;
+    /**
+     * 将资源交由当前视图托管。当视图销毁或重新渲染时，
+     * 框架会在合适的时机自动调用资源的 destroy 方法
+     * @param key 托管资源的唯一键。若该键已托管不同资源，旧资源将被自动销毁
+     * @param resource 待托管的资源对象
+     * @param destroyOnRender 当 render 方法再次调用时是否自动销毁该资源。
+     *                        通常 Lark.Service 实例需要在 render 时自动销毁
+     */
+    capture(
+      key: string,
+      resource?: unknown,
+      destroyOnRender?: boolean,
+    ): unknown;
+    /**
+     * 释放已托管的资源。返回被托管的资源对象，无论是否已销毁
+     * @param key 托管资源的键
+     * @param destroy 是否销毁资源（调用其 destroy 方法），默认为 true
+     */
+    release(key: string, destroy?: boolean): unknown;
+    /**
+     * 设置离开提醒。例如表单有未保存的变更时，
+     * 可提示用户选择直接离开还是保存后再离开。
+     * 框架将在路由变化（change 阶段）和页面卸载（beforeunload）时
+     * 调用 condition 函数，若返回 true 则阻止导航
+     * @param message 离开提示消息
+     * @param condition 判断是否显示提示的函数，返回 true 表示需要阻止导航
+     */
+    leaveTip(message: string, condition: () => boolean): void;
+    /**
+     * 视图销毁时触发
+     */
+    ondestroy: (this: this, e?: TriggerEventDescriptor) => void;
+    /**
+     * 当 render 方法被调用时触发
+     */
+    onrendercall: (this: this, e?: TriggerEventDescriptor) => void;
+  }
+  /**
+   * View 类接口（静态侧），提供视图的继承与扩展能力。
+   * View.extend() 是创建视图子类的唯一入口
+   */
+  export interface View {
+    /**
+     * 继承 Lark.View 创建新的视图子类。
+     * 支持 props.make 构造器、props.mixins 混入、
+     * 以及事件方法模式（如 `'name<click>'`）
+     * @param props 包含 init、render 等方法的原型属性对象
+     * @param statics 静态方法或属性的对象
+     */
+    extend<TProps = object, TStatics = object>(
+      props?: TExtendPropertyDescriptor<TProps & ViewPrototype>,
+      statics?: TStatics,
+    ): this & TStatics;
+    /**
+     * 将多个混入对象合并到 Lark.View 原型上。
+     * 已有的属性不会被覆盖，事件方法模式的冲突会自动合并
+     * @param args 混入对象列表
+     */
+    merge(...args: TExtendPropertyDescriptor<ViewPrototype>[]): this;
+    /**
+     * 原型
+     */
+    readonly prototype: ViewPrototype;
+  }
+  /**
+   * 接口管理类原型接口，提供 Service 实例的请求与队列管理能力
+   */
+  export interface ServicePrototype {
+    /**
+     * 并行发起所有请求，当全部完成（无论成功或失败）后回调。
+     * 如果接口指定了缓存且缓存有效，将直接使用缓存数据
+     * @param metas 接口名称字符串、参数对象或它们的数组
+     * @param done 完成回调，第一个参数为错误数组，后续为各接口的 Bag
+     */
+    all(
+      metas:
+        | string
+        | Record<string, unknown>
+        | (string | Record<string, unknown>)[],
+      done: (...args: unknown[]) => unknown,
+    ): this;
+    /**
+     * 与 all 类似，但始终跳过缓存，强制发起实际请求
+     * @param metas 接口名称字符串、参数对象或它们的数组
+     * @param done 完成回调
+     */
+    save(
+      metas:
+        | string
+        | Record<string, unknown>
+        | (string | Record<string, unknown>)[],
+      done: (...args: unknown[]) => unknown,
+    ): this;
+    /**
+     * 任意一个请求成功即立即回调，回调可能被调用多次
+     * @param metas 接口名称字符串、参数对象或它们的数组
+     * @param done 完成回调
+     */
+    one(
+      metas:
+        | string
+        | Record<string, unknown>
+        | (string | Record<string, unknown>)[],
+      done: (...args: unknown[]) => unknown,
+    ): this;
+    /**
+     * 排队执行任务。前一个 all/one/save 任务完成后，再执行下一个任务，类似 Promise 链
+     * @param callback 当前面的任务完成后调用的回调函数
+     */
+    enqueue(callback: (...args: unknown[]) => unknown): this;
+    /**
+     * 开始处理队列中的下一个任务
+     */
+    dequeue(...args: unknown[]): void;
+    /**
+     * 销毁当前 Service 实例。销毁后不可继续发起新请求，也不再调用回调
+     */
+    destroy(): void;
+  }
+  /**
+   * 接口管理类接口（静态侧），提供 API 端点注册、缓存管理和请求调度能力。
+   * 使用前需先通过 extend() 绑定数据同步函数，再通过 add() 注册接口元信息
+   */
+  export interface Service extends Event<Service> {
+    /**
+     * 继承产生新的 Service 子类，绑定自定义的数据同步函数
+     * @param sync 同步数据的方法，通常在该方法内与服务端交换数据
+     * @param cacheMax 最大缓存条目数
+     * @param cacheBuffer 缓存缓冲区大小
+     */
+    extend(
+      sync: (bag: Bag, callback: () => void) => void,
+      cacheMax?: number,
+      cacheBuffer?: number,
+    ): this;
+    /**
+     * 添加接口元信息，注册一个或多个 API 端点
+     * @param metas 接口元信息数组，也支持单个元信息对象
+     */
+    add(metas: ServiceInterfaceMeta | ServiceInterfaceMeta[]): void;
+    /**
+     * 根据接口元信息创建 Bag 对象
+     * @param meta 接口元信息对象或名称字符串
+     */
+    create(meta: Record<string, unknown>): Bag;
+    /**
+     * 获取元信息对象
+     * @param meta 接口元信息对象或名称字符串
+     */
+    meta(meta: string | Record<string, unknown>): ServiceInterfaceMeta;
+    /**
+     * 从缓存中获取或创建 Bag 对象
+     * @param meta 接口元信息对象
+     * @param createNew 是否创建新的 Bag 对象，若为 false 则优先从缓存中获取
+     */
+    get(
+      meta: Record<string, unknown>,
+      createNew?: boolean,
+    ): { entity: Bag; needsUpdate: boolean };
+    /**
+     * 从缓存中清除指定接口的数据
+     * @param names 逗号分隔的接口名称字符串或字符串数组
+     */
+    clear(names: string | string[]): void;
+    /**
+     * 从缓存中获取 Bag 对象，若缓存不存在或已过期则返回 undefined
+     * @param meta 接口元信息对象
+     */
+    cached(meta: Record<string, unknown>): Bag | undefined;
+    /**
+     * 接口发送请求前触发
+     */
+    onbegin: (this: this, e?: ServiceEvent) => void;
+    /**
+     * 接口请求结束时触发，无论成功或失败
+     */
+    onend: (this: this, e?: ServiceEvent) => void;
+    /**
+     * 创建 Service 实例
+     */
+    new (): ServicePrototype;
+    /**
+     * 原型
+     */
+    readonly prototype: ServicePrototype;
+  }
+  /**
+   * Lark 框架主对象接口，提供全局配置、应用初始化及工具方法。
+   * 作为 @lark.js/mvc 模块的默认导出
+   */
+  export interface Lark {
+    /**
+     * 设置或获取配置信息。
+     * - 传入配置对象时合并配置并返回合并后的配置
+     * - 传入字符串键名时返回该键对应的配置值
+     * - 不传参数时返回完整配置信息对象
+     * @param cfg 配置信息参数对象或配置键名
+     */
+    config<T extends object = Config>(cfg?: Config & T): Config & T;
+    config(key: string): unknown;
+    /**
+     * 应用初始化入口，启动框架并渲染根视图。
+     * 调用后将执行：合并配置 → 绑定路由事件 → 创建根 Frame → 挂载默认视图
+     * @param cfg 配置信息参数对象
+     */
+    boot(cfg: Config): void;
+    /**
+     * 将数组转换为哈希映射对象。
+     * - 简单数组：`Lark.toMap([1,2,3])` => `{1:1, 2:1, 3:1}`
+     * - 对象数组：`Lark.toMap([{id:20},{id:30}], 'id')` => `{20:{id:20}, 30:{id:30}}`
+     * @param list 源数组
+     * @param key 以数组中对象的哪个键的值作为哈希的键
+     */
+    toMap<T>(
+      list: T[] | null | undefined,
+      key?: keyof T,
+    ): Record<string, T | number>;
+    /**
+     * 以 try-catch 方式执行方法，忽略任何异常。
+     * 返回成功执行的最后一个方法的返回值
+     * @param fns 函数或函数数组
+     * @param args 传递给函数的参数数组
+     * @param context 函数执行时的 this 指向
+     */
+    toTry(
+      fns:
+        | ((...args: unknown[]) => unknown)
+        | ((...args: unknown[]) => unknown)[],
+      args?: unknown[],
+      context?: unknown,
+    ): unknown;
+    /**
+     * 将路径和参数转换为 URL 字符串。
+     * 例如 `Lark.toUrl('/xxx/', {a:'b',c:'d'})` => `/xxx/?a=b&c=d`
+     * @param path 路径字符串
+     * @param params 参数对象
+     * @param keepEmpty 保留空白值的键集合
+     */
+    toUrl(
+      path: string,
+      params?: Record<string, unknown>,
+      keepEmpty?: Record<string, number>,
+    ): string;
+    /**
+     * 将 URL 字符串解析为路径和参数对象。
+     * 例如 `Lark.parseUrl('/xxx/?a=b&c=d')` => `{path:'/xxx/', params:{a:'b',c:'d'}}`
+     * @param url URL 字符串
+     */
+    parseUrl(url: string): LarkMvc.RouterParseParts;
+    /**
+     * 将源对象的属性合并到目标对象上
+     * @param target 目标对象
+     * @param sources 一个或多个源对象
+     */
+    mix<T extends object>(target: T, ...sources: Partial<T>[]): T;
+    /**
+     * 检测对象是否拥有指定的自身属性（安全版 hasOwnProperty）
+     * @param owner 检测对象，支持 undefined/null
+     * @param prop 属性键名
+     */
+    has<T extends object>(
+      owner: T | undefined | null,
+      prop: PropertyKey,
+    ): boolean;
+    /**
+     * 获取对象自身可枚举属性的键名数组
+     * @param src 源对象
+     */
+    keys<T extends object>(src: T): string[];
+    /**
+     * 判断一个 DOM 节点是否包含在另一个节点内。
+     * 若两个节点为同一节点，也返回 true
+     * @param node 节点或节点 ID
+     * @param container 容器节点或节点 ID
+     */
+    inside(
+      node: HTMLElement | string,
+      container: HTMLElement | string,
+    ): boolean;
+    /**
+     * document.getElementById 的简写。
+     * 若传入的已是 Element 则直接返回
+     * @param id 节点 ID 或 Element 对象
+     */
+    node(id: string | Element | null): Element | null;
+    /**
+     * 确保 DOM 元素拥有 ID，若不存在则自动生成一个。
+     * 返回元素的 ID
+     * @param node DOM 元素对象
+     */
+    nodeId(node: HTMLElement): string;
+    /**
+     * 使用配置的模块加载器加载模块
+     * @param names 模块名称，支持字符串或字符串数组
+     * @param callback 模块加载完成后的回调
+     */
+    use(
+      names: string | string[],
+      callback?: (...modules: unknown[]) => void,
+    ): void;
+    /**
+     * 在调试模式下保护对象不被直接修改。
+     * 使用 Proxy 包装数据对象，拦截读写操作并给出警告，
+     * 引导开发者使用 State.set/digest 进行状态管理。
+     * 仅在 window.__lark_Debug 为 true 且 Proxy 可用时生效
+     * @param o 待保护的对象
+     */
+    guard<T extends object>(o: T): T;
+    /**
+     * 向页面动态注入 CSS 样式。返回一个清理函数用于移除注入的样式。
+     * 支持单条注入和批量注入两种方式：
+     * - `Lark.applyStyle("my-style", "body { color: red; }")` — 单条注入
+     * - `Lark.applyStyle(["style1", "css1", "style2", "css2"])` — 批量注入
+     * @param styleIdOrPairs 样式唯一键或 [id1, css1, id2, css2, ...] 批量数组
+     * @param cssText CSS 样式字符串（仅当第一个参数为字符串时使用）
+     */
+    applyStyle(styleIdOrPairs: string | string[], cssText?: string): () => void;
+    /**
+     * 生成全局唯一标识符（GUID）
+     * @param prefix GUID 前缀，默认为 "mx-"
+     */
+    guid(prefix?: string): string;
+    /**
+     * 创建异步回调有效性标记。
+     * 返回一个检查函数，若宿主对象被取消标记（例如视图重新渲染），
+     * 则检查函数返回 false，可防止过期的异步回调执行。
+     * 典型用法：`const check = Lark.mark(this, 'render'); setTimeout(() => { if (check()) ... })`
+     * @param host 宿主对象（通常是视图实例）
+     * @param key 标记键名（通常是 "render" 或特定异步操作标识）
+     */
+    mark(host: object, key: string): () => boolean;
+    /**
+     * 延时等待，基于 Promise 的 setTimeout 封装。
+     * 配合 async/await 使用可简化异步流程控制
+     * @param time 延时时间（毫秒）
+     */
+    delay(time: number): Promise<void>;
+    /**
+     * 接口服务管理类
+     */
+    Service: LarkMvc.Service;
+    /**
+     * 视图类
+     */
+    View: LarkMvc.View;
+    /**
+     * 缓存类
+     */
+    Cache: LarkMvc.Cache;
+    /**
+     * 全局状态对象
+     */
+    State: LarkMvc.State;
+    /**
+     * 事件对象
+     */
+    Event: LarkMvc.Event;
+    /**
+     * 路由对象
+     */
+    Router: LarkMvc.Router;
+    /**
+     * Frame 类，开发者不需要继承或实例化该类
+     */
+    Frame: LarkMvc.Frame;
+    /**
+     * 拥有 on/off/fire 事件的基类
+     */
+    Base: LarkMvc.Base;
+    default: Lark;
+  }
+}
+/**
+ * 模块导出声明。
+ * 通过 `import Lark from '@lark.js/mvc'` 引入框架主对象
+ */
+declare module "@lark.js/mvc" {
+  const Lark: LarkMvc.Lark;
+  export = Lark;
+}