KVS

Motivation

Common Features

Support Browsers

Packages

Usage

import{KVSIndexedDB,kvsIndexedDB}from"@kvs/env";(async()=>{conststorage=awaitkvsEnvStorage({name:"database-name",version:1});awaitstorage.set("a1","string");consta1=awaitstorage.get("a1");console.log(a1);// => "string"})();

API

exporttypeKVS<SchemaextendsStorageSchema>={/**     * Returns the value associated to the key.     * If the key does not exist, returns `undefined`.     */get<KextendsStoreNames<Schema>>(key:K):Promise<StoreValue<Schema,K>|undefined>;/**     * Sets the value for the key in the storage. Returns the storage.     */set<KextendsStoreNames<Schema>>(key:K,value:StoreValue<Schema,K>|undefined):Promise<KVS<Schema>>;/**     * Returns a boolean asserting whether a value has been associated to the key in the storage.     */has(key:StoreNames<Schema>):Promise<boolean>;/**     * Returns true if an key in the storage existed and has been removed.     * Returns false if the key does not exist.     */delete(key:StoreNames<Schema>):Promise<boolean>;/**     * Removes all key-value pairs from the storage.     * Note: clear method does not delete the storage.     * In other words, after clear(), the storage still has internal metadata like version.     */clear():Promise<void>;/**     * Drop the storage.     * It delete all data that includes metadata completely.     */dropInstance():Promise<void>;/*     * Close the KVS connection     * DB-like KVS close the connection via this method     * Of course, localStorage-like KVS implement do nothing. It is just noop function     */close():Promise<void>;}&AsyncIterable<[StoreNames<Schema>,StoreValue<Schema,StoreNames<Schema>>]>;

Basic Usage

importassertfrom"assert";import{kvsEnvStorage}from"@kvs/env";(async()=>{typeStorageSchema={a1:string;b2:number;c3:boolean;};// open database and initialize itconststorage=awaitkvsEnvStorage<StorageSchema>({name:"database-name",version:1});// setawaitstorage.set("a1","string");// type checkawaitstorage.set("b2",42);awaitstorage.set("c3",false);// hasconsole.log(awaitstorage.has("a1"));// => true// getconsta1=awaitstorage.get("a1");// a1 will be string typeconstb2=awaitstorage.get("b2");constc3=awaitstorage.get("c3");assert.strictEqual(a1,"string");assert.strictEqual(b2,42);assert.strictEqual(c3,false);// iterateforawait(const[key,value]ofstorage){console.log([key,value]);}// deleteawaitstorage.delete("a1");// clear all dataawaitstorage.clear();})();

Migration

import{kvsEnvStorage}from"@kvs/env";(async()=>{// Defaut version: 1// when update version 1 → 2, call upgrace functionconststorage=awaitkvsEnvStorage({name:"database-name",version:2,asyncupgrade({ kvs, oldVersion}){if(oldVersion<2){awaitkvs.set("v1","v1-migrated-value");// modify storage as migration}return;}});assert.strictEqual(awaitstorage.get("v1"),"v1-migrated-value");})();

First Initializing

import{KVSIndexedDB,kvsIndexedDB}from"@kvs/env";(async()=>{conststorage=awaitkvsEnvStorage({name:"database-name",version:1,asyncupgrade({ kvs, oldVersion, newVersion}){console.log(oldVersion);// => 0console.log(newVersion);// => 1}});})();

TypeScript

import{KVSIndexedDB,kvsIndexedDB}from"@kvs/env";(async()=>{typeStorageSchema={a1:string;b2:number;c3:boolean;};conststorage=awaitkvsEnvStorage<StorageSchema>({name:"database-name",version:1});awaitstorage.set("a1","string");// type checkawaitstorage.set("b2",42);awaitstorage.set("c3",false);consta1=awaitstorage.get("a1");// a1 will be string typeconstb2=awaitstorage.get("b2");constc3=awaitstorage.get("c3");assert.strictEqual(a1,"string");assert.strictEqual(b2,42);assert.strictEqual(c3,false);})();

Tips: Initial Data

(async()=>{typeUnixTimeStamp=number;typeScheme={timeStamp:UnixTimeStamp};conststorage=awaitkvsEnvStorage<Scheme>({name:"test-data",version:1,asyncupgrade({ kvs, oldVersion, newVersion}){// Initialize data// oldVersion is 0 and newVersion is 1 at first timeif(oldVersion<1){awaitkvs.set("timeStamp",Date.now());}}});consttimeStamp=awaitstorage.get("timeStamp");console.log(timeStamp);// => timestamp})()

Related

Changelog

Development

# install and linkyarn install# build all packageyarn run build

Running tests

yarn test

Contributing

Author

License