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

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:

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:

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

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

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

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

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

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