npm package: @plaindb/storage
Description: A storage interface and base class for building custom database storage adapters.
Author: Basedwon
Latest version: 0.0.6

# Storage

[![npm](https://img.shields.io/npm/v/@plaindb/storage?style=flat&logo=npm)](https://www.npmjs.com/package/@plaindb/storage)
[![pipeline](https://gitlab.com/frenware/framework/plaindb/storage/badges/master/pipeline.svg)](https://gitlab.com/frenware/framework/plaindb/storage/-/pipelines)
[![license](https://img.shields.io/npm/l/@plaindb/storage)](https://gitlab.com/frenware/framework/plaindb/storage/-/blob/master/LICENSE)
[![downloads](https://img.shields.io/npm/dw/@plaindb/storage)](https://www.npmjs.com/package/@plaindb/storage) 

[![Gitlab](https://img.shields.io/badge/Gitlab%20-%20?logo=gitlab&color=%23383a40)](https://gitlab.com/frenware/framework/plaindb/storage)
[![Github](https://img.shields.io/badge/Github%20-%20?logo=github&color=%23383a40)](https://github.com/basedwon/@plaindb/storage)
[![Twitter](https://img.shields.io/badge/@basdwon%20-%20?logo=twitter&color=%23383a40)](https://twitter.com/basdwon)
[![Discord](https://img.shields.io/badge/Basedwon%20-%20?logo=discord&color=%23383a40)](https://discordapp.com/users/basedwon)

A highly modular storage interface and base class for building custom database storage adapters.

## Features

- **Standardized API**: Offers a consistent way to interact with different storage backends.
- **Async/Await Support**: Built with native promise support for modern JavaScript workflows.
- **Iterator Support**: Asynchronous iterator function for traversing through stored keys.
- **Sub-storage**: Create sub-storages with a specified path.

## Installation

Install the package with:

```bash
npm install @plaindb/storage
```

## Usage

First, import the `Storage` library.

```js
import Storage from '@plaindb/storage'
```
or
```js
const Storage = require('@plaindb/storage')
```

```js
// create a storage instance:
const storage = new Storage()

// or, extend Storage to create a custom storage adapter:
class MyCustomStorage extends Storage {
  async _connect() {
    // Implement your connect logic here
  }
  async _disconnect() {
    // Implement your disconnect logic here
  }
}

const myStorage = new MyCustomStorage()
```

## Documentation

- [API Reference](/docs/api.md)

### Interface (IStorage)

The `IStorage` interface class provides the following methods which need to be implemented:

- `connect()`: Initialize the storage connection.
- `disconnect()`: Close the storage connection.
- `getNativeConnection()`: Retrieve the native client/connection object.
- `get(key)`: Retrieve a value by key.
- `put(key, value)`: Store a value by key.
- `del(key)`: Delete a value by key.
- `iterator(opts)`: Asynchronous iterator for key-value pairs.
- `sub(path, opts)`: Create a sub-storage with a specified path.

## Methods

### `connect()`

Connects to the storage backend.

### `disconnect()`

Disconnects from the storage backend.

### `get(key)`

Retrieves a value from the storage by key.

```js
const value = await storage.get('someKey')
```

### `put(key, value)`

Stores a value in the storage by key.

```js
await storage.put('someKey', 'someValue')
```

### `del(key)`

Deletes a value from the storage by key.

```js
await storage.del('someKey')
```

### `iterator(opts)`

Returns an asynchronous iterator for key-value pairs.

```js
for await (const { key, value } of storage.iterator()) {
  console.log(key, value)
}
```

### `sub(path, opts)`

Creates a sub-storage with a specified path.

```js
const subStorage = storage.sub('some/path')
```

## Events

- `error`: Emitted when there is an error in connecting or disconnecting.

```js
storage.on('error', (err) => {
  console.error(`Error: ${err}`)
})
```

## Tests

In order to run the test suite, simply clone the repository and install its dependencies:

```bash
git clone https://gitlab.com/frenware/framework/plaindb/storage.git
cd basd
npm install
```

To run the tests:

```bash
npm test
```

## Contributing

Thank you! Please see our [contributing guidelines](/docs/contributing.md) for details.

## Donations

If you find this project useful and want to help support further development, please send us some coin. We greatly appreciate any and all contributions. Thank you!

**Bitcoin (BTC):**
```
1JUb1yNFH6wjGekRUW6Dfgyg4J4h6wKKdF
```

**Monero (XMR):**
```
46uV2fMZT3EWkBrGUgszJCcbqFqEvqrB4bZBJwsbx7yA8e2WBakXzJSUK8aqT4GoqERzbg4oKT2SiPeCgjzVH6VpSQ5y7KQ
```

## License

@plaindb/storage is [MIT licensed](https://gitlab.com/frenware/framework/plaindb/storage/-/blob/master/LICENSE).