@sphereon/ssi-sdk.kv-store-temp 0.33.1-next.3 → 0.33.1-next.73

package/dist/index.d.ts

@@ -1,11 +1,324 @@
+import { EventEmitter } from 'events';
+import { OrPromise } from '@veramo/utils';
+import { DataSource, BaseEntity, MigrationInterface, QueryRunner } from 'typeorm';
+
 /**
- * Provides a {@link @sphereon/ssi-sdk.kv-store-temp#KeyValueStore} for the
- * {@link @veramo/core#Agent} plugin that implements {@link @sphereon/ssi-sdk.kv-store-temp#IKeyValueStore} interface
+ * This is how the store will actually store the value.
+ * It contains an optional `expires` property, which indicates when the value would expire
  *
- * @packageDocumentation
+ * @beta
  */
-export { KeyValueStore } from './key-value-store';
-export * from './store-adapters/tiered/index';
-export * from './store-adapters/typeorm/index';
-export * from './key-value-types';
-//# sourceMappingURL=index.d.ts.map
+interface IValueData<ValueType> {
+    value: ValueType | undefined;
+    expires: number | undefined;
+}
+/**
+ * Event listener arguments
+ *
+ * @beta
+ */
+interface IKeyValueStoreOnArgs {
+    eventName: string | symbol;
+    listener: (...args: any[]) => void;
+}
+/**
+ * Options for the Key Value store
+ *
+ * @beta
+ */
+interface IKeyValueStoreOptions<ValueType> {
+    [key: string]: any;
+    /** Namespace for the current instance. */
+    namespace?: string | undefined;
+    /** A custom serialization function. */
+    /** The connection string URI. */
+    uri?: string | undefined;
+    /** The storage adapter instance to be used by Keyv. or any other implementation */
+    store: IKeyValueStoreAdapter<ValueType> | Map<string, ValueType>;
+    /** Default TTL. Can be overridden by specifying a TTL on `.set()`. */
+    ttl?: number | undefined;
+    /** Enable compression option **/
+    emitErrors?: boolean;
+}
+/**
+ * A store adapter implementation needs to provide namespace support
+ *
+ * @beta
+ */
+interface IKeyValueStoreAdapter<ValueType> {
+    namespace?: string | undefined;
+}
+/**
+ * The types that can be stored by a store adapter
+ *
+ * @public
+ */
+type ValueStoreType = object | string | number | boolean;
+/**
+ * A Key Value store is responsible for managing Values identified by keys.
+ *
+ * @beta
+ */
+interface IKeyValueStore<ValueType extends ValueStoreType> {
+    /**
+     * Get a single value by key. Can be undefined as the underlying store typically will not throw an error for a non existing key
+     *
+     * @param key - Contains the key to search for
+     */
+    get(key: string): Promise<ValueType | undefined>;
+    /**
+     * Get a single item as Value Data from the store. Will always return a Value Data Object, but the value in it can be undefined in case the actual store does not contain the value
+     *
+     * @param key - Contains the key to search for
+     */
+    getAsValueData(key: string): Promise<IValueData<ValueType>>;
+    /**
+     * Get multiple values from the store. Will always return an array with values, but the values can be undefined in case the actual store does not contain the value for the respective key
+     *
+     * @param keys - Contains the keys to search for
+     */
+    getMany(keys: string[]): Promise<Array<ValueType | undefined>>;
+    /**
+     * Get multiple items as Value Data from the store. Will always return an array with Value Data Object, but the value in it can be undefined in case the actual store does not contain the value
+     *
+     * @param keys - Contains the keys to search for
+     */
+    getManyAsValueData(keys: string[]): Promise<Array<IValueData<ValueType>>>;
+    /**
+     * Store a single value
+     *
+     * @param key - The key
+     * @param value - The value
+     * @param ttl - An optional number how long to store the value in milliseconds. If not provided will be stored indefinitely
+     */
+    set(key: string, value: ValueType, ttl?: number): Promise<IValueData<ValueType>>;
+    /**
+     * Delete a value from the store by key
+     *
+     * @param key - The key to delete the value for
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete multiple values by provided keys
+     *
+     * @param keys - The keys to delete the values for
+     */
+    deleteMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * Clear the whole store (delete all values)
+     */
+    clear(): Promise<IKeyValueStore<ValueType>>;
+    /**
+     * Determine whether the store has the value belonging to the provided key
+     *
+     * @param key The key to search for
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Disconnect the backing store. After this operation the store typically cannot be reused, unless the store object is re-instantiated
+     */
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Agent plugin that implements {@link @sphereon/ssi-sdk.kv-store-temp#IKeyValueStore} interface
+ * @public
+ */
+declare class KeyValueStore<ValueType extends ValueStoreType> implements IKeyValueStore<ValueType> {
+    /**
+     * The main keyv typescript port which delegates to the storage adapters and takes care of some common functionality
+     *
+     * @internal
+     */
+    private readonly keyv;
+    constructor(options: IKeyValueStoreOptions<ValueType>);
+    get(key: string): Promise<ValueType | undefined>;
+    getAsValueData(key: string): Promise<IValueData<ValueType>>;
+    getMany(keys: string[]): Promise<Array<ValueType | undefined>>;
+    getManyAsValueData(keys: string[]): Promise<Array<IValueData<ValueType>>>;
+    set(key: string, value: ValueType, ttl?: number): Promise<IValueData<ValueType>>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean[]>;
+    clear(): Promise<IKeyValueStore<ValueType>>;
+    disconnect(): Promise<void>;
+    kvStoreOn(args: IKeyValueStoreOnArgs): Promise<IKeyValueStore<ValueType>>;
+    private toDeserializedValueData;
+}
+
+type Options<ValueType> = {
+    local: IKeyValueStoreAdapter<ValueType> | Map<string, ValueType>;
+    remote: IKeyValueStoreAdapter<ValueType> | Map<string, ValueType>;
+    localOnly?: boolean;
+    iterationLimit?: number | string;
+};
+type Options_$1 = {
+    validator: (value: any, key: string) => boolean;
+    dialect: string;
+    iterationLimit?: number | string;
+    localOnly?: boolean;
+};
+
+/**
+ * Please be aware these types are compatible with the keyv package, to ensure we can use its store-adapters for free.
+ *
+ * Be very careful when extending/changing!. Normally you will want to create an adapter or decorator for your additional behaviour or requirements
+ */
+
+interface KeyvOptions<Value> {
+    [key: string]: any;
+    /** Namespace for the current instance. */
+    namespace?: string | undefined;
+    /** A custom serialization function. */
+    serialize?: (data: KeyvDeserializedData<Value>) => OrPromise<string | undefined>;
+    /** A custom deserialization function. */
+    deserialize?: (data: any) => OrPromise<KeyvDeserializedData<Value> | undefined>;
+    /** The connection string URI. */
+    uri?: string | undefined;
+    /** The storage adapter instance to be used by Keyv. */
+    store?: KeyvStore<Value | undefined> | undefined;
+    /** Default TTL. Can be overridden by specififying a TTL on `.set()`. */
+    ttl?: number | undefined;
+    /** Specify an adapter to use. e.g `'redis'` or `'mongodb'`. */
+    adapter?: 'redis' | 'mongodb' | 'mongo' | 'sqlite' | 'postgresql' | 'postgres' | 'mysql' | object | string | undefined;
+    /** Enable compression option **/
+    compression?: KeyvCompressionAdapter | undefined;
+    emitErrors?: boolean;
+}
+interface KeyvCompressionAdapter {
+    compress(value: any, options?: any): OrPromise<any>;
+    decompress(value: any, options?: any): OrPromise<any>;
+    serialize(value: any): OrPromise<string>;
+    deserialize(value: any): OrPromise<any>;
+}
+interface KeyvDeserializedData<Value> {
+    value: Value;
+    expires: number | undefined;
+}
+type KeyvStoredData<Value> = KeyvDeserializedData<Value> | string | Value | undefined;
+interface KeyvStore<Value> {
+    namespace?: string | undefined;
+    opts: KeyvOptions<Value>;
+    on?(eventName: string | symbol, listener: (...args: any[]) => void): void;
+    get(key: string | string[], options?: {
+        raw?: boolean;
+    }): OrPromise<KeyvStoredData<Value> | Array<KeyvStoredData<Value>>>;
+    getMany?(keys: string[], options?: {
+        raw?: boolean;
+    }): OrPromise<Array<KeyvStoredData<Value>>> | undefined;
+    iterator?(namespace?: string | undefined): AsyncGenerator<any, void, any>;
+    set(key: string, value: Value, ttl?: number): any;
+    delete(key: string | string[]): OrPromise<boolean>;
+    deleteMany?(keys: string[]): OrPromise<boolean>;
+    clear(): OrPromise<void>;
+    has?(key: string): OrPromise<boolean>;
+    disconnect?(): void;
+}
+
+/**
+ * Tiered keyv store adapter, combining 2 adapters/stores into one
+ * @alpha
+ */
+declare class KeyValueTieredStoreAdapter<Value> extends EventEmitter implements KeyvStore<Value>, IKeyValueStoreAdapter<Value> {
+    opts: Options_$1;
+    remote: KeyvStore<Value>;
+    local: KeyvStore<Value>;
+    iterationLimit?: string | number;
+    namespace?: string | undefined;
+    constructor({ remote, local, ...options }: Options<Value>);
+    get(key: string | string[], options?: {
+        raw?: boolean;
+    }): Promise<KeyvStoredData<Value> | Array<KeyvStoredData<Value>>>;
+    getMany(keys: string[], options?: {
+        raw?: boolean;
+    }): Promise<Array<KeyvStoredData<Value>>>;
+    set(key: string, value: any, ttl?: number): Promise<any[]>;
+    clear(): Promise<undefined>;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    iterator(namespace?: string): AsyncGenerator<any, void, any>;
+}
+
+/**
+ * @public
+ */
+type KeyValueTypeORMOptions = {
+    dbConnection: OrPromise<DataSource>;
+    namespace?: string;
+};
+/**
+ * Internal options for the TypeORM adapter
+ *  @internal
+ */
+type Options_<Value> = {
+    validator: (value: any, key: string) => boolean;
+    dialect: string;
+    serialize: (data: KeyvDeserializedData<Value>) => OrPromise<string | undefined>;
+    /** A custom deserialization function. */
+    deserialize: (data: any) => OrPromise<KeyvDeserializedData<Value> | undefined>;
+};
+
+/**
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
+declare class KeyValueStoreEntity extends BaseEntity {
+    key: string;
+    data: string;
+    expires?: number;
+}
+
+/**
+ * Create the database layout for Veramo 3.0
+ *
+ * @public
+ */
+declare class CreateKVDatabaseMigration implements MigrationInterface {
+    private readonly _tableName;
+    readonly name: string;
+    constructor(tableName?: string);
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+}
+
+/**
+ * The migrations array that SHOULD be used when initializing a TypeORM database connection.
+ *
+ * These ensure the correct creation of tables and the proper migrations of data when tables change between versions.
+ *
+ * @public
+ */
+declare const kvStoreMigrations: (typeof CreateKVDatabaseMigration)[];
+
+/**
+ * TypeORM based key value store adapter
+ * @beta
+ */
+declare class KeyValueTypeORMStoreAdapter extends EventEmitter implements KeyvStore<string>, IKeyValueStoreAdapter<string> {
+    private readonly dbConnection;
+    readonly namespace: string;
+    opts: Options_<string>;
+    constructor(options: KeyValueTypeORMOptions);
+    get(key: string | string[], options?: {
+        raw?: boolean;
+    }): Promise<KeyvStoredData<string> | Array<KeyvStoredData<string>>>;
+    getMany(keys: string[], options?: {
+        raw?: boolean;
+    }): Promise<Array<KeyvStoredData<string>>>;
+    set(key: string, value: string, ttl?: number): Promise<KeyvStoredData<string>>;
+    delete(key: string | string[]): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+/**
+ *  Ensures that the provided DataSource is connected.
+ *
+ * @param dbConnection - a TypeORM DataSource or a Promise that resolves to a DataSource
+ * @internal
+ */
+declare function _getConnectedDb(dbConnection: OrPromise<DataSource>): Promise<DataSource>;
+
+export { type IKeyValueStore, type IKeyValueStoreAdapter, type IKeyValueStoreOnArgs, type IKeyValueStoreOptions, type IValueData, KeyValueStore, KeyValueStoreEntity, KeyValueTieredStoreAdapter, KeyValueTypeORMStoreAdapter, type ValueStoreType, _getConnectedDb, kvStoreMigrations };