https://github.com/fsteff/hyperobjects
Transactional object store built on hypercore
https://github.com/fsteff/hyperobjects
database hypercore p2p
Last synced: 20 days ago
JSON representation
Transactional object store built on hypercore
- Host: GitHub
- URL: https://github.com/fsteff/hyperobjects
- Owner: fsteff
- License: mit
- Created: 2020-12-04T12:21:30.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-03-19T14:36:26.000Z (almost 3 years ago)
- Last Synced: 2025-08-09T08:23:33.029Z (5 months ago)
- Topics: database, hypercore, p2p
- Language: TypeScript
- Homepage:
- Size: 323 KB
- Stars: 13
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HyperObjects
Simple object store with transaction support, built on [hypercore](https://github.com/hypercore-protocol/hypercore).
## Features
- simple DB journal
- concurrent, atomic transactions
- the default merge handler merges transactions that change different objects
- but a custom one can be passed to each transaction
- throws an error and rolls back the transaction if a collision occures
- generates sequential object IDs to maximize efficiency
- internally uses an octree to store object-ID > hypercore index mappings
## Usage
```javascript
const feed = somehowCreateHypercore()
const db = new HyperObjects(feed, {valueEncoding: 'utf-8'})
let objId
await db.transaction(async tr => {
/**
* Creates a new Object
* @param value (optional) object value
* @param immediate {boolean} (default: false) if the changes should be written to the feed
* cannot be undone, is persisted even if the transaction fails!
* @returns {Promise<{id: number|null}>} id is set AFTER the transaction is over!
*/
objId = tr.create('hello world', false)
})
await db.transaction(async tr => {
/**
* Fetches the value of an object
* @param key {number} object ID
* @param immediate {boolean} (default: false) if the changes should be written to the feed
* cannot be undone, is persisted even if the transaction fails!
* @returns {Promise} the object
*/
const greeting = await tr.get(objId.id, false)
console.log(greeting)
})
await db.transaction(async tr => {
/**
* Overwrites the value of an existing object
* @param key {number} object ID
* @param value {any} object value
* @param immediate {boolean} (default: false) if the changes should be written to the feed
* cannot be undone, is persisted even if the transaction fails!
* @returns {Promise}
*/
await tr.set(objId.id, 'something else')
})
await db.transaction(async tr => {
/**
* Deletes an object's value (practically it's set to null)
* @param key {number} object ID
* @returns {Promise}
*/
await tr.delete(objId.id)
/**
* Undos the transaction (changes are not persisted)
* Theoretically it is possible to make changes after this again,
* the previous ones are simply removed from the queue
*/
tr.rollback()
})
```