Summary

This PR adds Write-Ahead Logging (WAL) mode support to the @keyv/sqlite package. Users can now enable WAL mode via the wal option in the KeyvSqlite constructor for better concurrency and performance.

What is WAL Mode?

Write-Ahead Logging (WAL) is an alternative journaling mode in SQLite that provides:

• Better concurrency (readers don't block writers, writers don't block readers)
• Improved performance in many scenarios
• Better crash resistance
• Atomic commits

Reference: https://sqlite.org/wal.html

Changes Made

1. Type Definition (packages/sqlite/src/types.ts)

   • Added wal?: boolean option to KeyvSqliteOptions interface

2. Core Implementation (packages/sqlite/src/index.ts)

   • Modified the connect function to execute PRAGMA journal_mode=WAL after database connection if wal: true is specified
   • Added proper TypeScript type annotation for Promise<sqlite3.Database>

3. Tests (packages/sqlite/test/test.ts)

   • Added test to verify WAL mode is enabled when wal: true is specified
   • Added test to verify WAL mode is not enabled by default
   • Added test to verify in-memory databases remain in "memory" journal mode even with wal: true
   • All tests pass with 100% code coverage

4. Documentation (packages/sqlite/README.md)

   • Updated README to document the new wal option
   • Added Options section explaining all available configuration options
   • Documented the limitation with in-memory databases

Usage Example

```javascript
import Keyv from 'keyv';
import KeyvSqlite from '@keyv/sqlite';

// Enable WAL mode
const store = new KeyvSqlite({
uri: 'sqlite://path/to/database.sqlite',
wal: true
});

const keyv = new Keyv({ store });
```

Important Notes

In-Memory Database Limitation

WAL mode does NOT work with in-memory databases (:memory:). SQLite automatically uses a special "memory" journal mode for in-memory databases that cannot be changed. This is expected behavior and matches how SQLite works natively - it silently ignores the WAL mode request and remains in "memory" journal mode.

Default Behavior

WAL mode is disabled by default to maintain backward compatibility. Users must explicitly opt-in by setting wal: true in the options.

Benefits of WAL Mode

Pros:

• Better concurrency - multiple readers can access simultaneously, writers don't block readers
• Improved performance for most write operations
• Better crash resistance and atomic commits

Cons:

• Creates -wal and -shm files alongside the database file
• Not ideal for network filesystems (NFS, SMB)
• Slightly higher disk space usage

Testing

All tests pass with 100% code coverage:

• ✅ WAL mode is correctly enabled when wal: true is specified with file-based databases
• ✅ Default behavior (no WAL) remains unchanged
• ✅ In-memory databases remain in "memory" journal mode (expected behavior)
• ✅ All existing functionality works with and without WAL mode

References

• SQLite WAL Documentation
• SQLite PRAGMA journal_mode
• SQLite In-Memory Databases