Node.js V4→V5 API Migration Guide

Overview

This guide covers the essential changes needed to migrate your Ditto JavaScript 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 app from v4 to v5.

Copy AI Migration Prompt (Click to Expand)

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

INITIALIZATION:
Replace `new Ditto(identity, path)` with `await Ditto.open(config)` using async/await.
- Create a `DittoConfig` with `databaseID` and a connect mode object
- `{ type: 'onlinePlayground', appID, token }` → `new DittoConfig(databaseID, { mode: 'server', url: 'REPLACE_ME_WITH_YOUR_URL' })`. Copy the whole URL from the Ditto Portal (Connect via SDK → **URL**); do not build it from the database ID.
- `{ 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 — `DittoConfig` handles the server URL directly. Note: `updateTransportConfig()` itself still exists in v5 for advanced transport configuration
- 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 to maintain v4 behavior

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
- The handler is called for both initial auth and token refresh — check `timeUntilExpiration`
- `auth.loginWithToken(token, provider)` → removed, use `auth.login(token, provider)` instead
- `auth.loginWithUsernameAndPassword(u, p, provider)` → removed, use `auth.login(token, provider)` instead
- New: `auth.observeStatus(callback)` lets you observe auth status changes

OBSERVERS:
The `registerObserver` API is callback-based with simplified generic type parameters.
- `StoreObserver<T, U>` → `StoreObserver` (single type param `<T>` optional)
- `observer.cancel()` is unchanged
- `StoreObserver.liveQueryID` property is removed
- IMPORTANT: Parameter order changed — `registerObserver(query, handler, queryArguments?)` — handler comes BEFORE args

COLLECTION API → DQL:
The entire Collection/Document API is removed. Replace all collection operations with DQL via `store.execute()`.
- `store.collection(name)` → removed. Use `store.execute('SELECT * FROM <name>')`
- `store.collections()` → removed
- `store.collectionNames()` → removed, no replacement
- `collection.findAll().exec()` → `store.execute('SELECT * FROM <name>')`
- `collection.find(query).exec()` → `store.execute('SELECT * FROM <name> WHERE ...')`
- `collection.findByID(id).exec()` → `store.execute('SELECT * FROM <name> WHERE _id = :id', { id })`
- `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 })`
- `collection.findByID(id).evict()` → `store.execute('EVICT 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('SELECT * FROM <name>', handler)`
- `liveQuery.stop()` → `observer.cancel()`
- The `LiveQuery` class, `LiveQueryEvent` type, and the entire callback shape are different:
  - v4 handler: `(docs, event) => { ... }` where docs is an array of Document objects
  - v5 handler: `(result) => { ... }` where result is a QueryResult with `.items` property containing plain objects

SUBSCRIPTIONS:
- `collection.findAll().subscribe()` → `sync.registerSubscription('SELECT * FROM <name>')`
- `Subscription` class → replaced by `SyncSubscription`
- `SyncSubscription<T>` generics removed → plain `SyncSubscription`
- `syncSubscription.queryArgumentsCBOR` → renamed to `syncSubscription.queryArgumentsCBORData`

TRANSACTIONS:
- `store.write(callback)` → `store.transaction(scope, options?)`
- v4: `txn.scoped('name').upsert(value)` → v5: `txn.execute('INSERT INTO <name> DOCUMENTS (:doc)', { doc: value })`
- `WriteTransaction` / `WriteTransactionCollection` / `WriteTransactionResult` classes are all removed

PRESENCE:
- `peer.peerKeyString` → `peer.peerKey` (peerKey is now a string directly, not Uint8Array)
- `peer.peerKey` (was Uint8Array) → `peer.peerKey` (now string)
- `peer.address` → removed (Address type removed entirely)
- `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- `peer.isCompatible` → new optional boolean property
- `connection.peerKeyString1` / `peerKeyString2` → `connection.peer1` / `connection.peer2` (now strings)
- `connection.approximateDistanceInMeters` → removed
- `connectionRequest.peerKeyString` → `connectionRequest.peerKey`
- `ditto.observePeers(callback)` → `ditto.presence.observe(callback)`
- `Address` type / `addressToString()` → removed
- `PresenceManager` class → removed

ATTACHMENTS:
- `AttachmentToken` class → replaced by plain objects `{ id: string, len: number | bigint, metadata }`
- `TypedAttachmentToken` → renamed to `TypedAttachmentTokenV1` (marked `@internal`)
- `Attachment.len` type: `number | BigInt` → `number | bigint` (lowercase)
- `fetchAttachment(AttachmentToken, handler)` → `fetchAttachment({ id, len, metadata }, handler)` (plain object only)
- `AttachmentFetcher.attachment` promise: v4 could resolve to `null` on deletion → v5 rejects with `DittoError` instead

DITTO CLASS:
- `new Ditto(identity, path)` → `await Ditto.open(config)` or `Ditto.openSync(config)` (constructor private)
- `ditto.appID` → `ditto.config.databaseID`
- `ditto.identity` → `ditto.config`
- `ditto.path` / `ditto.persistenceDirectory` → `ditto.absolutePersistenceDirectory`
- `ditto.siteID` → removed
- `ditto.sdkVersion` → use `Ditto.VERSION` (static property)
- `ditto.runGarbageCollection()` → removed (automatic in v5)
- `ditto.disableSyncWithV3()` → removed (v3 protocol dropped)
- `ditto.observePeers(callback)` → `ditto.presence.observe(callback)`

LOGGER:
- `Logger.setLogFile(path)` → removed
- `Logger.setLogFileURL(url)` → removed
- `Logger.emojiLogLevelHeadingsEnabled` → removed
- `Logger.exportToFile(path)` — still available
- `Logger.enabled` / `Logger.minimumLogLevel` / `Logger.setCustomLogCallback()` — still available

ERRORS:
- `DittoError(code, message, context)` → `DittoError(code, message)` — context parameter removed
- `DittoError.context` property → removed
- Error code `'sdk/unsupported'` → `'unsupported'`
- Error code `'internal/unknown-error'` → `'unknown'`

TRANSPORT CONFIG:
- `TransportConfigListenHTTP.staticContentPath` → removed
- Default `websocketSync` changed from `true` to `false` — explicitly set `true` if your app needs it

TYPES:
- `BigInt` → `bigint` (lowercase) across the entire SDK
- `QueryResult.mutatedDocumentIDs()` → removed, use `QueryResult.mutatedDocumentIDsV2()` which returns `any[]`
- `StoreObserver<T, U>` → `StoreObserver` (no generics)
- `SyncSubscription<T>` → `SyncSubscription` (no generics)

REMOVED CLASSES (no replacement):
- `Document` / `MutableDocument` — DQL returns plain objects
- `DocumentID` / `DocumentPath` / `MutableDocumentPath`
- `Counter` / `Register` CRDT types
- `Collection` / `PendingCursorOperation` / `PendingIDSpecificOperation` / `PendingCollectionsOperation`
- `LiveQuery` / `LiveQueryEvent`
- `WriteTransaction` / `WriteTransactionCollection` / `WriteTransactionResult`
- `UpdateResult` / `UpdateResultsMap`
- `PresenceManager`

NEW APIs:
- `Ditto.open(config): Promise<Ditto>` — async factory
- `Ditto.openSync(config): Ditto` — sync factory
- `DittoConfig(id, connect, persistenceDir?)` — replaces Identity system
- `DittoConfig.DEFAULT_DATABASE_ID` / `.default` / `.copy()`
- `DittoConfigConnectServer` — `{ mode: 'server', url: string }`
- `DittoConfigConnectSmallPeersOnly` — `{ mode: 'smallPeersOnly', privateKey?: string }`
- `auth.login(token, provider): Promise<LoginResult>` — returns `{ clientInfo, error }`
- `Authenticator.DEVELOPMENT_PROVIDER` — static constant for dev provider
- `auth.observeStatus(callback): Observer` — observe auth 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`

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

await init();

const ditto = new Ditto(
  {
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'REPLACE_ME_WITH_YOUR_URL',
  },
  '/data/ditto'
)

ditto.updateTransportConfig((config) => {
  config.connect.websocketURLs.add('wss://...')
})
ditto.disableSyncWithV3()
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")
ditto.startSync()

// Presence
ditto.observePeers((peers) => {
  peers.forEach((peer) => {
    console.log(peer.peerKeyString, peer.isConnectedToDittoCloud)
  })
})

// Cleanup
ditto.stopSync()
await ditto.close()
```

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

const databaseID = 'your-database-id'
const config = new DittoConfig(databaseID, {
  mode: 'server',
  url: 'REPLACE_ME_WITH_YOUR_URL',
})

const ditto = await Ditto.open(config)

await ditto.auth.setExpirationHandler(async (ditto, timeUntilExpiration) => {
  try {
    const result = await ditto.auth.login('your-token', Authenticator.DEVELOPMENT_PROVIDER)
    if (result.error) {
      console.error(`Auth failed: ${result.error}, time until expiration: ${timeUntilExpiration}`)
    }
  } catch (error) {
    console.error(`Auth exception: ${error}`)
  }
})

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = true")

ditto.sync.start()

// Store observer (replaces live query)
const observer = ditto.store.registerObserver('SELECT * FROM cars', (result) => {
  updateUI(result.items)
})

// Sync subscription (replaces collection subscription)
const subscription = ditto.sync.registerSubscription('SELECT * FROM cars')

// Presence
ditto.presence.observe((graph) => {
  const allPeers = [graph.localPeer, ...graph.remotePeers]
  allPeers.forEach((peer) => {
    console.log(peer.peerKey, peer.isConnectedToDittoServer)
  })
})

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

CHECKLIST:
- Replace `new Ditto(identity, path)` with `await Ditto.open(new DittoConfig(...))`
- Add `await` for initialization — `Ditto.open()` is async
- Create `DittoConfig` with `databaseID` and connect mode (`server` or `smallPeersOnly`)
- Set `DQL_STRICT_MODE=true` BEFORE `sync.start()` if maintaining v4 strict behavior
- Set up `auth.setExpirationHandler()` and use `auth.login()` for authentication
- Replace `ditto.startSync()` / `stopSync()` with `ditto.sync.start()` / `stop()`
- Replace `ditto.isSyncActive` with `ditto.sync.isActive`
- Replace all `store.collection('x')` calls with `store.execute()` DQL queries
- Use parameterized DQL queries (`:paramName`) — never string interpolation
- Replace `collection.upsert()` with `INSERT INTO ... DOCUMENTS (:doc)`
- Replace `collection.findByID(id).update()` with `UPDATE ... SET ... WHERE _id = :id`
- Replace `collection.findByID(id).remove()` with `DELETE FROM ... WHERE _id = :id`
- Replace `collection.findAll().observeLocal(handler)` with `store.registerObserver(query, handler)`
- Note: v5 registerObserver parameter order is (query, handler, args?) — handler before args
- Replace `liveQuery.stop()` with `observer.cancel()`
- Replace `collection.findAll().subscribe()` with `sync.registerSubscription(query)`
- Replace `store.write()` with `store.transaction()`
- Replace `auth.loginWithToken()` with `auth.login()`
- Remove `AuthenticationHandler` interface usage
- Remove `disableSyncWithV3()` calls
- Remove `updateTransportConfig` workaround patterns for websocket URLs (method still exists for advanced use)
- Update `peer.peerKeyString` → `peer.peerKey`
- Update `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- Update `connection.peerKeyString1`/`peerKeyString2` → `connection.peer1`/`peer2`
- Update `connectionRequest.peerKeyString` → `connectionRequest.peerKey`
- Replace `ditto.observePeers()` with `ditto.presence.observe()`
- Update `AttachmentToken` class usage to plain `{ id, len, metadata }` objects
- Update `BigInt` type annotations to lowercase `bigint`
- Remove `Logger.setLogFile()` / `Logger.emojiLogLevelHeadingsEnabled` calls
- Remove `DittoError.context` usage
- Set `websocketSync = true` explicitly if your app relied on the v4 default of `true`
- Remove generic type parameters from `StoreObserver<T, U>` and `SyncSubscription<T>`

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'
await init()

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

// 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();

// Everything mixed together
const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'REPLACE_ME_WITH_YOUR_URL'
});

