Context

The context is the core Cordis object: every service, event, and lifecycle API is reached through ctx. Event methods are documented on Events, effects and the current fiber on Fiber, and plugin loading on Registry.

Root and child dependency containers for Cordis plugins.

A context is a proxy: normal property reads go through the service resolver, while extend(), isolate(), and intercept() create scoped child contexts without mutating their parent.

Source

ctx.extend(meta?)

/**
 * Create a child context with extra metadata on top of the current scope.
 *
 * The child prototypally inherits every property of this context; own
 * properties of `meta` shadow the inherited ones. The parent is not mutated.
 *
 * @param meta — own properties (including symbol keys) to define on the child.
 * @returns a child context inheriting from this one.
 */
extend(meta = {}): this

Create a child context with extra metadata on top of the current scope.

The child prototypally inherits every property of this context; own properties of meta shadow the inherited ones. The parent is not mutated.

• meta — own properties (including symbol keys) to define on the child.

Returns a child context inheriting from this one.

Source

ctx.isolate(name, label?)

/**
 * Create a child context with an independent service scope for `name`.
 *
 * Below the returned context, reads and writes of the service `name`
 * resolve against the new label instead of the parent's, so a different
 * implementation can be provided without affecting the parent scope.
 * Passing the same `label` to two `isolate()` calls joins their scopes.
 *
 * @param name — the service name to isolate.
 * @param label — scope label to join; defaults to a fresh unique symbol.
 * @returns a child context whose `name` service resolves in the new scope.
 */
isolate(name: string, label?: symbol)

Create a child context with an independent service scope for name.

Below the returned context, reads and writes of the service name resolve against the new label instead of the parent's, so a different implementation can be provided without affecting the parent scope. Passing the same label to two isolate() calls joins their scopes.

• name — the service name to isolate.
• label — scope label to join; defaults to a fresh unique symbol.

Returns a child context whose name service resolves in the new scope.

Source

ctx.intercept(name, config)

/**
 * Add service-specific intercept config for plugins started below this
 * context.
 *
 * Plugins loaded under the returned context see `config` merged into the
 * service's resolved config (ancestor entries first; see
 * `Service[symbols.resolveConfig]`). The parent context is not affected.
 *
 * @param name — the service name whose config to intercept.
 * @param config — the intercept config to merge for that service.
 * @returns a child context carrying the additional intercept entry.
 */
intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
intercept(name: string, config: any): this

Add service-specific intercept config for plugins started below this context.

Plugins loaded under the returned context see config merged into the service's resolved config (ancestor entries first; see Service[symbols.resolveConfig]). The parent context is not affected.

• name — the service name whose config to intercept.
• config — the intercept config to merge for that service.

Returns a child context carrying the additional intercept entry.

Source

ctx.root

/** The root context of the application (every child context shares it). @experimental */
root: this

The root context of the application (every child context shares it). @experimental

Source

ctx.baseUrl

/** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
baseUrl?: string

Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.

Source

ctx.events

/** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
events: EventsService

The event bus. Its methods are also mixed onto ctx (ctx.on, ctx.emit, ...).

Source

ctx.logger

/** The logging service. Call `ctx.logger(name)` for a named logger. */
logger: LoggerService

The logging service. Call ctx.logger(name) for a named logger.

Source

ctx.reflect

/** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
reflect: ReflectService

The reflection layer backing the context proxy (ctx.get, ctx.provide, ...).

Source

ctx.registry

/** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
registry: RegistryService

The plugin registry. Its methods are mixed onto ctx (ctx.plugin, ctx.inject).

Source

Static members

Context.effect

/** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
static readonly effect: unique symbol

Symbol key under which a disposer exposes its EffectMeta diagnostics tree.

Source

Context.filter

/** Symbol key for a context's listener filter, consulted on every event dispatch. */
static readonly filter: unique symbol

Symbol key for a context's listener filter, consulted on every event dispatch.

Source

