🔄 easy_rest_sync

A lightweight, beginner-friendly Flutter package for building offline-first applications that synchronize local data with a server through REST APIs and provide a package-owned reactive streaming system.

Your application communicates only with the clean EasyRestSync API. Local persistence, pending operations, retry handling, cursor tracking, synchronization, reactive lists, single-record streams, sync state, event broadcasting, and REST-based live polling are managed internally.

📦 Pub.dev: https://pub.dev/packages/easy_rest_sync

Your backend must provide compatible push and pull REST endpoints.

---

✅ Summary of Everything Included in This Package

• ✔️ Offline-first local data storage
• ✔️ REST API-based push and pull synchronization
• ✔️ Automatic local create and update handling
• ✔️ Offline delete and server delete synchronization
• ✔️ Pending operation queue
• ✔️ Automatic or manual synchronization
• ✔️ Cursor-based incremental data pulling
• ✔️ Batch push and pull support
• ✔️ Server-wins and client-wins conflict strategies
• ✔️ Failed operation retry support
• ✔️ Reactive list streaming with watchList()
• ✔️ Single-record streaming with watchOne()
• ✔️ Pending-operation count streaming
• ✔️ Rich synchronization state streaming
• ✔️ Global package event stream
• ✔️ REST-based live polling system
• ✔️ Start, pause, resume, and stop streaming controls
• ✔️ App lifecycle-aware streaming
• ✔️ Stream update debouncing
• ✔️ Single-record and list queries
• ✔️ Local filtering, sorting, and pagination
• ✔️ Bearer token provider support
• ✔️ Custom request headers
• ✔️ Multiple entity support
• ✔️ Sync status stream
• ✔️ Full Flutter example app
• ✔️ Pub.dev-ready formatting

---

⭐ Features

• 📱 Read and write data without an internet connection
• 🔄 Synchronize local changes with REST APIs
• 📥 Pull only new server changes using a cursor
• 📤 Push pending local operations in batches
• 💾 Internal local database management
• 🕵️ No direct local database code required in the application
• ⚡ Reactive watchList() support
• 👁 Watch one record using watchOne()
• 🔢 Watch pending operations using watchPendingCount()
• 📊 Watch detailed sync and streaming state using watchState()
• 📢 Listen to package-wide events using events
• 🌐 Run automatic REST-based live synchronization
• ⏸ Pause and resume live synchronization
• 📲 Pause streaming automatically when the app is in the background
• 🔍 Filter and sort local records
• 📄 Local pagination support
• 🧩 Register multiple model types as sync entities
• 🔐 Dynamic authentication token support
• 🧯 Retry failed operations
• ⚔️ Configurable conflict handling
• 📈 Synchronization result and status reporting
• 🧪 Complete example application included

---

🏗 How It Works

Flutter Application
       ↓
EasyRestSync Public API
       ↓
Internal Local Storage
       ↓
Pending Operation Queue
       ↓
REST Push / Pull API
       ↓
Server Database

The application always reads from and writes to the package API.

UI → EasyRestSync → Local Data

When synchronization runs:

Pending Local Changes → Push API → Server
Server Changes → Pull API → Local Data → UI

The package streaming layer works like this:

Local Save / Delete
       ↓
EasyRestSync Event System
       ↓
watchList / watchOne / watchState / events
       ↓
Flutter UI Rebuild

Remote live updates work through configurable REST polling:

Streaming Interval
       ↓
Push Pending Operations
       ↓
Pull New Server Changes
       ↓
Update Local Data
       ↓
Notify Streams
       ↓
Flutter UI Rebuild

Because the UI reads local data, previously synchronized records remain available when the device is offline.

---

⚠️ Important Backend Requirement

easy_rest_sync is a client-side synchronization engine. It does not automatically create your backend endpoints or database change log.

Your backend must provide:

• A push endpoint for receiving local create, update, and delete operations
• A pull endpoint for returning server-side changes after a cursor
• A unique operation result for every pushed operation
• A server version for conflict detection
• An incremental cursor for pull synchronization
• Authentication and authorization suitable for your application
• Idempotent operation processing using operationId
• Stable cursor ordering for pull responses

The backend can use any database or server technology, including:

