// Event subscription
function SyncNotifications() {
useSyncVaultEvent("job_success", (event) => {
toast.success(Synced: ${event.data.job.url});
});

useSyncVaultEvent("job_failed", (event) => {
if (!event.data.willRetry) {
toast.error(Failed: ${event.data.error.message});
}
});

return null;
}
`

---

$3

`vue



`

#### Additional Vue Composables

`typescript
import {
useSyncVault,
useOnlineStatus,
useQueueStatus,
useSyncRequest,
useSyncVaultEvent,
useJobWatcher,
} from "@sync-vault-js/core/vue";

// Online status
const isOnline = useOnlineStatus();

// Queue status
const { length, isProcessing, refresh } = useQueueStatus();

// Request with state
const { execute, data, loading, error, queued, reset } = useSyncRequest();

// Watch a specific job
const jobId = ref(null);
const { completed, success, error } = useJobWatcher(jobId);
`

---

$3

`typescript
// sync-vault.service.ts
import { Injectable } from "@angular/core";
import { SyncVaultService } from "@sync-vault-js/core/angular";

@Injectable({ providedIn: "root" })
export class AppSyncVaultService extends SyncVaultService {
constructor() {
super({ debug: true });
}
}

// todo.component.ts
import { Component, OnInit, OnDestroy } from "@angular/core";
import { Subscription } from "rxjs";
import { AppSyncVaultService } from "./sync-vault.service";

@Component({
selector: "app-todo",
template:

if (response.fromQueue) {
alert("Saved offline - will sync when online");
}
}
}
`

---

$3

`svelte


`typescript
import {
createSyncVaultStores,
createSyncVaultActions,
createEventStore,
createJobStore,
createRequestStore,
} from "@sync-vault-js/core/svelte";

// Create all stores
const { state, isOnline, isProcessing, queueLength, destroy } =
createSyncVaultStores();

// Create actions
const { post, get, clearQueue } = createSyncVaultActions();

// Event store
const successEvents = createEventStore("job_success");

// Track specific job
const jobStatus = createJobStore("job-123");

// Request with state management
const { data, loading, error, queued, execute, reset } = createRequestStore();
`

---

Configuration

`typescript
import { createSyncVault } from "@sync-vault-js/core";

const vault = createSyncVault({
// Storage configuration
dbName: "my-app-sync", // IndexedDB database name

// Queue configuration
queue: {
concurrency: 1, // Process one job at a time
processingDelay: 100, // Delay between jobs (ms)
maxSize: 0, // Max queue size (0 = unlimited)
},

// Retry configuration
retry: {
maxRetries: 3, // Max retry attempts
initialDelay: 1000, // Initial backoff delay (ms)
maxDelay: 30000, // Maximum delay cap (ms)
multiplier: 2, // Exponential multiplier
jitter: true, // Add randomness to prevent thundering herd
},

// Behavior
debug: false, // Enable debug logging
autoStart: true, // Auto-start processing when online

// Custom adapters (advanced)
storage: customStorageAdapter,
networkChecker: customNetworkChecker,
httpClient: customHttpClient,
});
`

---

Events

SyncVault emits various events throughout its lifecycle:

| Event | Description | Data |
| ----------------- | ------------------------------ | ------------------------------------------- |
| sync_started | Queue processing started | - |
| sync_completed | Queue processing finished | - |
| sync_paused | Processing paused | - |
| job_queued | New job added to queue | { job, queueLength } |
| job_started | Job processing started | { job } |
| job_success | Job completed successfully | { job, response, duration } |
| job_failed | Job failed | { job, error, willRetry } |
| job_retry | Job will be retried | { job, attempt, maxRetries, nextRetryIn } |
| job_dead | Job moved to Dead Letter Queue | { job, error, movedToDLQ } |
| network_online | Device came online | - |
| network_offline | Device went offline | - |
| queue_empty | Queue is now empty | - |
| queue_cleared | Queue was manually cleared | - |

`typescript
// Subscribe to events
const unsubscribe = vault.on("job_success", (event) => {
console.log("Job completed:", event.data);
});

// One-time subscription
vault.once("sync_completed", (event) => {
console.log("Initial sync done");
});

// Unsubscribe
unsubscribe();
`

---

Queue Management

`typescript
// Get queue status
const length = await vault.getQueueLength();
const jobs = await vault.getQueue();

// Manual control
vault.startProcessing();
vault.stopProcessing();
const syncing = vault.isProcessing();

// Clear queue
await vault.clearQueue();

// Manage specific jobs
await vault.retryJob("job-id");
await vault.removeJob("job-id");
`

---

Dead Letter Queue (DLQ)

Jobs that fail after max retries are moved to the DLQ:

`typescript
// Get failed jobs
const deadJobs = await vault.getDLQ();

// Retry all dead jobs
await vault.retryDLQ();

// Clear DLQ
await vault.clearDLQ();
`

---

Custom Storage Adapters

Implement the StorageAdapter interface for custom storage:

`typescript
import type { StorageAdapter, QueuedJob } from "@sync-vault-js/core";

class CustomStorageAdapter implements StorageAdapter {
async init(): Promise {
/ ... /
}
async add(job: QueuedJob): Promise {
/ ... /
}
async getAll(): Promise {
/ ... /
}
async get(id: string): Promise {
/ ... /
}
async update(id: string, updates: Partial): Promise {
/ ... /
}
async remove(id: string): Promise {
/ ... /
}
async count(): Promise {
/ ... /
}
async clear(): Promise {
/ ... /
}
async moveToDLQ(job: QueuedJob): Promise {
/ ... /
}
async getDLQ(): Promise {
/ ... /
}
async clearDLQ(): Promise {
/ ... /
}
async close(): Promise {
/ ... /
}
}

const vault = createSyncVault({
storage: new CustomStorageAdapter(),
});
`

---

React Native Integration

For React Native, use the custom network checker with @react-native-community/netinfo:

`typescript
import NetInfo from "@react-native-community/netinfo";
import {
createSyncVault,
createReactNativeNetworkChecker,
} from "@sync-vault-js/core";

const vault = createSyncVault({
networkChecker: createReactNativeNetworkChecker(NetInfo),
});
`

---

TypeScript Support

SyncVault is written in strict TypeScript with full type inference:

`typescript
interface User {
id: string;
name: string;
email: string;
}

interface CreateUserPayload {
name: string;
email: string;
}

// Fully typed request and response
const response = await vault.post("/api/users", {
name: "John",
email: "john@example.com",
});

// response.data is typed as User
console.log(response.data.id);
`

---

Architecture

`
┌─────────────────────────────────────────────────────────────────┐
│ SyncVault Client │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HTTP Client │ │ Event Emitter│ │Network Checker│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Queue Processor │ │
│ │ ┌─────────┐ ┌─────────────┐ ┌──────────────────┐ │ │
│ │ │ FIFO │ │ Exp Backoff │ │ Dead Letter Q │ │ │
│ │ │ Queue │ │ Retry │ │ │ │ │
│ │ └─────────┘ └─────────────┘ └──────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Storage Adapter (Interface) │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ IndexedDB │ │ Memory │ │ │
│ │ │ (Browser) │ │ (SSR/Node) │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
``

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

---

Authors

Nabhodipta Garai

- GitHub: @brownboycodes
- LinkedIn: Nabhodipta Garai
- 

Swayam Debata (Contributor)

- GitHub: @SwayamDebata
- LinkedIn: Swayam Debata
- 

---

License

MIT © SyncVault

---