# SonicJS Plugin Development Guide This comprehensive guide explains how to create plugins for SonicJS using the plugin framework and SDK. Learn from real-world examples including the complete Cache plugin implementation. ## Table of Contents 1. [Plugin System Architecture](#plugin-system-architecture) 2. [Core Concepts](#core-concepts) 3. [Getting Started](#getting-started) 4. [Plugin Manifest](#plugin-manifest) 5. [Creating Custom Plugins](#creating-custom-plugins) 6. [Plugin Lifecycle Hooks](#plugin-lifecycle-hooks) 7. [Hook System](#hook-system) 8. [Route Registration](#route-registration) 9. [Middleware Registration](#middleware-registration) 10. [Service Registration](#service-registration) 11. [Database Models](#database-models) 12. [Admin Interface](#admin-interface) 13. [Real-World Example: Cache Plugin](#real-world-example-cache-plugin) 14. [Testing Plugins](#testing-plugins) 15. [Best Practices](#best-practices) 16. [Advanced Topics](#advanced-topics) ## Plugin System Architecture The SonicJS plugin system is built on several core components that work together to provide a robust, extensible architecture: ``` ┌─────────────────────────────────────────────────────────┐ │ Plugin Manager │ │ - Orchestrates plugin lifecycle │ │ - Manages dependencies │ │ - Coordinates initialization │ └──────────────┬──────────────────────────────────────────┘ │ ┌──────┴──────┬──────────────┬──────────────┐ │ │ │ │ ┌───────▼────┐ ┌──────▼────┐ ┌──────▼────┐ ┌──────▼────┐ │ Plugin │ │ Hook │ │ Plugin │ │ Plugin │ │ Registry │ │ System │ │ Validator │ │ Context │ └────────────┘ └───────────┘ └───────────┘ └───────────┘ ``` ### Core Components #### 1. Plugin Manager Located at `/src/plugins/core/plugin-manager.ts` The Plugin Manager is the central orchestrator: - Manages plugin installation, activation, and deactivation - Resolves plugin dependencies - Provides plugin context - Registers plugin routes, middleware, and hooks - Handles plugin lifecycle events ```typescript export class PluginManager implements IPluginManager { public readonly registry: PluginRegistry public readonly hooks: HookSystem private validator: PluginValidator private context?: PluginContext private scopedHooks: Map = new Map() private pluginRoutes: Map = new Map() async install(plugin: Plugin, config?: PluginConfig): Promise async uninstall(name: string): Promise async initialize(context: PluginContext): Promise async loadPlugins(configs: PluginConfig[]): Promise } ``` #### 2. Plugin Registry Located at `/src/plugins/core/plugin-registry.ts` Manages plugin registration and status: - Tracks installed plugins - Manages plugin configuration - Handles plugin activation/deactivation - Resolves dependency order - Validates plugin requirements ```typescript export class PluginRegistryImpl implements PluginRegistry { async register(plugin: Plugin): Promise async unregister(name: string): Promise async activate(name: string): Promise async deactivate(name: string): Promise resolveLoadOrder(): string[] getDependencyGraph(): Map } ``` #### 3. Hook System Located at `/src/plugins/core/hook-system.ts` Provides event-driven extensibility: - Registers hook handlers - Executes hooks with priority ordering - Supports hook cancellation - Prevents infinite recursion - Provides scoped hooks per plugin ```typescript export class HookSystemImpl implements HookSystem { register(hookName: string, handler: HookHandler, priority?: number): void async execute(hookName: string, data: any, context?: any): Promise unregister(hookName: string, handler: HookHandler): void getHooks(hookName: string): PluginHook[] createScope(pluginName: string): ScopedHookSystem } ``` #### 4. Plugin Validator Located at `/src/plugins/core/plugin-validator.ts` Ensures plugin integrity: - Validates plugin structure - Checks dependencies - Verifies compatibility - Reports validation errors and warnings ## Core Concepts ### Plugin Interface Every plugin implements the `Plugin` interface defined in `/src/plugins/types.ts`: ```typescript export interface Plugin { // Metadata name: string version: string description?: string author?: { name: string email?: string url?: string } dependencies?: string[] compatibility?: string license?: string // Extension Points routes?: PluginRoutes[] middleware?: PluginMiddleware[] models?: PluginModel[] services?: PluginService[] adminPages?: PluginAdminPage[] adminComponents?: PluginComponent[] menuItems?: PluginMenuItem[] hooks?: PluginHook[] // Lifecycle Hooks install?: (context: PluginContext) => Promise uninstall?: (context: PluginContext) => Promise activate?: (context: PluginContext) => Promise deactivate?: (context: PluginContext) => Promise configure?: (config: PluginConfig) => Promise } ``` ### Plugin Context The `PluginContext` provides plugins access to core SonicJS APIs: ```typescript export interface PluginContext { db: D1Database // Database instance kv: KVNamespace // Key-value storage r2?: R2Bucket // R2 storage bucket config: PluginConfig // Plugin configuration services: { auth: AuthService content: ContentService media: MediaService } hooks: HookSystem // Hook system for events logger: PluginLogger // Logging utilities } ``` ### Standard Hooks SonicJS defines standard hooks for common events: ```typescript export const HOOKS = { // Application lifecycle APP_INIT: 'app:init', APP_READY: 'app:ready', APP_SHUTDOWN: 'app:shutdown', // Request lifecycle REQUEST_START: 'request:start', REQUEST_END: 'request:end', REQUEST_ERROR: 'request:error', // Authentication AUTH_LOGIN: 'auth:login', AUTH_LOGOUT: 'auth:logout', AUTH_REGISTER: 'auth:register', USER_LOGIN: 'user:login', USER_LOGOUT: 'user:logout', // Content lifecycle CONTENT_CREATE: 'content:create', CONTENT_UPDATE: 'content:update', CONTENT_DELETE: 'content:delete', CONTENT_PUBLISH: 'content:publish', CONTENT_SAVE: 'content:save', // Media lifecycle MEDIA_UPLOAD: 'media:upload', MEDIA_DELETE: 'media:delete', MEDIA_TRANSFORM: 'media:transform', // Plugin lifecycle PLUGIN_INSTALL: 'plugin:install', PLUGIN_UNINSTALL: 'plugin:uninstall', PLUGIN_ACTIVATE: 'plugin:activate', PLUGIN_DEACTIVATE: 'plugin:deactivate', // Admin interface ADMIN_MENU_RENDER: 'admin:menu:render', ADMIN_PAGE_RENDER: 'admin:page:render', // Database DB_MIGRATE: 'db:migrate', DB_SEED: 'db:seed', } as const ``` ## Getting Started ### Prerequisites - TypeScript knowledge - Understanding of Hono.js framework - Familiarity with SonicJS architecture - Node.js and npm installed ### Plugin Directory Structure ``` src/plugins/ ├── your-plugin/ │ ├── index.ts # Main plugin file │ ├── manifest.json # Plugin manifest │ ├── routes.ts # API routes │ ├── services/ # Business logic │ │ ├── service-a.ts │ │ └── service-b.ts │ ├── middleware/ # Custom middleware │ ├── models/ # Database models │ ├── migrations/ # Database migrations │ ├── tests/ # Plugin tests │ │ └── plugin.test.ts │ └── README.md # Plugin documentation ``` ### Creating Your First Plugin Create a new directory in `/src/plugins/` and add an `index.ts` file: ```typescript import { PluginBuilder } from '../sdk/plugin-builder' import { Hono } from 'hono' // Create plugin using builder pattern const plugin = PluginBuilder.create({ name: 'my-first-plugin', version: '1.0.0', description: 'My first SonicJS plugin' }) // Add metadata plugin.metadata({ author: { name: 'Your Name', email: 'you@example.com', url: 'https://yourwebsite.com' }, license: 'MIT', compatibility: '^0.1.0' }) // Add a simple route const routes = new Hono() routes.get('/hello', (c) => c.json({ message: 'Hello from my plugin!' })) plugin.addRoute('/api/my-plugin', routes, { description: 'My plugin API endpoints' }) // Add lifecycle hooks plugin.lifecycle({ activate: async (context) => { context.logger.info('Plugin activated!') }, deactivate: async (context) => { context.logger.info('Plugin deactivated!') } }) // Build and export export default plugin.build() ``` ## Plugin Manifest The `manifest.json` file defines plugin metadata and configuration. Here's a complete example from the Cache plugin (`/src/plugins/cache/manifest.json`): ```json { "id": "cache", "name": "Cache System", "version": "1.0.0-alpha.1", "description": "Three-tiered caching system with in-memory and KV storage. Provides automatic caching for content, users, media, and API responses with configurable TTL and invalidation patterns.", "author": "SonicJS", "homepage": "https://sonicjs.com/plugins/cache", "repository": "https://github.com/lane711/sonicjs-ai/tree/main/src/plugins/cache", "license": "MIT", "category": "performance", "tags": ["cache", "performance", "optimization", "kv", "memory"], "dependencies": [], "settings": { "memoryEnabled": { "type": "boolean", "label": "Enable In-Memory Cache", "description": "Fast tier-1 caching in memory (region-specific)", "default": true }, "kvEnabled": { "type": "boolean", "label": "Enable KV Cache", "description": "Tier-2 caching in Cloudflare KV (global, persistent)", "default": false }, "defaultTTL": { "type": "number", "label": "Default TTL (seconds)", "description": "Default time-to-live for cache entries", "default": 3600 }, "maxMemorySize": { "type": "number", "label": "Max Memory Size (MB)", "description": "Maximum size of in-memory cache in megabytes", "default": 50 } }, "hooks": { "onActivate": "activate", "onDeactivate": "deactivate", "onConfigure": "configure" }, "routes": [ { "path": "/admin/cache/stats", "method": "GET", "handler": "getStats", "description": "Get cache statistics" }, { "path": "/admin/cache/clear", "method": "POST", "handler": "clearCache", "description": "Clear all cache entries" }, { "path": "/admin/cache/invalidate", "method": "POST", "handler": "invalidatePattern", "description": "Invalidate cache entries matching pattern" } ], "permissions": { "cache.view": "View cache statistics", "cache.clear": "Clear cache entries", "cache.invalidate": "Invalidate cache patterns" } } ``` ### Manifest Schema ```typescript interface PluginManifest { id: string // Unique plugin identifier name: string // Display name version: string // Semantic version description: string // Detailed description author: string // Author name or organization homepage?: string // Plugin homepage URL repository?: string // Source repository URL license: string // License identifier category?: string // Plugin category tags?: string[] // Searchable tags dependencies?: string[] // Required plugin dependencies settings?: { // Plugin settings schema [key: string]: { type: 'boolean' | 'number' | 'string' | 'object' label: string description: string default: any } } hooks?: { // Lifecycle hook mapping [key: string]: string } routes?: Array<{ // Route definitions path: string method: string handler: string description: string }> permissions?: { // Permission definitions [key: string]: string } } ``` ## Creating Custom Plugins ### Step-by-Step Example: Weather Plugin Let's create a complete weather plugin from scratch: #### Step 1: Create Plugin Structure ```bash mkdir -p src/plugins/weather/{services,routes,tests} ``` #### Step 2: Create Manifest File: `/src/plugins/weather/manifest.json` ```json { "id": "weather", "name": "Weather Service", "version": "1.0.0", "description": "Provides weather information and forecasts", "author": "Your Name", "license": "MIT", "category": "utility", "tags": ["weather", "api", "forecast"], "dependencies": [], "settings": { "apiKey": { "type": "string", "label": "Weather API Key", "description": "API key for weather service", "default": "" }, "defaultCity": { "type": "string", "label": "Default City", "description": "Default city for weather queries", "default": "London" }, "cacheEnabled": { "type": "boolean", "label": "Enable Caching", "description": "Cache weather data to reduce API calls", "default": true }, "cacheTTL": { "type": "number", "label": "Cache TTL (seconds)", "description": "How long to cache weather data", "default": 300 } } } ``` #### Step 3: Create Weather Service File: `/src/plugins/weather/services/weather-service.ts` ```typescript /** * Weather Service * Fetches and caches weather data */ export interface WeatherData { city: string temperature: number condition: string humidity: number windSpeed: number forecast: Array<{ date: string high: number low: number condition: string }> } export class WeatherService { private apiKey: string private cache?: any constructor(apiKey: string, cache?: any) { this.apiKey = apiKey this.cache = cache } /** * Get current weather for a city */ async getCurrentWeather(city: string): Promise { // Check cache first if (this.cache) { const cacheKey = `weather:current:${city}` const cached = await this.cache.get(cacheKey) if (cached) { console.log(`Cache hit for ${city}`) return cached } } // Fetch from API (simulated) const weather: WeatherData = { city, temperature: 22, condition: 'Partly cloudy', humidity: 65, windSpeed: 12, forecast: [ { date: '2025-01-07', high: 24, low: 18, condition: 'Sunny' }, { date: '2025-01-08', high: 23, low: 17, condition: 'Cloudy' }, { date: '2025-01-09', high: 25, low: 19, condition: 'Sunny' } ] } // Store in cache if (this.cache) { const cacheKey = `weather:current:${city}` await this.cache.set(cacheKey, weather) } return weather } /** * Get weather forecast */ async getForecast(city: string, days: number = 7): Promise { const weather = await this.getCurrentWeather(city) return weather.forecast.slice(0, days) } /** * Search cities */ async searchCities(query: string): Promise { // Simulated city search const cities = ['London', 'Paris', 'New York', 'Tokyo', 'Sydney'] return cities.filter(city => city.toLowerCase().includes(query.toLowerCase()) ) } } ``` #### Step 4: Create Routes File: `/src/plugins/weather/routes.ts` ```typescript import { Hono } from 'hono' import type { Context } from 'hono' import { WeatherService } from './services/weather-service.js' const app = new Hono() // Middleware to inject weather service app.use('*', async (c, next) => { // Get service from plugin context (would be set during plugin activation) const weatherService = c.get('weatherService') if (!weatherService) { return c.json({ error: 'Weather service not initialized' }, 500) } await next() }) /** * GET /api/weather/current?city=London * Get current weather for a city */ app.get('/current', async (c: Context) => { const city = c.req.query('city') if (!city) { return c.json({ success: false, error: 'City parameter is required' }, 400) } try { const weatherService = c.get('weatherService') as WeatherService const weather = await weatherService.getCurrentWeather(city) return c.json({ success: true, data: weather, timestamp: new Date().toISOString() }) } catch (error) { console.error('Weather API error:', error) return c.json({ success: false, error: 'Failed to fetch weather data' }, 500) } }) /** * GET /api/weather/forecast?city=London&days=7 * Get weather forecast */ app.get('/forecast', async (c: Context) => { const city = c.req.query('city') const days = parseInt(c.req.query('days') || '7') if (!city) { return c.json({ success: false, error: 'City parameter is required' }, 400) } try { const weatherService = c.get('weatherService') as WeatherService const forecast = await weatherService.getForecast(city, days) return c.json({ success: true, data: { city, forecast }, timestamp: new Date().toISOString() }) } catch (error) { console.error('Forecast API error:', error) return c.json({ success: false, error: 'Failed to fetch forecast data' }, 500) } }) /** * GET /api/weather/search?q=Lon * Search for cities */ app.get('/search', async (c: Context) => { const query = c.req.query('q') if (!query || query.length < 2) { return c.json({ success: false, error: 'Query must be at least 2 characters' }, 400) } try { const weatherService = c.get('weatherService') as WeatherService const cities = await weatherService.searchCities(query) return c.json({ success: true, data: cities, timestamp: new Date().toISOString() }) } catch (error) { console.error('City search error:', error) return c.json({ success: false, error: 'Failed to search cities' }, 500) } }) export default app ``` #### Step 5: Create Main Plugin File File: `/src/plugins/weather/index.ts` ```typescript import { PluginBuilder } from '../sdk/plugin-builder' import { PluginContext } from '../types' import weatherRoutes from './routes.js' import { WeatherService } from './services/weather-service.js' import { getCacheService } from '../cache/index.js' // Create plugin const plugin = PluginBuilder.create({ name: 'weather', version: '1.0.0', description: 'Weather information and forecast plugin' }) // Add metadata plugin.metadata({ author: { name: 'Your Name', email: 'you@example.com' }, license: 'MIT', compatibility: '^0.1.0', dependencies: [] // Optional: add 'cache' if using cache plugin }) // Store service instance let weatherService: WeatherService | null = null // Add routes plugin.addRoute('/api/weather', weatherRoutes, { description: 'Weather API endpoints', priority: 5 }) // Add admin page plugin.addAdminPage( '/weather', 'Weather', 'WeatherDashboard', { description: 'View weather information', permissions: ['admin'], icon: 'cloud' } ) // Add menu item plugin.addMenuItem('Weather', '/admin/weather', { icon: 'cloud', order: 50 }) // Add lifecycle hooks plugin.lifecycle({ activate: async (context: PluginContext) => { console.log('Activating weather plugin...') const { apiKey, cacheEnabled } = context.config // Validate API key if (!apiKey) { throw new Error('Weather API key is required') } // Get cache service if enabled let cache = null if (cacheEnabled) { try { cache = getCacheService({ namespace: 'weather', ttl: context.config.cacheTTL || 300, memoryEnabled: true, kvEnabled: false, invalidateOn: [], version: 'v1' }) } catch (error) { console.warn('Cache service not available, proceeding without cache') } } // Initialize weather service weatherService = new WeatherService(apiKey, cache) console.log('Weather plugin activated successfully') }, deactivate: async (context: PluginContext) => { console.log('Deactivating weather plugin...') weatherService = null console.log('Weather plugin deactivated') }, configure: async (config: any) => { console.log('Configuring weather plugin...', config) // Reconfigure service if active if (weatherService && config.apiKey) { const cache = config.cacheEnabled ? getCacheService({ namespace: 'weather', ttl: config.cacheTTL || 300, memoryEnabled: true, kvEnabled: false, invalidateOn: [], version: 'v1' }) : null weatherService = new WeatherService(config.apiKey, cache) } } }) // Add hook to inject service into request context plugin.addHook('request:start', async (data, context) => { if (weatherService) { data.context.set('weatherService', weatherService) } return data }, { priority: 5, description: 'Inject weather service into request context' }) // Export plugin export default plugin.build() ``` ## Plugin Lifecycle Hooks Plugins have five lifecycle stages with corresponding hooks: ### 1. Install Called when the plugin is first installed. Use this to: - Create database tables - Initialize default configuration - Set up initial data ```typescript plugin.lifecycle({ install: async (context: PluginContext) => { console.log('Installing plugin...') // Create database tables await context.db.exec(` CREATE TABLE IF NOT EXISTS plugin_data ( id INTEGER PRIMARY KEY, key TEXT NOT NULL, value TEXT, created_at INTEGER DEFAULT (strftime('%s', 'now')) ) `) // Initialize configuration await context.db.exec(` INSERT INTO plugin_data (key, value) VALUES ('version', '1.0.0'), ('installed_at', ${Date.now()}) `) console.log('Plugin installed successfully') } }) ``` ### 2. Activate Called when the plugin is activated. Use this to: - Initialize services - Register event listeners - Start background tasks ```typescript plugin.lifecycle({ activate: async (context: PluginContext) => { console.log('Activating plugin...') // Initialize services const config = context.config const service = new MyService(config) // Store in context for later use context.services.myService = service // Register event listeners context.hooks.register('content:save', async (data) => { await service.handleContentSave(data) return data }) console.log('Plugin activated') } }) ``` ### 3. Configure Called when plugin configuration changes. Use this to: - Update service settings - Reconfigure connections - Apply new settings ```typescript plugin.lifecycle({ configure: async (config: PluginConfig) => { console.log('Configuring plugin...', config) // Validate configuration if (config.apiKey && config.apiKey.length < 10) { throw new Error('Invalid API key') } // Apply configuration changes if (myService) { myService.updateConfig(config) } console.log('Plugin configured') } }) ``` ### 4. Deactivate Called when the plugin is deactivated. Use this to: - Stop background tasks - Unregister event listeners - Clean up resources ```typescript plugin.lifecycle({ deactivate: async (context: PluginContext) => { console.log('Deactivating plugin...') // Stop background tasks if (backgroundTask) { backgroundTask.stop() } // Clean up resources if (context.services.myService) { await context.services.myService.cleanup() delete context.services.myService } console.log('Plugin deactivated') } }) ``` ### 5. Uninstall Called when the plugin is removed. Use this to: - Remove database tables - Delete plugin data - Clean up all traces ```typescript plugin.lifecycle({ uninstall: async (context: PluginContext) => { console.log('Uninstalling plugin...') // Remove database tables await context.db.exec('DROP TABLE IF EXISTS plugin_data') // Delete plugin files/configuration await context.kv.delete('plugin:config') console.log('Plugin uninstalled') } }) ``` ### Complete Lifecycle Example Here's a complete example from the Cache plugin: ```typescript export class CachePlugin { async activate(context: PluginContext): Promise { const settings = context.config || {} console.log('Cache plugin activated', { memoryEnabled: settings.memoryEnabled ?? true, kvEnabled: settings.kvEnabled ?? false, defaultTTL: settings.defaultTTL ?? 3600 }) // Initialize default cache services for (const [namespace, config] of Object.entries(CACHE_CONFIGS)) { getCacheService({ ...config, memoryEnabled: settings.memoryEnabled ?? config.memoryEnabled, kvEnabled: settings.kvEnabled ?? config.kvEnabled, ttl: settings.defaultTTL ?? config.ttl }) } // Setup event-based cache invalidation setupCacheInvalidation() } async deactivate(): Promise { console.log('Cache plugin deactivated - clearing all caches') await clearAllCaches() } async configure(settings: Record): Promise { console.log('Cache plugin configured', settings) // Reconfigure all cache instances with new settings for (const [namespace, config] of Object.entries(CACHE_CONFIGS)) { getCacheService({ ...config, memoryEnabled: settings.memoryEnabled ?? config.memoryEnabled, kvEnabled: settings.kvEnabled ?? config.kvEnabled, ttl: settings.defaultTTL ?? config.ttl }) } } } ``` ## Hook System The hook system (`/src/plugins/core/hook-system.ts`) provides event-driven extensibility. Plugins can register hooks to listen for events and modify data flow. ### Hook Priority Hooks execute in priority order (lower number = earlier execution): - Priority 1-5: Critical hooks that must run first - Priority 6-10: Normal hooks (default is 10) - Priority 11+: Lower priority hooks ### Registering Hooks ```typescript // Register a hook with default priority (10) plugin.addHook('content:save', async (data, context) => { console.log('Content being saved:', data.title) // Modify the data data.processedAt = Date.now() // Return modified data return data }) // Register a hook with custom priority plugin.addHook('content:save', async (data, context) => { // This runs before the above hook data.validated = true return data }, { priority: 5, description: 'Validate content before saving' }) ``` ### Hook Context Hooks receive a context object: ```typescript export interface HookContext { plugin: string // Plugin that triggered the hook context: PluginContext // Full plugin context cancel?: () => void // Cancel further hook execution } plugin.addHook('content:delete', async (data, context) => { // Check if content can be deleted if (data.protected) { console.warn('Cannot delete protected content') context.cancel?.() // Cancel further hooks and operation } return data }) ``` ### Executing Hooks Plugins can trigger their own hooks: ```typescript // From hook-system.ts async execute(hookName: string, data: any, context?: any): Promise { const hooks = this.hooks.get(hookName) if (!hooks || hooks.length === 0) { return data } // Prevent infinite recursion if (this.executing.has(hookName)) { console.warn(`Hook recursion detected for: ${hookName}`) return data } this.executing.add(hookName) try { let result = data let cancelled = false const hookContext: HookContext = { plugin: '', context: context || {}, cancel: () => { cancelled = true } } for (const hook of hooks) { if (cancelled) { console.debug(`Hook execution cancelled: ${hookName}`) break } try { console.debug(`Executing hook: ${hookName} (priority: ${hook.priority})`) result = await hook.handler(result, hookContext) } catch (error) { console.error(`Hook execution failed: ${hookName}`, error) // Continue executing other hooks unless critical error if (error instanceof Error && error.message.includes('CRITICAL')) { throw error } } } return result } finally { this.executing.delete(hookName) } } ``` ### Scoped Hooks Each plugin gets its own scoped hook system: ```typescript // From hook-system.ts export class ScopedHookSystem { private registeredHooks: { hookName: string; handler: HookHandler }[] = [] constructor( private parent: HookSystemImpl, private pluginName: string ) {} register(hookName: string, handler: HookHandler, priority?: number): void { this.parent.register(hookName, handler, priority) this.registeredHooks.push({ hookName, handler }) } async execute(hookName: string, data: any, context?: any): Promise { return this.parent.execute(hookName, data, context) } unregisterAll(): void { for (const { hookName, handler } of this.registeredHooks) { this.parent.unregister(hookName, handler) } this.registeredHooks.length = 0 } } ``` ### Hook Utilities The hook system provides utility functions: ```typescript // Create namespaced hook name const hookName = HookUtils.createHookName('my-plugin', 'data-processed') // Result: 'my-plugin:data-processed' // Parse hook name const { namespace, event } = HookUtils.parseHookName('my-plugin:data-processed') // namespace: 'my-plugin', event: 'data-processed' // Create debounced hook handler const debouncedHandler = HookUtils.debounce( async (data, context) => { console.log('Processing data:', data) return data }, 1000 // 1 second delay ) // Create throttled hook handler const throttledHandler = HookUtils.throttle( async (data, context) => { console.log('Processing data:', data) return data }, 5000 // Maximum once per 5 seconds ) ``` ### Real-World Hook Examples From the Auth plugin (`/src/plugins/core-plugins/auth-plugin.ts`): ```typescript // Track user login builder.addHook('auth:login', async (data: any) => { console.info(`User login attempt: ${data.email}`) return data }, { priority: 10, description: 'Handle user login events' }) // Track authentication status builder.addHook(HOOKS.REQUEST_START, async (data: any) => { const authHeader = data.request?.headers?.authorization if (authHeader) { data.authenticated = true } return data }, { priority: 5, description: 'Track authentication status on requests' }) ``` From the Media plugin (`/src/plugins/core-plugins/media-plugin.ts`): ```typescript // Auto-generate thumbnails builder.addHook('media:upload', async (data: any, context: any) => { console.info(`Media upload event: ${data.filename}`) if (data.mimeType?.startsWith('image/')) { data.generateThumbnail = true } return data }, { priority: 10, description: 'Handle media upload events' }) // Track media usage in content builder.addHook(HOOKS.CONTENT_SAVE, async (data: any, context: any) => { const content = data.content || '' const mediaReferences = content.match(/\/media\/[a-zA-Z0-9-]+/g) || [] if (mediaReferences.length > 0) { data.mediaReferences = mediaReferences console.debug(`Content references ${mediaReferences.length} media files`) } return data }, { priority: 8, description: 'Track media usage in content' }) ``` ## Route Registration Routes define API endpoints that your plugin exposes. SonicJS uses Hono.js for routing. ### Basic Route Registration ```typescript import { Hono } from 'hono' // Create a Hono app for your routes const routes = new Hono() // GET endpoint routes.get('/items', async (c) => { const items = [ { id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' } ] return c.json({ success: true, data: items }) }) // POST endpoint routes.post('/items', async (c) => { const body = await c.req.json() // Validate input if (!body.name) { return c.json({ success: false, error: 'Name is required' }, 400) } const item = { id: Date.now(), name: body.name, createdAt: new Date().toISOString() } return c.json({ success: true, data: item }, 201) }) // Register routes with your plugin plugin.addRoute('/api/my-plugin', routes, { description: 'My plugin API endpoints', requiresAuth: false, priority: 10 }) ``` ### Advanced Route Examples From the Cache plugin routes (`/src/plugins/cache/routes.ts`): ```typescript import { Hono } from 'hono' import type { Context } from 'hono' import { getAllCacheStats, clearAllCaches, getCacheService } from './services/cache.js' import { CACHE_CONFIGS } from './services/cache-config.js' const app = new Hono() /** * GET /admin/cache/stats * Detailed statistics for all namespaces */ app.get('/stats', async (c: Context) => { const stats = getAllCacheStats() return c.json({ success: true, data: stats, timestamp: new Date().toISOString() }) }) /** * GET /admin/cache/stats/:namespace * Statistics for a specific namespace */ app.get('/stats/:namespace', async (c: Context) => { const namespace = c.req.param('namespace') const config = CACHE_CONFIGS[namespace] if (!config) { return c.json({ success: false, error: `Unknown namespace: ${namespace}` }, 404) } const cache = getCacheService(config) const stats = cache.getStats() return c.json({ success: true, data: { namespace, config, stats }, timestamp: new Date().toISOString() }) }) /** * POST /admin/cache/clear * Clear all cache entries */ app.post('/clear', async (c: Context) => { await clearAllCaches() return c.json({ success: true, message: 'All cache entries cleared', timestamp: new Date().toISOString() }) }) /** * POST /admin/cache/invalidate * Invalidate cache entries matching a pattern */ app.post('/invalidate', async (c: Context) => { const body = await c.req.json() const { pattern, namespace } = body if (!pattern) { return c.json({ success: false, error: 'Pattern is required' }, 400) } let totalInvalidated = 0 if (namespace) { const config = CACHE_CONFIGS[namespace] if (!config) { return c.json({ success: false, error: `Unknown namespace: ${namespace}` }, 404) } const cache = getCacheService(config) totalInvalidated = await cache.invalidate(pattern) } else { // Invalidate from all namespaces for (const config of Object.values(CACHE_CONFIGS)) { const cache = getCacheService(config) totalInvalidated += await cache.invalidate(pattern) } } return c.json({ success: true, invalidated: totalInvalidated, pattern, namespace: namespace || 'all', timestamp: new Date().toISOString() }) }) export default app ``` ### Route Groups Organize related routes: ```typescript const api = new Hono() // User routes const users = new Hono() users.get('/', async (c) => c.json({ users: [] })) users.post('/', async (c) => c.json({ created: true })) users.get('/:id', async (c) => { const id = c.req.param('id') return c.json({ user: { id } }) }) // Mount user routes api.route('/users', users) // Posts routes const posts = new Hono() posts.get('/', async (c) => c.json({ posts: [] })) posts.post('/', async (c) => c.json({ created: true })) // Mount posts routes api.route('/posts', posts) // Register with plugin plugin.addRoute('/api/my-plugin', api) ``` ### Query Parameters ```typescript routes.get('/search', async (c) => { const query = c.req.query('q') const page = parseInt(c.req.query('page') || '1') const limit = parseInt(c.req.query('limit') || '20') const sortBy = c.req.query('sort') || 'name' // Validate if (!query || query.length < 2) { return c.json({ error: 'Query must be at least 2 characters' }, 400) } const results = await searchItems(query, { page, limit, sortBy }) return c.json({ success: true, data: results, pagination: { page, limit, total: results.length } }) }) ``` ### Request Body Validation ```typescript import { z } from 'zod' // Define schema const createItemSchema = z.object({ name: z.string().min(3).max(100), description: z.string().optional(), price: z.number().positive(), tags: z.array(z.string()).optional() }) routes.post('/items', async (c) => { try { const body = await c.req.json() // Validate const validated = createItemSchema.parse(body) // Create item const item = { id: Date.now(), ...validated, createdAt: new Date().toISOString() } return c.json({ success: true, data: item }, 201) } catch (error) { if (error instanceof z.ZodError) { return c.json({ success: false, error: 'Validation failed', details: error.errors }, 400) } throw error } }) ``` ## Middleware Registration Middleware allows you to intercept and modify requests and responses. ### Single Middleware ```typescript // Global middleware (runs on all requests) plugin.addSingleMiddleware('request-logger', async (c, next) => { const start = Date.now() const path = c.req.path await next() const duration = Date.now() - start console.log(`${c.req.method} ${path} - ${duration}ms`) }, { description: 'Log all requests with duration', global: true, priority: 1 }) // Route-specific middleware plugin.addSingleMiddleware('auth-check', async (c, next) => { const token = c.req.header('authorization') if (!token) { return c.json({ error: 'Unauthorized' }, 401) } // Verify token const user = await verifyToken(token) if (!user) { return c.json({ error: 'Invalid token' }, 401) } // Add user to context c.set('user', user) await next() }, { description: 'Verify authentication token', routes: ['/api/protected/*'], priority: 5 }) ``` ### Middleware Examples from Auth Plugin ```typescript // Session management middleware builder.addSingleMiddleware('auth-session', async (c: any, next: any) => { const sessionId = c.req.header('x-session-id') if (sessionId) { c.set('sessionId', sessionId) } await next() }, { description: 'Session management middleware', global: true, priority: 5 }) // Rate limiting middleware builder.addSingleMiddleware('auth-rate-limit', async (c: any, next: any) => { const path = c.req.path if (path.startsWith('/api/auth/')) { const clientIP = c.req.header('CF-Connecting-IP') || 'unknown' console.debug(`Auth rate limit check for IP: ${clientIP}`) // Rate limiting logic would go here } await next() }, { description: 'Rate limiting for authentication endpoints', routes: ['/api/auth/*'], priority: 3 }) ``` ### Error Handling Middleware ```typescript plugin.addSingleMiddleware('error-handler', async (c, next) => { try { await next() } catch (error) { console.error('Request error:', error) const message = error instanceof Error ? error.message : 'Internal server error' const status = error.status || 500 return c.json({ success: false, error: message, timestamp: new Date().toISOString() }, status) } }, { description: 'Handle errors from route handlers', global: true, priority: 0 // Run first }) ``` ### CORS Middleware ```typescript plugin.addSingleMiddleware('cors', async (c, next) => { // Handle preflight if (c.req.method === 'OPTIONS') { return new Response(null, { headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', 'Access-Control-Max-Age': '86400' } }) } await next() // Add CORS headers to response c.header('Access-Control-Allow-Origin', '*') c.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS') c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization') }, { description: 'Enable CORS for API endpoints', global: true, priority: 2 }) ``` ## Service Registration Services encapsulate business logic and can be shared across your plugin. ### Basic Service ```typescript // Define service class EmailService { private apiKey: string constructor(apiKey: string) { this.apiKey = apiKey } async sendEmail(to: string, subject: string, body: string): Promise { console.log(`Sending email to ${to}: ${subject}`) // Email sending logic here return true } async validateEmail(email: string): Promise { const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/ return regex.test(email) } } // Register service plugin.addService('emailService', new EmailService('api-key-here'), { description: 'Email sending and validation service', singleton: true }) ``` ### Service with Dependencies ```typescript class NotificationService { constructor( private emailService: EmailService, private smsService: SMSService ) {} async notify(userId: string, message: string, channels: string[]): Promise { for (const channel of channels) { if (channel === 'email') { const user = await getUser(userId) await this.emailService.sendEmail(user.email, 'Notification', message) } else if (channel === 'sms') { const user = await getUser(userId) await this.smsService.sendSMS(user.phone, message) } } } } plugin.addService('notificationService', new NotificationService( emailService, smsService ), { description: 'Multi-channel notification service', dependencies: ['emailService', 'smsService'], singleton: true }) ``` ### Service Examples from Plugins From the Auth plugin: ```typescript builder.addService('authService', { validateToken: (_token: string) => { return { valid: true, userId: 1 } }, generateToken: (userId: number) => { return `token-${userId}-${Date.now()}` }, hashPassword: (password: string) => { return `hashed-${password}` }, verifyPassword: (password: string, hash: string) => { return hash === `hashed-${password}` } }, { description: 'Core authentication service', singleton: true }) ``` From the Media plugin: ```typescript builder.addService('mediaService', { uploadFile: async (file: File, options?: any) => { return { id: `media-${Date.now()}`, url: `/media/${file.name}`, size: file.size, type: file.type } }, deleteFile: async (id: string) => { console.info(`Deleting media file: ${id}`) return true }, processImage: async (id: string, operations: any[]) => { console.info(`Processing image ${id} with operations:`, operations) return { jobId: `job-${id}-${Date.now()}` } }, getMetadata: async (id: string) => { return { width: 1920, height: 1080, format: 'JPEG', size: 1024000 } } }, { description: 'Core media processing service', singleton: true }) ``` ## Database Models Define database structures for your plugin using Zod schemas and migrations. ### Basic Model ```typescript import { z } from 'zod' import { PluginHelpers } from '../sdk/plugin-builder' // Define Zod schema const userSchema = z.object({ email: z.string().email(), firstName: z.string(), lastName: z.string(), active: z.boolean().default(true), metadata: z.record(z.any()).optional() }) // Create migration const userMigration = PluginHelpers.createMigration('plugin_users', [ { name: 'id', type: 'INTEGER', primaryKey: true }, { name: 'email', type: 'TEXT', nullable: false, unique: true }, { name: 'first_name', type: 'TEXT', nullable: false }, { name: 'last_name', type: 'TEXT', nullable: false }, { name: 'active', type: 'INTEGER', nullable: false, defaultValue: '1' }, { name: 'metadata', type: 'TEXT', nullable: true }, { name: 'created_at', type: 'INTEGER', nullable: false, defaultValue: "(strftime('%s', 'now'))" }, { name: 'updated_at', type: 'INTEGER', nullable: true } ]) // Register model plugin.addModel('PluginUser', { tableName: 'plugin_users', schema: userSchema, migrations: [userMigration] }) ``` ### Model with Relationships ```typescript // Product model const productSchema = z.object({ name: z.string(), description: z.string().optional(), price: z.number().positive(), categoryId: z.number(), tags: z.array(z.string()).optional() }) const productMigration = PluginHelpers.createMigration('products', [ { name: 'id', type: 'INTEGER', primaryKey: true }, { name: 'name', type: 'TEXT', nullable: false }, { name: 'description', type: 'TEXT', nullable: true }, { name: 'price', type: 'REAL', nullable: false }, { name: 'category_id', type: 'INTEGER', nullable: false }, { name: 'tags', type: 'TEXT', nullable: true }, { name: 'created_at', type: 'INTEGER', nullable: false } ]) plugin.addModel('Product', { tableName: 'products', schema: productSchema, migrations: [productMigration], relationships: [ { type: 'oneToMany', target: 'Category', foreignKey: 'category_id' } ] }) ``` ### Real-World Model Example From the Media plugin: ```typescript const mediaSchema = PluginHelpers.createSchema([ { name: 'filename', type: 'string', optional: false }, { name: 'originalName', type: 'string', optional: false }, { name: 'mimeType', type: 'string', optional: false }, { name: 'size', type: 'number', optional: false }, { name: 'url', type: 'string', optional: false }, { name: 'thumbnailUrl', type: 'string', optional: true }, { name: 'metadata', type: 'object', optional: true }, { name: 'uploadedBy', type: 'number', optional: true }, { name: 'tags', type: 'array', optional: true } ]) const mediaMigration = PluginHelpers.createMigration('media_files', [ { name: 'id', type: 'INTEGER', primaryKey: true }, { name: 'filename', type: 'TEXT', nullable: false }, { name: 'original_name', type: 'TEXT', nullable: false }, { name: 'mime_type', type: 'TEXT', nullable: false }, { name: 'size', type: 'INTEGER', nullable: false }, { name: 'url', type: 'TEXT', nullable: false }, { name: 'thumbnail_url', type: 'TEXT', nullable: true }, { name: 'metadata', type: 'TEXT', nullable: true }, { name: 'uploaded_by', type: 'INTEGER', nullable: true }, { name: 'tags', type: 'TEXT', nullable: true } ]) builder.addModel('MediaFile', { tableName: 'media_files', schema: mediaSchema, migrations: [mediaMigration], relationships: [ { type: 'oneToMany', target: 'User', foreignKey: 'uploaded_by' } ] }) ``` ## Admin Interface Add admin pages and menu items to the SonicJS admin interface. ### Admin Pages ```typescript // Add admin page plugin.addAdminPage( '/my-plugin', 'My Plugin', 'MyPluginView', { description: 'Manage my plugin settings and data', permissions: ['admin', 'plugin:manage'], icon: 'cog' } ) // Add sub-page plugin.addAdminPage( '/my-plugin/settings', 'Plugin Settings', 'MyPluginSettingsView', { description: 'Configure plugin settings', permissions: ['admin', 'plugin:configure'], icon: 'settings' } ) ``` ### Menu Items ```typescript // Add top-level menu item plugin.addMenuItem('My Plugin', '/admin/my-plugin', { icon: 'puzzle', order: 50, permissions: ['admin', 'plugin:manage'] }) // Add sub-menu items plugin.addMenuItem('Dashboard', '/admin/my-plugin', { icon: 'home', parent: 'My Plugin', order: 1 }) plugin.addMenuItem('Settings', '/admin/my-plugin/settings', { icon: 'cog', parent: 'My Plugin', order: 2, permissions: ['admin', 'plugin:configure'] }) ``` ### Real-World Examples From the Auth plugin: ```typescript builder.addAdminPage( '/auth/sessions', 'Active Sessions', 'AuthSessionsView', { description: 'View and manage active user sessions', permissions: ['admin', 'auth:manage'], icon: 'users' } ) builder.addMenuItem('Authentication', '/admin/auth', { icon: 'shield', order: 20, permissions: ['admin', 'auth:manage'] }) builder.addMenuItem('Sessions', '/admin/auth/sessions', { icon: 'users', parent: 'Authentication', order: 1, permissions: ['admin', 'auth:manage'] }) ``` From the Media plugin: ```typescript builder.addAdminPage( '/media', 'Media Library', 'MediaLibraryView', { description: 'Browse and manage media files', permissions: ['admin', 'media:manage'], icon: 'photo' } ) builder.addMenuItem('Media', '/admin/media', { icon: 'photo', order: 30, permissions: ['admin', 'media:manage'] }) builder.addMenuItem('Library', '/admin/media', { icon: 'photo', parent: 'Media', order: 1, permissions: ['admin', 'media:manage'] }) builder.addMenuItem('Upload', '/admin/media/upload', { icon: 'upload', parent: 'Media', order: 2, permissions: ['admin', 'media:upload'] }) ``` ## Real-World Example: Cache Plugin The Cache plugin (`/src/plugins/cache/`) is a complete, production-ready example that demonstrates all aspects of plugin development. ### Plugin Architecture ``` src/plugins/cache/ ├── index.ts # Main plugin class ├── manifest.json # Plugin manifest ├── routes.ts # Admin routes ├── services/ │ ├── cache.ts # Core cache service │ ├── cache-config.ts # Cache configuration │ ├── cache-invalidation.ts # Event-based invalidation │ ├── cache-warming.ts # Cache preloading │ └── event-bus.ts # Event system └── tests/ └── cache.test.ts # Unit tests ``` ### Main Plugin Implementation From `/src/plugins/cache/index.ts`: ```typescript export class CachePlugin { private context: PluginContext | null = null /** * Get plugin routes */ getRoutes() { return cacheRoutes } /** * Activate the cache plugin */ async activate(context: PluginContext): Promise { this.context = context const settings = context.config || {} console.log('Cache plugin activated', { memoryEnabled: settings.memoryEnabled ?? true, kvEnabled: settings.kvEnabled ?? false, defaultTTL: settings.defaultTTL ?? 3600 }) // Initialize default cache services for (const [namespace, config] of Object.entries(CACHE_CONFIGS)) { getCacheService({ ...config, memoryEnabled: settings.memoryEnabled ?? config.memoryEnabled, kvEnabled: settings.kvEnabled ?? config.kvEnabled, ttl: settings.defaultTTL ?? config.ttl }) } // Setup event-based cache invalidation setupCacheInvalidation() } /** * Deactivate the cache plugin */ async deactivate(): Promise { console.log('Cache plugin deactivated - clearing all caches') await clearAllCaches() this.context = null } /** * Configure the cache plugin */ async configure(settings: Record): Promise { console.log('Cache plugin configured', settings) // Reconfigure all cache instances with new settings for (const [namespace, config] of Object.entries(CACHE_CONFIGS)) { getCacheService({ ...config, memoryEnabled: settings.memoryEnabled ?? config.memoryEnabled, kvEnabled: settings.kvEnabled ?? config.kvEnabled, ttl: settings.defaultTTL ?? config.ttl }) } } } ``` ### Cache Service Implementation The Cache plugin implements a sophisticated three-tier caching system: ```typescript export class CacheService { private memoryCache: MemoryCache private config: CacheConfig private stats: CacheStats private kvNamespace?: KVNamespace constructor(config: CacheConfig, kvNamespace?: KVNamespace) { this.memoryCache = new MemoryCache() this.config = config this.kvNamespace = kvNamespace this.stats = { memoryHits: 0, memoryMisses: 0, kvHits: 0, kvMisses: 0, dbHits: 0, totalRequests: 0, hitRate: 0, memorySize: 0, entryCount: 0 } } /** * Get value from cache (tries memory first, then KV) */ async get(key: string): Promise { this.stats.totalRequests++ // Try memory cache first (Tier 1) if (this.config.memoryEnabled) { const memoryValue = this.memoryCache.get(key) if (memoryValue !== null) { this.stats.memoryHits++ this.updateHitRate() return memoryValue } this.stats.memoryMisses++ } // Try KV cache (Tier 2) if (this.config.kvEnabled && this.kvNamespace) { try { const kvValue = await this.kvNamespace.get(key, 'json') if (kvValue !== null) { this.stats.kvHits++ // Populate memory cache for faster subsequent access if (this.config.memoryEnabled) { this.memoryCache.set(key, kvValue as T, this.config.ttl, this.config.version) } this.updateHitRate() return kvValue as T } this.stats.kvMisses++ } catch (error) { console.error('KV cache read error:', error) this.stats.kvMisses++ } } this.updateHitRate() return null } /** * Set value in cache (stores in both memory and KV) */ async set( key: string, value: T, customConfig?: Partial ): Promise { const config = { ...this.config, ...customConfig } // Store in memory cache (Tier 1) if (config.memoryEnabled) { this.memoryCache.set(key, value, config.ttl, config.version) } // Store in KV cache (Tier 2) if (config.kvEnabled && this.kvNamespace) { try { await this.kvNamespace.put(key, JSON.stringify(value), { expirationTtl: config.ttl }) } catch (error) { console.error('KV cache write error:', error) } } } /** * Get or set pattern - fetch from cache or compute if not found */ async getOrSet( key: string, fetcher: () => Promise, customConfig?: Partial ): Promise { // Try to get from cache const cached = await this.get(key) if (cached !== null) { return cached } // Fetch from source const value = await fetcher() // Store in cache await this.set(key, value, customConfig) return value } } ``` ### Cache Configuration From `/src/plugins/cache/services/cache-config.ts`: ```typescript export interface CacheConfig { ttl: number // Time-to-live in seconds kvEnabled: boolean // Use KV cache tier memoryEnabled: boolean // Use in-memory cache tier namespace: string // Cache namespace/prefix invalidateOn: string[] // Events that invalidate this cache version?: string // Cache version for busting } /** * Default cache configurations by entity type */ export const CACHE_CONFIGS: Record = { // Content (high read, low write) content: { ttl: 3600, // 1 hour kvEnabled: true, memoryEnabled: true, namespace: 'content', invalidateOn: ['content.update', 'content.delete', 'content.publish'], version: 'v1' }, // User data (medium read, medium write) user: { ttl: 900, // 15 minutes kvEnabled: true, memoryEnabled: true, namespace: 'user', invalidateOn: ['user.update', 'user.delete', 'auth.login'], version: 'v1' }, // API responses (very high read, low write) api: { ttl: 300, // 5 minutes kvEnabled: true, memoryEnabled: true, namespace: 'api', invalidateOn: ['content.update', 'content.publish'], version: 'v1' } } /** * Generate a cache key with consistent format * Format: {namespace}:{type}:{identifier}:{version} */ export function generateCacheKey( namespace: string, type: string, identifier: string, version?: string ): string { const v = version || getCacheConfig(namespace).version || 'v1' return `${namespace}:${type}:${identifier}:${v}` } ``` ### Event-Based Cache Invalidation From `/src/plugins/cache/services/cache-invalidation.ts`: ```typescript import { onEvent, emitEvent } from './event-bus.js' import { getCacheService } from './cache.js' import { CACHE_CONFIGS, createCachePattern } from './cache-config.js' let invalidationStats = { totalInvalidations: 0, byNamespace: {} as Record, byEvent: {} as Record } const recentInvalidations: Array<{ timestamp: number namespace: string event: string pattern: string count: number }> = [] /** * Setup event-based cache invalidation */ export function setupCacheInvalidation(): void { console.log('Setting up cache invalidation listeners...') for (const [namespace, config] of Object.entries(CACHE_CONFIGS)) { const cache = getCacheService(config) // Listen to invalidation events for (const event of config.invalidateOn) { onEvent(event, async (data) => { console.log(`Cache invalidation triggered: ${event} for ${namespace}`) // Determine invalidation pattern let pattern = createCachePattern(namespace) if (data?.id) { pattern = createCachePattern(namespace, '*', data.id) } const count = await cache.invalidate(pattern) // Update stats invalidationStats.totalInvalidations += count invalidationStats.byNamespace[namespace] = (invalidationStats.byNamespace[namespace] || 0) + count invalidationStats.byEvent[event] = (invalidationStats.byEvent[event] || 0) + count // Track recent invalidations recentInvalidations.unshift({ timestamp: Date.now(), namespace, event, pattern, count }) // Keep only last 100 if (recentInvalidations.length > 100) { recentInvalidations.length = 100 } console.log(`Invalidated ${count} entries for ${namespace}`) }) } } console.log('Cache invalidation setup complete') } ``` ### Cache Routes The Cache plugin provides comprehensive admin routes for monitoring and managing the cache. See the full implementation in `/src/plugins/cache/routes.ts`. Key endpoints: - `GET /admin/cache` - Dashboard with statistics - `GET /admin/cache/stats` - Detailed statistics - `POST /admin/cache/clear` - Clear all caches - `POST /admin/cache/invalidate` - Invalidate by pattern - `GET /admin/cache/browser` - Browse cache entries - `GET /admin/cache/analytics` - Advanced analytics - `POST /admin/cache/warm` - Warm cache ### Usage in Other Plugins Other plugins can use the cache service: ```typescript import { getCacheService } from '../cache/index.js' // Get cache service for your namespace const cache = getCacheService({ namespace: 'my-plugin', ttl: 600, memoryEnabled: true, kvEnabled: false, invalidateOn: ['my-plugin:update'], version: 'v1' }) // Use cache in route handlers app.get('/data', async (c) => { const id = c.req.query('id') const cacheKey = `my-plugin:data:${id}:v1` // Try cache first const cached = await cache.get(cacheKey) if (cached) { return c.json({ data: cached, source: 'cache' }) } // Fetch from database const data = await fetchDataFromDB(id) // Store in cache await cache.set(cacheKey, data) return c.json({ data, source: 'database' }) }) // Or use getOrSet pattern app.get('/data/:id', async (c) => { const id = c.req.param('id') const cacheKey = `my-plugin:data:${id}:v1` const data = await cache.getOrSet( cacheKey, async () => { // This function only runs on cache miss return await fetchDataFromDB(id) } ) return c.json({ data }) }) ``` ## Testing Plugins ### Unit Testing Create tests in the `tests/` directory: ```typescript // tests/plugin.test.ts import { describe, it, expect, beforeEach } from 'vitest' import plugin from '../index.js' describe('My Plugin', () => { it('should have correct metadata', () => { expect(plugin.name).toBe('my-plugin') expect(plugin.version).toBe('1.0.0') }) it('should register routes', () => { expect(plugin.routes).toBeDefined() expect(plugin.routes?.length).toBeGreaterThan(0) }) it('should have lifecycle hooks', () => { expect(plugin.activate).toBeDefined() expect(plugin.deactivate).toBeDefined() }) }) ``` ### Integration Testing Test plugin integration with the plugin system: ```typescript import { describe, it, expect, beforeEach } from 'vitest' import { PluginManager } from '@/plugins/core/plugin-manager' import myPlugin from '../index.js' describe('Plugin Integration', () => { let manager: PluginManager beforeEach(() => { manager = new PluginManager() }) it('should install plugin', async () => { await manager.install(myPlugin, { enabled: true, apiKey: 'test-key' }) const status = manager.getStatus('my-plugin') expect(status.installed).toBe(true) }) it('should activate plugin', async () => { await manager.install(myPlugin, { enabled: true }) const status = manager.getStatus('my-plugin') expect(status.active).toBe(true) }) it('should handle configuration', async () => { await manager.install(myPlugin) const newConfig = { enabled: true, apiKey: 'updated-key' } await myPlugin.configure?.(newConfig) // Verify configuration was applied expect(manager.registry.getConfig('my-plugin')).toMatchObject(newConfig) }) }) ``` ### Service Testing Test your plugin services: ```typescript import { describe, it, expect } from 'vitest' import { WeatherService } from '../services/weather-service.js' describe('WeatherService', () => { const service = new WeatherService('test-api-key') it('should fetch current weather', async () => { const weather = await service.getCurrentWeather('London') expect(weather).toBeDefined() expect(weather.city).toBe('London') expect(weather.temperature).toBeGreaterThan(-50) expect(weather.temperature).toBeLessThan(60) }) it('should fetch forecast', async () => { const forecast = await service.getForecast('London', 7) expect(forecast).toHaveLength(7) expect(forecast[0]).toHaveProperty('date') expect(forecast[0]).toHaveProperty('high') expect(forecast[0]).toHaveProperty('low') }) it('should search cities', async () => { const cities = await service.searchCities('Lon') expect(cities).toContain('London') }) }) ``` ### Real-World Test Example From the Cache plugin (`/src/plugins/cache/tests/cache.test.ts`): ```typescript import { describe, it, expect, beforeEach } from 'vitest' import { CacheService } from '../services/cache.js' describe('CacheService', () => { let cache: CacheService beforeEach(() => { cache = new CacheService({ namespace: 'test', ttl: 60, memoryEnabled: true, kvEnabled: false, invalidateOn: [], version: 'v1' }) }) it('should set and get values', async () => { await cache.set('test-key', { foo: 'bar' }) const value = await cache.get('test-key') expect(value).toEqual({ foo: 'bar' }) }) it('should return null for missing keys', async () => { const value = await cache.get('missing-key') expect(value).toBeNull() }) it('should invalidate by pattern', async () => { await cache.set('user:1', { name: 'Alice' }) await cache.set('user:2', { name: 'Bob' }) await cache.set('post:1', { title: 'Hello' }) const count = await cache.invalidate('user:*') expect(count).toBe(2) expect(await cache.get('user:1')).toBeNull() expect(await cache.get('user:2')).toBeNull() expect(await cache.get('post:1')).toBeDefined() }) it('should track statistics', async () => { await cache.set('key1', 'value1') await cache.get('key1') // hit await cache.get('key2') // miss const stats = cache.getStats() expect(stats.memoryHits).toBe(1) expect(stats.memoryMisses).toBe(1) expect(stats.totalRequests).toBe(2) }) }) ``` ## Best Practices ### 1. Plugin Naming ```typescript // Good name: 'weather-forecast' name: 'user-analytics' name: 'advanced-search' // Avoid name: 'Weather' name: 'MyPlugin' name: 'plugin_name' ``` ### 2. Versioning Follow semantic versioning (semver): ```typescript // Major.Minor.Patch version: '1.0.0' // Initial release version: '1.1.0' // New feature (backward compatible) version: '1.1.1' // Bug fix version: '2.0.0' // Breaking change ``` ### 3. Configuration Provide sensible defaults: ```typescript plugin.lifecycle({ configure: async (config) => { const settings = { // Defaults enabled: true, cacheEnabled: true, cacheTTL: 3600, maxRetries: 3, timeout: 30000, // Override with user config ...config } // Validate if (settings.cacheTTL < 0) { throw new Error('cacheTTL must be positive') } // Apply applySettings(settings) } }) ``` ### 4. Error Handling Handle errors gracefully: ```typescript plugin.addRoute('/api/data', new Hono().get('/', async (c) => { try { const data = await fetchData() return c.json({ success: true, data }) } catch (error) { console.error('Failed to fetch data:', error) // Log detailed error context.logger.error('Data fetch failed', error, { path: c.req.path, timestamp: Date.now() }) // Return user-friendly error return c.json({ success: false, error: 'Failed to fetch data. Please try again later.' }, 500) } })) ``` ### 5. Security Validate and sanitize all inputs: ```typescript import { z } from 'zod' const inputSchema = z.object({ email: z.string().email(), name: z.string().min(1).max(100), age: z.number().int().min(0).max(150) }) routes.post('/users', async (c) => { try { const body = await c.req.json() const validated = inputSchema.parse(body) // Use validated data const user = await createUser(validated) return c.json({ success: true, data: user }) } catch (error) { if (error instanceof z.ZodError) { return c.json({ success: false, error: 'Invalid input', details: error.errors }, 400) } throw error } }) ``` ### 6. Logging Use structured logging: ```typescript // Good context.logger.info('User created', { userId: user.id, email: user.email, timestamp: Date.now() }) context.logger.error('Database error', error, { query: 'SELECT * FROM users', timestamp: Date.now() }) // Avoid console.log('User created') console.log(error) ``` ### 7. Dependencies Minimize and document dependencies: ```typescript plugin.metadata({ dependencies: ['cache', 'auth'], compatibility: '^0.1.0' }) // Document why each dependency is needed /** * Dependencies: * - cache: Used for caching API responses * - auth: Required for user authentication */ ``` ### 8. Documentation Document your plugin thoroughly: ```typescript /** * Weather Plugin * * Provides weather information and forecasts. * * Features: * - Current weather by city * - 7-day forecast * - City search * - Automatic caching * * Configuration: * - apiKey: Weather API key (required) * - defaultCity: Default city for queries * - cacheEnabled: Enable caching (default: true) * - cacheTTL: Cache duration in seconds (default: 300) * * Usage: * ```typescript * const weather = await weatherService.getCurrentWeather('London') * ``` */ ``` ### 9. Performance Optimize for performance: ```typescript // Use caching const cache = getCacheService({ namespace: 'my-plugin', ttl: 300 }) const data = await cache.getOrSet('expensive-query', async () => { return await expensiveOperation() }) // Batch operations const users = await Promise.all( userIds.map(id => fetchUser(id)) ) // Pagination const limit = Math.min(parseInt(c.req.query('limit') || '20'), 100) const offset = parseInt(c.req.query('offset') || '0') ``` ### 10. Testing Write comprehensive tests: ```typescript describe('My Plugin', () => { // Test metadata it('should have valid metadata', () => { expect(plugin.name).toBeTruthy() expect(plugin.version).toMatch(/^\d+\.\d+\.\d+$/) }) // Test lifecycle it('should activate successfully', async () => { await plugin.activate?.(mockContext) expect(plugin).toBeDefined() }) // Test functionality it('should process data correctly', async () => { const result = await service.processData(input) expect(result).toMatchSnapshot() }) // Test error handling it('should handle errors gracefully', async () => { await expect(service.processData(invalidInput)) .rejects.toThrow('Invalid input') }) }) ``` ## Advanced Topics ### Custom Hook Names Create plugin-specific hooks: ```typescript // Register custom hook plugin.addHook('my-plugin:data-processed', async (data, context) => { console.log('Data processed:', data) return data }, { priority: 10, description: 'Custom plugin hook' }) // Trigger from plugin code const result = await context.hooks.execute('my-plugin:data-processed', data) ``` ### Plugin Communication Plugins can communicate through hooks: ```typescript // Plugin A - Register hook pluginA.addHook('plugin-a:user-created', async (user) => { console.log('User created in Plugin A:', user) return user }) // Plugin B - Listen to Plugin A's hook pluginB.addHook('plugin-a:user-created', async (user, context) => { console.log('Plugin B notified of new user:', user) // Plugin B can react to Plugin A's event await pluginB.service.handleNewUser(user) return user }) ``` ### Resource Management Properly manage resources: ```typescript plugin.lifecycle({ activate: async (context) => { // Initialize resources const connection = await createDatabaseConnection() const interval = setInterval(() => { // Background task }, 60000) // Store for cleanup context.resources = { connection, interval } }, deactivate: async (context) => { // Clean up resources if (context.resources?.connection) { await context.resources.connection.close() } if (context.resources?.interval) { clearInterval(context.resources.interval) } } }) ``` ### Lazy Loading Load heavy dependencies only when needed: ```typescript let heavyLibrary: any = null async function getHeavyLibrary() { if (!heavyLibrary) { heavyLibrary = await import('heavy-library') } return heavyLibrary } routes.post('/process', async (c) => { const lib = await getHeavyLibrary() const result = lib.process(data) return c.json({ result }) }) ``` ### Plugin Hooks for Inter-Plugin Dependencies ```typescript // Plugin that provides a service const authPlugin = PluginBuilder.create({ name: 'auth', version: '1.0.0' }) authPlugin.addService('authService', authService, { singleton: true }) // Plugin that depends on auth const securePlugin = PluginBuilder.create({ name: 'secure-plugin', version: '1.0.0' }) securePlugin.metadata({ dependencies: ['auth'] }) securePlugin.lifecycle({ activate: async (context) => { // Access auth service from dependency const authService = context.services.authService if (!authService) { throw new Error('Auth service not available') } // Use auth service const isValid = await authService.validateToken(token) } }) ``` ### Dynamic Configuration Update configuration at runtime: ```typescript plugin.lifecycle({ configure: async (config) => { // Dynamic configuration if (config.mode === 'production') { cache.ttl = 3600 logger.level = 'error' } else { cache.ttl = 60 logger.level = 'debug' } // Hot reload if (config.hotReload) { setupHotReload() } } }) ``` ## Support and Resources - [SonicJS Documentation](https://docs.sonicjs.com) - [Plugin API Reference](https://docs.sonicjs.com/plugins/api) - [GitHub Repository](https://github.com/lane711/sonicjs-ai) - [Community Discord](https://discord.gg/sonicjs) - [GitHub Issues](https://github.com/lane711/sonicjs-ai/issues) ## Conclusion This guide has covered: 1. Plugin system architecture and core components 2. Creating custom plugins from scratch 3. Plugin manifest structure and configuration 4. Complete plugin lifecycle management 5. Hook system for event-driven programming 6. Route, middleware, and service registration 7. Database models and migrations 8. Admin interface integration 9. Real-world example: Complete Cache plugin 10. Testing strategies and best practices 11. Advanced topics and optimization techniques The Cache plugin serves as a comprehensive reference implementation demonstrating production-ready plugin development. Study its source code for additional insights into advanced patterns and techniques.