@scriptdb/browser-client

Browser-compatible WebSocket client for ScriptDB. Provides the same API as @scriptdb/client but uses WebSocket instead of TCP, making it suitable for browser environments.

Installation

npm install @scriptdb/browser-client
# or
bun add @scriptdb/browser-client

Usage

import { BrowserClient } from '@scriptdb/browser-client';

// Create client with URI (same format as @scriptdb/client)
const client = new BrowserClient('scriptdb://localhost:1234', {
  username: 'user',
  password: 'pass',
  secure: false,        // Use ws:// instead of wss://
  requestTimeout: 30000,
  retries: 3,
});

// Connect and authenticate
await client.connect();

// List databases
const { databases } = await client.listDatabases();
console.log('Databases:', databases);

// Create a database
await client.createDatabase('mydb');

// Execute code
const result = await client.run(`
  export const greeting = "Hello, World!";
`, 'mydb');
console.log(result);

// Close connection
client.close();

Constructor

new BrowserClient(uri: string, options?: ClientOptions)

URI Format

Supports multiple URI formats:

• scriptdb://localhost:1234
• ws://localhost:1235
• http://localhost:1234 (converted to scriptdb://)

Credentials can be embedded in the URI:

new BrowserClient('scriptdb://user:pass@localhost:1234')

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | secure | boolean | true | Use secure WebSocket (wss://) | | username | string | - | Username for authentication | | password | string | - | Password for authentication | | requestTimeout | number | 120000 | Request timeout in ms (0 = disabled) | | retries | number | 3 | Number of reconnection attempts | | retryDelay | number | 1000 | Initial retry delay in ms | | maxPending | number | 100 | Max concurrent pending requests | | maxQueue | number | 1000 | Max queued requests | | logger | Logger | - | Custom logger with debug/info/warn/error | | tokenRefresh | function | - | Async function to refresh expired tokens |

API Methods

Connection

// Connect to server
await client.connect();

// Check connection status
client.connected; // boolean

// Close connection
client.close();

// Disconnect (alias for close)
await client.disconnect();

// Destroy client completely (stops reconnection)
client.destroy();

Database Operations

// List all databases
const { databases, count } = await client.listDatabases();

// Create a database
await client.createDatabase('mydb');

// Remove a database
await client.removeDatabase('mydb');

// Rename a database
await client.renameDatabase('oldname', 'newname');

// Save database to disk
await client.saveDatabase('mydb');

// Update database metadata
await client.updateDatabase('mydb', { /* metadata */ });

Code Execution

// Execute code in a database
const result = await client.run(`
  export const data = { message: "Hello" };
  console.log("Executed!");
`, 'mydb');

// Result contains:
// - namespace: exported values
// - logs: console output

Authentication

// Login with credentials
await client.login('username', 'password');

// Logout
await client.logout();

Server Info

const info = await client.getInfo();

Low-level Execute

// Execute arbitrary command
const result = await client.execute({
  action: 'script-code',
  data: { code: '...', databaseName: 'mydb' }
});

Features

• URI Parsing: Supports scriptdb://, ws://, http:// URIs
• Auto-reconnect: Automatic reconnection with exponential backoff
• Token Management: Automatic token handling and refresh support
• Request Queue: Handles concurrent requests with queue management
• Logging: Configurable logging with automatic credential masking
• TypeScript: Full TypeScript support

WebSocket Proxy

This client connects to a WebSocket proxy server (typically running on TCP port + 1). The proxy handles communication with the ScriptDB TCP server.

Browser -> WebSocket (port 1235) -> Proxy -> TCP (port 1234) -> ScriptDB Server

Compatibility with @scriptdb/client

The API is designed to be compatible with @scriptdb/client:

// Node.js (TCP)
import { ScriptDBClient } from '@scriptdb/client';

// Browser (WebSocket)
import { ScriptDBClient } from '@scriptdb/browser-client';

// Same API
const client = new ScriptDBClient('scriptdb://localhost:1234', options);
await client.connect();

CLI Tool

ScriptDB also provides a CLI tool for server management:

# Install CLI globally
npm install -g @scriptdb/cli

# Start server
scriptdb start

# Start server in background (daemon mode with PM2)
scriptdb start -d

# Check server status
scriptdb status

# View real-time logs
scriptdb logs

# Monitor performance
scriptdb monit

# Stop server
scriptdb stop

# Restart server
scriptdb restart -d

# Start interactive shell
scriptdb shell

Changelog

1.1.2 (2025-01-16)

Added

• Native scriptdb logs command to view real-time logs
• Native scriptdb monit command to monitor performance
• Native scriptdb restart command to restart the server
• Native scriptdb stop command to stop the server
• ESLint configuration for TypeScript linting

Fixed

• Fixed TypeScript module resolution errors
• Improved error handling and Windows compatibility

License

MIT