@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

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

For Apollo Client support:
`bash
npm install @protocol-lattice/graphql-binary-protocol @apollo/client graphql
`

Usage

$3

`typescript
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);
`

$3

`typescript
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 } }
});
`

$3

`typescript
interface GbpLinkOptions {
uri: string; // GraphQL endpoint
useGbp?: boolean; // Enable GBP (default: true)
compression?: 'raw' | 'gzip' | 'lz4'; // Preferred compression
headers?: Record; // 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