@protocol-lattice/graphql-binary-protocol

High-performance GraphQL Binary Protocol (GBP) decoder and Apollo Client Link for TypeScript.

GBP is a structural binary encoding specifically designed for GraphQL responses, achieving up to 99% compression ratios by performing cross-request and intra-request structural deduplication.

Features

• Structural Deduplication: Efficiently handles highly redundant GraphQL data.
• Columnar Encoding: Optimized for large arrays of objects.
• Ultra-Fast: ~75 MB/s decode throughput in JavaScript.
• Apollo Client Integration: Drop-in replacement for HttpLink.
• Multiple Compression: Supports raw GBP, Gzip, and LZ4.

Installation

npm install @protocol-lattice/graphql-binary-protocol

For Apollo Client support:

npm install @protocol-lattice/graphql-binary-protocol @apollo/client graphql

Usage

Standalone Decoder

import { GbpDecoder } from '@protocol-lattice/graphql-binary-protocol';

const decoder = new GbpDecoder();

// Decode raw GBP
const response = decoder.decode(uint8Array);

// Decode Gzip-compressed GBP
const gzipResponse = decoder.decodeGzip(gzipUint8Array);

// Decode LZ4-compressed GBP
const lz4Response = decoder.decodeLz4(lz4Uint8Array);

console.log(response.data);

Apollo Client Integration

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { GbpLink } from '@protocol-lattice/graphql-binary-protocol';

const client = new ApolloClient({
  link: new GbpLink({ 
    uri: 'http://localhost:4000/graphql',
    // Optional: prefer specific compression
    compression: 'gzip' // 'raw' | 'gzip' | 'lz4'
  }),
  cache: new InMemoryCache()
});

// Use as normal - GBP compression is automatic!
const { data } = await client.query({
  query: gql`{ users { id name } }`
});

GbpLink Options

interface GbpLinkOptions {
  uri: string;                          // GraphQL endpoint
  useGbp?: boolean;                     // Enable GBP (default: true)
  compression?: 'raw' | 'gzip' | 'lz4'; // Preferred compression
  headers?: Record<string, string>;     // Additional headers
  credentials?: RequestCredentials;     // Fetch credentials mode
  fetch?: typeof fetch;                 // Custom fetch (for SSR)
}

Performance

Metric	Value
Decode Throughput	~75 MB/s
Compression Ratio	90-99%
Bundle Size	4KB gzipped

Protocol Details

GBP (v8) uses a multi-pass encoding strategy:

1. String Pooling: All strings are deduplicated and indexed.
2. Shape Pooling: Object keys are hashed and indexed into "shapes".
3. Value Pooling: Identical sub-trees (objects/arrays) are deduplicated.
4. Columnar Transformation: Large arrays of objects are transposed for better compression.

Server Support

GBP encoding is provided by grpc_graphql_gateway.

License

MIT