🔥 Zern Kernel

Strongly-Typed Plugin Kernel

Ultra-lightweight plugin orchestration with exceptional developer experience

Features • Quick Start • Documentation • Examples • API Reference

🌟 Overview

Zern Kernel is a next-generation plugin system designed for exceptional developer experience. It provides a minimal, type-safe core that enables plugins to work naturally like independent libraries, with automatic dependency resolution, transparent API augmentation, and powerful method interception.

Why Zern Kernel?

• 🎯 Natural API Design - Plugins feel like native libraries, not framework components
• 🔒 Complete Type Safety - Full TypeScript support with autocomplete everywhere
• 🚀 Zero Boilerplate - Fluent API eliminates ceremonial code
• 🔄 Intelligent Resolution - Automatic dependency ordering with version validation
• ⚡ Runtime Flexibility - Extend, intercept, and modify plugin behavior dynamically

✨ Features

Core Capabilities

| Feature | Description | | --------------------------------- | -------------------------------------------------------------------------- | | 🪶 Minimal Core | Only essential functionality - register, initialize, shutdown | | 🔄 Fluent API | Clean, chainable interface for plugin and kernel configuration | | 🤖 Auto Dependency Resolution | Topological sorting with intelligent cycle detection | | 🔧 API Extensions | Plugins can seamlessly extend other plugins' APIs | | 🎭 Method Proxying | Intercept and modify behavior with before/after/around hooks | | ⏱️ Lifecycle Hooks | onInit, onReady, onShutdown, onError for resource management | | 🗄️ Reactive Store | Automatic reactive state with watchers, computed values, and transactions | | 🏷️ Complete Plugin Access | kernel.get() returns API + $meta + $store for full plugin inspection | | 📦 Direct Exports | Import plugin methods directly like a normal library | | 🛡️ Error Handling | Hierarchical typed errors with stack traces, solutions, and severities | | 🔍 Version Control | Semantic versioning with flexible constraint matching |

Advanced Features

• ✅ 4 Proxy Modes: Self-proxy, single plugin, dependencies, and global
• ✅ Kernel-Level Proxies: Application-level interception via createKernel().proxy()
• ✅ Type-Safe Context: Plugin dependencies and metadata are fully typed
• ✅ Priority-Based Execution: Control proxy execution order with priorities
• ✅ Conditional Proxies: Apply interceptors based on runtime conditions
• ✅ Method Selectors: Fine-grained control with include/exclude patterns

🚀 Quick Start

Installation

npm install @zern/kernel

Basic Example

import { createKernel, plugin } from '@zern/kernel';

// 1️⃣ Create a database plugin
const databasePlugin = plugin('database', '1.0.0')
  .metadata({
    author: 'Zern Team',
    category: 'data',
  })
  .setup(() => ({
    async connect(url: string) {
      console.log(`Connected to: ${url}`);
      return { connected: true };
    },
    users: {
      async create(userData: { name: string; email: string }) {
        const id = Math.random().toString(36).slice(2);
        console.log(`User created: ${id}`);
        return { id, ...userData };
      },
    },
  }));

// 2️⃣ Create auth plugin with dependency
const authPlugin = plugin('auth', '1.0.0')
  .depends(databasePlugin, '^1.0.0')
  .onInit(({ plugins }) => {
    console.log('Auth initializing...');
    console.log('Database author:', plugins.database.$meta.author);
  })
  .setup(({ plugins }) => ({
    async validateToken(token: string) {
      console.log(`Validating token: ${token}`);
      return token === 'valid-token';
    },
  }));

// 3️⃣ Initialize kernel and use plugins
const kernel = await createKernel().use(databasePlugin).use(authPlugin).start();

// ✅ Type-safe plugin access with $meta and $store
const db = kernel.get('database');
await db.connect('postgresql://localhost:5432/mydb');

// Access metadata
console.log(db.$meta.author); // "Zern Team"
console.log(db.$meta.category); // "data"

const user = await db.users.create({
  name: 'John Doe',
  email: '[email protected]',
});

const auth = kernel.get('auth');
const isValid = await auth.validateToken('valid-token');

// Cleanup
await kernel.shutdown();

🔧 Core Concepts

1. Plugin Creation

const mathPlugin = plugin('math', '1.0.0')
  .metadata({ author: 'Zern Team' })
  .setup(() => ({
    add: (a: number, b: number) => a + b,
    multiply: (a: number, b: number) => a * b,
  }));

2. Dependencies

