JavaScript Web V4→V5 API Migration Guide

Overview

This guide covers the essential changes needed to migrate your Ditto JavaScript Web app from v4 to v5. The main architectural shift is moving from identity-based initialization to a four-phase configuration model with Promise-based APIs. Also required: v5 uses DQL (Ditto Query Language) for all data operations. See the DQL Migration Guide for query migration steps.

AI Agent Prompt

Use this prompt when working with an AI coding assistant to migrate your Ditto JavaScript Web app from v4 to v5.

Copy AI Migration Prompt (Click to Expand)

I need help migrating a Ditto JavaScript Web application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace `new Ditto(identity)` with `await Ditto.open(config)` using async/await.
- `await init()` is STILL required for web before any Ditto API calls (loads WebAssembly)
- Create a `DittoConfig` with `databaseID` and a connect mode object
- `{ type: 'onlinePlayground', appID, token }` → `new DittoConfig(databaseID, { mode: 'server', url: 'https://<databaseID>.cloud.ditto.live' })`
- `{ type: 'onlineWithAuthentication', appID, authHandler }` → `new DittoConfig(databaseID, { mode: 'server', url })` + `auth.setExpirationHandler()`
- `{ type: 'offlinePlayground', appID }` → `new DittoConfig(databaseID, { mode: 'smallPeersOnly' })`
- `{ type: 'sharedKey', appID, sharedKey }` → `new DittoConfig(databaseID, { mode: 'smallPeersOnly', privateKey: sharedKey })`
- `{ type: 'manual', certificate }` → **No replacement** — removed in v5
- The Ditto constructor is now private. You MUST use `Ditto.open(config)` (async) or `Ditto.openSync(config)` (sync).
- Remove `disableSyncWithV3()` calls — v3 protocol is fully dropped in v5
- Remove `updateTransportConfig` workaround patterns for adding websocket URLs
- Remove `ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")` — v5 defaults to `false`
- IMPORTANT: If your v4 app used the default (strict=true), set `DQL_STRICT_MODE=true` BEFORE starting sync

SYNC:
The sync API moved from top-level Ditto methods to the `ditto.sync` sub-object.
- `ditto.startSync()` → `ditto.sync.start()`
- `ditto.stopSync()` → `ditto.sync.stop()`
- `ditto.isSyncActive` → `ditto.sync.isActive`

AUTHENTICATION:
The `AuthenticationHandler` callback interface is removed. Replace with `setExpirationHandler` + `login()`.
- Set `await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => { ... })` after Ditto.open()
- Handler signature: `(ditto: Ditto, timeUntilExpiration: number) => Promise<any> | any`
- Inside the handler, call `await ditto.auth.login(token, provider)` which returns `{ clientInfo, error }`
- Use `Authenticator.DEVELOPMENT_PROVIDER` for playground/dev tokens

OBSERVERS:
Observers use callback-based pattern with `registerObserver(query, handler, queryArguments?)`.
- Parameter order: handler comes BEFORE query arguments
- `observer.cancel()` for cleanup (replaces `liveQuery.stop()`)
- For back-pressure: use `registerObserverWithSignalNext(query, handler, args?)` to control when next update fires

COLLECTION API → DQL:
The entire Collection/Document API is removed. Replace with `store.execute()`.
- `store.collection(name)` → `store.execute('SELECT * FROM <name>')`
- `collection.upsert(value)` → `store.execute('INSERT INTO <name> DOCUMENTS (:doc)', { doc: value })`
- `collection.findByID(id).update(fn)` → `store.execute('UPDATE <name> SET ... WHERE _id = :id', { id })`
- `collection.findByID(id).remove()` → `store.execute('DELETE FROM <name> WHERE _id = :id', { id })`
- Always use parameterized queries with `:paramName` — NEVER use string interpolation

LIVE QUERIES → STORE OBSERVERS:
- `collection.findAll().observeLocal(handler)` → `store.registerObserver(query, handler, args?)`
- `liveQuery.stop()` → `observer.cancel()`
- v4 handler: `(docs, event) => { ... }` → v5 handler: `(result) => { ... }` where result has `.items`

SUBSCRIPTIONS:
- `collection.findAll().subscribe()` → `sync.registerSubscription('SELECT * FROM <name>')`
- `Subscription` → `SyncSubscription`; generics removed

TRANSACTIONS:
- `store.write(callback)` → `store.transaction(scope, options?)`
- `WriteTransaction` classes removed — use DQL via `tx.execute()`

