@kysera/executor

Unified Execution Layer for Kysera - Plugin-aware Kysely wrapper that enables plugins to work seamlessly with both Repository and DAL patterns.

Installation

npm install @kysera/executor kysely

Overview

Dependencies: None (peer: kysely >=0.28.8)

@kysera/executor provides a unified plugin system that works seamlessly with both Repository and DAL patterns. It wraps Kysely instances with plugin interception capabilities while maintaining full type safety and zero overhead when plugins aren't active.

Key Features

Unified Plugin System - Single plugin architecture for both Repository and DAL
Zero Overhead - No performance penalty when no interceptor plugins are registered
Type Safe - Full TypeScript support with Kysely types preserved
Transaction Support - Plugins automatically propagate through transactions
Plugin Validation - Detects conflicts, missing dependencies, and circular dependencies
Cross-Runtime - Works with Node.js, Bun, and Deno

Quick Start

import { createExecutor } from '@kysera/executor'
import { softDeletePlugin } from '@kysera/soft-delete'

const executor = await createExecutor(db, [softDeletePlugin()])

// All queries now have soft-delete filter applied automatically
const users = await executor.selectFrom('users').selectAll().execute()

Intercepted Methods:

The executor intercepts these Kysely methods to apply plugins:

selectFrom(table) - SELECT queries
insertInto(table) - INSERT queries
updateTable(table) - UPDATE queries
deleteFrom(table) - DELETE queries

All other Kysely methods pass through unchanged.

Core Functions

createExecutor

Creates a plugin-aware executor with async plugin initialization.

async function createExecutor<DB>(
  db: Kysely<DB>,
  plugins?: readonly Plugin[],
  config?: ExecutorConfig
): Promise<KyseraExecutor<DB>>

Parameters:

db - Kysely database instance
plugins - Array of plugins to apply (default: [])
config.enabled - Enable/disable plugin interception at runtime (default: true)

Returns: KyseraExecutor<DB> - Plugin-aware Kysely wrapper

Example:

import { createExecutor } from '@kysera/executor'
import { softDeletePlugin } from '@kysera/soft-delete'
import { rlsPlugin } from '@kysera/rls'

// With multiple plugins
const executor = await createExecutor(db, [softDeletePlugin(), rlsPlugin({ schema: rlsSchema })])

// With config
const executor = await createExecutor(db, plugins, {
  enabled: process.env.NODE_ENV === 'production'
})

// Use like normal Kysely instance
const users = await executor.selectFrom('users').selectAll().execute()

Plugin Initialization:

Plugins are:

Validated for conflicts and dependencies
Sorted by priority and dependencies (topological sort)
Initialized via onInit lifecycle hook (async)
Cached for efficient interception

Performance:

No plugins: Returns augmented Kysely instance (zero overhead)
No interceptors: Returns augmented Kysely instance (minimal overhead)
With interceptors: Uses optimized Proxy with method caching

destroyExecutor

Destroy an executor and call cleanup hooks for all plugins.

async function destroyExecutor<DB>(executor: KyseraExecutor<DB>): Promise<void>

Parameters:

executor - KyseraExecutor instance to destroy

Returns: Promise<void> - Resolves when all plugin onDestroy hooks have completed

Example:

import { createExecutor, destroyExecutor } from '@kysera/executor'

const executor = await createExecutor(db, [myPlugin()])

// Use executor...
const users = await executor.selectFrom('users').selectAll().execute()

// Clean up when done (e.g., during application shutdown)
await destroyExecutor(executor)

Use Cases:

Application shutdown - clean up plugin resources (connections, timers, etc.)
Testing - ensure clean state between tests
Hot reloading - destroy old executor before creating new one
Resource management - explicitly release plugin resources

Behavior:

Calls onDestroy() hook for each plugin in reverse order (dependencies last)
Ignores plugins without onDestroy hook
Errors in cleanup hooks are logged but don't throw (best-effort cleanup)
Safe to call multiple times (no-op after first call)

createExecutorSync

Synchronous version of createExecutor that skips async plugin initialization.

function createExecutorSync<DB>(
  db: Kysely<DB>,
  plugins?: readonly Plugin[],
  config?: ExecutorConfig
): KyseraExecutor<DB>

Parameters:

db - Kysely database instance
plugins - Array of plugins to apply (default: [])
config.enabled - Enable/disable plugin interception (default: true)

