Skip to Content
Gap Analysis

Last Updated: 3/10/2026

Documentation Gap Analysis

Overview

This analysis identifies gaps between the Kysely codebase and existing documentation to help prioritize future documentation efforts.

Current Documentation Coverage

✅ Well Documented Areas

  1. Getting Started & Core Concepts

    • Introduction and installation
    • Basic query building (SELECT, INSERT, UPDATE, DELETE)
    • Type generation
    • Dialects and database support

  2. API Reference

    • 55 API documentation pages covering core classes and interfaces
    • Comprehensive TypeScript type documentation

  3. Recipes & Advanced Topics

    • Relations
    • Reusable helpers
    • Data types
    • Raw SQL
    • Conditional selects
    • Expressions
    • Schemas
    • Deduplicate joins
    • Type depth issues
    • Extending Kysely

  4. Runtime Support

    • Browser usage
    • Deno runtime

  5. Integrations

    • LLMs
    • Supabase

🔍 Identified Gaps

High Priority

1. Query Builder Components

Missing comprehensive guides for:

  • Aggregate Functions (src/query-builder/aggregate-function-builder.ts)

    • GROUP BY usage patterns
    • HAVING clauses
    • Window functions with OVER
    • Common aggregation patterns (COUNT, SUM, AVG, etc.)

  • CASE Expressions (src/query-builder/case-builder.ts)

    • CASE WHEN usage
    • Conditional logic in queries
    • Type-safe case expressions

  • CTEs (Common Table Expressions) (src/query-builder/cte-builder.ts)

    • WITH clause usage
    • Recursive CTEs
    • Multiple CTEs in a single query

  • MERGE Operations (src/query-builder/merge-query-builder.ts)

    • MERGE/UPSERT patterns
    • Database-specific MERGE support

  • ON CONFLICT (src/query-builder/on-conflict-builder.ts)

    • Upsert patterns
    • Conflict resolution strategies

  • JSON Path Operations (src/query-builder/json-path-builder.ts)

    • Working with JSON columns
    • JSON path queries
    • Type-safe JSON operations

2. Plugin System Deep Dive

Current state: Basic plugin documentation exists Missing:

  • Detailed guide on creating custom plugins
  • Plugin architecture explanation
  • Built-in plugin reference:
    • CamelCase plugin (src/plugin/camel-case)
    • Deduplicate joins plugin (src/plugin/deduplicate-joins)
    • Handle empty IN lists plugin (src/plugin/handle-empty-in-lists)
    • Immediate value plugin (src/plugin/immediate-value)
    • Parse JSON results plugin (src/plugin/parse-json-results)
    • With schema plugin (src/plugin/with-schema)

3. Migration System

Current state: Basic migrations documentation exists Missing:

  • File migration provider details
  • Migration best practices
  • Migration rollback strategies
  • Team workflow for migrations
  • Migration testing approaches

4. Error Handling

Missing:

  • NoResultError usage and handling (src/query-builder/no-result-error.ts)
  • Common error patterns
  • Type-safe error handling
  • Database-specific error handling

Medium Priority

5. Advanced Join Patterns

Partial coverage in examples Missing:

  • Self-joins
  • Multiple join conditions
  • Join performance considerations
  • Join builder advanced usage

6. Transaction Patterns

Current state: Basic transaction examples exist Missing:

  • Nested transactions
  • Transaction isolation levels
  • Savepoints usage
  • Transaction error recovery
  • Long-running transaction best practices

7. Query Execution & Performance

Current state: Basic execution flow documented Missing:

  • Query compilation details
  • Performance optimization guide
  • Batch operations
  • Streaming results
  • Connection pooling best practices

8. Testing with Kysely

Missing entirely:

  • Unit testing queries
  • Integration testing
  • Mocking strategies
  • Test database setup
  • Snapshot testing query builders

Low Priority

9. Advanced Type Patterns

Partial coverage exists Could expand:

  • Complex type inference scenarios
  • Generic query builders
  • Type narrowing techniques
  • Working with dynamic types

10. Dialect-Specific Features

Current state: Basic dialect documentation Missing:

  • PostgreSQL-specific features (arrays, JSON, full-text search)
  • MySQL-specific features
  • MSSQL-specific features
  • SQLite-specific features
  • Dialect comparison guide

📊 Documentation Statistics

  • Total imported articles: 82
  • API reference pages: 55
  • Guide/tutorial pages: 27
  • Example files: ~35 (in site/docs/examples/)

🎯 Recommended Next Steps

Immediate Actions

  1. Create comprehensive guide for aggregate functions and window functions
  2. Add detailed CASE expression tutorial
  3. Expand CTE documentation with recursive examples
  4. Document all built-in plugins with examples

Short-term (1-2 months)

  1. Create error handling guide
  2. Expand migration documentation
  3. Add testing guide for Kysely applications
  4. Document MERGE and ON CONFLICT patterns

Long-term (3-6 months)

  1. Create dialect-specific feature guides
  2. Add performance optimization guide
  3. Expand transaction documentation
  4. Create video tutorials for complex topics

📝 Notes

  • The existing documentation is comprehensive for basic usage
  • API documentation is excellent and auto-generated
  • Main gaps are in intermediate-to-advanced usage patterns
  • Examples exist for many features but lack narrative explanation
  • Plugin system documentation could be significantly expanded
LlmsRoadmap