const calculatorPlugin = plugin('calculator', '1.0.0')
  .depends(mathPlugin, '^1.0.0') // Semantic versioning
  .setup(({ plugins }) => ({
    calculate: (expr: string) => {
      // Access math plugin with full type safety
      return plugins.math.add(1, 2);
    },
  }));

3. Reactive Store

Create automatically reactive type-safe state accessible across all plugin stages:

const databasePlugin = plugin('database', '1.0.0')
  .store(() => ({
    connection: null as Connection | null,
    queryCount: 0,
    startTime: Date.now(),
  }))
  .onInit(async ({ store }) => {
    // Initialize connection in store
    store.connection = await createConnection();

    // 🔥 Watch for changes automatically
    store.watch('queryCount', change => {
      console.log(`Queries: ${change.oldValue} → ${change.newValue}`);
    });
  })
  .proxy({
    include: ['*'],
    before: ctx => {
      // Track queries in store (triggers watchers automatically)
      ctx.store.queryCount++;
    },
  })
  .setup(({ store }) => ({
    query: async (sql: string) => {
      // Access store in methods
      if (!store.connection) throw new Error('Not connected');
      return await store.connection.execute(sql);
    },
    getStats: () => ({
      queries: store.queryCount,
      uptime: Date.now() - store.startTime,
    }),
  }))
  .onReady(({ store, api }) => {
    // Access both store and api in hooks
    console.log(`Database ready. Stats:`, api.getStats());
  });

Reactive Features:

• ✅ Automatic reactivity - No manual setup required
• ✅ Watch changes - watch(), watchAll(), watchBatch()
• ✅ Computed values - Memoized derived state with computed()
• ✅ Batch updates - Group changes with batch()
• ✅ Transactions - Atomic updates with automatic rollback
• ✅ Performance - ~10x faster with optimized cloning and indexed watchers
• ✅ Type inference - No generics needed, full autocomplete
• ✅ Isolated - Each plugin has its own store

📚 See Store System for complete documentation

4. API Extensions

Extend another plugin's API transparently:

const advancedMathPlugin = plugin('advancedMath', '1.0.0')
  .depends(mathPlugin, '^1.0.0')
  .extend(mathPlugin, api => ({
    // Add new methods to math plugin
    power: (base: number, exp: number) => Math.pow(base, exp),
    sqrt: (x: number) => Math.sqrt(x),
  }))
  .setup(() => ({}));

// After kernel initialization:
const math = kernel.get('math');
math.power(2, 3); // ✅ Extended method available!
math.sqrt(16); // ✅ All extensions are merged

5. Method Proxying

Intercept and modify plugin behavior:

const loggingPlugin = plugin('logging', '1.0.0')
  .depends(mathPlugin, '^1.0.0')
  .proxy(mathPlugin, {
    include: ['add'], // Intercept specific method
    before: ctx => {
      console.log(`[LOG] Calling ${ctx.method} with:`, ctx.args);
    },
    after: (result, ctx) => {
      console.log(`[LOG] ${ctx.method} returned:`, result);
      return result;
    },
  })
  .setup(() => ({}));

Proxy Modes:

// 1. Self-proxy: Intercept own methods
.proxy({ include: ['add'], before: ctx => console.log('self') })

// 2. Single plugin proxy: Intercept specific plugin
.depends(mathPlugin, '^1.0.0')
.proxy(mathPlugin, { before: ctx => console.log('single') })

// 3. Dependencies proxy: Intercept all dependencies
.proxy('*', { before: ctx => console.log('all deps') })

// 4. Global proxy: Intercept ALL plugins
.proxy('**', { before: ctx => console.log('global') })

6. Kernel-Level Proxies

Apply proxies at the application level:

const kernel = await createKernel()
  .use(mathPlugin)
  .use(apiPlugin)
  // Global logging for all plugins
  .proxy('**', {
    priority: 80,
    before: ctx => {
      console.log(`[LOG] ${ctx.plugin}.${ctx.method}() called`);
    },
  })
  // Specific auth for API plugin
  .proxy(apiPlugin, {
    priority: 100,
    include: ['create*', 'update*', 'delete*'],
    before: ctx => checkPermissions(ctx.method),
  })
  .start();

7. Lifecycle Hooks

Manage plugin initialization, readiness, and cleanup:

