Research: Relational Document System for Neovim

SQLite Integration

Decision: Use lsqlite3 for SQLite database operations Rationale: lsqlite3 is the most mature and widely used SQLite binding for Lua, with excellent Neovim compatibility and minimal dependencies Alternatives considered:

lua-sqlite3 (less mature, fewer updates)
Custom file-based indexing (limited query capabilities)

YAML Parsing

Decision: Use lyaml for YAML header parsing Rationale: lyaml provides robust YAML parsing with proper error handling for malformed headers, essential for document reliability Alternatives considered:

Custom regex parsing (brittle, fails with complex YAML)
yaml.lua (less maintained than lyaml)

Virtual Buffer Management

Decision: Use Neovim's native nvim_buf_ API Rationale: Native API provides the most seamless integration with Neovim's buffer system, ensuring compatibility with existing plugins and user workflows Alternatives considered:

Floating windows (less persistent, not ideal for editing)
External terminal buffers (breaks Neovim integration)

Query Syntax Design

Decision: Custom block syntax similar to code blocks Rationale: Block syntax is familiar to markdown users and provides clear delimiters for query parsing while maintaining readability Alternatives considered:

Inline syntax (cluttered, hard to parse)
Special comments (not intuitive for query visualization)

Performance Optimization

Decision: Hybrid indexing approach (SQLite + in-memory cache) Rationale: SQLite provides persistent storage and complex query capabilities, while in-memory caching ensures sub-100ms response times for frequently accessed data Alternatives considered:

Pure file-based indexing (slow for large document sets)
Pure in-memory (data loss on restart)

Testing Framework

Decision: busted with nvim-test plugin Rationale: busted provides comprehensive testing capabilities with good async support, while nvim-test enables Neovim-specific testing scenarios Alternatives considered:

luaunit (limited Neovim integration)
Custom testing harness (maintenance overhead)

2.1 KiB Raw Blame History