Returns: KyseraExecutor<DB> - Plugin-aware Kysely wrapper

Example:

import { createExecutorSync } from '@kysera/executor'

// Synchronous creation (no onInit hooks called)
const executor = createExecutorSync(db, [softDeletePlugin()])

// Use immediately
const users = await executor.selectFrom('users').selectAll().execute()

Use Cases:

Plugins without onInit hooks
Performance-critical initialization paths
Testing scenarios where initialization isn't needed

Limitations:

Does not call plugin.onInit() hooks
Plugins requiring async initialization will not work correctly

isKyseraExecutor

Type guard to check if a value is a KyseraExecutor.

function isKyseraExecutor<DB>(value: Kysely<DB> | KyseraExecutor<DB>): value is KyseraExecutor<DB>

Parameters:

value - Kysely or KyseraExecutor instance to check

Returns: true if value is a KyseraExecutor, false otherwise

Example:

import { isKyseraExecutor, createExecutor } from '@kysera/executor'

function processDb(db: Kysely<DB> | KyseraExecutor<DB>) {
  if (isKyseraExecutor(db)) {
    const plugins = db.__plugins
    console.log(`Using ${plugins.length} plugins`)
  } else {
    console.log('Plain Kysely instance')
  }
}

const executor = await createExecutor(db, [softDeletePlugin()])
processDb(executor) // "Using 1 plugins"
processDb(db) // "Plain Kysely instance"

getPlugins

Get the list of plugins from a KyseraExecutor.

function getPlugins<DB>(executor: KyseraExecutor<DB>): readonly Plugin[]

Parameters:

executor - KyseraExecutor instance

Returns: Array of plugins in execution order

Example:

import { getPlugins } from '@kysera/executor'

const executor = await createExecutor(db, [softDeletePlugin(), rlsPlugin({ schema })])

const plugins = getPlugins(executor)
console.log(plugins.map(p => p.name))
// ['@kysera/rls', '@kysera/soft-delete']
// (ordered by priority and dependencies)

getRawDb

Get the raw Kysely instance from an executor, bypassing plugin interceptors.

function getRawDb<DB>(executor: Kysely<DB>): Kysely<DB>

Parameters:

executor - Kysely or KyseraExecutor instance

Returns: Raw Kysely instance without plugin interception

Example:

import { getRawDb } from '@kysera/executor'

const executor = await createExecutor(db, [softDeletePlugin()])

// This query has soft-delete filter applied
const users = await executor.selectFrom('users').selectAll().execute()

// This query BYPASSES soft-delete filter
const rawDb = getRawDb(executor)
const allUsers = await rawDb.selectFrom('users').selectAll().execute()

Use Cases:

Plugin internal queries that shouldn't trigger interceptors
Avoiding double-filtering (e.g., soft-delete plugin checking its own records)
Admin operations that need full database access
Performance-critical queries where plugin overhead must be avoided

Safety:

Use with caution - bypassing plugins can expose deleted records, violate RLS policies, etc.

wrapTransaction

Wrap a transaction with plugins from an executor.

function wrapTransaction<DB>(
  trx: Transaction<DB>,
  plugins: readonly Plugin[]
): KyseraTransaction<DB>

Parameters:

trx - Kysely transaction instance
plugins - Array of plugins to apply

Returns: KyseraTransaction<DB> - Plugin-aware transaction

Example:

import { wrapTransaction, getPlugins } from '@kysera/executor'

const executor = await createExecutor(db, [softDeletePlugin()])

await db.transaction().execute(async trx => {
  // Wrap transaction with same plugins as executor
  const wrappedTrx = wrapTransaction(trx, getPlugins(executor))

  // Plugins applied within transaction
  const users = await wrappedTrx.selectFrom('users').selectAll().execute()
})

Note: Usually not needed - executor.transaction() automatically wraps transactions.

applyPlugins

Manually apply plugins to a query builder.

function applyPlugins<QB>(qb: QB, plugins: readonly Plugin[], context: QueryBuilderContext): QB

Parameters:

qb - Query builder instance
plugins - Array of plugins to apply
context - Query context (operation, table, metadata)

Returns: Modified query builder

Example:

import { applyPlugins, getPlugins } from '@kysera/executor'

const executor = await createExecutor(db, [softDeletePlugin()])

// Manual plugin application for complex queries
let query = db.selectFrom('users').selectAll()

