Skip to content
forked from sagi/workers-kv

Cloudflare Workers KV API for Node.js

License

Notifications You must be signed in to change notification settings

mpint/workers-kv

 
 

Repository files navigation

workers-kv

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

CircleCI MIT License version

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 required The email you registered with Cloudflare.
  • cfAuthKey required Your Cloudflare Auth Key.
  • namespaceId optional The Workers KV namespace id. This argument is optional - either provide it here, or via the methods below.

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 2 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,
}) => { ... }

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.

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

About

Cloudflare Workers KV API for Node.js

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%