Inspected version: 0.1.3 · Source →

The kernel supplies application lifecycle, dependency injection, configuration, events, errors/results, logging, cache contracts and HTTP abstractions.

Entry points #

The manifest exports ., /events, /ioc, /errors, /logging, /http, /cache, /config, /server and /package.json.

Root: shared public APIs exported from cache, composition, config, errors, events, HTTP, IoC and logging.
/server: root exports plus server config loader/provider APIs and KernelServiceProvider.
Use /ioc, /events, /errors, /logging, /http, /cache, and /config when you want a narrower import surface.

Application lifecycle #

Application.configure() returns ApplicationBuilder.

API	Behavior
`use(provider)`	Adds a provider entry
`with(provider)`	Alias for `use`
`withProviders(providers)`	Adds several provider entries
`create()`	Creates an `Application`
`bootstrap()`	Registers all providers, then boots them, deduplicating concurrent bootstrap
`shutdown()`	Calls provider shutdown hooks in reverse order and resets bootstrap state

A provider entry can be a ServiceProvider instance, a provider class whose constructor receives the container, or a factory callback that receives the container. The base kernel inserts KernelServiceProvider before custom providers.

import { Application } from "@veap/kernel";
import { DatabaseServiceProvider } from "@veap/database";

const app = Application.configure()
  .use(DatabaseServiceProvider)
  .create();

await app.bootstrap();

The implementation skips bootstrap in a browser, during NEXT_PHASE=phase-production-build, and when SKIP_VEAP_INIT=true. Do not use this behavior as a substitute for a deliberate deployment migration step.

IoC container #

container is the process-global container; app() returns it, and app(token) resolves a registered token asynchronously.

import { app, container, Injectable, Inject } from "@veap/kernel";

const REPORTS = Symbol.for("app:reports");

@Injectable()
class ReportService {
  constructor(@Inject(REPORTS) private reports: string[]) {}
}

container.register({ token: REPORTS, useValue: ["weekly"] });
const reports = await app(ReportService);

Container.register() accepts a ProviderDef with token and one of useValue, useFactory, or useClass; inject specifies factory/class dependencies; singleton: false disables caching for a registered definition. resolve, has, make, clear and reset are available.

Important details from implementation:

Unregistered class tokens can be instantiated from reflected constructor metadata.
A class token that is resolved without a registered definition is cached by the container.
clear() clears instances and in-flight resolution but retains provider definitions.
reset() clears provider definitions and instances.
Constructor injection relies on reflect-metadata and TypeScript's emitted design metadata; a type-only import is erased and cannot serve as a runtime constructor token.

Service providers #

ServiceProvider requires register() and optionally supports boot() and shutdown(). All providers run register() first; only after registration completes does the application call boot() on each provider. Use shutdown() to close connections or release persistent resources.

Event bus #

The public event bus supports subscribe(eventType, subscriberId, handler), unsubscribe(eventType, subscriberId), once(eventType, handler, subscriberIdPrefix?), publish(eventType, payload, source?, options?), publishStrict(eventType, payload, source?), and clearAll().

Handlers receive a SystemEvent envelope containing type, payload, timestamp and source. The implementation inspected in the recorded source snapshot matches exact event types; do not rely on README claims about wildcard matching without verifying the installed version.

import { eventBus } from "@veap/kernel";

const unsubscribe = eventBus.subscribe(
  "orders:created",
  "search-index",
  async (event) => {
    // event.payload is the published payload.
  },
);

await eventBus.publish("orders:created", { orderId: "ord_123" });
// Later, when appropriate:
eventBus.unsubscribe("orders:created", "search-index");

The event bus is in-process pub/sub, not a durable queue. For jobs that must survive process restarts, use a persistent queue/outbox appropriate to your application.

Configuration #

ConfigService provides configuration reads, while /server exports getVeapConfig and config-provider support. Package-specific settings may be read through ConfigService, environment variables, or both; see Environment and configuration.

Errors and results #

The error utilities include AppError, HTTP status/error types, and result helpers such as ok and handleActionError. Use these helpers to keep Server Action responses serializable and consistent. Inspect the installed Result type before narrowing its shape.

HTTP and cache contracts #

The kernel exports HTTP request/context contracts and adapters (including Next.js/Waku-oriented adapters) as well as cache contracts and an in-memory cache implementation. These are integration primitives; they do not create Next.js routes or replace the framework's routing system.