npm package: @scriptdb/browser-client
Description: Browser WebSocket client for ScriptDB
Latest version: 1.1.3

# @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

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

## Usage

```typescript
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

```typescript
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:
```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

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

// Logout
await client.logout();
```

### Server Info

```typescript
const info = await client.getInfo();
```

### Low-level Execute

```typescript
// 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`:

```typescript
// 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:

```bash
# 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