Skip to main content

​
JavaScript SDK Overview

The GLYPH JavaScript SDK provides a token-efficient serialization format optimized for LLM communication. It reduces token usage by 40-60% compared to JSON while maintaining full type safety and schema validation.

​
Installation

Install the GLYPH JavaScript SDK using your preferred package manager: 
npm install glyph-js

​
Requirements

  • Node.js >= 18.0.0
  • TypeScript >= 5.0 (optional, for TypeScript projects)

​
TypeScript Support

The SDK is written in TypeScript and includes full type definitions out of the box: 
import { GValue, Schema, SchemaBuilder, t, g, field } from 'glyph-js';

// Full IntelliSense and type checking
const schema: Schema = new SchemaBuilder()
  .addPackedStruct('User', 'v1')
    .field('id', t.id(), { fid: 1, wireKey: 'i' })
    .field('name', t.str(), { fid: 2, wireKey: 'n' })
  .build();

​
Quick Start

Here’s a complete example showing the core workflow: 
import { 
  g, field,
  SchemaBuilder, t,
  emitPacked, parsePacked,
  fromJson, toJson,
} from 'glyph-js';

// 1. Define a schema
const schema = new SchemaBuilder()
  .addPackedStruct('Team', 'v2')
    .field('id', t.id(), { fid: 1, wireKey: 't' })
    .field('name', t.str(), { fid: 2, wireKey: 'n' })
    .field('league', t.str(), { fid: 3, wireKey: 'l' })
  .build();

// 2. Create values using constructors
const team = g.struct('Team',
  field('id', g.id('t', 'ARS')),
  field('name', g.str('Arsenal')),
  field('league', g.str('EPL'))
);

// 3. Emit as packed GLYPH format
const packed = emitPacked(team, schema);
// => "Team@(^t:ARS Arsenal EPL)"

// 4. Parse back to GValue
const parsed = parsePacked(packed, schema);
console.log(parsed.get('name')?.asStr()); // => "Arsenal"

// 5. Convert from JSON
const json = { $type: 'Team', id: '^t:ARS', name: 'Arsenal', league: 'EPL' };
const fromJsonValue = fromJson(json, { schema, typeName: 'Team' });

// 6. Convert to JSON
const backToJson = toJson(fromJsonValue, { includeTypeMarkers: true });

​
Token Savings

GLYPH achieves significant token savings over JSON:
Data TypeToken Savings
LLM messages40%
Tool calls42%
Conversations (25 msgs)49%
Search results (50 rows)52%
Batch tool results62%
Measure token savings in your own data: 
import { compareTokens } from 'glyph-js';

const stats = compareTokens(jsonData, schema);
console.log(`JSON: ${stats.json} tokens`);
console.log(`GLYPH: ${stats.lyph} tokens`);
console.log(`Savings: ${stats.savingsPercent.toFixed(1)}%`);

​
Encoding Modes

GLYPH supports multiple encoding modes optimized for different use cases:

​
Packed Mode

Positional encoding with optional bitmap compression: 
import { emitPacked } from 'glyph-js';

const packed = emitPacked(value, schema);
// Dense: Team@(^t:ARS Arsenal EPL)
// Sparse: Match@{bm=0b101}(^m:123 2025-12-19T20:00:00Z 2 1)

​
Tabular Mode

Optimized for lists of structs: 
import { emitTabular } from 'glyph-js';

const tabular = emitTabular(listValue, schema);
// @tab Team [t n l]
// ^t:ARS Arsenal EPL
// ^t:LIV Liverpool EPL
// @end

​
Struct Mode

Named field encoding (v1 compatible): 
import { emit } from 'glyph-js';

const struct = emit(value, schema, { keyMode: 'name' });
// Team{id=^t:ARS name=Arsenal league=EPL}

​
Core Concepts

​
GValue

The universal value container for all GLYPH data. See Core Types for details.

​
Schema

Defines types, fields, and encoding rules. See Core Types for details.

​
Parsing

Converts GLYPH format strings back to GValue objects. See Parsing for details.

​
Streaming

Incremental validation for real-time LLM tool calls. See Streaming for details.

​
API Organization

The JavaScript SDK is organized into several modules:
  • Core: GValue, Schema, type constructors
  • JSON: JSON conversion utilities
  • Emit: GLYPH format encoders
  • Parse: GLYPH format parsers
  • Stream: Streaming transport (GS1) and validation
  • Patch: Delta encoding for updates
  • Loose: Schema-optional mode

​
Next Steps

Core Types

Learn about GValue, Schema, and type constructors

Parsing

Parse GLYPH format strings

Streaming

Real-time validation and GS1 transport

GitHub

View source and examples

Build docs developers (and LLMs) love

Get started for freeTalk to us