Import Status

Quick Reference

Import status tells you what operations were applied and what’s pending due to missing dependencies. Essential for handling out-of-order updates in distributed systems.

Status Structure

interface ImportStatus {
  : <, >; // What was integrated into history
  : <, > | null; // What still needs dependencies
}
 
type  = `${number}`;
type  = {
  : number; // Inclusive
  : number;   // Exclusive (e.g., 0-50 = ops 0-49)
};

Both fields are present in the WASM and pure TypeScript implementations. pending is null when the import reports no pending operations. These ranges are JavaScript Map values: use .size, .get(peerId), or iteration; Object.keys() does not enumerate Map entries.

ImportStatus reports an import result, not a complete query of the document’s pending queue; pending === null does not guarantee that no earlier imports remain pending. Use exportPendingUpdates() to export all currently received but unintegrated operations; undefined means that queue is empty, not that the document is synced.

Pending Operations

Operations become pending when they depend on missing operations (causal dependencies). These are imported remote operations, not local edits waiting for commit(). Normal snapshot and update exports exclude them. The exportPendingUpdates() API exports them separately for persistence; see the checkpoint and recovery example. Restoring those bytes with ordinary import() preserves the pending operations, but they apply only after their actual missing dependencies arrive.

Common Scenario: Out-of-Order Delivery

const  = new ();
 
// Peer A creates ops 0-4, then 5-10
const  = new ();
.("text").(0, "Hello");
const  = .({ : "update" });
const  = .();
 
.("text").(5, " World");
const  = .({ : "update", :  });
 
// If update2 arrives first:
const  = .();
(.).();
(.).();
(.?.).(0); // Ops 5-10 need ops 0-4.
(.("text").()).("");
 
// Import missing dependencies:
const  = .(); // Both updates now applied
(.).();
(.("text").()).("Hello World");

Handling Pending Operations

async function (
  : ,
  : ,
  : (: ) => <>
) {
  const  = .();
  
  if (. !== null && .. > 0) {
    const  = await (.());
    .();
  }
}

Best Practices

Always Check Status

const  = new ();
const  = .();
if (. !== null && .. > 0) {
  .("Operations pending:", .);
  // Fetch missing updates
}

Use Batch Import

const : [] = [
  //...
];
const  = new ();
const  = .();
// Single status check for all updates

Version Vector - Understanding version vectors
Synchronization Guide - Complete sync patterns
PeerID Management - How peer IDs affect import

Cursor and Stable Positions PeerID Management