Context.isolate

/** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
static readonly isolate: unique symbol

Symbol key of the isolation map (see the Context[symbols.isolate] property).

Source

Context.intercept

/** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
static readonly intercept: unique symbol

Symbol key of the intercept map (see the Context[symbols.intercept] property).

Source

Context.is(value)

/**
 * Returns true for Cordis context proxies and context prototypes.
 *
 * Works across realms and across multiple copies of cordis, because the
 * brand is keyed by a global symbol rather than by `instanceof`.
 *
 * @param value — the value to test.
 * @returns `true` if `value` is a Cordis context, narrowing its type.
 */
static is(value: any): value is Context

Returns true for Cordis context proxies and context prototypes.

Works across realms and across multiple copies of cordis, because the brand is keyed by a global symbol rather than by instanceof.

• value — the value to test.

Returns true if value is a Cordis context, narrowing its type.

Source

Service store and mixins

ctx.get(name, strict?)

/**
 * Read a service from the store without the inject requirement.
 *
 * @param name — the service name.
 * @param strict — when `true` (default), only return implementations
 * whose providing fiber is currently active.
 * @returns the service value, or `undefined` when not (yet) provided.
 */
get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
get(name: string, strict?: boolean): any

Read a service from the store without the inject requirement.

• name — the service name.
• strict — when true (default), only return implementations whose providing fiber is currently active.

Returns the service value, or undefined when not (yet) provided.

Source

ctx.set(name, value)

/**
 * Overwrite a provided service's value.
 *
 * Only the fiber that provided the service may set it; setting an
 * unprovided name throws.
 *
 * @param name — the service name.
 * @param value — the new service value.
 */
set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
set(name: string, value: any): void

Overwrite a provided service's value.

Only the fiber that provided the service may set it; setting an unprovided name throws.

• name — the service name.
• value — the new service value.

Source

ctx.provide(name, value)

/**
 * Register a service implementation owned by the current fiber.
 *
 * The service becomes visible to dependents in the same isolation scope
 * once the fiber is active; it is unregistered (waking dependents) when
 * the returned disposer runs or the fiber unloads. Throws if the name is
 * already provided in this scope or declared as an accessor.
 *
 * @param name — the service name.
 * @param value — the service value.
 * @returns a disposer that unregisters the service.
 */
provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
provide(name: string, value?: any): () => void

Register a service implementation owned by the current fiber.

The service becomes visible to dependents in the same isolation scope once the fiber is active; it is unregistered (waking dependents) when the returned disposer runs or the fiber unloads. Throws if the name is already provided in this scope or declared as an accessor.

• name — the service name.
• value — the service value.

Returns a disposer that unregisters the service.

Source

ctx.accessor(name, options)

/**
 * Define a computed context property backed by get/set hooks.
 *
 * The accessor is removed when the current fiber unloads. Throws if the
 * name is already declared.
 *
 * @param name — the context property name.
 * @param options — the `get` hook and optional `set` hook.
 */
accessor(name: string, options: Omit<Property.Accessor, 'type'>): void

Define a computed context property backed by get/set hooks.

The accessor is removed when the current fiber unloads. Throws if the name is already declared.

• name — the context property name.
• options — the get hook and optional set hook.

Source

ctx.mixin(name, mixins)

/**
 * Expose selected members of a service directly on `ctx`.
 *
 * Each mixed-in key becomes an accessor that forwards to the service
 * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
 * Mixins are removed when the current fiber unloads.
 *
 * @param name — the context property holding the source service.
 * @param mixins — keys to forward, or a source-key → ctx-key map.
 */
mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void

Expose selected members of a service directly on ctx.

Each mixed-in key becomes an accessor that forwards to the service (binding methods to it), so e.g. ctx.on forwards to ctx.events.on. Mixins are removed when the current fiber unloads.

• name — the context property holding the source service.
• mixins — keys to forward, or a source-key → ctx-key map.

Source