Sync

Use mesh.sync when an app needs to queue work and flush it later: offline drafts, retryable uploads, background reconciliation, or provider operations that should survive process boundaries.

MeshKit stores sync jobs and checkpoints through the provider contract. It does not secretly run a background service for every runtime. Your app decides when to call flush, start a scheduler, or hand execution to a platform background task.

Queue And Flush Work

import { meshkit } from "@meshkit/meshkit";

const mesh = await meshkit();

await mesh.sync.enqueue({
  kind: "upload-draft",
  payload: { draftId: "draft-1" },
  conflictKey: "draft:draft-1",
  conflictPolicy: "replace",
});

const processed = await mesh.sync.flush({
  network: "online",
  handler: async (job) => {
    console.log("uploading", job.payload.draftId);
    return { uploaded: true };
  },
});

console.log(processed.map((job) => job.status));

How Sync Works

app creates job
-> provider stores durable job metadata
-> app resumes later
-> app calls flush when network/runtime allows
-> handler processes job
-> MeshKit stores status and checkpoints

This design is intentionally caller-managed. Browser service workers, React Native background tasks, Ionic/Capacitor tasks, and Node workers all have different lifecycle rules.

API

await mesh.sync.enqueue(input);
await mesh.sync.jobs();
await mesh.sync.checkpoint(jobId, checkpoint);
await mesh.sync.flush(options);
const scheduler = mesh.sync.createScheduler(options);

API	Use it for
`sync.enqueue(input)`	Add a durable job
`sync.jobs()`	List public sync jobs
`sync.checkpoint(jobId, checkpoint)`	Store progress for a job
`sync.flush(options)`	Process ready jobs now
`sync.createScheduler(options)`	Create a caller-managed interval scheduler

Conflict Policies

Policy	Behavior
`dedupe`	Reuse an existing active job for the same `conflictKey`
`fail`	Throw when a conflicting active job exists
`replace`	Replace the active job for the same `conflictKey`

Use conflictKey for user-visible resources such as draft:draft-1, file:avatar, or workspace:123:sync.

Provider Requirements

Sync needs a provider that can store sync job records. Raw byte storage alone is not enough. If a provider does not support sync queues, MeshKit fails with sync_not_supported.

Failure Modes

Error or symptom	Meaning	Action
`sync_not_supported`	Provider cannot store durable sync jobs	Use a MeshKit provider with sync job support
Job stays pending	App never called `flush` under allowed network/runtime conditions	Wire a scheduler, worker, or platform background callback
Duplicate work	Missing or weak `conflictKey`	Add a stable key and choose a conflict policy
Job loops forever	Handler returns failure without backoff or terminal state	Add retry limits and checkpoint progress

Production Notes

Keep handlers idempotent. A retry can run after partial progress.
Persist user-visible status in your app if users need progress after restart.
Store checkpoints for large multi-step work.
In mobile apps, pair sync with the platform's real background execution model.
Do not put secrets in job payloads unless they are encrypted and scoped for that runtime.

Next Steps

Stream large content with Streaming.
Choose runtime behavior in Runtimes.
Validate provider support in Provider testing.

On this page