KVSqlite

A powerful, document-oriented SQLite Key-Value store with full-text search, built on better-sqlite3.

KVSqlite is a high-performance, persistent Key-Value store that directly extends better-sqlite3. It provides a flexible, MongoDB-like document API on top of SQLite's robust feature set, designed for Node.js applications that need a simple yet powerful local database with advanced features like full-text search and flexible indexing.

✨ Key Features

• Flexible Document-Style API: Seamlessly store and query complex JSON objects. Fixed fields and JSON data are automatically merged.
• Automatic Timestamps: createdAt and updatedAt fields are automatically managed by database triggers.
• Powerful Full-Text Search (FTS5): Integrated support for boolean queries, result ranking, and advanced tokenizers, including pre-packaged Chinese word segmentation.
• Advanced Indexing: Create unique, partial, and JSON indexes for optimized query performance.
• Transactional Integrity: ACID-compliant transactions for reliable data manipulation.
• Extensible: Load custom SQLite extensions and plugins.

📦 Installation

This library requires better-sqlite3 as a peer dependency.

# Using npm
npm install @isdk/kvsqlite better-sqlite3

# Using yarn
yarn add @isdk/kvsqlite better-sqlite3

🚀 Quick Start

The KVSqlite constructor is identical to better-sqlite3's Database constructor. You can pass KVSqlite-specific options in the second argument.

import { KVSqlite } from '@isdk/kvsqlite';

// 1. Initialize the KVSqlite database.
// The constructor is the same as for better-sqlite3's Database.
// Use ':memory:' for an in-memory DB, or a file path for persistence.
const db = new KVSqlite(':memory:');

// By default, a collection named `kv` is created.
// You can operate on it directly from the db instance.
await db.set('some_key', { info: 'default collection data' });
const defaultData = await db.get('some_key');
console.log('Data in default collection:', defaultData);


// 2. Create and use a named collection for structured data (Recommended).
interface User {
  _id: string;
  name: string;
  age: number;
}

// Use the .create() method on the db instance to get a collection.
const users = db.create('users');

// 3. Now, perform operations on the 'users' collection.
const alice: User = {
  _id: 'u001',
  name: 'Alice',
  age: 30,
};
await users.set(alice);

const foundUser = await users.get('u001');
console.log('Found in users collection:', foundUser);

// 4. (Optional) Create collections on initialization.
const dbWithCollections = new KVSqlite(':memory:', {
  collections: ['products', 'orders']
});
const products = dbWithCollections.getCollection('products');
await products.set({ _id: 'p1', name: 'Laptop' });
console.log('Found in products collection:', await products.get('p1'));

Advanced Usage

Full-Text Search (FTS5)

Enable FTS5 when creating a collection to perform advanced text searches.

import { KVSqlite } from '@isdk/kvsqlite';

const db = new KVSqlite(':memory:');

const posts = db.create('posts', {
  // Enable FTS on creation
  fts: true,
});

await posts.bulkDocs([
  { _id: 'p01', content: 'SQLite is a powerful and fast database engine.' },
  { _id: 'p02', content: 'KVSqlite provides a simple API for SQLite.' },
]);

// Search for one or more terms
const results = await posts.searchFts('powerful OR simple');
console.log(results);

Chinese Full-Text Search

KVSqlite comes with a pre-built plugin for Chinese word segmentation.

import { KVSqlite } from '@isdk/kvsqlite';

const db = new KVSqlite(':memory:');

const articles = db.create('articles', {
  fts: {
    language: 'zh', // Enable the Chinese tokenizer
  },
});

await articles.set({ _id: 'a01', content: '数据库是一个非常有用的工具' });

// The search query will be tokenized automatically
const results = await articles.searchFts('数据库 工具');
console.log(results);

Using Custom Fields and Indexes

You can define a fixed schema with typed fields and create indexes for faster queries.

import { KVSqlite } from '@isdk/kvsqlite';

const db = new KVSqlite(':memory:');

const products = db.create('products', {
  // Define fixed fields alongside the default '_id' and 'val'
  fields: {
    category: { type: 'TEXT' },
    price: { type: 'REAL' },
  },
  indexes: [
    // Create an index on the 'category' field
    { name: 'category_idx', fields: ['category'] },
    // Create a partial index for expensive products
    { name: 'expensive_idx', fields: ['price'], partial: 'price > 1000' },
  ],
});

await products.set({ _id: 'prod01', category: 'electronics', price: 1200, val: { name: 'Laptop' } });

// This query will be fast due to the index
const electronics = await products.searchEx({ category: 'electronics' });
console.log(electronics);

📚 API Documentation

For a detailed API reference, please see the generated TypeDoc documentation.

📜 License

This project is licensed under the MIT License. See the LICENSE-MIT file for details.