Migrating from Y.js

This guide is for Y.js users who want a server-backed, offline-first data layer with durable Postgres storage and server-side queries. The mapping is one-to-one for whole-document and whole-map use cases (Y.Map / Y.Doc), but Y.js features built on character-level operational transform (Y.Text, RelativePosition) and presence (Y.Awareness, UndoManager) do not have direct TopGun equivalents — cross-check the Concept Mapping table and the roadmap before porting.

Concept Mapping

Side-by-Side Code Patterns

Pattern A — Initialize and connect

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { IndexeddbPersistence } from 'y-indexeddb';

const doc = new Y.Doc();

// Offline persistence
const idb = new IndexeddbPersistence('my-room', doc);

// Realtime sync
const provider = new WebsocketProvider(
  'wss://yjs.example.com',
  'my-room',
  doc,
);

import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

const client = new TopGunClient({
  serverUrl: 'wss://topgun.example.com',
  storage: new IDBAdapter(),
});

// JWT issuance is handled by your own auth server.
// See /docs/guides/authentication for integration options.
const jwt = await myAuthServer.signIn(email, password);
client.setAuthToken(jwt);

In Y.js, a Y.Doc is the unit of sync — each room/document gets its own provider and persistence. In TopGun, a single TopGunClient owns many maps and queries over one WebSocket connection; the per-document boundary disappears.

Pattern B — Read, write, and observe

const yMap = doc.getMap('todos');

// Read
const todo = yMap.get('todo-1');
console.log(todo);

// Write
yMap.set('todo-1', { title: 'Write guide', done: false });

// Observe — fires on any change to this Y.Map
yMap.observe((event) => {
  event.changes.keys.forEach((change, key) => {
    console.log(key, change.action, yMap.get(key));
  });
});

import { Predicates } from '@topgunbuild/client';

// Read — synchronous, local-first (no await)
const todo = client.getMap('todos').get('todo-1');
console.log(todo);

// Write — synchronous, local-first; syncs in background
client.getMap('todos').set('todo-1', {
  title: 'Write guide',
  done: false,
});

// Raw local-change notifications (no filter):
const unsubLocal = client.getMap('todos').onChange(() => {
  const todo = client.getMap('todos').get('todo-1');
  console.log(todo);
});

// Filter-aware server-pushed deltas:
const query = client.query('todos', {
  predicate: Predicates.equal('done', false),
});
const unsub = query.subscribe((results) => {
  console.log(results);
});

yMap.observe and client.getMap().onChange() are the closest match — both fire on any write to the local map. For filter-aware deltas (e.g. “only show open todos”), use client.query().subscribe(), which Y.js does not provide because all filtering in Y.js is client-side over the full document.

If you’re using React

import { useQuery, useMutation } from '@topgunbuild/react';
import { type Todo } from './schema';

function TodoList() {
  const { data: todos } = useQuery<Todo>('todos');
  const { create } = useMutation<Todo>('todos');
  const add = () => create(crypto.randomUUID(), { title: 'Write guide', done: false });
  return (
    <>
      <button onClick={add}>Add</button>
      <ul>{todos.map(t => <li key={t._key}>{t.title}</li>)}</ul>
    </>
  );
}

Deployment Mode Semantics

For a first migration, start on single-node. The partition-routed cluster mode works but does not yet have Raft-backed consensus; see the roadmap for cluster-safety status.

Why migrate?

• Local-first reads/writes: Operations never wait for network; the UI updates immediately (parity with Y.js).
• Server-side filtering and indexing: Y.js requires you to download the full document client-side and filter locally. TopGun supports client.query(filter) so the server returns only matching rows.
• Server-side queries: SQL-style queries and full-text search (tantivy) on the server. Y.js has no server-side query layer.
• Plain Postgres durable store: Migrate data off TopGun via pg_dump. Y.js typically pairs with a custom server (y-websocket, y-redis, y-leveldb) — TopGun ships with the durable store.
• Offline persistence via IDBAdapter: Always-on parity with IndexeddbPersistence.
• CRDT conflict resolution by HLC: Deterministic across clients (parity with Y.js’s CRDT semantics, but at whole-document granularity, not character-level).
• Performance: 483K ops/sec fire-and-forget, ~37K ops/sec fire-and-wait at 1.5ms p50 on M1 Max (200 connections). See benchmarks for methodology.

Migration checklist

1. Audit Y.js features in use — Y.Doc, Y.Map, Y.Array, Y.Text, Y.Awareness, Y.UndoManager, and the provider stack (y-websocket, y-indexeddb, y-leveldb, y-redis, etc.).
2. Cross-reference each against the Concept Mapping table above; mark mappings vs. gaps.
3. Flag any feature that maps to a “Not supported” or “Roadmap” cell — those need an explicit decision (drop, work around, or wait for the roadmap item).
4. Port the provider layer: replace Y.Doc + WebsocketProvider + IndexeddbPersistence with new TopGunClient({ serverUrl, storage: new IDBAdapter() }) and client.setAuthToken(jwt).
5. Port reads/writes/observes one map at a time: replace yMap.set / yMap.get / yMap.observe with client.getMap().set / .get / .onChange (and client.query().subscribe for filter-aware server-pushed deltas).
6. Backfill data: write a one-time migration script that reads from your Y.js persistence (e.g. y-leveldb / y-redis / y-mongodb) and writes to TopGun via the client SDK or directly to Postgres.