add types

README.md

@@ -0,0 +1,177 @@
+# 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