Fileverse Sync

The Fileverse Sync is a TypeScript-based package that enables real-time collaboration using Yjs for data synchronization and WebSockets for communication. This package provides a state machine (syncMachine) for handling synchronization logic and a React hook (useSyncMachine) for easy integration with React applications.

Features

• Real-time collaboration: Utilize WebSockets for instant updates.
• Data synchronization: Sync data across clients using Yjs.
• State management: Handle connection states with XState.
• Encryption: Secure data transmission with encryption and decryption capabilities.

Installation

Install the package using npm or yarn:

npm install @fileverse-dev/sync
or
yarn add @fileverse-dev/sync

Usage

SyncCore

The syncCore is an interpreted instance of the syncMachine for managing the synchronization state.

Example

import { syncCore } from ' @fileverse-dev/sync';

const sync = syncCore.start({
  roomId: 'fileverse'
});

sync.send({ type: 'CONNECT', data: { username: 'your-username', roomKey: 'aes-encryption-key' } });

sync.onTransition(state => {
  console.log(state.value);
});

useSyncMachine

The useSyncMachine hook simplifies the integration of the synchronization logic into React applications.

Example

import React, { useEffect } from 'react';
import { useSyncMachine } from 'fileverse-sync-client';

const App = () => {
  const { connect, disconnect, isConnected, ydoc } = useSyncMachine({ roomKey: 'your-room-key', wsUrl: 'wss//your-websocket-service' });

  useEffect(() => {
    connect('your-username', 'your-room-id');

    return () => {
      disconnect();
    };
  }, [connect, disconnect]);

  return (
    <div>
      <h1>{isConnected ? 'Connected' : 'Disconnected'}</h1>
      {/* Render your collaborative content here */}
    </div>
  );
};

export default App;

API

syncMachine

A state machine for managing the synchronization state.

States

• disconnected: The initial state. The machine transitions here when disconnected.
• connecting: The machine transitions here while attempting to connect.
• send_initial_update: State for sending the initial update after connecting.
• updating: State for sending updates.
• connected: The machine transitions here when connected.
• disconnecting: The machine transitions here while disconnecting.

Events

• CONNECT: Initiates the connection process.
• SEND_UPDATE: Sends an update.
• UPDATE_COMMIT: Commits an update.
• ROOM_MEMBERSHIP_CHANGE: Updates room members.
• MESSAGE_RECEIVED: Processes a received message.
• CONTENT_UPDATE: Applies a content update.
• SEND_INIT_UPDATE: Sends the initial update.
• DISCONNECT: Initiates the disconnection process.
• AWARENESS_UPDATE: Applies an awareness state update.
• INIT_AWARENESS: Initializes the awareness state.
• RESET_STATE: Resets the state.

Actions

• initSync: Initializes synchronization context.
• setConnectState: Sets the connection state.
• handleReset: Handles resetting the state.
• handleAwareness: Handles awareness initialization.
• applyAwarenessState: Applies the awareness state.
• processMessage: Processes a received message.
• updateRoomMembers: Updates the room members.
• applyUpdate: Applies an update to the document.

useSyncMachine

Hook

• connect(username: string, roomId: string): void
  • Connects to the WebSocket.
• disconnect(): void
  • Disconnects from the WebSocket.
• isConnected: boolean
  • Connection status.
• ydoc: Y.Doc
  • Yjs document.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.