{"id":17659379,"url":"https://github.com/topgunbuild/topgun","last_synced_at":"2026-01-04T17:14:30.647Z","repository":{"id":149944226,"uuid":"622511745","full_name":"TopGunBuild/topgun","owner":"TopGunBuild","description":"⚡️ Realtime, offline-first, secure, graph data synchronization engine. Reimplementation of gunDB in TypeScript","archived":false,"fork":false,"pushed_at":"2024-12-14T13:25:24.000Z","size":1719,"stargazers_count":33,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-12-19T07:06:20.050Z","etag":null,"topics":["crdt","cryptography","database","firebase","graph","key-value-store","nodejs","nosql","offline-first","pubsub","realtime","storage","typescript","websocket","websockets"],"latest_commit_sha":null,"homepage":"https://topgun.build","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TopGunBuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-02T10:40:52.000Z","updated_at":"2024-12-14T13:25:28.000Z","dependencies_parsed_at":"2023-09-24T13:30:40.115Z","dependency_job_id":"9d6b165b-0044-4663-ae29-7675a62caa8a","html_url":"https://github.com/TopGunBuild/topgun","commit_stats":{"total_commits":449,"total_committers":2,"mean_commits":224.5,"dds":0.08463251670378624,"last_synced_commit":"16278d6a8803d380fc47aeddf4617679df6d667e"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TopGunBuild%2Ftopgun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TopGunBuild%2Ftopgun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TopGunBuild%2Ftopgun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TopGunBuild%2Ftopgun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TopGunBuild","download_url":"https://codeload.github.com/TopGunBuild/topgun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230394228,"owners_count":18218707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crdt","cryptography","database","firebase","graph","key-value-store","nodejs","nosql","offline-first","pubsub","realtime","storage","typescript","websocket","websockets"],"created_at":"2024-10-23T16:06:52.002Z","updated_at":"2025-12-28T16:46:35.257Z","avatar_url":"https://github.com/TopGunBuild.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TopGun\n\n\u003e **Alpha** — API may change\n\nHybrid 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.\n\nTopGun v2 is a complete rewrite. It's not a port — it's a new architecture designed for production workloads.\n\n## Key features\n\n- **Local-first**: Data lives in memory. Reads and writes never wait for network.\n- **Offline support**: Changes persist to IndexedDB and sync when reconnected.\n- **CRDT conflict resolution**: LWW-Map and OR-Map with Hybrid Logical Clocks.\n- **Merkle tree sync**: Efficient delta synchronization — only changed data moves over the wire.\n- **Pluggable storage**: PostgreSQL for server, IndexedDB for client, or bring your own adapter.\n- **Cluster-ready**: Server-side partitioning, distributed locks, pub/sub.\n- **TypeScript-first**: Full type safety from client to server.\n\n## Quick start\n\n```bash\nnpm install @topgunbuild/client @topgunbuild/adapters @topgunbuild/react\n```\n\n```typescript\nimport { TopGunClient } from '@topgunbuild/client';\nimport { IDBAdapter } from '@topgunbuild/adapters';\n\nconst adapter = new IDBAdapter();\nconst client = new TopGunClient({\n  serverUrl: 'ws://localhost:8080',\n  storage: adapter,\n});\n\nclient.start();\n\n// Write data (instant, works offline)\nconst todos = client.getMap('todos');\ntodos.set('todo-1', {\n  id: 'todo-1',\n  text: 'Buy milk',\n  done: false,\n});\n\n// Read data\nconst todo = todos.get('todo-1');\n\n// Subscribe to changes via live queries\n// See useQuery hook for React integration\n```\n\nWith React:\n\n```tsx\nimport { TopGunProvider, useQuery, useClient } from '@topgunbuild/react';\n\nfunction App() {\n  return (\n    \u003cTopGunProvider client={client}\u003e\n      \u003cTodoList /\u003e\n    \u003c/TopGunProvider\u003e\n  );\n}\n\nfunction TodoList() {\n  const client = useClient();\n  const { data, loading } = useQuery('todos');\n\n  if (loading) return \u003cdiv\u003eLoading...\u003c/div\u003e;\n\n  const toggleTodo = (todo) =\u003e {\n    const todosMap = client.getMap('todos');\n    todosMap.set(todo.id, { ...todo, done: !todo.done });\n  };\n\n  return (\n    \u003cul\u003e\n      {data.map((todo) =\u003e (\n        \u003cli key={todo.id} onClick={() =\u003e toggleTodo(todo)}\u003e\n          {todo.text}\n        \u003c/li\u003e\n      ))}\n    \u003c/ul\u003e\n  );\n}\n```\n\n## Documentation\n\nFull docs: [topgun.build/docs](https://topgun.build/docs)\n\nSpecifications in this repo:\n- [System Architecture](specifications/01_SYSTEM_ARCHITECTURE.md)\n- [CRDT \u0026 Data Structures](specifications/02_DATA_STRUCTURES_CRDT.md)\n- [Synchronization Protocol](specifications/03_SYNCHRONIZATION_PROTOCOL.md)\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| `@topgunbuild/core` | CRDTs, Hybrid Logical Clock, Merkle trees, message schemas |\n| `@topgunbuild/client` | Browser/Node.js SDK with IndexedDB persistence |\n| `@topgunbuild/server` | WebSocket server, clustering, storage adapters |\n| `@topgunbuild/react` | React hooks: `useQuery`, `useMap`, `useMutation`, `useTopic` |\n| `@topgunbuild/adapters` | Storage adapters: IndexedDB |\n| `@topgunbuild/adapter-better-auth` | Better Auth integration |\n\n## Running locally\n\n```bash\n# Start server with Postgres\ndocker compose up --build\n\n# Or run the example app\ncd examples/notes-app\npnpm install\npnpm dev\n```\n\n## Performance Testing\n\n### Quick Smoke Test\n```bash\npnpm benchmark:smoke\n```\n\n### Full Throughput Benchmark\n```bash\npnpm benchmark:throughput\n```\n\n### Micro-Benchmarks (CRDT operations)\n```bash\npnpm --filter @topgunbuild/core bench\n```\n\nSee [tests/benchmark/README.md](tests/benchmark/README.md) for details.\n\n## TopGun v1\n\nLooking for the original gun.js TypeScript port? See the [`legacy-v1`](https://github.com/TopGunBuild/topgun/tree/legacy-v1) branch (unmaintained).\n\n---\n\nBuilt by [Ivan Kalashnik](https://github.com/ivkan)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopgunbuild%2Ftopgun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftopgunbuild%2Ftopgun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopgunbuild%2Ftopgun/lists"}