<h3 align="center"><img width="300" alt="KV.JS logo" src="https://raw.githubusercontent.com/HeyPuter/kv.js/main/logo.png"></h3> <h3 align="center">Advanced in-memory caching module for JavaScript.</h3> <h4 align="center">For when you need caching but running Redis would be an overkill.</h4> <hr>

KV.JS is a fast, in-memory data store written in pure JavaScript, heavily inspired by Redis and Memcached. It is capable of handling multiple data types, including strings, lists, sets, sorted sets, hashes, and geospatial indexes. Additionally, with more than 140 functions, KV.JS supports a vast variety of operations, ranging from SET, GET, EXPIRE, DEL to INCR, DECR, LPUSH, RPUSH, SADD, SREM, HSET, HGET, and many many more.

Installation

npm install @heyputer/kv.js

Usage

const kvjs = require('@heyputer/kv.js');

// Create a new kv.js instance
const kv = new kvjs();

// Set a key
kv.set('foo', 'bar');

// Get the key's value
kv.get('foo'); // "bar"

// Delete the key
kv.del('foo');

// Set another key
kv.set('username', 'heyputer');

// Automatically delete the key after 60 seconds
kv.expire('username', 60);

More usage examples

// Assuming the key 'counter' has been set, decrement the value of the key by 1
kv.decr('counter');

</details> <details> <summary><strong><code>decrby</code></strong></summary>

// Assuming the key 'counter' has been set, decrement the value of the key by 5 (output: -5)
kv.decrby('counter', 5);

// Assuming the key 'counter' has been set, decrement the value of the key by -3 (output: 3)
kv.decrby('counter', -3);

// Assuming the key 'counter' has been set, decrement the value of the key by 10 (output: -7)
kv.decrby('counter', 10);

// Assuming the key 'counter' has been set, decrement the value of the key by 0 (output: 0)
kv.decrby('counter', 0);

// Assuming the key 'counter' has been set, decrement the value of the key by -7 (output: 4)
kv.decrby('counter', -7);

</details> <details> <summary><strong><code>del</code></strong></summary>

Delete specified key(s). If a key does not exist, it is ignored.

// Delete a single key ("key1"), returns 1 if the key was deleted, 0 if it did not exist or has expired.
kv.del("key1");

// Delete multiple keys ("key2" and "key3"), returns the number of keys deleted (0, 1, or 2) depending on which keys existed and were not expired.
kv.del("key2", "key3");

// Attempt to delete a non-existent key ("nonExistentKey"), returns 0 since the key does not exist.
kv.del("nonExistentKey");

// Attempt to delete an expired key ("expiredKey"), returns 0 if the key has expired.
kv.del("expiredKey");

// Delete multiple keys ("key4", "key5", "key6"), returns the number of keys deleted (0 to 3) depending on which keys existed and were not expired.
kv.del("key4", "key5", "key6");

</details> <details> <summary><strong><code>exists</code></strong></summary>

Check if one or more keys exist.

// Check if a single key ("key1") exists, returns 1 if the key exists and is not expired, 0 otherwise.
kv.exists("key1");

// Check if multiple keys ("key2" and "key3") exist, returns the number of existing keys (0, 1, or 2) that are not expired.
kv.exists("key2", "key3");

// Check if a non-existent key ("nonExistentKey") exists, returns 0 since the key does not exist.
kv.exists("nonExistentKey");

// Check if an expired key ("expiredKey") exists, returns 0 if the key has expired.
kv.exists("expiredKey");

// Check if multiple keys ("key4", "key5", "key6") exist, returns the number of existing keys (0 to 3) that are not expired.
kv.exists("key4", "key5", "key6");

</details> <details> <summary><strong><code>expire</code></strong></summary>

// Set a key's time to live in seconds without any option
kv.expire('username', 60);

// Set a key's time to live in seconds only if the key does not have an expiry time
kv.expire('username', 120, {NX: true});

// Set a key's time to live in seconds only if the key already has an expiry time
kv.expire('username', 180, {XX: true});

// Set a key's time to live in seconds only if the key's expiry time is greater than the specified time
kv.expire('username', 240, {GT: true});

// Set a key's time to live in seconds only if the key's expiry time is less than the specified time
kv.expire('username', 300, {LT: true});

</details> <details> <summary><strong><code>expireat</code></strong></summary>

// Set the TTL for key "user1" to expire in 30 seconds.
kv.expireat("user1", Math.floor(Date.now() / 1000) + 30);

// Set the TTL for key "user2" to expire at a specific UNIX timestamp (e.g. 1700000000), only if the key does not already have an expiry time.
kv.expireat("user2", 1700000000, {NX: true});

