core

@objectstack/core

ObjectStack microkernel — dependency injection, plugin lifecycle, event bus, and service registry for metadata-driven runtimes.

Overview

@objectstack/core is the foundation every ObjectStack runtime is built on. It hosts two kernels, a plugin lifecycle, a typed service registry, a structured logger, and a plugin-to-plugin event bus:

• ObjectKernel — full-featured production kernel with hot reload, health monitoring, dependency resolution, and namespace isolation.
• LiteKernel — minimal kernel for serverless, edge, and test environments.

All other ObjectStack runtime packages (runtime, rest, plugin-*, driver-*, service-*) plug into a kernel instance.

Installation

pnpm add @objectstack/core

Quick Start

import { ObjectKernel } from '@objectstack/core';

const kernel = new ObjectKernel();

kernel.use({
  name: 'my-plugin',
  version: '1.0.0',
  async init(ctx) {
    ctx.logger.info('plugin initializing…');
    ctx.registerService('greeter', { hello: (n: string) => `hi ${n}` });
  },
  async start(ctx) {
    const svc = ctx.getService<{ hello: (s: string) => string }>('greeter')!;
    ctx.logger.info(svc.hello('world'));
  },
});

await kernel.bootstrap();
// …
await kernel.shutdown();

LiteKernel (serverless/edge/tests)

import { LiteKernel } from '@objectstack/core';

const kernel = new LiteKernel();
await kernel.bootstrap();

Key Exports

Export	Kind	Description
ObjectKernel	class	Production kernel with DI, lifecycle, event bus, hot reload, health monitor.
LiteKernel	class	Minimal kernel for constrained runtimes.
Plugin	interface	Plugin contract (init, start, stop, lifecycle hooks).
PluginContext	interface	{ logger, registerService, getService, eventBus, kernel }.
ObjectLogger	class	Structured logger over pino; swappable backends.
ApiRegistry	class	Runtime route registry (consumed by @objectstack/rest).
QA	namespace	Built-in kernel self-tests.
PackageManager	class	Per-package DI namespace resolver.

Plugin lifecycle

use()  → init()  → start()  → [running]  → stop()  → unload()

• init(ctx) — register services, wire dependencies. Do not make network calls.
• start(ctx) — resolve other services, begin work. Called after every plugin's init().
• stop(ctx) — graceful shutdown, flush, close connections.
• kernel.unload(name) — runtime removal; pairs with AppPlugin.onDisable().

Kernel choice

Kernel	Use when
ObjectKernel	Default. Production servers, Studio, tests that need plugin composition.
LiteKernel	Cloudflare Workers, Vercel Edge, Vitest unit tests, footprint-sensitive sandboxes.

EnhancedObjectKernel has been removed. Migrate to ObjectKernel.

Observability

• ObjectLogger is backed by pino; control verbosity with LOG_LEVEL=info|debug|trace.
• kernel.getHealth() returns per-plugin health snapshots.
• EventBus: ctx.eventBus.on('plugin.started', …), .emit(…).

When to use

• ✅ Building an ObjectStack application (always).
• ✅ Authoring a plugin, driver, or service.

When not to use

• ❌ You only need the schemas — import @objectstack/spec alone.
• ❌ You only need a REST client — import @objectstack/client.

Related Packages

• @objectstack/spec — protocol definitions.
• @objectstack/runtime — DriverPlugin / AppPlugin scaffolds.
• @objectstack/rest — auto-generated REST layer.

Links

• 📖 Docs: https://objectstack.ai/docs
• 📚 API Reference: https://objectstack.ai/docs/references/kernel
• 🤖 Skill: skills/objectstack-plugin/SKILL.md

License

Apache-2.0 © ObjectStack