@victorylabs/core

Plugin runtime for the @victorylabs/* framework. Zero runtime dependencies, zero React types, framework-agnostic.

@victorylabs/core is the foundation every @victorylabs/* package depends on. It provides the Core orchestrator, Plugin base class, typed PluginToken identity, facets for multi-contributor cross-cutting concerns, a typed EventEmitter, observable state, and a composable middleware primitive.

Install

pnpm add @victorylabs/core

Quick start

import { Core, Plugin, createPluginToken, createObservable } from '@victorylabs/core'

const CounterToken = createPluginToken<CounterPlugin>('CounterPlugin')

class CounterPlugin extends Plugin {
  readonly key = CounterToken
  readonly count = createObservable(0)

  increment(): void {
    this.count.set(this.count.get() + 1)
  }
}

const core = new Core()
core.register(new CounterPlugin())
await core.bootstrap()

const counter = core.get(CounterToken)
counter.increment()

Key exports

• Core — top-level orchestrator. register(plugin), bootstrap(), get(token), on(event, listener), healthCheck(), snapshot(), shutdown().
• Plugin — abstract base class. Override prepare(ctx) and start(ctx); declare key, dependencies, optional includes, destroy(), healthCheck().
• createPluginToken<T>(name) — typed identity for core.get(...) resolution.
• createObservable<T>(initial) — push-based reactive state with get(), set(), subscribe().
• computed(deps, fn) — derived observable that recomputes when any dep changes.
• createFacetToken<T>(name) / Facet<T> — multi-contributor channels (e.g. middleware arrays, React providers). Contributed to via ctx.facet(Token).contribute(source, values, Prec.default).
• Prec — precedence tiers for facet contributions (highest, high, default, low, lowest).
• EventEmitter / narrowEmitter<T>() — typed pub/sub. Plugins declare events via module augmentation of PluginEventRegistry.
• onBefore / onAfter / onError — middleware composition helpers.
• PluginError — wraps plugin failures with { pluginKey, phase, cause }.

Lifecycle

Every plugin participates in a two-phase bootstrap:

1. prepare(ctx) — set up state, contribute to facets, subscribe to events. Runs in dependency order.
2. start(ctx) — read owned facets, go live. Runs after every plugin has prepared.

Failure in either phase calls destroy() on every plugin that already ran (reverse order) and puts Core into a permanent failed state.

See also

• @victorylabs/kit — opinionated composition via defineApp()
• @victorylabs/cli — scaffold new projects wired to the kit