# 状态与资源 API

状态定义、效果、订阅和异步资源的类型化协议。

本页签名从公共包导出生成，中文说明与当前 JSDoc 同步校验。代码标识保持原名。

## 创建状态槽

调用后得到可安装的 slot，通过 addState 安装。

### defineState

参数 definition：文档级纯 reducer 和显式反向策略。返回可复用的可安装状态槽。

```ts
function defineState<T>(definition: StateDefinition<T>): StateSlot<T>
```

## 纯 reducer

完整状态模块和更新方式见 [状态教程](/guide/state)。

### StateDefinition

由事务管理的状态；每份文档独立初始化。

```ts
export interface StateDefinition<T> {
    readonly key: string;
    readonly create: (document: SourceDocument) => T;
    readonly update: (value: T, update: StateUpdate) => T;
    readonly invert?: (value: T, update: StateUpdate) => readonly StateEffect<unknown>[];
}
```

**key** — 安装时唯一的状态键，用于冲突诊断。

**create** — 参数 document：初始源码。返回不可变初始值。

**update** — 参数 value：旧值；update：纯事务上下文。返回新的不可变值。

**invert** — 可选反向效果，以事务之前的坐标表示。参数 value 为旧值、update 为正向事务；返回反向效果。省略则效果不加入撤销历史。

## 效果令牌

带位置的载荷需要 map；效果本身不等于有撤销策略。

### defineEffect

参数 map：可选的位置载荷映射函数。返回类型化事务效果令牌。

```ts
function defineEffect<T>(map?: (value: T, changes: ChangeDesc) => T | undefined): Effect<T>
```

## 事务元数据

用于关联来源，不能代替文档持久字段。

### defineMetadata

返回类型化事务元数据令牌，不引入第二份事务存储。

```ts
function defineMetadata<T>(): Metadata<T>
```

## 接受状态订阅

select 保持纯粹和有界，调用方单独读取初始值。

### StateSubscription

订阅已接受状态，试算草稿不会产生通知。

```ts
export interface StateSubscription<T> {
    readonly select: (state: EditorState) => T;
    readonly change: (next: T, previous: T) => void;
    readonly equal?: (a: T, b: T) => boolean;
}
```

**select** — 参数 state：已接受的不可变状态。返回纯粹且有界的选择结果。

**change** — 参数 next、previous：变化后的值和此前已发布的值。

**equal** — 参数 a、b：前后值。返回是否相等；默认 Object.is。

## 资源租约

TaskScope.acquire 使用本协议；详细生命周期见 [异步资源](/extensions/resources)。

### ResourceLease

一次获取所拥有的资源；每次获取必须返回独立的租约。

```ts
export interface ResourceLease<T> {
    readonly value: T;
    readonly release?: () => void;
}
```

**value** — 供组件使用的值，不会自动持久化到 Markdown。

**release** — 释放本次获取的资源，包括取消后才到达的结果。