ditto.updateTransportConfig((config) => {
    config.connect.websocketURLs.add('wss://...');
});
ditto.store.execute('ALTER SYSTEM SET DQL_STRICT_MODE = false');
ditto.disableSyncWithV3();

ditto.startSync();

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

Initialization Migration Steps

Replace Initialization

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

const config = new DittoConfig(
    "your-database-id",
    {
        mode: 'server',
        url: "REPLACE_ME_WITH_YOUR_URL"
    }
);

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

const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'REPLACE_ME_WITH_YOUR_URL'
});
ditto.startSync();

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}`);
        }
});

// Auth mixed with identity
const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: '...',
    token: '...',  // Token in identity
    customAuthURL: '...'
});

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: "REPLACE_ME_WITH_YOUR_URL"
    }
);
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: "REPLACE_ME_WITH_YOUR_URL"
    }
);
const ditto = await Ditto.open(config);

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

const ditto = new Ditto({
    type: 'onlinePlayground',
    appID: 'your-app-id',
    token: 'your-token',
    customAuthURL: 'REPLACE_ME_WITH_YOUR_URL'
});

// You explicitly set this in v4
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false");

ditto.startSync();

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: 'REPLACE_ME_WITH_YOUR_URL'
});

// 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 Node.js 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: "REPLACE_ME_WITH_YOUR_URL"
    },
    "/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)` — no longer accepts `AttachmentToken` instances
