# State and resource API

Typed definitions, effects, subscriptions and resource leases.

Signatures come from public package exports. Descriptions are checked against current JSDoc; identifiers retain their original names.

## Create a state slot

Returns a slot installed through addState.

### defineState

@param definition - Pure document-local reducer and explicit inverse policy.
@returns Reusable installable state slot.

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

## Pure reducers

See [Transaction state](/en/guide/state) for a complete module and updates.

### StateDefinition

Transaction-owned state; initialization is per document, not per definition.

```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** — Unique installation key, used in conflict diagnostics.

**create** — @param document - Initial canonical source.
@returns Immutable initial value.

**update** — @param value - Prior value.
@param update - Pure transaction context.
@returns Next immutable value.

**invert** — Optional inverse effects, expressed in pre-transaction coordinates. Omission means no effect history.
@param value - Pre-transaction slot value.
@param update - Forward transaction.
@returns Explicit inverse effects.

## Effect tokens

Positional payloads need mapping; an effect alone does not define undo.

### defineEffect

@param map - Optional mapping for positional payloads.
@returns Typed transaction effect token.

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

## Transaction metadata

Use for correlation, not persistent document fields.

### defineMetadata

@returns Typed metadata token without a second transaction store.

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

## Accepted-state subscriptions

Keep select pure and bounded; read the initial value separately.

### StateSubscription

Accepted-state subscription, with no speculative draft notifications.

```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** — @param state - Accepted immutable state.
@returns Selected value; must be pure and bounded.

**change** — @param next - Changed selected value.
@param previous - Previously published value.

**equal** — @param a - Previous value.
@param b - Next value.
@returns Equality; defaults to Object.is.

## Resource leases

Used by TaskScope.acquire; see [Resources](/en/extensions/resources) for lifetime rules.

### ResourceLease

One owned resource; each acquisition must return its own lease.

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

**value** — Consumer value, never automatically persisted in Markdown.

**release** — Releases this acquisition, including a result arriving after cancellation.