PRESENCE:
- `peer.peerKeyString` → `peer.peerKey`
- `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- `connection.peerKeyString1/2` → `connection.peer1/2`
- `connection.approximateDistanceInMeters` → removed
- `ditto.observePeers()` → `ditto.presence.observe()`

DITTO CLASS:
- `new Ditto(identity)` → `await Ditto.open(config)` (constructor private)
- `ditto.appID` → `ditto.config.databaseID`
- `ditto.siteID` → removed
- `ditto.sdkVersion` → `Ditto.VERSION` (static)
- `ditto.path` → `ditto.absolutePersistenceDirectory`
- `ditto.runGarbageCollection()` → removed (automatic)
- `ditto.close()` is still available (async)

BEFORE (v4):
```typescript
import { init, Ditto } from '@dittolive/ditto'
await init()

const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'https://your-server.ditto.live'
});
ditto.updateTransportConfig((config) => {
    config.connect.websocketURLs.add('wss://...');
});
ditto.store.execute('ALTER SYSTEM SET DQL_STRICT_MODE = false');
ditto.disableSyncWithV3();
ditto.startSync();

const observer = ditto.store.registerObserver(query, (result) => {
    updateUI(result.items);
}, args);
```

AFTER (v5):
```typescript
import { init, Ditto, DittoConfig, Authenticator } from '@dittolive/ditto'
await init()

const config = new DittoConfig(
    "your-database-id",
    { mode: 'server', url: "https://your-server.ditto.live" }
);
const ditto = await Ditto.open(config);

await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => {
    try {
        await ditto.auth.login("your-token", Authenticator.DEVELOPMENT_PROVIDER);
    } catch (error) {
        console.error(`Ditto auth failed: ${error}`);
    }
});

ditto.sync.start();

const observer = ditto.store.registerObserver(query, (result) => {
    updateUI(result.items);
}, args);

