🔄 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

easy_rest_sync 0.0.2 easy_rest_sync: ^0.0.2 copied to clipboard

Metadata