query = applyPlugins(query, getPlugins(executor), {
  operation: 'select',
  table: 'users',
  metadata: {}
})

const users = await query.execute()

Use Cases:

Dynamic query building where automatic interception doesn't work
Custom query builder patterns
Testing plugin behavior in isolation

validatePlugins

Validate plugins for conflicts, dependencies, and circular dependencies.

function validatePlugins(plugins: readonly Plugin[]): void

Parameters:

plugins - Array of plugins to validate

Throws: PluginValidationError if validation fails

Example:

import { validatePlugins, PluginValidationError } from '@kysera/executor'

try {
  validatePlugins([
    { name: 'plugin-a', version: '1.0.0', dependencies: ['plugin-b'] },
    { name: 'plugin-b', version: '1.0.0', dependencies: ['plugin-a'] }
  ])
} catch (error) {
  if (error instanceof PluginValidationError) {
    console.log(error.type) // 'CIRCULAR_DEPENDENCY'
    console.log(error.details) // { pluginName: 'plugin-a', cycle: [...] }
  }
}

Validation Checks:

Duplicate Names - Each plugin must have a unique name
Missing Dependencies - All dependencies must be registered
Conflicts - Conflicting plugins cannot be loaded together
Circular Dependencies - Dependency graph must be acyclic

Error Types:

type PluginValidationErrorType =
  | 'DUPLICATE_NAME'
  | 'MISSING_DEPENDENCY'
  | 'CONFLICT'
  | 'CIRCULAR_DEPENDENCY'

resolvePluginOrder

Resolve plugin execution order using topological sort with priority.

function resolvePluginOrder(plugins: readonly Plugin[]): Plugin[]

Parameters:

plugins - Array of plugins to sort

Returns: Sorted array of plugins in execution order

Example:

import { resolvePluginOrder } from '@kysera/executor'

const sorted = resolvePluginOrder([
  { name: 'audit', version: '1.0.0', priority: 0 },
  { name: 'rls', version: '1.0.0', priority: 50 },
  { name: 'soft-delete', version: '1.0.0', priority: 0 }
])

console.log(sorted.map(p => p.name))
// ['rls', 'audit', 'soft-delete']
// (rls first due to priority 50, then alphabetical)

Ordering Algorithm:

Topological Sort - Plugins with dependencies run after their dependencies
Priority - Within same level, higher priority runs first (default: 0)
Tie-Breaking - Alphabetical by name for stability

Priority Guidelines:

50: Security plugins (RLS) - must filter before other plugins see data
10: Validation plugins - validate early
0: Standard plugins (default)
-10: Logging/audit plugins - capture final state

Types

Plugin

Plugin interface for extending Kysera functionality.

interface Plugin {
  /** Unique plugin name */
  readonly name: string
  /** Plugin version */
  readonly version: string
  /** Plugin dependencies (must be loaded first) */
  readonly dependencies?: readonly string[]
  /** Higher priority = runs first (default: 0) */
  readonly priority?: number
  /** Plugins that conflict with this one */
  readonly conflictsWith?: readonly string[]

  /** Lifecycle: Called once when plugin is initialized */
  onInit?<DB>(db: Kysely<DB>): Promise<void> | void

  /** Lifecycle: Called when plugin is destroyed (cleanup) */
  onDestroy?(): Promise<void> | void

  /** Query interception: Modify query builder before execution */
  interceptQuery?<QB>(qb: QB, context: QueryBuilderContext): QB

  /** Repository extensions: Add methods to repositories (Repository pattern only) */
  extendRepository?<T extends object>(repo: T): T
}

Plugin Hooks:

Hook	When Called	Use Case
`onInit`	Once during `createExecutor`	Setup, validation, schema checks
`onDestroy`	During cleanup (manual or shutdown)	Close connections, release resources
`interceptQuery`	Before query execution	Add WHERE clauses, modify queries
`extendRepository`	Repository creation (Repository pattern only)	Add custom methods

Example:

import type { Plugin } from '@kysera/executor'

const loggingPlugin: Plugin = {
  name: '@myapp/logging',
  version: '1.0.0',
  priority: -10, // Run after other plugins

  onInit: async db => {
    console.log('Plugin initialized')
  },

  interceptQuery: (qb, context) => {
    console.log(`Query: ${context.operation} on ${context.table}`)
    return qb
  }
}

QueryBuilderContext

Context passed to interceptQuery hooks.