• Oracle Database and ORDS
• PostgreSQL
• MySQL
• SQL Server
• MongoDB
• Node.js
• Laravel
• Django
• ASP.NET
• Spring Boot

The built-in live streaming system uses repeated REST synchronization. WebSocket or Server-Sent Events are not required.

---

📦 Installation

Add the package to your pubspec.yaml:

dependencies:
  easy_rest_sync: ^0.0.2

Then run:

flutter pub get

For local package development:

dependencies:
  easy_rest_sync:
    path: ../

Import the package:

import 'package:easy_rest_sync/easy_rest_sync.dart';

---

🚀 Basic Initialization

Create and initialize EasyRestSync before runApp():

late final EasyRestSync easySync;

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  easySync = EasyRestSync(
    config: EasyRestSyncConfig(
      baseUrl: 'https://your-domain.com/api',
      pushEndpoint: '/sync/push',
      pullEndpoint: '/sync/pull',
      scope: 'user_506618',
      autoSyncOnWrite: true,
      syncOnStart: true,

      streamDebounce: const Duration(milliseconds: 50),

      streaming: const EasySyncStreamingConfig(
        enabled: true,
        interval: Duration(seconds: 10),
        syncImmediately: true,
        pauseWhenAppInBackground: true,
        continueAfterError: true,
        maxConsecutiveFailures: 0,
      ),

      tokenProvider: () async {
        return 'YOUR_ACCESS_TOKEN';
      },

      conflictStrategy: EasySyncConflictStrategy.serverWins,
    ),
  );

  easySync.registerEntity<Product>(
    EasySyncEntity<Product>(
      name: 'products',
      idSelector: (product) => product.id,
      toJson: (product) => product.toJson(),
      fromJson: Product.fromJson,
    ),
  );

  await easySync.initialize();

  runApp(const MyApp());
}

Register every entity before calling methods such as save(), get(), getList(), watchList(), or watchOne().

---

🧱 Create a Model

Every sync entity needs:

• A unique string ID
• A toJson() method
• A fromJson() factory

class Product {
  final String id;
  final String itemCode;
  final String itemName;
  final double quantity;

  const Product({
    required this.id,
    required this.itemCode,
    required this.itemName,
    required this.quantity,
  });

  factory Product.fromJson(Map<String, dynamic> json) {
    return Product(
      id: json['id']?.toString() ?? '',
      itemCode: json['itemCode']?.toString() ?? '',
      itemName: json['itemName']?.toString() ?? '',
      quantity:
          double.tryParse(json['quantity']?.toString() ?? '0') ?? 0,
    );
  }

  Map<String, dynamic> toJson() {
    return <String, dynamic>{
      'id': id,
      'itemCode': itemCode,
      'itemName': itemName,
      'quantity': quantity,
    };
  }
}

---

🧩 Register an Entity

easySync.registerEntity<Product>(
  EasySyncEntity<Product>(
    name: 'products',
    idSelector: (product) => product.id,
    toJson: (product) => product.toJson(),
    fromJson: Product.fromJson,
  ),
);

The entity name must match the entity value used by your push and pull APIs.

---

💾 Save or Update Data

The same save() method handles both create and update operations.

final product = Product(
  id: '101',
  itemCode: '34494',
  itemName: 'Plastic Chair',
  quantity: 10,
);

await easySync.save<Product>(
  entity: 'products',
  data: product,
);

The package will:

Save the record locally
       ↓
Create or update a pending sync operation
       ↓
Notify reactive streams
       ↓
Synchronize automatically when enabled

Control synchronization for a specific save:

await easySync.save<Product>(
  entity: 'products',
  data: product,
  syncNow: false,
);

Force immediate synchronization:

await easySync.save<Product>(
  entity: 'products',
  data: product,
  syncNow: true,
);

---

🔎 Get a Single Record

final product = await easySync.get<Product>(
  entity: 'products',
  id: '101',
);

if (product != null) {
  debugPrint(product.itemName);
}

Deleted or unavailable records return null.

---

📋 Get All Records

final products = await easySync.getList<Product>(
  entity: 'products',
);

---

⚡ Watch a Reactive List

watchList() emits the current list immediately and emits a new list whenever records for that entity change.

