lightningdevkit
Version:
Lightning Development Kit
143 lines • 7.97 kB
JavaScript
import { Result_CVec_u8ZIOErrorZ } from '../structs/Result_CVec_u8ZIOErrorZ.mjs';
import { Result_NoneIOErrorZ } from '../structs/Result_NoneIOErrorZ.mjs';
import { Result_CVec_StrZIOErrorZ } from '../structs/Result_CVec_StrZIOErrorZ.mjs';
import { CommonBase } from './CommonBase.mjs';
import * as bindings from '../bindings.mjs';
class LDKKVStoreHolder {
constructor() {
this.held = null;
}
}
/**
* Provides an interface that allows storage and retrieval of persisted values that are associated
* with given keys.
*
* In order to avoid collisions the key space is segmented based on the given `primary_namespace`s
* and `secondary_namespace`s. Implementations of this trait are free to handle them in different
* ways, as long as per-namespace key uniqueness is asserted.
*
* Keys and namespaces are required to be valid ASCII strings in the range of
* [`KVSTORE_NAMESPACE_KEY_ALPHABET`] and no longer than [`KVSTORE_NAMESPACE_KEY_MAX_LEN`]. Empty
* primary namespaces and secondary namespaces (`\"\"`) are assumed to be a valid, however, if
* `primary_namespace` is empty, `secondary_namespace` is required to be empty, too. This means
* that concerns should always be separated by primary namespace first, before secondary
* namespaces are used. While the number of primary namespaces will be relatively small and is
* determined at compile time, there may be many secondary namespaces per primary namespace. Note
* that per-namespace uniqueness needs to also hold for keys *and* namespaces in any given
* namespace, i.e., conflicts between keys and equally named
* primary namespaces/secondary namespaces must be avoided.
*
* Note:** Users migrating custom persistence backends from the pre-v0.0.117 `KVStorePersister`
* interface can use a concatenation of `[{primary_namespace}/[{secondary_namespace}/]]{key}` to
* recover a `key` compatible with the data model previously assumed by `KVStorePersister::persist`.
*/
export class KVStore extends CommonBase {
/* @internal */
constructor(_dummy, ptr) {
super(ptr, bindings.KVStore_free);
this.bindings_instance = null;
}
/** Creates a new instance of KVStore from a given implementation */
static new_impl(arg) {
const impl_holder = new LDKKVStoreHolder();
let structImplementation = {
read(primary_namespace, secondary_namespace, key) {
const primary_namespace_conv = bindings.decodeString(primary_namespace);
const secondary_namespace_conv = bindings.decodeString(secondary_namespace);
const key_conv = bindings.decodeString(key);
const ret = arg.read(primary_namespace_conv, secondary_namespace_conv, key_conv);
const result = ret.clone_ptr();
return result;
},
write(primary_namespace, secondary_namespace, key, buf) {
const primary_namespace_conv = bindings.decodeString(primary_namespace);
const secondary_namespace_conv = bindings.decodeString(secondary_namespace);
const key_conv = bindings.decodeString(key);
const buf_conv = bindings.decodeUint8Array(buf);
const ret = arg.write(primary_namespace_conv, secondary_namespace_conv, key_conv, buf_conv);
const result = ret.clone_ptr();
return result;
},
remove(primary_namespace, secondary_namespace, key, lazy) {
const primary_namespace_conv = bindings.decodeString(primary_namespace);
const secondary_namespace_conv = bindings.decodeString(secondary_namespace);
const key_conv = bindings.decodeString(key);
const ret = arg.remove(primary_namespace_conv, secondary_namespace_conv, key_conv, lazy);
const result = ret.clone_ptr();
return result;
},
list(primary_namespace, secondary_namespace) {
const primary_namespace_conv = bindings.decodeString(primary_namespace);
const secondary_namespace_conv = bindings.decodeString(secondary_namespace);
const ret = arg.list(primary_namespace_conv, secondary_namespace_conv);
const result = ret.clone_ptr();
return result;
},
};
const ptr_idx = bindings.LDKKVStore_new(structImplementation);
impl_holder.held = new KVStore(null, ptr_idx[0]);
impl_holder.held.instance_idx = ptr_idx[1];
impl_holder.held.bindings_instance = structImplementation;
return impl_holder.held;
}
/**
* Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
* `key`.
*
* Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
* `primary_namespace` and `secondary_namespace`.
*
* [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
*/
read(primary_namespace, secondary_namespace, key) {
const ret = bindings.KVStore_read(this.ptr, bindings.encodeString(primary_namespace), bindings.encodeString(secondary_namespace), bindings.encodeString(key));
const ret_hu_conv = Result_CVec_u8ZIOErrorZ.constr_from_ptr(ret);
return ret_hu_conv;
}
/**
* Persists the given data under the given `key`.
*
* Will create the given `primary_namespace` and `secondary_namespace` if not already present
* in the store.
*/
write(primary_namespace, secondary_namespace, key, buf) {
const ret = bindings.KVStore_write(this.ptr, bindings.encodeString(primary_namespace), bindings.encodeString(secondary_namespace), bindings.encodeString(key), bindings.encodeUint8Array(buf));
const ret_hu_conv = Result_NoneIOErrorZ.constr_from_ptr(ret);
return ret_hu_conv;
}
/**
* Removes any data that had previously been persisted under the given `key`.
*
* If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
* remove the given `key` at some point in time after the method returns, e.g., as part of an
* eventual batch deletion of multiple keys. As a consequence, subsequent calls to
* [`KVStore::list`] might include the removed key until the changes are actually persisted.
*
* Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
* `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
* potentially get lost on crash after the method returns. Therefore, this flag should only be
* set for `remove` operations that can be safely replayed at a later time.
*
* Returns successfully if no data will be stored for the given `primary_namespace`,
* `secondary_namespace`, and `key`, independently of whether it was present before its
* invokation or not.
*/
remove(primary_namespace, secondary_namespace, key, lazy) {
const ret = bindings.KVStore_remove(this.ptr, bindings.encodeString(primary_namespace), bindings.encodeString(secondary_namespace), bindings.encodeString(key), lazy);
const ret_hu_conv = Result_NoneIOErrorZ.constr_from_ptr(ret);
return ret_hu_conv;
}
/**
* Returns a list of keys that are stored under the given `secondary_namespace` in
* `primary_namespace`.
*
* Returns the keys in arbitrary order, so users requiring a particular order need to sort the
* returned keys. Returns an empty list if `primary_namespace` or `secondary_namespace` is unknown.
*/
list(primary_namespace, secondary_namespace) {
const ret = bindings.KVStore_list(this.ptr, bindings.encodeString(primary_namespace), bindings.encodeString(secondary_namespace));
const ret_hu_conv = Result_CVec_StrZIOErrorZ.constr_from_ptr(ret);
return ret_hu_conv;
}
}
//# sourceMappingURL=KVStore.mjs.map