From c7a899075bebd32ed5fac0fc9f3cae093e132939 Mon Sep 17 00:00:00 2001 From: Pierre Demailly Date: Thu, 9 Jan 2025 14:54:11 +0100 Subject: [PATCH] docs(KVPeer): update doc --- docs/KVPeer.md | 165 ++++++++++++++++++++++++++++--------------------- 1 file changed, 94 insertions(+), 71 deletions(-) diff --git a/docs/KVPeer.md b/docs/KVPeer.md index 1dd9e84..10b1cc5 100644 --- a/docs/KVPeer.md +++ b/docs/KVPeer.md @@ -1,113 +1,136 @@

- RedisKV + KVPeer

- This class is used to store and retrieve key-value pairs in Redis. + This class is used to store, retrieve and delete key-value pairs in Redis.

-## Interface +## 📚 Usage ```ts -export type KVType = "raw" | "object"; - -export type StringOrObject = string | Record; +import { KVPeer, RedisAdapter } from "@myunisoft/redis"; -type IsMetadataDefined, K extends Record | null = null> = K extends Record ? T & { customData: K } : T; +const redisAdapter = new RedisAdapter(); +await redisAdapter.initialize(); -type MappedValue | null = null> = T extends Record ? -IsMetadataDefined : T; +const kvPeer = new KVPeer({ + type: "raw", + adapter: redisAdapter, +}); -// How to restraint usage of the mapValue fn while T extends string? -export type KVMapper | null = null> = (value: T) => MappedValue; +await kvPeer.setValue({ key: "myKey", value: "boo" }); +const value = await kvPeer.getValue("myKey"); // "boo" +``` -export interface KVOptions, K extends Record | null = null> { - adapter: DatabaseConnection; - type?: KVType; - mapValue?: KVMapper; - prefix?: string; - prefixSeparator?: string; -} +## 📜 API -export type KVPeerSetValueOptions = Omit< - RedisSetValueOptions, - "type" ->; -``` +### constructor(options: KVOptions) -## Constants +You can instantiate a new `KVPeer` object by passing the following options: +- `adapter: DatabaseConnection` - the database connection object. +- `type?: KVType` - the type of the value that will be stored in Redis. It can be either `"raw"` or `"object"`. Default is `"raw"`. +- `mapValue?: KVMapper` - a function that will be used to map the value before storing it in Redis (only for `"object"` type). There is no map by default. +- `prefix?: string` - a prefix that will be added to the key before storing it in Redis. +- `prefixSeparator?: string` - a separator that will be used to separate the prefix from the key. Default is `"-"`. -- kDefaultKVType = "raw" +### setValue(options: KVPeerSetValueOptions): Promise> -## 📚 Usage +This method is used to set a key-value pair in Redis. ```ts -import { RedisKV, MemoryAdapter } from "@myunisoft/redis"; - -interface MyCustomObject { - foo: string; -} +const key = "foo"; +const value = { + bar: "baz", +}; -interface Metadata { - bar: string; +const result = await kvPeer.setValue({ key, value }); +if (result.err) { + console.error(result.val); } +``` -const memoryAdapter = new MemoryAdapter(); +Options are defined as follows: -const options: KVOptions = { - adapter: memoryAdapter, - type: "object", - mapValue: (value: MyCustomObject) => { - value.metadata = { - bar: "foo" - }; +- `key` - the key that will be used to store the value in Redis. +- `value` - the value that will be stored in Redis. +- `expiresIn` - the time in **seconds** after which the key will expire. - return value; - } +```ts +export interface RedisSetValueOptions> { + key: KeyType; + value: Partial; + type: KVType; + expiresIn?: number; } -const customKvWrapper = new RedisKV(options); +export type KVPeerSetValueOptions = Omit< + RedisSetValueOptions, + "type" +>; ``` -## 📜 API - -### setValue(options: KVPeerSetValueOptions< T >): Promise< KeyType > +### getValue(key: KeyType): Promise | null > -this method is used to set a key-value pair in Redis +This method is used to get a value in Redis. ```ts -const key = "foo"; -const value: MyCustomObject = { - foo: "bar", -}; - -await customKvWrapper.setValue(key, value); // "local-foo" +const value = await kvPeer.getValue("foo"); +// { bar: "baz" } ``` -### getValue(key: KeyType): Promise< MappedValue< T, K > | null > +### deleteValue(key: KeyType): Promise -this method is used to get a value from Redis +This method is used to delete a key-value pair in Redis. ```ts -const returnValue = await customKvWrapper.getValue(key); - -console.log(returnValue); -/* - { - foo: "bar", - customData: { - bar: "foo" - } - } -*/ +const result = await kvPeer.deleteValue("key"); + +console.log(result); // 0 for Failure, 1 for Success ``` -### deleteValue(key: KeyType): Promise< number > +## Usage with `mapValue` + +```ts +const kvPeer = new KVPeer({ + type: "object", + adapter: redisAdapter, + mapValue: (value) => { + return { + ...value, + metadata: { + bar: "baz", + }, + }; + }, +}); + +await kvPeer.setValue({ key: "myKey", value: { foo: "foz" } }); +const value = await kvPeer.getValue("myKey"); +// { foo: "foz", metadata: { bar: "baz" } } +``` -this method is used to delete a key-value pair +## Interface ```ts -const result = await customKvWrapper.deleteValue("key"); +export type KeyType = string | Buffer; +export type KVType = "raw" | "object"; -console.log(result); // 0 for Failure, 1 for Success +export type StringOrObject = string | Record; + +type IsMetadataDefined, K extends Record | null = null> = + K extends Record ? T & { customData: K; } : T; + +type MappedValue | null = null> = T extends Record ? + IsMetadataDefined : T; + +export type KVMapper | null = null> = (value: T) => MappedValue; + +export interface KVOptions, K extends Record | null = null> { + adapter: DatabaseConnection; + type?: KVType; + mapValue?: KVMapper; + prefix?: string; + prefixSeparator?: string; +} ```