// Cleanup
observer.cancel();
ditto.sync.stop();
await ditto.close();
```

CHECKLIST:
- Ensure `await init()` is called before Ditto APIs (required for web)
- Replace `new Ditto(identity)` with `await Ditto.open(new DittoConfig(...))`
- Create `DittoConfig` with `databaseID` and connect mode
- Set up `auth.setExpirationHandler()` with `(ditto, timeUntilExpiration)` signature
- Replace `startSync()` → `sync.start()`
- Replace all `store.collection()` calls with `store.execute()` DQL
- Replace `store.write()` with `store.transaction()`
- Replace `liveQuery.stop()` with `observer.cancel()`
- Replace `ditto.observePeers()` with `ditto.presence.observe()`
- Update `peerKeyString` → `peerKey`
- Update `isConnectedToDittoCloud` → `isConnectedToDittoServer`
- Remove `disableSyncWithV3()`, `updateTransportConfig` workarounds

Work through the codebase systematically. Show me each file's changes.

Ditto Instance Initialization

v5 separates initialization into four distinct phases for better clarity and control:

import { init, Ditto, DittoConfig, Authenticator } from '@dittolive/ditto'

// Required for web — initializes the WebAssembly module
await init()

// 1. Configure
const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "https://your-server.ditto.live"
    }
);

// 2. Initialize (async)
const ditto = await Ditto.open(config);

// 3. Authenticate
await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => {
    try {
        await ditto.auth.login("your-token", Authenticator.DEVELOPMENT_PROVIDER);
    } catch (error) {
        console.error(`Ditto auth failed: ${error}, time until expiration: ${timeUntilExpiration}`);
    }
});

// 4. Start sync
ditto.sync.start();

These changes provide:

Clear separation of connection, initialization, and authentication concerns
Async initialization prevents blocking the event loop
No workarounds needed (transport config, DQL strict mode, v3 sync disable)
Type-safe configuration with compile-time validation

Web-specific: await init() is still required before any Ditto API calls. It initializes the WebAssembly module. This is unchanged from v4.

Initialization Migration Steps

Replace Initialization

Replace new Ditto() constructor with await Ditto.open(config).

await init()  // Still required for web

const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "https://your-server.ditto.live"
    }
);

const ditto = await Ditto.open(config);
ditto.sync.start();

Key changes:

Use DittoConfig constructor instead of identity object
appID → databaseID (first parameter)
{ type: 'onlinePlayground' } → { mode: 'server', url: ... }
{ type: 'offlinePlayground' } → { mode: 'smallPeersOnly' }
{ type: 'sharedKey', sharedKey } → { mode: 'smallPeersOnly', privateKey: sharedKey }
Add await for async initialization
Remove updateTransportConfig, disableSyncWithV3(), and DQL strict mode queries

Update Authentication

Set authentication handler separately after initialization.

// Set handler after Ditto.open()
// Handler signature: (ditto: Ditto, timeUntilExpiration: number) => Promise<any> | any
await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => {
        // Initial auth or token refresh
        try {
            await ditto.auth.login(
                "your-token",
                Authenticator.DEVELOPMENT_PROVIDER
            );
        } catch (error) {
            console.error(`Ditto auth failed: ${error}`);
        }
});

Key changes:

Authentication now uses setExpirationHandler async function
Handler receives (ditto: Ditto, timeUntilExpiration: number)
First parameter is the Ditto instance — access auth via ditto.auth.login()
Handler called when auth required (timeUntilExpiration === 0) or token expiring
Use Authenticator.DEVELOPMENT_PROVIDER for playground tokens
Custom auth: "your-provider-name" string

Additional Changes

DQL Strict Mode Behavior Change

Breaking Change: v5 defaults to DQL_STRICT_MODE=false, which fundamentally changes how DQL queries behave.

v4 default: Objects treated as REGISTER (whole-object replacement)
v5 default: Objects treated as MAP (field-level merging)

This affects the behavior of all DQL SELECT, INSERT, and UPDATE operations.

Choose the appropriate migration path based on your current v4 configuration:

Currently Using DQL with DQL_STRICT_MODE=true (v4 default)

If you’re currently using the v4 default (DQL_STRICT_MODE=true), you must explicitly set strict mode to true in v5 before starting sync or executing any queries.

Failing to set strict mode will cause objects to merge at the field level instead of replacing entirely, which can result in unexpected data behavior and perceived data loss.

To migrate to DQL_STRICT_MODE=false (the new v5 default), contact Ditto Customer Support for guidance.

const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "https://your-server.ditto.live"
    }
);
const ditto = await Ditto.open(config);

// IMPORTANT: Set strict mode BEFORE starting sync or running queries
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = true");

// Now safe to start sync
ditto.sync.start();

Currently Using DQL with DQL_STRICT_MODE=false

If you explicitly set DQL_STRICT_MODE=false in v4, no changes are required.v5 uses DQL_STRICT_MODE=false as the default, so your existing DQL queries will behave identically. You can upgrade freely.Optional: You can remove the explicit ALTER SYSTEM SET DQL_STRICT_MODE = false statement in v5 since this is now the default behavior.

const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "https://your-server.ditto.live"
    }
);
const ditto = await Ditto.open(config);

// No need to set DQL_STRICT_MODE - false is now the default
ditto.sync.start();

Currently Using Legacy Query Builder

The Legacy Query Builder has been removed in v5. All queries must be converted to DQL before upgrading.Good news: Legacy Query Builder functionality has 1:1 support with DQL_STRICT_MODE=false (the v5 default), making migrations straightforward.Migration Steps:

In v4: Set DQL_STRICT_MODE=false after initialization:

const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'https://your-server.ditto.live'
});

// Set DQL_STRICT_MODE to false for Query Builder compatibility
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false");

ditto.startSync();

Convert all queries from Legacy Query Builder to DQL See the JavaScript Legacy→DQL Migration Guide for detailed conversion examples.
Upgrade to v5 No DQL configuration changes required—v5 defaults to DQL_STRICT_MODE=false.

For additional guidance or questions, contact Ditto Customer Support.

Default Persistence Directory

v5 includes the database ID in the default directory name: ditto-{databaseID} instead of ditto To maintain v4 compatibility:

const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "https://your-server.ditto.live"
    },
    "/app/data/ditto"  // Old v4 path
);

API Renames

v4.14	v5.0
`new Ditto(identity)` constructor	`Ditto.open(config)` (async) or `Ditto.openSync(config)`
`ditto.startSync()`	`ditto.sync.start()`
`ditto.stopSync()`	`ditto.sync.stop()`
`ditto.isSyncActive`	`ditto.sync.isActive`
`ditto.appID`	`ditto.config.databaseID`
`ditto.siteID`	Removed
`ditto.sdkVersion`	`Ditto.VERSION` (static)
`ditto.observePeers(callback)`	`ditto.presence.observe(callback)`
`Store.write(callback)`	`Store.transaction(callback)`
`Store.fetchAttachment(AttachmentToken)`	`Store.fetchAttachment(plain object)`
`registerObserver<T, U>()` (2 type params)	`registerObserver<T>()` (1 type param)
`Sync.registerSubscription<T>()` (typed)	`Sync.registerSubscription()` (no type param)
`QueryArguments` type	`DQLQueryArguments` (adds `bigint` support)
`SortDirection` / `WriteStrategy` exports	Removed — use DQL equivalents
`peerKeyString`	`peerKey`
`isConnectedToDittoCloud`	`isConnectedToDittoServer`
`connection.peerKeyString1` / `peerKeyString2`	`connection.peer1` / `peer2`
`connection.approximateDistanceInMeters`	REMOVED — no replacement

`Store.write()` → `Store.transaction()`

// v4
await ditto.store.write(async (tx) => {
    await tx.collection('cars').upsert({ _id: 'car-1', color: 'blue' });
});

// v5
await ditto.store.transaction(async (tx) => {
    await tx.execute(
        'INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE',
        { doc: { _id: 'car-1', color: 'blue' } }
    );
});

Back Pressure (registerObserverWithSignalNext)

The standard registerObserver automatically calls signalNext() after your handler returns (in a finally block). Use registerObserverWithSignalNext when your handler needs to perform async work before it is ready to receive the next update.

Coalescing behavior: While your handler is processing, Ditto coalesces intermediate changes. When you call signalNext(), you receive a single callback with the latest state — not every intermediate change.

Parameter order: Both registerObserver and registerObserverWithSignalNext take (query, handler, queryArguments?) — the handler comes before the query arguments.

// Standard observer — signalNext called automatically after handler returns
const observer = ditto.store.registerObserver(
    "SELECT * FROM cars WHERE color = :color",
    (result) => {
        updateUI(result.items);
        // signalNext() called automatically here
    },
    { color: "blue" }
);

// Back-pressure observer — call signalNext when ready for the next update
const observer = ditto.store.registerObserverWithSignalNext(
    "SELECT * FROM cars WHERE color = :color",
    async (result, signalNext) => {
        await expensiveOperation(result.items);
        signalNext();  // Ready for the next update
    },
    { color: "blue" }
);

observer.cancel(); // when done

When to use signal next:

Processing updates is computationally expensive
You’re performing async work (network calls, heavy rendering) on each update
Query results change very frequently and you want to process only the latest state

APIs Removed

Removed API	Notes
`new Ditto()` constructor	Use `Ditto.open(config)` or `Ditto.openSync(config)`
`ditto.disableSyncWithV3()`	v3 protocol support fully dropped
`ditto.runGarbageCollection()`	GC is now automatic
`ditto.siteID`	Removed entirely
`ditto.observePeers()`	Use `ditto.presence.observe()`
`Document` / `MutableDocument`	DQL returns plain objects
`DocumentID` / `DocumentPath` / `MutableDocumentPath`	Removed with legacy collection API
`Counter` / `Register` CRDT types	Use DQL `PN_INCREMENT` for counters
`Collection` / `PendingCursorOperation`	Use `store.execute()` with DQL
`LiveQuery` / `LiveQueryEvent`	Use `store.registerObserver()`
`WriteTransaction` / `WriteTransactionCollection` / `WriteTransactionResult`	Use `store.transaction()` with DQL
`UpdateResult` / `UpdateResultsMap`	DQL returns row counts
`PresenceManager`	Use `ditto.presence` directly
`SortDirection` / `WriteStrategy`	Use DQL equivalents
`AttachmentToken` class	Use plain `{ id, len, metadata }` objects
`Address` / `addressToString()`	Removed entirely
`auth.loginWithToken()` / `auth.loginWithUsernameAndPassword()`	Use `auth.login()`
`Logger.setLogFile()` / `Logger.setLogFileURL()`	Removed
`Logger.emojiLogLevelHeadingsEnabled`	Removed
`connection.approximateDistanceInMeters`	Removed

New APIs in v5

Ditto.open(config): Promise<Ditto> — async factory method
Ditto.openSync(config): Ditto — synchronous factory method
DittoConfig(id, connect, persistenceDir?) — replaces identity system
{ mode: 'server', url } / { mode: 'smallPeersOnly', privateKey? } — connect mode objects
auth.login(token, provider): Promise<LoginResult> — returns { clientInfo, error }
Authenticator.DEVELOPMENT_PROVIDER — static constant for dev provider
auth.observeStatus(callback): Observer — observe auth status changes
store.transaction(scope, options?) — DQL-based transaction
store.registerObserverWithSignalNext(query, handler, args?) — back-pressure control
StoreObserver.queryArgumentsCBORData / .queryArgumentsJSONString — introspection
SyncSubscription.queryArgumentsCBORData / .queryArgumentsJSONString — introspection
Peer.isCompatible — optional peer compatibility flag
Peer.isConnectedToDittoServer — replaces isConnectedToDittoCloud
Ditto.VERSION (static) — replaces ditto.sdkVersion
ditto.absolutePersistenceDirectory — replaces ditto.path / ditto.persistenceDirectory
QueryResult.mutatedDocumentIDsV2() — returns any[]

Migration Checklist

Initialization

Observers

Replace collection.findAll().observeLocal(handler) with store.registerObserver(query, handler, args?)
Observer callbacks now receive QueryResult with .items — update handler signatures
Replace liveQuery.stop() with observer.cancel()
Note parameter order: registerObserver(query, handler, queryArguments?)
If processing is expensive, use registerObserverWithSignalNext for back-pressure control

Authentication

Set setExpirationHandler async function after initialization
Handler receives (ditto: Ditto, timeUntilExpiration: number)
Use Authenticator.DEVELOPMENT_PROVIDER for playground tokens
Replace auth.loginWithToken() with auth.login()
Remove authentication from identity configuration

Data Operations

Replace all store.collection('x') calls with store.execute() DQL
Use parameterized queries with :paramName — never string interpolation
Replace .upsert() with INSERT INTO ... DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE
Replace .update() closures with UPDATE SET DQL
Replace .remove() with DELETE FROM
Replace .evict() with EVICT FROM
Replace .subscribe() with sync.registerSubscription()
Replace store.write() with store.transaction()

Breaking Changes

Verification

Build compiles with zero errors
No deprecated API warnings
Observers update UI immediately
Authentication works before sync starts
WebAssembly module loads correctly
No memory leaks on navigation

Common Pitfalls

DQL_STRICT_MODE silent change: Not setting DQL_STRICT_MODE=true when your v4 app used the default. Objects that were replaced whole will now merge at field level — causes unexpected data merging.
Missing await init(): For web apps, init() is still required before any Ditto API calls. It loads the WebAssembly module. Forgetting it will cause runtime errors.
Missing await on Ditto.open(): Ditto.open() returns a Promise. Forgetting await means you’re working with a Promise, not a Ditto instance.
String interpolation in queries: Never `SELECT * FROM cars WHERE color = '${color}'`. Always use parameterized queries: store.execute("SELECT * FROM cars WHERE color = :color", { color }).
Counter initialization: Don’t put 0 in insert documents for counter fields. Counters are created on first PN_INCREMENT. Inserting 0 creates a REGISTER, not a COUNTER.
Missing ON ID CONFLICT: INSERT fails if document _id already exists without a conflict clause.
Not checking timeUntilExpiration in auth handler: Handler is called for both initial auth (0) and token refresh (> 0). Handle both cases.

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

JavaScript Web V4→V5 API Migration Guide

Overview

AI Agent Prompt

Ditto Instance Initialization

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

API Renames

`Store.write()` → `Store.transaction()`

Back Pressure (registerObserverWithSignalNext)

APIs Removed

New APIs in v5

Migration Checklist

Initialization

Observers

Authentication

Data Operations

Breaking Changes

Verification

Common Pitfalls

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Documentation Index

​Overview

​AI Agent Prompt

​Ditto Instance Initialization

​Additional Changes

​DQL Strict Mode Behavior Change

​Default Persistence Directory

​API Renames

​Store.write() → Store.transaction()

​Back Pressure (registerObserverWithSignalNext)

​APIs Removed

​New APIs in v5

​Migration Checklist

​Initialization

​Observers

​Authentication

​Data Operations

​Breaking Changes

​Verification

​Common Pitfalls

Overview

AI Agent Prompt

Ditto Instance Initialization

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

API Renames

`Store.write()` → `Store.transaction()`

Back Pressure (registerObserverWithSignalNext)

APIs Removed

New APIs in v5

Migration Checklist

Initialization

Observers

Authentication

Data Operations

Breaking Changes

Verification

Common Pitfalls