const databasePlugin = plugin('database', '1.0.0')
  .metadata({ connectionString: 'postgresql://localhost:5432/db' })
  .onInit(({ plugins }) => {
    console.log('Initializing database...');
  })
  .onReady(({ plugins }) => {
    console.log('Database ready!');
  })
  .onShutdown(({ plugins }) => {
    console.log('Closing connections...');
  })
  .onError(({ error, plugins }) => {
    console.error('Database error:', error);
  })
  .setup(() => ({
    query: async (sql: string) => {
      /* ... */
    },
  }));

8. Accessing Plugin Metadata and Store

kernel.get() returns complete plugin access - API methods, metadata, and reactive store:

const mathPlugin = plugin('math', '1.0.0')
  .metadata({
    author: 'Zern Team',
    category: 'utilities',
    precision: 'high',
  })
  .store(() => ({
    operationCount: 0,
    lastResult: 0,
  }))
  .setup(({ store }) => ({
    add: (a: number, b: number) => {
      store.operationCount++;
      store.lastResult = a + b;
      return a + b;
    },
  }));

const kernel = await createKernel().use(mathPlugin).start();
const math = kernel.get('math');

// ✅ Use API methods
const result = math.add(10, 5); // 15

// ✅ Access metadata (read-only)
console.log(math.$meta.name); // "math"
console.log(math.$meta.version); // "1.0.0"
console.log(math.$meta.author); // "Zern Team"
console.log(math.$meta.precision); // "high"

// ✅ Access and modify reactive store
console.log(math.$store.operationCount); // 1
console.log(math.$store.lastResult); // 15

// ✅ Watch store changes
math.$store.watch('operationCount', change => {
  console.log(`Operations: ${change.oldValue} → ${change.newValue}`);
});

// ✅ Use all Store methods
math.$store.batch(() => {
  math.$store.operationCount++;
  math.$store.lastResult = 100;
});

const doubled = math.$store.computed(s => s.operationCount * 2);
console.log(doubled.value); // 4

// Next operation triggers watcher
math.add(20, 30); // Logs: "Operations: 2 → 3"

Available on every plugin:

| Property | Description | Example | | ---------------------- | ---------------------------------------- | -------------------------------------------------- | | API methods | All plugin methods with full type safety | math.add(1, 2) | | $meta.name | Plugin name | "math" | | $meta.version | Plugin version | "1.0.0" | | $meta.* | Custom metadata | math.$meta.author | | $store.* | Reactive state properties | math.$store.count | | $store.watch() | Watch specific property | math.$store.watch('count', fn) | | $store.watchAll() | Watch all changes | math.$store.watchAll(fn) | | $store.batch() | Batch multiple updates | math.$store.batch(() => {...}) | | $store.computed() | Create computed values | math.$store.computed(s => s.x * 2) | | $store.transaction() | Atomic updates with rollback | await math.$store.transaction(async () => {...}) |

📚 See Kernel Layer and Store System for complete documentation

9. Direct Method Exports

Use plugins like normal libraries:

// In your plugin file:
export const mathPlugin = plugin('math', '1.0.0').setup(() => ({
  add: (a: number, b: number) => a + b,
  multiply: (a: number, b: number) => a * b,
}));

// Export direct methods
export const { add, multiply } = createDirectExports('math', {
  add: (a: number, b: number): number => 0,
  multiply: (a: number, b: number): number => 0,
});

// Usage in other files:
import { add, multiply } from './math-plugin';
console.log(add(2, 3)); // ✅ Full type safety!
console.log(multiply(4, 5)); // ✅ Autocomplete works!

10. Error Handling

Professional error handling with typed errors, stack traces, and actionable solutions:

import { ValidationError, ErrorSeverity, solution } from '@zern/kernel';

const apiPlugin = plugin('api', '1.0.0')
  .config({
    errors: {
      showStackTrace: true,
      stackTraceLimit: 10,
      formatErrors: true,
      severity: ErrorSeverity.ERROR,
    },
  })
  .onError(async ({ error, phase, method }) => {
    // Global error handler for all plugin phases
    console.error(`[${phase}] Error in ${method}:`, error);

    // Send to monitoring service
    if (error.severity === ErrorSeverity.FATAL) {
      await alertTeam(error);
    }
  })
  .setup(() => ({
    async fetchUser(userId: string) {
      if (!userId) {
        throw new ValidationError(
          { userId },
          {
            severity: ErrorSeverity.ERROR,
            solutions: [
              solution(
                'Provide a valid user ID',
                'The userId parameter cannot be empty',
                'api.fetchUser("user-123")'
              ),
            ],
          }
        );
      }
      return { id: userId, name: 'John' };
    },
  }));

