KV.JS Documentation

KV.JS is a fast, pure JavaScript in-memory data store designed as a lightweight alternative to Redis when running a full Redis instance is overkill. It supports a wide variety of data types and operations, including:

• Data Types: Strings, lists, sets, sorted sets, hashes, and geospatial indexes.
• Operations: Over 140 functions including SET, GET, EXPIRE, DEL, INCR, DECR, LPUSH, RPUSH, SADD, SREM, HSET, HGET, and more.

Install the KV.JS package using npm to add the in-memory data store to your JavaScript project.

npm install @heyputer/kv.js

KV.JS is an in-memory data store inspired by Redis and Memcached. You can create an instance, set values, retrieve them, delete them, and set expiration times on keys.

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);

To use kvjs, instantiate the kvjs class. You can pass a string as the argument to set the dbName, or pass an options object for more control.

If you are running in a browser environment and provide a dbName, the client will automatically attempt to initialize IndexedDB for persistent storage. If you need to ensure IndexedDB is ready before performing operations, call await client.waitForInitialization().

Control how long keys remain valid using expire, expireat, or persist.

• expire(key, seconds, [options]): Sets a TTL in seconds. Options include NX (only if no expiry exists), XX (only if expiry exists), GT (only if new TTL > current), and LT (only if new TTL < current).
• expireat(key, timestamp, [options]): Sets a TTL to a specific Unix timestamp.
• persist(key): Removes the expiration from a key.
• ttl(key): Returns the remaining time-to-live in seconds.

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

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

// Remove the expiration from the key "key1"
kv.persist("key1");

// Check the time-to-live of key 'username'
kv.ttl('username');

KV.JS provides Set operations to manage collections of unique members.

• sadd(key, ...members): Adds one or more members to a set.
• smembers(key): Retrieves all members of a set.
• sismember(key, member): Checks if a value is in a set.
• scard(key): Returns the number of members in a set.
• spop(key, [count]): Removes and returns random members.
• smove(source, destination, member): Moves a member from one set to another.
• Set Math:
  • sinter(key1, key2, ...): Intersection (members in all sets).
  • sdiff(key1, key2, ...): Difference (members in the first set but not in subsequent sets).

Sorted Sets associate each member with a numeric score, allowing for ordered retrieval.

• zadd(key, score, member, ...): Adds or updates members with scores.
• zcard(key): Returns the number of members.
• zcount(key, min, max): Returns the number of members with scores within a range.
• zrange(key, min, max): Returns members within a score range.
• zrangebyscore(key, min, max): Returns members within a score range.
• zrank(key, member): Returns the rank of a member.
• zrem(key, member): Removes a member.
• zincrby(key, increment, member): Increments a member's score.

Efficiently manage multiple keys or find keys using patterns.

• mget(key1, key2, ...): Retrieves values for multiple keys.
• mset(key1, val1, key2, val2, ...): Sets multiple key-value pairs.
• del(key1, key2, ...): Deletes specified keys. Returns the number of keys deleted.
• exists(key1, key2, ...): Checks existence of multiple keys. Returns the count of existing, non-expired keys.
• keys(pattern): Finds all keys matching a glob-style pattern (e.g., user:*).
• getset(key, new_value): Replaces the value and returns the old value.

Use incr and decr for simple unit changes, or incrby and decrby to change values by a specific amount. These operations work on numeric values. If a key does not exist, incr and incrby treat the initial value as 0.

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

// Increment the value of a key by 5
kv.incrby('counter', 5);

// Decrement the value of the key by 1
kv.decr('counter');

// Decrement the value of the key by 5
kv.decrby('counter', 5);