`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` export	Removed — use `ASC`/`DESC` in DQL `ORDER BY`
`WriteStrategy` export	Removed — use `ON ID CONFLICT DO ...` in DQL
`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' } }
    );
});

Attachment Token Change

// v4 — AttachmentToken instance
const token: AttachmentToken = doc.attachment;
const result = await ditto.store.fetchAttachment(token, (event) => { });

// v5 — plain object from query result
const token = item.value['photo']; // plain object, not AttachmentToken
const result = await ditto.store.fetchAttachment(token, (event) => { });

Observer Type Parameter

// v4 — two type params
const observer = ditto.store.registerObserver<Car, CarExtra>(query, {}, handler);

// v5 — one type param, handler before args
const observer = ditto.store.registerObserver<Car>(query, handler, {});

Parameter order changed: In v5, registerObserver takes (query, handler, queryArguments?) — the handler comes before the query arguments.

DQL Query Arguments (adds bigint support)

// v4
import { QueryArguments } from '@dittolive/ditto';
const args: QueryArguments = { color: 'blue', count: 42 };

// v5 — renamed, adds bigint
import { DQLQueryArguments } from '@dittolive/ditto';
const args: DQLQueryArguments = { color: 'blue', count: 42n }; // bigint supported

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.

// 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

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` / `PendingIDSpecificOperation`	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 `ORDER BY ASC/DESC` and `ON ID CONFLICT DO ...`
`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
`TransportConfigListenHTTP.staticContentPath`	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
DittoConfig.DEFAULT_DATABASE_ID / .default / .copy() — config helpers
{ 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[] (replaces removed mutatedDocumentIDs())

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
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 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.
Observer parameter order: v5 registerObserver(query, handler, args?) puts the handler before the query arguments — different from v4 where args came before handler.
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

Node.js 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()`

Attachment Token Change

Observer Type Parameter

DQL Query Arguments (adds bigint support)

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()

​Attachment Token Change

​Observer Type Parameter

​DQL Query Arguments (adds bigint support)

​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()`

Attachment Token Change

Observer Type Parameter

DQL Query Arguments (adds bigint support)

Back Pressure (registerObserverWithSignalNext)

APIs Removed

New APIs in v5

Migration Checklist

Initialization

Observers

Authentication

Data Operations

Breaking Changes

Verification

Common Pitfalls