Error Features:

• ✅ Typed Errors - Hierarchical error classes with full type safety
• ✅ Stack Traces - Automatic parsing with file, line, and column
• ✅ Solutions - Actionable suggestions for resolving errors
• ✅ Severities - INFO, WARN, ERROR, FATAL levels
• ✅ Context - Rich metadata about where and why errors occurred
• ✅ Global Hooks - Capture errors from any phase (init, setup, runtime, shutdown)
• ✅ Formatting - Beautiful console output with colors and structure

📚 See Error Handling for complete documentation

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

| Document | Description | | --------------------------------------------------------------- | --------------------------------------------------------------- | | Architecture Overview | System design and layer architecture | | Getting Started | Installation and first steps | | Plugin System | Creating and managing plugins | | Kernel Layer | Kernel initialization and lifecycle | | Extension System | Extending plugin APIs | | Direct Exports | Library-like method exports | | Lifecycle Hooks | Plugin lifecycle management | | Metadata System | Custom metadata with type safety | | API Reference | Complete API documentation | | Best Practices | Patterns and guidelines | | Proxy System | Method interception and proxying | | Store System | Reactive state with watchers, computed values, and transactions | | Error Handling | Typed errors with stack traces, solutions, and severities |

💡 Examples

Explore complete examples in the examples/ directory:

• Basic Usage - Plugin creation, dependencies, and kernel initialization
• Direct Usage - Direct method exports and library-like usage
• Store Demo - Comprehensive reactive store features (watch, computed, batch, transaction)
• Store Example - Store usage with lifecycle hooks and plugin integration
• Store Benchmark - Performance benchmarks (~10x faster with optimizations)
• Proxy Demo - Method interception with multiple proxies
• Proxy Complete Demo - All 4 proxy modes in action
• Kernel Proxy Demo - Kernel-level proxy examples
• Error Handling Demo - Comprehensive error handling with telemetry, retry, and error boundaries
• Simple Plugin - Minimalist plugin boilerplate
• Math Plugin - Opinionated, scalable plugin architecture

🎯 Use Cases

Cross-Cutting Concerns

// Global logging
const loggingPlugin = plugin('logging', '1.0.0')
  .proxy('**', {
    before: ctx => console.log(`[LOG] ${ctx.plugin}.${ctx.method}()`),
  })
  .setup(() => ({}));

// Performance monitoring (using plugin store)
const timingPlugin = plugin('timing', '1.0.0')
  .store(() => new Map<string, number>()) // Map to store start times by method
  .proxy('**', {
    before: ctx => {
      const key = `${ctx.plugin}.${ctx.method}`;
      ctx.store.set(key, Date.now());
    },
    after: (result, ctx) => {
      const key = `${ctx.plugin}.${ctx.method}`;
      const startTime = ctx.store.get(key);
      if (startTime) {
        console.log(`⏱️ ${key} took ${Date.now() - startTime}ms`);
        ctx.store.delete(key);
      }
      return result;
    },
  })
  .setup(() => ({}));

Authentication & Authorization

const authPlugin = plugin('auth', '1.0.0')
  .depends(apiPlugin, '^1.0.0')
  .proxy(apiPlugin, {
    include: ['create*', 'update*', 'delete*'],
    priority: 100, // Execute first
    before: ctx => {
      if (!isAuthenticated()) {
        ctx.skip();
        throw new Error('Unauthorized');
      }
    },
  })
  .setup(() => ({
    /* ... */
  }));

Caching

const cachePlugin = plugin('cache', '1.0.0')
  .depends(apiPlugin, '^1.0.0')
  .proxy(apiPlugin, {
    include: ['get*', 'find*'],
    priority: 90,
    around: async (ctx, next) => {
      const key = `${ctx.method}:${JSON.stringify(ctx.args)}`;
      const cached = cache.get(key);
      if (cached) return cached;

      const result = await next();
      cache.set(key, result);
      return result;
    },
  })
  .setup(() => ({}));

Error Monitoring & Resilience

See examples/plugins/ for complete implementations:

// Telemetry: Track all errors across plugins
const telemetryPlugin = plugin('telemetry', '1.0.0')
  .proxy('**', {
    onError: async (error, ctx) => {
      // Capture and send to monitoring service
      console.log(`[TELEMETRY] Error in ${ctx.plugin}.${ctx.method}:`, error);
      await sendToDatadog({ error, context: ctx });
      throw error; // Re-throw to allow other handlers
    },
  })
  .setup(() => ({
    /* ... */
  }));

