2.1 KiB
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)