interface QueryBuilderContext {
  /** Type of operation */
  readonly operation: 'select' | 'insert' | 'update' | 'delete' | 'replace' | 'merge'
  /** Table name */
  readonly table: string
  /** Additional metadata (shared across plugin chain) */
  readonly metadata: Record<string, unknown>
}

Example:

interceptQuery: (qb, context) => {
  // Check operation type
  if (context.operation === 'select') {
    return qb.where(`${context.table}.deleted_at`, 'is', null)
  }

  // Share data between plugins via metadata
  context.metadata['processed_by_my_plugin'] = true

  return qb
}

Metadata Usage:

Plugins can use context.metadata to communicate:

// Plugin A sets metadata
const pluginA: Plugin = {
  name: 'plugin-a',
  interceptQuery: (qb, context) => {
    context.metadata['skip_plugin_b'] = true
    return qb
  }
}

// Plugin B reads metadata
const pluginB: Plugin = {
  name: 'plugin-b',
  dependencies: ['plugin-a'],
  interceptQuery: (qb, context) => {
    if (context.metadata['skip_plugin_b']) {
      return qb // Skip processing
    }
    return qb.where('active', '=', true)
  }
}

KyseraExecutor

Plugin-aware Kysely wrapper type.

type KyseraExecutor<DB> = Kysely<DB> & KyseraExecutorMarker<DB>

interface KyseraExecutorMarker<DB = unknown> {
  readonly __kysera: true
  readonly __plugins: readonly Plugin[]
  readonly __rawDb: Kysely<DB>
}

Properties:

__kysera - Type marker (always true)
__plugins - Registered plugins in execution order
__rawDb - Raw Kysely instance bypassing interceptors

Example:

const executor = await createExecutor(db, [softDeletePlugin()])

// Access marker properties
console.log(executor.__kysera) // true
console.log(executor.__plugins.length) // 1
console.log(executor.__rawDb === db) // true

// Use as normal Kysely instance
const users = await executor.selectFrom('users').selectAll().execute()

KyseraTransaction

Plugin-aware Transaction wrapper type.

type KyseraTransaction<DB> = Transaction<DB> & KyseraExecutorMarker<DB>

Transactions created from KyseraExecutor automatically inherit plugins:

const executor = await createExecutor(db, [softDeletePlugin()])

await executor.transaction().execute(async trx => {
  // trx is KyseraTransaction<DB> with plugins
  console.log(trx.__kysera) // true
  console.log(trx.__plugins.length) // 1

  // Queries inside transaction have plugins applied
  const users = await trx.selectFrom('users').selectAll().execute()
})

ExecutorConfig

Configuration for executor creation.

interface ExecutorConfig {
  /** Enable/disable plugin interception at runtime */
  readonly enabled?: boolean
}

Example:

// Disable plugins in development
const executor = await createExecutor(db, plugins, {
  enabled: process.env.NODE_ENV === 'production'
})

// Conditionally enable plugins
const executor = await createExecutor(db, plugins, {
  enabled: featureFlags.pluginsEnabled
})

PluginValidationError

Error thrown when plugin validation fails.

class PluginValidationError extends Error {
  constructor(
    message: string,
    public readonly type: PluginValidationErrorType,
    public readonly details: PluginValidationDetails
  );
}

type PluginValidationErrorType =
  | 'DUPLICATE_NAME'
  | 'MISSING_DEPENDENCY'
  | 'CONFLICT'
  | 'CIRCULAR_DEPENDENCY';

interface PluginValidationDetails {
  readonly pluginName: string;
  readonly missingDependency?: string;
  readonly conflictingPlugin?: string;
  readonly cycle?: readonly string[];
}

Example:

import { validatePlugins, PluginValidationError } from '@kysera/executor'

try {
  validatePlugins(plugins)
} catch (error) {
  if (error instanceof PluginValidationError) {
    switch (error.type) {
      case 'DUPLICATE_NAME':
        console.error(`Duplicate plugin: ${error.details.pluginName}`)
        break
      case 'MISSING_DEPENDENCY':
        console.error(
          `Plugin "${error.details.pluginName}" requires "${error.details.missingDependency}"`
        )
        break
      case 'CONFLICT':
        console.error(
          `Plugin "${error.details.pluginName}" conflicts with "${error.details.conflictingPlugin}"`
        )
        break
      case 'CIRCULAR_DEPENDENCY':
        console.error(`Circular dependency: ${error.details.cycle?.join(' -> ')}`)
        break
    }
  }
}

