wirekvs-js/README.md

# WireKVS-JS

A Node.js client for the WireKVS database service. This client provides a simple interface to interact with WireKVS databases, including real-time updates via WebSocket connections.

## Installation

```bash
npm install wirekvs-js
```

## Usage

There are two ways to use the WireKVS client:

### 1. Direct Database Connection

If you already have a database ID and access key, you can connect directly to the database:

```javascript
const WireKVS = require('wirekvs-js');

// Connect directly to a database
const db = WireKVS.connect('your-database-id', 'your-access-key');

// Set up real-time listeners with method chaining
db.on('connected', () => console.log('Connected'))
  .on('post', event => console.log('New value:', event))
  .on('error', error => console.error('Error:', error));

// Use the database
await db.set('key', 'value');
const value = await db.get('key');

// Disconnect when done
db.disconnect();
```

### 2. Using the Client for Database Management

If you need to create, list, or manage databases:

```javascript
const WireKVS = require('wirekvs-js');

// Initialize with your auth token
const client = new WireKVS('your-auth-token');

// Create a new database
const newDb = await client.createDatabase({
    name: 'My Database',
    allowPublicWrites: false,
    allowPublicReads: true,
    allowPublicModifications: false,
    allowSpecificPublicReads: false
});

// Connect to the new database using its access key
const db = client.database(newDb.kvsId, newDb.accessKey);

// Use the database...
await db.set('key', 'value');

// Disconnect when done
db.disconnect();
```

## Database Operations

### Basic Operations

```javascript
// Get all entries
const entries = await db.getAllEntries();

// Get a specific value
const value = await db.get('key');

// Set a value
await db.set('key', 'value');

// Update a value
await db.update('key', 'new value');

// Delete a value
await db.delete('key');

// Search for entries
const results = await db.search('searchTerm');
```

### Database Management

```javascript
// List all databases
const databases = await client.listDatabases();

// Update database settings
await client.updateDatabase(databaseId, {
    name: 'New Name',
    allowPublicReads: false
});

// Truncate a database
await client.truncateDatabase(databaseId);

// Delete a database
await client.deleteDatabase(databaseId);
```

## Real-time Updates

The database instance extends EventEmitter and provides real-time updates for all changes:

### Available Events

```javascript
// Connection events
db.on('connected', () => console.log('Connected'));
db.on('disconnected', () => console.log('Disconnected'));
db.on('error', error => console.error('Error:', error));

// Data events
db.on('post', event => console.log('New value set:', event.key, event.value));
db.on('patch', event => console.log('Value updated:', event.key, event.value));
db.on('delete', event => console.log('Value deleted:', event.key));
db.on('truncate', () => console.log('Database truncated'));
```

### Event Handling

```javascript
// Add event listeners with method chaining
db.on('event1', handler1)
  .on('event2', handler2);

// Remove specific event listener
db.off('event1', handler1);

// Remove all listeners for an event
db.off('event1');

// Disconnect and cleanup
db.disconnect(); // Removes all listeners and closes WebSocket
```

## Error Handling

All async methods will throw errors if the operation fails. It's recommended to use try-catch blocks:

```javascript
try {
    await db.set('key', 'value');
} catch (error) {
    if (error.response) {
        // Server responded with error
        console.error('Server error:', error.response.data);
    } else if (error.request) {
        // No response received
        console.error('No response:', error.request);
    } else {
        // Request setup error
        console.error('Error:', error.message);
    }
}
```

## Automatic Reconnection

The WebSocket connection automatically attempts to reconnect if disconnected unexpectedly. This ensures your real-time updates continue even after temporary network issues.

## Examples

Check out the `examples/demo.js` file for a complete working example of all features.

## License

MIT