API Reference | HostSpica SDK

SyncLayer

The main entry point for the SyncLayer SDK.

init

static Future<void> init(SyncConfig config)

Initialize SyncLayer with configuration

Parameters:

config (SyncConfig) - Configuration object

Returns:

Future<void>

Example:

dart

await SyncLayer.init(
  SyncConfig(
    baseUrl: 'https://api.example.com',
    collections: ['todos', 'users'],
    conflictStrategy: ConflictStrategy.lastWriteWins,
  ),
);

collection

static CollectionManager collection(String name)

Get a collection manager for CRUD operations

Parameters:

name (String) - Collection name

Returns:

CollectionManager

Example:

dart

final todos = SyncLayer.collection('todos');

syncNow

static Future<void> syncNow()

Trigger immediate synchronization

Returns:

Future<void>

Example:

dart

await SyncLayer.syncNow();

events

static Stream<SyncEvent> get events

Stream of sync events

Returns:

Stream<SyncEvent>

Example:

dart

SyncLayer.events.listen((event) {
  if (event is SyncStartedEvent) {
    print('Sync started');
  }
});

dispose

static Future<void> dispose()

Clean up resources and close connections

Returns:

Future<void>

Example:

dart

await SyncLayer.dispose();

SyncConfig

Configuration object for initializing SyncLayer.

Property	Type	Required	Default	Description
`baseUrl`	String?	No	-	Base URL for REST API (required if no custom adapter)
`collections`	List<String>	Yes	-	List of collection names to sync
`conflictStrategy`	ConflictStrategy	No	lastWriteWins	Strategy for conflict resolution
`syncInterval`	Duration	No	30 seconds	Automatic sync interval
`maxRetries`	int	No	3	Maximum retry attempts
`retryDelay`	Duration	No	2 seconds	Delay between retries
`customBackendAdapter`	BackendAdapter?	No	-	Custom backend adapter
`authToken`	String?	No	-	Authentication token

CollectionManager

Manages CRUD operations for a specific collection.

save

Future<String> save(Map<String, dynamic> data, {String? id})

Save or update a document

Parameters:

data (Map<String, dynamic>) - Document data
id (String?) - Optional document ID (for updates)

Returns:

Future<String> - Document ID

Example:

dart

final id = await SyncLayer
  .collection('todos')
  .save({'text': 'Buy milk', 'done': false});

get

Future<Map<String, dynamic>?> get(String id)

Retrieve a document by ID

Parameters:

id (String) - Document ID

Returns:

Future<Map<String, dynamic>?>

Example:

dart

final todo = await SyncLayer
  .collection('todos')
  .get(id);

getAll

Future<List<Map<String, dynamic>>> getAll()

Retrieve all documents in collection

Returns:

Future<List<Map<String, dynamic>>>

Example:

dart

final todos = await SyncLayer
  .collection('todos')
  .getAll();

delete

Future<void> delete(String id)

Delete a document by ID

Parameters:

id (String) - Document ID

Returns:

Future<void>

Example:

dart

await SyncLayer
  .collection('todos')
  .delete(id);

watch

Stream<List<Map<String, dynamic>>> watch()

Watch for real-time changes

Returns:

Stream<List<Map<String, dynamic>>>

Example:

dart

SyncLayer
  .collection('todos')
  .watch()
  .listen((todos) {
    print('Updated: ${todos.length} items');
  });

ConflictStrategy

Enum for conflict resolution strategies.

Value	Description
`lastWriteWins`	Most recent modification wins (by timestamp)
`serverWins`	Server data always takes precedence
`clientWins`	Local changes always take precedence

Events

Event types emitted by SyncLayer.

SyncStartedEvent

Sync process started

Properties: timestamp

SyncCompletedEvent

Sync completed successfully

Properties: timestamp, itemsSynced

SyncErrorEvent

Sync error occurred

Properties: timestamp, error, stackTrace

ConflictDetectedEvent

Conflict detected during sync

Properties: timestamp, collection, entityId

ConnectivityChangedEvent

Network connectivity changed

Properties: timestamp, isOnline

Backend Adapters

Built-in backend adapters for different services.

FirebaseAdapter

dart

import 'package:synclayer/adapters/firebase_adapter.dart';

await SyncLayer.init(
  SyncConfig(
    collections: ['todos'],
    customBackendAdapter: FirebaseAdapter(
      firestore: FirebaseFirestore.instance,
    ),
  ),
);

SupabaseAdapter

dart

import 'package:synclayer/adapters/supabase_adapter.dart';

await SyncLayer.init(
  SyncConfig(
    collections: ['todos'],
    customBackendAdapter: SupabaseAdapter(
      client: Supabase.instance.client,
    ),
  ),
);

AppwriteAdapter

dart

import 'package:synclayer/adapters/appwrite_adapter.dart';

await SyncLayer.init(
  SyncConfig(
    collections: ['todos'],
    customBackendAdapter: AppwriteAdapter(
      databases: databases,
      databaseId: 'your-database-id',
    ),
  ),
);

Need Help?

Check out our examples and guides for more detailed usage.

View Examples →Quick Start →Report Issue →