@stratasync/transport-graphql

GraphQL and REST transport adapter for sync communication, delta subscriptions, and Yjs collaborative editing in Strata Sync.

Implements TransportAdapter with NDJSON bootstrap streaming, REST/GraphQL mutations, WebSocket delta subscriptions, and Yjs collaborative editing: all with built-in retry and exponential backoff.

What it provides

createGraphQLTransport: factory function that creates a configured TransportAdapter instance
GraphQLTransportAdapter: the class implementing the full TransportAdapter interface
WebSocketManager: manages WebSocket connections for delta subscriptions with automatic reconnection
YjsTransportAdapter: bridges Yjs protocol messages over the WebSocket connection
Bootstrap streams: createBootstrapStream and createBatchLoadStream for NDJSON streaming
Delta fetching: fetchDeltas and fetchAllDeltas for REST-based catch-up
Mutation sending: sendMutations (GraphQL) and sendRestMutations (REST)
Retry utilities: retryWithBackoff, calculateBackoff, fetchWithTimeout, error classification helpers

Installation


npm install @stratasync/transport-graphql

@stratasync/transport-graphql has no peer dependencies. It depends on @stratasync/core and @stratasync/y-doc as workspace dependencies.

Quick start

@stratasync/transport-graphql

GraphQL and REST transport adapter for sync communication, delta subscriptions, and Yjs collaborative editing in Strata Sync.

Implements TransportAdapter with NDJSON bootstrap streaming, REST/GraphQL mutations, WebSocket delta subscriptions, and Yjs collaborative editing: all with built-in retry and exponential backoff.

What it provides

createGraphQLTransport: factory function that creates a configured TransportAdapter instance
GraphQLTransportAdapter: the class implementing the full TransportAdapter interface
WebSocketManager: manages WebSocket connections for delta subscriptions with automatic reconnection
YjsTransportAdapter: bridges Yjs protocol messages over the WebSocket connection
Bootstrap streams: createBootstrapStream and createBatchLoadStream for NDJSON streaming
Delta fetching: fetchDeltas and fetchAllDeltas for REST-based catch-up
Mutation sending: sendMutations (GraphQL) and sendRestMutations (REST)
Retry utilities: retryWithBackoff, calculateBackoff, fetchWithTimeout, error classification helpers

Installation


npm install @stratasync/transport-graphql

@stratasync/transport-graphql has no peer dependencies. It depends on @stratasync/core and @stratasync/y-doc as workspace dependencies.

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.

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.

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.

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.

@stratasync/transport-graphql

What it provides

Installation

Quick start

@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