Documentation

Installation

Install TerseJSON from npm:

npm install tersejson

Quick Start

1. Add the Express middleware

import express from 'express'
import { terse } from 'tersejson/express'

const app = express()

// Add TerseJSON middleware
app.use(terse())

app.get('/api/users', (req, res) => {
  res.json([
    { firstName: 'John', lastName: 'Doe' },
    { firstName: 'Jane', lastName: 'Smith' },
  ])
})

app.listen(3000)

2. Use the client wrapper

import { fetch } from 'tersejson/client'

// Drop-in replacement for fetch
const users = await fetch('/api/users').then(r => r.json())

// Access data normally
console.log(users[0].firstName) // "John"

How It Works

TerseJSON compresses repetitive JSON keys in API responses:

1. Server middleware intercepts JSON responses
2. Arrays of objects have their keys compressed to short aliases
3. A key mapping is sent with the response
4. Client wrapper transparently expands data using JavaScript Proxies
5. Your code continues to access original key names

This process is completely transparent - no changes needed to your business logic.

Configuration Options

app.use(terse({
  // Only compress arrays with 2+ items (default: 2)
  minArrayLength: 2,

  // Only compress keys with 3+ characters (default: 3)
  minKeyLength: 3,

  // Max nesting depth to traverse (default: 10)
  maxDepth: 10,

  // Key pattern: 'alpha' | 'numeric' | 'short' | 'prefixed'
  keyPattern: 'alpha',

  // Skip compression for specific routes
  shouldCompress: (req) => !req.path.includes('/graphql'),

  // Enable analytics
  analytics: {
    apiKey: 'your-api-key',
    projectId: 'my-api',
    reportToCloud: true
  }
}))