Changes may come from:

• Local save()
• Local delete()
• Remote pull synchronization
• Conflict resolution
• Server acknowledgement

StreamBuilder<List<Product>>(
  stream: easySync.watchList<Product>(
    entity: 'products',
  ),
  builder: (context, snapshot) {
    final products = snapshot.data ?? <Product>[];

    if (products.isEmpty) {
      return const Center(
        child: Text('No product found.'),
      );
    }

    return ListView.builder(
      itemCount: products.length,
      itemBuilder: (context, index) {
        final product = products[index];

        return ListTile(
          title: Text(product.itemName),
          subtitle: Text(product.itemCode),
          trailing: Text(product.quantity.toString()),
        );
      },
    );
  },
);

The application does not need to import or access the package's internal database.

---

👁 Watch a Single Record

Use watchOne() when only one record needs to update reactively.

StreamBuilder<Product?>(
  stream: easySync.watchOne<Product>(
    entity: 'products',
    id: '101',
  ),
  builder: (context, snapshot) {
    final product = snapshot.data;

    if (product == null) {
      return const Text('Product not found.');
    }

    return ListTile(
      title: Text(product.itemName),
      subtitle: Text(product.itemCode),
      trailing: Text(product.quantity.toString()),
    );
  },
);

The stream emits null when the record is deleted.

---

🔢 Watch Pending Operation Count

StreamBuilder<int>(
  stream: easySync.watchPendingCount(),
  builder: (context, snapshot) {
    final pending = snapshot.data ?? 0;

    return Text('Pending operations: $pending');
  },
);

This is useful for:

• Offline indicators
• Unsynchronized data badges
• Sync buttons
• Debugging pending writes

---

📊 Watch Detailed Sync State

StreamBuilder<EasySyncState>(
  stream: easySync.watchState(),
  initialData: easySync.state,
  builder: (context, snapshot) {
    final state = snapshot.data ?? easySync.state;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: <Widget>[
        Text('Sync status: ${state.status.name}'),
        Text('Streaming: ${state.streamingStatus.name}'),
        Text('Pending: ${state.pendingOperations}'),
        Text('Pushed: ${state.pushedCount}'),
        Text('Pulled: ${state.pulledCount}'),
        Text('Conflicts: ${state.conflictCount}'),
      ],
    );
  },
);

You can also use:

easySync.stateStream

Useful state properties:

easySync.state.isSyncing
easySync.state.isStreaming
easySync.state.lastSuccessfulSync
easySync.state.lastError

---

📢 Listen to Global Package Events

The events stream emits package-wide events.

final subscription = easySync.events.listen((event) {
  if (event.isRecordChange) {
    debugPrint(
      '${event.origin?.name}: '
      '${event.entity}/${event.recordId} '
      '${event.recordChangeType?.name}',
    );
  } else {
    debugPrint(event.type.name);
  }
});

Cancel the subscription when it is no longer needed:

await subscription.cancel();

Available event types include:

EasySyncEventType.initialized
EasySyncEventType.recordChanged
EasySyncEventType.pendingOperationsChanged
EasySyncEventType.syncStarted
EasySyncEventType.syncCompleted
EasySyncEventType.syncFailed
EasySyncEventType.streamingStarted
EasySyncEventType.streamingPaused
EasySyncEventType.streamingResumed
EasySyncEventType.streamingStopped
EasySyncEventType.streamingFailed

Record change types:

EasySyncRecordChangeType.created
EasySyncRecordChangeType.updated
EasySyncRecordChangeType.deleted

Change origins:

EasySyncChangeOrigin.local
EasySyncChangeOrigin.remote
EasySyncChangeOrigin.conflict
EasySyncChangeOrigin.serverAcknowledgement

---

🔍 Filter Local Data

final availableProducts = await easySync.getList<Product>(
  entity: 'products',
  where: (product) => product.quantity > 0,
);

Reactive filtering:

final stream = easySync.watchList<Product>(
  entity: 'products',
  where: (product) => product.itemCode.startsWith('34'),
);

---

↕️ Sort Local Data

final products = await easySync.getList<Product>(
  entity: 'products',
  sort: (a, b) => a.itemName.compareTo(b.itemName),
);

