Version 1.0

Description - Quick reference for all API changes in @couchbase/couchbase-lite-react-native version 1.0
Related Content - Release Notes | Using Logs

AT A GLANCE

Version 1.0 introduces several API changes:

1. Log Sink API - Replaces Database.setLogLevel() with LogSinks API
2. Listener Token API - New token.remove() replaces removeChangeListener()
3. New ReplicatorConfiguration - Collections passed in constructor

Breaking Changes

Listener Token Return Type (TypeScript)

We changed all addChangeListener functions to return a ListenerToken instead of a string, enabling the new token.remove() API and aligning with other platforms.

This is a breaking change only for TypeScript code that explicitly typed the token as string. JavaScript users and untyped TypeScript won't be affected.

TypeScript Migration Example:

// BEFORE (TypeScript compilation error in 1.0)
const token: string = await collection.addChangeListener(listener);

// AFTER
const token: ListenerToken = await collection.addChangeListener(listener);
token.remove();

The existing removeChangeListener(token) methods remain available for backward compatibility but are deprecated.

---

Deprecated APIs

1. Logging API

The old Database.setLogLevel() API is deprecated and replaced with the new LogSinks API.

OLD (Deprecated):

// This API is deprecated
await db.setLogLevel(LogDomain.ALL, LogLevel.VERBOSE);
await Database.setLogLevel(LogDomain.DATABASE, LogLevel.INFO);

NEW (Required in 1.0):

import { LogSinks, LogLevel, LogDomain } from '@couchbase/couchbase-lite-react-native';

await LogSinks.setConsole({
  level: LogLevel.VERBOSE,
  domains: [LogDomain.ALL]
});

Important

The old and new logging APIs cannot be used in tandem. If you are migrating to version 1.0, you must replace all instances of Database.setLogLevel() with LogSinks.setConsole().

Migration: Search your code for setLogLevel and replace with LogSinks.setConsole.

See: Using Logs

---

2. ReplicatorConfiguration API

The old constructor pattern using addCollection() is deprecated.

OLD (Deprecated):

const config = new ReplicatorConfiguration(endpoint);
config.addCollection(collection);
const replicator = await Replicator.create(config);

NEW (Recommended in 1.0):

import { CollectionConfiguration } from '@couchbase/couchbase-lite-react-native';

const collectionConfig = new CollectionConfiguration(collection);
const config = new ReplicatorConfiguration([collectionConfig], endpoint);
const replicator = await Replicator.create(config);

This method is deprecated. It remains available for backward compatibility, but new applications should use the new constructor pattern. Existing applications are strongly encouraged to migrate.

See: Remote Sync

---

3. Listener Removal Methods (Deprecated)

OLD (Deprecated in 1.0):

await collection.removeChangeListener(token);
await query.removeChangeListener(token);
await replicator.removeChangeListener(token);

NEW (Recommended in 1.0):

await token.remove();

This method is deprecated. It remains available for backward compatibility, but new applications should use token.remove(). Existing applications are strongly encouraged to migrate.

---

New Features in 1.0

1. Three Log Sink Types

// Console Sink - for development
await LogSinks.setConsole({ 
  level: LogLevel.VERBOSE, 
  domains: [LogDomain.ALL] 
});

// File Sink - for production logging
await LogSinks.setFile({ 
  level: LogLevel.WARNING, 
  directory: logDir,
  maxKeptFiles: 5,
  maxFileSize: 1024 * 1024,
  usePlaintext: true
});

// Custom Sink - for analytics
await LogSinks.setCustom({ 
  level: LogLevel.ERROR, 
  domains: [LogDomain.ALL],
  callback: (level, domain, message) => {
    Analytics.log({ level, domain, message });
  }
});

See: Using Logs

---

2. All 5 Change Listener Types

Now fully documented with examples:

// 1. Collection Change Listener
const token1 = await collection.addChangeListener((change) => {
  console.log('Changed docs:', change.documentIDs); // Capital IDs!
});

// 2. Document Change Listener
const token2 = await collection.addDocumentChangeListener('doc-id', (change) => {
  console.log('Doc changed:', change.documentId); // Lowercase Id!
});

// 3. Query Change Listener (Live Query)
const token3 = await query.addChangeListener((change) => {
  console.log('Results:', change.results);
});

// 4. Replicator Status Listener
const token4 = await replicator.addChangeListener((change) => {
  const status = change.status;
  console.log('Level:', status.getActivityLevel());
  console.log('Progress:', status.getProgress().getCompleted());
});

// 5. Replicator Document Listener
const token5 = await replicator.addDocumentChangeListener((change) => {
  console.log('Direction:', change.isPush ? 'Push' : 'Pull');
});

// All use same removal pattern
await token1.remove();

See: Scopes and Collections | Documents | Live Queries | Remote Sync

---

3. Collection.fullName()

const fullName = await collection.fullName();
console.log(fullName); // "production.users"

See: Scopes and Collections

---

Quick Migration Steps

Step 1: Update Logging (Required)

Find and replace in your code:

# Search for old API
grep -r "setLogLevel" .

# Replace with LogSinks.setConsole

Step 2: Update ReplicatorConfiguration (Recommended)

// Old (deprecated)
const config = new ReplicatorConfiguration(endpoint);
config.addCollection(collection);

// New (recommended)
const collectionConfig = new CollectionConfiguration(collection);
const config = new ReplicatorConfiguration([collectionConfig], endpoint);

Step 3: Update Listener Cleanup (Recommended)

// Old (deprecated)
await collection.removeChangeListener(token);

// New (recommended)
await token.remove();

---

Important Property Names

Listener Type	Property	Correct	Wrong
Collection Change	Document IDs	documentIDs	documentIds
Document Change	Document ID	documentId	documentID
Collection Change	Database	collection.database	database
Document Change	Database	database	N/A
Replicator Progress	Completed	getCompleted()	completed
Replicator Progress	Total	getTotal()	total

---

Need Help?

• Log Sink Examples: Using Logs
• Replication Setup: Remote Sync
• Full Release Notes: Version 1.0