@wiznetic/kernel

Programmable lifecycle microkernel by Wiznetic.

A minimal, flexible kernel that provides a mechanism for modules to connect, communicate, and extend the system. The kernel has no opinion about HTTP, WebSocket, CLI, or any specific technology — those are module responsibilities.

Installation

npm install @wiznetic/kernel

Concepts

The kernel does three things:

• Hooks — lifecycle points where modules can plug in (on / run)
• Events — typed messages dispatched between modules (listen / dispatch)
• Extension — the kernel itself can be extended or replaced (extend)

Everything else (HTTP server, WebSocket, Bootstrap chain, routing) is built on top as modules.

API

Kernel.on(hook, callback)

Register a callback on a named lifecycle hook.

import { Kernel } from '@wiznetic/kernel';

Kernel.on('start', async (ctx) => {
    console.log('system starting');
});

Kernel.run(hook, ctx?)

Execute all callbacks registered on a hook. Returns a Promise.

await Kernel.run('start');
await Kernel.run('request', { req, res });

Kernel.listen(EventClass, handler)

Register a handler for a specific event class.

import { Kernel } from '@wiznetic/kernel';
import { PathResolvedEvent } from './events/PathResolvedEvent.js';

Kernel.listen(PathResolvedEvent, async (event) => {
    console.log(event.path);
});

Kernel.dispatch(event)

Dispatch an event to all registered listeners. Returns a Promise resolving to the event.

const event = await Kernel.dispatch(new PathResolvedEvent('/var/www'));

Propagation can be stopped from within a handler:

Kernel.listen(PathResolvedEvent, async (event) => {
    event.stopPropagation(); // no further handlers will run
});

Kernel.extend(plugin)

Extend or replace parts of the kernel. The plugin receives the Kernel class directly.

Kernel.extend((kernel) => {
    const original = kernel.dispatch.bind(kernel);

    kernel.dispatch = async (event) => {
        console.log('dispatching', event.constructor.name);
        return original(event);
    };
});

Events

Extend the base Event class for typed events.

import { Event } from '@wiznetic/kernel';

export class PathResolvedEvent extends Event {
    constructor(path) {
        super();
        this.path = path;
    }
}

Example

import { Kernel, Event } from '@wiznetic/kernel';

class AppStartedEvent extends Event {
    constructor(config) {
        super();
        this.config = config;
    }
}

Kernel.listen(AppStartedEvent, async (event) => {
    console.log('App started with config:', event.config);
});

Kernel.on('start', async () => {
    await Kernel.dispatch(new AppStartedEvent({ port: 3000 }));
});

await Kernel.run('start');

Design

The kernel is intentionally minimal. It does not handle:

• HTTP or WebSocket servers — use a module
• Process management or uptime — use PM2 or Docker
• Reconnection logic — handle in the client module
• Bootstrap or dependency resolution — build on top via modules

The kernel is a base resource. Modules connect to it and own their problems.

License

MIT