sagi/workers-kv

Cloudflare Workers KV API for Node.js

workers-kv

@sagi.io/workers-kv is a Cloudflare Workers KV API for Node.js.

⭐ We use it at OpenSay to efficiently cache data on Cloudflare Workers KV.

Installation

$ npm i @sagi.io/workers-kv

Quickstart

First, instantiate a WorkersKVREST instance:

const WorkersKVREST = require('@sagi.io/workers-kv')

const cfAccountId = process.env.CLOUDFLARE_ACCOUNT_ID;
const cfAuthKey = process.env.CLOUDFLARE_AUTH_KEY;
const cfEmail = process.env.CLOUDFLARE_EMAIL;

const WorkersKV = new WorkersKVREST({ cfAccountId, cfAuthKey, cfEmail })

Then, access it's instance methods. For instance:

const namespaceId = '...'

const allKeys = await KV.listAllKeys({ namespaceId })

API

We adhere to Cloudflare's Workers KV REST API.

WorkersKVREST({ ... })

Instantiates a WorkersKV object with the defined below methods.

Function definition:

const WorkersKVREST = function({
  cfAccountId,
  cfEmail,
  cfAuthKey,
  namespaceId = '',
}){ ... }

Where:

• cfAccountId required Your Cloudflare account id.
• cfEmail optional|required The email you registered with Cloudflare.
• cfAuthKey optional|required Your Cloudflare Auth Key.
• cfAuthToken optional|required Your Cloudflare Auth Token.
• namespaceId optional The Workers KV namespace id. This argument is optional - either provide it here, or via the methods below.

Use cfAuthToken with a Cloudflare auth token. You can also set cfEmail and cfAuthKey directly without using an auth token.

WorkersKV.listKeys({ ... })

Function definition:

const listKeys = async ({
  namespaceId = '',
  limit = MAX_KEYS_LIMIT,
  cursor = undefined,
  prefix = undefined,
} = {}) => { ... }

Where:

• namespaceId optional The namespace id (can also be provided while instantiating WorkersKV).
• limit optional The number of keys to return. The cursor attribute may be used to iterate over the next batch of keys if there are more than the limit.
• cursor optional Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.
• prefix optional A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned.

WorkersKV.listAllKeys({ ... })

Cursors through listKeys requests for you.

Function definition:

const listAllKeys = async ({
  namespaceId = '',
  prefix = undefined,
  limit = MAX_KEYS_LIMIT,
} = {}) => { ... }

Where:

• namespaceId optional The namespace id (can also be provided while instantiating WorkersKV).
• cursor optional Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.
• prefix optional A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned.

listNamespaces({ ... })

Function definition:

const listNamespaces = async ({
  page = 1,
  per_page = 50,
} = {}) => { ... }

Where:

• page optional Page number of paginated results.
• per_page optional Maximum number of results per page.

readKey({ ... })

Function definition:

const readKey = async ({
  key,
  namespaceId = '',
}) => { ... }

Where:

• key required the key name.
• namespaceId optional The namespace id (can also be provided while instantiating WorkersKV).

WorkersKV.deleteKey({ ... })

Function definition:

const deleteKey= async ({
  key,
  namespaceId = '',
}) => { ... }

Where:

• key required the key name.
• namespaceId optional The namespace id (can also be provided while instantiating WorkersKV).

WorkersKV.writeKey({ ... })

Function definition:

const writeKey=> async ({
  key,
  value,
  namespaceId = '',
  expiration = undefined,
  expiration_ttl = undefined,
}) => { ... }

Where:

• key required A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
• value required A UTF-8 encoded string to be stored, up to 10 MB in length.
• namespaceId optional Is the namespace id (can also be provided while instantiating WorkersKV).
• expiration optional The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
• expiration_ttl optional The number of seconds for which the key should be visible before it expires. At least 60.

WorkersKV.writeMultipleKeys({ ... })

Function definition:

const writeMultipleKeys => async ({
  keyValueMap,
  namespaceId = '',
  expiration = undefined,
  expiration_ttl = undefined,
  base64 = false,
}) => { ... }

Where:

• keyValueMap required Is an object with string keys and values. e.g { keyName1: 'keyValue1', keyName2: 'keyValue2' }
• namespaceId optional Is the namespace id (can also be provided while instantiating WorkersKV).
• expiration optional The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
• expiration_ttl optional The number of seconds for which the key should be visible before it expires. At least 60.
• base64 optional Whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images. Default: false.

WorkersKV.deleteMultipleKeys({ ... })

Function definition:

const deleteMultipleKeys = async ({
  keys,
  namespaceId = '',
}) => { ... }

Where:

• keys required An array of keys to be deleted.
• namespaceId optional The namespace id (can also be provided while instantiating WorkersKV).