@ocap/indexdb-sqlite

OCAP indexdb adapter that uses SQLite as backend via Kysely

Install

npm install @ocap/indexdb-sqlite
// or
bun install @ocap/indexdb-sqlite

Usage

In-Memory Mode

For testing or ephemeral data:

const SqliteIndexDB = require('@ocap/indexdb-sqlite').default;

const indexdb = new SqliteIndexDB({ filename: ':memory:' });
await indexdb.initialize();

// Use indexdb...
await indexdb.tx.insert({ hash: 'abc123', sender: 'z1...' });

// Close when done
await indexdb.close();

File Mode

For persistent storage:

const SqliteIndexDB = require('@ocap/indexdb-sqlite').default;

const indexdb = new SqliteIndexDB({ filename: '/path/to/indexdb.sqlite' });
await indexdb.initialize();

// Data persists across restarts

Features

• WAL mode enabled by default for better concurrent read performance
• Automatic migrations on initialization
• Generated columns for big number sorting (balances up to 24+ digits)
• Full-featured list methods with filtering, pagination, and sorting
• All 12 index tables: tx, account, asset, token, factory, stake, delegation, rollup, etc.

Big Number Sorting

SQLite cannot natively sort numeric strings as numbers. This adapter uses generated columns to handle large balance values (commonly found in blockchain applications):

-- Accounts with balances like "99999999999999999999" sort correctly
SELECT * FROM account ORDER BY balance_sort DESC;

API

Constructor Options

interface SqliteIndexDBOptions {
  filename: string;  // ':memory:' or file path
}

Methods

• initialize() - Run migrations and prepare database
• close() - Close database connection
• listTransactions(params) - Query transactions with filters
• listTopAccounts(params) - Get accounts sorted by balance
• listAssets(params) - Query assets by owner/factory
• listTokens(params) - List all tokens
• listFactories(params) - List asset factories
• listStakes(params) - Query stake records
• listDelegations(params) - Query delegations
• listRollups(params) - List rollup configurations
• getRelatedAddresses(address) - Find related addresses