Reactive sorting:

final stream = easySync.watchList<Product>(
  entity: 'products',
  sort: (a, b) => b.quantity.compareTo(a.quantity),
);

---

📄 Local Pagination

Both page and pageSize must be greater than zero.

final firstPage = await easySync.getList<Product>(
  entity: 'products',
  page: 1,
  pageSize: 20,
);

Reactive pagination:

final stream = easySync.watchList<Product>(
  entity: 'products',
  page: 1,
  pageSize: 20,
);

Filtering and sorting are applied before local pagination.

---

🗑 Delete Data

await easySync.delete(
  entity: 'products',
  id: '101',
);

Delete locally without immediate synchronization:

await easySync.delete(
  entity: 'products',
  id: '101',
  syncNow: false,
);

The package:

Hides the record from local queries
       ↓
Creates or updates a pending delete operation
       ↓
Notifies list and record streams
       ↓
Sends the delete during synchronization

---

🌐 REST-Based Live Streaming

Easy REST Sync includes a package-owned live streaming system that works with normal REST APIs.

It periodically performs:

Push Pending Local Operations
       ↓
Pull New Server Changes
       ↓
Apply Changes Locally
       ↓
Notify Reactive Streams

This is configurable interval-based synchronization.

It is not a permanent WebSocket connection. It uses the package's standard REST push and pull endpoints.

---

⚙️ Enable Streaming in Configuration

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',

  streaming: const EasySyncStreamingConfig(
    enabled: true,
    interval: Duration(seconds: 10),
    syncImmediately: true,
    pauseWhenAppInBackground: true,
    continueAfterError: true,
    maxConsecutiveFailures: 0,
  ),
)

Streaming configuration options:

Property	Description
enabled	Automatically start streaming during initialization
interval	Time between REST synchronization ticks
syncImmediately	Synchronize immediately when streaming starts
pauseWhenAppInBackground	Pause polling while the app is backgrounded
continueAfterError	Continue polling after synchronization errors
maxConsecutiveFailures	Stop after repeated failures; 0 means unlimited

Choose a sensible interval based on:

• Server capacity
• Data freshness requirements
• Mobile data usage
• Battery consumption
• Expected number of active clients

---

▶️ Start Streaming Manually

Use the configuration already supplied to EasyRestSyncConfig:

await easySync.startStreaming();

Or provide a custom streaming configuration:

await easySync.startStreaming(
  config: const EasySyncStreamingConfig(
    interval: Duration(seconds: 10),
    syncImmediately: true,
    pauseWhenAppInBackground: true,
    continueAfterError: true,
  ),
);

---

⏸ Pause Streaming

await easySync.pauseStreaming();

This pauses future streaming ticks. It does not remove local records or pending operations.

---

▶️ Resume Streaming

Resume and synchronize immediately:

await easySync.resumeStreaming(
  syncNow: true,
);

Resume without immediate synchronization:

await easySync.resumeStreaming(
  syncNow: false,
);

---

⏹ Stop Streaming

await easySync.stopStreaming();

This stops the timer and removes the lifecycle observer used by the streaming system.

---

📲 Application Lifecycle Streaming

When enabled:

pauseWhenAppInBackground: true

The package behaves like this:

Application paused, inactive, detached, or hidden
       ↓
Streaming pauses

Application resumed
       ↓
Streaming resumes
       ↓
Immediate synchronization runs

This helps reduce unnecessary network requests while the application is not active.

---

🧘 Stream Debouncing

Large pull responses may update many records at once.

Use streamDebounce to combine many rapid changes into fewer UI refreshes:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  streamDebounce: const Duration(milliseconds: 50),
)

Example:

100 Remote Record Changes
       ↓
50 ms Debounce Window
       ↓
One List Stream Refresh

A value between 30 and 100 milliseconds is suitable for many applications.

---

🔄 Manual Synchronization

final result = await easySync.sync();

if (result.isSuccess) {
  debugPrint('Pushed: ${result.pushedCount}');
  debugPrint('Pulled: ${result.pulledCount}');
  debugPrint('Conflicts: ${result.conflictCount}');
  debugPrint('Pending: ${result.pendingCount}');
} else {
  debugPrint('Sync failed: ${result.message}');
}

