High-performance document database with CRDT real-time sync + HyperScale + Transaction Manager
High-performance document database with CRDT real-time sync.
``bash`
npm install kimdb
- Document Database: SQLite-based, JSON documents
- Real-time Sync: WebSocket + CRDT (Conflict-free Replicated Data Types)
- Offline-first: Local-first with automatic sync
- CRDT Primitives: VectorClock, LWWSet, LWWMap, RGA, RichText
- Presence: Real-time user presence and cursors
- Undo/Redo: Built-in undo/redo support
- TypeScript: Full TypeScript support
- Redis Clustering: Optional multi-server support
`bashInitialize project
npx kimdb init
$3
`typescript
import { KimDBServer } from 'kimdb/server';const server = new KimDBServer();
await server.start();
// Server running on http://localhost:40000
`$3
`typescript
import { KimDBClient } from 'kimdb/client';const client = new KimDBClient({
url: 'ws://localhost:40000/ws',
apiKey: 'your-api-key',
});
await client.connect();
// Subscribe to collection
client.subscribe('posts');
// Open document
const doc = await client.openDocument('posts', 'post-1');
// Set values
client.set('posts', 'post-1', 'title', 'Hello World');
client.set('posts', 'post-1', ['author', 'name'], 'John');
// Listen for sync events
client.onSync = (collection, event, data) => {
console.log('Sync:', collection, event, data);
};
`$3
`typescript
import { CRDTDocument, LWWSet, VectorClock } from 'kimdb/crdt';// Document with automatic conflict resolution
const doc = new CRDTDocument('node1', 'doc-1');
doc.set('title', 'My Document');
doc.listInsert('tags', 0, 'crdt');
doc.setAdd('authors', 'user1');
// Get as plain object
const obj = doc.toObject();
// Serialize for network/storage
const json = doc.toJSON();
const restored = CRDTDocument.fromJSON(json);
// Standalone CRDT types
const set = new LWWSet('node1');
set.add('item1');
set.remove('item2');
`Configuration
Environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
|
KIMDB_API_KEY | (required in prod) | API key for authentication |
| KIMDB_PORT | 40000 | Server port |
| KIMDB_HOST | 0.0.0.0 | Server host |
| KIMDB_DATA_DIR | ./data | Data directory |
| REDIS_ENABLED | false | Enable Redis for clustering |
| MARIADB_ENABLED | false | Enable MariaDB for logging |REST API
$3
`
GET /health
`$3
`
GET /api/collections
GET /api/c/:collection
GET /api/c/:collection/:id
`$3
`
POST /api/sql
{
"sql": "SELECT * FROM table WHERE id = ?",
"params": [1],
"collection": "my_collection"
}
`WebSocket API
Connect to
ws://host:port/ws$3
`typescript
// Subscribe
{ type: 'subscribe', collection: 'posts' }// Get CRDT state
{ type: 'crdt_get', collection: 'posts', docId: 'post-1' }
// Set value
{ type: 'crdt_set', collection: 'posts', docId: 'post-1', path: 'title', value: 'Hello' }
// Batch operations
{ type: 'crdt_ops', collection: 'posts', docId: 'post-1', operations: [...] }
// Presence
{ type: 'presence_join', collection: 'posts', docId: 'post-1', user: { name: 'John' } }
`CRDT Types
$3
Logical clock for causal ordering.`typescript
const clock = new VectorClock('node1');
clock.tick();
clock.merge(otherClock);
clock.compare(otherClock); // -1, 0, 1
`$3
Set with timestamps for conflict resolution.`typescript
const set = new LWWSet('node1');
set.add('item');
set.remove('item');
set.has('item');
set.toArray();
`$3
Map with LWW conflict resolution.`typescript
const map = new LWWMap('node1');
map.set('key', 'value');
map.get('key');
map.delete('key');
map.toObject();
`$3
Ordered list/text with character-level sync.`typescript
const rga = new RGA('node1');
rga.insert(0, 'a');
rga.insert(1, 'b');
rga.delete(0);
rga.toArray();
rga.toString();
`$3
Rich text with formatting support.`typescript
const rt = new RichText('node1');
rt.insert(0, 'H', { bold: true });
rt.format(0, 5, { italic: true });
rt.toDelta(); // Quill-compatible
`Production Deployment
$3
`bash
Initialize
npx kimdb initStart with PM2
pm2 start ecosystem.config.cjs
`$3
`dockerfile
FROM node:18-alpine
WORKDIR /app
RUN npm install kimdb
COPY .env .
CMD ["npx", "kimdb", "start"]
`Clustering
Multi-server synchronization via Redis Pub/Sub:
`
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Server 1 │────▶│ Redis │◀────│ Server 2 │
│ :40000 │◀────│ Pub/Sub │────▶│ :40001 │
└─────────────┘ └─────────────┘ └─────────────┘
``bash
Server 1
KIMDB_PORT=40000 REDIS_ENABLED=true REDIS_HOST=redis-server npx kimdb startServer 2
KIMDB_PORT=40001 REDIS_ENABLED=true REDIS_HOST=redis-server npx kimdb start
`Security
- Set
KIMDB_API_KEY` environment variable (required in production)MIT