@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

``bash
npm install @oxog/plugin
`

Quick Start

`typescript
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.

$3

- 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

$3

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

$3

| 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

`typescript
interface Plugin {
name: string;
version: string;
dependencies?: string[];

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

License

MIT © Ersin Koç

Links

- GitHub
- Website
- Documentation
- npm

---

Made with ❤️ by Ersin Koç