HPKV SDK Guides

Node.js REST SDK Reference

HPKVRestClient

The main client class for performing CRUD operations over HTTP.

Methods

class HPKVRestClient {
constructor(apiKey: string, baseUrl: string);

set(key: string, value: unknown, partialUpdate?: boolean): Promise<RecordResponse>
//Set a value for a key. If partialUpdate is true, the value will be appended to the existing. If the existing and new values are valid JSON, it performs an atomic JSON patching.

get(key: string): Promise<RecordResponse>
//Get a value by key.

delete(key: string): Promise<RecordResponse>
//Delete a key-value pair.

atomicIncrement(key: string, increment: number): Promise<RecordResponse>
//Increment or decrement a numeric value atomically.

range(startKey: string, endKey: string, limit=100): Promise<RangeResponse>
//Query records within a key range.

nexusSearch(query: string, options?: SearchOptions): Promise<SearchResponse>
//Perform semantic search using Nexus Search.

nexusQuery(query: string, options?: QueryOptions): Promise<QueryResponse>
//Get AI-generated answers using Nexus Query.


}

Node.js WebSocket SDK Reference

HPKVClientFactory

The main factory class for creating API and Subscription clients.

Methods

class HPKVClientFactory {
  /**
   * Creates an API client for CRUD operations using API key
   */
  static createApiClient(apiKey: string, baseUrl: string): HPKVApiClient;
  
  /**
   * Creates a subscription client for real-time monitoring and access-controlled CRUD operations
   */
  static createSubscriptionClient(token: string, baseUrl: string): HPKVSubscriptionClient;
}

BaseWebSocketClient

Base client class that handles WebSocket connections, reconnection logic, and common CRUD operations.

Constructor

constructor(baseUrl: string, config?: ConnectionConfig);

Methods

interface BaseWebSocketClient {
  /**
   * Connects to the WebSocket server
   * Must be called before any other method
   */
  connect(): Promise<void>;
  
  /**
   * Disconnects from the WebSocket server
   * @param cancelPendingRequests - Whether to cancel all pending requests (default: true)
   */
  disconnect(cancelPendingRequests?: boolean): Promise<void>;
  
  /**
   * Gets the value associated with the specified key
   * @param key - The key to get the value of
   * @param timeoutMs - Optional custom timeout for this operation
   */
  get(key: string, timeoutMs?: number): Promise<HPKVResponse>;
  
  /**
   * Sets a key-value pair
   * @param key - The key to set the value of
   * @param value - The value to set
   * @param partialUpdate - If true, performs a merge/patch instead of replacing the value
   * @param timeoutMs - Optional custom timeout for this operation
   */
  set(key: string, value: unknown, partialUpdate?: boolean, timeoutMs?: number): Promise<HPKVResponse>;
  
  /**
   * Deletes the specified key
   * @param key - The key to delete
   * @param timeoutMs - Optional custom timeout for this operation
   */
  delete(key: string, timeoutMs?: number): Promise<HPKVResponse>;
  
  /**
   * Performs a range query to retrieve multiple records
   * @param key - The key to start the range query from
   * @param endKey - The key to end the range query at
   * @param options - Optional range query options
   * @param timeoutMs - Optional custom timeout for this operation
   */
  range(key: string, endKey: string, options?: RangeQueryOptions, timeoutMs?: number): Promise<HPKVResponse>;
  
  /**
   * Atomically increments or decrements a numeric value
   * @param key - The key to increment or decrement
   * @param value - The amount to increment or decrement by
   * @param timeoutMs - Optional custom timeout for this operation
   */
  atomicIncrement(key: string, value: number, timeoutMs?: number): Promise<HPKVResponse>;
  
  /**
   * Register event listeners for connection events
   * @param event - The event to listen for
   * @param listener - The listener to call when the event occurs
   */
  on(event: 'connected' | 'disconnected' | 'reconnecting' | 'reconnectFailed', listener: (...args: any[]) => void): void;
  
  /**
   * Remove event listeners
   * @param event - The event to remove the listener from
   * @param listener - The listener to remove
   */
  off(event: 'connected' | 'disconnected' | 'reconnecting' | 'reconnectFailed', listener: (...args: any[]) => void): void;
  
  /**
   * Get the current connection state
   */
  getConnectionState(): ConnectionState;
  
  /**
   * Get current connection statistics
   */
  getConnectionStats(): ConnectionStats;

  /**
   * Clean up resources when instance is no longer needed
   */
  destroy(): void;
}

HPKVApiClient

Client for CRUD operations using API key authentication.

Constructor

constructor(apiKey: string, baseUrl: string, config?: ConnectionConfig);

Methods

Inherits all methods from BaseWebSocketClient.

HPKVSubscriptionClient

Client for real-time key monitoring (Pub-Sub) and access-controlled CRUD operations. Access is controlled by the subscription token.

Constructor

constructor(token: string, baseUrl: string, config?: ConnectionConfig);

Methods

Inherits all methods from BaseWebSocketClient.

interface HPKVSubscriptionClient extends BaseWebSocketClient {
  /**
   * Subscribes to changes for keys covered by the subscription token
   * @param callback Function to call when key values change
   * @returns callback id
   */
  subscribe(callback: HPKVEventHandler): string;
  
  /**
   * Unsubscribes the callback from the subscription
   */
  unsubscribe(callbackId: string): void;
}

WebsocketTokenManager

Manages token generation for subscription clients. Should only be used on the server side.

Constructor

constructor(apiKey: string, baseUrl: string);

Methods

class WebsocketTokenManager {
  /**
   * Generates a token for subscription client
   * @returns A subscription token
   */
  generateToken(config: HPKVTokenConfig): Promise<string>;
}

Type Definitions