Calling sync() while another synchronization is active returns the active synchronization result instead of starting a duplicate process.

---

📊 Listen to Basic Sync Status

StreamBuilder<EasySyncStatus>(
  stream: easySync.statusStream,
  initialData: easySync.status,
  builder: (context, snapshot) {
    final status =
        snapshot.data ?? EasySyncStatus.uninitialized;

    return Text(status.name);
  },
);

Available statuses:

EasySyncStatus.uninitialized
EasySyncStatus.idle
EasySyncStatus.pushing
EasySyncStatus.pulling
EasySyncStatus.completed
EasySyncStatus.offline
EasySyncStatus.failed

Streaming statuses:

EasySyncStreamingStatus.stopped
EasySyncStreamingStatus.starting
EasySyncStreamingStatus.running
EasySyncStreamingStatus.paused
EasySyncStreamingStatus.failed

---

📤 Automatic Sync on Save

Enable automatic synchronization after local writes:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  autoSyncOnWrite: true,
)

Disable it when you want only manual or streaming-based synchronization:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  autoSyncOnWrite: false,
)

A method-level syncNow value overrides autoSyncOnWrite.

---

▶️ Sync on Application Start

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  syncOnStart: true,
)

When streaming is enabled with syncImmediately: true, streaming performs the initial synchronization.

---

🔐 Authentication Token

Use tokenProvider to provide the latest access token for every request:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  tokenProvider: () async {
    return await authRepository.getAccessToken();
  },
)

When a non-empty token is returned, the package sends:

Authorization: Bearer YOUR_ACCESS_TOKEN

Do not hardcode production secrets in the application.

---

🧾 Custom Request Headers

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  headers: const <String, dynamic>{
    'X-App-Version': '1.0.0',
    'X-Platform': 'mobile',
  },
)

The token provider adds Authorization when that header is not already supplied.

---

👤 Client ID and Scope

A client ID identifies the current installation or synchronization client.

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  clientId: 'device-506618-01',
)

When clientId is not provided, the package creates and stores one automatically.

Use scope to isolate data by user, company, organization, branch, tenant, or workspace:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  scope: 'user_506618',
)

The selected scope is included in push and pull requests.

---

⚔️ Conflict Strategy

Server Wins

conflictStrategy: EasySyncConflictStrategy.serverWins,

When a conflict occurs, the server version replaces the conflicting local version.

A non-deleted conflict response must include serverData.

Client Wins

conflictStrategy: EasySyncConflictStrategy.clientWins,

The local operation is rebased using the server version and remains pending for another push attempt.

The server must still validate permissions and business rules. Client-wins does not bypass backend validation.

---

♻️ Pending and Failed Operations

Get the current pending operation count:

final count = await easySync.pendingCount();

Reset failed operations to pending:

final retried = await easySync.retryFailed();

debugPrint('$retried failed operations were queued again.');

Operations become failed after reaching maxRetries:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  maxRetries: 5,
)

---

🧭 Read the Last Cursor

final cursor = await easySync.getLastCursor();
debugPrint('Last cursor: $cursor');

Set a custom initial cursor:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  initialCursor: '0',
)

---

🕒 Read the Last Sync Time

final lastSyncTime = await easySync.getLastSyncTime();
debugPrint('Last sync: $lastSyncTime');

The value is null until a complete synchronization succeeds.

---

⚙️ Complete Configuration Example

final easySync = EasyRestSync(
  config: EasyRestSyncConfig(
    baseUrl: 'https://your-domain.com/api',
    pushEndpoint: '/sync/push',
    pullEndpoint: '/sync/pull',
    databaseName: 'my_application_sync',
    scope: 'user_506618',
    clientId: 'device-506618-01',
    batchSize: 100,
    maxRetries: 5,
    maxPullPages: 100,
    initialCursor: '0',
    autoSyncOnWrite: true,
    syncOnStart: true,
    connectTimeout: const Duration(seconds: 15),
    receiveTimeout: const Duration(seconds: 30),
    sendTimeout: const Duration(seconds: 30),
    streamDebounce: const Duration(milliseconds: 50),

    headers: const <String, dynamic>{
      'X-App-Name': 'Express ERP',
    },

    tokenProvider: () async {
      return await authRepository.getAccessToken();
    },

    conflictStrategy: EasySyncConflictStrategy.serverWins,

    streaming: const EasySyncStreamingConfig(
      enabled: true,
      interval: Duration(seconds: 10),
      syncImmediately: true,
      pauseWhenAppInBackground: true,
      continueAfterError: true,
      maxConsecutiveFailures: 0,
    ),
  ),
);

