@stratasync/transport-graphql

@stratasync/transport-graphql · Strata Sync


import { createSyncClient } from "@stratasync/client";
import { createGraphQLTransport } from "@stratasync/transport-graphql";

const transport = createGraphQLTransport({
  endpoint: "https://api.example.com/graphql",
  syncEndpoint: "https://api.example.com/sync",
  wsEndpoint: "wss://api.example.com/sync/ws",
  auth: {
    getAccessToken: () => getTokenFromStore(),
    refreshToken: () => refreshAccessToken(),
  },
});

const client = createSyncClient({
  transport,
  // ... storage, reactivity
});

Method	Signature	Description
`bootstrap`	`(options: BootstrapOptions) => AsyncGenerator<ModelRow, BootstrapMetadata>`	Streams initial data via NDJSON.
`batchLoad`	`(options: BatchLoadOptions) => AsyncIterable<ModelRow>`	Batch loads specific model instances.
`mutate`	`(batch: TransactionBatch) => Promise<MutateResult>`	Sends a batch of mutations.
`subscribe`	`(options: SubscribeOptions) => DeltaSubscription`	Subscribes to real-time delta updates via WebSocket.
`fetchDeltas`	`(after: number, limit?: number) => Promise<DeltaPacket>`	Fetches deltas via REST for catch-up.
`getConnectionState`	`() => ConnectionState`	Returns the WebSocket connection state.
`onConnectionStateChange`	`(callback) => () => void`	Subscribes to connection state changes.
`close`	`() => Promise<void>`	Closes the WebSocket connection.


interface TransportOptions {
  /** GraphQL endpoint URL */
  endpoint: string;
  /** Base REST sync endpoint (such as https://api.example.com/sync) */
  syncEndpoint: string;
  /** WebSocket endpoint for subscriptions */
  wsEndpoint: string;
  /** Authentication provider */
  auth: AuthProvider;
  /** GraphQL mutation builder (optional -- uses REST mutations if omitted) */
  mutationBuilder?: GraphQLMutationBuilder;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Retry configuration */
  retry?: RetryConfig;
  /** Custom HTTP headers */
  headers?: Record<string, string>;
  /** Custom WebSocket implementation (for non-browser environments) */
  webSocketFactory?: typeof WebSocket;
}


interface AuthProvider {
  /** Gets the current access token */
  getAccessToken(): Promise<string | null>;
  /** Refreshes the access token (optional) */
  refreshToken?(): Promise<string | null>;
  /** Called when auth fails (optional) */
  onAuthError?(error: Error): void;
}


interface RetryConfig {
  /** Maximum number of retries */
  maxRetries: number;
  /** Base delay in milliseconds */
  baseDelay: number;
  /** Maximum delay in milliseconds */
  maxDelay: number;
  /** Jitter factor (0-1) for randomizing delays */
  jitter?: number;
}


const stream = transport.bootstrap({
  type: "full",
  schemaHash: "abc123",
  syncGroups: ["workspace-1"],
});

for await (const row of stream) {
  // row: { modelName: string, data: Record<string, unknown> }
  await storage.put(row.modelName, row.data);
}

// The return value contains metadata
const metadata = await stream.return(); // BootstrapMetadata


const stream = transport.batchLoad({
  firstSyncId: 12345,
  requests: [
    { modelName: "Task", groupId: "team-abc" },
    { modelName: "Comment", indexedKey: "taskId", keyValue: "task-123" },
  ],
});

for await (const row of stream) {
  await storage.put(row.modelName, row.data);
}


import type {
  GraphQLMutationBuilder,
  GraphQLMutationSpec,
} from "@stratasync/transport-graphql";

const mutationBuilder: GraphQLMutationBuilder = (transaction, index) => {
  const spec: GraphQLMutationSpec = {
    mutation: `taskUpdate(input: $input${index}) { syncId success }`,
    variables: { [`input${index}`]: transaction.payload },
    variableTypes: { [`input${index}`]: "TaskUpdateInput!" },
  };
  return spec;
};

const transport = createGraphQLTransport({
  mutationBuilder,
  // ...
});

Property	Type	Description
`mutation`	`string`	GraphQL field invocation (such as `taskUpdate(input: $input0) { syncId }`).
`variables`	`Record<string, unknown>`	Variables used by the mutation.
`variableTypes`	`Record<string, string>`	GraphQL variable type definitions.


const subscription = transport.subscribe({
  afterSyncId: 12345,
  groups: ["workspace-1"],
});

for await (const packet of subscription) {
  // packet: DeltaPacket { actions: SyncAction[], lastSyncId: number, hasMore: boolean }
  for (const action of packet.actions) {
    await applyAction(action);
  }
}

// Clean up
subscription.unsubscribe();

State	Description
`"disconnected"`	No active WebSocket connection.
`"connecting"`	Initial connection in progress.
`"reconnecting"`	Reconnecting after a disconnect.
`"connected"`	WebSocket is open and ready.
`"error"`	Connection failed after all retry attempts.


// Single page
const packet = await transport.fetchDeltas(lastSyncId, 1000);

// Paginated generator
for await (const action of fetchAllDeltas({
  afterSyncId: lastSyncId,
  auth,
  batchSize: 1000,
  syncEndpoint,
})) {
  await applyAction(action);
}


class YjsTransportAdapter implements YjsTransport {
  send(message: ClientMessage): void;
  onMessage(callback: (message: ServerMessage) => void): () => void;
  handleIncoming(message: ServerMessage): void;
  isConnected(): boolean;
}

Function	Description
`retryWithBackoff(fn, config, shouldRetry)`	Retries an async function with exponential backoff.
`calculateBackoff(attempt, config)`	Computes the delay for a given retry attempt with jitter.
`fetchWithTimeout(url, options, timeoutMs)`	Wraps `fetch()` with an `AbortController` timeout.
`isNetworkError(error)`	Checks for network-level errors (TypeError, ECONNREFUSED, and others).
`isTimeoutError(error)`	Checks for timeout/abort errors.
`isRetryableError(error)`	Returns `true` for network errors, timeouts, 5xx, and 429 status codes.
`isAuthError(error)`	Returns `true` for 401/403 or Unauthorized/Forbidden errors.
`parseSyncId(value)`	Validates a string-encoded sync ID without losing precision.


sync-core (defines TransactionBatch, DeltaPacket, and more)
  ^-- sync-y-doc (defines YjsTransport interface)
        ^-- sync-transport-graphql (implements TransportAdapter + YjsTransport)
              ^-- sync-client (uses adapter for all server communication)

@stratasync/transport-graphql

What it provides

Installation

Quick start

TransportAdapter interface

Configuration

TransportOptions

AuthProvider

RetryConfig

Bootstrap streaming

Mutations

REST mutations (default)

GraphQL mutations

WebSocket subscriptions

WebSocketManager

Connection states

Delta fetching

Yjs transport

Retry utilities

Architecture role