@oxog/plugin

Micro-kernel plugin system for the @oxog ecosystem with typed events, lifecycle hooks, and dependency resolution.

@oxog/plugin is the heart of the @oxog ecosystem. It provides the core micro-kernel implementation that all other @oxog packages build upon.

Features

• Plugin Lifecycle - install → init → destroy with full async support
• Typed Events - Type-safe event bus for inter-plugin communication
• Dependency Resolution - Automatic topological sorting of plugins
• Error Boundaries - Configurable strategies: isolate, fail-fast, collect
• Context Management - Shared state between plugins
• Dynamic Plugins - Add, remove, replace, and reload at runtime
• Fluent API - Chainable method calls
• Zero Dependencies - Only @oxog/types at runtime
• Universal - Works in Node.js >= 18 and modern browsers
• Tiny Bundle - < 4KB gzipped core, < 6KB total

Installation

npm install @oxog/plugin

Quick Start

import { createKernel } from '@oxog/plugin';

// Create a kernel
const kernel = createKernel();

// Define a plugin
const loggerPlugin = {
  name: 'logger',
  version: '1.0.0',
  install(kernel) {
    kernel.log = (...args) => console.log('[LOG]', ...args);
  }
};

// Register and initialize
kernel.use(loggerPlugin);
await kernel.init();

// Use the plugin
(kernel as any).log('Hello, World!');

// Cleanup
await kernel.destroy();

Documentation

For full documentation, examples, and API reference, visit plugin.oxog.dev.

Examples

• 01 - Basic Kernel
• 02 - Plugin Registration
• 03 - Lifecycle Hooks
• 04 - Typed Events
• 05 - Wildcard Events
• 06 - Dependencies
• 07 - Error Handling
• 08 - Context Sharing
• 09 - Plugin Factories
• 10 - Dynamic Plugins
• 11 - Plugin Queries
• 12 - Kernel Events
• 13 - Error Strategies
• 14 - Replace & Reload
• 15 - Real-World App

API Reference

createKernel<TContext, TEvents>(options?)

Creates a new micro-kernel instance.

Options:

• context - Initial shared context
• errorStrategy - 'isolate' | 'fail-fast' | 'collect'
• onError - Global error handler
• onBeforeInit, onAfterInit - Init lifecycle hooks
• onBeforeDestroy, onAfterDestroy - Destroy lifecycle hooks

Returns: KernelInstance<TContext, TEvents>

KernelInstance Methods

| Method | Description | |--------|-------------| | use(plugin) | Register a plugin | | useAll(plugins[]) | Register multiple plugins | | init() | Initialize all plugins | | destroy() | Destroy all plugins | | waitForPlugin(name) | Wait for plugin initialization | | waitForAll() | Wait for all pending inits | | getPlugin(name) | Get a plugin by name | | hasPlugin(name) | Check if plugin exists | | listPlugins() | Get all plugins | | getPluginNames() | Get all plugin names | | getDependencyGraph() | Get dependency graph | | on(event, handler) | Subscribe to event | | once(event, handler) | Subscribe once | | emit(event, payload) | Emit event | | off(event, handler) | Unsubscribe | | onWildcard(handler) | Subscribe to all events | | onPattern(pattern, handler) | Subscribe to pattern | | getContext() | Get shared context | | updateContext(partial) | Shallow update context | | deepUpdateContext(partial) | Deep merge context | | unregister(name) | Remove plugin | | replace(plugin) | Replace plugin | | reload(name) | Reload plugin |

Plugin Interface

interface Plugin<TContext> {
  name: string;
  version: string;
  dependencies?: string[];

  install(kernel: Kernel<TContext>): void;
  onInit?(context: TContext): MaybePromise<void>;
  onDestroy?(): MaybePromise<void>;
  onError?(error: Error): void;
}

License

MIT © Ersin Koç

Links

• GitHub
• Website
• Documentation
• npm

Made with ❤️ by Ersin Koç