// Set the TTL for key "user3" to expire in 45 seconds, only if the key already has an expiry time.
kv.expireat("user3", Math.floor(Date.now() / 1000) + 45, {XX: true});

// Set the TTL for key "user4" to expire in 60 seconds, only if the new TTL is greater than the current TTL.
kv.expireat("user4", Math.floor(Date.now() / 1000) + 60, {GT: true});

// Set the TTL for key "user5" to expire in 15 seconds, only if the new TTL is less than the current TTL.
kv.expireat("user5", Math.floor(Date.now() / 1000) + 15, {LT: true});

// Set the TTL for key "user6" to expire at a specific UNIX timestamp (e.g. 1705000000), only if the key already have an expiry time.
kv.expireat("user6", 1705000000, {XX: true});

// Set the TTL for key "user7" to expire in 90 seconds, only if the key does not already have an expiry time.
kv.expireat("user7", Math.floor(Date.now() / 1000) + 90, {NX: true});

// Set the TTL for key "user8" to expire at a specific UNIX timestamp (e.g. 1710000000), only if the new TTL is greater than the current TTL.
kv.expireat("user8", 1710000000, {GT: true});

// Set the TTL for key "user9" to expire in 120 seconds, only if the new TTL is less than the current TTL.
kv.expireat("user9", Math.floor(Date.now() / 1000) + 120, {LT: true});

// Set the TTL for key "user10" to expire in 5 seconds.
kv.expireat("user10", Math.floor(Date.now() / 1000) + 5);

</details> <details> <summary><strong><code>get</code></strong></summary>

Get the value of a key.

// Example 1: Get the value of an existing key
kv.get('username'); // Returns the value associated with the key 'username'

// Example 2: Get the value of a non-existent key
kv.get('nonexistent'); // Returns null

// Example 3: Get the value of an expired key (assuming 'expiredKey' was set with an expiration)
kv.get('expiredKey'); // Returns null

// Example 4: Get the value of a key after updating its value
kv.set('color', 'red'); // Sets the key 'color' to the value 'red'
kv.get('color'); // Returns 'red'

// Example 5: Get the value of a key after deleting it (assuming 'deletedKey' was previously set)
kv.delete('deletedKey'); // Deletes the key 'deletedKey'
kv.get('deletedKey'); // Returns null

</details> <details> <summary><strong><code>getset</code></strong></summary>

// Set initial values for key.
kv.set("username", "John");

// Replace the value of "username" with "Alice" and return the old value ("John").
kv.getset("username", "Alice"); // Returns "John"

// Replace the value of "nonExistentKey" with "Bob" and return the old value (null).
kv.getset("nonExistentKey", "Bob"); // Returns null

</details> <details> <summary><strong><code>incr</code></strong></summary>

// Increment the value of an existing key ("key1") by 1, returns the new value of the key.
kv.incr("key1");

// Increment the value of a non-existing key ("nonExistentKey"), returns 1 as the new value of the key (since it's initialized as 0 and incremented by 1).
kv.incr("nonExistentKey");

// Increment the value of an expired key ("expiredKey"), if the key has expired, it will be treated as a new key, returns 1 as the new value of the key.
kv.incr("expiredKey");

// Increment the value of an existing key ("key2") with a non-numeric value, throws an error.
kv.incr("key2"); // Assuming "key2" has a non-numeric value

// Increment the value of an existing key ("key3") with a numeric value, returns the incremented value of the key.
kv.incr("key3"); // Assuming "key3" has a numeric value

</details> <details> <summary><strong><code>incrby</code></strong></summary>

// Increment the value of a key by 5 (assuming the key does not exist or its value is an integer)
kv.incrby('counter', 5);

// Increment the value of a key by -3 (assuming the key does not exist or its value is an integer)
kv.incrby('counter', -3);

// Increment the value of a key by 10 (assuming the key does not exist or its value is an integer)
kv.incrby('counter', 10);

// Increment the value of a key by 0 (assuming the key does not exist or its value is an integer)
kv.incrby('counter', 0);

// Increment the value of a key by -7 (assuming the key does not exist or its value is an integer)
kv.incrby('counter', -7);

</details> <details> <summary><strong><code>keys</code></strong></summary>

// Find all keys matching the pattern 'user:*' (assuming some keys matching the pattern exist)
kv.keys('user:*');

// Find all keys matching the pattern 'product:*' (assuming some keys matching the pattern exist)
kv.keys('product:*');

// Find all keys matching the pattern '*:email' (assuming some keys matching the pattern exist)
kv.keys('*:email');

// Find all keys matching the pattern 'username' (assuming some keys matching the pattern exist)
kv.keys('username');

</details> <details>

Kv.js

Install / Use

README

Installation

Usage

More usage examples