From 91b610ed58e4b589d91224a44f3efbea30168add Mon Sep 17 00:00:00 2001
From: Glauber Costa <glauber@turso.tech>
Date: Thu, 23 Apr 2026 16:37:48 -0400
Subject: [PATCH] Deprecate sync() across all client implementations

Add @deprecated JSDoc annotations to the Client interface and all
implementations (sqlite3, http, ws, wasm). The sqlite3 implementation
also emits a one-time console.warn() at runtime. Users are directed to
`@tursodatabase/sync` as a replacement. Learn more: https://tur.so/newsync

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/libsql-client-wasm/src/wasm.ts | 1 +
 packages/libsql-client/src/http.ts      | 1 +
 packages/libsql-client/src/sqlite3.ts   | 7 +++++++
 packages/libsql-client/src/ws.ts        | 1 +
 packages/libsql-core/src/api.ts         | 1 +
 5 files changed, 11 insertions(+)

diff --git a/packages/libsql-client-wasm/src/wasm.ts b/packages/libsql-client-wasm/src/wasm.ts
index 240244a..37f3946 100644
--- a/packages/libsql-client-wasm/src/wasm.ts
+++ b/packages/libsql-client-wasm/src/wasm.ts
@@ -212,6 +212,7 @@ export class Sqlite3Client implements Client {
         }
     }
 
+    /** @deprecated sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync */
     async sync(): Promise<Replicated> {
         throw new LibsqlError(
             "sync not supported in wasm mode",
diff --git a/packages/libsql-client/src/http.ts b/packages/libsql-client/src/http.ts
index 72aa2c5..c2822c7 100644
--- a/packages/libsql-client/src/http.ts
+++ b/packages/libsql-client/src/http.ts
@@ -274,6 +274,7 @@ export class HttpClient implements Client {
         });
     }
 
+    /** @deprecated sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync */
     sync(): Promise<Replicated> {
         throw new LibsqlError(
             "sync not supported in http mode",
diff --git a/packages/libsql-client/src/sqlite3.ts b/packages/libsql-client/src/sqlite3.ts
index b8a9ad8..7e1a478 100644
--- a/packages/libsql-client/src/sqlite3.ts
+++ b/packages/libsql-client/src/sqlite3.ts
@@ -26,6 +26,8 @@ import {
 
 export * from "@libsql/core/api";
 
+let _syncDeprecationWarned = false;
+
 export function createClient(config: Config): Client {
     return _createClient(expandConfig(config, true));
 }
@@ -255,7 +257,12 @@ export class Sqlite3Client implements Client {
         }
     }
 
+    /** @deprecated sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync */
     async sync(): Promise<Replicated> {
+        if (!_syncDeprecationWarned) {
+            console.warn("libSQL: sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync");
+            _syncDeprecationWarned = true;
+        }
         this.#checkNotClosed();
         const rep = await this.#getDb().sync();
         return {
diff --git a/packages/libsql-client/src/ws.ts b/packages/libsql-client/src/ws.ts
index e17fbb3..0acef6b 100644
--- a/packages/libsql-client/src/ws.ts
+++ b/packages/libsql-client/src/ws.ts
@@ -295,6 +295,7 @@ export class WsClient implements Client {
         });
     }
 
+    /** @deprecated sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync */
     sync(): Promise<Replicated> {
         throw new LibsqlError(
             "sync not supported in ws mode",
diff --git a/packages/libsql-core/src/api.ts b/packages/libsql-core/src/api.ts
index 471eb22..61db75f 100644
--- a/packages/libsql-core/src/api.ts
+++ b/packages/libsql-core/src/api.ts
@@ -234,6 +234,7 @@ export interface Client {
      */
     executeMultiple(sql: string): Promise<void>;
 
+    /** @deprecated sync() is deprecated and will be removed in a future release. Use `@tursodatabase/sync` instead. Learn more: https://tur.so/newsync */
     sync(): Promise<Replicated>;
 
     /** Close the client and release resources.