Intercepted Methods

The executor only intercepts these four Kysely methods to apply plugins:

const INTERCEPTED_METHODS = {
  selectFrom: 'select',
  insertInto: 'insert',
  updateTable: 'update',
  deleteFrom: 'delete'
} as const

Method Interception:

Kysely Method	Operation Type	Plugins Applied
`selectFrom(table)`	`'select'`	✅ Yes
`insertInto(table)`	`'insert'`	✅ Yes
`updateTable(table)`	`'update'`	✅ Yes
`deleteFrom(table)`	`'delete'`	✅ Yes
All other methods	N/A	❌ Pass-through

What this means:

Only table-starting methods trigger plugin interception
Builder methods (.where(), .select(), .join(), etc.) pass through unchanged
Execution methods (.execute(), .executeTakeFirst()) pass through unchanged
Schema methods (.schema, .introspection) pass through unchanged

Example:

const executor = await createExecutor(db, [softDeletePlugin()])

// ✅ Plugin intercepted (selectFrom triggers interception)
const users = await executor.selectFrom('users').selectAll().execute()
// WHERE deleted_at IS NULL is added

// ❌ Plugin NOT intercepted (starting with .with, not selectFrom)
const result = await executor
  .with('active_users', qb => qb.selectFrom('users').selectAll())
  .selectFrom('active_users')
  .selectAll()
  .execute()
// No deleted_at filter added (limitation - see below)

Limitations

While the executor provides powerful plugin capabilities, there are some limitations to be aware of:

