Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hypertekorg/hyperstack/llms.txt

Use this file to discover all available pages before exploring further.

The TypeScript SDK provides a framework-agnostic client for connecting to Hyperstack servers. Built on AsyncIterables, it works with Node.js, Bun, Deno, and all modern JavaScript runtimes.

​
Installation

npm install hyperstack-typescript

​
Requirements

  • Node.js 16+ or any modern JavaScript runtime
  • A generated stack definition from the Hyperstack CLI

​
Quick Start

​
Connect to a Server

import { HyperStack } from 'hyperstack-typescript';
import { SETTLEMENT_GAME_STACK } from './generated/settlement-game-stack';

const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
  stack: SETTLEMENT_GAME_STACK,
});

​
Stream Real-time Updates

Use AsyncIterables to stream updates: 
// Stream all updates for a list view
for await (const update of hs.views.settlementGame.list.watch()) {
  if (update.type === 'upsert') {
    console.log('Game updated:', update.key, update.data);
  } else if (update.type === 'delete') {
    console.log('Game deleted:', update.key);
  }
}

// Stream updates for a specific entity
for await (const update of hs.views.settlementGame.state.watch('game-123')) {
  console.log('Game 123 updated:', update.data);
}

​
Rich Updates (Before/After)

Track changes with before/after diffs: 
for await (const update of hs.views.settlementGame.list.watchRich()) {
  if (update.type === 'updated') {
    console.log('Changed from:', update.before);
    console.log('Changed to:', update.after);
  } else if (update.type === 'created') {
    console.log('New game:', update.data);
  } else if (update.type === 'deleted') {
    console.log('Deleted game:', update.lastKnown);
  }
}

​
One-Shot Queries

Fetch current state without streaming: 
// Get all games
const games = await hs.views.settlementGame.list.get();
console.log(`Found ${games.length} games`);

// Get a specific game
const game = await hs.views.settlementGame.state.get('game-123');
if (game) {
  console.log('Game data:', game);
}

​
Synchronous Access

Access cached data synchronously (if available): 
// Returns immediately with cached data or undefined
const games = hs.views.settlementGame.list.getSync();
const game = hs.views.settlementGame.state.getSync('game-123');

​
API Reference

​
HyperStack

Main client class with typed view accessors.

​
Methods

​
connect
static async (url: string, options: ConnectOptions) => HyperStack
Connect to a HyperStack server.
const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
  stack: MY_STACK,
});
​
views
ViewAccessors
Typed view accessors based on your stack definition.
hs.views.settlementGame.list.watch()
hs.views.settlementGame.state.get('key')
​
connectionState
ConnectionState
Current connection state: 'connected' | 'connecting' | 'disconnected' | 'error'
console.log(hs.connectionState);
​
onConnectionStateChange
(callback: (state: ConnectionState) => void) => () => void
Listen for connection state changes. Returns an unsubscribe function.
const unsubscribe = hs.onConnectionStateChange((state) => {
  console.log('Connection state:', state);
});

// Later...
unsubscribe();
​
disconnect
async () => void
Disconnect from the server.
await hs.disconnect();

​
Views

Each view provides streaming and query methods.

​
StateView (Keyed Entities)

​
watch
(key: string) => AsyncIterable<Update<T>>
Stream updates for a specific key.
for await (const update of view.state.watch('game-123')) {
  console.log(update.data);
}
​
watchRich
(key: string) => AsyncIterable<RichUpdate<T>>
Stream rich updates with before/after diffs.
for await (const update of view.state.watchRich('game-123')) {
  if (update.type === 'updated') {
    console.log('Before:', update.before);
    console.log('After:', update.after);
  }
}
​
get
async (key: string) => T | undefined
Get entity by key.
const game = await view.state.get('game-123');
​
getSync
(key: string) => T | undefined
Get entity synchronously from cache.
const game = view.state.getSync('game-123');

​
ListView (Collections)

​
watch
() => AsyncIterable<Update<T>>
Stream all updates.
for await (const update of view.list.watch()) {
  console.log(update.type, update.key, update.data);
}
​
watchRich
() => AsyncIterable<RichUpdate<T>>
Stream rich updates with before/after diffs.
for await (const update of view.list.watchRich()) {
  console.log(update.type, update.key);
}
​
get
async () => T[]
Get all entities.
const games = await view.list.get();
​
getSync
() => T[]
Get all entities synchronously from cache.
const games = view.list.getSync();

​
Update Types

type Update<T> =
  | { type: 'upsert'; key: string; data: T }
  | { type: 'patch'; key: string; data: Partial<T> }
  | { type: 'delete'; key: string };

type RichUpdate<T> =
  | { type: 'created'; key: string; data: T }
  | { type: 'updated'; key: string; before: T; after: T; patch?: unknown }
  | { type: 'deleted'; key: string; lastKnown?: T };

​
Advanced Usage

​
Connection Management

Monitor and manage the WebSocket connection: 
const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
  stack: MY_STACK,
});

// Check connection state
if (hs.connectionState === 'connected') {
  console.log('Ready to stream');
}

// Listen for changes
const unsubscribe = hs.onConnectionStateChange((state) => {
  if (state === 'disconnected') {
    console.log('Connection lost, will auto-reconnect');
  } else if (state === 'connected') {
    console.log('Reconnected!');
  }
});

// Cleanup
await hs.disconnect();
unsubscribe();

​
Error Handling

Handle errors in streams: 
try {
  for await (const update of hs.views.settlementGame.list.watch()) {
    // Process update
  }
} catch (error) {
  console.error('Stream error:', error);
  // Stream will auto-reconnect and resume
}

​
Multiple Concurrent Streams

// Stream multiple views concurrently
const [gamesStream, playersStream] = await Promise.all([
  (async () => {
    for await (const update of hs.views.games.list.watch()) {
      console.log('Game update:', update);
    }
  })(),
  (async () => {
    for await (const update of hs.views.players.list.watch()) {
      console.log('Player update:', update);
    }
  })(),
]);

​
Examples

​
Real-time Game Leaderboard

import { HyperStack } from 'hyperstack-typescript';
import { GAME_STACK } from './generated/game-stack';

const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
  stack: GAME_STACK,
});

// Get initial leaderboard
const players = await hs.views.players.list.get();
const sorted = players.sort((a, b) => b.score - a.score);
console.log('Top 10:', sorted.slice(0, 10));

// Watch for score changes
for await (const update of hs.views.players.list.watchRich()) {
  if (update.type === 'updated') {
    const scoreDiff = update.after.score - update.before.score;
    console.log(`${update.key} scored ${scoreDiff} points!`);
  }
}

​
Track Token Price Changes

for await (const update of hs.views.tokens.list.watchRich()) {
  if (update.type === 'updated') {
    const prev = update.before.price;
    const curr = update.after.price;
    const change = ((curr - prev) / prev) * 100;
    
    if (Math.abs(change) > 1) {
      console.log(`${update.key}: ${change.toFixed(2)}% change`);
    }
  }
}

​
Next Steps

React SDK

Use the React SDK for hooks-based integration

CLI Reference

Generate SDKs with the Hyperstack CLI

Stack API

Learn about the Stack API concepts

GitHub

View source code and examples

Build docs developers (and LLMs) love

Get started for freeTalk to us