ConnectionConfig

interface ConnectionConfig {
  maxReconnectAttempts?: number;
  initialDelayBetweenReconnects?: number;
  maxDelayBetweenReconnects?: number;
}

ConnectionStats

interface ConnectionStats {
  isConnected: boolean;
  reconnectAttempts: number;
  messagesPending: number;
  connectionState: string;
  queueSize: number;
}

ConnectionState

enum ConnectionState {
  CONNECTED = 1,
  DISCONNECTED = 2,
  RECONNECTING = 3,
  RECONNECT_FAILED = 4
}

HPKVTokenConfig

interface HPKVTokenConfig {
  /**
   * Keys to subscribe to for real-time monitoring
   */
  subscribeKeys: string[];
  
  /**
   * Regex pattern for keys that the client can perform CRUD operations on
   */
  accessPattern?: string;
}

RangeQueryOptions

interface RangeQueryOptions {
  limit?: number;
}

HPKVResponse

interface HPKVResponse {
  type?: string;
  code: number;
  message?: string;
  messageId?: number;
  key?: string;
  value?: string | number;
  newValue?: number;
  error?: string;
  success?: boolean;
  records?: Array<{
    key: string;
    value: string;
  }>;
  count?: number;
  truncated?: boolean;
  timestamp?: number;
}

HPKVEventHandler

type HPKVEventHandler = (data: HPKVResponse) => void;

Node.js SDK Reference

RiocClient

The main client class for interacting with HPKV through RIOC.

Constructor

class RiocClient {
  constructor(config: RiocConfig);
}

Creates a new RIOC client with the specified configuration.

Properties

class RiocClient {
  readonly isDisposed: boolean;  // Whether the client has been disposed
}

Methods

class RiocClient {
  /**
   * Gets a timestamp for write operations.
   * This method provides accurate timing for operations, though using local system time is also acceptable.
   */
  static getTimestamp(): bigint;
  
  /**
   * Retrieves the value associated with the specified key
   */
  get(key: Buffer): Buffer;
  
  /**
   * Retrieves multiple records within a key range
   */
  rangeQuery(startKey: Buffer, endKey: Buffer, limit?: number): { key: Buffer, value: Buffer }[];
  
  /**
   * Inserts or updates a key-value pair
   */
  insert(key: Buffer, value: Buffer, timestamp: bigint): void;
  
  /**
   * Deletes the specified key
   */
  delete(key: Buffer, timestamp: bigint): void;
  
  /**
   * Atomically increments or decrements a numeric value
   * @param key The key of the value to increment/decrement
   * @param increment The amount to increment (positive) or decrement (negative)
   * @param timestamp The operation timestamp
   * @returns The new value after the operation
   */
  atomicIncDec(key: Buffer, increment: number, timestamp: bigint): number;
  
  /**
   * Creates a new batch for executing multiple operations
   */
  createBatch(): RiocBatch;
  
  /**
   * Disposes of the client and releases all resources
   */
  dispose(): void;
}

String Helper Methods

class RiocClient {
  /**
   * Gets a value as a string
   */
  getString(key: string): string;
  
  /**
   * Inserts a string value
   */
  insertString(key: string, value: string, timestamp: bigint): void;
  
  /**
   * Deletes a key (string version)
   */
  deleteString(key: string, timestamp: bigint): void;
  
  /**
   * Performs a range query with string keys and values
   */
  rangeQueryString(startKey: string, endKey: string, limit?: number): { key: string, value: string }[];
  
  /**
   * Atomically increments or decrements a numeric value (string version)
   * @returns The new value after the operation
   */
  atomicIncDecString(key: string, increment: number, timestamp: bigint): number;
}

RiocBatch

Represents a batch of operations to be executed together.

Methods

class RiocBatch {
  /**
   * Adds a get operation to the batch
   */
  addGet(key: Buffer): void;
  
  /**
   * Adds a range query operation to the batch
   */
  addRangeQuery(startKey: Buffer, endKey: Buffer, limit?: number): void;
  
  /**
   * Adds an insert operation
   */
  addInsert(key: Buffer, value: Buffer, timestamp: bigint): void;
  
  /**
   * Adds a delete operation
   */
  addDelete(key: Buffer, timestamp: bigint): void;
  
  /**
   * Executes the batch asynchronously
   */
  executeAsync(): RiocBatchTracker;
  
  /**
   * Disposes of the batch and releases all resources
   */
  dispose(): void;
}

RiocBatchTracker

Tracks the execution of a batch operation.

Methods

class RiocBatchTracker {
  /**
   * Waits for the batch operation to complete
   */
  wait(timeoutMs: number): void;
  
  /**
   * Gets the response for a GET operation
   */
  getResponse(index: number): Buffer;
  
  /**
   * Gets the response for a RANGE QUERY operation
   */
  getRangeQueryResponse(index: number): { key: Buffer, value: Buffer }[];
  
  /**
   * Disposes of the tracker and releases all resources
   */
  dispose(): void;
}

Configuration Types

RiocConfig

interface RiocConfig {
  host: string;          // The host to connect to
  port: number;          // The port to connect to
  timeoutMs?: number;    // Operation timeout in milliseconds (default: 5000)
  tls?: RiocTlsConfig;  // TLS configuration
}

RiocTlsConfig

interface RiocTlsConfig {
  caPath: string;           // CA certificate path
  certificatePath: string;  // Client certificate path
  keyPath: string;         // Client private key path
  verifyHostname: string;  // Server hostname to verify
  verifyPeer: boolean;     // Enable certificate verification
}

Error Types

• RiocError

  Base error class for all RIOC errors.

• RiocTimeoutError

  Thrown when an operation times out.

• RiocConnectionError

  Thrown when there are connection issues.