1. SQL Template Strings (`sql`...`)

Raw SQL template strings bypass plugin interception entirely:

const executor = await createExecutor(db, [softDeletePlugin()])

// ❌ NO plugin filtering - raw SQL bypasses interception
const users = await sql<User[]>`SELECT * FROM users`.execute(executor)
// Returns ALL users including deleted ones

// ✅ Use query builder instead
const users = await executor.selectFrom('users').selectAll().execute()
// Soft-delete filter applied correctly

Workaround: Use Kysely's query builder methods instead of raw SQL when plugins are needed.

2. CTEs (Common Table Expressions)

Queries starting with .with() are not intercepted:

const executor = await createExecutor(db, [softDeletePlugin()])

// ❌ NO plugin filtering on CTE definition
const result = await executor
  .with('active_users', qb =>
    qb.selectFrom('users').selectAll() // No soft-delete filter here!
  )
  .selectFrom('active_users')
  .selectAll()
  .execute()

// ✅ Workaround: Apply plugins manually in CTE
const result = await executor
  .with('active_users', qb =>
    qb
      .selectFrom('users')
      .selectAll()
      .where('deleted_at', 'is', null) // Manual filter
  )
  .selectFrom('active_users')
  .selectAll()
  .execute()

Workaround: Manually apply filters in CTE definitions or use applyPlugins() helper.

3. Dynamic Query Building

Queries built outside the executor context don't get plugin interception:

const executor = await createExecutor(db, [softDeletePlugin()])

// ❌ Building query before passing to executor
const baseQuery = db.selectFrom('users').selectAll()
const users = await baseQuery.execute() // No plugins applied

// ✅ Build query through executor
const users = await executor.selectFrom('users').selectAll().execute()

Workaround: Always start queries from the executor, not the raw database instance.

4. Subqueries

Subqueries created with .selectFrom() inside expressions don't trigger interception:

const executor = await createExecutor(db, [softDeletePlugin()])

// ⚠️ Outer query gets filtering, subquery doesn't
const posts = await executor
  .selectFrom('posts')
  .select([
    'posts.id',
    'posts.title',
    eb =>
      eb
        .selectFrom('users') // Subquery - no soft-delete filter!
        .select('name')
        .whereRef('users.id', '=', 'posts.user_id')
        .as('author_name')
  ])
  .execute()

// ✅ Workaround: Use joins or apply filters manually
const posts = await executor
  .selectFrom('posts')
  .innerJoin('users', 'users.id', 'posts.user_id')
  .where('users.deleted_at', 'is', null) // Manual filter for join
  .select(['posts.id', 'posts.title', 'users.name as author_name'])
  .execute()

Workaround: Use joins instead of subqueries, or manually apply plugin filters.

5. Schema Introspection

Kysely's schema introspection methods bypass plugins:

const executor = await createExecutor(db, [rlsPlugin({ schema: rlsSchema })])

// ❌ NO RLS filtering on introspection
const tables = await executor.introspection.getTables()
// Returns all tables regardless of RLS context

Note: This is expected behavior - introspection is metadata only and should not be filtered.

Usage Patterns

With Repository Pattern

import { createExecutor } from '@kysera/executor'
import { createORM } from '@kysera/repository'
import { softDeletePlugin } from '@kysera/soft-delete'

// Create executor with plugins
const executor = await createExecutor(db, [softDeletePlugin()])

// Create repository manager using executor (no additional plugins needed)
const orm = await createORM(executor, [])

const userRepo = orm.createRepository(exec => {
  const factory = createRepositoryFactory(exec)
  return factory.create({
    tableName: 'users',
    mapRow: row => row,
    schemas: { create: CreateUserSchema }
  })
})

// Repository has plugin methods
await userRepo.softDelete(userId)

With DAL Pattern

import { createExecutor } from '@kysera/executor'
import { createQuery, withTransaction } from '@kysera/dal'

// Create executor with plugins
const executor = await createExecutor(db, [softDeletePlugin(), rlsPlugin({ schema: rlsSchema })])

// Create DAL queries
const getUsers = createQuery(ctx => ctx.db.selectFrom('users').selectAll().execute())

const createUser = createQuery((ctx, data: CreateUserInput) =>
  ctx.db.insertInto('users').values(data).returningAll().executeTakeFirstOrThrow()
)

// Plugins applied automatically
const users = await getUsers(executor)

// Plugins work in transactions
await withTransaction(executor, async ctx => {
  const user = await createUser(ctx, userData)
  return user
})

Transaction Propagation

Plugins automatically propagate through transactions:

const executor = await createExecutor(db, [softDeletePlugin(), rlsPlugin({ schema: rlsSchema })])

await executor.transaction().execute(async trx => {
  // trx inherits all plugins from executor
  const users = await trx.selectFrom('users').selectAll().execute()
  // ✅ Soft-delete filter applied
  // ✅ RLS filter applied

  await trx.insertInto('posts').values({ title: 'Post', user_id: 1 }).execute()
  // ✅ RLS context applied
})

Bypassing Plugins

Use getRawDb to bypass plugin interceptors:

const executor = await createExecutor(db, [softDeletePlugin()])

// With plugins
const activeUsers = await executor.selectFrom('users').selectAll().execute()
// Returns only non-deleted users

// Without plugins
const rawDb = getRawDb(executor)
const allUsers = await rawDb.selectFrom('users').selectAll().execute()
// Returns ALL users including deleted

Custom Plugin Example

import type { Plugin, QueryBuilderContext } from '@kysera/executor'

const tenantPlugin = (tenantId: string): Plugin => ({
  name: '@myapp/tenant-filter',
  version: '1.0.0',
  priority: 50, // High priority - run before other plugins

  interceptQuery: (qb, context) => {
    // Only apply to SELECT queries
    if (context.operation === 'select') {
      return qb.where('tenant_id', '=', tenantId)
    }
    return qb
  },

  extendRepository: (repo: any) => ({
    ...repo,
    // Add method to query across all tenants
    findAllTenants: async () => {
      const rawDb = getRawDb(repo.executor)
      return await rawDb.selectFrom(repo.tableName).selectAll().execute()
    }
  })
})

// Usage
const executor = await createExecutor(db, [tenantPlugin('tenant-123')])
const users = await executor.selectFrom('users').selectAll().execute()
// Automatically filtered by tenant_id = 'tenant-123'

Architecture

How It Works

The executor uses different strategies based on plugin configuration:

1. Zero Overhead Path (no plugins or disabled):

// Returns augmented Kysely with marker properties only
return Object.assign(db, {
  __kysera: true,
  __plugins: [],
  __rawDb: db
})

2. Minimal Overhead Path (no interceptors):

// Plugins have no interceptQuery hooks
// Returns augmented Kysely without Proxy
return Object.assign(db, {
  __kysera: true,
  __plugins: sortedPlugins,
  __rawDb: db
})

3. Proxy Path (with interceptors):

// Creates Proxy to intercept method calls
return new Proxy(db, {
  get(target, prop) {
    if (prop === 'selectFrom') {
      return table => {
        let qb = target.selectFrom(table)
        const context = { operation: 'select', table, metadata: {} }
        for (const plugin of interceptors) {
          qb = plugin.interceptQuery(qb, context)
        }
        return qb
      }
    }
    // ... similar for insertInto, updateTable, deleteFrom
  }
})

Intercepted Methods

Only these four methods trigger plugin interception:

Method	Operation	Context
`selectFrom(table)`	`'select'`	Query builder for SELECT
`insertInto(table)`	`'insert'`	Query builder for INSERT
`updateTable(table)`	`'update'`	Query builder for UPDATE
`deleteFrom(table)`	`'delete'`	Query builder for DELETE

All other Kysely methods (.where(), .select(), .execute(), etc.) pass through without interception.

Plugin Lifecycle

Validation - validatePlugins() checks for conflicts, dependencies, circular dependencies
Ordering - resolvePluginOrder() performs topological sort with priority
Initialization - Each plugin's onInit() called in order (async)
Filtering - Only plugins with interceptQuery are cached as interceptors
Execution - Interceptors applied on each intercepted method call

Transaction Handling

Transactions inherit plugins automatically:

executor.transaction().execute(async trx => {
  // trx is wrapped with same plugins as executor
  // Uses createProxy() with same interceptor array
})

Manual wrapping is also supported via wrapTransaction(trx, plugins).

Performance

Zero Overhead Fast Paths

The executor uses multiple optimization strategies:

No plugins: Returns augmented Kysely instance (zero overhead)
No interceptors: Returns augmented Kysely instance (minimal overhead)
With interceptors: Uses optimized Proxy with:
- Method caching (avoid repeated .bind() calls)
- Set-based lookups (O(1) instead of O(n))
- Cached intercepted methods
- Cached transaction wrapper

Benchmarks

// Plain Kysely
const db = new Kysely({ ... });
const users = await db.selectFrom('users').selectAll().execute();
// Baseline: 1.0x

// Executor with no plugins
const executor = await createExecutor(db, []);
const users = await executor.selectFrom('users').selectAll().execute();
// ~1.0x (negligible overhead)

// Executor with non-interceptor plugins
const executor = await createExecutor(db, [auditPlugin()]);
const users = await executor.selectFrom('users').selectAll().execute();
// ~1.0x (no interception, minimal overhead)

// Executor with interceptor plugins
const executor = await createExecutor(db, [softDeletePlugin()]);
const users = await executor.selectFrom('users').selectAll().execute();
// ~1.1x (Proxy overhead + plugin execution)

Installation​

Overview​

Key Features​

Quick Start​

Core Functions​

createExecutor​

destroyExecutor​

createExecutorSync​

isKyseraExecutor​

getPlugins​

getRawDb​

wrapTransaction​

applyPlugins​

validatePlugins​

resolvePluginOrder​

Types​

Plugin​

QueryBuilderContext​

KyseraExecutor​

KyseraTransaction​

ExecutorConfig​

PluginValidationError​

Intercepted Methods​

Limitations​

1. SQL Template Strings (sql...`)​