---

☁️ Push API Contract

Default endpoint:

POST /sync/push
Content-Type: application/json

Request body:

{
  "clientId": "device-506618-01",
  "scope": "user_506618",
  "operations": [
    {
      "operationId": "630d23c0-f7bb-42f9-85dd-fac2fac2f404",
      "entity": "products",
      "recordId": "101",
      "type": "create",
      "data": {
        "id": "101",
        "itemCode": "34494",
        "itemName": "Plastic Chair",
        "quantity": 10
      },
      "baseVersion": 0,
      "createdAt": "2026-07-16T04:00:00.000Z"
    }
  ]
}

Supported operation types:

create
update
delete

Each operation should be processed idempotently using operationId.

---

✅ Successful Push Response

The response must contain a result for every operation:

{
  "results": [
    {
      "operationId": "630d23c0-f7bb-42f9-85dd-fac2fac2f404",
      "status": "applied",
      "serverVersion": 1,
      "serverData": {
        "id": "101",
        "itemCode": "34494",
        "itemName": "Plastic Chair",
        "quantity": 10
      }
    }
  ]
}

Accepted success status values:

applied
success
completed

Successful delete response:

{
  "results": [
    {
      "operationId": "operation-uuid",
      "status": "applied",
      "serverVersion": 3,
      "serverDeleted": true
    }
  ]
}

---

⚠️ Push Conflict Response

{
  "results": [
    {
      "operationId": "operation-uuid",
      "status": "conflict",
      "serverVersion": 5,
      "serverData": {
        "id": "101",
        "itemCode": "34494",
        "itemName": "Server Product Name",
        "quantity": 20
      }
    }
  ]
}

When the server record was deleted:

{
  "results": [
    {
      "operationId": "operation-uuid",
      "status": "conflict",
      "serverVersion": 5,
      "serverDeleted": true
    }
  ]
}

---

📥 Pull API Contract

Default endpoint:

GET /sync/pull?cursor=100&limit=100&scope=user_506618&clientId=device-506618-01

Response:

{
  "changes": [
    {
      "cursor": "101",
      "entity": "products",
      "recordId": "101",
      "type": "update",
      "serverVersion": 2,
      "updatedAt": "2026-07-16T04:10:00.000Z",
      "data": {
        "id": "101",
        "itemCode": "34494",
        "itemName": "Plastic Chair Updated",
        "quantity": 20
      }
    }
  ],
  "nextCursor": "101",
  "hasMore": false
}

A non-delete change requires a data object.

The live streaming system repeatedly uses this pull endpoint at the configured interval.

---

🗑 Pull Delete Change

{
  "changes": [
    {
      "cursor": "102",
      "entity": "products",
      "recordId": "101",
      "type": "delete",
      "serverVersion": 3,
      "updatedAt": "2026-07-16T04:12:00.000Z"
    }
  ],
  "nextCursor": "102",
  "hasMore": false
}

---

📚 Multiple Pull Pages

When more changes are available, return a non-empty change page with hasMore: true:

{
  "changes": [
    {
      "cursor": "200",
      "entity": "products",
      "recordId": "200",
      "type": "update",
      "serverVersion": 4,
      "data": {
        "id": "200",
        "itemCode": "50001",
        "itemName": "Another Product",
        "quantity": 12
      }
    }
  ],
  "nextCursor": "200",
  "hasMore": true
}

The next response must advance nextCursor.

Return hasMore: false on the final page.

The package stops after maxPullPages to protect the application from an endless server loop:

EasyRestSyncConfig(
  baseUrl: 'https://your-domain.com/api',
  maxPullPages: 100,
)

---

🧪 Complete Usage Example

import 'dart:async';

import 'package:easy_rest_sync/easy_rest_sync.dart';
import 'package:flutter/material.dart';

