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.
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.
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.
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.
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
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.
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, ...).
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.
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, ...).
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).
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.
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.
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).
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).
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.
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— whentrue(default), only return implementations whose providing fiber is currently active.
Returns the service value, or undefined when not (yet) provided.
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.
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.
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— thegethook and optionalsethook.
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.