https://github.com/topgunbuild/topgun
⚡️ Realtime, offline-first, secure, graph data synchronization engine. Reimplementation of gunDB in TypeScript
https://github.com/topgunbuild/topgun
crdt cryptography database firebase graph key-value-store nodejs nosql offline-first pubsub realtime storage typescript websocket websockets
Last synced: 5 months ago
JSON representation
⚡️ Realtime, offline-first, secure, graph data synchronization engine. Reimplementation of gunDB in TypeScript
- Host: GitHub
- URL: https://github.com/topgunbuild/topgun
- Owner: TopGunBuild
- License: mit
- Created: 2023-04-02T10:40:52.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-14T13:25:24.000Z (over 1 year ago)
- Last Synced: 2024-12-19T07:06:20.050Z (over 1 year ago)
- Topics: crdt, cryptography, database, firebase, graph, key-value-store, nodejs, nosql, offline-first, pubsub, realtime, storage, typescript, websocket, websockets
- Language: TypeScript
- Homepage: https://topgun.build
- Size: 1.64 MB
- Stars: 33
- Watchers: 6
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TopGun
> **Alpha** — API may change
Hybrid offline-first in-memory data grid. Zero-latency reads and writes via local CRDTs, real-time sync via WebSockets, durable storage on your own infrastructure.
TopGun v2 is a complete rewrite. It's not a port — it's a new architecture designed for production workloads.
## Key features
- **Local-first**: Data lives in memory. Reads and writes never wait for network.
- **Offline support**: Changes persist to IndexedDB and sync when reconnected.
- **CRDT conflict resolution**: LWW-Map and OR-Map with Hybrid Logical Clocks.
- **Merkle tree sync**: Efficient delta synchronization — only changed data moves over the wire.
- **Pluggable storage**: PostgreSQL for server, IndexedDB for client, or bring your own adapter.
- **Cluster-ready**: Server-side partitioning, distributed locks, pub/sub.
- **TypeScript-first**: Full type safety from client to server.
## Quick start
```bash
npm install @topgunbuild/client @topgunbuild/adapters @topgunbuild/react
```
```typescript
import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';
const adapter = new IDBAdapter();
const client = new TopGunClient({
serverUrl: 'ws://localhost:8080',
storage: adapter,
});
client.start();
// Write data (instant, works offline)
const todos = client.getMap('todos');
todos.set('todo-1', {
id: 'todo-1',
text: 'Buy milk',
done: false,
});
// Read data
const todo = todos.get('todo-1');
// Subscribe to changes via live queries
// See useQuery hook for React integration
```
With React:
```tsx
import { TopGunProvider, useQuery, useClient } from '@topgunbuild/react';
function App() {
return (
);
}
function TodoList() {
const client = useClient();
const { data, loading } = useQuery('todos');
if (loading) return
Loading...;
const toggleTodo = (todo) => {
const todosMap = client.getMap('todos');
todosMap.set(todo.id, { ...todo, done: !todo.done });
};
return (
- toggleTodo(todo)}>
{todo.text}
{data.map((todo) => (
))}
);
}
```
## Documentation
Full docs: [topgun.build/docs](https://topgun.build/docs)
Specifications in this repo:
- [System Architecture](specifications/01_SYSTEM_ARCHITECTURE.md)
- [CRDT & Data Structures](specifications/02_DATA_STRUCTURES_CRDT.md)
- [Synchronization Protocol](specifications/03_SYNCHRONIZATION_PROTOCOL.md)
## Packages
| Package | Description |
|---------|-------------|
| `@topgunbuild/core` | CRDTs, Hybrid Logical Clock, Merkle trees, message schemas |
| `@topgunbuild/client` | Browser/Node.js SDK with IndexedDB persistence |
| `@topgunbuild/server` | WebSocket server, clustering, storage adapters |
| `@topgunbuild/react` | React hooks: `useQuery`, `useMap`, `useMutation`, `useTopic` |
| `@topgunbuild/adapters` | Storage adapters: IndexedDB |
| `@topgunbuild/adapter-better-auth` | Better Auth integration |
## Running locally
```bash
# Start server with Postgres
docker compose up --build
# Or run the example app
cd examples/notes-app
pnpm install
pnpm dev
```
## Performance Testing
### Quick Smoke Test
```bash
pnpm benchmark:smoke
```
### Full Throughput Benchmark
```bash
pnpm benchmark:throughput
```
### Micro-Benchmarks (CRDT operations)
```bash
pnpm --filter @topgunbuild/core bench
```
See [tests/benchmark/README.md](tests/benchmark/README.md) for details.
## TopGun v1
Looking for the original gun.js TypeScript port? See the [`legacy-v1`](https://github.com/TopGunBuild/topgun/tree/legacy-v1) branch (unmaintained).
---
Built by [Ivan Kalashnik](https://github.com/ivkan)