deepseek-harness/website/zh-CN/api/cordis/fiber.md

Fiber

A fiber is one loaded plugin instance: its lifecycle state, validated config, and registered effects. ctx.fiber is the current fiber; ctx.effect() delegates to it.

ctx.effect(execute, label?)

effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>

Register a cleanup-aware effect on this fiber. execute runs immediately; the disposers it produces are collected and run (in reverse order) either when the returned disposer is called or when the fiber unloads, whichever comes first. Calling the disposer twice is a no-op. Throws CordisError('INACTIVE_EFFECT') if the fiber is already disposed, and TypeError if execute returns an invalid shape.

• execute — the effect body; see Effect for accepted shapes.
• label — effect label shown in getEffects() diagnostics.

Returns a disposer that tears the effect down and settles once done.

Source

ctx.fiber

fiber: Fiber

The fiber (plugin runtime instance) that owns this context.

Source

The Fiber class

Runtime instance of one plugin application. A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by ctx.plugin().

Source

fiber.uid

public uid: number | null

Unique id within the registry; 0 for the root fiber, null once disposed.

Source

fiber.ctx

public readonly ctx: Context

The context this fiber's plugin runs in (extends the parent context).

Source

fiber.config

public config: any

The validated plugin config (updated by update()).

Source

fiber.state

public state

Current lifecycle state; transitions emit internal/status.

Source

fiber.dispose

public readonly dispose: () => Promise<void>

Dispose this fiber: unload the plugin, then settle once cleanup finished.

Source

fiber.store

public store: Dict<Impl> | undefined

Snapshot of required service implementations while loaded; undefined otherwise.

Source

fiber.inertia

public inertia: Promise<void> | undefined

The in-flight load/unload transition, if one is currently running.

Source

fiber.name

get name()

The plugin's display name, inherited from the nearest named ancestor, else 'root'.

Source

fiber.assertActive()

assertActive()

Throw if the fiber has already been disposed.

Returns nothing when the fiber is still active.

Source

fiber.effect(execute, label?)

effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>

Register a cleanup-aware effect on this fiber. execute runs immediately; the disposers it produces are collected and run (in reverse order) either when the returned disposer is called or when the fiber unloads, whichever comes first. Calling the disposer twice is a no-op. Throws CordisError('INACTIVE_EFFECT') if the fiber is already disposed, and TypeError if execute returns an invalid shape.

• execute — the effect body; see Effect for accepted shapes.
• label — effect label shown in getEffects() diagnostics.

Returns a disposer that tears the effect down and settles once done.

Source

fiber.getEffects()

getEffects()

Return metadata for currently registered effects.

Returns one EffectMeta tree per labeled live effect.

Source

fiber.await()

async await()

Wait for current lifecycle work and rethrow startup errors.

Returns this fiber, once it has settled into a stable state.

Source

fiber.restart()

async restart()

Dispose and immediately reload this plugin with its current config.

Returns a promise resolving once the reload settled.

Source

fiber.update(config, noSave?)

update(config: any, noSave = false)

Validate and apply new config, then restart the plugin. Runs the internal/update waterfall first, so update hooks (and HMR) can veto or replace the restart.

• config — the new raw config; validated before anything restarts.
• noSave — hint for persistence hooks not to write the change back.

Returns nothing; the restart runs behind the internal/update waterfall.

Source

Effect

Effect body result accepted by ctx.effect() and plugin startup. Either a single disposer, a promise of one, or a (possibly async) iterable yielding several — generator effects register each yielded disposer as it is produced.

type Effect<T = any> =
  | SyncEffect<T>
  | AsyncEffect<T>

Source

Disposable

Function returned by an effect to release resources during disposal. Disposers run in reverse registration order when the owning fiber unloads; they may be async, in which case unloading awaits them.

type Disposable<T = any> = () => T

Source

EffectMeta

Tree node used to expose nested effect labels for diagnostics.

interface EffectMeta {
  /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
  label: string
  /** Metadata of nested effects registered while this effect ran. */
  children: EffectMeta[]
}

Source

CordisError

Framework error with a stable machine-readable code.

class CordisError extends Error {
  /**
   * @param code — the stable error code; also the default message.
   * @param message — optional human-readable override.
   */
  constructor(public code: CordisError.Code, message?: string)
}

namespace CordisError {
  export type Code = keyof typeof Code

  export const Code = {
    INACTIVE_EFFECT: 'cannot create effect on inactive context',
  } as const
}

Source

ValidationError

Error raised when plugin configuration fails standard-schema validation.

class ValidationError extends TypeError {
  name = 'ValidationError'

  /**
   * Build the aggregated message from schema issues.
   *
   * @param issues — the standard-schema issues, one message line each.
   */
  constructor(issues: readonly StandardSchemaV1.Issue[])
}

Source