mirror of https://codeberg.org/pzp/pzp-db.git
205 lines
7.3 KiB
Markdown
205 lines
7.3 KiB
Markdown
# pzp-db
|
|
|
|
The message database for PZP.
|
|
|
|
## Installation
|
|
|
|
|
|
```
|
|
npm install pzp-db
|
|
```
|
|
|
|
## Usage
|
|
|
|
It's a secret-stack plugin much like ssb-db2. Other than that, you can also use
|
|
the feed format `const FeedV1 = require('pzp-db/feed-v1')`.
|
|
|
|
You can use it like
|
|
|
|
```js
|
|
const p = require('node:util').promisify
|
|
|
|
const keypair = Keypair.generate('ed25519', 'alice')
|
|
const DIR = path.join(os.tmpdir(), 'pzp-db-temp')
|
|
|
|
const pzp = require('secret-stack/bare')()
|
|
.use(require('secret-stack/plugins/net'))
|
|
.use(require('secret-handshake-ext/secret-stack'))
|
|
.use(require('pzp-db'))
|
|
.use(require('ssb-box'))
|
|
.call(null, {
|
|
shse: { caps: require('pzp-caps')
|
|
},
|
|
global: {
|
|
keypair,
|
|
path: DIR
|
|
}
|
|
})
|
|
|
|
|
|
await pzp.db.loaded()
|
|
|
|
const account = await p(pzp.db.account.create)({
|
|
keypair,
|
|
subdomain: 'person',
|
|
})
|
|
|
|
const record = await p(pzp.db.feed.publish)({
|
|
account,
|
|
domain: 'post',
|
|
data: { text: 'I am 1st post' },
|
|
})
|
|
|
|
console.log("account:", account, "record:", JSON.stringify(record, null, 2))
|
|
|
|
//account: 8VLSqiWCX26w1173212RBRvY8N7MEbY3ar8fv22cGx6b record: {
|
|
// "id": "H8dQH6LzeW2He7oRVXKP6u6WbC1GQ8EABh3PgS587L3w",
|
|
// "msg": {
|
|
// "data": {
|
|
// "text": "I am 1st post"
|
|
// },
|
|
// "metadata": {
|
|
// "dataHash": "39FJFLNXj7L83nFJbrrbADdKCeFe2vP2ikuNZXVKYSXP",
|
|
// "dataSize": 24,
|
|
// "account": "8VLSqiWCX26w1173212RBRvY8N7MEbY3ar8fv22cGx6b",
|
|
// "accountTips": [
|
|
// "8VLSqiWCX26w1173212RBRvY8N7MEbY3ar8fv22cGx6b"
|
|
// ],
|
|
// "tangles": {
|
|
// "9HdQRpQNHgxiuxRy8eSEvEDG3nAL4EAYYkYHiHbU7Xqo": {
|
|
// "depth": 1,
|
|
// "prev": [
|
|
// "9HdQRpQNHgxiuxRy8eSEvEDG3nAL4EAYYkYHiHbU7Xqo"
|
|
// ]
|
|
// }
|
|
// },
|
|
// "domain": "post",
|
|
// "v": 4
|
|
// },
|
|
// "sigkey": "4mjQ5aJu378cEu6TksRG3uXAiKFiwGjYQtWAjfVjDAJW",
|
|
// "sig": "WNY4WZiT3SLQKFn4J6ESLn8WqPfLRh5fPdTiZTkvDNf5u79wFmXv367UV93XjyzACi6C3fgwZkstq5JczCk3YPH"
|
|
// },
|
|
// "received": 1712503926457
|
|
//}
|
|
```
|
|
|
|
## API
|
|
|
|
NOTE: All functions that take a callback (cb) return a promise instead if you omit the callback.
|
|
|
|
### `pzp.db.installEncryptionFormat(encryptionFormat)`
|
|
|
|
If `encryptionFormat` conforms to the [ssb-encryption-format](https://github.com/ssbc/ssb-encryption-format) spec, then this method will install the `encryptionFormat` in this database instance, meaning that you can now encrypt and decrypt messages using that encryption format.
|
|
|
|
### `pzp.db.loaded(cb)
|
|
|
|
Calls back when the database is ready to be used.
|
|
|
|
### `pzp.db.add(msg: Msg, tangleID: MsgId | null, cb: CB<RecPresent>)
|
|
|
|
Adds a message to the database. Usually performed automatically when you do other things like publishing messages or syncing from other peers.
|
|
|
|
### `pzp.db.account.find({ keypair?: KeypairPublicSlice, subdomain: string}, cb: CB<string>)`
|
|
|
|
Find the account that contains this `keypair` (or the implicit `config.global.keypair`) under the given `subdomain` (will be converted to an actual msg domain).
|
|
|
|
### `pzp.db.account.create({ keypair?: Keypair, subdomain: string }, cb: CB<string>)`
|
|
|
|
Create an account (root msg) for the given `keypair` (or the implicit `config.global.keypair`) under the given `subdomain` (will be converted to an actual msg domain).
|
|
|
|
### `pzp.db.account.findOrCreate({ keypair?: Keypair, subdomain: string }, cb: CB<string>)`
|
|
|
|
Find or create an account (root msg) for the given `keypair` (or the implicit `config.global.keypair`) under the given `domain` (will be converted to an actual msg domain).
|
|
|
|
### `pzp.db.account.add({ account: string, keypair: Keypair | KeypairPublicSlice, powers?: Array<AccountPower>, consent?: string }, cb: CB<RecPresent>)`
|
|
|
|
Add the given `keypair` to the given `account`, authorized by the given `consent` (or implicitly created on the fly if the `keypair` contains the private key) with the specified `powers` (defaulting to no powers).
|
|
|
|
### `pzp.db.account.del({ account: string, keypair: KeypairPublicSlice }, cb: CB<RecPresent>)`
|
|
|
|
Remove the given `keypair` from the given `account`.
|
|
|
|
### `pzp.db.account.consent({ keypair?: KeypairPrivateSlice, account: string }) => string`
|
|
|
|
Create a consent signature for the given `keypair` (or the implicit `config.global.keypair`) to be added to the given `account`.
|
|
|
|
### `pzp.db.account.has({ keypair?: KeypairPublicSlice, account: string }, cb: CB<boolean>)
|
|
|
|
Does this `account` have this `keypair` (or the implicit `config.global.keypair`)?
|
|
|
|
feed: {
|
|
### `pzp.db.feed.publish({ keypair?: Keypair, encryptionFormat?: string, data: object, domain: string, account: string, tangles?: Array<MsgID> }, cb: CB<RecPresent>)`
|
|
|
|
Publishes a message to the feed of the given `domain`.
|
|
|
|
### `pzp.db.feed.getID(accountId: string, domain: string) => string`
|
|
|
|
Gets the moot ID (the ID of an account's domain's root message) for a given account and domain. That message is deterministic so you can calculate its ID even if you e.g. haven't been given it directly.
|
|
|
|
### `pzp.db.feed.findMoot(accountId: string, domain: string, cb: CB<RecPresent | null>)`
|
|
|
|
Gets the moot for the specified account and domain from the database. A moot is the root message for an account's domain.
|
|
|
|
### `pzp.db.getRecord(msgID: MsgID, cb: CB<RecPresent | null>)`
|
|
|
|
Gets a message's record using its message ID, if you have it in your database. The record has the shape `{ id: string, msg: Msg, received: number }`.
|
|
|
|
### `pzp.db.get(msgID: MsgID, cb: CB<Msg | null>)`
|
|
|
|
Gets a message using its message ID, if you have it in your database.
|
|
|
|
### `pzp.db.del(msgID: MsgID, cb: CB<void>)`
|
|
|
|
Deletes a specific message from your database.
|
|
|
|
### `pzp.db.erase(msgID: MsgID, cb: CB<void>)
|
|
|
|
Erases a specific message in your database. Erasing, as opposed to deleting, only removes a message's `data`. Metadata is kept and the message integrity can still be verified.
|
|
|
|
### `pzp.db.ghosts.add({ tangleID: MsgID, msgID: MsgID, span: number }, cb: CB<void>)`
|
|
|
|
Adds a [ghost][ghost] to the database.
|
|
|
|
### `pzp.db.ghosts.get(tangleID: MsgID) => Array<string>`
|
|
|
|
Gets a [ghost][ghost] from the database.
|
|
|
|
### `pzp.db.ghosts.getMinDepth(tangleID: MsgID) => number`
|
|
|
|
Gets the depth of the ghost in the tangle with the lowest depth.
|
|
|
|
### `pzp.db.onRecordAdded`
|
|
|
|
An [obz][obz] observable that triggers when a record is added to the database.
|
|
|
|
### `pzp.db.onRecordDeletedOrErased`
|
|
|
|
An [obz][obz] observable that triggers when a record is either deleted or erased. Erasing means that only the `data` field of the message has been cleared.
|
|
|
|
### `pzp.db.getTangle(tangleID: MsgID, cb: CB<DBTangle | null>)`
|
|
|
|
Tries to get a `DBTangle` object representing an entire tangle in the database.
|
|
|
|
### `pzp.db.msgs() => AsyncGenerator<Msg>`
|
|
|
|
Returns an async generator letting you iterate over all messages in the database.
|
|
|
|
### `pzp.db.records() => AsyncGenerator<Rec>`
|
|
|
|
Returns an async generator letting you iterate over all records in the database. The records have the shape `{ id: string, msg: Msg, received: number }` if they exist but they might also be deleted.
|
|
|
|
### `pzp.db.log.stats(cb: CB<{ totalBytes: number; deletedBytes: number }>)`
|
|
|
|
Returns some size stats on the log file, where messages are stored.
|
|
|
|
### `pzp.db.log.compact(cb: CB<void>)`
|
|
|
|
Makes the log file (the message store) take up less space by compacting it into the space freed by messages that have been deleted.
|
|
|
|
|
|
## License
|
|
|
|
Copyright © 2023-2024 Andre 'Staltz' Medeiros <contact@staltz.com> and contributors. Licensed under the MIT license.
|
|
|
|
[ghost]: https://www.manyver.se/blog/2023-11-05
|
|
[obz]: https://www.npmjs.com/package/obz |