Skip to main content

WebSocket SDK

The WebSocket SDK provides a powerful way to interact with your Capela application in real-time. It's the recommended way to connect your frontend applications to Capela.

Overview​

The WebSocket SDK provides:

  • Real-time state synchronization
  • Automatic reconnection handling
  • Type-safe value access
  • Efficient caching and subscription management

Basic Usage​

import { getValue, setValue, subscribe } from 'capela-sdk';

// Get a value
const value = await getValue("!partition_id/variable_name");

// Set a value
await setValue("!partition_id/variable_name", new_value);

// Subscribe to changes
const unsubscribe = subscribe("!partition_id/variable_name", (newValue) => {
    console.log("Value changed:", newValue);
});

// Later, when you want to stop listening:
unsubscribe();

Advanced Features​

Caching​

The SDK automatically caches values to improve performance and reduce network traffic. The cache is automatically invalidated when values change.

Subscriptions​

The subscription system allows you to receive real-time updates when values change. Subscriptions are managed efficiently:

  • Multiple subscribers to the same path share a single WebSocket subscription
  • Subscriptions are automatically cleaned up when no listeners remain
  • Subscriptions are automatically re-established on reconnection

Type Safety​

The SDK provides type information for your values:

// Get type information
const type = await getType("!partition_id/variable_name");

// Type information includes:
// - objectType: The type name of the value
// - catType: Detailed type information

Error Handling​

The SDK provides robust error handling:

try {
    const value = await getValue("!partition_id/variable_name");
} catch (error) {
    console.error("Error fetching value:", error);
}

Children Access​

You can access child nodes of a path:

// List children of a path
const children = await listChildren("!partition_id/parent_path");

// Access nested values
const nestedValue = await getValue("!partition_id/parent_path/child_name");

Best Practices​

  1. Use Subscriptions for Real-time Updates: Instead of polling, use subscriptions to receive updates when values change.

  2. Clean Up Subscriptions: Always call the unsubscribe function when you no longer need updates to prevent memory leaks.

  3. Handle Reconnection: The SDK automatically handles reconnection, but you may want to show a loading state to users during reconnection.

  4. Use Type Information: Take advantage of the type system to ensure type safety in your application.

Example: Real-time Counter​

Here's a complete example of a real-time counter using the WebSocket SDK:

import { getValue, setValue, subscribe } from 'capela-sdk';

async function setupCounter(partitionId: string) {
    // Get initial value
    const count = await getValue(`${partitionId}/count`);
    updateDisplay(count);

    // Subscribe to changes
    const unsubscribe = subscribe(`${partitionId}/count`, (newCount) => {
        updateDisplay(newCount);
    });

    // Setup increment button
    document.getElementById('increment').onclick = async () => {
        const currentCount = await getValue(`${partitionId}/count`);
        await setValue(`${partitionId}/count`, currentCount + 1);
    };

    return unsubscribe;
}

function updateDisplay(count: number) {
    document.getElementById('counter').textContent = count.toString();
}

// Usage
const partitionId = "!your_partition_id";
const unsubscribe = await setupCounter(partitionId);

// Later, when the component is destroyed:
unsubscribe();

Next Steps​