update

modules/storage/rocksdb.md

@@ -1,13 +1,94 @@
-# rocksdb-native - KV Storage
+# rocksdb-native
+
+RocksDB bindings for JavaScript (via librocksdb).
+
+## Install
+
+```sh
+npm i rocksdb-native
+```
 
 ## Overview
 
-RocksDB bindings for hyperblobs/hypercore-storage alt.
+`rocksdb-native` provides a JavaScript API for RocksDB, backed by `librocksdb`. It supports read/write batches and is used for local-only storage.
 
-**Feat**: SSD-opt LSM tree, compaction.
+## API
 
-**Hyper**: Persistent blobs beyond flat-tree.
+### `new RocksDB(path)`
 
-**Ex**: new RocksDB(path)
+### Write batch
 
-**Source**: github/rocksdb-native
+- `const w = db.write()`
+- `w.put(key, value)`
+- `w.del(key)`
+- `await w.flush()`
+
+### Read batch
+
+- `const r = db.read()`
+- `const p = r.get(key)`
+- `r.flush()`
+
+## Examples
+
+### Basic write/read
+
+```js
+const RocksDB = require('rocksdb-native')
+
+const db = new RocksDB('./example.db')
+const w = db.write()
+w.put('hello', 'world')
+await w.flush()
+
+const r = db.read()
+const p = r.get('hello')
+r.flush()
+console.log(await p)
+```
+
+### Batch deletes
+
+```js
+const w = db.write()
+w.del('old-key')
+await w.flush()
+```
+
+### Multiple reads
+
+```js
+const r = db.read()
+const a = r.get('a')
+const b = r.get('b')
+r.flush()
+console.log(await a, await b)
+```
+
+## Best Practices
+
+- Use batches to reduce write amplification.
+
+## Performance
+
+- LSM-tree storage performs well on SSDs and large datasets.
+
+## Security
+
+- Store databases in protected directories.
+
+## Error Handling
+
+- Handle errors on `flush()` for I/O failures.
+
+## Integration
+
+- Used by local Hypercore storage and indexing tools.
+
+## Notes
+
+- On Linux, `libatomic` must be installed.
+
+## License
+
+Apache-2.0