// Retry: Automatic retry with exponential backoff
const retryPlugin = plugin('retry', '1.0.0')
  .proxy('**', {
    around: async (ctx, next) => {
      const maxRetries = 3;
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await next();
        } catch (error) {
          if (i === maxRetries - 1) throw error;
          await sleep(Math.pow(2, i) * 1000);
        }
      }
    },
  })
  .setup(() => ({
    /* ... */
  }));

// Error Boundary: Graceful fallbacks
const errorBoundaryPlugin = plugin('errorBoundary', '1.0.0')
  .proxy('**', {
    onError: async (error, ctx) => {
      console.error(`[BOUNDARY] Caught error in ${ctx.plugin}.${ctx.method}`);
      return getFallbackValue(ctx.method); // Return fallback instead of throwing
    },
  })
  .setup(() => ({
    /* ... */
  }));

💡 Pro Tip: These patterns demonstrate how Zern's proxy system enables powerful cross-cutting concerns without modifying plugin code!

🔍 Advanced Configuration

Kernel Configuration

const kernel = await createKernel()
  .use(myPlugin)
  .config({
    autoGlobal: true, // Auto-register as global kernel
    strictVersioning: true, // Enforce strict version matching
    circularDependencies: false, // Disallow circular dependencies
    initializationTimeout: 30000, // Timeout in milliseconds
    extensionsEnabled: true, // Enable plugin extensions
    logLevel: 'info', // Log level: debug | info | warn | error
    errors: {
      showStackTrace: true, // Show stack traces in errors
      stackTraceLimit: 10, // Limit stack trace depth
      formatErrors: true, // Format errors for console output
    },
  })
  .start();

Version Constraints

const authPlugin = plugin('auth', '1.0.0')
  .depends(databasePlugin, '^1.0.0') // Compatible with 1.x.x
  .depends(cachePlugin, '>=2.0.0') // Requires 2.0.0 or higher
  .depends(utilsPlugin, '~1.2.3') // Compatible with 1.2.x
  .setup(({ plugins }) => ({
    /* ... */
  }));

🛠️ API Quick Reference

Creating Plugins

plugin(name: string, version: string)
  .metadata(data: Record<string, unknown>)
  .store(factory: () => state)                 // Reactive store (watch, computed, batch, transaction)
  .config(options: Partial<PluginConfig>)      // Plugin-level configuration (errors, etc)
  .depends(plugin: BuiltPlugin, versionRange?: string)
  .extend(target: BuiltPlugin, fn: (api) => extensions)
  .proxy(config: ProxyConfig)                  // Self-proxy
  .proxy(target: BuiltPlugin, config: ProxyConfig)  // Single plugin
  .proxy('*', config: ProxyConfig)             // All dependencies
  .proxy('**', config: ProxyConfig)            // All plugins
  .onInit(hook: (ctx) => void)
  .onReady(hook: (ctx) => void)
  .onShutdown(hook: (ctx) => void)
  .onError(hook: (ctx) => void)                // Captures errors from all phases
  .setup(fn: (ctx) => api)

Creating Kernel

createKernel()
  .use(plugin: BuiltPlugin)
  .config(config: Partial<KernelConfig>)       // Kernel-level configuration
  .proxy(target: BuiltPlugin, config: ProxyConfig)
  .proxy('**', config: ProxyConfig)
  .build()
  .start()

Using Kernel

kernel.get(name: string)      // Get plugin API + $meta + $store
kernel.shutdown()             // Shutdown all plugins

What kernel.get() returns:

const plugin = kernel.get('myPlugin');

// ✅ API methods (fully typed)
plugin.myMethod();

// ✅ Metadata access
plugin.$meta.name; // Plugin name
plugin.$meta.version; // Plugin version
plugin.$meta.author; // Custom metadata

// ✅ Reactive store access
plugin.$store.count; // Read state
plugin.$store.count++; // Update state
plugin.$store.watch('count', change => {
  console.log(`Changed: ${change.newValue}`);
});

🧪 Testing

import { createKernel, plugin } from '@zern/kernel';

describe('MyPlugin', () => {
  it('should work correctly', async () => {
    const kernel = await createKernel().use(myPlugin).start();

    const api = kernel.get('myPlugin');
    expect(api.myMethod()).toBe('expected');

    await kernel.shutdown();
  });
});

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

📄 License

MIT © ZernJS

⬆ Back to Top

Made with ❤️ by the Zern Team