SoulCache

Plugins

Learn about SoulCache's plugin system for extensibility

Plugins

The Plugin System allows you to extend SoulCache with custom behavior.

Usage

SoulCache provides a plugin infrastructure for custom extensions. Plugins are registered through the plugin manager at initialization time.

// Plugin types are internal to @soulcache/core
// Import from the plugin subpath when it becomes public
import type { Plugin, PluginContext } from '@soulcache/core/plugin';
 
const myPlugin: Plugin = {
  metadata: {
    id: 'logging',
    name: 'Logging Plugin',
    version: '1.0.0',
  },
  onAfterInit: (ctx: PluginContext) => {
    ctx.log('info', 'Plugin initialized');
  },
  onBeforeQuery: (queryKey: unknown[], ctx: PluginContext) => {
    ctx.log('info', `Query starting: ${queryKey.join('/')}`);
  },
  onAfterQuery: (queryKey: unknown[], ctx: PluginContext) => {
    ctx.log('info', `Query completed: ${queryKey.join('/')}`);
  },
};

Lifecycle

Plugins go through a well-defined lifecycle:

StateDescription
discoveredPlugin found
validatedMetadata valid
registeredAdded to manager
initializedonBeforeInit/onAfterInit called
activeHooks running
suspendedTemporarily disabled
resumingBeing resumed from suspension
stoppingDisposal in progress
disposedCleaned up
removedUnregistered from manager
errorInitialization failed

Hooks

HookWhen
onBeforeInitBefore initialization
onAfterInitAfter initialization
onBeforeQueryBefore query execution
onAfterQueryAfter query completion
onBeforeMutationBefore mutation
onAfterMutationAfter mutation
onCacheUpdatedCache entry updated
onCacheInvalidatedCache entry invalidated
onShutdownRuntime shutdown
onSuspendPlugin suspended
onResumePlugin resumed
onDisposePlugin disposed

Features

Dependency Resolution

Automatic dependency resolution ensures correct load order

Error Isolation

Each hook is isolated so errors don't cascade

State Machine

Well-defined lifecycle states for predictable behavior

Dependency Checking

Automatic verification of plugin dependencies

Best Practices

Plugin Guidelines

  • Keep plugins small — Single responsibility principle
  • Handle errors — Hooks are isolated but should be robust
  • Declare dependencies — Ensure correct load order
  • Clean up — Use onDispose for resource cleanup

On this page