2. CTEs (Common Table Expressions)​

3. Dynamic Query Building​

4. Subqueries​

5. Schema Introspection​

Usage Patterns​

With Repository Pattern​

With DAL Pattern​

Transaction Propagation​

Bypassing Plugins​

Custom Plugin Example​

Architecture​

How It Works​

Intercepted Methods​

Plugin Lifecycle​

Transaction Handling​

Performance​

Zero Overhead Fast Paths​

Benchmarks​

See Also​

Installation

Overview

Key Features

Quick Start

Core Functions

createExecutor

destroyExecutor

createExecutorSync

isKyseraExecutor

getPlugins

getRawDb

wrapTransaction

applyPlugins

validatePlugins

resolvePluginOrder

Types

Plugin

QueryBuilderContext

KyseraExecutor

KyseraTransaction

ExecutorConfig

PluginValidationError

Intercepted Methods

Limitations

1. SQL Template Strings (`sql`...`)

2. CTEs (Common Table Expressions)

3. Dynamic Query Building

4. Subqueries

5. Schema Introspection

Usage Patterns

With Repository Pattern

With DAL Pattern

Transaction Propagation

Bypassing Plugins

Custom Plugin Example

Architecture

How It Works

Intercepted Methods

Plugin Lifecycle

Transaction Handling

Performance

Zero Overhead Fast Paths

Benchmarks

See Also