Skip to content

cxKV

Auto-generated documentation from JSDoc comments

cxKV

Key Value Store, Globally Synced Atomic and Eventually Consistent

Example

import { kv, ko } from 'cxKV';

export async function main(data) {
  await kv.set('hello', 'world');
  await ko.set('record', { hello: 'world' });

  let a = await kv.get('hello');
  let b = await ko.get('record');

  return { a, b };
}

Kind: global class

cxKV.incr(key, [value], [ttl]) ⇒ Promise.<number>

Increment a numeric value atomically

Kind: static method of cxKV
Returns: Promise.<number> - The new value after incrementing

Param Type Default Description
key string The key to increment
[value] number 1 The amount to increment by (can be negative to decrement)
[ttl] number 0 Time to live in seconds (0 = no expiration)

Example

const newValue = await incr('counter');
const decremented = await incr('counter', -1);
const withExpiry = await incr('daily_count', 1, 86400);

cxKV.usage() ⇒ Promise.<number>

Get current storage usage in bytes

Kind: static method of cxKV
Returns: Promise.<number> - Current storage usage in bytes
Example

const currentUsage = await usage();
console.log(`Using ${currentUsage} bytes`);

cxKV.quota() ⇒ Promise.<object>

Get Quota

Kind: static method of cxKV
Returns: Promise.<object> - The quota information including limits and current usage
Example

const quotaInfo = await quota();
console.log('Storage limit:', quotaInfo.limit);

cxKV.keys() ⇒ Promise.<Array.<string>>

Get all keys in the store

Kind: static method of cxKV
Returns: Promise.<Array.<string>> - Array of all keys
Example

const allKeys = await keys();
console.log(`Found ${allKeys.length} keys`);

cxKV.lock(key, fn, [options]) ⇒ Promise.<*>

Run a function while holding an exclusive lock (mutex) shared by all parallel executions

The lock is a lease: it is released when fn settles, and expires after ttl regardless, so a crashed or timed-out script cannot hold it forever. Choose a ttl longer than fn is expected to take; if fn outlives it another execution may acquire the lock.

Kind: static method of cxKV
Returns: Promise.<*> - The value returned by fn
Throws:

  • Error With code LOCK_TIMEOUT if the lock is not acquired within wait
Param Type Default Description
key string The lock name
fn function Function to run while holding the lock (may be async)
[options] object
[options.ttl] number 30000 Lease duration in ms (max 300000)
[options.wait] number 0 How long to keep trying to acquire in ms (0 = try once)
[options.retry] number 100 Base delay between attempts in ms (jittered)

Example

const total = await lock('invoice:123', async () => {
  const current = Number(await kv.get('invoice:123:total'));
  await kv.set('invoice:123:total', String(current + 10));
  return current + 10;
}, { ttl: 10000, wait: 5000 });