late final EasyRestSync easySync;

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  easySync = EasyRestSync(
    config: EasyRestSyncConfig(
      baseUrl: 'https://your-domain.com/api',
      scope: 'current_user',
      autoSyncOnWrite: false,
      syncOnStart: false,
      streamDebounce: const Duration(milliseconds: 50),
      streaming: const EasySyncStreamingConfig(
        enabled: true,
        interval: Duration(seconds: 10),
        syncImmediately: true,
      ),
      tokenProvider: () async => null,
    ),
  );

  easySync.registerEntity<Product>(
    EasySyncEntity<Product>(
      name: 'products',
      idSelector: (product) => product.id,
      toJson: (product) => product.toJson(),
      fromJson: Product.fromJson,
    ),
  );

  await easySync.initialize();

  runApp(const MyApp());
}

class Product {
  final String id;
  final String name;
  final double quantity;

  const Product({
    required this.id,
    required this.name,
    required this.quantity,
  });

  factory Product.fromJson(Map<String, dynamic> json) {
    return Product(
      id: json['id']?.toString() ?? '',
      name: json['name']?.toString() ?? '',
      quantity:
          double.tryParse(json['quantity']?.toString() ?? '0') ?? 0,
    );
  }

  Map<String, dynamic> toJson() {
    return <String, dynamic>{
      'id': id,
      'name': name,
      'quantity': quantity,
    };
  }
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Easy REST Sync'),
          actions: <Widget>[
            StreamBuilder<EasySyncState>(
              stream: easySync.watchState(),
              initialData: easySync.state,
              builder: (context, snapshot) {
                final state = snapshot.data ?? easySync.state;

                return Center(
                  child: Padding(
                    padding: const EdgeInsets.symmetric(
                      horizontal: 8,
                    ),
                    child: Text(
                      '${state.streamingStatus.name} '
                      '(${state.pendingOperations})',
                    ),
                  ),
                );
              },
            ),
            IconButton(
              onPressed: () async {
                await easySync.sync();
              },
              icon: const Icon(Icons.sync),
            ),
          ],
        ),
        body: StreamBuilder<List<Product>>(
          stream: easySync.watchList<Product>(
            entity: 'products',
          ),
          builder: (context, snapshot) {
            final products = snapshot.data ?? <Product>[];

            if (products.isEmpty) {
              return const Center(
                child: Text('No products found.'),
              );
            }

            return ListView.builder(
              itemCount: products.length,
              itemBuilder: (context, index) {
                final product = products[index];

                return ListTile(
                  title: Text(product.name),
                  trailing: Text(product.quantity.toString()),
                  onLongPress: () async {
                    await easySync.delete(
                      entity: 'products',
                      id: product.id,
                    );
                  },
                );
              },
            );
          },
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () async {
            final product = Product(
              id: DateTime.now()
                  .microsecondsSinceEpoch
                  .toString(),
              name: 'New Product',
              quantity: 1,
            );

            await easySync.save<Product>(
              entity: 'products',
              data: product,
            );
          },
          child: const Icon(Icons.add),
        ),
      ),
    );
  }
}

---

▶️ Example App Run Instructions

Create an example application from the package root:

flutter create example

Add the local package dependency to example/pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter

  easy_rest_sync:
    path: ../

Go to the example folder:

cd example

Then run:

flutter clean
flutter pub get
flutter run

---

🧹 Dispose Resources

Call dispose() when the sync instance is no longer needed:

await easySync.dispose();

This:

• Stops the streaming timer
• Removes the application lifecycle observer
• Cancels internal debounce timers
• Closes record and entity stream controllers
• Closes the event stream
• Closes the state stream
• Closes the status stream
• Releases the internally created network client

---

❗ Common Issues

Entity is not registered

Error:

Entity "products" is not registered. Call registerEntity() first.

Fix:

easySync.registerEntity<Product>(
  EasySyncEntity<Product>(
    name: 'products',
    idSelector: (product) => product.id,
    toJson: (product) => product.toJson(),
    fromJson: Product.fromJson,
  ),
);

---

Package is not initialized

Error:

Call EasyRestSync.initialize() before using the package.

Fix:

await easySync.initialize();

