Package Exports

syncflow-engine
syncflow-engine/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (syncflow-engine) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

SyncFlow

A flexible and robust data synchronization library for JavaScript/TypeScript applications, with first-class React/Next.js support.

Features

🔄 Robust synchronization engine
💾 Built-in memory store with customizable storage adapters
⚛️ React hooks and context provider
📱 Offline-first capabilities
🔍 Debug mode for development
📦 TypeScript support
⚡ Automatic retries with configurable limits
🎯 Event-driven architecture

Installation

npm install syncflow
# or
yarn add syncflow
# or
pnpm add syncflow

Quick Start

Basic Usage (JavaScript/TypeScript)

import { SyncEngine, MemorySyncStore } from 'syncflow';

const store = new MemorySyncStore();
const syncEngine = new SyncEngine(store, {
  retryLimit: 3,
  retryDelay: 2000,
  batchSize: 5,
  autoStart: true,
  debug: true,
});

// Add sync operation
await store.addOperation({
  type: "create",
  entity: "user",
  data: { name: "John Doe" },
  status: "pending",
  retryCount: 0,
});

// Start syncing
await syncEngine.start();

React/Next.js Usage

Wrap your application with SyncProvider:

// _app.tsx or layout.tsx
import { SyncProvider } from 'syncflow';

function App({ Component, pageProps }) {
  return (
    <SyncProvider
      config={{
        retryLimit: 3,
        retryDelay: 2000,
        batchSize: 5,
        autoStart: true,
        debug: true,
      }}
    >
      <Component {...pageProps} />
    </SyncProvider>
  );
}

Use hooks in your components:

import { useSync, useSyncOperation, useSyncListener } from 'syncflow';

function MyComponent() {
  const { status } = useSync();
  const { sync, isLoading } = useSyncOperation();

  useSyncListener("syncComplete", () => {
    console.log("Sync completed!");
  });

  const handleCreateUser = async () => {
    await sync("create", "user", {
      name: "John Doe",
      email: "john@example.com",
    });
  };

  return (
    <div>
      <p>Sync Status: {status}</p>
      <button onClick={handleCreateUser} disabled={isLoading}>
        {isLoading ? "Syncing..." : "Create User"}
      </button>
    </div>
  );
}

API Reference

Core Types

type SyncStatus = "idle" | "syncing" | "error" | "offline";

type SyncOperation = {
  id: string;
  timestamp: number;
  type: "create" | "update" | "delete";
  entity: string;
  data: unknown;
  status: "pending" | "completed" | "error";
  retryCount: number;
};

type SyncConfig = {
  retryLimit: number;
  retryDelay: number;
  batchSize: number;
  autoStart?: boolean;
  debug?: boolean;
};

SyncEngine

The main synchronization engine that handles operations.

class SyncEngine {
  constructor(store: ISyncStore, config?: SyncConfig);
  start(): Promise<void>;
  stop(): Promise<void>;
  sync(): Promise<void>;
  getStatus(): SyncStatus;
  addListener(event: SyncEventType, callback: SyncEventCallback): void;
  removeListener(event: SyncEventType, callback: SyncEventCallback): void;
}

React Hooks

useSync(): Access sync context
useSyncOperation(): Perform sync operations
useSyncListener(event, callback): Listen to sync events

Configuration Options

Option	Type	Default	Description
retryLimit	number	3	Maximum number of retry attempts
retryDelay	number	1000	Delay between retries (ms)
batchSize	number	10	Number of operations to process at once
autoStart	boolean	true	Start sync engine automatically
debug	boolean	false	Enable debug logging

Events

syncStart: Emitted when sync starts
syncComplete: Emitted when sync completes
syncError: Emitted on sync error
statusChange: Emitted when sync status changes
operationComplete: Emitted when an operation completes

Custom Storage Implementation

Implement the ISyncStore interface to create your own storage adapter:

interface ISyncStore {
  getOperations(): Promise<SyncOperation[]>;
  addOperation(operation: Omit<SyncOperation, "id" | "timestamp">): Promise<void>;
  updateOperation(id: string, updates: Partial<SyncOperation>): Promise<void>;
  removeOperation(id: string): Promise<void>;
}

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Caio Theodoro

Support

Star this repo
Create an issue
Submit a PR

Acknowledgments

Inspired by offline-first architecture
Built with TypeScript
React hooks implementation inspired by modern React patterns