kvstore-client

A TypeScript/JavaScript client library for managing key-value storage operations through REST API. This library provides a comprehensive interface for interacting with remote key-value stores, including user management, database operations, and CRUD operations.

Features

• 🔐 User Authentication - Register, login, and token management
• 🗄️ Database Management - Create, list, and delete databases
• 📦 Store Operations - Create, manage, and delete stores within databases
• 🔑 Key-Value Operations - Full CRUD operations with batch support
• 📝 TypeScript Support - Full type safety and IntelliSense
• 🌐 REST API Integration - Clean HTTP-based communication
• ⚡ Zero Dependencies - Lightweight with no external dependencies

Installation

npm install kvstore-client

Quick Start

import { KVStore } from 'kvstore-client';

// Initialize the client
const store = new KVStore('https://your-api-endpoint.com/connect', {
  accessToken: 'your-access-token',
  storeName: 'my-store',
  dbName: 'my-database'
});

// Set and get values
await store.set('user:123', { name: 'John Doe', email: '[email protected]' });
const user = await store.get('user:123');
console.log(user); // { name: 'John Doe', email: '[email protected]' }

API Reference

Constructor

const store = new KVStore(apiUrl: string, options: KVStoreOptions)

Parameters:

• apiUrl: The REST API endpoint URL
• options: Configuration object
  • accessToken: Authentication token
  • storeName: Name of the store to operate on
  • dbName: Name of the database to operate on

User Management

Register a new user

await store.register({
  username: 'john_doe',
  email: '[email protected]',
  password: 'secure123'
});

Login

await store.login({
  username: 'john_doe',
  password: 'secure123'
});

Generate authentication token

const tokenResponse = await store.generateToken();

Get user information

const userInfo = await store.getUserInfo();

Database Operations

List databases

const databases = await store.getDatabases();

Create a database

await store.createDatabase('new-database');

Delete a database

await store.deleteDatabase('database-name');

Store Operations

Get stores in a database

const stores = await store.getStores('database-name');

Create a store

await store.createStore('database-name', 'store-name');

Delete a store

await store.deleteStore('database-name', 'store-name');

Key-Value Operations

Set a value

await store.set('key', 'value');
await store.set('user:123', { name: 'John', age: 30 });

Get a value

const value = await store.get('key');

Update a value

await store.update('key', 'new-value');

Delete a key

await store.delete('key');

Batch Operations

Set multiple values

await store.setMany([
  { key: 'user:1', value: { name: 'Alice' } },
  { key: 'user:2', value: { name: 'Bob' } }
]);

Get multiple values

const values = await store.getMany(['user:1', 'user:2']);

Delete multiple keys

await store.deleteMany(['key1', 'key2', 'key3']);

Store Inspection

Get all keys

const keys = await store.keys();

Get all values

const values = await store.values();

Get all entries

const entries = await store.entries('database-name', 'store-name');

Clear all data

await store.clear(); // ⚠️ This cannot be undone

Account Management

Change password

await store.changePassword('currentPassword123', 'newSecurePassword456');

Delete account

await store.deleteAccount('password123', 'DELETE'); // ⚠️ This cannot be undone

Factory Function (Legacy)

For backward compatibility, you can also use the factory function:

import { store } from 'kvstore-client';

const kvStore = store('https://api.example.com/connect', {
  accessToken: 'token',
  storeName: 'mystore',
  dbName: 'mydb'
});

TypeScript Interfaces

The library provides full TypeScript support with the following interfaces:

interface KVStoreOptions {
  accessToken: string;
  storeName: string;
  dbName: string;
}

interface RegisterFormData {
  username: string;
  email: string;
  password: string;
  [key: string]: any;
}

interface LoginFormData {
  username: string;
  password: string;
  [key: string]: any;
}

interface KVEntry {
  key: string;
  value: any;
}

interface APIResponse<T = any> {
  success?: boolean;
  error?: string;
  data?: T;
  [key: string]: any;
}

Error Handling

All methods return promises and will throw errors for failed requests:

try {
  await store.set('key', 'value');
} catch (error) {
  console.error('Operation failed:', error.message);
}

Requirements

• Node.js >= 14.0.0
• Modern browsers with fetch support

Development

# Build the library
npm run build

# Run tests
npm test

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Sebastian Korotkiewicz

• GitHub: @skorotkiewicz
• Repository: kvstore-client

Support

If you encounter any issues or have questions, please open an issue on GitHub.