---

Streaming interval is invalid

The streaming interval must be greater than zero.

Correct:

await easySync.startStreaming(
  config: const EasySyncStreamingConfig(
    interval: Duration(seconds: 10),
  ),
);

---

Streaming does not start automatically

Check that streaming is enabled:

streaming: const EasySyncStreamingConfig(
  enabled: true,
)

Or start it manually:

await easySync.startStreaming();

---

Streaming pauses in the background

This is expected when:

pauseWhenAppInBackground: true

Disable lifecycle pausing:

streaming: const EasySyncStreamingConfig(
  enabled: true,
  pauseWhenAppInBackground: false,
)

---

Push response does not contain results

The push API must return:

{
  "results": []
}

It must return one result for every submitted operationId.

---

Pull response does not contain changes

The pull API must return:

{
  "changes": [],
  "nextCursor": "0",
  "hasMore": false
}

---

Sync status becomes offline

The package reports EasySyncStatus.offline for connection errors and network timeouts.

Local reads and writes can continue. Pending operations can be synchronized later.

---

Failed operations are not being pushed

Operations that reached maxRetries have the failed state.

Reset them:

await easySync.retryFailed();
await easySync.sync();

---

Pagination throws an ArgumentError

Provide both page and pageSize, and ensure both are greater than zero:

await easySync.getList<Product>(
  entity: 'products',
  page: 1,
  pageSize: 20,
);

---

📚 API Overview

EasyRestSync(
  config: EasyRestSyncConfig(...),
);

easySync.registerEntity<Product>(...);

await easySync.initialize();

await easySync.save<Product>(
  entity: 'products',
  data: product,
);

await easySync.get<Product>(
  entity: 'products',
  id: '101',
);

await easySync.getList<Product>(
  entity: 'products',
);

easySync.watchList<Product>(
  entity: 'products',
);

easySync.watchOne<Product>(
  entity: 'products',
  id: '101',
);

easySync.watchPendingCount();

easySync.watchState();

easySync.statusStream;

easySync.stateStream;

easySync.events;

await easySync.delete(
  entity: 'products',
  id: '101',
);

await easySync.startStreaming();

await easySync.pauseStreaming();

await easySync.resumeStreaming(
  syncNow: true,
);

await easySync.stopStreaming();

await easySync.sync();

await easySync.pendingCount();

await easySync.retryFailed();

await easySync.getLastCursor();

await easySync.getLastSyncTime();

await easySync.dispose();

---

🔐 Security Best Practices

• Always use HTTPS in production
• Validate the authenticated user on every push and pull request
• Never trust scope, entity, recordId, or client-provided data without validation
• Verify that the user can access every requested record
• Process operationId idempotently to prevent duplicate writes
• Use server-side version checks for updates and deletes
• Do not store database credentials or backend secrets in the Flutter app
• Return only data belonging to the authenticated user's scope
• Apply request-size and batch limits on the server
• Log rejected and conflicting operations for debugging
• Rate-limit synchronization endpoints
• Select a safe streaming interval
• Monitor polling traffic and server load
• Avoid returning sensitive information in sync errors

---

📝 Current Limitations

• The backend push and pull endpoints must be implemented separately
• REST live streaming is interval-based polling, not WebSocket push
• File and image synchronization are not included
• Field-level merge conflicts are not included
• Custom conflict resolvers are not included
• Local filters and pagination run after loading records for the selected entity
• Background execution after the operating system suspends the application is not guaranteed
• Native background scheduling must be added separately when required
• Indexed local queries are not included in the current version
• Storage migrations and encryption configuration are not yet exposed publicly

---

🛣 Planned Improvements

• Typed collection API
• Indexed local queries
• Bulk save and delete
• Exponential retry backoff
• Custom REST protocol adapters
• Custom conflict resolvers
• Encryption configuration
• Migration support
• Isolate-based heavy processing
• File and image synchronization
• Server-Sent Events adapter
• WebSocket adapter
• Detailed diagnostics and logging
• Automated backend contract tests

---

📄 License

MIT License

See the LICENSE file for details.

---

👨‍💻 Author

Developed by Nafim Ahmed.

📦 Package: https://pub.dev/packages/easy_rest_sync