Skip to content

v1.md

Latest commit

 

History

History
259 lines (184 loc) · 7.24 KB

v1.md

File metadata and controls

259 lines (184 loc) · 7.24 KB
Raw
id migration-guide-v1
sidebar_position 1

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

:::important 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]
});

:::caution 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?