thundersync/README.md

A Firebase-based alternative to Socket.IO, providing real-time communication and event-driven functionality using Firebase Realtime Database without a server.

# ThunderSync ⚡

**ThunderSync** is a lightning-fast, serverless WebSocket-like library built using Firebase Realtime Database. It enables real-time events, room management, and socket-style communication between clients—all powered by Firebase. Designed to mimic Socket.IO’s behavior without servers, it’s perfect for scalable, low-latency apps.

## Features

- **Real-time** sync using Firebase Realtime Database
- **Socket-like** communication (events, rooms, broadcasts)
- **Room-based** messaging (join/leave rooms)
- **Direct client-to-client** messaging via mapped IDs
- **Automatic connection handling** (`connect`/`disconnect` events)

## Installation

```bash
npm install thundersync
```

Then, import `ThunderSync` into your project:

```typescript
import ThunderSync from "thundersync";
```

## Usage

### Initialization

To create a new instance of `ThunderSync`, provide your Firebase Realtime Database URL:

```typescript
const thunder = new ThunderSync("https://your-firebase-database-url");
```

### Connecting to Firebase

ThunderSync automatically connects to Firebase and creates a unique thunder ID for each instance. You can retrieve the thunder ID with:

```typescript
console.log(thunder.id);
// 3d585b39-0b3e-496f-9d0b-eabc0ce37c36
```

### Listening to Events

```typescript
thunder.on("connect", () => {
  console.log("⚡ Connected! Socket ID:", thunder.id);
});

thunder.on("message", (data) => {
  console.log("📨 Received:", data);
});
```

### Emitting Events

Broadcast to all clients:

```typescript
thunder.emit("alert", { text: "Hello, world!" });
```

Send to a room:

```typescript
thunder.join("lobby");
thunder.toRoom("lobby").emit("chat", { user: "Alice", msg: "Hi!" });
```

Target a specific user:

```typescript
thunder.mapId("user-123");
thunder.toMapId("user-123").emit("whisper", { secret: "PSST..." });
```

### Rooms

#### Joining a Room

Join a room by calling the `join` method:

```typescript
thunder.join("room-name");
```

#### Leaving a Room

To leave a room:

```typescript
thunder.leave("room-name");
```

### Custom ID Mapping

You can map custom user IDs to thunder IDs.
It is helpful to send events to single user e.g. chat applications.

```typescript
thunder.mapId("custom-id");
```

And send events to a specific user mapped by their ID:

```typescript
thunder.toMapId("custom-id").emit("your-event", { key: "value" });
```

### Disconnecting

To disconnect the socket manually:

```typescript
thunder.disconnect();
```

### Retrieving Sockets

You can retrieve the list of all connected sockets with:

```typescript
thunder.getSockets((sockets) => {
  console.log(sockets);
});
```

### Retrieving Rooms

You can get all rooms and their members with:

```typescript
thunder.getRooms((rooms) => {
  console.log(rooms);
});
```

### Leaving and Stopping Event Listeners

To stop listening to a specific event, use:

```typescript
thunder.off("your-event");
```

## Example

Here's a complete example of using ThunderSync:

```typescript
import ThunderSync from "thundersync";

const thunder = new ThunderSync("https://your-firebase-database-url");

thunder.on("connect", () => {
  console.log("Connected to Firebase!");

  thunder.emit("greet", { message: "Hello, World!" });

  thunder.on("greet-back", (data) => {
    console.log("Received: ", data);
  });
});

thunder.join("chat-room");

thunder.toRoom("chat-room").emit("message", { text: "Hello everyone!" });

thunder.on("message", (data) => {
  console.log("New message in chat-room: ", data);
});
```

## Core API

### Methods

- `thunder.on(event: string, callback: (data: any) => void)` - Listen for a specific event.
- `thunder.emit(event: string, data: any)` - Emit an event to all clients.
- `thunder.toRoom(room: string).emit(event: string, data: any)` - Emit an event to a specific room.
- `thunder.join(room: string)` - Join a room.
- `thunder.leave(room: string)` - Leave a room.
- `thunder.mapId(id: string)` - Map a custom ID to a socket.
- `thunder.toMapId(id: string).emit(event: string, data: any)` - Emit an event to a specific mapped user ID.
- `thunder.disconnect()` - Manually disconnect the socket.

### Properties

- `thunder.id` - The unique ID of the thunder.
- `thunder.connected` - Connection status (boolean).

## Why ThunderSync?

Serverless: No backend code—Firebase handles the heavy lifting.

Scalable: Built for Firebase’s real-time infrastructure.

Familiar API: Works like Socket.IO but without servers.

## License

MIT License.